StateArray#

class StateArray(epoch: EpochArray, origin: Body, state: StateDefinition)#

Bases: object

Container for an estimation state vector at a given epoch and origin.

The full estimation state is a stacked vector of kinematic components and scalar/vector parameters for one or more bodies:

\[\begin{split}\mathbf{x} = \begin{bmatrix} \mathbf{r}_1 \\ \dot{\mathbf{r}}_1 \\ \vdots \\ \mathbf{r}_N \\ \dot{\mathbf{r}}_N \\ p_1 \ \cdots \ p_M \end{bmatrix}\end{split}\]

where \(\mathbf{r}_i\), \(\dot{\mathbf{r}}_i\) are the position and velocity of body \(i\), and \(p_j\) are scalar parameters (static or dynamic, estimated or considered).

This class holds a definition and corresponding values for a mixed state: spacecraft/body states (e.g., position/velocity) and scalar/vector parameters (e.g., SRP scale, gravity terms). The state definition is provided via a StateDefinition builder, which yields the canonical tuple encoding expected internally.

Parameters:
epochEpochArray

Epoch for which the state vector is defined (time tag of this state).

originBody

Origin body with respect to which kinematic components (e.g., position/velocity) are expressed.

stateStateDefinition

Fluent state builder. When iterated, it produces a sequence of 6-tuples:

(name: str, dim: int, estimation: str, dynamics: str, owner, value)

where:
  • name: component name. Reserved: "position", "velocity". Arbitrary parameter names (e.g., "eta_srp", "Cr", "mu") are allowed.

  • dim: component dimension (e.g., 3 for position/velocity; 1 for scalars).

  • estimation: "estimated" or "considered".

  • dynamics: "dynamic" or "static".

  • owner: the entity the component belongs to (e.g., Body, Spacecraft, GroundStation, or None for global params).

  • value: initial value, typically an ArrayWUnits (vector of size dim for vector components; scalar for dim == 1).

Attributes:
epoch

Epoch for which the state vector is defined.

index_rep

Representation of the state that links the parameters to the location of that parameter’s value(s) in the state vector.

origin

Origin for which the state vector is defined.

size

Size (length) of the state vector.

state

Full state vector definition as defined and input to the constructor.

state_definition

Parameter definition representation of the state vector.

state_dot_definition

Parameter definition representation of the time derivative of the state vector.

values0

Numerical values of the state vector at t0, as an ArrayWUnits.

values_array

Dict mapping (name, owner) keys to initial ArrayWUnits values.

Methods

add_state_at_epoch(epoch, new_values)

Adds a new state at a specific epoch, keeping epochs in order and reinitializing the StateArray.

add_to_state_vector(new_components)

Adds additional components to the state vector and properly re-initializes the StateArray.

find_indices(parameter_name, body[, flag_dot])

Finds the indices of a parameter (e.g., position, velocity) in the state vector for a specific body.

from_dict(data[, owner_overrides])

Reconstruct a StateArray from a dict produced by to_dict().

get_state_at_epoch(epoch)

Retrieves the state vector for a given epoch.

reinitialize(**kwargs)

Reinitializes the StateArray object with new attribute values in place.

remove_state_at_epoch(epoch)

Removes a state at a specific epoch, ensuring consistency across parameters and reinitializing the StateArray.

to_dict()

Serialize the StateArray to a JSON-friendly dict.

update_state_at_epoch(epoch, updated_values)

Updates the state at a given epoch while maintaining structure and reinitializing the StateArray.

Raises:
ValueError

If the builder emits an unsupported token for estimation/dynamics, or if a vector value length is inconsistent with dim (when validated).

See also

scarabaeus.StateDefinition

Fluent builder for constructing valid state components.

scarabaeus.FilterOD

Filter that consumes StateArray in estimation workflows.

scarabaeus.SolutionOD

OD result container that references StateArray.

Notes

  • Units: supply value with units via ArrayWUnits (e.g., km, km/s, rad).

  • Dimensions: reserved kinematic components use dim = 3; scalar parameters default to dim = 1.

  • Allowed tokens (case-sensitive):

    estimation: "estimated" or "considered"; dynamics: "dynamic" or "static".

  • StateDefinition performs light validation (e.g., len(value) == dim when vector-like).

Examples

Build a state vector using the fluent builder:

import scarabaeus as scb
from scarabaeus import StateDefinition

# Owners
Orbiter = scb.Spacecraft("SCB-1")
Vesta   = scb.Body("Vesta")

# Initial values with units
pos_0 = scb.ArrayWUnits([+10.0, -2.0, +1.0], "km")
vel_0 = scb.ArrayWUnits([ -0.002, 0.001, 0.0005], "km/s")
eta_0 = scb.ArrayWUnits(1.0, "1")  # unitless

state_def = (
    StateDefinition()
    .position(Orbiter, pos_0)                   # 3D, estimated+dynamic by default
    .velocity(Orbiter, vel_0)                   # 3D
    .param("eta_srp", Orbiter, eta_0, static=True)  # scalar, static
)

state_vec = scb.StateArray(epoch=epoch_array[0], origin=Vesta, state=state_def)

Advanced: add considered/static parameters and station terms:

DSN = scb.GroundStation("DSS-14")
range_bias = scb.ArrayWUnits(0.0, "m/s")  # range-rate bias, considered

