4. ForceModel#

class ForceModel(dynamics_mode_list: list, state_vector: StateArray, point_masses: list, main_spacecraft: Spacecraft, sph_harm_order: int, sph_harm_cs_file: str, sph_harm_body: CelestialBody, sph_harm_norm_flag: bool, sph_degree_max: int, approx_dv_flag: bool, t0: EpochArray, base_frame: Frame)#

Bases: object

Computes all the accelerations and acceleration partials based on selected dynamics.

Integrates various force models, including point-mass gravity, spherical harmonics gravity, third-body gravity, solar radiation pressure, and thrust-related dynamics. Used for orbital propagation and state estimation.

Parameters:

  • dynamics_mode_list (list[str]) –

    List of dynamics models to initialize. Supported models:

    • 'PointMassGravity'

    • 'ThreeBodyGravity'

    • 'SphericalHarmonicsGravity'

    • 'CannonballSRP'

    • 'nPlateSRP'

    • 'FiniteBurn'

    • 'ImpulsiveBurn'

  • state_vector (StateArray) – The state vector of the main spacecraft, containing all dynamic and static parameters considered in the simulation (position, velocity, estimated parameters), the reference frame in which the state is defined, the origin body relative to which the state is expressed, and the epoch corresponding to the state.

  • point_masses (list[str]) – List of point masses considered for gravitational calculations.

  • main_spacecraft (Spacecraft) – The main spacecraft object containing mass, area, and other physical properties.

  • sph_harm_order (int) – The order of spherical harmonics for gravity modeling.

  • sph_harm_cs_file (str) – File path to the spherical harmonics coefficient data.

  • sph_harm_body (Body) – The celestial body for which spherical harmonics are calculated.

  • sph_harm_norm_flag (bool) – Flag indicating whether to normalize spherical harmonics.

  • sph_degree_max (int) – The maximum degree for spherical harmonics calculations.

  • approx_dv_flag (bool) – Flag indicating whether to approximate delta-v for impulsive burns.

  • t0 (EpochArray) – The initial epoch of the simulation.

  • base_frame (Frame) – The frame in which the propagation happens.

See also

scarabaeus.DynamicModel

Base class for dynamic models.

Notes

Dynamically initializes only the requested force models.

Each force model computes its own acceleration and partial derivatives.

References

Vallado, D. A. (2013). Fundamentals of Astrodynamics and Applications, 4th Ed.

Attributes

approx_dv_flag

Flag indicating whether to approximate delta-v for impulsive burns.

dynamics_mode_list

List of active dynamics models.

force_models

Dictionary of initialized force models.

main_spacecraft

The main spacecraft which forces are applied to.

point_masses

Point masses considered for gravitational calculations.

sph_degree_max

The maximum degree for spherical harmonics calculations.

sph_harm_body

The celestial body for which spherical harmonics are calculated.

sph_harm_cs_file

File path to the spherical harmonics coefficient data.

sph_harm_norm_flag

Flag indicating whether to normalize spherical harmonics.

sph_harm_order

The order of spherical harmonics for gravity modeling.

state_vector

The state vector of the main spacecraft.

t0

The initial epoch of the simulation.

Methods

collect_parameter_dynamics(name, position, ...)

Retrieves the dynamic equation associated with a specified parameter.

collect_partials(name, position, ...)

Retrieves the function computing the partial derivative of a specified dynamic parameter.

compute_acceleration_partial_by_dv(position, ...)

Computes the partial derivative of acceleration with respect to the applied delta-v.

compute_acceleration_partial_by_eta(...)

Computes the partial derivative of acceleration with respect to the solar radiation pressure (SRP) scale factor.

compute_total_acceleration(position, ...)

Computes the total acceleration from all selected dynamical models.

compute_total_acceleration_partial(position, ...)

Computes the total acceleration Jacobian with respect to position.

compute_total_velocity_partial(position, ...)

Computes the Jacobian of velocity with respect to itself.
collect_parameter_dynamics(name: str, position: ArrayWUnits, current_state: dict, epoch: float, body: CelestialBody)#

Retrieves the dynamic equation associated with a specified parameter.

Acts as a lookup for the governing equations of various dynamic parameters, returning the appropriate function based on the provided name.

Parameters:

  • name (str) – The name of the dynamic parameter.

  • position (ArrayWUnits) – 3x1 vector describing the position of the affected object. Expressed in units of kilometers.

  • current_state (dict) – Dictionary containing the current state parameters.

  • epoch (float) – Current simulation epoch.

  • body (CelestialBody) – The celestial body influencing the dynamics.

Returns:

param_dynamics – The function defining the parameter’s dynamics, or raises an error if not found.

Return type:

Callable

collect_partials(name: str, position: ArrayWUnits, current_state: dict, epoch, body)#

Retrieves the function computing the partial derivative of a specified dynamic parameter.

Provides a mapping between parameter names and their corresponding derivative computation functions.

