PiecewiseFirstOrderGaussMarkov#

class PiecewiseFirstOrderGaussMarkov(origin: Body, spacecraft: Spacecraft, base_frame: Frame, t0: EpochArray | float, batch_length: float, n_batches: int, default_beta: ndarray | None = None, frame: str = 'inertial', body_fixed_frame=None, relative_body=None)#

Bases: DynamicModel

Piecewise first-order exponentially correlated Gauss-Markov acceleration model using a single stacked acceleration state.

The propagation arc is divided into \(N_b\) fixed-length time batches. Each batch \(k\) carries an independent empirical acceleration \(\mathbf{a}^{(k)}\) that decays exponentially within the batch:

\[\dot{\mathbf{a}}^{(k)} = -\mathbf{B}^{(k)}\,\mathbf{a}^{(k)}\]

Only the active batch \(k^*\) at the current epoch contributes to the translational dynamics: \(\ddot{\mathbf{r}} = \mathbf{a}_{\mathrm{other}} + \mathbf T\,\mathbf{a}^{(k^*)}\), where \(\mathbf T\) rotates the frame the components are expressed in (frame) into the propagation frame. The inverse correlation times \(\beta_i^{(k)}\) can be estimated as static parameters via ("beta_pfogm", spice_id) state entries.

The model partitions the propagation arc into fixed-length time batches and assigns one 3D empirical acceleration state to each batch. The full augmented acceleration state is stored as

\[\begin{split}\mathbf a_{pfogm} = \begin{bmatrix} \mathbf a^{(0)} \\ \mathbf a^{(1)} \\ \vdots \\ \mathbf a^{(N_b-1)} \end{bmatrix} \in \mathbb{R}^{3N_b}\end{split}\]

where each batch state is

\[\begin{split}\mathbf a^{(k)} = \begin{bmatrix} a_x^{(k)} \\ a_y^{(k)} \\ a_z^{(k)} \end{bmatrix}\end{split}\]

The translational dynamics are

\[\dot{\mathbf r} = \mathbf v\]
\[\dot{\mathbf v} = \mathbf T\,\mathbf a^{(k^*)}\]

where \(k^*\) is the active batch index at the current epoch.

Each batch follows first-order Gauss-Markov drift

\[\dot{\mathbf a}^{(k)} = -\mathbf B^{(k)} \mathbf a^{(k)}\]

with

\[\begin{split}\mathbf B^{(k)} = \begin{bmatrix} \beta_x^{(k)} & 0 & 0 \\ 0 & \beta_y^{(k)} & 0 \\ 0 & 0 & \beta_z^{(k)} \end{bmatrix}\end{split}\]

The full stacked dynamics are therefore block diagonal.

Parameters:
originBody

Propagation origin. a_pfogm and beta_pfogm are read from the propagated state at evaluation time.

spacecraftSpacecraft

Spacecraft object associated with the propagated body.

base_frameFrame

Reference frame of the propagator.

t0EpochArray or float

Reference epoch at which batch 0 starts, as an EpochArray or as raw ephemeris seconds (TDB). It is the origin of the batch grid, not the start of the current propagation: in a multi-leg MissionSequence every leg must be given the same t0 so the batches tile the whole arc and a batch index means the same thing in every leg.

batch_lengthfloat

Duration of each time batch, in seconds.

n_batchesint

Number of piecewise time batches.

default_betanp.ndarray, optional

Default 3-vector of inverse correlation coefficients [beta_x, beta_y, beta_z] used for every batch when beta_pfogm is not provided in the state array.

framestr, optional

Frame the components of every batch (and of their \(\boldsymbol\beta\)) are expressed in: "inertial" (the propagation frame, the default), "RTN" (radial / along-track / cross-track, the RTN triad) or "body_fixed".

body_fixed_framestr or Frame, optional

Frame the components are expressed in, for frame="body_fixed" (for example 'IAU_BENNU').

relative_bodystr or Body, optional

Body the RTN triad is built about, when that is not the propagation origin. Defaults to the propagation origin.

Attributes:
batch_length

Duration of one batch.

body_fixed_frame

Body-fixed frame the components are expressed in, if any.

default_beta

Default inverse correlation coefficients used when ‘beta_pfogm’ is not provided.

depends_on_velocity

Whether the applied acceleration is a function of velocity.

frame

Frame the batch components are expressed in.

n_batches

Number of batches.

origin

Celestial body serving as origin of the state vector.

origin_name

Name of the origin body.

ref_frame

Reference frame used by the model.

relative_body

Body the RTN triad is referred to, if any.

t0

Reference epoch of the first batch.

Methods

clear_batch_window()

Drop any pinned batch, restoring the per-epoch lookup.

compute_acceleration(position, ...)

Return the active batch Gauss-Markov acceleration applied to the body.

get_active_batch_bounds(epoch)

