Skip to content

Build State From Cartesian Data

This guide shows how to create a State from canonical position and velocity data, inspect its stacked array form, and repeat the same construction for batched [x, y, z, vx, vy, vz] rows.

For the model behind State and reference frames, read Frames And State Representation. Continue to Transform State Between Frames when you need frame conversion.

Prerequisites

  • Activate the project environment described in Installation.
  • No SPK kernel is required for this guide.

1. Create one canonical BCRS state

Use State(...) when your source data already has an epoch, a Cartesian position, a Cartesian velocity, and a reference frame.

from difforb.core import BCRS, State, Time

t = Time.from_tdb_date(2025, 1, 2)

state = State(
    tdb=t.tdb(),
    pos=[1.685775738339898, -1.336388854313325, -0.2144927004440800],
    vel=[0.008995712853117517, 0.006985684417802803, 0.004020851173846060],
    frame=BCRS,
)

print("STATE_ARRAY", state.array)
print("DIST", float(state.dist))
print("LT", float(state.lt))
Output
STATE_ARRAY [ 1.68577574 -1.33638885 -0.2144927   0.00899571  0.00698568  0.00402085]
DIST 2.1618931815545612
LT 0.012486053700677017

The stacked array is always ordered as [x, y, z, vx, vy, vz].

2. Create from a stacked array

Use State.from_array(...) when your upstream source already stores Cartesian states in [..., 6] form.

from difforb.core import BCRS, State, Time

t = Time.from_tdb_jd(2451545.0, 0.0)

state_from_array = State.from_array(
    tdb=t.tdb(),
    array=[1.0, -2.0, 0.5, 0.01, 0.02, -0.03],
    frame=BCRS,
)

print("ARRAY", state_from_array.array)
print("FRAME", state_from_array.frame.name)
Output
ARRAY [ 1.   -2.    0.5   0.01  0.02 -0.03]
FRAME BCRS

3. Batch Cartesian inputs

State follows the broadcast shape carried by tdb, pos, and vel.

import jax.numpy as jnp

from difforb.core import BCRS, State, Time

batched = State(
    tdb=Time.from_tdb_jd(
        jnp.array([2451545.0, 2451546.0]),
        jnp.array([0.0, 0.25]),
    ).tdb(),
    pos=jnp.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
    vel=jnp.array([0.1, 0.2, 0.3]),
    frame=BCRS,
)

print("BATCH_SHAPE", batched.shape)
print("BATCH_VEL", batched.vel)
Output
BATCH_SHAPE (2,)
BATCH_VEL [[0.1 0.2 0.3]
 [0.1 0.2 0.3]]

Common Mistakes

  • pos is in au and vel is in au / day.
  • State stores the epoch in TDB.
  • The stacked array order is position first, velocity second.

Next Steps