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
Attributes:
components

The internal list of state components as tuples.

Methods

as_state_definition(obj)

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

custom_param(name, owner, value[, ...])

Register and add a user-defined parameter in a single call.

custom_parameters()

Return a copy of the registered custom state components.

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.

register_custom_parameter(name[, dimension, ...])

Declare a user-defined state component so it passes state validation.

to_components()

Return the state definition as a list of legacy tuples: (name, dim, estimation, dynamics, owner, value)

unregister_custom_parameter(name)

Remove a previously registered custom state component.

velocity(owner, value[, estimation, dynamics])

Add a velocity component to the state vector.

See also

scarabaeus.StateArray

The class that consumes StateDefinition objects.

Notes

Custom components

Beyond the built-in component names, user scripts may register their own solve-for parameters with register_custom_parameter() (or implicitly through custom_param()) so that a CustomDynamicModel can estimate them without any change to the library source.

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.

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.

eta_thermal

Thermal radiation

1

Dimensionless

–

Thermal re-radiation scale factor. Nominal value 1.0.

eta_antenna

Antenna radiation

1

Dimensionless

–

Antenna/LIDAR radiation pressure 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

Cartesian correction in the station’s declared body-fixed frame.

gs_delta_location_CYL_[tag]

Ground station

3

Length

km

Local cylindrical delta (radius, east arc length, Z).

eop_delta_pole_x, eop_delta_pole_y

Earth or Earth station

1 each

Angle

rad

Intended minus nominal terrestrial xp/yp; static measurement parameters.

eop_delta_ut1

Earth or Earth station

1

Time

sec

Intended minus nominal UT1; positive advances spin.

eop_delta_celestial_pole_x, eop_delta_celestial_pole_y

Earth or Earth station

1 each

Angle

rad

Intended minus nominal celestial pole offsets dX/dY (nutation).

body_orientation_delta

Central body or station

3

Angle

rad

Active body-fixed X/Y/Z station rotation; usable on any planet.

love_h2, shida_l2

Central body or station

1 each

unitless

—

Degree-2 displacement Love and Shida numbers. Scale how far the solid tide moves a station, so they need an attached SolidTide; without one the partial is zero.

love_k_[n]_[m]

Central body

1 each

unitless

—

Degree-n order-m potential Love number. Scales how far the solid tide moves the gravity field, a different quantity from love_h2. Reaches the observable only through the trajectory, so it needs a SolidTide on the harmonics model.

tropo_zenith_delay_[tag]

Ground station

1

Length

km

Estimated zenith tropospheric delay, mapped to the slant direction by the Chao wet mapping. Additive on the modelled troposphere.

iono_zenith_delay_[tag]

Ground station

1

Length

km

Estimated zenith ionospheric delay at 2295 MHz, scaled by (2295 MHz / f)^2 and mapped by the thin-shell obliquity.

dt_dv

Spacecraft

1

Time

sec

Time offset of an impulsive maneuver.

dv_smooth

Spacecraft

3

Velocity

km/sec

Smoothed impulsive burn components.

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

dyn

Dimensionless

RU

Range bias in range units for station [tag]; one element for every pass or one per pass.

rangerate_bias_Hz_[tag]

Radiometric bias

dyn

per Time

Hz

Doppler bias in Hz for station [tag]; one element for every pass or one per pass.

dor_bias_[tag]

Radiometric bias

dyn

Length

km

Range bias on the first station [tag] of a differential one-way range; one element for every pass or one per pass.

uplink_delay_bias_[tag]

Ground station

1

Time

sec

Electronic delay correction at t1 (transmit) for station [tag], common to its passes; enters the round-trip light time of range measurements.

transponder_delay_bias

Spacecraft

1

Time

sec

Transponder delay correction at t2, common to every station and pass; enters the round-trip light time of range measurements.

downlink_delay_bias_[tag]

Ground station

1

Time

sec

Electronic delay correction at t3 (receive) for station [tag], common to its passes; enters the round-trip light time of range measurements.

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

pole_w0

Body orientation

1

Angle

rad

