Frames

Units used throughout kete are distance in au, and time in Days TDB scaled.

Coordinate frames match the coordinate frames used by cSPICE.

Representation of States, Vectors, and coordinate Frames.

class kete.vector.CometElements(desig, epoch, eccentricity, inclination, peri_dist, peri_arg, peri_time, lon_of_ascending, center_id=10)

Cometary Elements class made accessible to python.

Angles must be in degrees, distances in AU.

Parameters:

desig – The designations of the object.
epoch – The epoch time for the orbital elements.
eccentricity – The eccentricity of the orbit.
inclination – The inclination, must be in degrees.
peri_dist – The perihelion distance in AU.
peri_arg – The argument of perihelion, must be in degrees.
peri_time – The JD time of perihelion.
lon_of_ascending – The longitude of ascending node, in degrees.
center_id – NAIF ID of the central body, defaults to 10 (Sun).

aphelion: Aphelion distance in au, infinite if the orbit is not bound.

center_id: NAIF ID of the central body.

desig: Designation of the object.

eccentric_anomaly

Eccentric Anomaly in degrees.

For a hyperbolic orbit this is the hyperbolic anomaly. For a parabolic orbit the value is zero.

eccentricity: Eccentricity of the orbit.

epoch: Epoch of the elements in JD.

static from_state(state)

Construct a new CometElements object from a State.

Parameters:: State – State Object.

inclination: Inclination of the orbit in degrees.

lon_of_ascending: Longitude of the ascending node of the orbit in degrees.

mean_anomaly

Mean Anomaly in degrees.

The value is zero for a parabolic orbit.

mean_motion

Mean Motion of the orbit in degrees per day.

The value is zero for a parabolic orbit.

orbital_period: Orbital Period in days, infinite if the orbit is not bound.

peri_arg: Argument of Perihelion of the orbit in degrees.

peri_dist: Distance of Perihelion of the orbit in au.

peri_time: Perihelion time of the orbit in JD.

semi_major

Semi Major Axis of the orbit in au.

The value is negative for a hyperbolic orbit and infinite for a parabolic orbit.

state: Convert the orbital elements into a cartesian State.

true_anomaly: True Anomaly in degrees.

class kete.vector.EquinoctialElements(desig, epoch, semi_latus, ecc_f, ecc_g, pole_h, pole_k, true_lon, center_id=10)

Modified equinoctial orbital elements, in the formulation of Walker, Ireland and Owens (1985).

Six floats, no constraints between them, describing one conic about a gravitating body. This is the representation cov_matrix stores a covariance over, and elements returns one of; unlike CometElements there is no Kepler solve or eccentricity branch anywhere in its conversions, which is why it is what a fitted covariance is carried in.

attribute	symbol	meaning
`semi_latus`	`p`	semi-latus rectum in AU, positive on every conic
`ecc_f`	`f`	`e * cos(peri_arg + lon_of_ascending)`
`ecc_g`	`g`	`e * sin(peri_arg + lon_of_ascending)`
`pole_h`	`h`	`tan(i / 2) * cos(lon_of_ascending)`
`pole_k`	`k`	`tan(i / 2) * sin(lon_of_ascending)`
`true_lon`	`L`	true longitude at the epoch, in degrees

Every angle here is in degrees, as everywhere else in the Python interface. cov_matrix follows the same convention, so its L row and column are in degrees and degrees squared and line up with these six directly. The Rust core stores and works in radians throughout; the conversion happens at this boundary.

Zero eccentricity and zero inclination are ordinary points, with no perihelion or ascending node needed to measure an angle from. The one singularity is the retrograde-equatorial pole, inclination = 180 degrees exactly, where (h, k) diverges; from_state() rejects states there.

Parameters:

desig – The designation of the object.
epoch – The epoch time for the elements.
semi_latus – Semi-latus rectum in AU.
ecc_f – Eccentricity component f.
ecc_g – Eccentricity component g.
pole_h – Pole component h.
pole_k – Pole component k.
true_lon – True longitude at the epoch, in degrees.
center_id – NAIF ID of the central body, defaults to 10 (Sun).

