Inputs

Sorcha requires two input files describing the synthetic solar system objects to simulate -- one for the orbital parameters and one for the physical parameters -- as well as a survey pointing database. Optionally, the user can provide a pre-generated ephemeris file with the positions of each object and a complex physical parameter file for rotational light curves and cometary activity. Each of these files are described within this section and example files are shown.

Tip

Each synthetic planetesimal has its own unique object identifier set by the user and must have entries in the orbits and physical parameters files, as well as the cometary activity file, if used.

Warning

Sorcha does not check whether or not a planetesimal ID has been repeated in another row of the input files. It is up to the user to ensure their input files include only unique IDs.

Orbit File

This is a file which contains the orbital information of a set of synthetic objects.

Tip

Sorcha is designed to handle heliocentric Cometary (COM), Keplerian (KEP), and Cartesian (CART) orbits, as well as their barycentric equivalents: Barycentric Cometary (BCOM), Keplerian (BKEP) and Cartesian (BCART)
The orbit file must have a consistent format (i.e. Cometary or Keplerian or Cartesian) throughout
The first column must be ObjID, but the ordering of the remaining columns does not matter as long as the required columns exist and have entries
The first row in the orbit file must be a header listing the column names
The correct capitalization of column names is required
The orbit file can be either whitespace-separated or comma-separated values (CSV)
Each simulated particle must have a unique string identifier
The orbit file must only have 9 columns (object identifier, format column, 6 orbital parameters, and a time epoch)

Warning

The orbit epoch is expected to be given in TDB (Barycentric Dynamical Time)

Tip

If using Sorcha's internal ephemeris generator (which is the default mode), we recommend calculating/creating your input orbits with epochs close in time to the start of the first survey observation. This will minimize the n-body integrations required to set up the ephemeris generation.

Tip

Be careful about the way your input elements are defined! Using heliocentric elements as barycentric (or vice-versa) will lead to wrong outputs. Similarly, if using Cartesian elements, be careful about the orientation of the coordinate system! Sorcha assumes that Cartesian elements are Ecliptic-oriented.

Attention

Use the --ob (--orbits) flag with the sorcha run command on the terminal to specify the orbit file that Sorcha should use.

Note

For readability we show examples of whitespace-separated files below. We show only the heliocentric versions of these inputs, as the barycentric column requirements are identical, changing only the FORMAT designation

Cometary Orbit Format

Example Orbit File in Cometary Format

ObjID FORMAT q e inc node argPeri t_p_MJD_TDB epochMJD_TDB
S1000000a COM 3.01822 0.05208 22.56035 211.00286 335.42134 51575.94061 54800.00000
S1000001a COM 2.10974 0.07518 4.91571 209.40298 322.66447 54205.77161 54800.00000
S1000002a COM 2.80523 0.07777 1.24945 112.52284 139.86858 54468.71747 54800.00000
S1000003a COM 2.10917 0.13219 1.46615 266.54621 232.24412 54212.16304 54800.00000
S1000004a COM 2.17676 0.19949 12.92422 162.14580 192.22312 51895.46586 54800.00000

Cometary Orbit Format Required Columns

Keyword	Description
ObjID	Object identifier for each synthetic planetesimal simulated (string)
FORMAT	Orbit format string (COM for heliocentric or BCOM for barycentric)
q	Perihelion distance (au)
e	Eccentricity
inc	Inclination (degrees)
node	Longitude of the ascending node (degrees)
argPeri	Argument of perihelion (degrees)
t_p_MJD_TDB	Time of periapsis specified as Mean Julian Date (MJD) in TDB (Barycentric Dynamical Time)
epochMJD_TDB	Epoch specified as Mean Julian Date (MJD) in TDB (Barycentric Dynamical Time)

Keplerian Orbit Format

Example Orbit File in Keplerian Format

ObjID FORMAT a e inc node argPeri ma epochMJD_TDB
t1 KEP 47.9877 0.0585 11.3584 148.4661 140.4756 308.3244 53157.00
t2 KEP 47.7468 0.0552 7.1829 171.9226 55.3728 158.9403 53157.00
t3 KEP 47.9300 0.3805 3.4292 72.9463 7.0754 84.7860 53157.00
t4 KEP 47.6833 0.1973 14.0872 344.2142 167.0238 220.2356 53157.00
t5 KEP 47.9356 0.2912 4.3621 306.0908 217.8116 18.7043 53157.00
t6 KEP 47.9786 0.2730 2.2425 147.9340 166.6578 327.8996 53157.00