Prime-meridian angle at J2000 (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.

gamma_rel

Relativity

1

Dimensionless

–

PPN parameter gamma in the light-time delay (Moyer 12-24).

solar_corona_scale

Media

1

Dimensionless

–

Multiplicative scale on the solar-corona delay (Moyer 10-76).

a_fourier

Empirical accel.

3*(2N+1)

Acceleration

km/s^2

Fourier series coefficients; dim = 3 x (2 x degree + 1).

a_ppoly

Empirical accel.

3*(N_b+p)

Acceleration

km/s^2

Piecewise polynomial coefficients; order p = 0 or 1 over N_b batches.

dyn in the Dim column means the dimension is inferred from the supplied initial value. For a_pfogm / beta_pfogm / a_fourier / a_ppoly 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")
classmethod as_state_definition(obj) → StateDefinition#

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

classmethod custom_parameters() → Dict[str, List]#

Return a copy of the registered custom state components.

Returns:
dict

Mapping name -> [physical_type, size, pattern].

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

The body associated with the state.

frameFrame, optional

Reference frame. If None, position/velocity are stored with no frame.

pos_unitsUnits, optional

Position units. Defaults to km.

vel_unitsUnits, optional

Velocity units. Defaults to km/sec.

estimationstr, optional

Defaults to "estimated".

dynamicsstr, optional

Defaults to "dynamic".

Returns:
StateDefinition

A new StateDefinition with NaN position and velocity.

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:
componentslist of tuple

Each tuple must be: (name:str, dim:int, estimation:str, dynamics:str, owner, value)

clearbool, optional

Ignored for classmethod (kept for API symmetry). Always starts from an empty definition.

Returns:
StateDefinition

Newly built object populated from the provided list.

Raises:
ValueError

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

classmethod register_custom_parameter(name: str, dimension=1, physical_type: str | None = None) → None#

Declare a user-defined state component so it passes state validation.

Registration is global and idempotent: re-registering the same name with the same dimension and physical type is a no-op, which lets a script build several state definitions (truth, reference, filter) from the same parameter declaration.

Parameters:
namestr

Component name. Must be a plain identifier (letters, digits and underscores) and must not match any built-in component pattern.

dimensionint or str, optional

Fixed component size, or "dynamic" to accept any size. Defaults to 1.

physical_typestr, optional

Required unit-dimension name (e.g. "Acceleration", "Dimensionless"). None (default) disables the check.

Raises:
StateDefinition.ReservedComponentNameError

If name is not a valid identifier or collides with a built-in component pattern.

StateDefinition.CustomParameterConflictError

If name was already registered with a different dimension or physical type.

See also

scarabaeus.CustomParameter

Declares a parameter and registers it here.

scarabaeus.CustomDynamicModel

Consumes the registered parameter.

classmethod unregister_custom_parameter(name: str) → None#

Remove a previously registered custom state component.

Parameters:
namestr

Name passed to register_custom_parameter(). Unknown names are ignored.

custom_param(name, owner, value, dimension=None, estimation='estimated', dynamics='static', physical_type=None)#

Register and add a user-defined parameter in a single call.

Convenience wrapper around register_custom_parameter() followed by param(), so a script can introduce a brand-new solve-for parameter — one consumed by a CustomDynamicModel — without touching the library source.

Parameters:
namestr

Parameter name (e.g. "drag_cd"). Must not collide with a built-in component name.

ownerBody, Spacecraft, GroundStation, or None

The body this parameter belongs to.

valueArrayWUnits or ArrayWFrame

Initial value with units.

dimensionint, optional

Parameter dimension. Inferred from value when None.

estimationstr, optional

"estimated" (default) or "considered".

dynamicsstr, optional

"static" (default, constant parameter) or "dynamic" (the parameter has its own ODE, supplied through CustomParameter).

physical_typestr, optional

Dimension name enforced on value (e.g. "Acceleration"). None (default) skips the check.

Returns:
StateDefinition

Self, for method chaining.

Examples

state_def = (scb.StateDefinition()
    .position(sc, pos_0)
    .velocity(sc, vel_0)
    .custom_param("drag_cd", sc, scb.ArrayWFrame(2.2, None, None))
)
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:
componentslist of tuple

Each tuple must be: (name:str, dim:int, estimation:str, dynamics:str, owner, value)

clearbool, optional

If True, reset the builder before appending.

Returns:
StateDefinition

Self, for chaining.

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

Parameter name (e.g., “eta_srp”, “dv_man”, “range_bias”). Must match an allowed pattern in the state dictionary.

ownerBody, Spacecraft, GroundStation, or None

The body/spacecraft associated with this parameter, or None for global parameters.

valueArrayWUnits

Parameter value with units.

dimensionint, optional

Parameter dimension/size. If None, inferred from value length. Defaults to None.

estimationstr, optional

Estimation mode: “estimated” or “considered”. Defaults to “estimated”.

dynamicsstr, optional

Dynamics mode: “dynamic” or “static”. Defaults to “dynamic”.

Returns:
StateDefinition

Self for method chaining.

Raises:
ValueError

If parameter name is not allowed, dimension/physical type mismatch, multiple delta-v maneuvers are specified, or duplicate component exists.

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

Add a position component to the state vector.

Parameters:
ownerBody, Spacecraft, or GroundStation

The body/spacecraft associated with this position.

valueArrayWUnits

Position vector with units (must be 3D with Length dimensions).

estimationstr, optional

Estimation mode: “estimated” or “considered”. Defaults to “estimated”.

dynamicsstr, optional

Dynamics mode: “dynamic” or “static”. Defaults to “dynamic”.

Returns:
StateDefinition

Self for method chaining.

Raises:
ValueError

If component validation fails (wrong dimension, physical type, etc.) or if duplicate component for the same owner exists.

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:
ownerBody, Spacecraft, or GroundStation

The body/spacecraft associated with this velocity.

valueArrayWUnits

Velocity vector with units (must be 3D with Velocity dimensions).

estimationstr, optional

Estimation mode: “estimated” or “considered”. Defaults to “estimated”.

dynamicsstr, optional

Dynamics mode: “dynamic” or “static”. Defaults to “dynamic”.

Returns:
StateDefinition

Self for method chaining.

Raises:
ValueError

If velocity is not added immediately after position, if validation fails, or if duplicate component for the same owner exists.

property components: List[tuple]#

The internal list of state components as tuples.

Returns:
list of tuple

List of component tuples in format: (name, dimension, estimation, dynamics, owner, value)

exception CustomParameterConflictError#

Bases: ValueError

Raised when a custom parameter is re-registered with a different definition.

exception ReservedComponentNameError#

Bases: ValueError

Raised when a custom parameter name collides with a built-in component.

exception UnknownComponentError#

Bases: ValueError

Raised when a component name matches no allowed (built-in or custom) pattern.