4. StateArray#

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

Bases: object

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

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 scarabaeus.ArrayWUnits (vector of size dim for vector components; scalar for dim == 1).

See also

StateDefinition: Fluent builder for constructing valid state components.

FilterOD, SolutionOD

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 vectorat t0.
`values_array`	Returns the internal _values_array attribute.

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.
`extract_state_definition`()	Generates a standardized definition of the state.
`extract_values0`()	Generates a state vector representation consisting of only the parameter values.
`extract_values_array`()	Extract a body-aware representation of the state vector.
`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.
`generate_state_dot_definition`()	Generates a standardized definition of the first time derivative of the state.
`get_state_at_epoch`(epoch)	Retrieves the state vector for a given epoch.
`make_direct_representation`([y])	Build a direct numeric-ID-based representation of the current state.
`make_index_rep`()	Build an index map from state definition entries to slices in the flat state vector.
`reinitialize`(**kwargs)	Reinitializes the StateArray object with new attribute values in place.
`reinitialize_with_dv`(dv)	Reinitializes the state vector by updating the velocity field with the given delta-v.
`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.

extract_state_definition() → list#

Generates a standardized definition of the state. Uses only the parameter definitions used in constructing the state Vector. Does not include the parameter values. This representation is used in the propagator when computing accelerations, general dynamics, and partials (the jocobian).

Returns:: State vector consisting only of the parameters and their definitions
Return type:: list

extract_values0() → ArrayWUnits#

Generates a state vector representation consisting of only the parameter values. This vector is what is used when propagating, for example.

Returns:: Vector of values that define the state.
Return type:: ArrayWUnits

extract_values_array() → dict#

Extract a body-aware representation of the state vector.

For each state entry of the form:: (name, dim, est, dyn, owner, ArrayWFrame)

this returns a dictionary:

(name, spice_id) -> (values, units)

where: - spice_id is taken from owner.spice_id when available, - if owner has no spice_id (e.g. global parameter), spice_id is None.

For dynamic parameters: - If values are given as a time history (shape (N, dim) or (N,)), N is checked to be consistent across parameters and with epoch.size. - If values are just a single vector of size dim, they are treated as initial values only (no time history check).

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

generate_state_dot_definition() → list#

Generates a standardized definition of the first time derivative of the state. Uses only the parameter definitions used in constructing the state Vector. Does not include the parameter values. This representation is used in the propagator when computing accelerations, general dynamics, and partials (the jocobian).

Returns:: Vector consisting of the definitions of the time derivative of the parameters in the state vector
Return type:: list

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.

make_direct_representation(y=None) → dict#

Build a direct numeric-ID-based representation of the current state.

Each entry is keyed as (name, spice_id), where spice_id is taken from the owner object of that state component. Only numeric identifiers are used, no object or string aliases.

Parameters:: y (np.ndarray, optional) – Flat state vector at the current step. If None, uses self.values.
Returns:: Mapping from (name, spice_id) → np.ndarray or scalar.
Return type:: dict

make_index_rep() → dict#

Build an index map from state definition entries to slices in the flat state vector.

For each state entry of the form:: (name, dim, est, dyn, owner, value)

this returns a dictionary mapping:

(name, spice_id) -> slice(i_start, i_end)

where: - spice_id is taken from owner.spice_id when available. - If owner has no spice_id (e.g. global parameter), the key is just name.

This makes multi-body states unambiguous, e.g.:

(‘position’, -1000) -> Orbiter position slice (‘position’, 399) -> Earth position slice

instead of overwriting everything under “position”.

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.

reinitialize_with_dv(dv: ImpulsiveBurn)#

Reinitializes the state vector by updating the velocity field with the given delta-v.

Parameters:: dv (ImpulsiveBurn) – The delta-v to be added to the velocity field.
Returns:: A new instance of StateArray with the updated state.
Return type:: StateArray
Raises:: ValueError – If no velocity component exists, multiple velocity components found, or if there’s a frame mismatch between velocity and delta-v.

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 vectorat t0.

Returns:: State vector values at t0
Return type:: ArrayWUnits

property values_array: dict#

Returns the internal _values_array attribute.

Returns:: The _values_array dictionary.
Return type:: dict

4. StateArray#

This Page