4. StateArray#

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

Bases: object

CLASS DESCRIPTION

Parameters:

  • epoch (EpochArray) – Epoch for which the state vector isa defined.

  • origin (Body) – Origin for which the state vector is defined.

  • state (list) – Full state vector definition.

Notes

Build a state vector. Input the parameter list and values as a list input

Example Layout: parameter [string], dimension (size) [int], estimated or considered [string], dynamic or static [string], body [Body, None] (position, 3, estimated, dynamic, ID1, value) (velocity, 3, estimated, dynamic, ID1, value) (position, 3, estimated, static, ID2, value) (parameter1, 1, estimated, static, None, value) (parameter2, 1, estimated, dynamic, None, value) (parameter3, 1, considered, static, None, value)

Examples

Build a state vector by inputting parameter list and values as a list:

# initial setup
import scarabaeus as scb

>>> parameter [string], dimension (size) [int], estimated or considered [string], dynamic or static [string], body [Body, None]
(position, 3, estimated, dynamic, ID1, value)
(velocity, 3, estimated, dynamic, ID1, value)
(position, 3, estimated, static, ID2, value)
(parameter1, 1, estimated, static, None, value)
(parameter2, 1, estimated, dynamic, None, value)
(parameter3, 1, considered, static, None, value)

Attributes

allowed_state

Representation of the allowed components in the StateArray.

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()

Extracts the state vector representation, preserving individual parameters.

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_allowed_state_dictionary()

Generate a dictionary of the components allowed in a StateArray

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])

Generates a representation of the state vector that directly links the parameters to their values.

make_index_rep()

Generates a representation of the state that links the parameter name to the location of that parameter's value(s) in the 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.
classmethod generate_allowed_state_dictionary() → dict#

Generate a dictionary of the components allowed in a StateArray

Returns:

dictionary with the allowed name, physicalType, and size. (name: [physicalType, size, pattern])

Return type:

dict

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

  • new_values (dict) – A dictionary where keys are parameter names and values are new state values.

Raises:

ValueError – If the new state is inconsistent with existing parameters.

add_to_state_vector(new_components)#

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

Parameters:

new_components (list) – List of new state components to be added. Each component should follow the format: (parameter_name, size, estimated/considered, dynamic/static, body, value)

Returns:

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

Return type:

StateArray

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:

scb.ArrayWUnits

extract_values_array() → dict#

Extracts the state vector representation, preserving individual parameters.

Returns:

A dictionary where keys are parameter names, and values are tuples of

(values array, units array).

Return type:

dict

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 (scbt.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 (scb.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#

Generates a representation of the state vector that directly links the parameters to their values. This is used in the propagator to extract the current state values and link them to their respective parameter definitions.

Parameters:

y (np.array) – Current state vector in the propagator at some time step

Returns:

A representation that links the parameter to the parameter values directly

Return type:

dict

make_index_rep() → dict#

Generates a representation of the state that links the parameter name to the location of that parameter’s value(s) in the state vector. This representation allows us to efficiently select slices of the state vector when it is just values of the parameters. This representation is used in the propagator when computing accelerations, general dynamics, and partials (the jocobian). For example: the first parameter in the state is a position and the second is a velocity, then the index representation will be {position: (0:3), velocity: (3:6)}

Returns:

A representation of the state vector that connects the parameters to the positions of their values in the state vector

Return type:

dict

reinitialize(**kwargs)#

Reinitializes the StateArray object with new attribute values in place.

Parameters:

**kwargs – Keyword arguments representing the new attribute values.

Modifies:

Updates the existing instance (self) instead of creating a new one.

reinitialize_with_dv(dv: ImpulsiveBurn)#

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

Parameters:

dv (scb.ImpulsiveBurn) – The delta-v to be added to the velocity field.

Returns:

A new instance of StateArray with the updated state.

Return type:

StateArray

remove_state_at_epoch(epoch)#

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

Parameters:

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

  • updated_values (dict) – A dictionary where keys are parameter names and values are updated state values.

Raises:

ValueError – If the epoch is not found or values are inconsistent.

property allowed_state: dict#

Representation of the allowed components in the StateArray.

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:

scb.ArrayWUnits

property values_array: dict#

Returns the internal _values_array attribute.

Returns:

The _values_array dictionary.

Return type:

dict