aphelion: Aphelion distance in AU. Infinite if the orbit is not bound.

center_id: NAIF ID of the central body.

desig: Designation of the object.

displaced_by(delta)

The same orbit displaced by an offset of the six stored floats.

Parameters:: delta (list[float]) – Length-6 offset, in the order [p, f, g, h, k, L] – the same order as cov_matrix, with L in degrees. true_lon is not reduced by this; see offset_to().

ecc_f: Eccentricity component f = e cos(peri_arg + lon_of_ascending).

ecc_g: Eccentricity component g = e sin(peri_arg + lon_of_ascending).

eccentricity: Eccentricity.

epoch: Epoch of the elements in JD.

epoch_distance

Distance from the central body at the epoch, in AU.

Only physical while the orbit equation is positive, see state.

static from_state(state)

Construct a new EquinoctialElements object from a State.

Parameters:: State – State Object.

inclination: Inclination in degrees, between 0 and 180.

inverse_semi_major

Inverse of the semi major axis, in 1/AU.

Passes smoothly through zero at unit eccentricity, where the semi major axis itself diverges; prefer this over 1 / semi_major near there.

lon_of_ascending

Longitude of ascending node in degrees, between 0 and 360.

Undefined for an uninclined orbit; zero is returned there rather than an error.

lon_of_peri

Longitude of perihelion in degrees, between 0 and 360.

Unlike the argument of perihelion this is defined for an uninclined orbit, since it is measured from the reference direction rather than from the node.

offset_to(other)

The offset carrying this orbit to other, the inverse of displaced_by().

Five coordinates are a plain difference; true_lon is reduced to the shortest signed angle, so two orbits a whole turn apart read as coincident. That last entry is in degrees.

Parameters:: other (EquinoctialElements)

orbital_period: Orbital period in days. Infinite if the orbit is not bound.

peri_arg

Argument of perihelion in degrees, between 0 and 360.

Meaningful only when both the eccentricity and the inclination are non-zero.

peri_dist: Perihelion distance in AU. Finite and positive for every conic.

pole_h: Pole component h = tan(i / 2) cos(lon_of_ascending).

pole_k: Pole component k = tan(i / 2) sin(lon_of_ascending).

semi_latus: Semi-latus rectum in AU, p. Finite and positive on every conic.

semi_major: Semi major axis in AU. Infinite if the orbit is parabolic.

state

Convert the elements into a cartesian State.

Raises:: ValueError – If the true longitude is outside the physical domain of an open orbit.

true_anomaly

True anomaly at the epoch in degrees, between 0 and 360.

Closed form and defined at every eccentricity; only meaningful when the eccentricity is non-zero.

true_lon

True longitude at the epoch, in degrees.

Matches row/column 5 of cov_matrix, which is in degrees for the same reason. It wraps; use offset_to() rather than subtracting two values directly.

class kete.vector.Frames

Defined inertial frames supported by the python side of kete.

All vectors and states are defined by these coordinate frames.

Coordinate frames are defined to be equivalent to the J2000 frames used by the JPL Horizons system and SPICE.

Ecliptic = Frames.Ecliptic

Equatorial = Frames.Equatorial

FK4 = Frames.FK4

Galactic = Frames.Galactic

class kete.vector.SimultaneousStates(states, fov=None)

Representation of a collection of [State] at a single point in time.

The main value in this is that also includes an optional Field of View. If the FOV is provided, it is implied that the states which are present in this file were objects seen by the FOV.

In the case where the FOV is provided, it is expected that the states positions will include light delay, so an object which is ~1au away from the FOV observer will have a JD which is offset by about 8 minutes.

center_id: The reference center NAIF ID for this state.

elongation

If a FOV is present, this returns the elongation of the observed objects.

If the center ID of the observer is the Sun, this is the solar elongation.

Specifically, this is the angle between the center_id and the object as seen from the observer. Typically the center is the Sun.

fov: The FOV if it exists.

jd: The time of the simultaneous states.

static load(filename): Load a single SimultaneousStates from a file.

static load_list(filename)

Load a list from a binary file.

Note that this loads a list of SimultaneousStates, meaning it is a list of a list of States.

