FiniteBurn#

class FiniteBurn(spacecraft: Spacecraft, base_frame: Frame, maneuver: Maneuver, state_vector: StateArray)#

Bases: DynamicModel

Models the acceleration induced by a finite-duration burn with estimable thrust magnitude and pointing-bias parameters.

This model represents a continuous thrust arc in which the spacecraft acceleration is computed from the commanded thrust magnitude, the spacecraft mass, and the thrust direction. In addition to the nominal maneuver polynomials, the model supports three estimable parameters retrieved from the StateArray and optionally overridden at runtime through current_state:

  • k_thrust (unitless): multiplicative scale factor on thrust magnitude.

  • dRA (rad): additive right-ascension bias applied to the nominal thrust direction.

  • dDEC (rad): additive declination bias applied to the nominal thrust direction.

The acceleration is computed as

\[\mathbf{a}(t) = \frac{k_{\mathrm{thrust}}\,T(t)}{m(t)}\,\hat{\mathbf{u}}(t)\]

where \(T(t)\) is the thrust magnitude in kN and \(m(t)\) is spacecraft mass in kg; dividing kN by kg gives km/s² directly. The unit direction \(\hat{\mathbf{u}}(t)\) is formed from biased angles

\[\alpha(t) = \alpha_0(t) + d\alpha,\qquad \delta(t) = \delta_0(t) + d\delta,\]

with

\[\begin{split}\hat{\mathbf{u}}(\alpha,\delta) = \begin{bmatrix} \cos\delta\cos\alpha \\ \cos\delta\sin\alpha \\ \sin\delta \end{bmatrix}.\end{split}\]

The nominal angles \((\alpha_0,\delta_0)\) are obtained in one of two ways:

  1. If the maneuver object provides maneuver.ra and maneuver.dec polynomials, they are evaluated directly.

  2. Otherwise, the direction is derived from the evaluated direction-component polynomials maneuver.ux, maneuver.uy, maneuver.uz by normalization and conversion to \((\alpha_0,\delta_0)\).

Parameters:

  • spacecraft (Spacecraft) – Spacecraft object providing the mass model spacecraft.mass(epoch) used in the thrust-to-acceleration conversion.

  • base_frame (Frame) – Reference frame in which the burn acceleration is returned.

  • maneuver (Maneuver) –

    Maneuver definition providing thrust magnitude and direction polynomials. Required fields are thrust and either:

    • ra and dec polynomials, or

    • ux, uy, uz direction-component polynomials.

  • state_vector (StateArray) – StateArray used to initialize cached defaults for k_thrust, dRA, and dDEC (keyed by owner spice_id).

Notes

During initialization, the class scans the provided StateArray and caches default values for each estimable parameter keyed by the owner’s spice_id. Expected state entries are of the form:

("k_thrust", 1, "estimated", "static", owner, ArrayWUnits(1.0, None))
("dRA",      1, "estimated", "static", owner, ArrayWUnits(0.0, "rad"))
("dDEC",     1, "estimated", "static", owner, ArrayWUnits(0.0, "rad"))

At runtime the parameter resolution priority is: (1) cached initialization values, (2) current_state[(name, spice_id)] if present (allowing filter/OD updates), (3) a conservative fallback (k_thrust=1, dRA=0, dDEC=0).

The model provides analytic partial derivatives: \(\partial\mathbf{a}/\partial k_{\mathrm{thrust}}\) (3×1) and \(\partial\mathbf{a}/\partial[d\alpha\; d\delta]\) (3×2). The acceleration is position-independent, so _compute_partial_by_position() returns zeros.

The RA/DEC bias parameterization becomes ill-conditioned near the poles (\(\cos\delta \to 0\)). If near-polar thrusting is expected, a local tangent-plane perturbation may be preferable.

See also

scarabaeus.CannonballSRP

Uses the same StateArray-scan pattern for an estimable SRP scale factor.

scarabaeus.Maneuver

Provides maneuver polynomials for thrust magnitude and direction.

scarabaeus.Spacecraft

