StateArray#
- class StateArray(epoch: EpochArray, origin: Body, state: StateDefinition)#
Bases:
objectContainer 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
StateDefinitionbuilder, 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, orNonefor global params).value: initial value, typically anArrayWUnits(vector of sizedimfor vector components; scalar fordim == 1).
- Attributes:
epochEpoch for which the state vector is defined.
index_repRepresentation of the state that links the parameters to the location of that parameter’s value(s) in the state vector.
originOrigin for which the state vector is defined.
sizeSize (length) of the state vector.
stateFull state vector definition as defined and input to the constructor.
state_definitionParameter definition representation of the state vector.
state_dot_definitionParameter definition representation of the time derivative of the state vector.
values0Numerical values of the state vector at t0, as an
ArrayWUnits.values_arrayDict mapping
(name, owner)keys to initialArrayWUnitsvalues.
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 vectorvaluelength is inconsistent withdim(when validated).
See also
scarabaeus.StateDefinitionFluent builder for constructing valid state components.
scarabaeus.FilterODFilter that consumes StateArray in estimation workflows.
scarabaeus.SolutionODOD result container that references StateArray.
Notes
Units: supply
valuewith units viaArrayWUnits(e.g., km, km/s, rad).Dimensions: reserved kinematic components use
dim = 3; scalar parameters default todim = 1.- Allowed tokens (case-sensitive):
estimation:"estimated"or"considered";dynamics:"dynamic"or"static".
StateDefinitionperforms light validation (e.g.,len(value) == dimwhen 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 -> Bodyused to substitute pre-built owners (e.g. so a Propagator reuses itsprimary_bodyinstance instead of constructing a duplicate). Components whose ownerspice_idis 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 anArrayWFrame.
- 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 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.