Keplerian Orbit Format Required Columns

Keyword	Description
ObjID	Object identifier for each synthetic planetesimal simulated (string)
FORMAT	Orbit format string (KEP for heliocentric or BKEP for barycentric)
a	Semimajor axis (au)
e	Eccentricity
inc	Inclination (degree)
node	Longitude of the ascending node (degrees)
argPeri	Argument of perihelion (degrees)
ma	Mean Anomaly (degrees)
epochMJD_TDB	Epoch specified as Mean Julian Date (MJD) in TDB (Barycentric Dynamical Time)

Cartesian Orbit Format

Example Orbit File in Cartesian format

ObjID FORMAT x y z xdot ydot zdot epochMJD_TDB
STC001TFa CART  36.701800449281706  -8.770729364470023 -0.6261488665458296  0.0007155581026554  0.0026593939322716  7.344098975957749e-06   54466.0  36.54594860110992   0.04317
STC001TG  CART -21.58733368378989   43.39783041151296   1.56699314137673   -0.0022005866864537 -0.0008717014384454 -4.735561770155727e-05   54466.0  44.842379308393234  0.11655
STC001THa CART -37.814635799443394 -15.408895634838116 -5.805017616166551   0.0013198883808779 -0.0023982304849102  0.0001541826365505      54466.0  43.31324469003626,  0.13135
STC001TI  CART  41.24248251296191   -5.652356017018537  2.248705059605729   0.0002800360644183  0.0027490608404251 -2.751096337281987e-05   54466.0  45.1101872463009    0.08356
STC001TJa CART  17.40239702643279   34.77710957157372   0.0084291177638708 -0.0026387164932318  0.0010268353976719 -0.0001037528579236      54466.0  41.15242897966045   0.10765
STC001TKa CART -15.182212553033564  31.98846596524726   0.179545295303334  -0.0026490933334786 -0.0013306706378324  0.0001110412982125      54466.0  37.39443807826161   0.05752
STC001TLa CART  33.603411395500856  18.87464811210368  -0.6359802780512743 -0.0012855812467388  0.0025081701870071 -2.1885697562103903e-05  54466.0  39.93776165518987   0.05171
STC001TMa CART -35.205151144286006 -21.59643017634877  -6.399036148167812   0.0012861312376887 -0.0023168284708868 -0.0001863582741122      54466.0  41.6549967769547    0.05369
STC001TNa CART -33.79882997522472  -16.266135214977684 -5.221001391031022   0.0013485808895118 -0.0024033901851641 -0.0001051222283375      54466.0  36.890329257623286  0.06274

Cartesian Orbit Format Required Columns

Keyword	Description
ObjID	Object identifier for each synthetic planetesimal simulated (string)
FORMAT	Orbit format string (CART for heliocentric or BCART for barycentric)
x	heliocentric or barycentric position on the ecliptic x axis (au)
y	heliocentric or barycentric position on the ecliptic y axis (au)
z	heliocentric or barycentric position on the ecliptic z axis (au)
xdot	heliocentric or barycentric velocity on the ecliptic x axis (au/day)
ydot	heliocentric or barycentric velocity on the ecliptic y axis (au/day)
zdot	heliocentric or barycentric velocity on the ecliptic z axis (au/day)
epochMJD_TDB	Epoch specified as Mean Julian Date (MJD) in TDB (Barycentric Dynamical Time)

Note

All positions and velocities are in respect to J2000

Orbit File Configuration Parameters

Sorcha is initialized for the format of the input orbit file through the configuration file INPUT sections:

[INPUT]

# Sorcha chunk size: how many objects should be processed at once?

size_serial_chunk = 20000

# Format for the orbit, physical parameters, and complex physical parameters input files.
# Options: csv or whitespace

aux_format = csv

Physical Parameters File

The input file for the physical parameters includes information about the objects' optical colors, phase curve parameters, and absolute magnitude. The contents of this file are the bare minimum needed to simulate survey detections. For more advanced handling of the apparent magnitude of the synthetic objects, including light curve effects and cometary activity, you would also specify values in the complex physical parameters file.

Tip