static load_parquet(filename): Load states from a parquet file.

static load_parquet_update_times(filename): Load the last time the states were updated as saved in a parquet file.

obs_vecs: If a FOV is present, calculate all vectors from the observer position to the position of the objects.

phase_angles

If a FOV is present, this returns the phases of the observed objects.

Specifically, this is the angle between the center_id and the observer as seen from the object. Typically the center is the Sun.

ra_dec_with_rates

If a FOV is present, calculate the RA/Decs and their rates for all states in this object. This will automatically convert all frames to Equatorial.

4 numbers are returned for each object, [RA, DEC, RA’, DEC’], where rates are provided in degrees/day.

The returned RA’ rate is scaled by cos(dec) so that it is equivalent to a linear projection onto the observing plane.

save(filename): Save a single SimultaneousStates to a file.

static save_list(vec, filename)

Save a list to a binary file.

Note that this saves a list of SimultaneousStates, meaning it is a list of a list of States.

save_parquet(filename, last_updated=None)

Save states as a parquet file.

Optionally save the times when the states were last updated. If a single value is provided, then all states are assumed to have been updated at the same time, otherwise the number of provided times must match the number of states.

states: States contained within.

class kete.vector.State(desig, jd, pos, vel, frame=None, center_id=Ellipsis)

Representation of the state of an object at a specific moment in time.

Parameters:

desig (str) – Name of the object, optional.
jd – The time of the state in TDB jd time, see kete.Time.
pos – Position of the object with respect to the center ID in au.
vel – Velocity of the object with respect to the center ID in au / day.
frame – The frame of reference defining the position and velocity vectors.
center_id – The SPICE kernel ID which defines the central reference point, defaults to the Sun (10).

aphelion: Distance of Aphelion of the orbit in au, infinite if the orbit is not bound.

as_ecliptic: Convert state to the Ecliptic Frame.

as_equatorial: Convert state to the Equatorial Frame.

as_fk4: Convert state to the FK4 Frame.

as_galactic: Convert state to the Galactic Frame.

center_id: Central ID of the object used as reference for the coordinate frame.

change_center(naif_id)

Change the center ID of the state from the current state to the target state.

If the desired state is not a known NAIF id this will raise an exception.

change_frame(frame): Change the frame of the state to the target frame.

desig: Designation of the object if defined.

eccentric_anomaly: Eccentric Anomaly in degrees.

eccentricity: Eccentricity of the orbit.

elements

Cometary orbital elements of the state.

The elements are about the state’s center. This and the element properties below raise ValueError if the center has no known mass, such as the solar system barycenter. Use change_center() to move the state to the Sun first.

frame: Frame of reference used to define the coordinate system.

inclination: Inclination of the orbit in degrees.

is_finite: Is the state finite?

jd: JD of the object’s state in TDB scaled time.

lon_of_ascending: Longitude of the ascending node of the orbit in degrees.

mean_anomaly: Mean Anomaly in degrees.

mean_motion: Mean Motion of the orbit in degrees per day.

orbital_period: Orbital Period in days, infinite if the orbit is not bound.

peri_arg: Argument of Perihelion of the orbit in degrees.

peri_dist: Distance of Perihelion of the orbit in au.

peri_time: Perihelion time of the orbit in JD.

pos: Position of the object in AU with respect to the central object.

semi_major: Semi Major Axis of the orbit in au.

true_anomaly: True Anomaly in degrees.

vel: Velocity of the object in AU/Day.

class kete.vector.UncertainState

Uncertain orbit state: a best-fit orbit together with a covariance matrix spanning that orbit’s six coordinates and any fitted non-gravitational parameters.

The best-fit orbit is stored as modified equinoctial orbital elements, and cov_matrix is a covariance over those six elements rather than over cartesian position and velocity. See cov_matrix for the coordinates and the ordering, state for the best-fit orbit as a State, and cartesian_cov_matrix for the covariance in position and velocity.

cartesian_cov_matrix

Covariance matrix in cartesian position and velocity, as a list of lists.

