ADCS.mc.mcconfig module

class ADCS.mc.mcconfig.Goal

Bases: object

Base class for guidance and pointing goals.

This class defines the abstract interface for all guidance and pointing objectives in the ADCS framework. A goal represents a mapping from the current orbital state to a reference definition used by downstream guidance and control laws.

Mathematically, a goal defines a function

\[G : \mathcal{O} \rightarrow \left( \mathbf{r}_{\mathrm{ref}}, \boldsymbol{\omega}_{\mathrm{ref}} \right)\]

where \(\mathcal{O}\) denotes the orbital state space, \(\mathbf{r}_{\mathrm{ref}} \in \mathbb{R}^3\) is an inertial reference direction, and \(\boldsymbol{\omega}_{\mathrm{ref}} \in \mathbb{R}^3\) is the reference angular velocity expressed in the same inertial frame.

This base class provides no concrete guidance logic. All subclasses must override the reference generation and error computation methods.

See also

ECI_Goal, Coordinate_Goal, GoalList

error(q, body_boresight, os0)

Compute the pointing or attitude error associated with the goal.

This method computes an error quantity suitable for use by a guidance or control law. In general, the error is a function of

• the current attitude representation \(\mathbf{q}\)

• the spacecraft body-frame boresight vector

• the current orbital state

A typical error definition may take the form

\[\mathbf{e} = f\!\left( \mathbf{q}, \mathbf{b}, \mathcal{O}(t) \right)\]

where \(\mathbf{b}\) denotes the body-frame boresight vector.

This base method is abstract and must be overridden by all subclasses.

Parameters:

• q (numpy.ndarray) – Current spacecraft attitude representation.

• body_boresight (numpy.ndarray) – Boresight direction expressed in the spacecraft body frame.

• os0 (Orbital_State) – Current orbital state.

Returns:

Goal-specific error vector.

Return type:

numpy.ndarray

to_ref(os0)

Generate inertial reference vectors from the current orbital state.

This method defines the primary mapping implemented by a goal. Given the current orbital state \(\mathcal{O}(t)\), it returns a reference direction and reference angular velocity:

\[\left( \mathbf{r}_{\mathrm{ref}}, \boldsymbol{\omega}_{\mathrm{ref}} \right) = G\!\left( \mathcal{O}(t) \right)\]

The exact physical interpretation of these quantities depends on the specific subclass implementation.

This base method is abstract and must be overridden.

Parameters:

os0 (Orbital_State) – Current orbital state.

Returns:

Inertial reference direction and reference angular velocity.

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

class ADCS.mc.mcconfig.MCConfig(w=None, q=None, h=None, orbit=None, goal=None, dt=None, tf=None)

Bases: object

Configuration container defining run-to-run sampling rules for Monte Carlo ADCS simulations.

Each attribute may be either a fixed value or a callable sampler. If a callable is provided, it is invoked once per Monte Carlo run to generate the value applied to that run. This class is consumed by simulate_mc() to perturb initial conditions, goals, timing parameters, and orbit definitions.

All attributes are optional; unspecified fields fall back to the base values passed directly to the Monte Carlo simulation function.

Parameters:

• w (numpy.ndarray or None) – Initial angular velocity override. If provided, replaces the first three elements of the state vector.

• q (numpy.ndarray or None) – Initial attitude quaternion override. If provided, replaces elements 3 through 6 of the state vector.

• h (numpy.ndarray or None) – Initial reaction wheel momentum override. If provided, replaces the reaction wheel portion of the state vector.

• orbit (Orbit or None) – Orbit override for the run. This may be an Orbit instance, an Orbital_State, or an equivalent dictionary representation, depending on how it is sampled and applied.

• goal (Goal or None) – Goal override for the run. If provided, replaces the base goal passed to the Monte Carlo simulation.

• dt (float or None) – Simulation time step override in seconds.

• tf (float or None) – Simulation duration override in seconds.

dt: float | None = None

goal: Goal | None = None

h: ndarray | None = None

orbit: Orbit | None = None

q: ndarray | None = None

tf: float | None = None

w: ndarray | None = None

