Help page for Roman EXOSIMS-UI

Overview

EXOSIMS-UI (User Interface) is the Web-based interface to the EXOSIMS open-source python simulation code, developed by Dmitry Savransky, Christian Delacroix, and Daniel Garrett at Cornell and SIOS Lab.

For detailed information, please see the Source Code Reference Manual.

EXOSIMS-UI is a Web-based GUI for running the EXOSIMS simulator for you on our server. The results are presented to you via your browser.

Please be patient. Some queries may take several tens of minutes to run. How long a query takes depends on several factors. Performance may also be affected by other activity on our server.

The results you see will not be stored permanently on our server. When you see results you want to keep, remember to save them onto your local disk. We will try to provide a grace period of a month during which you may save your results.

Below you will find sections on:

EXOSIMS Operations
Inputs
Output

The Result Page
How to Save Your Results
Email Calculation Results

EXOSIMS Operations

The Exoplanet Open-Source Imaging Mission Simulator (EXOSIMS) is a sophisticated python-based simulation software that provides planetary yield estimates for space-based coronagraphic missions. EXOSIMS incorporates Monte Carlo completeness modeling, simulates a planet-finding survey given a target list and other constraints, and optimizes the observing time during a given mission lifetime. Surveys using the coronagraphic instrument aboard the Roman Space Telescope will require hours if not days of observing time to detect planets at flux ratios down to 10^-9 with respect to the stellar flux. To help plan and optimize the telescope time and an observer's mission yield, this user interface has been developed around EXOSIMS here at IPAC.

EXOSIMS is not meant to be used as a stand-alone exposure time calculator. It generates a complete observing sequence for the set of input targets and help the user understand the likelihood of detection. The simulation performs the following tasks prior to simulating a full survey:

I) Simulated Universe:

1) Target Generation: EXOSIMS begins by creating a simulated universe based on the targets the user intializes. Targets are populated with basic stellar information, such as mass and visual magnitudes, colors, etc., from empirical relations documented in the EXOSIMS ICD. It stores the positions, parallaxes and other essential stellar metadata as well. EXOSIMS will then simulate planets around each target. The number and range of masses for each planet in the system depends on whether one wishes known planets or distribution-sampled planets and their masses to be simulated. Simulated or calculated planet masses and separations are then used to calculate planet orbital and physical properties. The mass, size, and orbital location of the planet are used to calculate the albedo using the Lambertian approximation, which then provides a flux ratio estimate between the planet and star.

EXOSIMS also calculates the contribution of astrophysical noise from background sources. In particular, background sources are generated based on the position of the star on the sky. Contribution of emission from the local zodiacal dust is based on the pointing vector of the spacecraft, while the exozodiacal dust emission is a function of stellar separation. Both are factored into the noise budget of the observations.

2) Completeness Calculation: EXOSIMS prioritizes targets based on the probability of detection calculated from its obscurational and photometric completeness distribution in contrast and separation phase space. The basic method of calculating this completeness follows a brute-force Monte Carlo approach, outlined in Brown (2005). EXOSIMS is capable of calculating the completeness for each target using a Monte Carlo approach, or analytically, developed by Garrett & Savransky (2016). EXOSIMS-UI facilitates the analytical calculation of the completeness.

Throughout the survey, the completeness for visited targets is updated. Targets with completeness levels greater than the user-specified minimum completeness threshold and less than the maximum integration cutoff threshold will be scheduled for observations.

II) Survey Specifics:

1) Observatory: The telescope specifications are managed by EXOSIMS. For the EXOSIMS-UI, we are using the standard EXOSIMS definition of the Roman Space Telescope in an L2 orbit.

The code tracks the orbit of the Roman Space Telescope in a heliocentric equatorial frame based on the user-specified mission start time and assumed initial orbital parameters. The user can specify a cumulative telescope overhead time that is then factored into the total survey time. Additionally, the observatory module in EXOSIMS determines whether targets are observable based on a user-specified keepout angle with respect to solar system objects.

2) Optical System: The optical system in EXOSIMS can be split into three main categories: telescope optical system, science instruments, and starlight suppression systems. EXOSIMS also includes the limiting delta magnitude of observations, telescope keepout angle, and maximum allowed integration time for a single observing sequence.

The telescope optical system defines the secondary mirror obscuration factor, unobscured pupil shape factor, pupil diameter/area, and optical throughput. These parameters are fixed and not accessible to the user.

The science instruments are currently restricted to the imaging EMCDD and the integral field spectrograph (IFS). For both, the detector pitch, focal length, dark current, clock induced charge, read noise, excess noise factor (ENF), resolving power, quantum efficiency, and per frame exposure time are defined. These parameters are fixed and not accessible to the user. For more information on fixed parameters, please see the IPAC Roman Space Telescope Parameters Page.

The stellar suppression systems are the coronagraphic systems that we expect the Roman Space Telescope to launch with. Currently, we offer the interface for the hybrid lyot coronagraph (HLC) and the shaped pupil coronagraph (SPC). The parameters for these systems include (but are not limited to) their system throughput, core contrast, core area, platescale, and a system set-up overhead cost. The inner working angle (IWA) and outer working angle (OWA) are fixed for each system at a particular central wavelength and bandwidth. The IWA and OWA are later scaled to the user-specified central wavelength and bandwidth.

