Overview of Roman I-Sim

This article provides an overview of Roman I-Sim , a GalSim-based imaging simulator for the Wide Field Instrument (WFI) of the Nancy Grace Roman Space Telescope (Roman), how to install it, and the minimum requirements for a successful simulation. Additional information can be found on the dedicated readthedocs documentation.  




Installation of Roman I-Sim


Roman I-Sim relies on a few dependencies, both in terms of Python packages and C libraries. All python dependencies are installed via pip except for the C library FFTW.

Software dependencies can be found in the relevant block of the pyproject.toml file in the github repository of Roman I-Sim .

Some of the main dependencies include asdf, rad, gwcs and roman_datamodels, which are needed to deal with Roman's ASDF file format; galsim is the simulator engine; astropy is mainly used for catalog I/O and for dealing with units; webbpsf and crds are needed to tailor simulations to the use of Roman PSF and reference files.

We recommend new users closely follow the installation steps detailed below for a smooth experience.

Step 1 - New Conda Environment

If possible, create a new environment specifically for  Roman I-Sim   as installed packages may sometimes conflict with some of the dependencies  Roman I-Sim needs. A clean environment usually fixes these types of issues. Next, activate the new environment. If using Conda, the commands are:

Shell command
conda create -n "env.name" python=3.12
conda activate "env.name"
 where "env.name" is the name of the environment you want to create, and where the last argument in the create command is optional and allows the user to specify a python version for the environment.


Step 2 - FFTW for Galsim

Roman I-Sim requires the Galsim package, which itself requires FFTW, a set of discrete Fourier transform libraries written in C. It is critical that the FFTW libraries are installed before galsim.


Note

Step 2 is needed regardless of the computer architecture, but is only required in case you don't already have FFTW installed and configured on your system. If you do, please skip to Step 3.

First, download and install the FFTW libraries following the instructions on the respective website https://www.fftw.org/

Note

FFTW versions from 3.3.7 to 3.3.10 are known to work with Galsim. Other versions of FFTW might also work but have not been tested.

Next, make sure the environment variable FFTW_DIR is correctly set. In a bash environment, this is done by adding the following line in ~/.bashrc or ~/.bash_profile as follows:

Bash
export FFTW_DIR='install.dir'

where 'install.dir' is the directory in which FFTW has been installed. Make sure the environment variable is active in your current terminal before proceeding to Step 3.

Warning

GalSim needs to know where the FFTW libraries are. If the environment variable FFTW_DIR is not set and active, GalSim (and hence Roman I-Sim ) will install incorrectly and will not run.


Step 3 - Roman I-Sim

From here, you can proceed with the normal installation of Roman I-Sim , e.g., via pip install: 

Shell command
pip install romanisim


Step 4 - WebbPSF and CRDS

Installation of WebbPSF and the Calibration Reference Data System (CRDS) python package is strongly encouraged to ensure  Roman I-Sim uses the correct Roman PSF models and the correct calibration reference files stored in CRDS.

When CRDS isn't called with --usecrds, then  Roman I-Sim uses simplified and outdated defaults that will significantly degrade the accuracy of the simulated products. Running  Roman I-Sim without CRDS is not advised. 

When WebbPSF is called with --webbpsf but WebbPSF is not available, then Roman I-Sim will provide an error message. When WebbPSF isn't called, GalSim is used to model the Roman WFI PSFs instead. 

  • For the installation of the Roman module of WebbPSF, please follow the instructions posted here. Make sure the WEBBPSF_PATH environment variable is set correctly. In a bash environment, this is done as follows: 
    Bash
    export WEBBPSF_PATH='install.dir'

where 'install.dir' is the directory in which the WebbPSF data has been installed. (Also add this command line in your ~/.bashrc or ~/.bash_profile.)

  • To install CRDS, follows the instructions posted here. In this case, there are 2 environment variables that need to be set up: CRDS_SERVER_URL and CRDS_CONTEXT. In a bash environment, this is done as follows: 
    Bash
    export CRDS_SERVER_URL='https://roman-crds.stsci.edu'
export CRDS_CONTEXT='roman_00XX.pmap'

where 'roman_00XX.pmap' is the current operational context. You can check the version number of the current operational context on the Roman CRDS website.

(Again, make sure you also add these command lines in your ~/.bashrc or ~/.bash_profile.)

Tip

Make sure that the current operational CRDS context is selected, so that the most up-to-date Roman calibration reference files are used by  Roman I-Sim . You can verify this by looking at the most up-to-date context in the Roman CRDS website.



Roman I-Sim Workflow

Roman I-Sim can operate in two distinct ways:

  1. Via command line, e.g., using the romanisim-make-image executable, together with a suite of command-line arguments that help characterize the simulated image (see, e.g., Running Roman I-Sim on readthedocs for a quick reference).
  2. Via direct calls of methods and functions within a python script. We refer the user to Roman I-Sim Image readthedocs page for more information on the functionality of specific modules and functions.

The former is meant for general simulations of level-1 and level-2 imaging data, while the latter allows the users to perform more sophisticated actions, including creating parametric catalogs of sources and other useful functionalities.

Example scripts and tutorials are available at this Roman I-Sim Tutorial page on RDox.



Acknowledgements

Roman I-Sim is written and maintained by the Roman Science Operations Center (SOC) at STScI.


For additional questions not answered in this article, please contact the Roman Help Desk at STScI.



References



Latest Update

Publication

 

Initial publication of article.