Class ClockDynamics

Inheritance Relationships

Base Type

Class Documentation

class ClockDynamics : public lupnt::Dynamics

Clock-bias/drift/drift-rate error-state propagation and noise model.

ClockDynamics propagates a 2-state ([bias, drift]) or 3-state ([bias, drift, drift-rate]) ClockState3-type state using a polynomial state transition matrix (TwoStatePhi/ThreeStatePhi) plus, if a ClockModel oscillator model is set, additive random-walk process noise (TwoStateNoise/ThreeStateNoise) drawn via GetProcessNoise. Optionally applies a special-relativistic clock rate correction (PropagateWithRelativity / RelativisticRateCorrection). Used by devices/clock.hClock to propagate each agent’s “true” clock-error state, and by JointOrbitClockDynamics to propagate the clock portion of the coupled orbit+clock filter state.

Public Functions

ClockDynamics()

Construct with an undefined (no-noise) clock model.

ClockDynamics(Config &config)

Construct from a YAML configuration node.

Reads the optional model (ClockModel) and clock_bias_unit/bias_unit (ClockBiasUnit) fields.

inline void SetSeed(int seed)

Set the random-number-generator seed used for process-noise sampling.

Reseeds the internal Mersenne Twister RNG (rng_).

inline int GetSeed() const

Return the current RNG seed.

inline void SetModel(ClockModel model)

Set the oscillator model used for process-noise generation.

inline ClockModel GetModel() const

Return the configured oscillator model.

inline void SetAddNoise(bool add_noise)

Enable/disable adding stochastic process noise during propagation.

inline bool GetAddNoise() const

Return whether stochastic process noise is added during propagation.

inline void SetClockBiasUnit(ClockBiasUnit unit)

Set the unit (seconds/meters/kilometers) used for the clock-bias state.

inline ClockBiasUnit GetClockBiasUnit() const

Return the unit used for the clock-bias state.

VecX GetProcessNoise(Real dt, int state_size)

Draw a sample of the clock process noise over a time step dt.

Builds the noise covariance via TwoStateNoise/ThreeStateNoise (using model_ and bias_unit_) and draws one sample via SampleMvNormal using the internal RNG (rng_).

Parameters:

  • dt – Time step [s].

  • state_size – Clock state size (2 or 3).

Returns:

Process-noise sample vector, in bias_unit_ units.

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

Propagate the clock-bias state and compute its state transition matrix, without relativistic correction.

Equivalent to PropagateImpl(x0, t0, tf, u, nullptr, stm).

Parameters:

  • x0 – Initial clock state (2- or 3-element) at time t0.

  • t0 – Initial epoch [s].

  • tf – Final epoch [s].

  • u – Unused; must be nullptr.

  • stm – Output: clock state transition matrix; left unmodified if nullptr.

Returns:

Propagated clock state at time tf.

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

Propagate the clock-bias state without relativistic correction or STM output.

Equivalent to PropagateImpl(x0, t0, tf, u, nullptr, nullptr).

State PropagateWithRelativity(const State &x0, Real t0, Real tf, const ClockRelativityContext &relativity, const State *u = nullptr, MatXd *stm = nullptr)

Propagate the clock-bias state including a special-relativistic clock rate correction.

Called by JointOrbitClockDynamics/devices/clock.hClock when the object’s orbital position/velocity relative to a central body is known, so that the gravitational + velocity time-dilation rate (see RelativisticRateCorrection) is added to the clock-bias drift over [t0, / tf]. 

    @param x0          Initial clock state at time `t0`.
    @param t0          Initial epoch [s].
    @param tf          Final epoch [s].
    @param relativity  Relativistic-correction context: centered
                        position/velocity at `t0` and `tf`, central-body GM,
                        speed of light, and reference rate offset.
    @param u           Unused; must be nullptr.
    @param stm         Output: clock state transition matrix; left unmodified if
                        nullptr.
    @return            Propagated clock state at time `tf`, including the
                        relativistic bias contribution.

inline virtual StateType GetStateType() const override

Return ClockState3::TYPE, the clock-bias state type propagated by this model.

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).

Public Static Functions

static std::tuple<double, double, double> GetClockValues(ClockModel clk_model)

Look up the oscillator power-spectral-density coefficients (q1, q2, q3) for a given clock model.

These are the white-frequency, random-walk-frequency, and (for 3-state models) frequency-drift PSD coefficients used by TwoStateNoise/ThreeStateNoise to build the process-noise covariance over a time step dt. Values are taken from manufacturer/mission specifications (e.g. OCXO, USO, CSAC, MINI_RAFS, RAFS, DSAC); see the source comments for references.

Parameters:

clk_model – Clock oscillator model.

Returns:

Tuple (q1 [s^2/s], q2 [1/s], q3 [1/s^3]) (units as consumed by TwoStateNoise/ThreeStateNoise).

static double SecondsToBiasUnitScale(ClockBiasUnit unit)

