3. 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 (CannonballSRP-style) 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)\,10^{-3},\]

where \(T(t)\) is thrust in Newtons, \(m(t)\) is spacecraft mass in kilograms, and the \(10^{-3}\) factor converts \(\mathrm{m/s^2}\) to \(\mathrm{km/s^2}\). 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.ra and maneuver.dec polynomials, they are evaluated directly.
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)\).

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_partial_by_direction`(position, ...)	Computes the partial derivatives of the acceleration with respect to the thrust direction components.
`compute_partial_by_k_thrust`(position, ...)	Computes the partial derivative of the spacecraft's acceleration with respect to the thrust magnitude (k_thrust) at a given epoch.
`compute_partial_by_position`(position, ...)	Computes the partial derivative of the finite burn acceleration with respect to the position vector.
`compute_partial_by_ra_dec_bias`(position, ...)	Computes the partial derivatives of the acceleration vector with respect to right ascension (RA) and declination (DEC) biases.
`compute_partial_by_thrust`(position, ...)	Computes the partial derivative of the spacecraft's acceleration with respect to thrust direction.
`evaluate_polynomial`(values, t)	Evaluates a 6th-order polynomial or returns a scalar value with units.

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.

compute_partial_by_direction(position, current_state, epoch, body) → ndarray#

Computes the partial derivatives of the acceleration with respect to the thrust direction components.

This method calculates the normalized acceleration magnitude based on the current thrust, spacecraft mass, and a thrust scaling parameter. It returns a diagonal matrix representing the partial derivatives of the acceleration with respect to each direction component.

Parameters:

position (np.ndarray) – The current position vector of the spacecraft (unused in this method).
current_state (dict) – The current state of the spacecraft, used to extract parameters.
epoch (float or compatible) – The current epoch or time at which the computation is performed.
body (object) – The celestial body object, used for parameter extraction.

Returns:

A 3x3 diagonal matrix containing the partial derivatives of the acceleration with respect to the thrust direction components, scaled appropriately.

Return type:

np.ndarray

compute_partial_by_k_thrust(position: ndarray, current_state: dict, epoch: float, body: Body) → ndarray#

Computes the partial derivative of the spacecraft’s acceleration with respect to the thrust magnitude (k_thrust) at a given epoch.

Parameters:

position (np.ndarray) – The current position vector of the spacecraft (unused in this method).
current_state (dict) – The current state dictionary containing possible perturbation parameters such as ‘dRA’ and ‘dDEC’.
epoch (float) – The current epoch (time) at which to evaluate the thrust and spacecraft mass.
body (Body) – The celestial body object providing context for the maneuver and parameter retrieval.

Returns:

A (3, 1) array representing the partial derivative of the acceleration vector with respect to the thrust magnitude, in km/s².

Return type:

np.ndarray

compute_partial_by_position(position, current_state, epoch, body) → ndarray#

Computes the partial derivative of the finite burn acceleration with respect to the position vector.

Parameters:

(np.ndarray) (current_state)
(np.ndarray)
datetime) (epoch (float or)
(object) (body)

Returns:

np.ndarray

Return type:

A 3x3 matrix representing the partial derivative of the acceleration with respect to the position vector.

compute_partial_by_ra_dec_bias(position: ndarray, current_state: dict, epoch: float, body: Body) → ndarray#

Computes the partial derivatives of the acceleration vector with respect to right ascension (RA) and declination (DEC) biases.

This method calculates the Jacobian matrix representing the sensitivity of the thrust acceleration direction to small changes in RA and DEC biases. The computation uses the current spacecraft state, epoch, and body parameters to evaluate the thrust, mass, and orientation.

Parameters:

position (np.ndarray) – The current position vector of the spacecraft (shape: (3,)).
current_state (dict) – Dictionary containing the current state parameters, including possible thrust scaling and RA/DEC biases.
epoch (float) – The current epoch (time) at which to evaluate the partial derivatives.
body (Body) – The celestial body object providing context for the maneuver.

Returns:

A (3, 2) Jacobian matrix where the first column is the partial derivative with respect to RA bias, and the second column is the partial derivative with respect to DEC bias.

Return type:

np.ndarray

compute_partial_by_thrust(position, current_state, epoch, body) → ndarray#

Computes the partial derivative of the spacecraft’s acceleration with respect to thrust direction.

Parameters:

position (np.ndarray) – The current position vector of the spacecraft (unused in this method).
current_state (dict) – The current state dictionary containing parameters for the spacecraft and environment.
epoch (astropy.time.Time or float) – The current epoch or time at which the computation is performed.
body (object) – The celestial body or environment context for the computation.

Returns:

The partial derivative vector (shape: (3,)) representing the effect of thrust direction on acceleration, in km/s².

Return type:

np.ndarray

Notes

The thrust direction is determined by the nominal right ascension and declination, with optional deviations (dRA, dDEC) from the current state.
The thrust magnitude is scaled by k_thrust and normalized by the spacecraft mass at the given epoch.
The result is scaled by 1e-3 to convert units if necessary.

evaluate_polynomial(values, t)#

Evaluates a 6th-order polynomial or returns a scalar value with units.

Parameters:

values (ArrayWUnits) – An object containing the polynomial coefficients or a scalar value, along with associated units. If values.values is a scalar (float or int), it is returned as is. If values.values is a sequence (list, tuple, np.ndarray, or ArrayBox) of length 7, it is interpreted as the coefficients of a 6th-order polynomial in descending order of degree.
t (float or int) – The value at which to evaluate the polynomial.

Returns:

The evaluated polynomial (or scalar value) with the same units as the input.

Return type:

ArrayWUnits

Raises:

ValueError – If values.values is a sequence but does not contain exactly 7 elements.

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.

3. FiniteBurn#

This Page