state_def = (
    StateDefinition()
    .position(Orbiter, pos_0)
    .velocity(Orbiter, vel_0)
    .param("Cr", Orbiter, scb.ArrayWUnits(1.8, "1"), static=True)
    .param("mu", Vesta, scb.ArrayWUnits(17.8e-3, "km^3/s^2"), estimated=False, static=True)
    .param("range_bias_RU", DSN, range_bias, estimated=False, static=True)
)

state_vec = scb.StateArray(epoch=epoch_array[0], origin=Vesta, state=state_def)
classmethod from_dict(data: dict, owner_overrides: dict = None) → StateArray#

Reconstruct a StateArray from a dict produced by to_dict().

Parameters:
datadict

Serialized state.

owner_overridesdict, optional

Mapping spice_id -> Body used to substitute pre-built owners (e.g. so a Propagator reuses its primary_body instance instead of constructing a duplicate). Components whose owner spice_id is present here use the supplied object.

add_state_at_epoch(epoch, new_values)#

Adds a new state at a specific epoch, keeping epochs in order and reinitializing the StateArray.

Parameters:
epochEpochArray or float

The epoch at which to add the state.

new_valuesdict

Dictionary where keys match self._values_array keys, i.e. (param_name, body_id), and values are the new state values for that epoch (ArrayWFrame, with frame possibly None).

Example keys:
{

(‘position’, -1000): ArrayWFrame(…, frame=J2000), (‘velocity’, -1000): ArrayWFrame(…, frame=J2000), (‘eta_srp’, -1000): ArrayWFrame(ArrayWUnits(…), frame=None), (‘range_bias_1’, 399014): ArrayWFrame(ArrayWUnits(…), frame=None), }

Raises:
ValueError

If the new state is inconsistent with existing parameters.

TypeError

If a provided value has the wrong type.

add_to_state_vector(new_components)#

Adds additional components to the state vector and properly re-initializes the StateArray.

Parameters:
new_componentslist or StateDefinition

New state components to be added. Can be either: - A StateDefinition object - A list of tuples in format: (parameter_name, size, estimated/considered, dynamic/static, body, value)

Returns:
StateArray

A new re-initialized StateArray instance with the updated state.

Raises:
TypeError

If new_components is not a list or StateDefinition.

ValueError

If duplicate parameters are detected.

find_indices(parameter_name: str, body: Body, flag_dot=False) → tuple#

Finds the indices of a parameter (e.g., position, velocity) in the state vector for a specific body.

Parameters:
parameter_namestr

The name of the parameter to search for (e.g., “position”, “velocity”).

bodyBody

The associated body of the parameter.

flag_dotbool

Flag to indicate whether to search for the time derivative of the parameter

Returns:
tuple

A tuple (start_index, end_index) indicating the slice of the state vector corresponding to the parameter. Returns None if the parameter is not found.

get_state_at_epoch(epoch)#

Retrieves the state vector for a given epoch.

Parameters:
epochEpochArray or float

The epoch for which to retrieve the state.

Returns:
StateArray

A new StateArray instance with only the specified epoch’s data.

Raises:
ValueError

If the epoch is not found in the state vector.

reinitialize(**kwargs)#

Reinitializes the StateArray object with new attribute values in place.

Parameters:
**kwargs

Keyword arguments representing the new attribute values:

  • epoch (EpochArray, optional): New epoch array

  • origin (Body, optional): New origin body

  • state (StateDefinition or list, optional): New state definition

Notes

Updates the existing instance (self) instead of creating a new one. If ‘state’ is provided as a raw list of tuples, it will be automatically converted to a StateDefinition object for compatibility.

remove_state_at_epoch(epoch)#

Removes a state at a specific epoch, ensuring consistency across parameters and reinitializing the StateArray.

Parameters:
epochEpochArray or float

The epoch at which to remove the state.

Raises:
ValueError

If the epoch is not found in the state vector.

to_dict() → dict#

Serialize the StateArray to a JSON-friendly dict.

Captures the epoch, origin, and every state component (name, dimension, estimation/dynamics modes, owner, values, units, and frame) so the state can be reconstructed by from_dict(). Supports the position / velocity / dynamic+static parameter components used by the propagator; each component’s values must be an ArrayWFrame.

update_state_at_epoch(epoch, updated_values)#

Updates the state at a given epoch while maintaining structure and reinitializing the StateArray.

Parameters:
epochEpochArray or float

The epoch at which to update the state.

updated_valuesdict

Dictionary where keys match self._values_array keys, i.e. (param_name, body_id), and values are ArrayWFrame / ArrayWUnits with the new values for that epoch.

Example:

{
    ('position', -1000): ArrayWFrame(...),
    ('velocity', -1000): ArrayWFrame(...),
    ('eta_srp', -1000): ArrayWFrame(ArrayWUnits(...), None),
}
Raises:
ValueError

If the epoch is not found or values are inconsistent.

TypeError

If a provided value has the wrong type.

property epoch: EpochArray#

Epoch for which the state vector is defined.

property index_rep: dict#

Representation of the state that links the parameters to the location of that parameter’s value(s) in the state vector.

property origin: Body#

Origin for which the state vector is defined.

property size: int#

Size (length) of the state vector.

property state: list#

Full state vector definition as defined and input to the constructor.

property state_definition: list#

Parameter definition representation of the state vector. Does not include values.

property state_dot_definition: list#

Parameter definition representation of the time derivative of the state vector. Does not include values.

property values0: ArrayWUnits#

Numerical values of the state vector at t0, as an ArrayWUnits.

property values_array: dict#

Dict mapping (name, owner) keys to initial ArrayWUnits values.