nPlateModel#

class nPlateModel(plates_config_path=None, plates_data: dict = None)#

Bases: object

Defines a flat plate model used to represent the spacecraft structure for calculating solar radiation pressure acting on it.

The SRP force on a single plate of area \(A\) with reflectivity coefficient \(C_r\), illuminated at angle of incidence \(\theta\) from the sun, is

\[\mathbf{F}_{SRP} = \frac{P_{sun}\,A\cos\theta}{c} \bigl[(1 - C_r)\,\hat{\ell} + 2C_r\cos\theta\,\hat{n}\bigr]\]

where \(P_{sun}\) is the solar radiation pressure at 1 AU, \(c\) is the speed of light, \(\hat{\ell}\) is the unit sun-direction vector, and \(\hat{n}\) is the outward plate normal. The total SRP force on the spacecraft is the vector sum over all illuminated plates. A double-sided plate lit from behind is illuminated on its back face, so it acts as a plate with the opposite normal and the same coefficients; a single-sided plate lit from behind contributes nothing.

Parameters:
plates_config_pathstr or os.PathLike, optional

Path to a JSON file containing all necessary information to configure the N-plate model. See Notes section for more information on configuration file formatting.

plates_datadict, optional

The same configuration already in memory, with the keys the file would have held. Use this when the plate layout is assembled in a script, pulled from a database, or varied across a study, rather than living in a file on disk. Supply this or plates_config_path, not both.

The dictionary is copied, so the model does not alias the caller’s lists and later edits to it cannot silently change the spacecraft.

Attributes:
abs_ref_coeffs

The absorption coefficients of each plate in the N-plate model.

areas

The surface are of each plate in the N-plate model.

body_frame_plates

Whether each plate’s normal is given in the spacecraft body frame (a Fixed plate with no frame).

diff_ref_coeffs

The diffuse reflection coefficients of each plate in the N-plate model.

double_sided

Whether each plate is double-sided: lit from behind, it acts as a plate with the opposite normal.

frames

The frame each plate’s normal is constant in: None for the spacecraft body frame (oriented by the Spacecraft attitudeMode), otherwise a SPICE frame name or frame ID.

names

The names of each panel defined in the N-plate model.

normals

The normal vectors of each plate in the N-plate model.

plate_ids

The NAIF integer code for each plate in the N-plate model.

plate_types

The type of each plate in the N-plate model.

ref_coeffs

The reflectivity coefficients of each plate in the N-plate model.

spec_ref_coeffs

The specular reflection coefficients of each plate in the N-plate model.

Methods

from_dict(data)

Reconstruct an nPlateModel from a dict produced by to_dict().

get_all_normals(epoch, sc_id[, inertial_frame])

Queries the normal vectors of each panel in the N-plate model at a given epoch.

to_dict()

Serialize the plate configuration to a JSON-friendly dict.

Raises:
ConfigurationError

If neither or both sources are supplied, the configuration’s columns disagree on how many plates there are, or a frames or double sided entry is invalid.

See also

scarabaeus.Spacecraft

Assign an nPlateModel to a craft.

scarabaeus.nPlateSRP

Calculate solar radiation pressure.

Notes

The N-plate model requires a JSON file with the following properties:

  • names: an array of strings defining the name of each plate in the configuration.

  • areas: an array of numbers defining the area, in square kilometers, of each plate in the configuration.

  • ref coeffs: an array of numbers defining the reflectivity coefficient of each plate in the configuration.

  • abs coeffs: an array of numbers defining the absorption coefficient of each plate in the configuration.

  • dref coeffs: an array of numbers defining the diffuse reflection coefficient of each plate in the configuration.

  • sref coeffs: an array of numbers defining the specular reflection coefficient of each plate in the configuration.

  • normal vectors: an array of numerical 3-element arrays defining the components of the normal vector (u vector) for each plate in the configuration. For CK frames, the array defines the normal vector to be rotated by the quaternion derived from its respective C-kernel.

  • types: an array of strings where

    • "Fixed" defines a plate whose normal is constant in the frame given by frames, by default the spacecraft body frame. That frame is oriented by the Spacecraft attitudeMode; it is not an inertial frame.

    • "CK" defines a time-variant plate with associated reference frame defined by a SPICE C-matrix kernel.

  • ids: an array of integers and/or nulls, where

    • a null defines a Fixed plate — it has no NAIF integer code.

    • an integer defines the NAIF ID of a CK plate.

  • frames (optional): an array of strings, integers and/or nulls giving the frame a Fixed plate’s normal is constant in, where

    • a null is the spacecraft body frame (the default for every plate).

    • a string or integer is a SPICE frame name or frame ID; the normal is rotated out of that frame at each epoch, whatever the Spacecraft attitudeMode. Use this when a CK (through its frame kernel) or any other SPICE frame defines the bus orientation. CK plates must leave it null.

  • double sided (optional): an array of booleans, true for a plate that is also illuminated from behind (e.g. a solar array). Defaults to false for every plate, the right choice for bus faces, which would otherwise double their area seen from the Sun.