The first column must be ObjID, but the ordering of the remaining columns does not matter as long as the required columns exist and have entries
The first row in the physical parameters file must be a header listing the column names
The correct capitalization of column names is required
The physical parameters file can be either whitespace-separated or comma-separated values (CSV)
Each simulated object must have a unique string identifier
You must use the same phase curve prescription for all simulated objects. If you want to use different phase curve prescriptions for different synthetic populations, you will need to run them in separate input files to Sorcha
If the phase curve function is set to NONE in the configuration value then no phase curve parameter values are required in the physical parameters files.
In the configuration file you can decide which observing filters (e.g r-band,*g*-band,etc) you want have Sorcha run on and specify which observing filter is the main filter that the absolute magnitude is defined for. You only need to provide colors for those filters specified in the configuration file.

We have implemented several phase curve parameterizations that can be specified in the configuration file and then inputted through the physical parameters. You can either specify one set of phase curve parameters for all observing filters or specify values for each filter examined by Sorcha. We are using the sbpy phase function utilities. The supported options are: HG, HG1G2, HG12, linear (specified by S in the header of the physical parameters file), and none (if no columns for phase curve are included in the physical parameters file then the synthetic object is considered to have a flat phase curve). Note that the HG12 model is the Penttilä et al. (2016) modified model, and not the original (IAU adopted) Muinonen et al. (2010) model.

Example Physical Parameters File (single linear slope phase curve parameter for all observing filters)

Note

For readability we show examples of whitespace-separated files below.

ObjID H u-r g-r i-r z-r y-r GS
St500000a 5.63 2.55 0.92 -0.38 -0.59 -0.70 0.15
St500001a 6.25 2.55 0.92 -0.38 -0.59 -0.70 0.15
St500002a 6.36 1.72 0.48 -0.11 -0.12 -0.12 0.15
St500003a 6.67 1.72 0.48 -0.11 -0.12 -0.12 0.15
St500004a 10.2 1.90 0.58 -0.21 -0.30 -0.39 0.15

Example Physical Parameters File (a HG value is specified for each observing filter)

Note

For readability we show examples of whitespace-separated files below.

ObjID H u-r g-r i-r z-r y-r Gr Gu Gg Gi Gz Gy
St500000a 5.63 2.55 0.92 -0.38 -0.59 -0.70 0.15 0.17 0.14 0.19 0.18 0.20
St500001a 6.25 2.55 0.92 -0.38 -0.59 -0.70 0.15 0.17 0.14 0.17 0.19 0.17
St500002a 6.36 1.72 0.48 -0.11 -0.12 -0.12 0.15 0.17 0.13 0.17 0.16 0.18
St500003a 6.67 1.72 0.48 -0.11 -0.12 -0.12 0.15 0.16 0.12 0.20 0.15 0.19
St500004a 10.2 1.90 0.58 -0.21 -0.30 -0.39 0.15 0.15 0.16 0.15 0.14 0.16

Rubin Observatory will survey the sky in six broadband (optical filters), u, g, r, i, z, and y . In the physical parameters file, you will specify the object's absolute magnitude in the main filter as specified in the configuration file (usually this is g or r band) and then provide the synthetic planetesimal's color in other filters relative to the main filter.

Required Physical Parameters File Columns and Format

Keyword	Description
ObjID	Object identifier for each synthetic planetesimal simulated (string)
H	Absolute magnitude in the main filter
u-r,g-r,etc	Photometric colors in the relevant survey filters
G, G1&G2, G12, S	Phase curve parameter(s) for all filters (either G12, G1 & G2, or β) (optional)

Note

The Phase curve parameters(s) column will not be present if the phase curve function/calculation is set to None in the configuration file.

Note

In the configuration file you can decide which filters you want to have Sorcha run on and specify which filter is the main filter that the absolute magnitude is defined for. You only need to provide colors for those filters specified in the configuration file.

Attention

Use the -p (--physical-parameters) flag with the sorcha run command on the terminal to specify the pointing database that Sorcha should use.

Physical Parameters File Configuration Parameters

Sorcha is initialized for the format of the input physical parameters file through the configuration file INPUT, FILTERS, and PHASECURVES sections:

[INPUT]

# Sorcha chunk size: how many objects should be processed at once?

size_serial_chunk = 20000

# Format for the orbit, physical parameters, and complex physical parameters input files.
# Options: csv or whitespace

aux_format = csv

[FILTERS]

# Filters of the observations you are interested in, comma-separated.
# Your physical parameters file must have H calculated in one of these filters
# and colour offset columns defined relative to that filter.

