`Utils`#

class Utils#

Bases: object

Collection of general-purpose utility methods used throughout Scarabaeus.

Provides static helpers for array manipulation, file I/O, and Verification-and-Validation (V&V) trajectory comparison against SPICE ground-truth kernels.

See also

scarabaeus.SpiceManager: SPICE kernel interface used by the V&V methods.
scarabaeus.EpochArray: Time-tag array type accepted by several helpers.

Methods

`VandV_compare`(positions, velocities, times, ...)	Compare a Scarabaeus-generated trajectory against a SPICE ground truth.
`VandV_plot_errors`(errorPosition, ...)	Plot position and velocity errors in a standardised V&V layout.
`build_reorder_operator`(old_list, new_list)	Build the `Q` selection/reorder operator mapping the old state to the new.
`check_slices_equal`(arr)	Checks if all slices are equal across an array.
`enumerate_state_blocks`(state_list)	Enumerate the scalar blocks of a state definition with a rich key.
`equal_along_rows`(arr)	Check equality along rows of the given array.
`find_date_indices_in_epochs`(epochsTDB, ...)	Find the index or indices of target date(s) in a numpy array of epochs, accounting for floating-point precision.
`load_json`(dir[, print_flag])	Load and parse a JSON file from disk.
`make_dir`(dir)	Generate a folder in the given directory.
`max_of_last_slice`(arr)	Finds the maximum value of the last slice of an array.
`open_pickle`(dir)	Return a pickle object handle from dir.
`reorder_covariance`(Q, P[, new_block_variances])	Reorder a covariance: `P' = Q P Q^T`, with a-priori variances for new states.
`reorder_stm`(Q, STM[, new_blocks])	Reorder a State Transition Matrix: `Phi' = Q Phi Q^T`.
`reorder_vector`(Q, x)	Apply the reorder operator to a state / deviation vector: `X' = Q X`.
`tile_array`(arr, desired_shape)	Construct an array by repeating A the number of times given by reps.

static VandV_compare(positions: ndarray, velocities: ndarray, times: EpochArray, caseId: str, integratorName: str, flag_SUN: bool = False, leg1_period=None, leg2_period=None)#

Compare a Scarabaeus-generated trajectory against a SPICE ground truth.

Loads the SPICE BSP kernel for caseId, queries the reference state at each epoch in times, computes the component-wise and norm errors, prints a summary to stdout, and delegates plotting to VandV_plot_errors().

Parameters:

positions (numpy.ndarray) – Spacecraft positions from Scarabaeus, shape (N, 3) in km.
velocities (numpy.ndarray) – Spacecraft velocities from Scarabaeus, shape (N, 3) in km/s.
times (EpochArray) – Epoch array of length N corresponding to each state sample.
caseId (str) – Scenario identifier; used to locate the BSP kernel at <cwd>/data/kernels/validation/<caseId>.bsp.
integratorName (str) – Integration scheme label, printed in the summary and plot titles.
flag_SUN (bool, optional) – When True uses the Sun as the inertial origin; otherwise uses Earth. Defaults to False.
leg1_period (ArrayWUnits or None, optional) – Duration of the first trajectory leg in seconds. Required for multi-leg cases (MONTE_case17a/b/c); None otherwise.
leg2_period (ArrayWUnits or None, optional) – Duration of the second trajectory leg in seconds. Required for multi-leg cases; None otherwise.

Returns:

figHandle (matplotlib.figure.Figure) – Handle to the V&V error plot.
max_state_error_norm_pos (float) – Maximum position error norm over the trajectory in km.
max_state_error_norm_vel (float) – Maximum velocity error norm over the trajectory in km/s.

static VandV_plot_errors(errorPosition: ndarray, errorVelocity: ndarray, times: EpochArray, caseId: str, integratorName: str)#

Plot position and velocity errors in a standardised V&V layout.

Produces a two-panel figure with position error (top) and velocity error (bottom) as functions of elapsed time in days.

Parameters:

errorPosition (numpy.ndarray) – Position error array of shape (N, 3) in km, computed as positions_scb - positions_truth.
errorVelocity (numpy.ndarray) – Velocity error array of shape (N, 3) in km/s, computed as velocities_scb - velocities_truth.
times (EpochArray) – Epoch array of length N corresponding to each error sample.
caseId (str) – Scenario identifier used as the plot title prefix.
integratorName (str) – Integration scheme label appended to each subplot title.

Returns:

figHandle – Handle to the generated figure.

Return type:

matplotlib.figure.Figure

static build_reorder_operator(old_list, new_list)#

Build the Q selection/reorder operator mapping the old state to the new.

Blocks are matched on (name, spice_id, occurrence). A new block with no old counterpart yields an all-zero row in Q (an expansion target).

Parameters:

old_list (list) – State definition before the node transition.
new_list (list) – State definition after the node transition.

Returns:

