FORECAST

FORECAST is a new flexible and adaptable software package that generates realistic astronomical images and galaxy surveys by forward modeling the output snapshot of any hydrodynamical cosmological simulation. With customizable options for filters, size of the field of view, and survey parameters, it allows users to tailor the synthetic images to their specific research requirements.

Table of Contents

1. In a few words
2. Requirements
3. How to install and run
4. Pipeline
5. Configuration file
6. Input files format
7. Output description
8. Contributing
9. Citation and Acknowledgement

In a few words

FORECAST constructs a lightcone centered on the observer's position exploiting the output snapshots of a chosen simulation and computes the observed fluxes of each simulated stellar element, modeled as a Single Stellar Population (SSP), in any chosen set of pass-band filters, including k-correction, IGM absorption, and dust attenuation. These fluxes are then used to create an image on a grid of pixels, to which observational features such as background noise and PSF blurring can be added with our Python script to post-process the images (upon request), or by the user with their own script.

Requirements

FORECAST is written in C and C++; it is supported by independent libraries to make the code more readable and user-friendly. It requires the following C/C++ standard libraries:

• GSL
• openBLAS
• LAPACK
• CCfits
• CFITSIO
• FFTW
• Eigen
• Armadillo
• H5Cpp
• HDF5 C++
• gcc compiler
• bc03 or [cb16](flaminia.fortuni at inaf.it) SSP models.

How to install and run

• Download the code with the "Code" green button on this page, or clone it with git clone https://github.com/flaminiafortuni/FORECAST
• Download and install the required C/C++ libraries (see Requirements)
• Download the hydrodynamical simulation snapshots as input files (e.g., IllustrisTNG, EAGLE)
• In each of the four modules (lc, df, dc, igm):
  1. open the Makefile and link proper libraries (change only "LIBS" an "ALLFLAGS" paths; e.g., in line -L/usr/local/lib/ -lgsl -lgslcblas \ change only /usr/local/lib/)
  2. compile the Makefile(s) with make
• Change paths and parameters in the input configuration file \*.ini (in each module; see Configuration file for further details)
• Write the list of filters in the file filters.dat located in files folder, exactly as you named them in your filters folder (e.g., if you want to use VIMOS_U.dat, in the list, you will write VIMOS_U). Ensure that the filter file contains no header and consist of two columns: wavelength in AA and filter transmission
• Modify *module*.sh by writing the snapshots you want to run on (single available snapshot or a list), and run bash *module*.sh or sh *module*.sh (one partition per time; refer to planes_list file to choose the partition/(snapshot,plane) pair).

Pipeline

The FORECAST code, currently available in beta version, is structured into four interconnected modules; each module relies on the output of the previous one. The first and third modules require the input file from the snapshots of hydrodynamical simulation to extract relevant properties of the simulated stellar and gas resolution elements.

The architecture of the code is serial. To construct the full lightcone, the lc module must be executed N times, where N is the number of partitions that constitute the cone - a partition is identified by the (snapshot, plane) pair in the planes_list file. The same applies to the other modules and to post-processing script that creates the final image. This implies that the output of a single run is specific to the (snapshot, plane) pair.

• lightcone, lc The first module handles the construction of the light cone, exploiting the data products of a chosen hydrodynamical simulation. Its architecture details are recorded in the planes_list file, generated by executing this module. It contains the following information with columns: #plane_i, z_plane_i, Di[Mpc/h], Di+1[Mpc/h], Nreplication_i, snapshot_i, z_nominal_snapshot_i. In output, it produces an ASCII file containing the properties of the SSPs included in the field of view (IDs, coordinates, redshift, and physical properties), which is used as input file for the next module. This step might be skipped if a user already has their light cone, as long as the input file for the next module is written in the proper format.
• dust-free, df The second module computes the flux of each SSP within the field of view, applying k-correction. It takes as input the catalog generated in the previous step. It generates an ASCII file containing the properties of the star particles and their dust-free fluxes in the selected filters.
• dust-corrected, dc The third module addresses the computation of the dust attenuation caused by dust distributed in and around each galaxy. This attenuation is traced by gas resolution elements included in the hydrodynamical simulation, providing the necessary data to calculate the dust attenuation effects (gas metallicity and neutral hydrogen column density). The module relies on data products from the hydrodynamical simulation to extract gas properties; it also takes the catalog generated in the previous step as input. As output, it generates an ASCII file containing the properties of the star particles and their dust-corrected fluxes in the selected filters.
• IGM, igm The final module adds the IGM correction to dust-corrected fluxes, taking as input the catalog generated in the previous step and producing the final output catalog, which includes the physical properties of the stellar particles and their corrected fluxes.

Post-processing scripts

