Configuration File

Sorcha uses a configuration file to set the majority of the various required and optional parameters as well as providing the ability to turn on and off various calculations and filters applied to the input small body population. Details about the main settings and options available in the configuration files are described in the Inputs, Ephemeris Generator, Post-Processing (Applying Survey Biases) and Outputs pages.

The configuration file is using the Windowst INI file format. The configuration file is formatted into distinct sections with headers. The headers are enclosed in square brackets ([]). Below each header are the associated configuration variable key pair (e.g. configvariablename = value). Any lines started with '#' are considered comments and ignored when parsing the cofiguration file.

The presence or absence of various variables in the configuration file will turn on/off or initialize different functions and features within Sorcha.

Attention

Use the -c (--config) flag when using the sorcha run command on the terminal to specify the configuration file that Sorcha should use.

Example Configuration Files

We provide below example configuration files appropriate for setting up Sorcha to simulate what the LSST would discover. These example config files come installed with Sorcha and can be copied over to your working directory by typing on the command line:

sorcha init

Rubin Full Footprint

This configuration file is appropriate for running Sorcha using the Rubin LSSTCam (LSST Camera) full detector footprint.

  1# Sorcha Configuration File
  2# This configuration file will set up Sorcha to simulate what the LSST would discover.
  3# This version uses the full LSSTCam detector footprint to detect whether objects are lost to chip gaps.
  4# This is slightly slower than using a circular approximation, but more accurate.
  5
  6
  7[INPUT]
  8
  9# The simulation used for the ephemeris input. 
 10# ar=ASSIST+REBOUND interal ephemeris generation 
 11# external=providing an external input file from the command line
 12# Options: "ar", "external"
 13ephemerides_type = ar
 14
 15# Format for ephemeris simulation input file if a file is specified at the command line. 
 16# This is also the format to which ephemeris files will be written out, if specified.
 17# Options: csv, whitespace, hdf5
 18eph_format = csv
 19
 20# Sorcha chunk size: how many objects should be processed at once?
 21size_serial_chunk = 20000
 22
 23# Format for the orbit, physical parameters, and complex physical parameters input files.
 24# Options: csv or whitespace
 25aux_format = csv
 26
 27# SQL query for extracting data from the pointing database.
 28pointing_sql_query = SELECT observationId, observationStartMJD as observationStartMJD_TAI, visitTime, visitExposureTime, filter, seeingFwhmGeom as seeingFwhmGeom_arcsec, seeingFwhmEff as seeingFwhmEff_arcsec, fiveSigmaDepth as fieldFiveSigmaDepth_mag , fieldRA as fieldRA_deg, fieldDec as fieldDec_deg, rotSkyPos as fieldRotSkyPos_deg FROM observations order by observationId
 29
 30
 31[SIMULATION]
 32# Configuration for running the ASSIST+REBOUND ephemerides generator.
 33
 34# the field of view of our search field, in degrees
 35ar_ang_fov = 2.06
 36
 37# the buffer zone around the field of view we want to include, in degrees
 38ar_fov_buffer = 0.2
 39
 40# the "picket" is our imprecise discretization of time that allows us to move progress
 41# our simulations forward without getting too granular when we don't have to.
 42# the unit is number of days.
 43ar_picket = 1
 44
 45# the obscode is the MPC observatory code for the provided telescope.
 46ar_obs_code = X05
 47
 48# the order of healpix which we will use for the healpy portions of the code.
 49# the nside is equivalent to 2**ar_healpix_order
 50ar_healpix_order = 6
 51
 52
 53[FILTERS]
 54
 55# Filters of the observations you are interested in, comma-separated.
 56# Your physical parameters file must have H calculated in one of these filters
 57# and colour offset columns defined relative to that filter.
 58observing_filters = r,g,i,z,u,y
 59
 60
 61[SATURATION]
 62
 63# Upper magnitude limit on sources that will overfill the detector pixels/have
 64# counts above the non-linearity regime of the pixels where one can’t do 
 65# photometry. Objects brighter than this limit (in magnitude) will be cut. 
 66# Comment out for no saturation limit.
 67# Two formats are accepted:
 68# Single float: applies same saturation limit to observations in all filters.
 69# Comma-separated list of floats: applies saturation limit per filter, in order as
 70# given in observing_filters keyword.
 71bright_limit = 16.0
 72
 73
 74[PHASECURVES]
 75
 76# The phase function used to calculate apparent magnitude. The physical parameters input
 77# file must contain the columns needed to calculate the phase function.
 78# Options: HG, HG1G2, HG12, linear, none.
 79phase_function = HG
 80
 81
 82[FOV]
 83
 84# Choose between circular or actual camera footprint, including chip gaps.
 85# Options: circle, footprint.
 86camera_model = footprint
 87
 88# The distance from the edge of a detector (in arcseconds on the focal plane)
 89# at which we will not correctly extract an object. By default this is 10px or 2 arcseconds.
 90# Comment out or do not include if not using footprint camera model.
 91footprint_edge_threshold = 2.
 92
 93# Path to camera footprint file. Uncomment to provide a path to the desired camera 
 94# detector configuration file if not using the default built-in LSSTCam detector 
 95# configuration for the actual camera footprint.
 96# footprint_path= ./data/detectors_corners.csv
 97
 98
 99[FADINGFUNCTION]