Return the active batch index and its time bounds.

get_all_batch_accelerations(current_state, body)

Return all batch acceleration states reshaped as (n_batches, 3).

pin_batch_window(t_start, t_end)

Pin the batch that owns an integration arc, so the dynamics stay continuous across it.

Raises:
ValueError

If batch_length <= 0 or n_batches < 1.

InvalidEpochError

If t0 is neither an EpochArray nor a real number.

DynamicalUtils.InvalidFrameError

If frame is not one of the supported frames.

DynamicalUtils.MissingBodyFixedFrameError

If frame="body_fixed" is requested without body_fixed_frame.

See also

scarabaeus.FirstOrderGaussMarkov

Single-arc variant of this model.

scarabaeus.StateArray

State vector used to initialize the model.

scarabaeus.Propagator

Propagator that integrates the augmented state.

scarabaeus.DynamicModel

Abstract base class for all force model components.

Notes

The state vector must contain:

  • ("a_pfogm", 3 * n_batches, "estimated", "dynamic", owner, value)

Optionally, if the inverse correlation times are estimated:

  • ("beta_pfogm", 3 * n_batches, "estimated", "static", owner, value)

If beta_pfogm is not provided, default_beta is repeated for all batches.

Only the active batch contributes to compute_acceleration(); all stacked batch states evolve according to their own drift, giving block-diagonal Jacobians and a simple selection matrix.

Every batch lives in the chosen frame: in "RTN" its components are radial, along-track and cross-track, and the drift acts on those components. Only the applied acceleration is rotated, so the selection matrix becomes \(\mathbf T\) at the active batch. The RTN triad is built from the state, which adds the position and velocity partials frame_partials() returns; the inertial and body-fixed rotations depend on the epoch alone.

clear_batch_window() → None#

Drop any pinned batch, restoring the per-epoch lookup.

compute_acceleration(position: ndarray, current_state: dict, epoch: float, body: Body) → ndarray#

Return the active batch Gauss-Markov acceleration applied to the body.

Parameters:
positionnp.ndarray

Spacecraft position vector, used by the RTN triad.

current_statedict

Dictionary containing the propagated state.

epochfloat

Current propagation epoch.

bodyBody

Body for which the acceleration is evaluated.

Returns:
np.ndarray

Active batch acceleration \(\mathbf T\,\mathbf a^{(k^*)}\) in the propagation frame, shape (3,).

get_active_batch_bounds(epoch: float) → tuple[int, float, float]#

Return the active batch index and its time bounds.

Parameters:
epochfloat

Current epoch.

Returns:
tuple[int, float, float]

Tuple (batch_idx, batch_start, batch_end).

get_all_batch_accelerations(current_state: dict, body: Body) → ndarray#

Return all batch acceleration states reshaped as (n_batches, 3).

Returns:
np.ndarray

Matrix whose k-th row is the acceleration vector of batch k.

pin_batch_window(t_start: float, t_end: float) → int | None#

Pin the batch that owns an integration arc, so the dynamics stay continuous across it.

Batch membership is right-continuous, so the epoch closing an arc that ends on a batch boundary belongs to the next batch. An integrator evaluating its final stage there sees the acceleration and Jacobian jump at the very point it has to land on, shrinks its step to resolve a discontinuity that never moves, and gives up once the step falls below the spacing of the epoch — which at ephemeris-second magnitudes is large enough to hit in practice. Pinning the batch for the arc removes the jump from the arc’s interior and endpoint alike.

Only arcs that lie within a single batch are pinned; the propagator already splits arcs at interior batch boundaries, so that is the normal case. Anything else clears the pin and leaves the per-epoch lookup in charge.

Parameters:
t_start, t_endfloat

Arc bounds in ephemeris seconds (TDB); order does not matter.

Returns:
int or None

The pinned batch index, or None if the arc was not pinned.

property batch_length: float#

Duration of one batch.

property body_fixed_frame: str | None#

Body-fixed frame the components are expressed in, if any.

property default_beta: ndarray#

Default inverse correlation coefficients used when ‘beta_pfogm’ is not provided.

property depends_on_velocity: bool#

Whether the applied acceleration is a function of velocity.

True for the RTN frame, whose triad is built from the velocity. The force model reads this to decide whether a \(\partial \mathbf a / \partial \mathbf v\) block is needed.

property frame: str#

Frame the batch components are expressed in.

property n_batches: int#

Number of batches.

property origin: Body#

Celestial body serving as origin of the state vector.

property origin_name: str#

Name of the origin body.

property ref_frame: str#

Reference frame used by the model.

property relative_body: str | None#

Body the RTN triad is referred to, if any.

property t0: float#

Reference epoch of the first batch.

exception InvalidEpochError#

Bases: TypeError

Raised when t0 is neither an EpochArray nor a real number.