observing_filters = r,g,i,z,u,y

[PHASECURVES]

# The phase function used to calculate apparent magnitude. The physical parameters input
# file must contain the columns needed to calculate the phase function.
# Options: HG, HG1G2, HG12, linear, none.

phase_function = linear

Note

In the configuration file you can decide which filters you want to have Sorcha run on and specify which filter is the main filter that the absolute magnitude is defined for. You only need to provide colors for those filters specified in the configuration file.

Complex Physical Parameters File (Optional)

The complex physical parameters file is only needed if you're going to include your own rotational light curve class or cometary activity class to augment the calculated apparent magnitudes. Sorcha is set up such that any values required for this such as (light curve amplitude and period per simulated object) are included in a file, separate from the physical parameters file, that we refer to as the complex physical parameters file. What columns are required in the complex physical parameters file depends on the classes you are using.

Tip

The first column must be ObjID, but the ordering of the remaining columns does not matter as long as the required columns exist and have entries
The first row in the complex physical parameters file must list the column names
The correct capitalization of column names is required
The complex physical parameters file can be either whitespace-separated or comma-separated values (CSV)
Each simulated object must have a unique string identifier

Complex Parameters File Configuration Parameters

Sorcha is initialized for the format of the complex physical parameters file through the configuration file INPUT sections:

[INPUT]

# Sorcha chunk size: how many objects should be processed at once?

size_serial_chunk = 20000

# Format for the orbit, physical parameters, and complex physical parameters input files.
# Options: csv or whitespace

aux_format = csv

Survey Pointing Database

Note

Currently Sorcha is set up to run with the LSST cadence simulations pointing databases.

This database contains information about the LSST pointing history and observing conditions. We use observation mid-point time, right ascension, declination, rotation angle of the camera, 5-sigma limiting magnitude, filter, and seeing information in Sorcha to determine if a synthetic Solar System object is observable.

What we call the LSST pointing database (currently simulated since Rubin Observatory hasn’t started operations) is generated through the Rubin Observatory scheduler (since 2021 referred to as rubin_sim and previously known as OpSim). This software is currently under active development and is being used to run many simulated iterations of LSST scenarios, showing what the cadence would look like with differing survey strategies. A description of an early version of this Python software can be found in Delgado et al.(2014). The output of rubin_sim is a SQLlite database containing the pointing history and associated metadata of the simulated observation history of LSST.

Tip

The contents of the observations table in the SQLite LSST pointing database can be found here

Warning

The pointing databases times are expected to be TAI (Temps Atomique International; French for International Atomic Time),

Attention

Use the --pd flag on the command line to specify the pointing database that Sorcha should use.

The latest version of rubin_sim cadence simulations can be found at https://survey-strategy.lsst.io/baseline/index.html or https://s3df.slac.stanford.edu/data/rubin/sim-data/. An example rubin_sim simulation visualized on sky is shown in the plot below of the number of on-sky visits over the 10-year simulated baseline v3.2 survey (image credit: Lynne Jones):

Attention

There may be changes to how this information is read in when the Rubin Observatory operations begin in mid 2026.

Setting Up the Correct LSST Pointing Database Query

Sorcha's ppsqldbquery configuration file parameter contains the SQL query for obtaining this information from the pointing database.

From rubin_sim v5.0 cadence simulations onward and the Rubin Science Validation Survey Pointing Database <https://survey-strategy.lsst.io/progress/sv_status/sv_20250930.html> use the query:

SELECT observationId, observationStartMJD as observationStartMJD_TAI, visitTime, visitExposureTime, band as 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

From rubin_sim v2.0 up to v4.0 cadence simulations use the 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

For past rubin_sim LSST cadence simulations pre-v2.0 use the query:

SELECT observationId, observationStartMJD as observationStartMJD_TAI, visitTime, visitExposureTime, filter, seeingFwhmGeom as seeingFwhmGeom_arcsec, seeingFwhmEff as seeingFwhmEff_arcsec, fiveSigmaDepth  fieldFiveSigmaDepth_mag, fieldRA as fieldRA_deg, fieldDec as fieldDec_deg, rotSkyPos as fieldRotSkyPos_deg  FROM SummaryAllProps order by observationId

Survey Pointing Database Configuration Parameters

The survey pointing database query is set in the configuration file INPUT section:

[INPUT]

# SQL query for extracting data from the pointing database.

