ForceModelTranslation#

class ForceModelTranslation(primary_body: Spacecraft, t0: EpochArray | float = None, third_bodies: list | None = None, cannonball_SRP: bool = False, nplate_SRP: bool = False, sph_harm: bool = False, sph_harm_body: CelestialBody | None = None, sph_harm_order: int | None = None, sph_harm_cs_file: str | None = None, sph_harm_norm_flag: bool | None = None, sph_degree_max: int = 100, sph_harm_bodies: list | None = None, finite_burn: bool = False, maneuver: Maneuver | None = None, smoothed_maneuvers: list | None = None, dv_smoothing_factor: float = 1.0, yarkovsky_effect: bool = False, thermal_radiation: bool = False, thermal_model=None, antenna_radiation_pressure: bool = False, antenna_emitters: list | None = None, first_order_gauss_markov: bool = False, fogm_beta: ndarray | float | None = None, fogm_frame: str = 'inertial', fogm_body_fixed_frame=None, fogm_relative_body=None, piecewise_first_order_gauss_markov: bool = False, pfogm_beta: ndarray | float | None = None, pfogm_batch_length: float | None = None, pfogm_n_batches: int | None = None, pfogm_frame: str = 'inertial', pfogm_body_fixed_frame=None, pfogm_relative_body=None, fourier_acceleration: bool = False, fourier_degree: int = 0, fourier_frame: str = 'inertial', fourier_angle: str = 'time', fourier_period: float | None = None, fourier_body_fixed_frame=None, fourier_relative_body=None, fourier_coefficients: ndarray | None = None, piecewise_polynomial: bool = False, ppoly_order: int | None = None, ppoly_batch_length: float | None = None, ppoly_n_batches: int | None = None, ppoly_coefficients: ndarray | None = None, ppoly_frame: str = 'inertial', ppoly_body_fixed_frame=None, ppoly_relative_body=None, polyhedral_gravity: bool = False, polyhedron_shape=None, polyhedron_faces: ndarray | None = None, polyhedron_density=None, polyhedron_gm=None, polyhedron_body_fixed_frame=None, polyhedron_scale: float = 1.0, custom_models: list | None = None)#

Bases: ForceModel

High-level translational dynamics force model.

This class aggregates and manages all translational (i.e., orbital) force contributions acting on a spacecraft — such as point-mass gravity, spherical harmonics, solar radiation pressure, and thrust — into a single, configurable interface. It acts as the physical backbone of trajectory propagation and estimation in Scarabaeus.

The total translational acceleration is the ordered sum of all active sub-models:

\[\mathbf{a}_\text{total} = \mathbf{a}_\text{grav} + \mathbf{a}_\text{3b} + \mathbf{a}_\text{SRP} + \mathbf{a}_\text{thrust} + \mathbf{a}_\text{Yark} + \mathbf{a}_\text{FOGM} + \cdots\]

where each term is non-zero only when the corresponding flag is enabled at construction time.

Unlike low-level force model components (e.g., PointMassGravity, CannonballSRP), this class serves as a meta-model: it does not compute accelerations itself, but dynamically instantiates and combines sub-models according to the selected configuration flags.

Parameters:
primary_bodySpacecraft

The primary spacecraft object to which the forces are applied. Contains physical properties such as mass, area, and reflectivity.

t0EpochArray or float, optional

The initial epoch for the force model. Sub-models that are bound to a propagation leg (ephemeris caching windows, impulsive burns) use the leg’s own start epoch instead, supplied by Propagator when it binds the model. This value is kept as configured and is what anchors the batch grid of PiecewiseFirstOrderGaussMarkov and PiecewisePolynomialAcceleration, which is required for those models and must be the same epoch for every leg of a MissionSequence.

third_bodieslist of CelestialBody, optional

List of bodies to be used in computing third body accelerations. SPICE-defined body positions are queried by EphemerisCache.

cannonball_SRPbool, optional

Enable a classical cannonball solar radiation pressure model. Ignored if nplate_SRP=True.

nplate_SRPbool, optional

Enable a multi-facet (n-plate) SRP model. Takes precedence over cannonball_SRP.

polyhedral_gravitybool, optional

Enable constant-density polyhedral (shape-model) gravity for the propagation origin. Replaces the default point mass, since a shape model already carries the body’s whole field.

