Third-Body Perturbations¶

Third-body gravitational perturbation accelerations from the Sun, Moon, and planets.

Note

For conceptual explanations and examples, see Third-Body Perturbations in the Learn section.

Analytical Models¶

accel_third_body_sun `builtin` ¶

accel_third_body_sun(epc: Epoch, r_object: ndarray) -> ndarray

Calculate the acceleration due to the Sun on an object using low-precision analytical ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate the Sun's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to the Sun. Units: (m/s²)

Example

import brahe as bh
import numpy as np

epc = bh.Epoch.from_date(2024, 2, 25, bh.TimeSystem.UTC)

# Using position vector
r_object = np.array([bh.R_EARTH + 500e3, 0.0, 0.0])
a = bh.accel_third_body_sun(epc, r_object)

# Or using state vector directly
x_object = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7500.0, 0.0])
a = bh.accel_third_body_sun(epc, x_object)

accel_third_body_sun_spice `builtin` ¶

accel_third_body_sun_spice(epc: Epoch, r_object: ndarray, source: EphemerisSource) -> ndarray

Calculate the acceleration due to the Sun on an object using DE high-precision ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate the Sun's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required
`source`	`EphemerisSource`	Ephemeris source to use (DE440s or DE440)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to the Sun. Units: (m/s²)

Example

import brahe as bh
import numpy as np

bh.load_common_spice_kernels()
epc = bh.Epoch.from_date(2024, 2, 25, bh.TimeSystem.UTC)
r_object = np.array([bh.R_EARTH + 500e3, 0.0, 0.0])
a = bh.accel_third_body_sun_spice(epc, r_object, bh.EphemerisSource.DE440s)

Moon Perturbations¶

accel_third_body_moon `builtin` ¶

accel_third_body_moon(epc: Epoch, r_object: ndarray) -> ndarray

Calculate the acceleration due to the Moon on an object using low-precision analytical ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate the Moon's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to the Moon. Units: (m/s²)

Example

import brahe as bh
import numpy as np

epc = bh.Epoch.from_date(2024, 2, 25, bh.TimeSystem.UTC)
r_object = np.array([bh.R_EARTH + 500e3, 0.0, 0.0])
a = bh.accel_third_body_moon(epc, r_object)

accel_third_body_moon_spice `builtin` ¶

accel_third_body_moon_spice(epc: Epoch, r_object: ndarray, source: EphemerisSource) -> ndarray

Calculate the acceleration due to the Moon on an object using DE high-precision ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate the Moon's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required
`source`	`EphemerisSource`	Ephemeris source to use (DE440s or DE440)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to the Moon. Units: (m/s²)

Example

import brahe as bh
import numpy as np

bh.load_common_spice_kernels()
epc = bh.Epoch.from_date(2024, 2, 25, bh.TimeSystem.UTC)
r_object = np.array([bh.R_EARTH + 500e3, 0.0, 0.0])
a = bh.accel_third_body_moon_spice(epc, r_object, bh.EphemerisSource.DE440s)

accel_third_body_sun_spice `builtin` ¶

accel_third_body_sun_spice(epc: Epoch, r_object: ndarray, source: EphemerisSource) -> ndarray

Calculate the acceleration due to the Sun on an object using DE high-precision ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate the Sun's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required
`source`	`EphemerisSource`	Ephemeris source to use (DE440s or DE440)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to the Sun. Units: (m/s²)

Example

import brahe as bh
import numpy as np

bh.load_common_spice_kernels()
epc = bh.Epoch.from_date(2024, 2, 25, bh.TimeSystem.UTC)
r_object = np.array([bh.R_EARTH + 500e3, 0.0, 0.0])
a = bh.accel_third_body_sun_spice(epc, r_object, bh.EphemerisSource.DE440s)

accel_third_body_mercury_spice `builtin` ¶

accel_third_body_mercury_spice(epc: Epoch, r_object: ndarray, source: EphemerisSource) -> ndarray

Calculate the acceleration due to Mercury on an object using DE ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate Mercury's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required
`source`	`EphemerisSource`	Which ephemeris kernel to use (DE440s or DE440)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to Mercury. Units: (m/s²)

accel_third_body_venus_spice `builtin` ¶

accel_third_body_venus_spice(epc: Epoch, r_object: ndarray, source: EphemerisSource) -> ndarray

Calculate the acceleration due to Venus on an object using DE ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate Venus's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required
`source`	`EphemerisSource`	Which ephemeris kernel to use (DE440s or DE440)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to Venus. Units: (m/s²)

accel_third_body_mars_spice `builtin` ¶

accel_third_body_mars_spice(epc: Epoch, r_object: ndarray, source: EphemerisSource) -> ndarray

Calculate the acceleration due to Mars on an object using DE ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate Mars's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required
`source`	`EphemerisSource`	Which ephemeris kernel to use (DE440s or DE440)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to Mars. Units: (m/s²)

accel_third_body_jupiter_spice `builtin` ¶

accel_third_body_jupiter_spice(epc: Epoch, r_object: ndarray, source: EphemerisSource) -> ndarray

Calculate the acceleration due to Jupiter on an object using DE ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate Jupiter's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required
`source`	`EphemerisSource`	Which ephemeris kernel to use (DE440s or DE440)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to Jupiter. Units: (m/s²)