pointing_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

Camera Footprint File (Optional)

Attention

The camera footprint file is only required if you are using the camera footprint

If you are going to simulate the full camera architecture including CCD locations and chip gaps in the camera focal plane, you will need to provide a file that describes the layout of detectors on the camera focal plane.

The camera footprint file is a comma-separated values (CSV) file with three columns describing the detector shapes, with the header “detector,x,y”. The first column indicates which detector a point belongs to, and should be an integer. Second and third columns specify where on the focal plane the corners are. Values are unitless, equal to tan( ra ), tan( dec ), where ra and dec are the vertical and horizontal angles of the points from the center of the sphere tangent to origin in the focal plane. Ordering does not matter, as the constructor sorts the points automatically.

Tip

Sorcha comes with a representation of the LSSTCam architecture already installed. Further details of how to use this built-in default file can be found in the description of the Full Camera Footprint Filter.

Example Camera Footprint File

detector,x,y
0,-0.014454999586454067,-0.030674401533576857
0,-0.014457817428781026,-0.0267326018208852
0,-0.018331914977872454,-0.0267292699961917
0,-0.018328290076900438,-0.030670610782016904
1,-0.01036615542093107,-0.03067481791936949
1,-0.010368340883416585,-0.026732650098983575
1,-0.014243242319031606,-0.02673031575218622
1,-0.014240248598515198,-0.03067213887948379
2,-0.006276838632680806,-0.030680624958627452
2,-0.006277282529055899,-0.026738212912728553
2,-0.010152758821055591,-0.02673578862768631
2,-0.010151505598878474,-0.03067797062417792
3,-0.014459830990935755,-0.02658368647444251
3,-0.014462296539872094,-0.022640368109892405
3,-0.018337114680618473,-0.022637587243695124
3,-0.018333956374213457,-0.02658044525004437
4,-0.010368143775707085,-0.026586724804545197
4,-0.010369363721863475,-0.022643038620489414
4,-0.014244987315414771,-0.02264041587675749

Required Camera Footprints File Columns and Format

Keyword	Description
detector	Detector identifier (integer)
x	x position of the detector corner on the focal plane (float)
y	y position of the detector corner on the focal plane (float)

Note

The x and y values are unitless and are respectively equal to tan(ra) and tan(dec) , where ra and dec are the vertical and horizontal angles of the points from the center of the sphere tangent to the origin in the focal plane. For each detector, all four corners must be specified in the camera footprint file.

Camera Footprint File Configuration Parameters

You can set whether you're using a camera footprint file and the location of the file in the configuration file FOV section:

[FOV]

# Choose between circular or actual camera footprint, including chip gaps.
# Options: circle, footprint.

camera_model = footprint


# Path to camera footprint file. Uncomment to provide a path to the desired camera
# detector configuration file if not using the default built-in LSSTCam detector
# configuration for the actual camera footprint.

footprint_path= ./data/detectors_corners.csv

Note

If camera_model is set to footprint and footprint_path variable is not set, Sorcha will automatically read in its installed LSSTCam detector footprint file.

Tip

If using the cicle camera model, the footprint_path variable should not be present or commented out of the configuration file .

Ephemeris File (Optional)

Note

Sorcha has an Ephemeris Generator that we recommend using by default, but as an alternative Sorcha can read in an external file containing calculated ephemeris values for each simulated object within a reasonable search radius of a given survey field pointing and observation times as specified in the survey pointing database. This could be the output from a previous Sorcha run or provided from your own separate ephemeris generation method,

Tip

The first column must be ObjID, but the ordering of the remaining columns does not matter as long as the required columns exist and have entries
The first row in the physical parameters file must list the column names
The correct capitalization of column names is required
The ephemeris file can be either whitespace-separated or comma-separated values (CSV)
Each simulated object must have a unique string identifier

Attention

Use the --er (--ephem-read) flag with the sorcha run command on then terminal to specify the external ephemeris file that Sorcha should use.

Warning

We have validated Sorcha with its internal ephemeris generator. If the user chooses to use a different ephemeris engine's calculations as input for Sorcha, the user has the responsibility to check the accuracy of this input.

Example Ephemeris File

Note

For readability we show an example of a whitespace-separated file below.

