ADCS.helpers.plotting_mc.plot_controller_mc module

ADCS.helpers.plotting_mc.plot_controller_mc.plot_convergence_histogram_mc(full_results, body_boresight=array([0., 0., 1.]), title='Monte Carlo Convergence Error (Final Timestep)', bin_width_deg=5.0, under_thresh_deg=1.0, show_stats_box=True)

Plot and analyze the distribution of final-timestep tracking error across Monte Carlo simulations.

This function computes the angular tracking error at the final timestep for each valid Monte Carlo run and visualizes the resulting distribution using a histogram with fixed-width angular bins. Summary statistics are optionally displayed on the plot.

Final Error Definition

For each Monte Carlo run, the final angular tracking error is defined as

\[\theta_f = \cos^{-1}\!\left( \hat{\mathbf{b}}_f^{\text{ECI}} \cdot \hat{\mathbf{g}}_f \right)\]

where:

• \(\hat{\mathbf{b}}_f^{\text{ECI}}\) is the final boresight direction

• \(\hat{\mathbf{g}}_f\) is the final target direction

Statistics Reported

The following summary statistics are computed:

Statistic	Description
pct_under_thresh	Percent of runs below threshold
min	Minimum final error (deg)
max	Maximum final error (deg)
mean	Mean final error (deg)
median	Median final error (deg)
n	Number of valid runs

Histogram Construction

• Histogram bins start at 0 degrees

• Bin width is user-defined

• Bins cover the full range of observed errors

param full_results:

List of Monte Carlo result dictionaries.

type full_results:

list of dict

param body_boresight:

Fixed boresight direction expressed in the body frame.

type body_boresight:

numpy.ndarray

param title:

Plot title.

type title:

str

param bin_width_deg:

Width of histogram bins in degrees.

type bin_width_deg:

float

param under_thresh_deg:

Threshold angle (degrees) used for convergence statistics.

type under_thresh_deg:

float

param show_stats_box:

If True, display a statistics summary box on the plot.

type show_stats_box:

bool

return:

Array of final tracking errors (degrees) and a dictionary of summary statistics.

rtype:

tuple of numpy.ndarray and dict

Parameters:

• full_results (List[Dict[str, Any]])

• body_boresight (ndarray)

• title (str)

• bin_width_deg (float)

• under_thresh_deg (float)

• show_stats_box (bool)

Return type:

Tuple[ndarray, Dict[str, float]]

ADCS.helpers.plotting_mc.plot_controller_mc.plot_h_tracking_mc(full_results, body_boresight=array([0, 0, 1]), title='Monte Carlo Target Stored Angular Momentum')

Plot stored reaction wheel angular momentum for multiple Monte Carlo runs.

This function overlays reaction wheel stored angular momentum histories from a set of Monte Carlo simulations on a single figure. Each Monte Carlo run is plotted with low opacity to visualize dispersion and trends across the ensemble.

State Assumption

Each Monte Carlo result dictionary is expected to contain:

• "time" — time history

• "state" — state history with reaction wheel momentum stored from index 7 onward

The reaction wheel momentum vector is assumed to be

\[\mathbf{h}_{\text{rw}}(t) \in \mathbb{R}^{N_{\text{rw}}}\]

Visualization Strategy

• Each reaction wheel component is assigned a consistent color

• Individual Monte Carlo runs are plotted with transparency

• A non-transparent legend entry is added for clarity

param full_results:

List of Monte Carlo result dictionaries.

type full_results:

list of dict

param body_boresight:

Fixed boresight direction expressed in the body frame. (Included for interface consistency; not used in computation.)

type body_boresight:

numpy.ndarray

param title:

Plot title.

type title:

str

return:

None. The function generates a Matplotlib figure.

rtype:

None

Parameters:

• full_results (List[Dict[str, Any]])

• body_boresight (ndarray)

• title (str)

Return type:

None

ADCS.helpers.plotting_mc.plot_controller_mc.plot_target_tracking_mc(full_results, body_boresight=array([0, 0, 1]), title='Monte Carlo Target Tracking Error')

Plot angular target tracking error for multiple Monte Carlo runs.

This function computes and overlays the instantaneous angular tracking error between a fixed body-frame boresight and a desired inertial target direction across many Monte Carlo simulations.

Tracking Error Definition

Let:

• \(\hat{\mathbf{b}}\) be the normalized boresight direction in the body frame

• \(\mathbf{R}_{\mathcal{B}\rightarrow\mathcal{I}}\) be the attitude rotation matrix

• \(\hat{\mathbf{g}}_i\) be the normalized target direction in ECI

The boresight direction in ECI is

\[\hat{\mathbf{b}}_i^{\text{ECI}} = \mathbf{R}_{\mathcal{B}\rightarrow\mathcal{I}} \hat{\mathbf{b}}\]

The angular tracking error at time \(t_i\) is

\[\theta_i = \cos^{-1}\!\left( \hat{\mathbf{b}}_i^{\text{ECI}} \cdot \hat{\mathbf{g}}_i \right)\]

Visualization Strategy

• Each Monte Carlo run is plotted with low opacity

• All runs share a common color for ensemble visualization

param full_results:

List of Monte Carlo result dictionaries.

type full_results:

list of dict

param body_boresight:

Fixed boresight direction expressed in the body frame.

type body_boresight:

numpy.ndarray

param title:

Plot title.

type title:

str

return:

None. The function generates a Matplotlib figure.

rtype:

None

Parameters:

• full_results (List[Dict[str, Any]])

• body_boresight (ndarray)

• title (str)

Return type:

None