State

class sbpy.dynamics.state.State(r: Quantity, v: Quantity, t: Quantity | Time, frame: FrameInputTypes | None = None)

Bases: StateBase

Dynamical state.

Parameters:

rQuantity

Position (x, y, z), shape = (3,) or (N, 3).

vQuantity

Velocity (x, y, z), shape = (3,) or (N, 3).

tTime or Quantity

Time, a scalar or shape = (N,). Time as a Quantity may only be used with the ArbitraryFrame coordinate frame.

frameBaseCoordinateFrame class or str, optional

Reference frame for r and v. Default: ArbitraryFrame.

Notes

State data is immutable.

Examples

>>> from astropy.time import Time
>>> import astropy.units as u
>>> from sbpy.dynamics import State
>>> r = [1e9, 1e9, 0] * u.km
>>> v = [0, 0, 10] * u.km / u.s
>>> t = Time("2022-07-24", scale="tdb")
>>> state = State(r, v, t)

Or, specify time relative to an arbitrary epoch:

>>> t = 327 * u.day
>>> state = State(r, v, t)

Attributes Summary

arbitrary_time	True if the time attribute is arbitrary.
frame
r	Position vector.
rv	Position in km, and velocity in km/s.
t	Time.
v	Velocity vector.
v_x	x component of the velocity vector.
v_y	y component of the velocity vector.
v_z	z component of the velocity vector.
x	x component of the position vector.
y	y component of the position vector.
z	z component of the position vector.

Methods Summary

from_ephem(eph[, frame])	Initialize from an Ephem object.
from_skycoord(coords)	Initialize from astropy SkyCoord.
from_states(states)	Initialize from a list of states.
observe(target)	Project a target's position onto the sky.
to_ephem([observer, coords])	Convert to an sbpy ephemeris object.
to_skycoord()	Convert to a SkyCoord object.
transform_to(frame)	Transform state into another reference frame.

Attributes Documentation

arbitrary_time

True if the time attribute is arbitrary.

frame

r

Position vector.

rv

Position in km, and velocity in km/s.

t

Time.

v

Velocity vector.

v_x

x component of the velocity vector.

v_y

y component of the velocity vector.

v_z

z component of the velocity vector.

x

x component of the position vector.

y

y component of the position vector.

z

z component of the position vector.

Methods Documentation

classmethod from_ephem(eph: Ephem, frame: FrameInputTypes | None = None) → StateType

Initialize from an Ephem object.

Parameters:

ephEphem

Ephemeris object, must have time, position, and velocity. Position and velocity may be specified using (“x”, “y”, “z”, “vx”, “vy”, and “vz”), or (“ra”, “dec”, “Delta”, “RA*cos(Dec)_rate”, “Dec_rate”, and “deltadot”).

framestr or BaseCoordinateFrame, optional

The reference frame for the ephemeris.

classmethod from_skycoord(coords: SkyCoord) → StateType

Initialize from astropy SkyCoord.

Parameters:

coords: ~astropy.coordinates.SkyCoord

The object state. Must have position and velocity, obstime, and be convertible to cartesian (3D) coordinates.

classmethod from_states(states: Iterable[StateType]) → StateType

Initialize from a list of states.

The resulting reference frame will be that of states[0].

Parameters:

statesarray

observe(target: StateType) → SkyCoord

Project a target’s position onto the sky.

Parameters:

targetState

The target to observe.

Returns:

coordsSkyCoord

to_ephem(observer: StateType | None = None, coords: SkyCoord | None = None) → Ephem

Convert to an sbpy ephemeris object.

Parameters:

observerState, optional

Include this observer in the metadata. If coords is None, then also calculate RA/longitude, Dec/latitude, distance, etc for this observer.

coordsSkyCoord, optional

Include these observer-based coordinates in the result.

Returns:

ephEphem

Notes

Observer state is stored in the Ephem.meta attribute. coords is calculated for the given observer.

Attribute or quantity	Ephem field name
t, as Time	date
t, as Quantity	t_relative
\(|r|\)	r
\(|v \cdot \hat{r}|\)	rdot
coords.ra	ra
coords.dec	dec
coords.pm_ra_cosdec	ra*cos(dec)_rate
coords.pm_dec	dec_rate
coords.lon	lon
coords.lat	lat
coords.pm_lon_coslat	lon*cos(lat)_rate
coords.pm_lat	lat_rate
coords.distance	delta
coords.radial_velocity	deltadot
x	x
y	y
z	z
v_x	vx
v_y	vy
v_z	vz

to_skycoord() → SkyCoord

Convert to a SkyCoord object.

transform_to(frame: FrameInputTypes) → StateBaseType

Transform state into another reference frame.

Parameters:

framestr or BaseCoordinateFrame

Transform into this reference frame.

Returns:

stateState

The transformed state.