GitHub

API Reference

This page provides a comprehensive reference for the AstroForceModels.jl API. All force models implement the common acceleration interface and can be combined to create comprehensive orbital dynamics simulations.

Core Interface

acceleration Function

The primary interface for all force models:

AstroForceModels.acceleration — Function
acceleration(u::AbstractVector, p::ComponentVector, t::Number, drag_model::DragAstroModel)

Computes the drag acceleration acting on a spacecraft given a drag model and current state and parameters of an object.

Arguments

  • u::AbstractVector: Current State of the simulation.
  • p::ComponentVector: Current parameters of the simulation.
  • t::Number: Current time of the simulation.
  • drag_model::DragAstroModel: Drag model struct containing the relevant information to compute the acceleration.

Returns

  • acceleration: SVector{3}: The 3-dimensional drag acceleration acting on the spacecraft.
source
acceleration(u::AbstractVector, p::ComponentVector, t::Number, third_body_model::ThirdBodyModel)

Computes the third-body gravitational acceleration acting on a spacecraft given a third body model and current state and parameters of an object.

Arguments

  • u::AbstractVector: Current State of the simulation.
  • p::ComponentVector: Current parameters of the simulation.
  • t::Number: Current time of the simulation.
  • third_body_model::ThirdBodyModel: Third body model struct containing the relevant information to compute the acceleration.

Returns

  • acceleration: SVector{3}: The 3-dimensional third-body acceleration acting on the spacecraft.
source
acceleration(u::AbstractVector, p::ComponentVector, t::Number, relativity_model::RelativityModel)

Computes the relativistic acceleration acting on a spacecraft given a relativity model and current state and parameters of an object.

Arguments

  • u::AbstractVector: Current State of the simulation.
  • p::ComponentVector: Current parameters of the simulation.
  • t::Number: Current time of the simulation.
  • relativity_model::RelativityModel: Relativity model struct containing the relevant information to compute the acceleration.

Returns

  • acceleration: SVector{3}: The 3-dimensional relativity acceleration acting on the spacecraft.
source
acceleration(u::AbstractVector, p::ComponentVector, t::Number, srp_model::SRPAstroModel)

Computes the srp acceleration acting on a spacecraft given a srp model and current state and parameters of an object.

Arguments

  • u::AbstractVector: Current State of the simulation.
  • p::ComponentVector: Current parameters of the simulation.
  • t::Number: Current time of the simulation.
  • srp_model::SRPAstroModel: SRP model struct containing the relevant information to compute the acceleration.

Returns

  • acceleration: SVector{3}: The 3-dimensional srp acceleration acting on the spacecraft.
source
acceleration(u::AbstractVector, p::ComponentVector, t::Number, albedo_model::AlbedoAstroModel)

Computes the albedo acceleration acting on a spacecraft given an albedo model and current state and parameters of an object.

Arguments

  • u::AbstractVector: Current State of the simulation.
  • p::ComponentVector: Current parameters of the simulation.
  • t::Number: Current time of the simulation.
  • albedo_model::AlbedoAstroModel: Albedo model struct containing the relevant information to compute the acceleration.

Returns

  • acceleration: SVector{3}: The 3-dimensional albedo acceleration acting on the spacecraft.
source
acceleration(u, p, t, model::SolidBodyTidesModel) -> SVector{3}

Compute the solid body tides acceleration perturbation on a satellite.

Arguments

  • u::AbstractVector: Spacecraft state [rx, ry, rz, vx, vy, vz] in km and km/s (J2000 ECI).
  • p::ComponentVector: Simulation parameters (must contain JD).
  • t::Number: Elapsed time since epoch [s].
  • model::SolidBodyTidesModel: Solid body tides model configuration.

Returns

  • SVector{3}: Acceleration perturbation [km/s²] in J2000 ECI.
source
acceleration(u::AbstractVector, p::ComponentVector, t::Number, model::ThermalEmissionAstroModel)

Compute the acceleration from spacecraft thermal emission given a thermal model and the current state and parameters of the spacecraft.

Arguments

  • u::AbstractVector: Current state of the simulation [km, km/s].
  • p::ComponentVector: Current parameters of the simulation.
  • t::Number: Current time of the simulation [s].
  • model::ThermalEmissionAstroModel: Thermal emission model.

Returns

  • SVector{3}: The 3-dimensional thermal emission acceleration [km/s²].
source
acceleration(u::AbstractVector, p::ComponentVector, t::Number, model::MagneticFieldAstroModel)

Compute the geomagnetic Lorentz force acceleration on a charged spacecraft.

Arguments

  • u::AbstractVector: Current state [rx, ry, rz, vx, vy, vz] in km and km/s (J2000).
  • p::ComponentVector: Parameters including JD (Julian Date at epoch).
  • t::Number: Elapsed time since epoch [s].
  • model::MagneticFieldAstroModel: Magnetic field force model configuration.

Returns

  • SVector{3}: Lorentz force acceleration [km/s²] in J2000 frame.
source
acceleration(u::AbstractVector, p::ComponentVector, t::Number, grav_model::GravityHarmonicsAstroModel)