accel_third_body_saturn_spice `builtin` ¶

accel_third_body_saturn_spice(epc: Epoch, r_object: ndarray, source: EphemerisSource) -> ndarray

Calculate the acceleration due to Saturn on an object using DE ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate Saturn's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required
`source`	`EphemerisSource`	Which ephemeris kernel to use (DE440s or DE440)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to Saturn. Units: (m/s²)

accel_third_body_uranus_spice `builtin` ¶

accel_third_body_uranus_spice(epc: Epoch, r_object: ndarray, source: EphemerisSource) -> ndarray

Calculate the acceleration due to Uranus on an object using DE ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate Uranus's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required
`source`	`EphemerisSource`	Which ephemeris kernel to use (DE440s or DE440)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to Uranus. Units: (m/s²)

accel_third_body_neptune_spice `builtin` ¶

accel_third_body_neptune_spice(epc: Epoch, r_object: ndarray, source: EphemerisSource) -> ndarray

Calculate the acceleration due to Neptune on an object using DE ephemerides.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch at which to calculate Neptune's position	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object in the GCRF frame. Units: (m)	required
`source`	`EphemerisSource`	Which ephemeris kernel to use (DE440s or DE440)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration due to Neptune. Units: (m/s²)

Arbitrary Central Body¶

accel_third_body_for_body `builtin` ¶

accel_third_body_for_body(central_body: CentralBody, body: ThirdBody, source: EphemerisSource, epc: Epoch, r_object: ndarray) -> ndarray

Calculate the acceleration due to a third body on an object propagated about an arbitrary central body.

Generalizes the body-specific accel_third_body_* functions to non-Earth central bodies (e.g. CentralBody.Moon, CentralBody.Mars, CentralBody.EMB), applying the direct-vs-differential barycenter rule: for CentralBody.SSB the direct (non-differential) form is always used; for CentralBody.EMB it is used only when body is ThirdBody.EARTH or ThirdBody.MOON; every other combination uses the differential form.

Accepts either a 3D position vector or a 6D state vector for r_object.

Parameters:

Name	Type	Description	Default
`central_body`	`CentralBody`	Body the object's position and the returned acceleration are expressed relative to.	required
`body`	`ThirdBody`	Perturbing celestial body.	required
`source`	`EphemerisSource`	Ephemeris source for the perturber's position. Honored via kernel-scoped queries regardless of which other kernels are loaded; satellite-system bodies (e.g. `ThirdBody.PHOBOS`) take their body-relative-to-barycenter leg from their system's satellite ephemeris kernel. Custom NAIF IDs outside DE and known satellite-kernel coverage resolve across all loaded kernels instead. `EphemerisSource.LowPrecision` is only valid when `central_body` is `CentralBody.Earth` and `body` is `ThirdBody.SUN` or `ThirdBody.MOON`.	required
`epc`	`Epoch`	Epoch for ephemeris lookup.	required
`r_object`	`ndarray`	Position (length 3) or state (length 6) of the object, relative to `central_body`. Units: (m)	required

Returns:

Type	Description
`ndarray`	np.ndarray: Acceleration in the inertial frame centered on `central_body`. Units: (m/s²)

Raises:

Type	Description
`RuntimeError`	If `source` is `LowPrecision` with a non-Earth `central_body` or a `body` other than Sun/Moon, if `body` has the same NAIF ID as `central_body`, or if the ephemeris kernel cannot be loaded or queried.

Example

import brahe as bh
import numpy as np

bh.load_common_spice_kernels()
epc = bh.Epoch.from_date(2024, 2, 25, bh.TimeSystem.UTC)
r_object = np.array([bh.R_MOON + 100e3, 0.0, 0.0])
a_earth = bh.accel_third_body_for_body(
    bh.CentralBody.Moon, bh.ThirdBody.EARTH, bh.EphemerisSource.DE440s, epc, r_object
)

Third-Body Perturbations¶

Analytical Models¶

accel_third_body_sun builtin ¶

accel_third_body_sun_spice builtin ¶

Moon Perturbations¶

accel_third_body_moon builtin ¶

accel_third_body_moon_spice builtin ¶

accel_third_body_sun_spice builtin ¶

accel_third_body_mercury_spice builtin ¶

accel_third_body_venus_spice builtin ¶

accel_third_body_mars_spice builtin ¶

accel_third_body_jupiter_spice builtin ¶

accel_third_body_saturn_spice builtin ¶

accel_third_body_uranus_spice builtin ¶

accel_third_body_neptune_spice builtin ¶

Arbitrary Central Body¶

accel_third_body_for_body builtin ¶

See Also¶

accel_third_body_sun `builtin` ¶

accel_third_body_sun_spice `builtin` ¶

accel_third_body_moon `builtin` ¶

accel_third_body_moon_spice `builtin` ¶

accel_third_body_sun_spice `builtin` ¶

accel_third_body_mercury_spice `builtin` ¶

accel_third_body_venus_spice `builtin` ¶

accel_third_body_mars_spice `builtin` ¶

accel_third_body_jupiter_spice `builtin` ¶

accel_third_body_saturn_spice `builtin` ¶

accel_third_body_uranus_spice `builtin` ¶

accel_third_body_neptune_spice `builtin` ¶

accel_third_body_for_body `builtin` ¶