Skip to content

Documentation / @interstellar-tools/tracking / stateAt

Function: stateAt() ​

ts
function stateAt(
  ephemeris: EphemerisInterface,
  date: Date,
  options?: StateAtOptionsInterface
): StateVectorInterface;

Defined in: probes/interpolate.ts:68

The state of a spacecraft at any moment of an ephemeris: its position and velocity, interpolated between the samples.

Fits the Hermite polynomial through the positions and velocities of the points samples around the date, a polynomial of degree 2n−1 for n samples, and evaluates it and its derivative:

r(t)=∑k=02n−1ck∏j<k(t−zj),v(t)=r˙(t)

Where:

  • z0=z1=t0, z2=z3=t1,… are the sample times, each twice
  • ck are the divided differences of the positions, with the velocities as the first differences at each sample

Units

  • Inputs: the ephemeris from parseOem or parseHorizonsVectors, and a Date.
  • Output: r in m and v in m/s, from the ephemeris's centre, on its frame's axes.

Notes

  • Using the velocities matches the slope as well as the position at each sample: the default 4 samples interpolate to degree 7, as the OEM standard's own example recommends, and follow a sharp perihelion that linear interpolation cuts across.
  • At a sample's epoch, the sample is returned exactly.
  • Only within the ephemeris: outside the first and last samples, it throws rather than extrapolate. Near either end, the samples are taken from the one side.
  • The samples should be close enough to follow the motion: for a probe in cruise, a day apart; near a planet or the Sun, hours or minutes.

Parameters ​

ParameterTypeDescription
ephemerisEphemerisInterfaceThe ephemeris, from parseOem or parseHorizonsVectors.
dateDateThe moment, as a Date, within the ephemeris.
options?StateAtOptionsInterfacepoints, the number of samples to interpolate through (an integer from 2 to 8, default 4).

Returns ​

StateVectorInterface

The position r in m and velocity v in m/s: see StateVectorInterface.

Throws ​

  • If date is not a valid Date, the ephemeris has no samples, or points is not an integer.
  • If date is outside the ephemeris, or points is outside 2 to 8.

Example ​

ts
const voyager1 = parseHorizonsVectors(text);
const { r, v } = stateAt(voyager1, new Date('2026-01-05T06:00:00Z'));

Math.hypot(...r) / AU_METERS; // ≈ 169: au from the Sun

See ​