ForceModel#

class ForceModel#

Bases: ABC

Abstract base class for force models.

A ForceModel aggregates one or more DynamicModel sub-models into a single configurable interface. The total translational acceleration delivered to the integrator is the sum of all active sub-model contributions:

\[\mathbf{a}(t) = \sum_{i} \mathbf{a}_i(\mathbf{r},\,\dot{\mathbf{r}},\,\mathbf{p},\,t)\]

where each \(\mathbf{a}_i\) is computed by the corresponding DynamicModel instance and \(\mathbf{p}\) is the vector of solve-for or consider parameters.

In addition to the total acceleration, the ForceModel collects the partial derivatives \(\partial \mathbf{a} / \partial \mathbf{p}\) from each active sub-model. These partials populate the \(\partial \mathbf{f} / \partial \mathbf{p}\) term required to integrate the variational equations

\[\dot{\mathbf{S}} = F\,\mathbf{S} + \frac{\partial \mathbf{f}}{\partial \mathbf{p}}\]

whose solution \(\mathbf{S}\) is the sensitivity matrix used by the orbit-determination filter.

Parameters:
None
Attributes:
base_frame

Reference frame used for all dynamics computations.

force_models

Dictionary of instantiated sub-model objects keyed by model name string.

state_vector

State vector bound to this force model.

t0

Initial epoch for this force model.

tf

Final epohc for the force model.

Methods

initialize_force_models(state_vector[, ...])

Bind this ForceModel to a concrete state and frame, then build internal models.

list_forces()

Readable labels of the forces this model applies to its body.

See also

scarabaeus.ForceModelTranslation

Translational force model aggregator.

scarabaeus.DynamicModel

Base class for individual force model components.

Notes

Concrete sub-classes must override _initialize_force_models() and _compute_total_acceleration(). Call initialize_force_models() before invoking any compute methods to bind the model to a concrete StateArray, reference frame, and epoch.

initialize_force_models(state_vector: StateArray, base_frame: Frame | None = None, t0: float | None = None, tf: float | None = None) → None#

Bind this ForceModel to a concrete state and frame, then build internal models.

Must be called before any compute methods are invoked.

Parameters:
state_vectorStateArray

Initial state vector that internal force models will be constructed from.

base_frameFrame, optional

Reference frame for all dynamics computations. Defaults to None, which uses J2000.

t0float, optional

Start of the propagation span, in TDB seconds past J2000. Sub-models use it to bound their ephemeris caches. Defaults to None.

tffloat, optional

End of the propagation span, in TDB seconds past J2000. Defaults to None.

list_forces() → list[str]#

Readable labels of the forces this model applies to its body.

The base form is the sub-model names, in force_models order, and is empty before initialization. Sub-classes refine it with the details that tell one configuration of a sub-model from another.

Returns:
list of str

See also

scarabaeus.ForceModelTranslation.list_forces

The translational labels.

scarabaeus.Propagator.list_forces

The labels of every integrated object.

property base_frame: Frame#

Reference frame used for all dynamics computations. Defaults to J2000.

property force_models: dict#

Dictionary of instantiated sub-model objects keyed by model name string.

Raises:
RuntimeError

If the model has not been initialized.

property state_vector: StateArray#

State vector bound to this force model.

Raises:
RuntimeError

If initialize_force_models has not been called.

property t0: EpochArray | float#

Initial epoch for this force model.

Raises:
RuntimeError

If initialize_force_models has not been called.

property tf: EpochArray | float#

Final epohc for the force model.