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 as orbits 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.