StateDefinition#
- class StateDefinition#
Bases:
objectFluent 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:
componentsThe 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.
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.
Return the state definition as a list of legacy tuples: (name, dim, estimation, dynamics, owner, value)
Remove a previously registered custom state component.
velocity(owner, value[, estimation, dynamics])Add a velocity component to the state vector.
See also
scarabaeus.StateArrayThe 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 throughcustom_param()) so that aCustomDynamicModelcan 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_man2may appear at most once per state.dRA[N]anddDEC[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
positionKinematics
3
Length
km
Cartesian position. Added via
.position().velocityKinematics
3
Velocity
km/s
Cartesian velocity. Added via
.velocity().eta_srpSRP
1
Dimensionless
–
Cannonball SRP scale factor. Nominal value 1.0.
eta_thermalThermal radiation
1
Dimensionless
–
Thermal re-radiation scale factor. Nominal value 1.0.
eta_antennaAntenna 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_yEarth or Earth station
1 each
Angle
rad
Intended minus nominal terrestrial xp/yp; static measurement parameters.
eop_delta_ut1Earth or Earth station
1
Time
sec
Intended minus nominal UT1; positive advances spin.
eop_delta_celestial_pole_x,eop_delta_celestial_pole_yEarth or Earth station
1 each
Angle
rad
Intended minus nominal celestial pole offsets dX/dY (nutation).
body_orientation_deltaCentral body or station
3
Angle
rad
Active body-fixed X/Y/Z station rotation; usable on any planet.
love_h2,shida_l2Central 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-
norder-mpotential Love number. Scales how far the solid tide moves the gravity field, a different quantity fromlove_h2. Reaches the observable only through the trajectory, so it needs aSolidTideon 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_dvSpacecraft
1
Time
sec
Time offset of an impulsive maneuver.
dv_smoothSpacecraft
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_biasSpacecraft
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].gmGravity
1
Gravitational parameter
km^3/s^2
GM of any body in the force model.
cnm_N_MGravity (harmonics)
1
Dimensionless
–
Cosine spherical harmonic coefficient C_nm, degree N order M.
snm_N_MGravity (harmonics)
1
Dimensionless
–
Sine spherical harmonic coefficient S_nm, degree N order M.
pole_raBody orientation
1
Angle
rad
Right ascension of the body’s north pole.
pole_decBody orientation
1
Angle
rad
Declination of the body’s north pole.
pole_pmBody orientation
1
Dimensionless
deg/day
Prime-meridian rotation rate (IAU convention).
pole_w0Body orientation
1
Angle
rad
Prime-meridian angle at J2000 (IAU convention).
A2_yarkSmall-body
1
Length / Time^2
AU/day^2
Yarkovsky transverse acceleration coefficient A2.
a_fogmEmpirical accel.
3
Acceleration
km/s^2
FOGM empirical acceleration vector.
beta_fogmEmpirical accel.
3
per Time
1/s
FOGM inverse correlation time beta = 1/tau per axis.
a_pfogmEmpirical accel.
3*n
Acceleration
km/s^2
Piecewise FOGM accel.; dim = 3 x n_batches.
beta_pfogmEmpirical accel.
3*n
per Time
1/s
Piecewise FOGM correlation time; same sizing as
a_pfogm.gamma_relRelativity
1
Dimensionless
–
PPN parameter gamma in the light-time delay (Moyer 12-24).
solar_corona_scaleMedia
1
Dimensionless
–
Multiplicative scale on the solar-corona delay (Moyer 10-76).
a_fourierEmpirical accel.
3*(2N+1)
Acceleration
km/s^2
Fourier series coefficients; dim = 3 x (2 x degree + 1).
a_ppolyEmpirical 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_ppolyit 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
nameis not a valid identifier or collides with a built-in component pattern.- StateDefinition.CustomParameterConflictError
If
namewas already registered with a different dimension or physical type.
See also
scarabaeus.CustomParameterDeclares a parameter and registers it here.
scarabaeus.CustomDynamicModelConsumes 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 byparam(), so a script can introduce a brand-new solve-for parameter — one consumed by aCustomDynamicModel— 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
valuewhenNone.- estimationstr, optional
"estimated"(default) or"considered".- dynamicsstr, optional
"static"(default, constant parameter) or"dynamic"(the parameter has its own ODE, supplied throughCustomParameter).- 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:
ValueErrorRaised when a custom parameter is re-registered with a different definition.
- exception ReservedComponentNameError#
Bases:
ValueErrorRaised when a custom parameter name collides with a built-in component.
- exception UnknownComponentError#
Bases:
ValueErrorRaised when a component name matches no allowed (built-in or custom) pattern.