polyhedron_shapestr or Path or object or np.ndarray, optional

The body’s shape: a path to a Wavefront .obj or an ASCII vertex/facet table, any object exposing vertices and faces, a (vertices, faces) pair, or a vertex array paired with polyhedron_faces.

polyhedron_facesnp.ndarray, optional

Facet indices, needed only when polyhedron_shape is a bare vertex array.

polyhedron_densityfloat or ArrayWUnits, optional

Bulk density in kg/km^3. Supply this or polyhedron_gm.

polyhedron_gmfloat or ArrayWUnits, optional

Gravitational parameter in km^3/s^2; the density follows from the mesh volume.

polyhedron_body_fixed_framestr or Frame, optional

Frame the mesh is expressed in, rotated through SPICE each evaluation.

polyhedron_scalefloat, optional

Multiplier taking the shape file’s length unit to km.

sph_harmbool, optional

Enable a spherical harmonics gravity field expansion. On its own it only turns harmonics on; the fields may be named either by the singular keywords below or by sph_harm_bodies.

sph_harm_bodyCelestialBody, optional

The celestial body for which the spherical harmonics are defined. Optional when the fields are listed in sph_harm_bodies instead.

sph_harm_orderint, optional

The maximum harmonic order (m) to include.

sph_harm_cs_filestr, optional

Path to the coefficient file containing Cnm/Snm terms.

sph_harm_norm_flagbool, optional

Whether the coefficients are normalized (True) or unnormalized (False).

sph_degree_maxint, optional

The maximum spherical harmonic degree (n) to include. Default is 100.

sph_harm_bodieslist of dict, optional

Harmonic fields, for flying somewhere several bodies have one — Jupiter and its moons, say. Each entry is a dict with body, order and cs_file, optionally norm_flag (default True) and degree_max (default 100). List every field here, central body included, and leave the singular keywords out:

sph_harm=True,
sph_harm_bodies=[
    {"body": jupiter, "order": 8, "cs_file": jup_cs},
    {"body": io,      "order": 2, "cs_file": io_cs},
]

A field named by the singular keywords is simply the first field, so the two spellings compose and an existing single-field model can gain a second body without its first being rewritten. One field per body: two fields for the same body would count that body’s gravity twice and are refused. Each field’s Cnm/Snm, GM and pole partials are keyed by its own body, so several fields can be estimated at once.

finite_burnbool, optional

Enable continuous-thrust (finite burn) modeling.

maneuverManeuver, optional

Maneuver definition object for finite-burn or impulsive dynamics.

yarkovsky_effectbool, optional

Enable Yarkovsky effect modeling.

thermal_radiationbool, optional

Enable the recoil of the heat the spacecraft radiates, scaled by the estimable eta_thermal. Requires thermal_model.

thermal_modeldict or str, optional

Temperature tables and radiating surfaces, or the path of a JSON file holding them; see ThermalRadiation.

antenna_radiation_pressurebool, optional

Enable the recoil of the power the spacecraft transmits (radio antennas, LIDAR), scaled by the estimable eta_antenna. Requires antenna_emitters.

antenna_emitterslist of dict, optional

The emitters; see AntennaRadiationPressure.

piecewise_polynomialbool, optional

Enable a deterministic empirical acceleration that is a polynomial in time over each batch of a fixed grid anchored at t0; see PiecewisePolynomialAcceleration. Its coefficients are estimated through a static a_ppoly state entry. May be combined with the Gauss-Markov and Fourier models.

ppoly_orderint, optional

Polynomial order within a batch, required when piecewise_polynomial is on: 0 for a zero-order hold (one constant acceleration per batch, 3 * ppoly_n_batches coefficients) or 1 for a first-order hold (linear per batch and continuous across batches, 3 * (ppoly_n_batches + 1) node values).

ppoly_batch_lengthfloat, optional

Duration of each batch, in seconds.

ppoly_n_batchesint, optional

Number of batches.

ppoly_coefficientsnp.ndarray, optional

Coefficients applied when the state carries no a_ppoly entry, to use the model as a known force without estimating it.

fogm_frame, pfogm_frame, ppoly_framestr, optional