class ADCS.mc.mcconfig.Orbit(os0, end_time=None, dt=None, use_J2=True, fast=True, verbose=True)

Bases: object

Time-ordered container and propagator for orbital states.

Notes

The fast argument is accepted for backward compatibility but is ignored: this implementation always computes real environment vectors (Sun and magnetic field) and full frame transforms for each stored Orbital_State.

Performance

For propagated orbits, this constructor propagates the translational dynamics using pure NumPy and then batch-computes the expensive environment quantities (Skyfield frames / Sun vector and ppigrf geomagnetic field) for the full time array once, before constructing individual Orbital_State objects.

param os0:

Initial orbital state or list of orbital states.

type os0:

Orbital_State or list[Orbital_State]

param end_time:

Final propagation time in J2000 centuries.

type end_time:

float or None

param dt:

Propagation time step in seconds.

type dt:

float or None

param use_J2:

Enable or disable the J2 gravitational perturbation.

type use_J2:

bool

param fast:

Backward-compatible parameter (ignored).

type fast:

bool

param verbose:

Enable progress bar output during propagation.

type verbose:

bool

raises ValueError:

If input arguments are inconsistent or unsupported.

ecef_to_eci_orbit(b_ecef_vec)

Convert ECEF vectors to ECI coordinates along the orbit.

Parameters:

b_ecef_vec (numpy.ndarray) – Vectors expressed in the ECEF frame.

Returns:

Vectors expressed in the ECI frame.

Return type:

numpy.ndarray

geocentric_to_ecef_orbit(b_vec)

Convert geocentric spherical vectors to ECEF coordinates along the orbit.

Parameters:

b_vec (numpy.ndarray) – Geocentric vector components (b_r, b_theta, b_phi).

Returns:

Vectors expressed in the ECEF frame.

Return type:

numpy.ndarray

get_b_eci_orbit()

Compute the geomagnetic field in the ECI frame along the orbit.

If per-state magnetic field vectors are already available, they are returned directly.

Returns:

Geomagnetic field vectors in ECI coordinates [Tesla].

Return type:

numpy.ndarray

get_os(J2000)

Retrieve or interpolate the orbital state at a given epoch.

Parameters:

J2000 (float) – Requested epoch in J2000 centuries.

Returns:

Orbital state at the specified time.

Return type:

Orbital_State

Raises:

ValueError – If the requested time lies outside the orbit span.

get_range(t_0, t_1, dt=None)

Extract a sub-orbit over a specified time interval.

Parameters:

• t_0 (float) – Start time in J2000 centuries.

• t_1 (float) – End time in J2000 centuries.

• dt (float or None) – Optional sampling interval in seconds.

Returns:

New orbit or orbital state(s) within the given time range.

Return type:

Orbit or Orbital_State

Raises:

ValueError – If the time bounds are invalid or outside the orbit span.

get_vecs()

Return commonly used orbit-related vectors.

Returns:

Lists of vectors [R, V, B, S, rho] over the orbit.

Return type:

list[list[numpy.ndarray]]

max_time()

Return the latest epoch in the orbit.

Returns:

Maximum J2000 time.

Return type:

float

min_time()

Return the earliest epoch in the orbit.

Returns:

Minimum J2000 time.

Return type:

float

new_orbit_from_times(time_list)

Construct a new orbit sampled at specific epochs.

Parameters:

time_list (list[float]) – List of epochs in J2000 centuries.

Returns:

New orbit containing interpolated states.

Return type:

Orbit

Raises:

ValueError – If any requested time lies outside the orbit span.

next_state(input)

Return the next available orbital state after a given time.

Parameters:

input (Orbital_State or float) – Reference time or orbital state.

Returns:

Next orbital state in chronological order.

Return type:

Orbital_State

Raises:

ValueError – If the input time lies outside the orbit span.

time_in_span(t)

Check whether a time lies within the orbit span.

Parameters:

t (float) – Time in J2000 centuries.

Returns:

True if the time is within the orbit span.

Return type:

bool

Parameters:

• os0 (Orbital_State | List[Orbital_State])

• end_time (float)

• dt (float)

• use_J2 (bool)

• fast (bool)

• verbose (bool)

ADCS.mc.mcconfig.dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.