Using the Tester - B612-Asteroid-Institute/orb_it Wiki
For an interactive demo, you can find a Jupyter Notebook in the demo folder.
This page will go over the functionality and features of the main tester of orb_it.
runTest()
Runs the end-to-end test for a list of orbits. Generates ephemeris, conducts orbit determination, and propagates the initial orbits to the final time and returns the comparison.
Parameters
- orbits : orbit object
~orb_it.raiden.Orbits
Orbits to be tested. - observatory_code: str or list of strings MPC Observatory code(s) for the observatory to be tested. (500 for Geocenter)
- dts : array of floats, 2D array of floats, or list of
~astropy.time.core.Time
objects with the same length asorbits
List of observation times after the initial time to test the orbits over. Measured in days. NOTE: Anything passed to this parameter must have values in ASCENDING ORDER. - backend : backend object
~orb_it.backend.backend.BACKEND
Integrator backend to be used for the test. - astrometric_error : float or list of floats, optional Astrometric error to be added to the generated observations. If None, no astrometric error is added. Units are milliarcseconds.
- full_output : bool, optional If True, returns the full output of the test including residuals and covariance matrices. DOES NOT WORK WITH PYOORB CURRENTLY.
- out : str, optional Path to the output directory for saving necessary files for this test to be run independently. This includes configuration files, generated files, and bash scripts. It has the file structure '{out}/{orbit_id}/{days propagated}days_{error}mas_{timestamp}'. If None, no files are saved.
Returns
- result :
~pandas.DataFrame
DataFrame with the results of the test. Has the following columns:- orbit_id : str Orbit ID of the object being tested.
- integrator : str Name of the integrator backend used for test.
- observatory_code : str MPC Observatory code for the observatory to be tested. (500 for Geocenter)
- arc_length [days] : float Length of time in days over which the orbits are tested.
- num_obs : int Number of observations generated in the test.
- epoch [mjd] : float Time at the end of the arc in mjd (t0 + final dt day).
- astrometric_error [mas] : float Astrometric error added to the observations.
- delta epoch [mjd] : float Difference between the final epochs of the orbit determination and the propagated orbit.
- delta r [km] : float The absolute distance between the orbit determination result and the propagated orbit. Measured in kilometers.
- delta v [m/s] : float The absolute velocity difference between the orbit determination result and the propagated orbit. Measured in meters per second.
- delta x [km] : float The x position difference between the orbit determination result and the propagated orbit. Measured in kilometers.
- delta y [km] : float The y position difference between the orbit determination result and the propagated orbit. Measured in kilometers.
- delta z [km] : float The z position difference between the orbit determination result and the propagated orbit. Measured in kilometers.
- delta vx [m/s] : float The x velocity difference between the orbit determination result and the propagated orbit. Measured in meters per second.
- delta vy [m/s] : float The y velocity difference between the orbit determination result and the propagated orbit. Measured in meters per second.
- delta vz [m/s] : float The z velocity difference between the orbit determination result and the propagated orbit. Measured in meters per second.
- rms delta ra [arcsec] : float, choose
full_output=True
to get this value The root mean square difference of the Right Acension of the Residuals from Orbit Determination. Measured in arcseconds. - rms delta dec [arcsec] : float, choose
full_output=True
to get this value The root mean square difference of the Declination of the Residuals from Orbit Determination. Measured in arcseconds. - rms delta time [seconds] : float, choose
full_output=True
to get this value The root mean square difference of the Time of the Residuals from Orbit Determination. Measured in seconds.
Varying Parameters with runTest()
You can vary specific parameters if given to runTest()
as a list or array.
Varying orbits
You can supply multiple different orbits in one object (see orbits object) and it will be varied over first (ie it will be the first parameter loop).
Varying dts
You can supply many different dts
to the tester. You can supply a single array of floats which acts as days added on to the t0
time of the orbit (a single arc). Example,
# If you specify dts as
dts = np.arange(0, 30, 1)
# which is an array spanning 0 to 29 with an element counting for one whole number step
# the tester will read this as "one month of observations (arc) with one observation every day".
You can pass it a 2D array of floats to vary over different arcs. Example,
# This will iterate over both arcs
dts = [np.arange(0, 30, 1), np.arange(0, 77, 7)]
Or you can provide it with a list of ~astropy.time.core.Time
objects that has the same length as the amount of orbits provided. This allows a user to specify specific times for the observations to be tested over. The index of the Time objects in the list must correspond to the index of the orbit being tested. Example,
# Specifying the arcs
arc0 = Time([59000,59001,...], format='mjd)
arc1 = Time([59050,59052,...], format='mjd)
...
# Putting into a times list
times = [arc0, arc1, ...]
# These arcs will correspond to orbits[0], orbits[1], ...
The dts
are varied over second (second parameter loop).
Varying astrometric_error
You can vary over astrometric errors by supplying an array of errors to test over. Example,
errors = [0., 10., 100.]
# would test over 0, then 10, then 100 milliarcseconds of error
It is varied over third (third parameter loop).
Varying over observatory_code
You can pass a list of MPC observatory codes to the tester. Example,
obsc = ['500', 'I11', '664']
# It will test over these codes sequentially
It is varied over fourth (fourth parameter loop).
Using out
This parameter allows you to save the files generated during the test so that they can be analyzed further. It has a general file path guideline of,
{out}/{orbit_id}/{days propagated}_{error}_{timestamp}/{integrator}/{function or process}/files
Some integrator functionality may make out
cumbersome with how many files are generated. With this, a waiver that can be specified before the first trial will be generated acknowledging that you know the risks of saving these files.