Introduction
Building confidence in a mission concept’s ability to achieve its science goals is always desirable. Unfortunately, accurately modeling the science yield of an exoplanet imaging mission can be almost as complicated as designing the mission itself. It is challenging to compare science simulation results and systematically test the effects of changing one aspect of the instrument or mission design.
EXOSIMS addresses this problem by generating ensembles of mission simulations for exoplanet direct imaging missions to estimate science yields—what is known as Monte Carlo Mission Simulation (MCMS). It is designed to allow systematic exploration of exoplanet imaging mission science yields. It consists of stand-alone modules written in Python which may be modified without requiring modifications to other portions of the code. This allows EXOSIMS to be easily used to investigate new designs for instruments, observatories, or overall mission designs independently.
Purpose and Scope
The MCMS approach, and many of the algorithms used by EXOSIMS are extensively described in the academic literature (in particular in [Savransky2010] and [Savransky2015], but see also the rest of the References). This documentation is intended to provide an overview of the software framework of EXOSIMS and details on its component parts. As the software is intended to be highly reconfigurable, operational aspects of the code are emphasized, with a focus on required input/output interfaces for all pieces of the framework. Users wishing to implement their own EXOSIMS modules should read all of this. Users who only wish to use existing implementations to run simulations (or generate intermediate products like synthetic planets or keepout maps, etc.) can skip to Quick Start Guide (but should probably also read the references to understand the code’s operational principles).
Framework
EXOSIMS is composed of 14 distinct object classes (called ‘modules’):
BackgroundSources
Encodes information about background (astrophysical confusion) sourcesCompleteness
Provides methods for computing single-visit and dynamic completenessObservatory
Encodes information about the observatory spacecraft (and any external occulter spacecraft) and provides methods for orbital propagation and fuel use computationOpticalSystem
Encodes everything about the science instrument(s), starlight suppression system(s), and provides methods for calculating integration timesPlanetPhysicalModel
Provides models of planet physical attributes (e.g., density and albedo models)PlanetPopulation
Encodes distributions of planet physical and orbital parameters and provides methods for sampling themPostProcessing
Encodes effects of image post-processingSimulatedUniverse
Provides methods for generating synthetic universes composed of real stars and fake planets (or mixtures of real and fake planets) and encodes exosystem informationStarCatalog
Input catalog of potential target starsSurveySimulation
Provides methods for scheduling and simulating full observing programsSurveyEnsemble
Provides methods for running ensembles of survey simulationsTargetList
Provides methods for filtering input star catalogs into final target lists and stores all required star information for the final target list.TimeKeeping
Encodes information about mission timeZodiacalLight
Information about local and exo-zodiacal light
EXOSIMS provides a reference implementation (called ‘prototypes’) for each of these 14 modules, along with multiple additional implementations of most module types. Different implementations of the modules contain specific mission design parameters and physical descriptions of the universe, and will change according to the mission and planet population of interest. The prototype implementations (and especially their docstrings) provide the input/outptut specification (interface control) for the framework. Every module implementation must inherit a prototype module, and any method overloading a method defined in a prototype implementation must conform to the inputs/outputs of the prototype method.
In addition to the 14 modules, there is a top-level MissionSim
class, used to instantiate objects of all 14 module types required to run a full simulation ensemble. The MissionSim
works with an input specification file (see Input Specification) to set input parameters throughout all of the modules.
The overall framework of EXOSIMS is depicted in Fig. 1, which shows all of the component
software modules in the order in which they are instantiated. Instantiating a MissionSim
object will automatically instantiate 14 objects (accessible as attributes of the MissionSim
).
Objects of all module classes can be instantiated independently,
although most modules require the instantiation of other modules during
their initialization—generating an object of any type will also generate objects of
all downstream module classes, as depicted in Fig. 1.
The upstream
modules (including TargetList
, SimulatedUniverse
, SurveySimulation
, and SurveyEnsemble
) use attributes and methods from
downstream modules and perform mission simulation tasks. Any module may
perform any number or kind of calculations using any or all of the input
parameters provided to the full framework. The specific implementations are only constrained
by their input and output specification, as encoded by the prototypes. When creating new
implementations, it can always be assumed that a module of a given type has access to
all downstream module objects at runtime.
Terminology
The terminology used to describe the EXOSIMS software is loosely based upon object-oriented programing (OOP) terminology, and, in particular on the Python language and conventions. The term module can refer to the object class prototype representing the abstracted functionality of one piece of the software, an implementation of this object class which inherits the attributes and methods of the prototype, or an instance of this class. Input/output definitions of modules refer to the class prototype. Implemented modules refer to the inherited class definition. Passing modules (or their outputs) means the instantiation of the inherited object class being used in a given simulation. Relying on strict inheritance for all implemented module classes provides an automated error and consistency-checking mechanism. The outputs of a given object instance may be compared to the outputs of the prototype. It is trivial to pre-check whether a given module implementation will work within the larger framework, and this approach allows for flexibility and adaptability.
Directory Layout
The EXOSIMS repository directory structure is:
EXOSIMS/
│
├── EXOSIMS/
│ ├── BackgroundSources/
│ ├── Completeness/
│ ├── Observatory
│ ├── OpticalSystem
│ ├── PlanetPhysicalModel
│ ├── PlanetPopulation
│ ├── PostProcessing
│ ├── Prototypes
│ ├── Scripts
│ ├── SimulatedUniverse
│ ├── StarCatalog
│ ├── SurveyEnsemble
│ ├── SurveySimulation
│ ├── TargetList
│ ├── TimeKeeping
│ ├── ZodiacalLight
│ ├── run
│ └── util
│
├── tests/
│ ├── BackgroundSources/
│ ├── Completeness/
│ ├── Observatory
│ ├── OpticalSystem
│ ├── PlanetPhysicalModel
│ ├── PlanetPopulation
│ ├── PostProcessing
│ ├── Prototypes
│ ├── SimulatedUniverse
│ ├── StarCatalog
│ ├── SurveyEnsemble
│ ├── SurveySimulation
│ ├── TargetList
│ ├── TestModules
│ ├── TestSupport
│ ├── TimeKeeping
│ ├── ZodiacalLight
│ └── util
│
├── documentation/
The top-level EXOSIMS directory (the one containing all subfolders and the setup.py
file) is referred to as the EXOSIMS root directory. The code resides in the EXOSIMS
sub-folder, defining the top-level EXOSIMS
package, which has 16 sub-packages. The Prototypes
sub-package contains all of the prototype module implementations as sub-modules. Additional implementations of each module type are sub-modules to sub-packages of the same name as the module type (i.e., all Completeness implementations other than the prototype are submodules of Completeness
, etc.). The 16th sub-package is util
and contains various utilities used by the EXOSIMS modules as well as standalone analysis and plotting tools. The EXOSIMS top-level directory also contains two additiona folders that are not sub-packages of the code. The Scripts
directory contains sample and template input specification files. The run
directory contains methods for parallel code execution (see SurveyEnsemble for more details).
The tests
directory mirrors the layout of the EXOSIMS package, with additional folders for test support code. Further details are provided in Testing.