Skip to content

Dynamics API

CometOutgassingEffect(sun, estimated_params=('A1', 'A2', 'A3'), A1=0.0, A2=0.0, A3=0.0, alpha=0.1112620426, r0=2.808, m=2.15, n=5.093, k=4.6142, param_prefix='Outgassing')

Bases: RTNDistanceLawNonGravEffect

Symmetric cometary outgassing effect expressed in the heliocentric RTN frame.

Initialize the symmetric comet-outgassing effect.

get_estimated_param_scales()

Return characteristic scales for estimated comet outgassing parameters.

Returns:

Type Description
Float[Array, N_estimated]

Characteristic A1, A2, and A3 scales in au / day^2.

DynamicSystem()

Collection of perturbing bodies and extra forces used to build a force model.

Initialize an empty dynamic system.

from_standard_system(eph=None) classmethod

Build a dynamic system from the standard planetary set.

Parameters:

Name Type Description Default
eph Ephemeris

Ephemeris source used to build the perturbing bodies.

 None

Returns:

Type Description
DynamicSystem

System with the Sun, major planets, and the Moon. All listed bodies use the PPN gravity model.

from_extended_system(eph=None) classmethod

Build a dynamic system from the extended body set.

Parameters:

Name Type Description Default
eph Ephemeris

Ephemeris source used to build the perturbing bodies.

 None

Returns:

Type Description
DynamicSystem

Standard system plus the supported large asteroids. The extra asteroids use the Newtonian gravity model.

add_body(body, use_ppn=False)

Add one perturbing body.

Parameters:

Name Type Description Default
body EphemerisBody

Perturbing body.

 required
use_ppn bool

If True, add the body to the PPN gravity list. Otherwise, add it to the Newtonian gravity list.

 False

add_non_grav_force(force)

Add one non-gravitational force model.

Parameters:

Name Type Description Default
force Force

Force model to append.

 required

build_force_model()

Build the combined force model.

Returns:

Type Description
ForceModel

Force model assembled from the stored non-gravitational forces, Newtonian gravity bodies, and PPN gravity bodies.

EmpiricalRadiationPressure(sun, estimated_params=('A1',), A1=0.0, alpha=1.0, r0=1.0, m=2.0, n=1.0, k=0.0, param_prefix='RadiationPressure')

Bases: RTNDistanceLawNonGravEffect

Empirical solar-radiation-pressure-like effect represented by one radial RTN term.

Initialize the empirical radiation-pressure effect.

get_estimated_param_scales()

Return the characteristic scale for the estimated radial acceleration.

Returns:

Type Description
Float[Array, N_estimated]

Characteristic A1 scale in au / day^2.

EmpiricalYarkovskyEffect(sun, estimated_params=('A2',), A2=0.0, alpha=1.0, r0=1.0, m=2.0, n=1.0, k=0.0, param_prefix='Yarkovsky')

Bases: RTNDistanceLawNonGravEffect

Empirical Yarkovsky-like effect represented by one transverse RTN term.

Initialize the empirical Yarkovsky effect.

get_estimated_param_scales()

Return the characteristic scale for the estimated transverse acceleration.

Returns:

Type Description
Float[Array, N_estimated]

Characteristic A2 scale in au / day^2.

EarthJ2Perturbation(body, j2=J2_EARTH, radius=R_EARTH, max_distance=EARTH_J2_MAX_DISTANCE, fixed_pole_unit_vec=None)

Bases: Force

Terrestrial J2 perturbation with an epoch-dependent Earth pole.

By default, the pole is the ITRS z-axis transformed through polar motion, Earth rotation, and the CIRS to GCRS rotation at the requested epoch. A fixed pole can be supplied for tests or simplified sensitivity calculations.

Initialize an Earth J2 perturbation.

Parameters:

Name Type Description Default
body EphemerisBody

Earth ephemeris body that supplies the center position and gravitational parameter.

 required
j2 Float[ArrayLike, '']

Positive dimensionless terrestrial J2.

 J2_EARTH
radius Float[ArrayLike, '']

Terrestrial equatorial reference radius in au.

 R_EARTH
max_distance Float[ArrayLike, '']

Maximum geocentric distance for applying the term, in au.

 0.1
fixed_pole_unit_vec Float[ArrayLike, 3] or None

Fixed Earth pole unit vector in BCRS axes. If omitted, the pole is evaluated at each TDB epoch from ITRS through the Earth-rotation matrices.

 None

shape property

Return the batch shape.

get_current_pole(tdb_jd1, tdb_jd2)

Return the Earth pole unit vector in BCRS axes at one TDB epoch.

Parameters:

Name Type Description Default
tdb_jd1 Float[Array, '']

Two parts of the TDB Julian Date.

 required
tdb_jd2 Float[Array, '']

Two parts of the TDB Julian Date.

 required

Returns:

Type Description
Float[Array, 3]

Unit pole vector in the same axes as the propagated BCRS state.

__call__(tdb_jd1, tdb_jd2, state, args=None)

Evaluate the Earth J2 acceleration at one TDB epoch.

Parameters:

Name Type Description Default
tdb_jd1 Float[Array, '']

Two parts of the TDB Julian Date.

 required
tdb_jd2 Float[Array, '']

Two parts of the TDB Julian Date.

 required
state tuple[Float[Array, 3], Float[Array, 3]]

Integrated body state (pos, vel) in BCRS. Position is in au.

 required
args Any

Extra propagator data. This force does not use it.

 None

Returns:

Type Description
Float[Array, 3]

Earth J2 acceleration in au / day^2. It is zero outside max_distance.

Force

Bases: BatchableObject

Base class for force terms used by :class:ForceModel.

__call__(tdb_jd1, tdb_jd2, state, args) abstractmethod

Evaluate the acceleration.

Parameters:

Name Type Description Default
tdb_jd1 Float[Array, '']

Split Julian date of the TDB epoch.

 required
tdb_jd2 Float[Array, '']

Split Julian date of the TDB epoch.

 required
state tuple[Float[Array, 3], Float[Array, 3]]

Cartesian state (pos, vel) in BCRS.

 required
args Any

Extra runtime data passed by the propagator.

 required

Returns:

Type Description
Float[Array, 3]

Acceleration in au / day^2.

ForceModel(forces)

Bases: BatchableObject

Sum a list of force terms for numerical propagation.

Initialize the force model.

Parameters:

Name Type Description Default
forces list[Force]

Force terms included in the model.

 required

Raises:

Type Description
TypeError

If any force does not implement the ordinary float64 force interface.

shape property

Return the broadcast batch shape of all force terms.

__call__(tdb_offset, state, args=None)

Evaluate the total acceleration.

Parameters:

Name Type Description Default
tdb_offset float

Offset in days from the reference TDB epoch stored in args.

 required
state tuple[Float[Array, 3], Float[Array, 3]]

Cartesian state (pos, vel) in BCRS.

 required
args Any

Extra runtime data. The first two items must be (t0_jd1, t0_jd2).

 None

Returns:

Type Description
Float[Array, 3]

Total acceleration in au / day^2.

get_all_estimated_params()

Collect all estimated parameters into one array.

get_all_estimated_param_scales()

Collect all estimated parameter scales into one array.

update_estimated_params(estimated_params)

Return a new ForceModel instance with updated estimated parameters.

get_all_estimated_param_names()

Return the names of all estimated parameters.

NewtonianGravity(bodies)

Bases: Force

Point-mass gravity from a fixed list of ephemeris bodies.

Initialize the Newtonian gravity model.

Parameters:

Name Type Description Default
bodies list[EphemerisBody]

Perturbing bodies.

 required

shape property

Return the batch shape.

__call__(tdb_jd1, tdb_jd2, state, args)

Evaluate the Newtonian acceleration at one TDB epoch.

Parameters:

Name Type Description Default
tdb_jd1 Float[Array, '']

Two parts of the TDB Julian Date.

 required
tdb_jd2 Float[Array, '']

Two parts of the TDB Julian Date.

 required
state tuple[Float[Array, 3], Float[Array, 3]]

Integrated body state (pos, vel) in BCRS. Position is in au.

 required
args Any

Extra propagator data. This force does not use it.

 required

Returns:

Type Description
Float[Array, 3]

Acceleration in au / day^2.

PPNGravity(bodies)

Bases: Force

Post-Newtonian gravity from a fixed list of ephemeris bodies.

Initialize the parametrized post-Newtonian gravity model.

Parameters:

Name Type Description Default
bodies list[EphemerisBody]

Perturbing bodies.

 required
References
  1. Urban, S. E., & Seidelmann, P. K. (2012). Explanatory Supplement to the Astronomical Almanac. Sec. 8.3.1.

shape property

Return the batch shape.

__call__(tdb_jd1, tdb_jd2, state, args)

Evaluate the PPN acceleration at one TDB epoch.

Parameters:

Name Type Description Default
tdb_jd1 Float[Array, '']

Two parts of the TDB Julian Date.

 required
tdb_jd2 Float[Array, '']

Two parts of the TDB Julian Date.

 required
state tuple[Float[Array, 3], Float[Array, 3]]

Integrated body state (pos, vel) in BCRS. Position is in au and velocity is in au / day.

 required
args Any

Extra propagator data. This force does not use it.

 required

Returns:

Type Description
Float[Array, 3]

Acceleration in au / day^2.

ParametrizedForce

Bases: Force

Base class for force terms with estimable parameters used by :class:ForceModel.

n_estimated_params abstractmethod property

Number of estimable parameters.

get_estimated_params() abstractmethod

Return the current estimated parameters.

get_estimated_param_scales() abstractmethod

Return characteristic scales for the estimated parameters.

The scales are multiplicative parameter increments in the same units as :meth:get_estimated_params. Solvers can use them to normalize model parameters before forming least-squares or trust-region steps. Each concrete parametrized force must provide scales that match its estimated-parameter ordering.

Returns:

Type Description
Float[Array, N_estimated]

Characteristic scales for each estimated parameter.

update_estimated_params(new_params) abstractmethod

Return a new ParametrizedForce instance with updated estimated parameters.