Rows and columns 0-5 are [x, y, z, vx, vy, vz] in AU and AU/day, Sun-centered and ecliptic, which is the frame state reports its position and velocity in, so the two can be used together directly. Rows 6 onward are the fitted force parameters. This is the form to use for reporting, for interchange, and for comparison against an externally supplied covariance.

The conversion from the stored element coordinates is exact as a linear map. What it cannot recover is accuracy already lost: a cartesian covariance is a much poorer description of the same distribution over a long arc, which is why it is not the stored form.

Raises:: ValueError – If the orbit lies outside the domain where the conversion exists.

cov_matrix

Covariance matrix as a list of lists (use np.array() to convert).

Warning

Rows and columns 0-5 are modified equinoctial orbital elements, not cartesian position and velocity. Use cartesian_cov_matrix for the cartesian form.

The six element coordinates, in order and in the ecliptic frame, are the semi-latus rectum p in AU, the two eccentricity components f = e cos(w + node) and g = e sin(w + node), the two pole components h = tan(i/2) cos(node) and k = tan(i/2) sin(node), and the true longitude at the epoch L = node + w + nu in degrees. All six are dimensionless except the first, in AU, and the last, in degrees. Rows 6 onward are the fitted force parameters, unchanged in meaning and in the order given by param_names.

The L row and column are reported in degrees to match true_lon and every other angle in the Python interface, so the variance there is in degrees squared and its cross terms in degrees. The Rust core holds the same matrix in radians.

The covariance is stored this way because a cartesian covariance stops describing the distribution within a fraction of an orbit, as the distribution shears into a curved shape no linear map can represent. These coordinates stay accurate considerably longer.

The true longitude wraps. Differencing two of these covariances, or averaging their means, has to reduce that coordinate to the shortest signed angle.

desig: Object designator (shortcut for self.state.desig).

elements

Best-fit orbit as an EquinoctialElements, the basis cov_matrix is a covariance over.

This is the mean the covariance is centered on: state gives the same orbit converted to cartesian, and cov_matrix gives the spread around this point in these coordinates.

epoch: Reference epoch as a Time (shortcut for self.state.epoch).

static from_cometary(elements, cov_matrix, non_grav=None)

Build an UncertainState from cometary orbital elements and a covariance expressed in element space.

The element-space covariance is transformed to a Cartesian covariance via a numerically evaluated Jacobian.

Parameters:

elements (CometElements) – Cometary orbital elements (with desig and epoch).
cov_matrix (list[list[float]]) – Covariance matrix in element space, (6+Np)x(6+Np). Element order: [e, q, tp, node, w, i, <nongrav...>], with node, w and i in degrees to match CometElements. Their variances are therefore in degrees squared and their cross terms in degrees.
non_grav (NonGravModel, optional) – Non-gravitational model template. Free parameters are centered on the model’s starting values.

static from_state(state, pos_sigma=0.01, vel_sigma=0.0001, non_grav=None)

Build an UncertainState from a state with isotropic diagonal uncertainties.

The covariance is initialized to a diagonal matrix with the given pos_sigma (AU) and vel_sigma (AU/day) on the diagonal. Useful for seeding MCMC from an IOD candidate.

The input state is automatically re-centered on the Sun if needed, since orbital elements are defined about a gravitating body. That re-centering is a translation by a function of time, so it leaves the covariance unchanged.

Parameters:

state (State) – Object state (any center / frame – will be converted to Sun-centered internally).
pos_sigma (float) – 1-sigma position uncertainty in AU (default 0.01).
vel_sigma (float) – 1-sigma velocity uncertainty in AU/day (default 0.0001).
non_grav (NonGravModel, optional) – Non-gravitational model template. Parameters left free (passed as float("nan")) extend the covariance to (6+Np)x(6+Np) with negligible variance, centered on the model’s starting values.

non_grav

Non-gravitational model template, or None.

The template carries the model variant and fixed coefficients (g(r) shape, albedo, spin pole, etc.). The fitted parameter values are stored on the underlying state’s free_params and merged here to reconstruct the full model.

param_names

Names of all parameters in the covariance matrix, in row/column order.

Always starts with ["p", "f", "g", "h", "k", "L"], the modified equinoctial elements described on cov_matrix, with L in degrees, followed by any non-gravitational parameter names.