ObjID,FieldID,fieldMJD_TAI,fieldJD_TDB,Range_LTC_km,RangeRate_LTC_km_s,RA_deg,RARateCosDec_deg_day,Dec_deg,DecRate_deg_day,Obj_Sun_x_LTC_km,Obj_Sun_y_LTC_km,Obj_Sun_z_LTC_km,Obj_Sun_vx_LTC_km_s,Obj_Sun_vy_LTC_km_s,Obj_Sun_vz_LTC_km_s,Obs_Sun_x_km,Obs_Sun_y_km,Obs_Sun_z_km,Obs_Sun_vx_km_s,Obs_Sun_vy_km_s,Obs_Sun_vz_km_s,phase_deg
356450,5829,60225.290312576966,2460225.790684981,5709680724.41986,2.9494487919188273,11.320285331417496,-0.0202269680887021,-2.2954835668700517,-0.0086571153987747,5738902219.480821,1154027853.2765138,-213890791.67465413,-1.1237773887302347,4.256320269710808,1.338224247429126,144794625.40484905,34155056.75767293,14799217.574331297,-8.200800543902561,26.63196130851409,11.43334668276991,0.208857985027727
356450,5879,60225.31402420935,2460225.8143969807,5709686825.650296,3.005675102037283,11.319805737949514,-0.0201911594240885,-2.2956888093378214,-0.0086541915770451,5738899917.193501,1154036573.1830225,-213888050.05912232,-1.123785630643529,4.256318396445951,1.3382244158453602,144777774.99738884,34209566.28272891,14822640.142409474,-8.247704257179537,26.580497557273908,11.432249026241127,0.2092184416163637
356450,8279,60228.246178492176,2460228.746550981,5710564645.602968,4.402971645819728,11.261362776567957,-0.0201913422994515,-2.3208128916169457,-0.0084624706793145,5738615093.671786,1155114819.0324504,-213549028.09331504,-1.124804483718967,4.25608649472876,1.3382451467932135,142592297.0115333,40842929.6802401,17698863.7214609,-9.600335952786711,26.31769948707328,11.270539338139608,0.2605217667068308
356450,8283,60228.24796230145,2460228.748334981,5710565324.651465,4.407953783636989,11.261326727231816,-0.0201895534290408,-2.32082798843048,-0.0084622075388368,5738614920.299598,1155115475.0458145,-213548821.82242855,-1.1248051034291482,4.256086353471984,1.3382451593468847,142590816.89337063,40846985.99754304,17700600.92776723,-9.604811884506798,26.314709457556543,11.270439994269912,0.260556514528297
356450,8329,60228.26853255524,2460228.7689049807,5710573208.673566,4.463641549792378,11.26091131954451,-0.0201661328520933,-2.3210020252236085,-0.0084592296480674,5738612921.26505,1155123039.053614,-213546443.4638528,-1.1248122488372363,4.2560847247289,1.3382453040886182,142573702.33103642,40893721.37345689,17720630.272800464,-9.654066564548495,26.277416149442864,11.269288400898144,0.2609572713746479
356450,8333,60228.270314360816,2460228.770686981,5710573896.276966,4.468299651654041,11.260875356002185,-0.0201638688452555,-2.3210170993461468,-0.0084589770034579,5738612748.086066,1155123694.3311272,-213546237.42423072,-1.1248128678497935,4.256084583627966,1.3382453166272692,142572215.6322337,40897766.90450707,17722365.33887649,-9.658117538456535,26.27395197806917,11.269188077872911,0.2609919975449258
356450,9212,60229.28456713632,2460229.784939981,5710968855.09468,5.026365908021004,11.240715390786704,-0.0200985496164067,-2.3295666061382683,-0.0083834267123284,5738514165.129657,1155496652.123135,-213428966.4779463,-1.1251651529026658,4.256004240632483,1.338252440848253,141728777.44150686,43169617.04211715,18707103.63980833,-10.185247961988,26.095441693092535,11.2060717162176,0.2810902774788717
356450,9213,60229.28501510557,2460229.7853879808,5710969049.672443,5.027457791227193,11.24070637934352,-0.0200978874801124,-2.329570361896788,-0.0083833641569524,5738514121.578418,1155496816.8582718,-213428914.6788428,-1.1251653084925506,4.256004205129916,1.3382524439895254,141728383.18153384,43170627.104314215,18707537.394639105,-10.186168213171548,26.094481513377133,11.20604462226726,0.2810993975224624
356450,9262,60229.30845866669,2460229.8088309807,5710979288.46942,5.081517905998171,11.240235263755997,-0.0200604272434325,-2.329766855512199,-0.0083801909025578,5738511842.6139345,1155505437.142398,-213426204.12706903,-1.1251734502053166,4.256002347327566,1.3382526083596191,141707705.0485357,43223428.154788755,18730233.517916635,-10.230672353792196,26.041655952602504,11.204617544730104,0.2815766174584465
356450,9263,60229.30890693124,2460229.809278981,5710979485.179835,5.08248913326226,11.240226269418642,-0.0200596603119751,-2.3297706098258524,-0.0083801322791434,5738511799.062336,1155505601.8776026,-213426152.32791463,-1.1251736057946045,4.256002311824266,1.338252611500631,141707309.03264847,43224436.13429753,18730667.21690369,-10.231450639506717,26.0406007494812,11.204590089563284,0.281585736713016
356450,9876,60230.20314531156,2460230.703517981,5711364609.535016,5.323329254254495,11.222526198147053,-0.0201290426390518,-2.337243724004218,-0.0083190427489149,5738424855.057949,1155834422.0006428,-213322757.39089885,-1.125484145442695,4.255931418302017,1.3382588712361088,140929324.07653886,45213311.50555949,19594035.93857417,-10.478482412939217,26.076249903629595,11.145257408961456,0.2999530373640972
356450,9877,60230.203594850136,2460230.703966981,5711364816.072356,5.3246718040085375,11.222517152735849,-0.0201288088624788,-2.3372474592375747,-0.0083189704847176,5738424811.397141,1155834587.100593,-213322705.47594604,-1.125484301351659,4.255931382692821,1.3382588743740893,140928917.55405006,45214323.08685056,19594468.302620243,-10.479745269131168,26.075725987712833,11.145229521325744,0.2999624798272167
356450,9926,60230.2269069164,2460230.727278981,5711375610.2610235,5.3932243833505265,11.222047689971282,-0.020112969785029,-2.3374413476126894,-0.0083152543524016,5738422544.527387,1155843159.0591066,-213320010.06054977,-1.125492396098844,4.255929533851034,1.338259037290468,140907744.9688948,45266813.590758234,19616915.080807637,-10.543350766003348,26.04456074915406,11.143776236891537,0.3004527966281898
356450,9927,60230.22735589767,2460230.727727981,5711375819.508911,5.394518395686001,11.222038651813312,-0.0201125944961966,-2.337445081145399,-0.0083151836068398,5738422500.866269,1155843324.1589444,-213319958.14560288,-1.125492552007045,4.255929498241128,1.3382590404281771,140907335.93146807,45267823.93978993,19617347.387389548,-10.544534223146774,26.043886169722796,11.14374813380168,0.3004622413081458
356450,12583,60234.11622691274,2460234.6165989814,5713475093.421965,7.136328360782388,11.145541140456457,-0.0198557549934996,-2.3691773033561514,-0.0079951764978681,5738044118.144555,1157273228.305127,-212870309.96635804,-1.1268423798125815,4.255620554639672,1.338286017232046,137120690.14070824,53791805.35848329,23314249.22923764,-12.17813426556875,25.43535453569694,10.853038860824384,0.3848399434856629
356450,12584,60234.11664241298,2460234.6170149813,5713475349.941043,7.137557150294676,11.145532873355346,-0.0198559576557215,-2.3691806293338407,-0.0079951044123958,5738044077.6441,1157273381.2586775,-212870261.8662979,-1.1268425241497957,4.25562052153472,1.3382860200957738,137120252.40697125,53792719.56587117,23314639.312848084,-12.179384162394513,25.43534870210667,10.853007333295238,0.3848493140355404
356450,12588,60234.11829303164,2460234.6186659816,5713476368.43734,7.142440888017259,11.145500062467926,-0.0198567391343093,-2.3691938290167553,-0.0079948180703628,5738043916.907811,1157273988.293285,-212870070.96911553,-1.1268430969881955,4.2556203901492635,1.3382860314611498,137118514.70752877,53796347.82423515,23316187.44656607,-12.184346449297438,25.435298344842593,10.852882207365347,0.3848865043269647
356450,12633,60234.14017770294,2460234.6405499815,5713489935.005032,7.208026327048856,11.145065058638384,-0.0198636113603137,-2.3693687458361334,-0.0079909912784873,5738041786.3416195,1157282034.5312943,-212867540.62804925,-1.1268506899394093,4.2556186486175624,1.3382861821019252,137095414.56522062,53844437.003276326,23336706.26476899,-12.250180028583614,25.43051913116931,10.851223038284248,0.3853795796673233
356450,12634,60234.14062745727,2460234.640999981,5713490215.279682,7.2093876042103,11.14505611235432,-0.0198636840019759,-2.369372341762015,-0.0079909121111771,5738041742.530737,1157282199.9856703,-212867488.59676296,-1.1268508460725526,4.2556186128061695,1.3382861851994037,137094938.2522754,53845425.73774761,23337128.159377597,-12.251530862938882,25.430340662505795,10.851188899387196,0.3853897206872156