100
101# Uses the fading function as outlined in
102# Chesley and Vereš (2017) to remove observations.
103
104# Width parameter for fading function. Should be greater than zero and less than 0.5.
105# Suggested value is 0.1 after Chesley and Vereš (2017).
106fading_function_width = 0.1
107
108# Peak efficiency for the fading function, called the 'fill factor' in Chesley and Veres (2017).
109# Suggested value is 1. Do not change this unless you are sure of what you are doing.
110fading_function_peak_efficiency = 1.
111
112
113[LINKINGFILTER]
114
115# SSP detection efficiency. Which fraction of the objects will
116# the automated Rubin Solar System Processing (SSP) pipeline successfully link? Float.
117SSP_detection_efficiency = 0.95
118
119# Length of tracklets. How many observations of an object during one night are
120# required to produce a valid tracklet?
121SSP_number_observations = 2
122
123# Minimum separation (in arcsec) between two observations of an object required 
124# for the linking software to distinguish them as separate and therefore as a valid tracklet.
125SSP_separation_threshold = 0.5
126
127# Maximum time separation (in days) between subsequent observations in a tracklet. 
128# Default is 0.0625 days (90mins).
129SSP_maximum_time = 0.0625
130
131# Number of tracklets for detection. How many tracklets are required to classify
132# an object as detected? 
133SSP_number_tracklets = 3
134
135# The number of tracklets defined above must occur in <= this number of days to 
136# constitute a complete track/detection.
137SSP_track_window = 15
138
139# The time in UTC at which it is noon at the observatory location (in standard time).
140# For the LSST, 12pm Chile Standard Time is 4pm UTC.
141SSP_night_start_utc = 16.0
142
143
144[OUTPUT]
145
146# Output format of the output file[s]
147# Options: csv, sqlite3, hdf5
148output_format = sqlite3
149
150# Controls which columns are in the output files.
151# Options are "basic" and "all", which returns all columns.
152output_columns = basic
153
154
155[LIGHTCURVE]
156
157# The unique name of the lightcurve model to use. Defined in the ``name_id`` method 
158# of the subclasses of AbstractLightCurve. If not none, the complex physical parameters 
159# file must be specified at the command line.lc_model = none
160lc_model = none
161
162
163[ACTIVITY]
164
165# The unique name of the actvity model to use. Defined in the ``name_id`` method
166#  of the subclasses of AbstractCometaryActivity.  If not none, a complex physical parameters 
167# file must be specified at the command line.
168comet_activity = none

Rubin Circular Approximation

