`StateDefinition`#

class StateDefinition#

Bases: object

Fluent builder for constructing state vector definitions compatible with StateArray.

This class provides a clean, type-safe interface for building state vectors by replacing raw tuple lists with method chaining. It validates components against allowed patterns and enforces structural constraints (e.g., velocity must follow position).

Parameters:: None

See also

scarabaeus.StateArray: The class that consumes StateDefinition objects.

Notes

Ordering rules

Dynamic components must appear before static components.
Estimated components must appear before considered components.
Each .velocity() call must immediately follow its paired .position() call.
Each of dv_man / dv_man1 / dv_man2 may appear at most once per state.
dRA[N] and dDEC[N] finite-burn angle pairs must both be present for the same owner and numeric suffix.
"considered" estimation mode is not yet fully implemented.

Estimation and dynamics modes

Every component accepts two keyword arguments:

estimation — "estimated" (default): corrected by the filter; "considered": contributes to covariance only, not corrected.
dynamics — "dynamic" (default): propagated by the force model; "static": held constant across the arc, only corrected by the filter.

Complete table of allowed state components

All parameter names are case-sensitive. [N] denotes an optional non-negative integer suffix (e.g. dRA, dRA1, dRA2). [tag] denotes a free-form identifier string such as a ground-station or camera name.

Name pattern	Category	Dim	Physical type	Unit	Description
`position`	Kinematics	3	Length	km	Cartesian position. Added via `.position()`.
`velocity`	Kinematics	3	Velocity	km/s	Cartesian velocity. Added via `.velocity()`.
`eta_srp`	SRP	1	Dimensionless	–	Cannonball SRP scale factor. Nominal value 1.0.
`k_thrust[N]`	Finite burn	1	Dimensionless	–	Thrust-magnitude scale factor for burn arc `N`.
`dRA[N]`	Finite burn	1	Angle	rad	Right-ascension pointing correction for burn `N`.
`dDEC[N]`	Finite burn	1	Angle	rad	Declination pointing correction for burn `N`.
`dv_man[N]`	Impulsive maneuver	3	Velocity	km/s	Impulsive delta-v vector. Suffixes: none, `1`, `2`.
`gs_delta_location_ECEF_[tag]`	Ground station	3	Length	km	ECEF position correction for station `[tag]`.
`range_bias_[tag]`	Radiometric bias	dyn	Length	km / m	Additive range bias for station `[tag]`.
`rangerate_bias_[tag]`	Radiometric bias	dyn	Velocity	km/s	Additive range-rate bias for station `[tag]`.
`range_bias_RU_[tag]`	Radiometric bias	1	Dimensionless	RU	Range bias in range units for station `[tag]`.
`rangerate_bias_Hz_[tag]`	Radiometric bias	1	per Time	Hz	Doppler bias in Hz for station `[tag]`.
`angular_bias_[tag]`	Optical navigation	dyn	Dimensionless	pix / rad	Additive RA/DEC angular bias for camera `[tag]`.
`centroid_bias_[tag]`	Optical navigation	dyn	Dimensionless	pixels	Pixel centroid bias for camera `[tag]`.
`cam_focal_length_[tag]`	Optical navigation	2	Dimensionless	pix/rad	Focal length (fx, fy) for camera `[tag]`.
`cam_pp_offset_[tag]`	Optical navigation	2	Dimensionless	pixels	Principal-point offset (cx, cy) for camera `[tag]`.
`gm`	Gravity	1	Gravitational parameter	km^3/s^2	GM of any body in the force model.
`cnm_N_M`	Gravity (harmonics)	1	Dimensionless	–	Cosine spherical harmonic coefficient C_nm, degree N order M.
`snm_N_M`	Gravity (harmonics)	1	Dimensionless	–	Sine spherical harmonic coefficient S_nm, degree N order M.
`pole_ra`	Body orientation	1	Angle	rad	Right ascension of the body’s north pole.
`pole_dec`	Body orientation	1	Angle	rad	Declination of the body’s north pole.
`pole_pm`	Body orientation	1	Dimensionless	deg/day	Prime-meridian rotation rate (IAU convention).
`A2_yark`	Small-body	1	Length / Time^2	AU/day^2	Yarkovsky transverse acceleration coefficient A2.
`a_fogm`	Empirical accel.	3	Acceleration	km/s^2	FOGM empirical acceleration vector.
`beta_fogm`	Empirical accel.	3	per Time	1/s	FOGM inverse correlation time beta = 1/tau per axis.
`a_pfogm`	Empirical accel.	3*n	Acceleration	km/s^2	Piecewise FOGM accel.; dim = 3 x n_batches.
`beta_pfogm`	Empirical accel.	3*n	per Time	1/s	Piecewise FOGM correlation time; same sizing as `a_pfogm`.