The optical system calculates the electron count rate for the planet, background, and speckle signals, and determines the integration time required for a specific target.

III) Time Management:

The time keeping portion of EXOSIMS starts with the user specifying the modified Julian start date of the survey, the total mission lifetime, and the fraction of the mission which can be allocated to the Coronagraph Instrument portion of the survey. From there, the total time for the Coronagraph Instrument survey is allocated, and observing intervals are calculated for each target. Once all the available time has been used up, the simulation ends.

Inputs

/p> EXOSIMS contains a large number of available input parameters, as the code can be adapted to any space-based coronagraphic mission. For the UI, we have provided the user the option to select a limited number of parameters, as those related to the Roman Space Telescope spacecraft and instruments have been fixed. All parameter values are provided to the user in the final output file for inspection. Here are the parameter categories that link to details of all the parameters included. Parameter ranges can also be revealed by hovering over the input box on the front page.

Mission Parameters
Built-in Targets
HLC Imaging and Detection System
SPC IFS and Characterization System

Mission Parameters

Length of Mission

The total Roman Space Telescope mission lifetime (Wide-Field Imager AND Coronagraph Instrument) in units of years.

Allowed range from 0.0 to 6.0 (default: 5.0).

EXOSIMS parameter name: missionLife.

Portion of Mission

The portion of the Roman Space Telescope Length of Mission that is dedicated to observations with the Coronagraph Instrument, and specifically to this project with the parameters listed on this GUI. NOTE: this refers to the particular simulation run by the user. This is not the TRUE overall amount of Roman Space Telescope time dedicated to the Coronagraph Instrument.

Allowed range from 0.0 to 1.0 (default: 0.1667).

EXOSIMS parameter name: missionPortion.

Mission Extension

Amount of time to add to the initial mission time. This will typically only include revisits.

Allowed range from 0.0 to 3.0 years (default: 0.0 years).

EXOSIMS parameter name: extendedLife.

Start of Mission

Modified Julian Date (MJD) of the Roman Space Telescope mission start.

Allowed range greater than or equal to 57754.0 MJD (default: 60676.0, corresponding to January 1st, 2025).

EXOSIMS parameter name: missionStart.

Star-to-Planet Contrast Limit

Fundamental limiting magnitude (contrast) difference between the star and planet to which the the mission will be sensitive.

Allowed range from 5.0 to 27.0 mag (default: 20.0 mag).

EXOSIMS parameter name: dMagLim.

Settling Time

Amount of time, in units of days, needed for observatory to settle after a repointing.

Allowed range greater than 0.0 days (default: 0.02 days).

EXOSIMS parameter name: settlingTime.

Minimum Completeness Inclusion (MCI)

The minimum completeness level for each target to be included in the survey. The single-visit obscurational and photometric completeness is derived from the joint probability of detecting the planet, calculated using an analytical approach shown in Garrett & Savransky (2016), derived from the Monte Carlo approach by Brown (2005). If the MCI is below the user-selected “Minimum Completeness Inclusion”, that star is not included in the simulations.

Allowed range from 0.0 to 1.0. (default: 0.02).

EXOSIMS parameter name: minComp.

Telescope Keepout

This defines the angular region centered on Solar System objects within which to ignore any targets.

Allowed range from 0.0 to 360.0 degrees (default: 10.0 degrees).

EXOSIMS parameter name: telescopeKeepout.

Max Integration Time

Maximum allowed integration time for any target in units of days per target. No integrations will be started that would take longer than this value.

Allowed range greater than 0.0 days (default: 30.0 days).

EXOSIMS parameter name: intCutoff.

Planet Occurrence Rate

This is the average occurrence rate of planets per target for the entire population. This can be seen as a rate parameter of a Poisson distribution, from which the number of planets per target is drawn. This does not guarantee that targets will have a minimum of at least 1 planet (if simulating a non-RV target list case).

Allowed range greater than 0.0 (default: 0.1).

EXOSIMS parameter name: eta.

Post-processing Gain

Assumed gain in planet to star contrast once post-processing techniques are applied. Currently this gain is assumed uniform at all angular separations.

Allowed range from 0.0 to 1.0 (default: 0.3 = 30% gain).

EXOSIMS parameter name: ppFact.

False Alarm Probability

Planet detection false alarm probability.

Allowed range greater than 0.0 (default: 0.0000003).

EXOSIMS parameter name: FAP.

Missed Detection Probability

Probability that a planet detection was missed.

Allowed range greater than 0.0 (default: 0.001).

EXOSIMS parameter name: MDP.

Built-in Targets

Target List

Currently there are three types of target sets that can be used.