Provides mass model required for thrust-to-acceleration conversion.

scarabaeus.ImpulsiveBurn

Instantaneous delta-v model.

Examples

import scarabaeus as scb

# Define estimable parameters in the state
state = [
    ("position", 3, "estimated", "dynamic", sc, scb.ArrayWUnits([7000, 0, 0], "km")),
    ("velocity", 3, "estimated", "dynamic", sc, scb.ArrayWUnits([0, 7.5, 0], "km/s")),
    ("k_thrust", 1, "estimated", "static",  sc, scb.ArrayWUnits(1.0, None)),
    ("dRA",      1, "estimated", "static",  sc, scb.ArrayWUnits(0.0, "rad")),
    ("dDEC",     1, "estimated", "static",  sc, scb.ArrayWUnits(0.0, "rad")),
]
state_vector = scb.StateArray(epoch=epochs[0], frame="J2000", origin=scb.CelestialBody("Earth"), state=state)

# Create the model
fb = FiniteBurn(spacecraft=sc, base_frame="J2000", maneuver=man, state_vector=state_vector)

# During OD/filtering, override values through current_state:
current_state = {
    ("k_thrust", sc.spice_id): 0.98,
    ("dRA",      sc.spice_id): 2e-4,
    ("dDEC",     sc.spice_id): -1e-4,
}
a = fb.compute_acceleration(position=r_sc, current_state=current_state, epoch=t, body=sc)
Attributes:
ddec_map

Cached default DEC biases (rad) keyed by owner spice_id.

dra_map

Cached default RA biases (rad) keyed by owner spice_id.

estimable_parameter_names

Names of estimable parameters handled by this model.

has_direction_angles

True if maneuver provides ra/dec polynomials directly; otherwise direction is derived from ux/uy/uz.

k_thrust_map

Cached default thrust scale factors (unitless) keyed by owner spice_id.

ref_frame

Reference frame in which the finite-burn acceleration is expressed.

spacecraft

Spacecraft providing the mass model used to convert thrust to acceleration.

state_vector

StateArray used to initialize cached estimable-parameter defaults.

Methods

compute_acceleration(position, ...)

Compute the acceleration vector due to finite burn thrust.
compute_acceleration(position: ndarray, current_state: dict, epoch: float, body: CelestialBody) → ndarray#

Compute the acceleration vector due to finite burn thrust.

Parameters:

  • position (np.ndarray) – Position vector (not directly used in calculation).

  • current_state (dict) – Dictionary containing estimable parameters including thrust scaling factor and thrust direction offsets.

  • epoch (float) – Epoch at which to evaluate thrust and spacecraft mass.

  • body (CelestialBody) – Celestial body reference for parameter lookup.

Returns:

Acceleration vector in km/s^2 due to thrust.

Return type:

np.ndarray

Notes

The method computes thrust acceleration using a cannonball-style model with estimable parameters: - k_thrust: thrust magnitude scaling factor (default 1.0) - dRA: right ascension offset (default 0.0 rad) - dDEC: declination offset (default 0.0 rad)

The thrust direction is specified in RA/DEC coordinates and combined with the nominal thrust direction to obtain the final acceleration vector.

property ddec_map: dict[int, float]#

Cached default DEC biases (rad) keyed by owner spice_id.

property dra_map: dict[int, float]#

Cached default RA biases (rad) keyed by owner spice_id.

property estimable_parameter_names: tuple[str, ...]#

Names of estimable parameters handled by this model.

property has_direction_angles: bool#

True if maneuver provides ra/dec polynomials directly; otherwise direction is derived from ux/uy/uz.

property k_thrust_map: dict[int, float]#

Cached default thrust scale factors (unitless) keyed by owner spice_id.

property ref_frame: Frame#

Reference frame in which the finite-burn acceleration is expressed.

property spacecraft: Spacecraft#

Spacecraft providing the mass model used to convert thrust to acceleration.

property state_vector: StateArray#

StateArray used to initialize cached estimable-parameter defaults.