This configuration file is appropriate for running Sorcha using a circular approximation of the Rubin LSSTCam (LSST Camera) field-of-view (FOV).

  1# Sorcha Configuration File
  2# This configuration file will set up Sorcha to simulate what the LSST would discover.
  3# This version simulates objects lost to chip gaps between LSSTCam's detectors by 
  4# simulating a circular detector and approximating the chip gaps, removing all objects 
  5# outside of a 1.75deg radius and 10% of objects within. 
  6# This is slightly faster than using the full footprint.
  7
  8
  9[INPUT]
 10
 11# The simulation used for the ephemeris input. 
 12# ar=ASSIST+REBOUND interal ephemeris generation 
 13# external=providing an external input file from the command line
 14# Options: "ar", "external"
 15ephemerides_type = ar
 16
 17# Format for ephemeris simulation input file if a file is specified at the command line. 
 18# This is also the format to which ephemeris files will be written out, if specified.
 19# Options: csv, whitespace, hdf5
 20eph_format = csv
 21
 22# Sorcha chunk size: how many objects should be processed at once?
 23size_serial_chunk = 20000
 24
 25# Format for the orbit, physical parameters, and complex physical parameters input files.
 26# Options: csv or whitespace
 27aux_format = csv
 28
 29# SQL query for extracting data from the pointing database.
 30pointing_sql_query = SELECT observationId, observationStartMJD as observationStartMJD_TAI, visitTime, visitExposureTime, filter, seeingFwhmGeom as seeingFwhmGeom_arcsec, seeingFwhmEff as seeingFwhmEff_arcsec, fiveSigmaDepth as fieldFiveSigmaDepth_mag , fieldRA as fieldRA_deg, fieldDec as fieldDec_deg, rotSkyPos as fieldRotSkyPos_deg FROM observations order by observationId
 31
 32
 33[SIMULATION]
 34# Configuration for running the ASSIST+REBOUND ephemerides generator.
 35
 36# the field of view of our search field, in degrees
 37ar_ang_fov = 2.06
 38
 39# the buffer zone around the field of view we want to include, in degrees
 40ar_fov_buffer = 0.2
 41
 42# the "picket" is our imprecise discretization of time that allows us to move progress
 43# our simulations forward without getting too granular when we don't have to.
 44# the unit is number of days.
 45ar_picket = 1
 46
 47# the obscode is the MPC observatory code for the provided telescope.
 48ar_obs_code = X05
 49
 50# the order of healpix which we will use for the healpy portions of the code.
 51# the nside is equivalent to 2**ar_healpix_order
 52ar_healpix_order = 6
 53
 54
 55[FILTERS]
 56
 57# Filters of the observations you are interested in, comma-separated.
 58# Your physical parameters file must have H calculated in one of these filters
 59# and colour offset columns defined relative to that filter.
 60observing_filters = r,g,i,z,u,y
 61
 62
 63[SATURATION]
 64
 65# Upper magnitude limit on sources that will overfill the detector pixels/have
 66# counts above the non-linearity regime of the pixels where one can’t do 
 67# photometry. Objects brighter than this limit (in magnitude) will be cut. 
 68# Comment out for no saturation limit.
 69# Two formats are accepted:
 70# Single float: applies same saturation limit to observations in all filters.
 71# Comma-separated list of floats: applies saturation limit per filter, in order as
 72# given in observing_filters keyword.
 73bright_limit = 16.0
 74
 75
 76[PHASECURVES]
 77
 78# The phase function used to calculate apparent magnitude. The physical parameters input
 79# file must contain the columns needed to calculate the phase function.
 80# Options: HG, HG1G2, HG12, linear, none.
 81phase_function = HG
 82
 83
 84[FOV]
 85
 86# Choose between circular or actual camera footprint, including chip gaps.
 87# Options: circle, footprint.
 88camera_model = circle
 89
 90# Fraction of detector surface area which contains CCD -- simulates chip gaps
 91# for OIF output. Comment out if using camera footprint.
 92fill_factor = 0.9
 93
 94# Radius of the circle for a circular footprint (in degrees). Float.
 95# Comment out or do not include if using footprint camera model.
 96circle_radius = 1.75
 97
 98
 99[FADINGFUNCTION]