Frame the components of the first-order Gauss-Markov, piecewise Gauss-Markov and piecewise polynomial accelerations are expressed in, as fourier_frame is for the Fourier one: "inertial" (the propagation frame, the default), "RTN" (radial / along-track / cross-track, the RTN triad) or "body_fixed".

fogm_body_fixed_frame, pfogm_body_fixed_frame, ppoly_body_fixed_framestr or Frame, optional

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

fogm_relative_body, pfogm_relative_body, ppoly_relative_bodystr or Body, optional

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

custom_modelslist of CustomDynamicModel, optional

User-defined force models built in a script. Their accelerations are summed with the built-in ones, and the CustomParameter objects they declare are propagated, differentiated, and estimated like any built-in solve-for parameter — so a new force needs no change to the library source.

Attributes:
custom_models

User-defined force models keyed by name, in declaration order.

dynamics_mode_list

Ordered list of active force model names (strings) built during construction.

fogm_beta

Time-correlation coefficient(s) for the first-order Gauss-Markov model.

fogm_frame

Frame the first-order Gauss-Markov components are expressed in.

fourier_angle

Phase angle driving the Fourier series.

fourier_degree

Highest harmonic of the Fourier empirical acceleration.

fourier_frame

Frame the Fourier coefficients are expressed in.

fourier_period

Repeat period of a time-based Fourier phase, in seconds.

maneuver

Maneuver definition used by the finite-burn sub-model, or None.

pfogm_batch_length

Duration of each piecewise FOGM batch in seconds.

pfogm_beta

Time-correlation coefficient(s) for the piecewise first-order Gauss-Markov model.

pfogm_frame

Frame the piecewise FOGM batch components are expressed in.

pfogm_n_batches

Number of batches in the piecewise FOGM model.

ppoly_batch_length

Duration of one batch of the piecewise polynomial acceleration, in seconds.

ppoly_frame

Frame the piecewise polynomial coefficients are expressed in.

ppoly_n_batches

Number of batches of the piecewise polynomial acceleration.

ppoly_order

Polynomial order of the piecewise polynomial acceleration (0 or 1).

primary_body

Primary spacecraft object to which all forces are applied.

sph_degree_max

Maximum harmonic degree (n) included in the expansion.

sph_harm_body

Central body for which spherical harmonics are defined, or None.

sph_harm_cs_file

Path to the Cnm/Snm coefficient file, or None when SH is inactive.

sph_harm_norm_flag

True if coefficients are normalized; False for unnormalized.

sph_harm_order

Maximum harmonic order (m) used in the spherical harmonics model.

third_bodies

List of point-mass bodies included in third-body gravity, or None.

Methods

from_dict(data, primary_body[, t0])

Reconstruct a ForceModelTranslation from to_dict().

list_forces()

Readable labels of the forces this model applies to primary_body.

load(filepath[, primary_body, fmt])

Reconstruct a ForceModelTranslation from a file written by save().

save(filepath[, fmt])

Save this force model's configuration to a JSON or pickle file.

to_dict()

Serialize the force-model configuration to a JSON-friendly dict.

See also

scarabaeus.ForceModel

Abstract parent class defining the shared interface.

scarabaeus.ForceModelRotation

Rotational placeholder (attitude dynamics stub).

scarabaeus.PointMassGravity

Single-body Newtonian gravity.

scarabaeus.SphericalHarmonicsGravity

Gravity field expansion model.

scarabaeus.CannonballSRP

Cannonball solar radiation pressure model.

scarabaeus.nPlateSRP

Multi-plate solar radiation pressure model.

scarabaeus.ThermalRadiation

Thermal re-radiation recoil.

scarabaeus.AntennaRadiationPressure

Antenna and LIDAR recoil.

scarabaeus.FiniteBurn

Continuous finite-duration thrust model.

scarabaeus.ImpulsiveBurn

Instantaneous delta-v model.

scarabaeus.PiecewisePolynomialAcceleration

Piecewise-in-time empirical acceleration.

scarabaeus.CustomDynamicModel

User-defined force model added from a script.

Notes

The constructor defines which physical models are active and stores all metadata (files, degrees, body references, etc.) needed for later use. Actual sub-model objects are not built until initialize_force_models() is called, which binds the model to a specific StateArray, reference frame, and epoch.

When both SRP flags are False, SRP effects are excluded entirely. If spherical harmonics are not activated, a baseline point-mass gravity model is always included.