get_estimated_param_names() abstractmethod

Return the names of the estimated parameters.

RTNDistanceLawNonGravEffect(sun, estimated_params=('A1', 'A2', 'A3'), A1=0.0, A2=0.0, A3=0.0, alpha=0.1112620426, r0=2.808, m=2.15, n=5.093, k=4.6142, param_prefix='NG')

Bases: ParametrizedForce

Non-gravitational acceleration in the heliocentric RTN frame.

Initialize one heliocentric RTN non-gravitational effect.

Parameters:

Name Type Description Default
sun EphemerisBody

Sun ephemeris body used to build the heliocentric relative state.

 required
estimated_params tuple[str, ...]

Names of the estimated parameters.

 ('A1', 'A2', 'A3')
A1 Float[ArrayLike, ...]

Initial radial, transverse, and normal non-gravitational parameters in au / day^2.

 0
A2 Float[ArrayLike, ...]

Initial radial, transverse, and normal non-gravitational parameters in au / day^2.

 0
A3 Float[ArrayLike, ...]

Initial radial, transverse, and normal non-gravitational parameters in au / day^2.

 0
alpha Float[ArrayLike, ...]

Parameters of the radial distance law g(r).

 0.1112620426
r0 Float[ArrayLike, ...]

Parameters of the radial distance law g(r).

 0.1112620426
m Float[ArrayLike, ...]

Parameters of the radial distance law g(r).

 0.1112620426
n Float[ArrayLike, ...]

Parameters of the radial distance law g(r).

 0.1112620426
k Float[ArrayLike, ...]

Parameters of the radial distance law g(r).

 0.1112620426
param_prefix str

Prefix used when exposing estimated-parameter names through :class:ForceModel.

 "NG"

n_estimated_params property

Return the number of estimated acceleration parameters.

shape property

Return the batch shape of the parameter arrays.

get_estimated_params()

Return the selected RTN acceleration parameters.

Returns:

Type Description
Float[Array, N_estimated]

Estimated parameters in au / day^2.

get_estimated_param_scales()

Return characteristic scales for estimated RTN acceleration parameters.

The A1, A2, and A3 parameters are accelerations in au / day^2 before radial distance-law scaling. The generic RTN model uses one conservative scale for all three components; specialized subclasses may override this with narrower model-specific values.

Returns:

Type Description
Float[Array, N_estimated]

Characteristic acceleration scales in au / day^2.

update_estimated_params(new_params)

Return a copy with new estimated acceleration parameters.

Parameters:

Name Type Description Default
new_params Float[Array, N_estimated]

New values for the selected RTN parameters, in au / day^2.

 required

Returns:

Type Description
RTNDistanceLawNonGravEffect

Force with updated parameters.

get_estimated_param_names()

Return the names of the selected RTN parameters.

__call__(tdb_jd1, tdb_jd2, state, args=None)

Evaluate the non-gravitational acceleration at one TDB epoch.

Parameters:

Name Type Description Default
tdb_jd1 Float[Array, '']

Two parts of the TDB Julian Date.

 required
tdb_jd2 Float[Array, '']

Two parts of the TDB Julian Date.

 required
state tuple[Float[Array, 3], Float[Array, 3]]

Integrated body state (pos, vel) in BCRS. Position is in au and velocity is in au / day.

 required
args Any

Extra propagator data. This force does not use it.

 None

Returns:

Type Description
Float[Array, 3]

Acceleration in au / day^2.

SolarJ2Perturbation(body, j2=J2_SUN, radius=R_SUN, pole_unit_vec=None)

Bases: Force

Solar oblateness perturbation with a fixed inertial pole.

The default pole follows the OrbFit solar J2 approximation: the pole is normal to the ecliptic-of-J2000 plane and expressed in the BCRS/ICRS axes used by the propagation state.

Initialize a solar J2 perturbation.

Parameters:

Name Type Description Default
body EphemerisBody

Solar ephemeris body that supplies the center position and gravitational parameter.

 required
j2 Float[ArrayLike, '']

Positive dimensionless solar J2.

 J2_SUN
radius Float[ArrayLike, '']

Solar reference radius in au.

 R_SUN
pole_unit_vec Float[ArrayLike, 3] or None

Fixed solar pole unit vector in BCRS axes. If omitted, use the ecliptic-of-J2000 pole expressed in ICRS axes, matching the OrbFit approximation that neglects solar-spin-axis tilt to the ecliptic.

 None

shape property

Return the batch shape.

__call__(tdb_jd1, tdb_jd2, state, args=None)

Evaluate the solar J2 acceleration at one TDB epoch.

Parameters:

Name Type Description Default
tdb_jd1 Float[Array, '']

Two parts of the TDB Julian Date.

 required
tdb_jd2 Float[Array, '']

Two parts of the TDB Julian Date.

 required
state tuple[Float[Array, 3], Float[Array, 3]]

Integrated body state (pos, vel) in BCRS. Position is in au.

 required
args Any

Extra propagator data. This force does not use it.

 None

Returns:

Type Description
Float[Array, 3]

Solar J2 acceleration in au / day^2.