100
101# Uses the fading function as outlined in
102# Chesley and Vereš (2017) to remove observations.
103
104# Width parameter for fading function. Should be greater than zero and less than 0.5.
105# Suggested value is 0.1 after Chesley and Vereš (2017).
106fading_function_width = 0.1
107
108# Peak efficiency for the fading function, called the 'fill factor' in Chesley and Veres (2017).
109# Suggested value is 1. Do not change this unless you are sure of what you are doing.
110fading_function_peak_efficiency = 1.
111
112
113[LINKINGFILTER]
114
115# SSP detection efficiency. Which fraction of the objects will
116# the automated Rubin Solar System Processing (SSP) pipeline successfully link? Float.
117SSP_detection_efficiency = 0.95
118
119
120# Length of tracklets. How many observations of an object during one night are
121# required to produce a valid tracklet?
122SSP_number_observations = 2
123
124# Minimum separation (in arcsec) between two observations of an object required 
125# for the linking software to distinguish them as separate and therefore as a valid tracklet.
126SSP_separation_threshold = 0.5
127
128# Maximum time separation (in days) between subsequent observations in a tracklet. 
129# Default is 0.0625 days (90mins).
130SSP_maximum_time = 0.0625
131
132# Number of tracklets for detection. How many tracklets are required to classify
133# an object as detected? 
134SSP_number_tracklets = 3
135
136# The number of tracklets defined above must occur in <= this number of days to 
137# constitute a complete track/detection.
138SSP_track_window = 15
139
140# The time in UTC at which it is noon at the observatory location (in standard time).
141# For the LSST, 12pm Chile Standard Time is 4pm UTC.
142SSP_night_start_utc = 16.0
143
144
145[OUTPUT]
146
147# Output format of the output file[s]
148# Options: csv, sqlite3, hdf5
149output_format = sqlite3
150
151# Controls which columns are in the output files.
152# Options are "basic" and "all", which returns all columns.
153output_columns = basic
154
155
156[LIGHTCURVE]
157
158# The unique name of the lightcurve model to use. Defined in the ``name_id`` method 
159# of the subclasses of AbstractLightCurve. If not none, the complex physical parameters 
160# file must be specified at the command line.
161lc_model = none
162
163
164[ACTIVITY]
165
166# The unique name of the actvity model to use. Defined in the ``name_id`` method
167#  of the subclasses of AbstractCometaryActivity.  If not none, a complex physical parameters 
168# file must be specified at the command line.
169comet_activity = none

Rubin Known Object Prediction

This configuration file is appropriate for running Sorcha using the full camera footprint but with randomization, applying the fading function, accounting for vignetting, applying the linking filter, using the saturation limit filter, and accounting for trailing losses all turned off. This will output all potential detections of the input population which lie on the LSSTCam (LSST Camera) CCDs (Charged Couple Devices) with unadulterated apparent magnitudes. This could thus be used to predict when and where known objects will land in LSST observations.

Warning