Parameters:

  • name (str) – The key representing the desired partial derivative computation.

  • position (ArrayWUnits) – 3x1 vector describing the position of the affected object. Expressed in units of kilometers.

  • current_state (dict) – Dictionary containing the current state parameters.

  • epoch (float) – Current simulation epoch.

  • body (CelestialBody) – The celestial body influencing the dynamics.

Returns:

partials – The function computing the partial derivative if found, otherwise None.

Return type:

Callable or None

compute_acceleration_partial_by_dv(position: ArrayWUnits, current_state: dict, epoch, body) → ArrayWUnits#

Computes the partial derivative of acceleration with respect to the applied delta-v.

Relevant for impulsive maneuvers where the spacecraft undergoes a sudden change in velocity.

Parameters:

  • position (ArrayWUnits) – 3x1 vector describing the position of the spacecraft. Expressed in units of kilometers.

  • current_state (dict) – Dictionary containing the current state parameters.

  • epoch (float) – Current simulation epoch.

  • body (CelestialBody) – The celestial body influencing the dynamics.

Returns:

partial_by_dv – The 3x3 partial derivative of acceleration with respect to delta-v. Expressed in units of \(\frac{1}{s}\).

Return type:

ArrayWUnits

compute_acceleration_partial_by_eta(position: ArrayWUnits, current_state: dict, epoch, body) → ArrayWUnits#

Computes the partial derivative of acceleration with respect to the solar radiation pressure (SRP) scale factor.

Accounts for different SRP models (cannonball or n-plate) and returns the corresponding derivative.

Parameters:

  • position (ArrayWUnits) – 3x1 vector describing the position of the spacecraft. Expressed in units of kilometers.

  • current_state (dict) – Dictionary containing the current state parameters.

  • epoch (float) – Current simulation epoch.

  • body (CelestialBody) – The celestial body influencing the dynamics.

Returns:

partial_by_eta – The 3x3 partial derivative of acceleration with respect to SRP. Expressed in units of \(\frac{km}{s^2}\).

Return type:

ArrayWUnits

compute_total_acceleration(position: ArrayWUnits, current_state: dict, epoch: float, body: CelestialBody) → ArrayWUnits#

Computes the total acceleration from all selected dynamical models.

Iterates through the active force models and computes the cumulative acceleration acting on the spacecraft.

Parameters:

  • position (ArrayWUnits) – 3x1 vector describing the position of the spacecraft. Expressed in units of kilometers.

  • current_state (dict) – Dictionary containing the current state parameters.

  • epoch (float) – Current simulation epoch.

  • body (CelestialBody) – The celestial body influencing the dynamics.

Returns:

acc_vec – 3x1 vector describing the total acceleration of the spacecraft. Expressed in units of \(\frac{km}{s^2}\).

Return type:

ArrayWUnits

compute_total_acceleration_partial(position: ArrayWUnits, current_state: dict, epoch, body) → ArrayWUnits#

Computes the total acceleration Jacobian with respect to position.

Sums the contributions of all active force models to determine how the acceleration changes with respect to position.

Parameters:

  • position (ArrayWUnits) – 3x1 vector describing the position of the spacecraft. Expressed in units of kilometers.

  • current_state (dict) – Dictionary containing the current state parameters.

  • epoch (float) – Current simulation epoch.

  • body (CelestialBody) – The celestial body influencing the dynamics.

Returns:

jacobian – The 3x3 Jacobian matrix of acceleration with respect to position. Expressed in units of \(\frac{1}{s^2}\).

Return type:

ArrayWUnits

compute_total_velocity_partial(position: ArrayWUnits, current_state: dict, epoch, body) → ArrayWUnits#

Computes the Jacobian of velocity with respect to itself.

Since velocity is directly mapped to itself in the state transition, the partial derivative results in an identity matrix.

Parameters:

  • position (ArrayWUnits) – 3x1 vector describing the position of the spacecraft. Expressed in units of kilometers.

  • current_state (dict) – Dictionary containing the current state parameters.

  • epoch (float) – Current simulation epoch.

  • body (CelestialBody) – The celestial body influencing the dynamics.

Returns:

vel_partial – 3x3 identity matrix representing dv/dv. Unitless.

Return type:

ArrayWUnits

property approx_dv_flag: bool#

Flag indicating whether to approximate delta-v for impulsive burns.

property dynamics_mode_list: list[str]#

List of active dynamics models.

property force_models: dict#

Dictionary of initialized force models.

property main_spacecraft: Spacecraft#

The main spacecraft which forces are applied to.

property point_masses: list[str]#

Point masses considered for gravitational calculations.

property sph_degree_max: int#

The maximum degree for spherical harmonics calculations.

property sph_harm_body: CelestialBody#

The celestial body for which spherical harmonics are calculated.

property sph_harm_cs_file: str#

File path to the spherical harmonics coefficient data.

property sph_harm_norm_flag: bool#

Flag indicating whether to normalize spherical harmonics.

property sph_harm_order: int#

The order of spherical harmonics for gravity modeling.

property state_vector: StateArray#

The state vector of the main spacecraft.

property t0: EpochArray#

The initial epoch of the simulation.