Required Ephemeris File Columns and Format

Keyword	Description
ObjID	Object identifier for each synthetic planetesimal simulated (string)
FieldID	Observation pointing field identificator
fieldMJD_TAI	Observation Mean Julian Date (MJD) in TAI (International Atomic Time)
fieldJD_TDB	Observation Julian Date in TDB (Barycentric Dynamical Time)
Range_LTC_km	Topocentric distance to the simulated object
RangeRate_LTC_km_s	Radial component of the object’s topocentric velocity (km/s)
RA_deg	Object right ascension (degrees)
RARateCosDec_deg_day	Object right ascension rate of motion multiplied by cos(Dec) (deg/day)
Dec_deg	Object declination (degrees)
DecRate_deg_day	Object declination rate of motion (deg/day)
Obj_Sun_x_LTC_km	Light-time-corrected Cartesian X-component of the object’s heliocentric distance (km)
Obj_Sun_y_LT_km	Light-time-corrected Cartesian Y-component of the object’s heliocentric distance (km)
Obj_Sun_z_LTC_km	Light-time-corrected Cartesian X-component of the object’s heliocentric distance (km)
Obj_Sun_vx_LTC_km_s	Light-time-corrected Cartesian X-component of the object’s heliocentric velocity (km/s)
Obj_Sun_vy_LTC_km_s	Light-time-corrected Cartesian Y-component of the object’s heliocentric velocity (km/s)
Obj_Sun_vz_LTC_km_s	Light-time-corrected Cartesian Z-component of the object’s heliocentric velocity (km/s)
Obs_Sun_x_km	Cartesian X-component of observer's heliocentric distance (km)
Obs_Sun_y_km	Cartesian Y-component of the observer's heliocentric distance (km)
Obs_Sun_z_km	Cartesian Z-component of the observer's heliocentric distance (km)
Obs_Sun_vx_km_s	Cartesian X-component of the observer's heliocentric velocity (km/s)
Obs_Sun_vy_km_s	Cartesian Y-component of the observer's heliocentric velocity (km/s)
Obs_Sun_vz_km_s	Cartesian Z-component of the observer’s heliocentric velocity (km/s)
phase_deg	Phase angle between the Sun, object, and observer (degrees)

