`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:

epoch (EpochArray) – Epoch for which the state vector is defined (time tag of this state).
origin (Body) – Origin body with respect to which kinematic components (e.g., position/velocity) are expressed.
state (StateDefinition) –
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).

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","considered"}, dynamics ∈ {"dynamic","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)

Raises:

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

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.
`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.
`update_state_at_epoch`(epoch, updated_values)	Updates the state at a given epoch while maintaining structure and reinitializing the StateArray.

add_state_at_epoch(epoch, new_values)#

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

Parameters:

epoch (EpochArray or float) – The epoch at which to add the state.
new_values (dict) –
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_components (list 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:

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

Return type:

StateArray

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_name (str) – The name of the parameter to search for (e.g., “position”, “velocity”).
body (Body) – The associated body of the parameter.
flag_dot (bool) – Flag to indicate whether to search for the time derivative of the parameter

Returns:

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.

Return type:

tuple

get_state_at_epoch(epoch)#

Retrieves the state vector for a given epoch.

Parameters:: epoch (EpochArray or float) – The epoch for which to retrieve the state.
Returns:: A new StateArray instance with only the specified epoch’s data.
Return type:: StateArray
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
Modifies – Updates the existing instance (self) instead of creating a new one.

Notes

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:: epoch (EpochArray or float) – The epoch at which to remove the state.
Raises:: ValueError – If the epoch is not found in the state vector.

update_state_at_epoch(epoch, updated_values)#

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

Parameters:

epoch (EpochArray or float) – The epoch at which to update the state.
updated_values (dict) –
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.

StateArray#

`StateArray`#