nPlateSRP#

class nPlateSRP(origin: CelestialBody, spacecraft: Spacecraft, base_frame: Frame, t0: float = None, tf: float = None)#

Bases: DynamicModel

Models the acceleration due to Solar Radiation Pressure (SRP) using an N-plate model.

The spacecraft is decomposed into \(N\) flat plates, each with its own area, surface normal, specular reflectivity \(\rho_s\), and diffuse reflectivity \(\rho_d\). For each illuminated plate \(i\) (i.e., \(\hat{\mathbf{n}}_i \cdot \hat{\mathbf{s}} > 0\)), the SRP acceleration contribution is:

\[\mathbf{a}_i = -\frac{\nu\, P_\odot}{m} \left(\frac{r_\odot}{r}\right)^2 A_i \left(\hat{\mathbf{n}}_i \cdot \hat{\mathbf{r}}_\odot\right) \left[ (1 - \rho_s)\,\hat{\mathbf{r}}_\odot + 2\rho_s \left(\hat{\mathbf{n}}_i \cdot \hat{\mathbf{r}}_\odot\right) \hat{\mathbf{n}}_i + \tfrac{2}{3}\rho_d\,\hat{\mathbf{n}}_i \right]\]

where \(\nu\) is the shadow factor (0 in eclipse, 1 in full Sun), \(P_\odot\) is the solar radiation pressure at 1 AU, \(r_\odot / r\) is the inverse-square scaling with heliocentric distance, and \(\hat{\mathbf{r}}_\odot\) is the unit vector from the spacecraft to the Sun (direction of incoming radiation); the dot product \(\hat{\mathbf{n}}_i \cdot \hat{\mathbf{r}}_\odot > 0\) selects illuminated plates, and the leading minus sign yields acceleration directed away from the Sun. The total acceleration is:

\[\mathbf{a}_\text{SRP} = \eta_\text{SRP} \sum_{i=1}^{N} \mathbf{a}_i\]

where \(\eta_\text{SRP}\) is an estimable scale factor (default 1) retrieved from the state vector via a ("eta_srp", spice_id) entry and can be solved for in the OD process.

A double-sided plate (nPlateModel.double_sided) lit from behind (\(\hat{\mathbf{n}}_i \cdot \hat{\mathbf{r}}_\odot < 0\)) contributes as a plate with normal \(-\hat{\mathbf{n}}_i\).

Plates in the spacecraft body frame (Fixed plates without a frame) are oriented by the spacecraft attitudeMode (see DynamicalUtils): a C-kernel, an inertially fixed DCM, or nadirPointingSun. The nadir attitude follows the spacecraft state, so its position partial carries the attitude terms and its velocity partial is non-zero (depends_on_velocity). CK plates and Fixed plates in a named SPICE frame are oriented by SPICE alone, so their contribution does not depend on the attitudeMode; a model with no body-frame plate needs none. The two groups can be mixed under any attitude (a nadir-pointed bus with solar arrays on their own CK, say): each is summed in its own frame.

Parameters:
originCelestialBody

Propagation origin. Used for the Sun-relative geometry; the estimable eta_srp is read from the propagated state at evaluation time.

spacecraftSpacecraft

The spacecraft containing physical and plate model properties.

Attributes:
P_SRP

The precomputed SRP constant for scaling factors.

area

The total surface area of the spacecraft.

depends_on_velocity

Whether the acceleration depends on the spacecraft velocity.

eta_srp

The SRP scale factor.

frame

The reference frame in which SRP calculations are performed.

origin

The celestial body that serves as the origin for the state vector.

origin_name

The name of the origin body.

plate_model

The associated nPlateModel used to calculate SRP.

ref_coeff

The reflectivity coefficient of the spacecraft.

spacecraft

The spacecraft associated with the SRP model.

Methods

compute_acceleration(position, ...)

Computes the acceleration due to solar radiation pressure (SRP) based on the n-plate model.

inertial_to_body_DCM(epoch[, tol])

Computes the Direction Cosine Matrix (DCM) to transform vectors from the inertial frame to the spacecraft-fixed frame.