Note

All positions and velocities are in respect to J2000

Tip

The format and columns contained in Sorcha's optional ephemeris output file are the same as the columns outlined above.

Ephemeris File Configuration Parameters

Sorcha is initialized to use an external ephemeris file through the configuration file INPUT section:

[INPUT]


# The simulation used for the ephemeris input.
# ar=ASSIST+REBOUND interal ephemeris generation
# external=providing an external input file from the command line
# Options: "ar", "external"

ephemerides_type = external


# Format for ephemeris simulation input file if a file is specified at the command line.
# This is also the format to which ephemeris files will be written out, if specified.
# Options: csv, whitespace, hdf5

eph_format = csv

Downloading Auxiliary Files For the Ephemeris Generator

To run Sorcha's built in ephemeris generator, you will need to download the auxiliary files required for performing the N-body integrations.

To install the necessary SPICE (Spacecraft, Planet, Instrument, C-matrix, Events) auxiliary files and other required data files for ephemeris generation (774 MB total in size), run:

sorcha bootstrap

Note

This script will download and store the auxiliary files in your computer's local cache directory by default.

Note

The optional --cache flag allows you to specify a specific location to download the auxiliary files. If the files have already downloaded and want a fresh download, you need to use the -f flag.

Warning

These files can change/be updated with the revised positions of the planets every once in a while. So if you're running simulations for population statistics, we recommend downloading these files to a directory and having all Sorcha runs these files for consistency.