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:
DynamicModelPiecewise 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_pfogmandbeta_pfogmare 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
EpochArrayor as raw ephemeris seconds (TDB). It is the origin of the batch grid, not the start of the current propagation: in a multi-legMissionSequenceevery leg must be given the samet0so 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 whenbeta_pfogmis 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_lengthDuration of one batch.
body_fixed_frameBody-fixed frame the components are expressed in, if any.
default_betaDefault inverse correlation coefficients used when ‘beta_pfogm’ is not provided.
depends_on_velocityWhether the applied acceleration is a function of velocity.
frameFrame the batch components are expressed in.
n_batchesNumber of batches.
originCelestial body serving as origin of the state vector.
origin_nameName of the origin body.
ref_frameReference frame used by the model.
relative_bodyBody the RTN triad is referred to, if any.
t0Reference epoch of the first batch.
Methods
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 <= 0orn_batches < 1.- InvalidEpochError
If
t0is neither anEpochArraynor a real number.- DynamicalUtils.InvalidFrameError
If
frameis not one of the supported frames.- DynamicalUtils.MissingBodyFixedFrameError
If
frame="body_fixed"is requested withoutbody_fixed_frame.
See also
scarabaeus.FirstOrderGaussMarkovSingle-arc variant of this model.
scarabaeus.StateArrayState vector used to initialize the model.
scarabaeus.PropagatorPropagator that integrates the augmented state.
scarabaeus.DynamicModelAbstract 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_pfogmis not provided,default_betais 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 partialsframe_partials()returns; the inertial and body-fixed rotations depend on the epoch alone.- 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
Noneif the arc was not pinned.
- property default_beta: ndarray#
Default inverse correlation coefficients used when ‘beta_pfogm’ is not provided.