Raises:
ValueError

If any plate area in the n-plate model is not expressed in km^2.

See also

scarabaeus.StateArray

Represents state vectors with origins and reference frames.

scarabaeus.Spacecraft

Defines spacecraft properties including mass and area.

scarabaeus.Propagator

Uses this model when nPlate_SRP = True.

scarabaeus.CannonballSRP

Lower fidelity model for calculating SRP.

Notes

The Sun’s position is retrieved dynamically from SPICE data.

References

[1]

P. W. Kenneally, “High geometric fidelity solar radiation pressure modeling via graphics processing unit,” Master’s thesis, Colorado Boulder, 2016.

compute_acceleration(position: ndarray, current_state: dict, epoch: float, body: Spacecraft) → ndarray#

Computes the acceleration due to solar radiation pressure (SRP) based on the n-plate model.

Calculates the contribution of each spacecraft plate to the total acceleration, considering reflection, absorption, and the relative orientation of the spacecraft with respect to the Sun. The plate sums and the SC-fixed -> inertial mapping run in rust (NPlateSRPCore), one core per plate group (body frame; CK and named frame), summed.

Parameters:
positionnp.ndarray

3x1 vector describing the spacecraft’s position. Assumed in units of kilometers.

current_statedict

Dictionary containing the current state parameters.

epochfloat

Current simulation epoch in seconds.

bodySpacecraft

The spacecraft for which SRP acceleration is calculated.

Returns:
total_srp_accnp.ndarrays

3x1 vector describing the total SRP acceleration. Assumed in units of \(\frac{km}{s^2}\).

Raises:
RustCoreUnavailableError

If the rust extension is not available.

AutogradTracingError

If autograd is tracing position or eta_srp.

inertial_to_body_DCM(epoch: EpochArray, tol: int = 50) → float#

Computes the Direction Cosine Matrix (DCM) to transform vectors from the inertial frame to the spacecraft-fixed frame.

Parameters:
epochEpochArray

The current epoch given in ephemeris time (seconds past J2000).

tolint, optional

The time tolerance for retrieving attitude and angular velocity from the specified spacecraft clock time. Defaults to 50.

Returns:
dcmnp.ndarray

The DCM for transforming inertial vectors to spacecraft-fixed coordinates.

Notes

The epoch parameter is converted from ephemeris time to continuous encoded spacecraft clock “ticks”. Due to this, the time tolerance should be given as sclock ticks and not seconds.

property P_SRP: float#

The precomputed SRP constant for scaling factors. Expressed in units of \(\frac{N}{m^2}\).

property area: float#

The total surface area of the spacecraft. Expressed in units of square meters.

property depends_on_velocity: bool#

Whether the acceleration depends on the spacecraft velocity.

True only for the nadirPointingSun attitude, where the spacecraft Y axis follows the heliocentric velocity, and only when some plate is in the body frame.

property eta_srp: float#

The SRP scale factor. Unitless.

property frame: str#

The reference frame in which SRP calculations are performed.

property origin: Body#

The celestial body that serves as the origin for the state vector.

property origin_name: str#

The name of the origin body.

property plate_model: nPlateModel#

The associated nPlateModel used to calculate SRP.

property ref_coeff: float#

The reflectivity coefficient of the spacecraft. Unitless.

property spacecraft: Spacecraft#

The spacecraft associated with the SRP model.

exception AutogradTracingError#

Bases: Exception

Autograd is tracing the acceleration through the Rust kernels.

The autograd NumPy backend (UseAutoGrad=TRUE) is fine on its own — the model runs on plain arrays under it. Only a traced position or eta_srp cannot pass into Rust. The partials are verified by the Rust dual-number differentiation instead (NPlateSRPCore.compute_partials_ad), which is what check_force_model_partials=TRUE runs.

exception RustCoreUnavailableError#

Bases: Exception

The rust N-plate SRP core is unavailable.

Raised by the compute and partial methods when _rust_cores could not be built because the extension is not importable. The Rust kernels are the only implementation of the acceleration and its position partial.