dyn in the Dim column means the dimension is inferred from the supplied initial value. For a_pfogm / beta_pfogm it must be a multiple of 3.

Examples

Basic state vector with position, velocity, and a static SRP parameter:

import scarabaeus as scb

state_def = (StateDefinition()
    .position(Orbiter, pos_0)
    .velocity(Orbiter, vel_0)
    .param("eta_srp", Orbiter, par1_0, dynamics="static")
)

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

Multi-spacecraft configuration:

state_def = (StateDefinition()
    .position(Orbiter1, pos_1)
    .velocity(Orbiter1, vel_1)
    .param("eta_srp", Orbiter1, srp_1, dynamics="static")
    .position(Orbiter2, pos_2)
    .velocity(Orbiter2, vel_2)
    .param("eta_srp", Orbiter2, srp_2, dynamics="static")
)

State with spherical harmonics and a range bias:

state_def = (StateDefinition()
    .position(Orbiter, pos_0)
    .velocity(Orbiter, vel_0)
    .param("cnm_2_0", Vesta, c20_0, dynamics="static")
    .param("cnm_2_2", Vesta, c22_0, dynamics="static")
    .param("snm_2_1", Vesta, s21_0, dynamics="static")
    .param("range_bias_DSS14", DSS14, rb_0, dynamics="static")
)

Accessing components directly:

state_def = StateDefinition().position(Orbiter, pos_0).velocity(Orbiter, vel_0)
components = state_def.components  # list of (name, dim, est, dyn, owner, value)
print(f"State has {len(state_def)} components")

Attributes:

components: The internal list of state components as tuples.

Methods

`as_state_definition`(obj)	Accept either:
`empty_pv`(owner[, frame, pos_units, ...])	Create a StateDefinition with NaN position and velocity for a given owner.
`extend_from_components`(components, *[, clear])	Append components from a (name, dim, est, dyn, owner, value) list into this builder.
`from_components`(components, *[, clear])	Construct a StateDefinition from a pre-existing (name, dim, est, dyn, owner, value) list.
`from_legacy`(components)	Build a StateDefinition from a legacy tuple list (name, dim, est, dyn, owner, value).
`param`(name, owner, value[, dimension, ...])	Add a generic parameter to the state vector.
`position`(owner, value[, estimation, dynamics])	Add a position component to the state vector.
`to_components`()	Return the state definition as a list of legacy tuples: (name, dim, estimation, dynamics, owner, value)
`velocity`(owner, value[, estimation, dynamics])	Add a velocity component to the state vector.

classmethod as_state_definition(obj) → StateDefinition#

Accept either:

an existing StateDefinition, or
a legacy list of tuples (name, dim, est, dyn, owner, value),

and return a StateDefinition instance.

classmethod empty_pv(owner, frame=None, pos_units=None, vel_units=None, estimation: str = 'estimated', dynamics: str = 'dynamic') → StateDefinition#

Create a StateDefinition with NaN position and velocity for a given owner.

Useful for non-initial legs where ICs are inherited from the previous leg.

Parameters:

owner (Spacecraft) – The body associated with the state.
frame (Frame, optional) – Reference frame. If None, position/velocity are stored with no frame.
pos_units (Units, optional) – Position units. Defaults to km.
vel_units (Units, optional) – Velocity units. Defaults to km/sec.
estimation (str, optional) – Defaults to "estimated".
dynamics (str, optional) – Defaults to "dynamic".

Returns:

A new StateDefinition with NaN position and velocity.

Return type:

StateDefinition

Examples

# Coast leg — just pos/vel
leg_state = StateDefinition.nan_pv(Orbiter, frame=J2000)

# Finite burn leg — pos/vel + burn params
leg_state = (StateDefinition.nan_pv(Orbiter, frame=J2000)
    .param("k_thrust1", Orbiter, ArrayWFrame(0.9, None, None), dynamics="static")
    .param("dRA1",      Orbiter, ArrayWFrame(0.4, rad, J2000), dynamics="static")
    .param("dDEC1",     Orbiter, ArrayWFrame(0.3, rad, J2000), dynamics="static")
)

