OVERVIEW
=================================================================================================================================

Stingray is a Fortran tool to produce mock observing cones from semi-analytic models (SAMs) of galaxy formation.

V0.1  13/03/2018: First release
V0.6  09/10/2018: Various bug fixes
V0.7  26/10/2018: Separated user-module into a two modules for routines and selection function;
                  Added selection by "apparent mass" to reduce the amount of data in the positioning step
                  Added a correction of group positions that were 'wrapped away' from all group members
V0.8  10/12/2018: Fixed bug with galaxy counting in multi-threading mode
V0.9  26/02/2019: Updated HDF5 module for increased flexibility with data type conversions
V0.10 26/03/2019: Better commenting, copy parameter file, instead of rewriting it
V0.11 29/04/2019: Improved cosmology module, general clean up, improved makefile
V0.12 12/09/2019: Bug fixes, developper version of HI-line module added
V0.13 19/09/2019: Emission line maker for HI and CO with many rotation curve models for halos, disks and bulges
v0.14 28/10/2019: Added pre_selection function to module_user_selections
v0.15 04/02/2020: New entry "make_groups" in the parameter file, id_galaxy_sky changed and id_galaxy_sky_smart added,
                  Included test data (shark subvolume L40_N512/199/0/)
v0.16 25/02/2020: Input argument check fixed
v0.17 01/03/2020: Changed id_galaxy_sky in shark user module to better cope with Viperfish
v0.20 20/04/2020: Significant restructuring of the code, inclusion of shared modules
v0.21 21/04/2020: Use of system-independent pseudo-random number generator
v0.22 21/04/2020: Completely revised layout of module "module_user_selection"; only one function per survey needed
v0.23 23/04/2020: Implementation of parameter sets; new parameter "options"; added CO lines to shark module
v0.24 23/04/2020: Many additional galaxy properties, including all those added to stingray by Claudia Lagos
v0.25 23/04/2020: All in Fortran 2008 standard
v0.26 24/04/2020: Default parameterset via "parameterset*"
v0.27 30/04/2020: Added module "shared_module_vectors", removed module "module_interface", minor fixes, comments
v0.28 01/05/2020: New module "module_selection_tools" to simplify "module_user_selection_..."
v0.29 04/05/2020: Parameter file with logical types, improved automatic parameter evaluation via set_auto_parameter routine
v0.30 10/05/2020: New projection methods (see randomisation parameter)
v0.31 11/05/2020: Various OOP improvements; packed relevant snapshot/tile/shell data into type_base for interfacing with user
v0.32 18/05/2020: Updated makefile; optional developer parameters added
v0.33 20/05/2020: Minor bug fix in shared modules
v0.34 21/06/2020: Corrected CO fluxes
v0.35 25/06/2020: Temporary folder for processing, added stingray_timestamp to output
v0.36 07/12/2020: Improved documentation
v0.37 11/12/2020: Fixed illegal tmp file names, added DSA-2000 as examples in shark selection
v0.38 18/08/2022: New way of assigning unique galaxy IDs to avoid duplicated indices for duplicated galaxies; bug fix with zobs
v0.39 21/10/2024: Relax requirement that each group must have exactly one central, to each group must have at most one central
v0.40 21/10/2024: Updated makefile

Developed by Danail Obreschkow (danail.obreschkow@icrar.org)


GETTING STARTED
=================================================================================================================================

1) Prerequisites:
   a) make sure gfortran is installed (code tested for GNU Fortran 9.3.0) and available;
      on some systems, it may be necessary to load the compiler using something like
      > module load gfortran
   b) make sure that HDF5 is installed (version 1.10.1 or higher) and available;
      on some systems, it may be necessary to load the library using something like
      > module load gfortran hdf5
   c) set the environment variable HDF5_DIR to the directory containing the HDF5 module ($DF5_DIR/include and $HDF5_DIR}/lib),
      e.g. use
      > export HDF5_DIR=...

2) In terminal, download Stingray
   > git clone https://github.com/obreschkow/stingray
   
3) Go to stingray directory
   > cd stingray
   
4) Clean potential previous compilations
   > make clean
   
5) Compile the code by typing
   > make
   NB: There are optional arguments ('sam', 'system', and 'mode') described in the makefile'.
   For example, to activate all debugging flags, use
       > make mode=dev
       
6) Check stingray version
   > ./stingray -v
       
7) Try to run the test-cone using the
   > ./stingray
   NB: This command assumes the default parameter file "parameters.txt" to be in the current directory.
       Otherwise you must specify the path+filename of the parameter file using the option -parameterfile ...
       
The command above should produce a sky containing 502 galaxies in 488 groups. These data is written in the directory "example".

To produce your own, custom-made mock sky,

8) Edit the parameter file parameter.txt as required. (see explanations in default parameter file)

9) Edit the selection function "module_user_selection_..." as required. (see explanations in the default module)
   
10) Produce mock observing cone
    > ./stingray [-parameterfile .../parameter.txt] [-parameterset ...]
    
If using a SAM other than Shark, you need to also update the module "module_user_routines_..."
   

QUICK START ON ICRAR-HYADES
=================================================================================================================================

# To install and compile stingray in your home directory, run the following code in the remote terminal:
cd ~
rm -rf stingray/ # remove previous surfsuite directory
git clone https://github.com/obreschkow/stingray # install updated version
cd stingray # change to surfsuite directory
module load gfortran hdf5 # load required modules
make system=hyades # compile code

# Verify stingray installation and version
./stingray version

# To run a quick test execute the following line (still from within the stingray directory):
./stingray

# The sky should contain 502 galaxies in 488 groups. These data are written in the directory "example".
# Do *not* keep executing stingray this way, but submit a job to the workload manager.


QUICK START ON PAWSEY-SETONIX
=================================================================================================================================

# To install and compile stingray in your home directory, run the following code in the remote terminal:
cd ~
rm -rf stingray/ # remove previous surfsuite directory
git clone https://github.com/obreschkow/stingray # install updated version
cd stingray # change to surfsuite directory
latest_hdf5=$(module avail hdf5 2>&1 | grep -o 'hdf5/[0-9.]\+-api-[a-z0-9]\+' | sort -V | tail -n 1)
module load "$latest_hdf5" # load latest HDF5 version
export HDF5_DIR=$(module show "$latest_hdf5" 2>&1 | grep -o '/[^ ]*/hdf5-[^ ]*' | head -n 1 | sed 's/[")]*$//')
make # compile code

# Verify stingray installation and version
./stingray version

# To run a quick test execute the following line (still from within the stingray directory):
./stingray

# The sky should contain 502 galaxies in 488 groups. These data are written in the directory "example".
# Do *not* keep executing stingray this way, but submit a job to the workload manager.


ARGUMENTS
=================================================================================================================================

Generally, Stingray is called as
> ./stingray [-option argument] [-option argument] ...

Optional arguments:

-parameterfile (default parameters.txt): path+filename of parameter-file

-parameterset: if this option is specified, e.g. "-parameterset abc", the parameters listed in this parameterset, e.g. between
 the lines "parameterset abc" and "end" overwrite the default parameters specified outside the parameterset. The user can mark
 at most one parameterset in the parameterfile as the default parameterset using an asterix: "parameterset* abc". This
 parameterset is taken as the default, if the option "-parameterset" is not provided. If no parameterset is marked as default
 and if no parameterset is selected via "-parameterset", all parameters in parametersets are ignored.

-logfile (default none) optional filename of an ascii-file for the screen output

-verbose (default n if logfile given, otherwise y): logical flag (y or n) specifying whether the log should be
 displayed on the screen
 
-version: returns the version of Stingray