An independent C++ script handles the arrangement of the fluxes on a grid of pixels, with fov size and resolution chosen by the user. It follows the same approach of the main modules, running independently for each (snapshot, plane) pair and filter.
Two additional independent scripts, written in Python, are made available (i) to build the galaxy catalog, in ASCII format, from the N particle catalogs given in output by FORECAST; (ii) to post-process the FORECAST images with noise and PSF pipeline.

Configuration file

FORECAST is adaptable to the choices of the user by selecting a set of input parameters. The input parameters can be changed in the *module*.ini file(s). As an example, it is possible to choose the hydrodynamical simulation that provides the backbone of the light cone (box with side-length L_box); the highest redshift to be included, z_s, which determines the maximum distance covered by the light cone, D_s; the dimensions of the field of view, L_{fov} in degrees; the resolution of the ideal simulated images, in arcsecs; the filters, by the order they are written in the filters file; the SSP model (Bruzual&Charlot 2003, bc03; or Gutkin et al. 2016, cb16) and the IMF (Chabrier or Salpeter); the limiting magnitude within which to process objects using the dust model adopted in FORECAST; the paths where the simulations snapshot are stored, and where to store the outputs of the specific module.

Input files format

FORECAST works by taking as input the physical properties of stellar particles and gas cells recorded in each snapshot of the chosen simulation. Currently, the code reads input files in the IllustrisTNG format. Users are required to convert their data into the TNG format (*.hdf5 files with the same column names as TNG columns) to ensure the effective utilization of the code. Future updates to the code will include additional scripts to read input files from multiple hydrodynamical simulations in different formats, such as the EAGLE Project and the Simba Simulation data products.

For stellar particles (" PartType4 "), FORECAST requires:

• " Coordinates " x,y,z-comoving coordinates within the simulated volume, in ckpc
• " Masses " stellar mass, in $M_{\odot}$
• " InitialMass " initial stellar mass, in $M_{\odot}$
• " GFM_Metallicity " metallicity as $M_{Z}/M_{TOT}$
• " GFM_StellarFormationTime " scale factor indicating the exact time when a star is formed, to compute age in yr
• " particle subhalo membership ID " this info is not available; it is reconstructed with a designed algorithm that uses SubFind subhalo catalogs and Offset files, exploiting the specific organization of halos and subhalos within the catalog files.

For gas cells (" PartType0 "):

• " Coordinates " x,y,z-comoving coordinates of the geometrical center within the snapshot, in ckpc
• " Masses " gas mass, in $M_{\odot}$; needed to compute Volume
• " Density " gas comoving volume, in $ckpc^{3}$; needed to compute Volume
• " GFM_Metallicity " gas metallicity, in $M_{Z}/M_{TOT}$ (with $M_Z$ the total mass all metal elements)
• " ElectronAbundance " gas cell fractional electron number density in $ckpc^{-2}$ with respect total hydrogen number density,
• " InternalEnergy " gas cell internal (thermal) energy per unit mass $u$, needed to derive the neutral hydrogen column density
• " cell subhalo membership ID " same as for stellar particles

For the exact descriptions of the fields, please refer to IllustrisTNG/DataSpecification.

Output description

The outputs of the code are the catalogs (one for each partition and module), including the physical properties and the true fluxes of the simulated stellar particles. They are used to build the galaxy catalog, created with a post-processing script. The catalogs, both the particles and the galaxy ones, have different sizes depending on the number of particles (or galaxies) included in the field of view and typically grow in size as the redshift increases since more structures are included. The total size of output files is 1 TB. The output images are recorded on 16-bit floating-point FITS files. Each plane (projection on a bi-dimensional map of fluxes from a volume of the Universe included in the field of view, in a redshift range) occupies 3 GB, while the size of the final stacked image is 5 GB.

Contributing

Citation and Acknowledgment

When using the code, please cite the release paper Fortuni et al., 2023.

       author = {{Fortuni}, Flaminia and {Merlin}, Emiliano and {Fontana}, Adriano and {Giocoli}, Carlo and {Romelli}, Erik and {Graziani}, Luca and {Santini}, Paola and {Castellano}, Marco and {Charlot}, St{\'e}phane and {Chevallard}, Jacopo},
        title = "{FORECAST: A flexible software to forward model cosmological hydrodynamical simulations mimicking real observations}",
      journal = {\aap},
     keywords = {virtual observatory tools, galaxies: evolution, Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Astrophysics of Galaxies, 85},
         year = 2023,
        month = sep,
       volume = {677},
          eid = {A102},
        pages = {A102},
          doi = {10.1051/0004-6361/202346725},
archivePrefix = {arXiv},
       eprint = {2305.19166},
 primaryClass = {astro-ph.IM},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2023A&A...677A.102F},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}