As this configuration file turns off most of Sorcha's features, we strongly recommend you do not use this example configuration file unless you are certain that this is what you need out of Sorcha.

  1# Sorcha Configuration File
  2# This configuration file is appropriate for running Sorcha using the full camera footprint 
  3# but with randomization, fading function, vignetting, SSP linking, saturation limit and 
  4# trailing losses off. This will output all detections which lie on the CCD with unadulterated 
  5# apparent magnitudes. This could thus be used to predict when and where known objects will appear 
  6# in Rubin observations. 
  7# WARNING: This configuration file turns off most of Sorcha's features,
  8# We do not recommend you use this unless you know what you are doing.
  9
 10
 11[INPUT]
 12
 13# The simulation used for the ephemeris input.
 14# ar=ASSIST+REBOUND interal ephemeris generation
 15# external=providing an external input file from the command line
 16# Options: "ar", "external"
 17ephemerides_type = ar
 18
 19# Format for ephemeris simulation input file if a file is specified at the command line. 
 20# This is also the format to which ephemeris files will be written out, if specified.
 21# Options: csv, whitespace, hdf5
 22eph_format = csv
 23
 24# Sorcha chunk size: how many objects should be processed at once?
 25size_serial_chunk = 20000
 26
 27# Format for the orbit, physical parameters, and complex physical parameters input files.
 28# Options: csv or whitespace
 29aux_format = csv
 30
 31# SQL query for extracting data from the pointing database.
 32pointing_sql_query = SELECT observationId, observationStartMJD as observationStartMJD_TAI, visitTime, visitExposureTime, filter, seeingFwhmGeom as seeingFwhmGeom_arcsec, seeingFwhmEff as seeingFwhmEff_arcsec, fiveSigmaDepth as fieldFiveSigmaDepth_mag , fieldRA as fieldRA_deg, fieldDec as fieldDec_deg, rotSkyPos as fieldRotSkyPos_deg FROM observations order by observationId
 33
 34
 35[SIMULATION]
 36# Configs for running the ASSIST+REBOUND ephemerides generator.
 37
 38# the field of view of our search field, in degrees
 39ar_ang_fov = 2.06
 40
 41# the buffer zone around the field of view we want to include, in degrees
 42ar_fov_buffer = 0.2
 43
 44# the "picket" is our imprecise discretization of time that allows us to move progress
 45# our simulations forward without getting too granular when we don't have to.
 46# the unit is number of days.
 47ar_picket = 1
 48
 49# the obscode is the MPC observatory code for the provided telescope.
 50ar_obs_code = X05
 51
 52# the order of healpix which we will use for the healpy portions of the code.
 53# the nside is equivalent to 2**ar_healpix_order
 54ar_healpix_order = 6
 55
 56
 57[FILTERS]
 58
 59# Filters of the observations you are interested in, comma-separated.
 60# Your physical parameters file must have H calculated in one of these filters
 61# and colour offset columns defined relative to that filter.
 62observing_filters = r,g,i,z,u,y
 63
 64
 65[PHASECURVES]
 66
 67# The phase function used to calculate apparent magnitude. The physical parameters input
 68# file must contain the columns needed to calculate the phase function.
 69# Options: HG, HG1G2, HG12, linear, none.
 70phase_function = HG
 71
 72
 73[FOV]
 74
 75# Choose between circular or actual camera footprint, including chip gaps.
 76# Options: circle, footprint.
 77camera_model = footprint
 78
 79# Path to camera footprint file. Uncomment to provide a path to the desired camera 
 80# detector configuration file if not using the default built-in LSSTCam detector 
 81# configuration for the actual camera footprint.
 82# footprint_path= ./data/detectors_corners.csv
 83
 84# The distance from the edge of a detector (in arcseconds on the focal plane)
 85# at which we will not correctly extract an object. By default this is 10px or 2 arcseconds.
 86# Comment out or do not include if not using footprint camera model.
 87footprint_edge_threshold = 2.
 88
 89
 90[OUTPUT]
 91
 92# Output format of the output file[s]
 93# Options: csv, sqlite3, hdf5
 94output_format = sqlite3
 95
 96# Controls which columns are in the output files.
 97# Options are "basic" and "all", which returns all columns.
 98output_columns = basic
 99
100
101[LIGHTCURVE]
102
103# The unique name of the lightcurve model to use. Defined in the ``name_id`` method 
104# of the subclasses of AbstractLightCurve. If not none, the complex physical parameters 
105# file must be specified at the command line.lc_model = none
106lc_model = none
107
108
109[ACTIVITY]
110
111# The unique name of the actvity model to use. Defined in the ``name_id`` method
112#  of the subclasses of AbstractCometaryActivity.  If not none, a complex physical parameters 
113# file must be specified at the command line.
114comet_activity = none
115
116
117[EXPERT]
118# Turning off all randomization, vignetting and trailing losses.
119randomization_on = False
120vignetting_on = False
121trailing_losses_on = False