Note

The abs, dref, and sref must sum to unity for each plate.

Note

The two faces of a double-sided plate share its coefficients. A back face with different optical properties is a second, single-sided plate with the opposite normal.

Following this format, an example plate configuration file looks like:
{
    "names"          : ["plusX"  , "minusX"  , "SA1"    ],
    "areas"          : [10       , 10        , 10       ],
    "ref coeffs"     : [1.5      , 1.5       , 1.1      ],
    "abs coeffs"     : [0.33     , 0.33      , 0.33     ],
    "dref coeffs"    : [0.33     , 0.33      , 0.33     ],
    "sref coeffs"    : [0.34     , 0.34      , 0.34     ],
    "normal vectors" : [[1, 0, 0], [-1, 0, 0], [1, 0, 0]],
    "types"          : ["Fixed"  , "Fixed"   , "CK"     ],
    "ids"            : [null     , null      , -64001   ],
    "frames"         : [null     , null      , null     ],
    "double sided"   : [false    , false     , true     ]
}
classmethod from_dict(data: dict) → nPlateModel#

Reconstruct an nPlateModel from a dict produced by to_dict().

Parameters:
datadict

Serialized plate configuration.

Returns:
nPlateModel

The reconstructed model.

get_all_normals(epoch, sc_id: int, inertial_frame: str = 'J2000')#

Queries the normal vectors of each panel in the N-plate model at a given epoch.

Normals of plates in the spacecraft body frame (body_frame_plates) are returned as configured; the others, CK plates and Fixed plates in a named frame, are rotated into inertial_frame. A caller that knows the attitude maps the latter into the body frame with its transpose.

Parameters:
epochEpochArray

The epoch at which to query the C-kernel in ephemeris time (TDB) for all CK type panels in the model.

sc_idint

NAIF spacecraft ID code for the craft C-kernel plates are attached to. Required to convert to encoded SCLK ticks.

inertial_framestr, optional

The frame CK and named-frame normals are returned in. Defaults to "J2000".

Returns:
normalslist

A list of normals for each panel in the model.

Raises:
PlateOrientationError

If a CK plate or a Fixed plate’s named frame cannot be oriented at epoch.

to_dict() → dict#

Serialize the plate configuration to a JSON-friendly dict.

The dict holds exactly the keys a configuration file would, so it can be fed straight back to the constructor as plates_data (which is what from_dict() does). Areas are written as plain floats in \(km^2\), the units the constructor expects.

Returns:
dict

Serialized plate configuration.

property abs_ref_coeffs: list[float]#

The absorption coefficients of each plate in the N-plate model.

property areas: list[ArrayWUnits]#

The surface are of each plate in the N-plate model. Expressed in units of \(km^2\).

property body_frame_plates: list[bool]#

Whether each plate’s normal is given in the spacecraft body frame (a Fixed plate with no frame). get_all_normals() returns these normals as configured and the others in an inertial frame.

property diff_ref_coeffs: list[float]#

The diffuse reflection coefficients of each plate in the N-plate model.

property double_sided: list[bool]#

Whether each plate is double-sided: lit from behind, it acts as a plate with the opposite normal. Single-sided plates lit from behind contribute nothing.

property frames: list[str | int | None]#

The frame each plate’s normal is constant in: None for the spacecraft body frame (oriented by the Spacecraft attitudeMode), otherwise a SPICE frame name or frame ID. Always None for CK plates, whose orientation comes from their C-kernel.

property names: list[str]#

The names of each panel defined in the N-plate model.

property normals: list[ndarray]#

The normal vectors of each plate in the N-plate model.

property plate_ids: list[int | None]#

The NAIF integer code for each plate in the N-plate model. Fixed type plates have no associated ID, therefore all plate ID’s of the respective type are None. All CK type plate ID’s are given as int.

property plate_types: list[str]#

The type of each plate in the N-plate model. Either:

  • 'Fixed', representing a static plate.

  • 'CK', representing a time-variant plate, with reference frame defined by a SPICE C-matrix kernel.

property ref_coeffs: list[float]#

The reflectivity coefficients of each plate in the N-plate model.

property spec_ref_coeffs: list[float]#

The specular reflection coefficients of each plate in the N-plate model.

exception ConfigurationError#

Bases: ValueError

Raised when a plate configuration cannot define an N-plate model.

exception PlateOrientationError#

Bases: Exception

Raised when SPICE cannot orient a CK plate or a plate defined in a named frame.