Propagation results

After numerically propagating the dynamics, as follows:

dynamics_simulator = dynamics.simulator.create_dynamics_simulator(
    body_system, propagator_settings)
propagation_results = dynamics_simulator.propagation_results

the results are stored in the propagation_results object. For a single-arc propagation, this object is of the type SingleArcSimulationResults. Multi- and hybrid-arc results are discussed briefly below.

The three primary numerical results of the propagation are:

• The numerical results of the propagation, in ‘processed’ coordinates (e.g. Cartesian elements for translational dynamics, see Processed Elements), stored in the state_history attribute

• The numerical results of the propagation, in the propagated coordinates, stored in the unprocessed_state_history attribute

• The dependent variables of the propagation (if any, see dependent variables API documentation), stored in the dependent_variable_history attribute

Each of these is returned as a dictionary, with the numerical integration epochs as key, and the current state/dependent variable as value. For example:

# Propagate dynamics
dynamics_simulator = dynamics.simulator.create_dynamics_simulator(
    body_system, propagator_settings)

# Retrieve object with full results
propagation_results = dynamics_simulator.propagation_results

# Retrieve the individual result histories
states = propagation_results.state_history
unprocessed_states = propagation_results.unprocessed_state_history
dependent_variables = propagation_results.dependent_variable_history

The order of the entries of the state/dependent variable vector at every epoch can be printed to the consol before propagation as described here. This information can also be retrieved as dictionaries from the processed_state_ids propagated_state_ids and dependent_variable_ids attributes.

Additional results of the propagation, such as the runtime (e.g. real clock time) and number of function evaluations as a function of simulation time (e.g. epoch in th simulation) can also be extracted from the SingleArcPropagatorResult class. See the API documentation entries for this class for a comprehensive list of options.

Understanding the state output

It is important to realize that, regardless of the propagator that is used (for translational dynamics: Cowell, Gauss-Kepler, etc., see Translational Dynamics) the state_history attribute will always provide the results of the propagation in Cartesian elements (for the case of translational dynamics). In the case where a different formulation than the Cowell formulation is used, the states that were actually used during the numerical integration can be accessed through the dependent_variable_history. For instance, whe using the gauss_keplerian propagator, it is the equations of motion in Keplerian elements which are solved numerically. The unprocessed_state_history attribute will thn provide you with the history of the Keplerian elements, which were directly solved for by the integrator, while the state_history provides the Cartesian elements, obtained from the conversion of the propagated Keplerian elements (see Processed vs. Propagated State Elements for more details).

Checking the outcome of the propagation

For various reasons, such as the occurrence of a NaN or Inf value in the state during a propagation, segmentation fault in underlying (user-defined) code, etc., the propagation may not propagate successfully to the final user-specified conditions. In the case of any such errors, the propagation results will be saved and are accessible as indicated above - up until the time of termination.

To determine whether the propagation encountered any issues, the integration_completed_successfully boolean of the SingleArcSimulationResults class can be queried

More details on the specifics of the reason for termination can be extracted from the termination_details attribute of the SingleArcSimulationResults class.

See also

For a complete example of a perturbed single-arc propagation, please see the tutorial Perturbed satellite orbit.

Multi- and hybrid-arc results

When performing a multi- or hybrid-arc propagation, the results are stored in a MultiArcPropagatorResults and HybridArcPropagatorResults object, respectively. The main contents of these objects are a set of SingleArcSimulationResults objects, which contain the results of the constituent single arcs, as described above. In addition, the multi- and hybrid arc results objects contain a number of pieces of information that are specific to the full propagation, as opposed to its separate arcs. The reader is referred to the API documentation for more details. A small example is shown below:

# Propagate multi-arc dynamics (as defined by propagator_settings object)
dynamics_simulator = dynamics.simulator.create_dynamics_simulator(
    body_system, propagator_settings)

# Extract multi-arc results
propagation_results = dynamics_simulator.propagation_results
number_of_arcs = propagation_results.number_of_arcs

# Extract full results of first arc, and retrieve the propagated states
first_arc_propagation_results = propagation_results.get_arc_results( 0 )
first_arc_states = first_arc_propagation_results.state_history