Using the Tester - B612-Asteroid-Institute/orb_it GitHub 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.

The Basic Test

The main functionality of orb_it is in its testing procedure. The basic framework of the test is as follows,

  1. Input an initial orbit state at a specified t0 time and a set of times to generate observations over.
  2. Generate Ephemerides using the integrator over the set of times provided in the first step. (A user can also provide an astrometric error here to simulate real observational inaccuracies)
  3. Use the integrator’s Orbit Determination function to fit the Ephemeris observations to obtain an orbital state at the time of the last observation.
  4. Propagate the initial input orbit to the time of the last generated observation or the time of the orbit from step 3.
  5. Compare the orbital state vectors from step 3 to the vectors from step 4.

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 python 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 Ascension 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 python orbits 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 (observational arcs) 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).

Varying over backend (integrator)

You can pass a list of supported integrator backend objects to backend=. Example,

integs = [FINDORB(),PYOORB(),ORBFIT()]
runTest(...,backend=integs,...)

It is varied over fifth (fifth 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

NOTE: Some integrators have special paths for saving their files, and some backends produce bash files for easy reproducibility.

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.