classmethod from_components(components: List[tuple], *, clear: bool = True) → StateDefinition#

Construct a StateDefinition from a pre-existing (name, dim, est, dyn, owner, value) list.

Parameters:

components (list of tuple) – Each tuple must be: (name:str, dim:int, estimation:str, dynamics:str, owner, value)
clear (bool, optional) – Ignored for classmethod (kept for API symmetry). Always starts from an empty definition.

Returns:

Newly built object populated from the provided list.

Return type:

StateDefinition

Raises:

ValueError / NotImplementedError – Propagates validation errors from position/velocity/param methods.

classmethod from_legacy(components: list[tuple]) → StateDefinition#: Build a StateDefinition from a legacy tuple list (name, dim, est, dyn, owner, value).

extend_from_components(components: List[tuple], *, clear: bool = False) → StateDefinition#

Append components from a (name, dim, est, dyn, owner, value) list into this builder.

Parameters:

components (list of tuple) – Each tuple must be: (name:str, dim:int, estimation:str, dynamics:str, owner, value)
clear (bool, optional) – If True, reset the builder before appending.

Returns:

Self, for chaining.

Return type:

StateDefinition

Notes

This method routes each tuple through the canonical public APIs (.position, .velocity, .param), so all validations and ordering rules apply.
Dimensional consistency and allowed-name checks are enforced by _validate_component().

param(name, owner, value, dimension=None, estimation='estimated', dynamics='dynamic')#

Add a generic parameter to the state vector.

This method can be used for any allowed state component beyond position and velocity, such as solar radiation pressure coefficients, measurement biases, or delta-v maneuvers.

Parameters:

name (str) – Parameter name (e.g., “eta_srp”, “dv_man”, “range_bias”). Must match an allowed pattern in the state dictionary.
owner (Body, Spacecraft, GroundStation, or None) – The body/spacecraft associated with this parameter, or None for global parameters.
value (ArrayWUnits) – Parameter value with units.
dimension (int, optional) – Parameter dimension/size. If None, inferred from value length. Defaults to None.
estimation (str, optional) – Estimation mode: “estimated” or “considered”. Defaults to “estimated”. Note: “considered” is not yet implemented.
dynamics (str, optional) – Dynamics mode: “dynamic” or “static”. Defaults to “dynamic”.

Returns:

Self for method chaining.

Return type:

StateDefinition

Raises:

ValueError – If parameter name is not allowed, dimension/physical type mismatch, multiple delta-v maneuvers are specified, or duplicate component exists.
NotImplementedError – If estimation=”considered” is specified.

position(owner, value, estimation='estimated', dynamics='dynamic')#

Add a position component to the state vector.

Parameters:

owner (Body, Spacecraft, or GroundStation) – The body/spacecraft associated with this position.
value (ArrayWUnits) – Position vector with units (must be 3D with Length dimensions).
estimation (str, optional) – Estimation mode: “estimated” or “considered”. Defaults to “estimated”. Note: “considered” is not yet implemented.
dynamics (str, optional) – Dynamics mode: “dynamic” or “static”. Defaults to “dynamic”.

Returns:

Self for method chaining.

Return type:

StateDefinition

Raises:

ValueError – If component validation fails (wrong dimension, physical type, etc.) or if duplicate component for the same owner exists.
NotImplementedError – If estimation=”considered” is specified.

to_components() → list[tuple]#: Return the state definition as a list of legacy tuples: (name, dim, estimation, dynamics, owner, value)

velocity(owner, value, estimation='estimated', dynamics='dynamic')#

Add a velocity component to the state vector.

The velocity component must immediately follow a position component.

Parameters:

owner (Body, Spacecraft, or GroundStation) – The body/spacecraft associated with this velocity.
value (ArrayWUnits) – Velocity vector with units (must be 3D with Velocity dimensions).
estimation (str, optional) – Estimation mode: “estimated” or “considered”. Defaults to “estimated”. Note: “considered” is not yet implemented.
dynamics (str, optional) – Dynamics mode: “dynamic” or “static”. Defaults to “dynamic”.

Returns:

Self for method chaining.

Return type:

StateDefinition

Raises:

ValueError – If velocity is not added immediately after position, if validation fails, or if duplicate component for the same owner exists.
NotImplementedError – If estimation=”considered” is specified.

property components: List[tuple]#

The internal list of state components as tuples.

Returns:: List of component tuples in format: (name, dimension, estimation, dynamics, owner, value)
Return type:: list of tuple