Examples

Create a force model with third body perturbations.

>>> import scarabaeus as scb
>>> sc = scb.Spacecraft('EXAMPLE SC', -123)     # example spacecraft
>>> sun, venus, moon, mars = scb.CelestialBody.from_constants(['sun', 'venus', 'moon', 'mars'])
>>> third_bodies = [sun, venus, moon, mars.barycenter()]
>>> fm = scb.ForceModelTranslation(primary_body = sc, third_bodies = third_bodies)

Add a user-defined force with its own estimated parameter, without touching the library source.

>>> k = scb.CustomParameter("thermal_k", default=1.0)
>>> def thermal(position, params):
...     r = np.linalg.norm(position)
...     return params["thermal_k"][0] * 1e-12 * position / r
>>> fm = scb.ForceModelTranslation(
...     primary_body = sc,
...     custom_models = [scb.CustomDynamicModel("Thermal", thermal, parameters=[k])],
... )
classmethod from_dict(data: dict, primary_body, t0=None) → ForceModelTranslation#

Reconstruct a ForceModelTranslation from to_dict().

Parameters:
datadict

Serialized force-model config.

primary_bodySpacecraft

The body this model acts on (owned by the Propagator).

t0EpochArray or float, optional

Configured epoch. Defaults to None, which uses the one recorded in data.

Returns:
ForceModelTranslation

The rebuilt model, not yet initialized (see initialize_force_models()).

Warns:
UserWarning

For each part of the configuration that cannot be rebuilt from the file and is left out: a finite-burn maneuver, smoothed impulsive maneuvers, custom models, or a polyhedral gravity model whose shape was not recorded.

classmethod load(filepath, primary_body=None, fmt: str = None) → ForceModelTranslation#

Reconstruct a ForceModelTranslation from a file written by save().

Parameters:
filepathstr or Path

File written by save().

primary_bodySpacecraft, optional

Body the model acts on. Pass the spacecraft that owns your state components so the model and the state share one instance. Defaults to None, which rebuilds a new one from the file.

fmt{“json”, “pickle”}, optional

Input format. Defaults to None, which infers it from the file extension.

Returns:
ForceModelTranslation

The rebuilt model, not yet initialized.

Raises:
NotAForceModelFileError

If the file was not written by this class’s save(), for example a Propagator file.

UnknownSerializationFormatError

If fmt is neither "json" nor "pickle".

list_forces() → list[str]#

Readable labels of the forces this model applies to primary_body.

One label per entry of dynamics_mode_list, in that order. A label is the sub-model’s class name followed, in parentheses, by what tells one configuration of that model from another: the origin of the point-mass term, the bodies the third-body term attracts with, the field body and truncation of a spherical-harmonics term, the name of a custom model, and so on.

Returns:
list of str

For example ['ThreeBodyGravity(SUN, MOON)', 'CannonballSRP', 'PointMassGravity(EARTH)'].

See also

scarabaeus.Propagator.list_forces

The same listing for every integrated object.

scarabaeus.MissionSequence.list_forces

The same listing, leg by leg.

Notes

Before initialize_force_models() has run (i.e. before the model is handed to a Propagator) the labels describe the configuration as passed to the constructor; details that only the propagation fixes, such as the origin, are left out. Once bound, the labels come from the live sub-models and can differ from the configuration:

  • PointMassGravity is added at binding when spherical-harmonics fields are configured but none is centred on the propagation origin, so the origin keeps its monopole.

  • ThreeBodyGravity lists the bodies that actually attract: a third body that also carries a harmonics field is dropped (the field already includes its monopole), and every celestial body integrated in the state is added whether or not it was in third_bodies.

  • A spherical-harmonics truncation is clamped to the maximum degree of its coefficient file.

save(filepath, fmt: str = None) → Path#

Save this force model’s configuration to a JSON or pickle file.

The file holds to_dict() plus the primary body, so load() can rebuild the model on its own, without a Propagator.

Parameters:
filepathstr or Path

Destination file.

fmt{“json”, “pickle”}, optional

On-disk format. Defaults to None, which infers it from the file extension: .pkl or .pickle gives pickle, anything else JSON.

Returns:
Path

The resolved path written.

Raises:
UnknownSerializationFormatError

If fmt is neither "json" nor "pickle".