sample(n_samples, seed=None)

Draw random samples from the covariance distribution.

Returns a tuple (states, non_gravs) where states is a list of State objects and non_gravs is a list of NonGravModel or None.

Parameters:

n_samples (int) – Number of samples to draw.
seed (int) – Random seed for reproducibility (optional).

state: Best-fit state at the reference epoch (Sun-centered, Ecliptic).

class kete.vector.Vector(raw, frame=Ellipsis)

Vector class which is a vector along with a reference frame.

Vectors are always 3 dimensional cartesian coordinates, where the coordinate system is defined by the frame. For example, the Ecliptic frame is the coordinate frame of the solar system as used by JPL Horizons and SPICE.

Only inertial frames are supported in the Python wrapper, these are available in the kete.Frames enum.

Parameters:

raw (list) – 3 floats which define the direction of the vector.
frame – The frame of reference defining the coordinate frame of the vector, defaults to ecliptic.

angle_between(other): Compute the angle in degrees between two vectors in degrees. This will automatically make a frame change if necessary.

as_ecliptic: Return the vector in the ecliptic frame, regardless of starting frame.

as_equatorial: Return the vector in the equatorial frame, regardless of starting frame.

as_fk4: Return the vector in the fk4 frame, regardless of starting frame.

as_galactic: Return the vector in the galactic frame, regardless of starting frame.

az: Azimuth in degrees from the X axis in the X-Y plane of the coordinate frame.

change_frame(target_frame): Return the vector in the target frame, regardless of starting frame.

dec: Declination in degrees in the Equatorial Frame.

dec_dms: The declination, in degrees-arcminutes-arcseconds string format.

el: Elevation in degrees from the X-Y plane of the coordinate frame. Values will be between -180 and 180

frame: The Frame of reference.

static from_el_az(el, az, r, frame)

Create a new Vector from the elevation and azimuthal angle in degrees.

Parameters:

el (float) – Elevation above the X-Y plane of the frame. (Degrees)
az (float) – Azimuthal angle on the X-Y plane for the frame. (Degrees)
frame (Frames) – Frame of reference which define the coordinate axis.
r – Optional length of the vector, defaults to 1.

static from_lat_lon(lat, lon, r=1.0)

Create a new Ecliptic Vector with the specified latitude/longitude.

Parameters:

lat (float) – Latitude in the ecliptic frame. (Degrees)
lon (float) – Longitude in the ecliptic frame. (Degrees)
r – Optional length of the vector, defaults to 1.

static from_ra_dec(ra, dec, r=1.0)

Create a new Equatorial Vector with the specified RA/DEC.

Parameters:

ra (float) – Right Ascension in the equatorial frame. (Degrees)
dec (float) – Declination in the equatorial frame. (Degrees)
r – Optional length of the vector, defaults to 1.

lat: Latitude in degrees in the Ecliptic Frame.

lon: Longitude in degrees in the Ecliptic Frame.

r: Length of the Vector

ra: Right Ascension in degrees in the Equatorial Frame.

ra_hms: The right ascension, in hours-minutes-seconds string format.

raw: The raw vector without the Frame.

rotate_around(other, angle)

Rotate this vector around another vector by the provided angle.

Parameters:

other (Vector) – The other vector to rotate around.
angle – The angle in degrees of the rotation.

x: X coordinate in au.

y: Y coordinate in au.

z: Z coordinate in au.

kete.vector.ecef_to_wgs_lat_lon(x, y, z)

Compute WCS84 Geodetic latitude/longitude/height from a ECEF position.

This returns the lat, lon, and height from the WGS84 oblate Earth.

Parameters:

x – ECEF x position in km.
y – ECEF y position in km.
z – ECEF z position in km.

kete.vector.wgs_lat_lon_to_ecef(lat, lon, h)

Compute a ECEF position from WCS84 Geodetic latitude/longitude/height.

This returns the X/Y/Z coordinates in km from the geocenter of the Earth.

Parameters:

lat – Latitude in degrees.
lon – Longitude in degrees.
h – Height above the surface of the Earth in km.