FiniteBurn#
- class FiniteBurn(spacecraft: Spacecraft, base_frame: Frame, maneuver: Maneuver)#
Bases:
DynamicModelModels 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:
If the maneuver object provides
maneuver.raandmaneuver.decpolynomials, they are evaluated directly.Otherwise, the direction is derived from the evaluated direction-component polynomials
maneuver.ux,maneuver.uy,maneuver.uzby 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
thrustand either theraanddecpolynomials, or theux,uy,uzdirection-component polynomials.
- Attributes:
ddec_mapCaller-supplied declination bias overrides, in rad, keyed by owner
spice_id.dra_mapCaller-supplied right-ascension bias overrides, in rad, keyed by owner
spice_id.estimable_parameter_namesNames of estimable parameters handled by this model.
has_direction_anglesTrue if maneuver provides ra/dec polynomials directly; otherwise direction is derived from ux/uy/uz.
k_thrust_mapCaller-supplied thrust scale-factor overrides (unitless), keyed by owner
spice_id.ref_frameReference frame in which the finite-burn acceleration is expressed.
spacecraftSpacecraft 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.CannonballSRPReads an estimable SRP scale factor from the state the same way.
scarabaeus.ManeuverProvides maneuver polynomials for thrust magnitude and direction.
scarabaeus.SpacecraftProvides mass model required for thrust-to-acceleration conversion.
scarabaeus.ImpulsiveBurnInstantaneous 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 intok_thrust_map,dra_maporddec_map, (3) an indexed entry such as("k_thrust1", spice_id)incurrent_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_stateholds 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_stateholds 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_stateholds no("k_thrust", spice_id)entry (see_get_param()).
- property spacecraft: Spacecraft#
Spacecraft providing the mass model used to convert thrust to acceleration.