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:
ForceModelHigh-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
Propagatorwhen it binds the model. This value is kept as configured and is what anchors the batch grid ofPiecewiseFirstOrderGaussMarkovandPiecewisePolynomialAcceleration, which is required for those models and must be the same epoch for every leg of aMissionSequence.- 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
.objor an ASCII vertex/facet table, any object exposingverticesandfaces, a(vertices, faces)pair, or a vertex array paired withpolyhedron_faces.- polyhedron_facesnp.ndarray, optional
Facet indices, needed only when
polyhedron_shapeis 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_bodiesinstead.- 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,orderandcs_file, optionallynorm_flag(default True) anddegree_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. Requiresthermal_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. Requiresantenna_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; seePiecewisePolynomialAcceleration. Its coefficients are estimated through a statica_ppolystate entry. May be combined with the Gauss-Markov and Fourier models.- ppoly_orderint, optional
Polynomial order within a batch, required when
piecewise_polynomialis on:0for a zero-order hold (one constant acceleration per batch,3 * ppoly_n_batchescoefficients) or1for 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_ppolyentry, 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_frameis 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
CustomParameterobjects 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_modelsUser-defined force models keyed by name, in declaration order.
dynamics_mode_listOrdered list of active force model names (strings) built during construction.
fogm_betaTime-correlation coefficient(s) for the first-order Gauss-Markov model.
fogm_frameFrame the first-order Gauss-Markov components are expressed in.
fourier_anglePhase angle driving the Fourier series.
fourier_degreeHighest harmonic of the Fourier empirical acceleration.
fourier_frameFrame the Fourier coefficients are expressed in.
fourier_periodRepeat period of a time-based Fourier phase, in seconds.
maneuverManeuver definition used by the finite-burn sub-model, or
None.pfogm_batch_lengthDuration of each piecewise FOGM batch in seconds.
pfogm_betaTime-correlation coefficient(s) for the piecewise first-order Gauss-Markov model.
pfogm_frameFrame the piecewise FOGM batch components are expressed in.
pfogm_n_batchesNumber of batches in the piecewise FOGM model.
ppoly_batch_lengthDuration of one batch of the piecewise polynomial acceleration, in seconds.
ppoly_frameFrame the piecewise polynomial coefficients are expressed in.
ppoly_n_batchesNumber of batches of the piecewise polynomial acceleration.
ppoly_orderPolynomial order of the piecewise polynomial acceleration (0 or 1).
primary_bodyPrimary spacecraft object to which all forces are applied.
sph_degree_maxMaximum harmonic degree (n) included in the expansion.
sph_harm_bodyCentral body for which spherical harmonics are defined, or
None.sph_harm_cs_filePath to the Cnm/Snm coefficient file, or
Nonewhen SH is inactive.sph_harm_norm_flagTrueif coefficients are normalized;Falsefor unnormalized.sph_harm_orderMaximum harmonic order (m) used in the spherical harmonics model.
third_bodiesList of point-mass bodies included in third-body gravity, or
None.
Methods
from_dict(data, primary_body[, t0])Reconstruct a ForceModelTranslation from
to_dict().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.ForceModelAbstract parent class defining the shared interface.
scarabaeus.ForceModelRotationRotational placeholder (attitude dynamics stub).
scarabaeus.PointMassGravitySingle-body Newtonian gravity.
scarabaeus.SphericalHarmonicsGravityGravity field expansion model.
scarabaeus.CannonballSRPCannonball solar radiation pressure model.
scarabaeus.nPlateSRPMulti-plate solar radiation pressure model.
scarabaeus.ThermalRadiationThermal re-radiation recoil.
scarabaeus.AntennaRadiationPressureAntenna and LIDAR recoil.
scarabaeus.FiniteBurnContinuous finite-duration thrust model.
scarabaeus.ImpulsiveBurnInstantaneous delta-v model.
scarabaeus.PiecewisePolynomialAccelerationPiecewise-in-time empirical acceleration.
scarabaeus.CustomDynamicModelUser-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 specificStateArray, 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 indata.
- 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
fmtis 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_forcesThe same listing for every integrated object.
scarabaeus.MissionSequence.list_forcesThe same listing, leg by leg.
Notes
Before
initialize_force_models()has run (i.e. before the model is handed to aPropagator) 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:PointMassGravityis added at binding when spherical-harmonics fields are configured but none is centred on the propagation origin, so the origin keeps its monopole.ThreeBodyGravitylists 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 inthird_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, soload()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:.pklor.picklegives pickle, anything else JSON.
- Returns:
- Path
The resolved path written.
- Raises:
- UnknownSerializationFormatError
If
fmtis 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_bodyis intentionally omitted: it is owned by the Propagator and re-supplied tofrom_dict()(a file written bysave()carries it alongside).t0is 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 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 pfogm_beta: float | None#
Time-correlation coefficient(s) for the piecewise first-order Gauss-Markov model.
- property ppoly_batch_length: float | None#
Duration of one batch of the piecewise polynomial acceleration, in seconds.
- 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_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
Nonewhen SH is inactive.
- property third_bodies: list[str]#
List of point-mass bodies included in third-body gravity, or
None.
- exception CustomModelTypeError#
Bases:
TypeErrorRaised when
custom_modelsholds something other than a CustomDynamicModel.
- exception DuplicateCustomDynamicsError#
Bases:
ValueErrorRaised when two custom models define the dynamics of the same parameter.
- exception DuplicateCustomModelError#
Bases:
ValueErrorRaised when two active force models share the same name.
- exception MissingBatchEpochError#
Bases:
ValueErrorRaised when a batch-grid model (piecewise Gauss-Markov or piecewise polynomial) is requested without a
t0.
- exception MissingEmissionModelError#
Bases:
ValueErrorRaised when thermal or antenna recoil is enabled without its
thermal_modelorantenna_emitters.
- exception NotAForceModelFileError#
Bases:
ValueErrorRaised by
load()when the file was not written bysave().
- exception SelfGravityError#
Bases:
ValueErrorA force model was asked for a body’s acceleration under its own gravity field.
Raised when
sph_harm_bodynames the same body asprimary_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:
ValueErrorA spherical-harmonics field is missing a setting or names a body that another field already covers.
- exception ThirdBodyTypeError#
Bases:
TypeErrorRaised when
third_bodiesholds anything but a CelestialBody.
- exception UnknownThirdBodyError#
Bases:
ExceptionA third body was named but could not be resolved.
Raised by
_coerce_third_bodies()when an entry ofthird_bodiesis a name that Scarabaeus’ constants library does not define, or a type that is neither a name nor aCelestialBody.