# N-Plate Model and Spacecraft Attitude#
Scarabaeus | Last revised 2026
What this notebook covers#
Two tightly related topics: the N-Plate SRP model which requires attitude data from SPICE C-kernels to orient solar array panels, and the spacecraft attitude interface used to extract orientation quaternions directly from C-kernels. Both are demonstrated using the OSIRIS-REx mission.
Topics#
# |
Topic |
|---|---|
1 |
N-Plate Model — construction from a configuration file |
2 |
N-Plate Model — examining CK panel intervals |
3 |
N-Plate Model — querying time-varying normal vectors |
4 |
N-Plate Model — static normals and spacecraft integration |
5 |
Spacecraft Attitude — quaternion history from a C-kernel |
How to run#
Run from the project root directory (scarabaeus/).
0. Imports and Setup#
[1]:
import scarabaeus as scb
import supplementary as supp
from pathlib import Path
import numpy as np
# load tutorial data
data = supp.load_data()
# define units and fraes
km, hr, sec, kg = scb.Units.get_units(['km', 'hr', 'sec', 'kg'])
J2000 = scb.Frame('J2000')
# ── kernel pool (SC body CK + solar array CK + ephemeris) ─────────
scb.SpiceManager.clear_kernels()
scb.SpiceManager.load_kernel_from_mkfile(data.OREx_mk.path)
SCB supplementary data out of date.
---------------------------------------------------------------------------
StdinNotImplementedError Traceback (most recent call last)
Cell In[1], line 8
4 from pathlib import Path
5 import numpy as np
6
7 # load tutorial data
----> 8 data = supp.load_data()
9
10 # define units and fraes
11 km, hr, sec, kg = scb.Units.get_units(['km', 'hr', 'sec', 'kg'])
File ~/scb_public/scarabaeus/docs/online_documentation/sphinx_files/_collections/tutorials/supplementary/supp_data.py:433, in load_data()
431 waiting = True
432 while waiting:
--> 433 response = input("\nDownload and generate missing files? (y/n): ")
434 match response.strip().lower():
435 case "y":
File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/ipykernel/kernelbase.py:1514, in Kernel.raw_input(self, prompt)
1512 if not self._allow_stdin:
1513 msg = "raw_input was called, but this frontend does not support input requests."
-> 1514 raise StdinNotImplementedError(msg)
1515 return self._input_request(
1516 str(prompt),
1517 self._get_shell_context_var(self._shell_parent_ident),
1518 self.get_parent("shell"),
1519 password=False,
1520 )
StdinNotImplementedError: raw_input was called, but this frontend does not support input requests.
1. N-Plate Model#
The N-Plate SRP model represents a spacecraft’s solar-radiation-pressure geometry as a finite set of flat plates, each with its own area, reflectivity coefficients, and surface normal. Panels can be fixed in the spacecraft body frame or attitude-driven by a SPICE C-kernel (CK), as is the case for articulated solar arrays.
The model is constructed from a JSON configuration file that specifies each panel’s physical properties and SPICE frame ID. The two meta-kernel types loaded above are:
Kernel type |
Purpose |
|---|---|
CK (spacecraft body) |
Main-bus attitude → body-frame orientation in J2000 |
CK (solar arrays) |
Solar-panel articulation → time-varying panel normals |
Constructing the Model#
Examining CK Panel Intervals#
SpiceManager.ckbrief inspects a binary C-kernel and returns the SPICE frame IDs and their valid time intervals. The N-plate configuration defines panels -64017 and -64027 (OSIRIS-REx solar arrays), which are plates 3 and 4 in the CK. Both share the same interval, so we take the first entry to get the query bounds.
[2]:
# ── build N-plate model from configuration JSON ───────────────────
n_model = scb.nPlateModel(data.OREx_nplate.path)
print(n_model)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[2], line 2
1 # ── build N-plate model from configuration JSON ───────────────────
----> 2 n_model = scb.nPlateModel(data.OREx_nplate.path)
3 print(n_model)
NameError: name 'data' is not defined
Querying Time-Varying Normal Vectors#
nPlateModel._get_ck_normals(epoch, sc_id) returns the inertially-expressed unit normals for all CK-driven panels at a given epoch. sc_id is the spacecraft NAIF ID needed to convert the epoch to spacecraft-clock ticks (SCLK) internally.
[3]:
# ── inspect C-kernel for solar array panel intervals ─────────────
brief = scb.SpiceManager.ckbrief(data.OREx_ck_sa.path, disp=True)
# panels -64017 and -64027 share the same valid interval → take first entry
plate4 = brief[0]
start, end = plate4['TDB_INTERVAL'][0][0], plate4['TDB_INTERVAL'][0][1]
print(f"\nQuery interval: {start} → {end}")
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[3], line 2
1 # ── inspect C-kernel for solar array panel intervals ─────────────
----> 2 brief = scb.SpiceManager.ckbrief(data.OREx_ck_sa.path, disp=True)
3
4 # panels -64017 and -64027 share the same valid interval → take first entry
5 plate4 = brief[0]
NameError: name 'data' is not defined
The plot below shows how the two solar-array normals (ORX_SA_PY_IG and ORX_SA_NY_IG) rotate over the queried interval. The interactive version lets you scrub through time; the inline version renders statically for documentation.
[4]:
# ── query CK normals every half-hour across the full interval ─────
orex_id = -64 # NAIF SC ID for SCLK
dt = scb.ArrayWUnits(0.5, hr)
times = scb.EpochArray.interval(start.to(rep = 'NUM'), end.to(rep ='NUM'), dt)
normals = [n_model._get_ck_normals(t, orex_id) for t in times]
print(f"{len(normals)} epochs queried, {len(normals[0])} CK panels per epoch")
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[4], line 3
1 # ── query CK normals every half-hour across the full interval ─────
2 orex_id = -64 # NAIF SC ID for SCLK
----> 3 dt = scb.ArrayWUnits(0.5, hr)
4 times = scb.EpochArray.interval(start.to(rep = 'NUM'), end.to(rep ='NUM'), dt)
5
6 normals = [n_model._get_ck_normals(t, orex_id) for t in times]
NameError: name 'hr' is not defined
Plotting Normal Vectors#
Note:
%matplotlib widgetmakes the figure interactive (time slider).
[6]:
%matplotlib inline
# NOTE: rerun static version of the plot so that it displays for online tutorial
supp.plotting.plot_normals(normals, times)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[6], line 3
1 get_ipython().run_line_magic('matplotlib', 'inline')
2 # NOTE: rerun static version of the plot so that it displays for online tutorial
----> 3 supp.plotting.plot_normals(normals, times)
NameError: name 'normals' is not defined
Static Normals at a Single Epoch#
nPlateModel.get_all_normals(epoch, sc_id) returns normals for all panels — both fixed body-frame plates and CK-driven plates — resolved into the inertial frame at a single epoch. This is the call the propagator uses internally at each integration step.
[7]:
# ── all normals (fixed + CK) at the start of the interval ────────
all_norms = n_model.get_all_normals(start, orex_id)
print("Panel normals at epoch start:")
for i, n in enumerate(all_norms):
print(f" Plate {i+1}: {np.array(n).round(4)}")
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[7], line 2
1 # ── all normals (fixed + CK) at the start of the interval ────────
----> 2 all_norms = n_model.get_all_normals(start, orex_id)
3 print("Panel normals at epoch start:")
4 for i, n in enumerate(all_norms):
5 print(f" Plate {i+1}: {np.array(n).round(4)}")
NameError: name 'n_model' is not defined
Attaching to a Spacecraft#
Pass n_plate_model to Spacecraft to activate N-plate SRP in the force model. get_dependent_spice_ids() lists every SPICE frame ID that the model depends on — useful for verifying all required CK/FK kernels are loaded before propagation.
[8]:
# ── attach N-plate model to spacecraft ────────────────────────────
orex = scb.Spacecraft(
'OSIRIS-REx', -64,
scb.ArrayWUnits(0, kg),
n_plate_model=n_model,
)
print("Spacecraft SPICE IDs required by the N-plate model:")
print(orex.get_dependent_spice_ids())
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[8], line 4
1 # ── attach N-plate model to spacecraft ────────────────────────────
2 orex = scb.Spacecraft(
3 'OSIRIS-REx', -64,
----> 4 scb.ArrayWUnits(0, kg),
5 n_plate_model=n_model,
6 )
7
NameError: name 'kg' is not defined
2. Spacecraft Attitude#
Spacecraft.get_attitude(frame, et) queries the C-kernel and returns the orientation of the spacecraft body frame as a unit quaternion \([q_0,\, q_1,\, q_2,\, q_3]\) at the given epoch. This wraps the underlying SPICE ckgpav / m2q calls and expresses the result in the requested inertial frame.
The example below extracts the quaternion history for OSIRIS-REx over a five-day window and plots all four components.
[9]:
# ── attitude query over a 5-day window ───────────────────────────
et_start = scb.SpiceManager.str2et("2021 AUG 17 12:00:00 UTC")
et_end = scb.SpiceManager.str2et("2021 AUG 22 08:00:00 UTC")
step_sec = 20 # sample every 20 s
et_arr = np.arange(et_start, et_end, step_sec)
# reuse the spacecraft defined in §1 (orex already has the N-plate model)
attitudes = [orex.get_attitude(J2000, et) for et in et_arr]
attitudes = np.array(attitudes) # shape: (N, 4)
print(f"Queried {len(attitudes)} attitude epochs")
print(f"First quaternion [q0 q1 q2 q3] : {attitudes[0].round(6)}")
print(f"Norm check (should be 1.0) : {np.linalg.norm(attitudes[0]):.8f}")
---------------------------------------------------------------------------
SpiceNOLEAPSECONDS Traceback (most recent call last)
Cell In[9], line 2
1 # ── attitude query over a 5-day window ───────────────────────────
----> 2 et_start = scb.SpiceManager.str2et("2021 AUG 17 12:00:00 UTC")
3 et_end = scb.SpiceManager.str2et("2021 AUG 22 08:00:00 UTC")
4 step_sec = 20 # sample every 20 s
5
File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/SpiceManager.py:2166, in SpiceManager.str2et(s)
2148 @staticmethod
2149 def str2et(s: str) -> float:
2150 """Convert a time string to ephemeris time (TDB seconds past J2000).
2151
2152 Thin wrapper around ``spice.str2et``. Accepts a wide range of
(...) 2164 TDB seconds past J2000 corresponding to *s*.
2165 """
-> 2166 return spice.str2et(s)
File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/spiceypy/spiceypy.py:161, in spice_error_check.<locals>.with_errcheck(*args, **kwargs)
157 res = f(*args, **kwargs)
158 check_for_spice_error(f)
159 return res
160 except BaseException:
--> 161 raise
File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/spiceypy/spiceypy.py:141, in check_for_spice_error(f)
137 explain = getmsg("EXPLAIN", 100).strip()
138 long = getmsg("LONG", 1841).strip()
139 traceback = qcktrc(200)
140 reset()
--> 141 raise dynamically_instantiate_spiceyerror(
142 short=short, explain=explain, long=long, traceback=traceback
143 )
SpiceNOLEAPSECONDS:
================================================================================
Toolkit version: CSPICE_N0067
SPICE(NOLEAPSECONDS) --
The variable that points to the leapseconds (DELTET/DELTA_AT) could not be located in the kernel pool. It is likely that the leapseconds kernel has not been loaded.
str2et_c --> STR2ET --> TTRANS
================================================================================