FiniteBurn#

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

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 read from the propagated state 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^2 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:
spacecraftSpacecraft

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

base_frameFrame

Reference frame in which the burn acceleration is returned.

maneuverManeuver

Maneuver definition providing thrust magnitude and direction polynomials. Required fields are thrust and either the ra and dec polynomials, or the ux, uy, uz direction-component polynomials.

Attributes:
ddec_map

Caller-supplied declination bias overrides, in rad, keyed by owner spice_id.

dra_map

Caller-supplied right-ascension bias overrides, in 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

Caller-supplied thrust scale-factor overrides (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.

Methods

compute_acceleration(position, ...)

Compute the acceleration vector due to finite burn thrust.

See also

scarabaeus.CannonballSRP

Reads an estimable SRP scale factor from the state the same way.

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.

Notes

The estimable parameters are read from the propagated state on every evaluation, keyed by (name, spice_id) of the owner. 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"))

The parameter resolution priority is (see _get_param()): (1) current_state[(name, spice_id)] if present, (2) a value a caller pushed into k_thrust_map, dra_map or ddec_map, (3) an indexed entry such as ("k_thrust1", spice_id) in current_state, (4) a conservative fallback (k_thrust=1, dRA=0, dDEC=0).

The model provides analytic partial derivatives: \(\partial\mathbf{a}/\partial k_{\mathrm{thrust}}\) of shape (3, 1) and \(\partial\mathbf{a}/\partial[d\alpha,\ d\delta]\) of shape (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.

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)

# 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)
compute_acceleration(position: ndarray, current_state: dict, epoch: float, body: CelestialBody) → ndarray#

Compute the acceleration vector due to finite burn thrust.

Parameters:
positionnp.ndarray

Position vector (not directly used in calculation).

current_statedict

Dictionary containing estimable parameters including thrust scaling factor and thrust direction offsets.

epochfloat

Epoch at which to evaluate thrust and spacecraft mass.

bodyCelestialBody

Celestial body reference for parameter lookup.

Returns:
np.ndarray

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

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

Caller-supplied declination bias overrides, in rad, keyed by owner spice_id.

Empty by default; an entry here is used only when current_state holds no ("dDEC", spice_id) entry (see _get_param()).

property dra_map: dict[int, float]#

Caller-supplied right-ascension bias overrides, in rad, keyed by owner spice_id.

Empty by default; an entry here is used only when current_state holds no ("dRA", spice_id) entry (see _get_param()).

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

Caller-supplied thrust scale-factor overrides (unitless), keyed by owner spice_id.

Empty by default; an entry here is used only when current_state holds no ("k_thrust", spice_id) entry (see _get_param()).

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.