Computes the gravitational acceleration acting on a spacecraft given a gravity model and current state and parameters of an object.

Arguments

  • u::AbstractVector: Current State of the simulation.
  • p::ComponentVector: Current parameters of the simulation.
  • t::Number: Current time of the simulation.
  • gravity_model::GravityHarmonicsAstroModel: Gravity model struct containing the relevant information to compute the acceleration.

Returns

  • acceleration: SVector{3}: The 3-dimensional gravity acceleration acting on the spacecraft.
source
acceleration(u::AbstractVector, p::ComponentVector, t::Number, grav_model::KeplerianGravityAstroModel)

Computes the gravitational acceleration acting on a spacecraft given a gravity model and current state and parameters of an object.

Arguments

  • u::AbstractVector: Current State of the simulation.
  • p::ComponentVector: Current parameters of the simulation.
  • t::Number: Current time of the simulation.
  • gravity_model::KeplerianGravityAstroModel: Gravity model struct containing the relevant information to compute the acceleration.

Returns

  • acceleration: SVector{3}: The 3-dimensional gravity acceleration acting on the spacecraft.
source
acceleration(u, p, t, model::PlasmaDragAstroModel) -> SVector{3}

Compute the plasma drag acceleration on a spacecraft.

Arguments

  • u::AbstractVector: State vector [r; v] in J2000 ECI [km; km/s].
  • p::ComponentVector: Parameters; must include p.JD (Julian Date at epoch).
  • t::Number: Elapsed time since epoch [s].
  • model::PlasmaDragAstroModel: Plasma drag force model.

Returns

  • SVector{3}: Plasma drag acceleration in J2000 ECI [km/s²].
source
acceleration(u::AbstractVector, p::ComponentVector, t::Number, lt_model::LowThrustAstroModel)

Computes the low-thrust acceleration acting on a spacecraft in the inertial frame.

The thrust model first produces a 3-component acceleration in the model's reference frame, which is then transformed to the inertial frame using transform_to_inertial.

Arguments

  • u::AbstractVector: Current state of the simulation [x, y, z, vx, vy, vz] in km and km/s.
  • p::ComponentVector: Current parameters of the simulation.
  • t::Number: Current time of the simulation [s].
  • lt_model::LowThrustAstroModel: Low-thrust model containing the thrust configuration.

Returns

  • SVector{3}: The 3-dimensional thrust acceleration in the inertial frame [km/s²].
source

Abstract Types

AstroForceModels defines a hierarchy of abstract types to organize different force models:

  • AbstractAstroForceModel: Base type for all force models
  • AbstractNonPotentialBasedForce: Non-conservative forces (drag, SRP, etc.)
  • AbstractPotentialBasedForce: Conservative forces derivable from potential (gravity)
  • AbstractDynamicsModel: Base type for dynamics model combinations

Dynamics Models

The dynamics model system provides efficient ways to combine multiple force models:

AstroForceModels.build_dynamics_model — Function
build_dynamics_model(u::AbstractVector, p::ComponentVector, t::Number, models::CentralBodyDynamicsModel)

Compute the total acceleration acting on a spacecraft using a CentralBodyDynamicsModel.

This function efficiently combines the central body gravity acceleration with all perturbing accelerations to produce the total acceleration vector. It is optimized for use in ODE integration routines and provides better performance than manually summing individual force model accelerations.

Arguments

  • u::AbstractVector: Current spacecraft state vector [rx, ry, rz, vx, vy, vz] in km and km/s
  • p::ComponentVector: Simulation parameters including time references (JD), spacecraft properties, etc.
  • t::Number: Current simulation time (typically seconds since epoch)
  • models::CentralBodyDynamicsModel: Combined dynamics model containing gravity and perturbing forces

Returns

  • SVector{3}: The 3-dimensional total acceleration vector [ax, ay, az] in km/s²

Performance Notes

The function is marked @inline for performance and uses compile-time optimizations through the tuple-based storage of perturbing models. This approach provides:

  • Zero-cost abstraction over manual force summation
  • Type stability for all force combinations
  • Efficient memory access patterns

Example

# Create dynamics model
dynamics = CentralBodyDynamicsModel(gravity_model, (drag_model, srp_model))

# Compute acceleration at current state
state = [6678.137, 0.0, 0.0, 0.0, 7.66, 0.0]  # km, km/s
params = ComponentVector(JD = 2.460310e6)  # Julian Date
time = 0.0

total_accel = build_dynamics_model(state, params, time, dynamics)

See Also

source

The CentralBodyDynamicsModel type is documented in the Library section.

Usage Example

# Create individual force models
gravity_model = GravityHarmonicsAstroModel(...)
drag_model = DragAstroModel(...)
srp_model = SRPAstroModel(...)

# Combine into dynamics model
dynamics_model = CentralBodyDynamicsModel(
    gravity_model,
    (drag_model, srp_model)
)

# Use in ODE system
function dynamics!(du, u, p, t)
    du[1:3] = u[4:6]  # velocity
    du[4:6] = build_dynamics_model(u, p, t, dynamics_model)
end

Force Models

AstroForceModels provides several categories of force models:

Gravity Models

  • GravityHarmonicsAstroModel: Spherical harmonics gravity model with EGM96/EGM2008 coefficients
  • KeplerianGravityAstroModel: Simple point-mass gravity model

Atmospheric Drag Models

  • DragAstroModel: Atmospheric drag force model with various atmospheric density models
  • CannonballFixedDrag: Fixed ballistic coefficient satellite shape model

Solar Radiation Pressure Models

  • SRPAstroModel: Solar radiation pressure force model with shadow modeling
  • CannonballFixedSRP: Fixed reflectivity coefficient satellite shape model

Albedo Radiation Pressure Models

  • AlbedoAstroModel: Earth albedo radiation pressure force model with Lebedev quadrature integration
  • UniformAlbedoModel: Uniform albedo model with constant visible albedo and infrared emissivity

Third Body Models

  • ThirdBodyModel: Third body ephemeris provider (Sun, Moon, planets)

Relativistic Effects

  • RelativityModel: General relativistic effects (Schwarzschild, Lense-Thirring, de Sitter)

Solid Body Tides

  • SolidBodyTidesModel: Tidal deformation perturbation from tide-raising bodies (IERS 2010, Step 1)

Plasma Drag (Ionospheric Ion Drag)

  • PlasmaDragAstroModel: Ionospheric plasma drag force from direct ion collection (Lafleur 2023, Chapra 1961)
  • CannonballFixedPlasmaDrag: Fixed ion ballistic coefficient satellite model
  • StatePlasmaDragModel: State-dependent ion ballistic coefficient for estimation
  • ChapmanIonosphere: Chapman layer F2-region ion density model (configurable peak density, altitude, scale height)
  • ConstantIonosphere: Fixed ion density for testing and parametric studies
  • NoIonosphere: Zero ion density (disables plasma drag)

Thermal Emission

  • ThermalEmissionAstroModel: Spacecraft thermal re-radiation force from anisotropic surface emission
  • FixedThermalEmission: Fixed thermal emission coefficient model
  • FlatPlateThermalModel: Physical flat plate model with front/back emissivity, absorptivity, and efficiency

Geomagnetic Lorentz Force

  • MagneticFieldAstroModel: Lorentz force on charged spacecraft from Earth's geomagnetic field (IGRF or dipole)
  • FixedChargeMassRatio: Fixed charge-to-mass ratio model [C/kg]
  • StateChargeModel: State-dependent charge-to-mass ratio function
  • IGRFField: IGRF v14 geomagnetic field model (spherical harmonics up to degree 13)
  • DipoleMagneticField: Simplified dipole geomagnetic field model

Low-Thrust Propulsion

  • LowThrustAstroModel: Low-thrust propulsion force model with frame support
  • ConstantCartesianThrust: Fixed thrust acceleration vector (frame-dependent)
  • ConstantTangentialThrust: Constant-magnitude velocity-aligned thrust
  • StateThrustModel: User-defined state-dependent thrust profile
  • PiecewiseConstantThrust: Piecewise-constant arc-based thrust schedule

Reference Frames

  • InertialFrame: ECI/J2000 inertial frame (default)
  • RTNFrame: Radial–Transverse–Normal orbit-fixed frame
  • VNBFrame: Velocity–Normal–Binormal velocity-fixed frame

All force models implement the common acceleration(state, params, time, model) interface.

Type Definitions

Component Arrays

The package uses ComponentArrays.jl for structured parameter handling:

using ComponentArrays
using SatelliteToolboxBase

JD = date_to_jd(2024, 1, 5, 12, 0, 0.0)
p = ComponentVector(; JD=JD)

State Vectors

State vectors are typically 6-element arrays representing position and velocity:

# State vector format: [rx, ry, rz, vx, vy, vz]
state = [
    6.378137e3 + 400,    # x position [km]
    0.0,                 # y position [km]  
    0.0,                 # z position [km]
    0.0,                 # x velocity [km/s]
    7.660,               # y velocity [km/s]
    0.0                  # z velocity [km/s]
]

Integration with SatelliteToolbox.jl

AstroForceModels is designed to be built off packages in the SatelliteToolbox.jl ecosystem:

Required Dependencies

using SatelliteToolboxBase               # Base types and constants
using SatelliteToolboxGravityModels      # Gravity field models
using SatelliteToolboxAtmosphericModels  # Atmospheric density models
using SatelliteToolboxCelestialBodies    # Celestial body ephemeris
using SatelliteToolboxGeomagneticField   # Geomagnetic field models (IGRF, dipole)
using SatelliteToolboxTransformations    # Coordinate transformations

Earth Orientation Parameters

# Fetch latest EOP data
eop_data = fetch_iers_eop()

# Use with force models
gravity_model = GravityHarmonicsAstroModel(
    gravity_model = GravityModels.load(IcgemFile, fetch_icgem_file(:EGM96)),
    eop_data = eop_data,
    order = 20,
    degree = 20
)

Examples and Tutorials

For practical examples and step-by-step tutorials, see:

  • Usage Guide: Comprehensive usage examples
  • Test suite: Working examples in the /test directory
  • Benchmarks: Performance comparisons in the /benchmark directory