Particle

Particle#

The Particle class.

The jitted/host helper functions that implement each integration branch live in sibling modules of this subpackage:

jorbit.particle.ephem (generic integrate/ephem, leapfrog)
jorbit.particle.ias15_dense (IAS15 interpolate=True)
jorbit.particle.ias15_forced (IAS15 interpolate=False)
jorbit.particle.keplerian (analytic two-body path)
jorbit.particle.covariance (shared forward-mode-AD covariance leaves)
jorbit.particle.likelihood (residuals/log-likelihood for fitting)

class jorbit.particle.particle.Particle(state=None, time=None, x=None, v=None, observations=None, name='', gravity='default solar system', de_ephemeris_version='440', integrator='ias15', earliest_time=<Time object: scale='utc' format='iso' value=1980-01-01 00:00:00.000>, latest_time=<Time object: scale='utc' format='iso' value=2050-01-01 00:00:00.000>, fit_seed=None, max_step_size=None, step_scheduler='prs23')[source]#

Bases: object

An object representing a single particle in the solar system.

This class is used to represent and manipulate a single particle moving within the solar system. It is mostly a collection of convenience wrappers around the more general integrators and accelerations, but it also provides some useful methods for projecting the particle’s position onto the sky and fitting orbits to observations.

By construction, Particle objects are massless.

Note: none of the methods associated with this class will alter the underlying state of the particle. For example, “integrate” will give you the positions and velocities of the particle at future times, but after it returns, the particle will still be at its original state.

Parameters:

state (KeplerianState | CartesianState | None)
time (Time | None)
x (jnp.ndarray | None)
v (jnp.ndarray | None)
observations (Observations | None)
name (str)
gravity (str | Callable)
de_ephemeris_version (str | None)
integrator (str)
earliest_time (Time)
latest_time (Time)
fit_seed (KeplerianState | CartesianState | None)
max_step_size (u.Quantity | None)
step_scheduler (str)

state#: The state of the particle, either in Cartesian or Keplerian coordinates.

time#: The time of the particle’s state.

x#: The position of the particle in Cartesian coordinates.

v#: The velocity of the particle in Cartesian coordinates.

observations#: A collection of observations of the particle.

name#: The name of the particle.

gravity#: The gravitational acceleration function to use for the particle.

integrator#: The integrator to use for the particle.

earliest_time#: The earliest time for which ephemeris data is available.

latest_time#: The latest time for which ephemeris data is available.

fit_seed#: A seed for fitting the orbit of the particle.

classmethod from_horizons(name, time, observations=None, gravity='default solar system', integrator='ias15', earliest_time=<Time object: scale='utc' format='iso' value=1980-01-01 00:00:00.000>, latest_time=<Time object: scale='utc' format='iso' value=2050-01-01 00:00:00.000>, fit_seed=None, max_step_size=None, de_ephemeris_version='440')[source]#

Query JPL Horizons for an SSOs state at a given time and create a Particle object.

Parameters:

name (str) – The name of the SSO to query. Can be a string or an integer.
time (Time) – The time to query the SSO at.
observations (Observations | None) – Optional Observations associated with the particle. Necessary if fitting or evaluating likelihoods.
gravity (str | Callable) – The gravitational acceleration function to use when integrating the particle’s orbit. Defaults to “default solar system”, which corresponds to parameterized post-Newtonian interactions with the 10 bodies in the JPL DE440 ephemeris, plus Newtonian interactions with the 16 largest asteroids in the asteroids_de441/sb441-n16.bsp ephemeris. Can also be a jax.tree_util.Partial object that follows the same signature as the acceleration functions in jorbit.accelerations. Other string options are “newtonian planets”, “newtonian solar system”, “gr planets”, and “gr solar system”.
integrator (str) – The integrator to use for the particle. Choices are “ias15”, which is a 15th order adaptive step-size integrator, or “Y4”, “Y6”, or “Y8”, which are 4th, 6th, and 8th order Yoshida leapfrog integrators with fixed step sizes. Defaults to “ias15”.
earliest_time (Time) – The earliest time we expect to integrate the particle to. Defaults to Time(“1980-01-01”). Larger time windows will result in larger in-memory ephemeris objects.
latest_time (Time) – The latest time we expect to integrate the particle to. Defaults to Time(“2050-01-01”). Larger time windows will result in larger in-memory ephemeris objects.
fit_seed (KeplerianState | CartesianState | None) – A seed for fitting the orbit of the particle. If None, a seed will be generated from the observations if they exist. Otherwise, a circular orbit with semi-major axis 2.5 AU will be used.
max_step_size (Quantity | None) – The fixed step size to use for leapfrog integrators. Required if integrator is “Y4”, “Y6”, or “Y8”. Ignored if integrator is “ias15”. Note that this is the maximum step size; the actual step size may be smaller to ensure that the particle lands exactly on the requested output times, and that the step size may change if the spacing between output times is not constant. Defaults to None.
de_ephemeris_version (str | None) – Which version of the JPL DE ephemeris to use for perturber positions. When using from_horizons to pull an initial state, only DE440 is supported. Defaults to “440”, will error on anything else as a safeguard.

Returns:

A Particle object representing the SSO at the given time.

Return type:

Particle

ephemeris(times, observer, state=None, interpolate=True, uncertainty=False, return_steps=False)[source]#

Compute an ephemeris for the particle.

Parameters:

times (Time) – The times to compute the ephemeris for. Can be a single time or an array of times. If provided as a jnp.array, the entries are assumed to be in TDB JD.
observer (str | Array) – The observer to compute the ephemeris for. Can be a string representing an observatory name, or a 3D position vector in AU. For more info on acceptable strings, see the get_observer_positions function.
state (CartesianState | KeplerianState | None) – The state to compute the ephemeris from. If None, the particle’s current state will be used. Usually not necessary to provide this.
interpolate (bool) – Whether to use integrate or integrate_or_interpolate for the underlying integrations.
uncertainty (bool) – If True, also propagate the 6x6 covariance matrix stored on the state’s cov field onto the sky plane via forward-mode autodiff (linear error propagation). The covariance is propagated in whichever parameterization the input state uses (Cartesian or Keplerian); no automatic conversion between parameterizations is performed. Expect roughly a 6x cost relative to the nominal call because jax.jacfwd performs one JVP evaluation per input dimension. Defaults to False.
return_steps (bool) – If True, also return the total number of integration steps taken (summed across any stitched interpolation chunks / inserted forced-landing landings). Appended as the final element of the returned tuple. For the IAS15 integrator this is the figure to watch: the nominal ephemeris is truncation-proof, but the count reveals an unusually heavy integration. None for the analytic Keplerian and fixed-step leapfrog paths, which cannot truncate. Defaults to False.

Returns:

If uncertainty=False (default), returns a SkyCoord with the ephemeris of the particle at the given times, in ICRS coordinates, as seen from that specific observer and correcting for light travel time. If uncertainty=True, returns a tuple with the same SkyCoord and the propagated (N, 2, 2) sky-plane covariance in arcsec**2 (axis order (RA, Dec)). If return_steps=True, the step count is appended as the final tuple element.

Return type:

SkyCoord | tuple

integrate(times, state=None, return_steps=False)[source]#

Integrate the particle’s orbit to specified times, landing exactly on each one.

Note that this method does not change the state of the particle. It returns the positions and velocities of the particle at the given times, but the particle itself is not changed.

Parameters:

times (Time) – The times to integrate to. Can be a single time or an array of times. If provided as a jnp.array, the entries are assumed to be in TDB JD.
state (CartesianState | KeplerianState | None) – The state to integrate from. If None, the particle’s current state will be used. Usually not necessary to provide this.
return_steps (bool) – Whether to return the number of steps taken to reach each output time. If True, the method returns a tuple of (positions, velocities, steps). If False, only returns (positions, velocities). Defaults to False.

Returns:

The positions of the particle at the given times, in AU, and the The velocities of the particle at the given times, in AU/day. If return_steps is True, also returns an array of the number of steps taken to reach each output time.

Return type:

tuple[Array, Array]

integrate_or_interpolate(times, state=None, return_steps=False)[source]#

Integrate the particle’s orbit to specified times, overshooting and ‘interpolating’ if necessary.

Note that this method does not change the state of the particle. It returns the positions and velocities of the particle at the given times, but the particle itself is not changed.

Parameters:

times (Time) – The times to integrate to. Can be a single time or an array of times. If provided as a jnp.array, the entries are assumed to be in TDB JD.
state (CartesianState | KeplerianState | None) – The state to integrate from. If None, the particle’s current state will be used. Usually not necessary to provide this.
return_steps (bool) – Whether to return the number of steps taken to reach each output time. If True, the method returns a tuple of (positions, velocities, steps). If False, only returns (positions, velocities). Defaults to False.

Returns:

Return type:

tuple[Array, Array]

is_observable(times, observer, sun_limit=20.0, ephem=None, return_angle=False)[source]#

Check whether a particle is observable or too close to the Sun.

Parameters:

times (Time) – The times to check the observability.
observer (str | Array) – The observer/observatory making the observations. Can be a string for the name/code of an observatory, or a jnp.array of 3D barycentric ICRS positions in AU.
sun_limit (float) – The minimum allowed angular separation from the Sun, in degrees. Defaults to 20 degrees.
ephem (SkyCoord | None) – Optionally, the ephemeris of the particle at the given times. If not provided, will be computed using the ephemeris method. Helpful if you’ve already computed the ephemeris and want to avoid doing it twice.
return_angle (bool) – If True, will return the angles to the Sun in degrees, not the mask. Default is False.

Returns:

A boolean array indicating whether the particle is observable at each time (True) or too close to the Sun (False).

Return type:

Array

max_likelihood(fit_seed=None, verbose=False)[source]#

Find the maximum likelihood orbit for the particle.

Parameters:

fit_seed (CartesianState | KeplerianState | None) – A seed for fitting the orbit of the particle. If None, a seed will be generated from the observations if they exist. Otherwise, a circular orbit with semi-major axis 2.5 AU will be used.
verbose (bool) – Whether to print the optimization progress. Defaults to False.

Returns:

A new Particle object whose state matches the maximum likelihood orbit.

Return type:

Particle

property cartesian_state: CartesianState#

Return the Cartesian state of the particle.

The state is self-describing about its absolute epoch via the (relative_time, time_reference) pair: relative_time is 0.0 (the offset in the particle’s internal frame) and time_reference is t_ref_jd (the absolute JD anchor).

property keplerian_state: KeplerianState#

Return the Keplerian state of the particle.

property observations: Observations | None#: Return the observations associated with the particle.

property t_ref: astropy.time.core.Time#

Reference time (astropy Time, TDB) — the particle’s epoch.

All JAX-visible times inside the Particle are offsets in days from this reference, which keeps the integrator’s internal arithmetic well-conditioned at decadal timescales.

property t_ref_jd: float#: Reference time as a float JD (TDB), matching t_ref.

Particle

Contents

Particle#