Class Dynamics

Inheritance Relationships

Derived Types

Class Documentation

class Dynamics

Base interface for all state-propagation models in LuPNT (orbit, attitude, clock, IMU, surface, parameter, and joint dynamics).

A Dynamics subclass owns the “physics” for one state vector: it defines how to advance a State from t0 to tf (Propagate), optionally returning a state transition matrix (STM) via automatic differentiation, and exposes a ParamState of force-model/clock/etc. parameters that filters (filters/) can read, perturb, or estimate. Numerical subclasses (NumericalDynamics and its descendants) additionally provide a ComputeRates right-hand-side consumed by the integrators in numerics/integrator.h.

Subclassed by lupnt::AnalyticalDynamics, lupnt::AttitudeDynamics, lupnt::ClockDynamics, lupnt::ImuDynamics, lupnt::NumericalDynamics, lupnt::ParameterDynamics, lupnt::StaticDynamics, lupnt::SurfaceDynamics2D

Public Functions

Dynamics() = default
Dynamics(Config &config)

Construct from a YAML configuration node.

Reads the optional print_progress flag. Called by the AssetFactory<Dynamics, Config&>-based constructors of concrete dynamics classes (e.g. NumericalDynamics, ClockDynamics, AttitudeDynamics) when an agent/asset is built from a simulation YAML config.

Parameters:

config – YAML configuration node for this dynamics model.

virtual ~Dynamics() = default
inline void SetPrintProgress(bool print)

Enable/disable printing a progress bar during multi-step Propagate calls.

inline bool GetPrintProgress()

Return whether progress printing is enabled.

virtual State Propagate(const State &x0, Real t0, Real tf, const State *u = nullptr) = 0

Propagate the state from t0 to tf without computing a state transition matrix.

This is the core propagation entry point implemented by every concrete dynamics class (e.g. NumericalDynamics::Propagate, AnalyticalDynamics::Propagate, ClockDynamics::Propagate). It is called once per integration/measurement step by simulation drivers in applications/ and by agents/ to advance an object’s true or estimated state.

Parameters:

  • x0 – Initial state at time t0 (layout/units defined by the subclass).

  • t0 – Initial epoch [s, TDB since J2000 for orbit/attitude dynamics].

  • tf – Final epoch [s, TDB since J2000 for orbit/attitude dynamics].

  • u – Optional control/forcing input (e.g. thrust, RTN reference state); nullptr if unused.

Returns:

Propagated state at time tf.

virtual State Propagate(const State &x0, Real t0, Real tf, const State *u, MatXd *stm)

Propagate the state and compute the state transition matrix (STM) d(xf)/d(x0) via automatic differentiation.

Default implementation: if stm == nullptr, forwards to the no-STM Propagate overload; otherwise wraps Propagate(x0, t0, tf, u) in an autodiff Jacobian (jacobian(...)) with respect to x0. Used by filters (filters/) that need the linearized state transition for covariance propagation (e.g. EKF/UKF time updates).

Parameters:

  • x0 – Initial state at time t0.

  • t0 – Initial epoch [s, TDB since J2000].

  • tf – Final epoch [s, TDB since J2000].

  • u – Optional control/forcing input; nullptr if unused.

  • stm – Output: state transition matrix d(xf)/d(x0); left unmodified if nullptr.

Returns:

Propagated state at time tf.

virtual MatX Propagate(const State &x0, const VecX &tfs, const State *u = nullptr)

Propagate the state to a sequence of output epochs.

Repeatedly calls Propagate(x0, t0, tf, u) between consecutive entries of tfs, accumulating each result as a row of the returned matrix. Used by applications/ and analysis scripts to generate a full trajectory time history in one call, with optional progress-bar output (see SetPrintProgress).

Parameters:

  • x0 – Initial state at tfs(0).

  • tfs – Vector of output epochs [s, TDB since J2000], including the initial epoch as tfs(0).

  • u – Optional control/forcing input applied at every step; nullptr if unused.

Returns:

Matrix whose i-th row is the propagated state at tfs(i).

virtual State PropagateWithParams(const State &x0, Real t0, Real tf, const ParamState &params, const State *u = nullptr)

Propagate the state after first installing a given parameter set.

Calls SetParams(params) then Propagate(x0, t0, tf, u). Used by filters and consider-covariance analyses that need to evaluate the dynamics under a specific (e.g. perturbed or estimated) parameter vector without permanently mutating the dynamics object’s stored parameters beforehand.

Parameters:

  • x0 – Initial state at time t0.

  • t0 – Initial epoch [s, TDB since J2000].

  • tf – Final epoch [s, TDB since J2000].

  • params – Parameter values/names to install before propagating (see ParamState, GetParams/SetParams).

  • u – Optional control/forcing input; nullptr if unused.

Returns:

Propagated state at time tf.

virtual State PropagateWithParams(const State &x0, Real t0, Real tf, const ParamState &params, const State *u, MatXd *stm_state, MatXd *stm_param)

Propagate the state and parameters, returning both the state-transition and parameter-sensitivity Jacobians.

If both stm_state and stm_param are nullptr, forwards to the no-Jacobian PropagateWithParams overload. Otherwise computes d(xf)/d(x0) into stm_state and d(xf)/d(params) into stm_param via autodiff. Used by batch least-squares and EKF/UKF filters (filters/) that jointly estimate the state and dynamics parameters (e.g. SRP/drag coefficients, clock-bias parameters).

Parameters:

  • x0 – Initial state at time t0.

  • t0 – Initial epoch [s, TDB since J2000].

  • tf – Final epoch [s, TDB since J2000].

  • params – Parameter values/names to install before propagating.

  • u – Optional control/forcing input; nullptr if unused.

  • stm_state – State-transition Jacobian d(xf)/d(x0); unmodified if nullptr.

  • stm_param – Parameter-sensitivity Jacobian d(xf)/d(params); unmodified if nullptr.

Returns:

Propagated state at time tf.

virtual MatX PropagateWithParams(const State &x0, const VecX &tfs, const ParamState &params, const State *u = nullptr)

Propagate the state with the given parameters to a sequence of output epochs.

Sequence-output counterpart of PropagateWithParams, analogous to Propagate(x0, tfs, u) but holding params fixed across all steps.

Parameters:

  • x0 – Initial state at tfs(0).

  • tfs – Vector of output epochs [s, TDB since J2000].

  • params – Parameter values/names to install before propagating.

  • u – Optional control/forcing input applied at every step; nullptr if unused.

Returns:

Matrix whose i-th row is the propagated state at tfs(i).

inline void SetParams(const ParamState &params)

Replace the dynamics’ parameter vector (e.g. SRP/drag coefficients, clock model parameters) wholesale.

inline void SetParam(const std::string &key, const Real value)

Set a single named parameter’s value in-place.

Looks up key among the current parameter names and overwrites that entry’s value with value. Used by force-model setters (e.g. NBodyDynamics::SetSrpCoeff/SetDragCoeff) and by filters when updating estimated parameter values between iterations. Logs a warning (does nothing) if key is not a known parameter name.

Parameters:

  • key – Parameter name to update (must already exist in params_).

  • value – New scalar value for the parameter.

inline ParamState GetParams() const

Return the dynamics’ current parameter vector (names + values).

inline Real GetParam(const std::string &key) const

Look up a single named parameter’s value.

Parameters:

key – Parameter name to look up.

Returns:

The parameter’s value, or Real(0) if key is not found.

virtual StateType GetStateType() const = 0

Return the StateType tag of the state vector this dynamics model operates on (e.g. Cart6::TYPE, Attitude::TYPE, ClockState3::TYPE).

Used by state-converters and asset wiring code to verify that a dynamics object is paired with a compatible state representation.

Protected Attributes

bool print_progress_ = false

Flag to indicate whether to print progress.

ParamState params_

Parameters for the dynamics, initialized as empty.