RV Planets + Known RV Host Stars: This is a list of known radial velocity planets and their host stars taken from the NExScl Exoplanet Archive. As described further in the EXOSIMS docstring, the eccentricity and semi-mjor axis distributions are the same distributions used in the simulation of the Kepler-Like planets (i.e. Rayleigh and power-law with exponential decays, respectively). The planet radii are calculated from the mass via planet physical models from Chen & Kippling (2016).

Earth Twin Hab Planets + EXOCAT: This population of planets is simulated assuming twins of the Earth (Earth radius mass, and albedo) on circular, habitable zone orbits from 0.7 to 1.5 au. The list of host stars comes from EXOCAT.

Kepler-Like Planets + EXOCAT: This population of planet simulations combines the Kepler-discovered planet-radius distribution with an RV-like semi-major axis distribution with an exponential decay. The list of host stars comes from EXOCAT.

HLC Imaging and Detection System

This section defines the parameters for the Hybrid Lyot Coronagraph and corresponding imaging EMCCD system used for initial planet detection. The Roman Space Telescope system parameters are fixed (e.g., inner working angle, read noise, etc.) as per specifications from the IPAC Roman Space Telescope Parameters page.

Imaging Central Wavelength

Central wavelength of the bandpass used for planet detection with the EMCCD. Coronagraph inner and outer working angles are automatically scaled to the selected wavelength.

Allowed range from 400 to 1000 nm (default: 550 nm). Parameter name: Dlam.

Imaging Bandwidth

Bandwidth (FWHM/lambda) of the filter centered on the set central wavelength.

Allowed range from 0.1 to 1.0 (default: 0.1). Parameter name: DBW.

Imaging SNR

Signal to Noise Ratio threshold for detection.

Allowed range greater than or equal to 1.0 (default: 5.0). Parameter name: DSNR.

Imaging Optical System Overhead

Optical system overhead time. This is the constant amount of time required to set up the optical system (i.e., dig dark hole, find alignment with occulter). This is added to every observation, and is separate from the observatory overhead (i.e., settling time). Both overheads are added to the integration time to determine the full duration of each detection observation.

Allowed range greater than 0.0 days (default: 0.1 days). Parameter name: DohTime.

IFS and Characterization System + SPC

This section defines the parameters for the Shaped Pupil Coronagraph and corresponding integral field spectrograph used for detected planet characterization. The Roman Space Telescope system parameters are fixed (e.g., inner working angle, read noise, etc.) as per specifications from the IPAC Roman Space Telescope Parameters page.

IFS Central Wavelength

Central wavelength of the bandpass used for planet characterization with the IFS. Coronagraph inner and outer working angles are automatically scaled to the selected wavelength.

Allowed range from 400 to 1000 nm (default: 550 nm). Parameter name: Clam.

IFS Bandwidth

Bandwidth (FWHM/lambda) of the IFS centered on the central wavelength.

Allowed range from 0.1 to 1.0 (default: 0.1). Parameter name: CBW.

IFS SNR

Signal to Noise Ratio threshold for characterization.

Allowed range greater than or equal to 1.0 (default: 5.0). Parameter name: CSNR.

IFS Optical System Overhead

Allowed range greater than 0.0 days (default: 0.1 days). Parameter name: CohTime.

Action Buttons

Submit: Submit the calculation to run in the background. You will be forwarded to the result page which will auto-refresh itself until results are displayed.
Set Defaults: Reset numeric fields to their default values; enable all controls which are enabled by default.

Output

result page

The Result Page

Each run has its own unique page to display the results of the calculation. For long runs, this page will auto-refresh until results are ready. This can take several minutes, or longer if the job has to wait in the queue. There is a button to cancel the calculation in case you realize it was not what was intended.

The result page also offers a link to a tar file containing the same information as that displayed on the result page plus other files associated with your run.

The result page displays this content:

Run Information: This section displays the time the run was submitted for processing, and the unique ID assigned to the run.
Run Parameters: This section displays the parameters specified on the web form, as described above.
Run Output: When the run has completed, this section shows the textual output from the run, including all the results of the performance calculations. For long runs, a status message will be displayed until results are ready.

These links are available:

Start a New Calculation: Return to the EXOSIMS-UI form with default values filled in.
Modify This Calculation: Return to the form with the values used in this calculation filled in.
Download Full Results: Open a file download dialog to download a tar file containing your results (see below).

How to Save Your Results

result page.

Results.html: the result web page.
Out.txt: the run output.
RunParameters.txt: the run parameters.
RunInfo.txt: the run information.
simResults.csv: This file contains data from the simulation. All the simulation input parameters (from the UI and internally fixed ones) are listed at the top of the file as comments preceded by "#". Each row consists of the EXOSIMS parameter and associated value, comma separated. The rest of the file contains information on the stars and their parameters used in the simulation (column names preceded by "st_"), associated planets (column names preceded by "pl_") and detection descriptors. The column descriptions are included in "headerinfo.csv".
headerinfo.csv: Text file containing a description of all the columns in "simResults.csv".

Email Calculation Results

When processing is finished, a notification and run output can be sent by email to a given address. The notification includes:

the run's input;
the textual output;
a link to the result page.

Nancy Grace Roman Space Telescope Simulations