Return the multiplicative scale factor converting a clock bias from seconds to unit.

SECONDS -> 1, METERS -> C (speed of light), KILOMETERS -> C * KM_M. Used to convert clock-bias states/covariances between time and range-equivalent units for pseudorange-based measurements (measurements/).

Parameters:

unit – Target clock-bias unit.

Returns:

Scale factor such that value_in_unit = value_in_seconds * scale.

static Real SecondsToBiasUnits(Real value_s, ClockBiasUnit unit)

Convert a clock-bias value from seconds to the given bias unit.

Parameters:

  • value_s – Clock bias [s].

  • unit – Target clock-bias unit.

Returns:

Clock bias in unit (seconds, meters, or kilometers).

static Real BiasUnitsToSeconds(Real value, ClockBiasUnit unit)

Convert a clock-bias value from the given bias unit back to seconds.

Parameters:

  • value – Clock bias in unit.

  • unit – Source clock-bias unit.

Returns:

Clock bias [s].

static std::vector<std::string> GetStateUnits(int state_size, ClockBiasUnit unit)

Return the unit strings for a clock state vector of the given size and bias unit.

E.g. for unit = SECONDS and state_size = 3, returns {"s", "s/s", "s/s^2"}. Used to tag ClockState3/State objects with human-readable units after propagation.

Parameters:

  • state_size – Clock state size (must be 2 or 3).

  • unit – Clock-bias unit.

Returns:

Vector of state_size unit strings (bias, drift, [drift-rate]).

static Real RelativisticRateCorrection(const Vec3 &r_centered, const Vec3 &v_centered, Real GM, Real c = C, Real reference_rate_offset = 0.0)

Compute the special/general-relativistic fractional clock-rate correction for an object at a given position/velocity relative to a central body.

Returns reference_rate_offset - (GM/r + 0.5*v^2) / c^2, the leading-order gravitational + velocity time-dilation term (combined Sagnac/Shapiro-style rate offset) relative to a clock at infinity at rest. Used by PropagateImpl/PropagateWithRelativity to add a relativistic drift to the clock-bias rate, and by JointOrbitClockDynamics::RelativisticRate to couple the orbit state to the clock-bias rate in the joint filter state.

Parameters:

  • r_centered – Position relative to the central body [m] (inertial frame, e.g. GCRF).

  • v_centered – Velocity relative to the central body [m/s] (inertial frame, e.g. GCRF).

  • GM – Gravitational parameter of the central body [m^3/s^2].

  • c – Speed of light [m/s] (defaults to the global constant C).

  • reference_rate_offset – Constant offset added to the result, e.g. to reference the rate to a different clock/frame [dimensionless].

Returns:

Fractional clock-rate correction [dimensionless, i.e. ds/dt].

static Mat2 TwoStatePhi(Real dt)

Return the 2-state (bias, drift) clock state transition matrix for time step dt: [[1, dt], [0, 1]].

static Mat3 ThreeStatePhi(Real dt)

Return the 3-state (bias, drift, drift-rate) clock state transition matrix for time step dt: [[1, dt, dt^2/2], [0, 1, dt], [0, 0, 1]].

static Mat2 TwoStateNoise(ClockModel clk_model, Real dt)

Compute the 2-state clock process-noise covariance over time step dt, in seconds-equivalent units.

Built from the white-frequency (q1) and random-walk-frequency (q2) power-spectral densities returned by GetClockValues for clk_model.

Parameters:

  • clk_model – Clock oscillator model.

  • dt – Time step [s].

Returns:

2x2 process-noise covariance Q for [bias, drift], in seconds^2 / (seconds/s)^2.

static Mat2 TwoStateNoise(ClockModel clk_model, Real dt, ClockBiasUnit unit)

2-state process-noise covariance, scaled to the given clock-bias unit.

Equivalent to TwoStateNoise(clk_model, dt) * scale^2 where scale = / SecondsToBiasUnitScale(unit).

static Mat3 ThreeStateNoise(ClockModel clk_model, Real dt)

Compute the 3-state clock process-noise covariance over time step dt, in seconds-equivalent units.

Built from the white-frequency (q1), random-walk-frequency (q2), and frequency-drift (q3) power-spectral densities returned by GetClockValues for clk_model.

Parameters:

  • clk_model – Clock oscillator model.

  • dt – Time step [s].

Returns:

3x3 process-noise covariance Q for [bias, drift, drift-rate], in seconds-equivalent units.

static Mat3 ThreeStateNoise(ClockModel clk_model, Real dt, ClockBiasUnit unit)

3-state process-noise covariance, scaled to the given clock-bias unit.

Equivalent to ThreeStateNoise(clk_model, dt) * scale^2 where scale = / SecondsToBiasUnitScale(unit).

Protected Attributes

int seed_ = 0
Ptr<std::mt19937> rng_ = nullptr
ClockModel model_
bool add_noise_ = true
ClockBiasUnit bias_unit_ = ClockBiasUnit::SECONDS