to_dict() → dict#

Serialize the force-model configuration to a JSON-friendly dict.

Captures the constructor options needed to rebuild this model. primary_body is intentionally omitted: it is owned by the Propagator and re-supplied to from_dict() (a file written by save() carries it alongside). t0 is the epoch the model was configured with, which anchors the PFOGM batch grid and the Fourier phase; binding to a leg does not change it. Maneuver objects and custom models cannot be serialized (both hold user callables); only their presence is recorded.

Returns:
dict

The constructor options, readable by from_dict().

property custom_models: dict#

User-defined force models keyed by name, in declaration order.

property dynamics_mode_list: list[str]#

Ordered list of active force model names (strings) built during construction.

property fogm_beta: float | None#

Time-correlation coefficient(s) for the first-order Gauss-Markov model.

property fogm_frame: str#

Frame the first-order Gauss-Markov components are expressed in.

property fourier_angle: str#

Phase angle driving the Fourier series.

property fourier_degree: int#

Highest harmonic of the Fourier empirical acceleration.

property fourier_frame: str#

Frame the Fourier coefficients are expressed in.

property fourier_period: float | None#

Repeat period of a time-based Fourier phase, in seconds.

property maneuver: Maneuver | None#

Maneuver definition used by the finite-burn sub-model, or None.

property pfogm_batch_length: float | None#

Duration of each piecewise FOGM batch in seconds.

property pfogm_beta: float | None#

Time-correlation coefficient(s) for the piecewise first-order Gauss-Markov model.

property pfogm_frame: str#

Frame the piecewise FOGM batch components are expressed in.

property pfogm_n_batches: int | None#

Number of batches in the piecewise FOGM model.

property ppoly_batch_length: float | None#

Duration of one batch of the piecewise polynomial acceleration, in seconds.

property ppoly_frame: str#

Frame the piecewise polynomial coefficients are expressed in.

property ppoly_n_batches: int | None#

Number of batches of the piecewise polynomial acceleration.

property ppoly_order: int | None#

Polynomial order of the piecewise polynomial acceleration (0 or 1).

property primary_body: Spacecraft#

Primary spacecraft object to which all forces are applied.

property sph_degree_max: int#

Maximum harmonic degree (n) included in the expansion.

property sph_harm_body: CelestialBody | None#

Central body for which spherical harmonics are defined, or None.

property sph_harm_cs_file: str | None#

Path to the Cnm/Snm coefficient file, or None when SH is inactive.

property sph_harm_norm_flag: bool#

True if coefficients are normalized; False for unnormalized.

property sph_harm_order: int#

Maximum harmonic order (m) used in the spherical harmonics model.

property third_bodies: list[str]#

List of point-mass bodies included in third-body gravity, or None.

exception CustomModelTypeError#

Bases: TypeError

Raised when custom_models holds something other than a CustomDynamicModel.

exception DuplicateCustomDynamicsError#

Bases: ValueError

Raised when two custom models define the dynamics of the same parameter.

exception DuplicateCustomModelError#

Bases: ValueError

Raised when two active force models share the same name.

exception MissingBatchEpochError#

Bases: ValueError

Raised when a batch-grid model (piecewise Gauss-Markov or piecewise polynomial) is requested without a t0.

exception MissingEmissionModelError#

Bases: ValueError

Raised when thermal or antenna recoil is enabled without its thermal_model or antenna_emitters.

exception NotAForceModelFileError#

Bases: ValueError

Raised by load() when the file was not written by save().

exception SelfGravityError#

Bases: ValueError

A force model was asked for a body’s acceleration under its own gravity field.

Raised when sph_harm_body names the same body as primary_body: the harmonic expansion would be evaluated at zero separation, and the physical answer — a body exerts no net force on itself — is not what that configuration computes.

exception SphericalHarmonicsSpecError#

Bases: ValueError

A spherical-harmonics field is missing a setting or names a body that another field already covers.

exception ThirdBodyTypeError#

Bases: TypeError

Raised when third_bodies holds anything but a CelestialBody.

exception UnknownThirdBodyError#

Bases: Exception

A third body was named but could not be resolved.

Raised by _coerce_third_bodies() when an entry of third_bodies is a name that Scarabaeus’ constants library does not define, or a type that is neither a name nor a CelestialBody.