Q (numpy.ndarray) – (new_n, old_n) operator with Q[i, j] = 1 when old scalar j maps to new scalar i.
new_n (int) – Dimension of the new state.
new_blocks (list of (str, int, int)) – (name, start, size) of blocks present in new_list but absent from old_list (expansion targets — zero rows of Q).

static check_slices_equal(arr: ndarray)#

Checks if all slices are equal across an array.

Parameters:: arr (numpy.ndarray) – The array to examine.
Returns:: are_equal – Indicates if all slices are equal or not.
Return type:: bool

static enumerate_state_blocks(state_list)#

Enumerate the scalar blocks of a state definition with a rich key.

The key (name, size, spice_id, frame_name, occurrence) fully disambiguates repeated parameters across bodies and occurrences, so it can project values between a global state and per-leg definitions with one consistent keying convention.

Parameters:

state_list (list) – State-definition entries (6-tuples (name, size, est, dyn, body, awf)).

Yields:

key (tuple) – (name, size, spice_id, frame_name, occurrence).
start (int) – Scalar offset of the block in the stacked state vector.
size (int) – Number of scalars in the block.
entry (tuple) – The original state-definition entry.

static equal_along_rows(arr: ndarray) → bool#

Check equality along rows of the given array.

Parameters:: arr (numpy.ndarray) – The array to examine.
Returns:: are_equal – Returns True if all values are equal along rows. Returns False if they are not.
Return type:: bool

static find_date_indices_in_epochs(epochsTDB, target_dates, rtol=1e-06)#

Find the index or indices of target date(s) in a numpy array of epochs, accounting for floating-point precision.

Parameters:

epochsTDB (EpochArray) – Reference epoch array to search within.
target_dates (EpochArray or list of EpochArray) – Target epoch(s) to locate inside epochsTDB.
rtol (float, optional) – Relative tolerance for comparing the dates. Defaults to 1e-6.

Returns:

ind – The index or indices of the target date(s), or None if not found.

Return type:

int or list of ints

static load_json(dir: str, print_flag: bool = False) → dict#

Load and parse a JSON file from disk.

Parameters:

dir (str) – Path to the .json file to load.
print_flag (bool, optional) – When True, prints a confirmation message after a successful read. Defaults to False.

Returns:

data – Parsed JSON content.

Return type:

dict or list

static make_dir(dir: str) → None#

Generate a folder in the given directory.

Parameters:: dir (str) – The directory path to a generate a folder in.
Return type:: None

static max_of_last_slice(arr: ndarray)#

Finds the maximum value of the last slice of an array.

Parameters:: arr (numpy.ndarray) – The array to examine.
Returns:: max_vals – The max value of the last slice.
Return type:: Any

static open_pickle(dir: str)#

Return a pickle object handle from dir.

Parameters:: dir (str) – Directory + name of the pickle object.
Returns:: pickle_handle – The Python object deserialised from the pickle file.
Return type:: object

static reorder_covariance(Q, P, new_block_variances=None)#

Reorder a covariance: P' = Q P Q^T, with a-priori variances for new states.

Parameters:

Q (numpy.ndarray) – Reorder operator from build_reorder_operator().
P (array_like) – Old (old_n, old_n) covariance.
new_block_variances (list of (int, array_like), optional) – (start, variances) for each expansion block; variances is the 1-D array of a-priori variances (\(\sigma^2\)) placed on that block’s diagonal. Off-diagonal (cross) terms stay zero (P_yz = 0).

Returns:

The (new_n, new_n) reordered covariance.

Return type:

numpy.ndarray

static reorder_stm(Q, STM, new_blocks=None)#

Reorder a State Transition Matrix: Phi' = Q Phi Q^T.

Newly augmented states (zero rows of Q) receive a decoupled identity block, matching the convention that a fresh parameter starts uncorrelated with unit STM.

Parameters:

Q (numpy.ndarray) – Reorder operator from build_reorder_operator().
STM (array_like) – Old (old_n, old_n) State Transition Matrix.
new_blocks (list of (str, int, int), optional) – (name, start, size) expansion blocks (as returned by build_reorder_operator()) to set to identity.

Returns:

The (new_n, new_n) reordered STM.

Return type:

numpy.ndarray

static reorder_vector(Q, x)#

Apply the reorder operator to a state / deviation vector: X' = Q X.

Parameters:

Q (numpy.ndarray) – Reorder operator from build_reorder_operator().
x (array_like) – Old state or deviation vector (old_n elements, any shape).

Returns:

The reordered vector as an (new_n, 1) column. Newly augmented states map to zero.

Return type:

numpy.ndarray

static tile_array(arr, desired_shape)#

Construct an array by repeating A the number of times given by reps.

Parameters:

arr (numpy.ndarray) – The array to examine.
desired_shape (tuple of int) – Target shape of the output array. The last dimension must equal len(arr); all preceding dimensions specify how many times to repeat the array along each axis.

Returns:

tiled – The new tiled array.

Return type:

numpy.ndarray