opengnc.simulation package

Submodules

opengnc.simulation.events module

class opengnc.simulation.events.Event(t: float, callback: Callable[[...], Any], *args: Any, **kwargs: Any)

Bases: object

A single discrete event to be processed at a specific time.

execute() → Any

Executes the event callback.

class opengnc.simulation.events.EventQueue

Bases: object

Priority queue managing discrete events in the simulation. Handles maneuver scheduling and mode transitions.

has_events() → bool

Returns True if there are pending events.

next_event_time() → float

Returns the time of the next pending event, or infinity if empty.

process_until(current_time: float) → None

Process all events scheduled up to the provided current_time.

Parameters:

current_time (float) – The current simulation time.

schedule(t: float, callback: Callable[[...], Any], *args: Any, **kwargs: Any) → None

Schedule a new event.

Parameters:

• t (float) – Time at which to run the callback.

• callback (Callable) – The function to execute.

opengnc.simulation.logging module

class opengnc.simulation.logging.SimulationLogger(filename: str)

Bases: object

Simulation replay and logging interface. Records state history and outputs to common formats like JSON, CSV. (HDF5 support optionally using h5py if installed).

log(t: float, state: Any, measurements: Any = None, estimates: Any = None, commands: Any = None) → None

Record a simulation step.

Parameters:

• t (float) – Simulation time.

• state (Any) – True state of the system (e.g. state vector).

• measurements (Any, optional) – Sensor measurements at this time step.

• estimates (Any, optional) – Filter estimates at this time step.

• commands (Any, optional) – Control commands sent to actuators.

save_csv() → None

Saves the log’s top-level keys to a CSV file.

save_hdf5() → None

Saves the logged history to an HDF5 file (requires h5py).

save_json() → None

Saves the logged history to a JSON file.

opengnc.simulation.monte_carlo module

Monte Carlo simulation harness and statistical analysis helpers.

class opengnc.simulation.monte_carlo.MonteCarloSim(simulator_factory: Callable[[...], Any])

Bases: object

Monte Carlo simulation harness.

Facilitates large-scale robustness analysis by executing multiple simulation runs with stochastic variations.

Parameters:

simulator_factory (Callable[..., Any]) – Generator function that produces simulator instances or direct results. Signature: (seed, **kwargs) -> simulator_or_result.

get_analyzer() → MonteCarloAnalyzer

Produce a statistical analyzer for the current simulation results.

Returns:

Analyzer initialized with the current trial data.

Return type:

MonteCarloAnalyzer

run_parallel(num_runs: int, processes: int | None = None, **kwargs: Any) → list[Any]

Execute Monte Carlo iterations across multiple processor cores.

Parameters:

• num_runs (int) – Number of trials to execute.

• processes (int | None, optional) – Number of parallel workers. Defaults to machine CPU count.

• **kwargs (Any) – Parameters for simulation configuration.

Returns:

Aggregated results.

Return type:

list[Any]

run_sequential(num_runs: int, **kwargs: Any) → list[Any]

Execute Monte Carlo iterations in a single thread.

Parameters:

• num_runs (int) – Number of trials to execute.

• **kwargs (Any) – Variable parameters passed to the simulator factory.

Returns:

Aggregated results from all trials.

Return type:

list[Any]

opengnc.simulation.monte_carlo_analyzer module

class opengnc.simulation.monte_carlo_analyzer.MonteCarloAnalyzer(results: list[dict[str, Any]])

Bases: object

Statistical analysis suite for Monte Carlo simulations.

Provides tools for calculating performance margins, stability metrics, and covariance consistency checks.

check_covariance_consistency(error_key: str, cov_key: str) → dict[str, float | str]

Perform a covariance consistency check such as NIS or NEES.

Parameters:

• error_key (str) – Result key for estimation error vectors.

• cov_key (str) – Result key for covariance matrices.

Returns:

Aggregate consistency metrics, or {"status": "missing_data"} when the required keys are not present.

Return type:

dict[str, float | str]

get_aggregate_stats(key: str) → dict[str, ndarray]

Extract summary statistics for a specific telemetry key.

Parameters:

key (str) – Result dictionary key containing scalar or array-like telemetry.

Returns:

Mean, spread, and extrema statistics for the requested key.

Return type:

dict[str, np.ndarray]

summarize_failures(criteria_func: Callable[[dict[str, Any]], bool]) → dict[str, int | float]

Calculate failure rates based on a user-defined criteria function.

opengnc.simulation.multibody module

class opengnc.simulation.multibody.ConstellationSimulator(num_satellites: int, propagator: Callable[[float, Any, float, Any], Any], sensor_model: Callable[[float, Any], Any] | None = None, estimator: Callable[[float, Any], Any] | None = None, controller: Callable[[float, Any], Any] | None = None, logger: SimulationLogger | None = None)

Bases: object

Multi-Agent / Constellation Simulator.

Manages simultaneous simulation of multiple spacecraft, enabling coordinated formation flying or large network analysis.

Parameters:

• num_satellites (int) – Total spacecraft count.

• propagator (PropagatorFunc) – Joint or vectorized propagator function.

• sensor_model (Optional[SensorFunc]) – Measurement model.

• estimator (Optional[EstimatorFunc]) – Centralized or multi-state estimator.

• controller (Optional[ControllerFunc]) – Coordinating control logic.

• logger (Optional[SimulationLogger]) – Data recording utility.

initialize(t0: float, initial_states: list[Any]) → None

Initialize starting conditions for all members.

Parameters:

• t0 (float) – Start simulation time (s).

• initial_states (List[Any]) – Container of starting states for each spacecraft.

run(t_end: float, dt: float) → Any

Execute the constrained multi-body simulation.

Parameters:

• t_end (float) – Termination time (s).

• dt (float) – Physics update rate (s).

Returns:

Aggregate simulation results.

Return type:

Any

opengnc.simulation.realtime module

class opengnc.simulation.realtime.RealTimeSimulator(*args: Any, rtf: float = 1.0, **kwargs: Any)

Bases: MissionSimulator

Real-time simulation synchronizing simulation time to wall-clock time. Supports Hardware-In-the-Loop (HIL) or Software-In-the-Loop (SIL) testing.

initialize(t0: float, initial_state: Any) → None

Set the simulation starting epoch and state.

Parameters:

• t0 (float) – Start time (s).

• initial_state (Any) – Initial truth state vector or object.

run(t_end: float, dt: float) → None

Runs the simulation loop until the end time, matching wall-clock pace.

Parameters:

• t_end (float) – Simulation end time.

• dt (float) – Simulation time step.

opengnc.simulation.scenario module

Scenario Configuration Manager.

class opengnc.simulation.scenario.ScenarioConfig(filename: str | Path)

Bases: object

Scenario Configuration Manager.

Handles loading and parsing of reproducible mission configurations from external formatted files (JSON, YAML).

Parameters:

filename (Union[str, Path]) – Path to the configuration file.

get(key: str, default: Any = None) → Any

Retrieve a configuration value using dot-notation.

Example: config.get(‘spacecraft.mass’, 500.0) retrieves the ‘mass’ property from the ‘spacecraft’ object.

Parameters:

• key (str) – Dot-separated access path (e.g., ‘propulsion.tank_vol’).

• default (Any, optional) – Fallback value if key is missing.

Returns:

The requested parameter value.

Return type:

Any

load() → None

Load data from the filesystem into the internal configuration dictionary.

Raises:

• FileNotFoundError – If path does not exist.

• ImportError – If YAML is requested but PyYAML is missing.

• ValueError – If file extension is unsupported.

opengnc.simulation.simulator module

class opengnc.simulation.simulator.MissionSimulator(propagator: Callable[[float, Any, float, Any], Any], sensor_model: Callable[[float, Any], Any] | None = None, estimator: Callable[[float, Any], Any] | None = None, controller: Callable[[float, Any], Any] | None = None, logger: SimulationLogger | None = None)

Bases: object

High-Fidelity Mission Simulator.

Loop Sequence: 1. Update Sense: $mathbf{y} = h(t, mathbf{x}) + mathbf{v}$ 2. Estimate: $hat{mathbf{x}} = f(t, mathbf{y})$ 3. Control: $mathbf{u} = g(t, hat{mathbf{x}})$ 4. Propagate: $dot{mathbf{x}} = f(t, mathbf{x}, mathbf{u})$

Parameters:

• propagator (PropagatorFunc) – Truth propagation: $(t, x, dt, u) to x_{new}$

• sensor_model (Optional[SensorFunc]) – Measurement model: $(t, x) to y$

• estimator (Optional[EstimatorFunc]) – State estimation: $(t, y) to hat{x}$

• controller (Optional[ControllerFunc]) – Control law: $(t, hat{x}) to u$

• logger (Optional[SimulationLogger]) – Telemetry recording.

initialize(t0: float, initial_state: Any) → None

Set the simulation starting epoch and state.

Parameters:

• t0 (float) – Start time (s).

• initial_state (Any) – Initial truth state vector or object.

run(t_end: float, dt: float) → Any

Execute the simulation loop until the termination time.

Parameters:

• t_end (float) – Simulation stop time (s).

• dt (float) – Fixed integration step (s).

Returns:

Returns logger history if available, otherwise simulation end state.

Return type:

Any

schedule_event(t: float, callback: Callable[[...], Any], *args: Any, **kwargs: Any) → None

Register a discrete event for future execution.

Parameters:

• t (float) – Target execution time (s).

• callback (Callable) – Function to execute at time $t$.

step(dt: float) → None

Execute a single fixed-step simulation frame.

Sequence: 1. Process pending discrete events. 2. Generate synthetic measurements (Sense). 3. Solve for state estimate (Estimate). 4. Compute control effort (Control). 5. Log data series. 6. Advance physics (Propagate).

Parameters:

dt (float) – Simulation time step (s).

Module contents

Simulation module for the opengnc.

This module provides the architecture for end-to-end mission simulation, including scenario configuration, discrete-event scheduling, simulation logging, Monte Carlo harness, and real-time/multi-body support.

class opengnc.simulation.ConstellationSimulator(num_satellites: int, propagator: Callable[[float, Any, float, Any], Any], sensor_model: Callable[[float, Any], Any] | None = None, estimator: Callable[[float, Any], Any] | None = None, controller: Callable[[float, Any], Any] | None = None, logger: SimulationLogger | None = None)

Bases: object

Multi-Agent / Constellation Simulator.

Manages simultaneous simulation of multiple spacecraft, enabling coordinated formation flying or large network analysis.

Parameters:

• num_satellites (int) – Total spacecraft count.

• propagator (PropagatorFunc) – Joint or vectorized propagator function.

• sensor_model (Optional[SensorFunc]) – Measurement model.

• estimator (Optional[EstimatorFunc]) – Centralized or multi-state estimator.

• controller (Optional[ControllerFunc]) – Coordinating control logic.

• logger (Optional[SimulationLogger]) – Data recording utility.

initialize(t0: float, initial_states: list[Any]) → None

Initialize starting conditions for all members.

Parameters:

• t0 (float) – Start simulation time (s).

• initial_states (List[Any]) – Container of starting states for each spacecraft.

run(t_end: float, dt: float) → Any

Execute the constrained multi-body simulation.

Parameters:

• t_end (float) – Termination time (s).

• dt (float) – Physics update rate (s).

Returns:

Aggregate simulation results.

Return type:

Any

class opengnc.simulation.Event(t: float, callback: Callable[[...], Any], *args: Any, **kwargs: Any)

Bases: object

A single discrete event to be processed at a specific time.

execute() → Any

Executes the event callback.

class opengnc.simulation.EventQueue

Bases: object

Priority queue managing discrete events in the simulation. Handles maneuver scheduling and mode transitions.

has_events() → bool

Returns True if there are pending events.

next_event_time() → float

Returns the time of the next pending event, or infinity if empty.

process_until(current_time: float) → None

Process all events scheduled up to the provided current_time.

Parameters:

current_time (float) – The current simulation time.

schedule(t: float, callback: Callable[[...], Any], *args: Any, **kwargs: Any) → None

Schedule a new event.

Parameters:

• t (float) – Time at which to run the callback.

• callback (Callable) – The function to execute.

class opengnc.simulation.MissionSimulator(propagator: Callable[[float, Any, float, Any], Any], sensor_model: Callable[[float, Any], Any] | None = None, estimator: Callable[[float, Any], Any] | None = None, controller: Callable[[float, Any], Any] | None = None, logger: SimulationLogger | None = None)

Bases: object

High-Fidelity Mission Simulator.

Loop Sequence: 1. Update Sense: $mathbf{y} = h(t, mathbf{x}) + mathbf{v}$ 2. Estimate: $hat{mathbf{x}} = f(t, mathbf{y})$ 3. Control: $mathbf{u} = g(t, hat{mathbf{x}})$ 4. Propagate: $dot{mathbf{x}} = f(t, mathbf{x}, mathbf{u})$

Parameters:

• propagator (PropagatorFunc) – Truth propagation: $(t, x, dt, u) to x_{new}$

• sensor_model (Optional[SensorFunc]) – Measurement model: $(t, x) to y$

• estimator (Optional[EstimatorFunc]) – State estimation: $(t, y) to hat{x}$

• controller (Optional[ControllerFunc]) – Control law: $(t, hat{x}) to u$

• logger (Optional[SimulationLogger]) – Telemetry recording.

initialize(t0: float, initial_state: Any) → None

Set the simulation starting epoch and state.

Parameters:

• t0 (float) – Start time (s).

• initial_state (Any) – Initial truth state vector or object.

run(t_end: float, dt: float) → Any

Execute the simulation loop until the termination time.

Parameters:

• t_end (float) – Simulation stop time (s).

• dt (float) – Fixed integration step (s).

Returns:

Returns logger history if available, otherwise simulation end state.

Return type:

Any

schedule_event(t: float, callback: Callable[[...], Any], *args: Any, **kwargs: Any) → None

Register a discrete event for future execution.

Parameters:

• t (float) – Target execution time (s).

• callback (Callable) – Function to execute at time $t$.

step(dt: float) → None

Execute a single fixed-step simulation frame.

Sequence: 1. Process pending discrete events. 2. Generate synthetic measurements (Sense). 3. Solve for state estimate (Estimate). 4. Compute control effort (Control). 5. Log data series. 6. Advance physics (Propagate).

Parameters:

dt (float) – Simulation time step (s).

class opengnc.simulation.MonteCarloSim(simulator_factory: Callable[[...], Any])

Bases: object

Monte Carlo simulation harness.

Facilitates large-scale robustness analysis by executing multiple simulation runs with stochastic variations.

Parameters:

simulator_factory (Callable[..., Any]) – Generator function that produces simulator instances or direct results. Signature: (seed, **kwargs) -> simulator_or_result.

get_analyzer() → MonteCarloAnalyzer

Produce a statistical analyzer for the current simulation results.

Returns:

Analyzer initialized with the current trial data.

Return type:

MonteCarloAnalyzer

run_parallel(num_runs: int, processes: int | None = None, **kwargs: Any) → list[Any]

Execute Monte Carlo iterations across multiple processor cores.

Parameters:

• num_runs (int) – Number of trials to execute.

• processes (int | None, optional) – Number of parallel workers. Defaults to machine CPU count.

• **kwargs (Any) – Parameters for simulation configuration.

Returns:

Aggregated results.

Return type:

list[Any]

run_sequential(num_runs: int, **kwargs: Any) → list[Any]

Execute Monte Carlo iterations in a single thread.

Parameters:

• num_runs (int) – Number of trials to execute.

• **kwargs (Any) – Variable parameters passed to the simulator factory.

Returns:

Aggregated results from all trials.

Return type:

list[Any]

class opengnc.simulation.RealTimeSimulator(*args: Any, rtf: float = 1.0, **kwargs: Any)

Bases: MissionSimulator

Real-time simulation synchronizing simulation time to wall-clock time. Supports Hardware-In-the-Loop (HIL) or Software-In-the-Loop (SIL) testing.

initialize(t0: float, initial_state: Any) → None

Set the simulation starting epoch and state.

Parameters:

• t0 (float) – Start time (s).

• initial_state (Any) – Initial truth state vector or object.

run(t_end: float, dt: float) → None

Runs the simulation loop until the end time, matching wall-clock pace.

Parameters:

• t_end (float) – Simulation end time.

• dt (float) – Simulation time step.

class opengnc.simulation.ScenarioConfig(filename: str | Path)

Bases: object

Scenario Configuration Manager.

Handles loading and parsing of reproducible mission configurations from external formatted files (JSON, YAML).

Parameters:

filename (Union[str, Path]) – Path to the configuration file.

get(key: str, default: Any = None) → Any

Retrieve a configuration value using dot-notation.

Example: config.get(‘spacecraft.mass’, 500.0) retrieves the ‘mass’ property from the ‘spacecraft’ object.

Parameters:

• key (str) – Dot-separated access path (e.g., ‘propulsion.tank_vol’).

• default (Any, optional) – Fallback value if key is missing.

Returns:

The requested parameter value.

Return type:

Any

load() → None

Load data from the filesystem into the internal configuration dictionary.

Raises:

• FileNotFoundError – If path does not exist.

• ImportError – If YAML is requested but PyYAML is missing.

• ValueError – If file extension is unsupported.

class opengnc.simulation.SimulationLogger(filename: str)

Bases: object

Simulation replay and logging interface. Records state history and outputs to common formats like JSON, CSV. (HDF5 support optionally using h5py if installed).

log(t: float, state: Any, measurements: Any = None, estimates: Any = None, commands: Any = None) → None

Record a simulation step.

Parameters:

• t (float) – Simulation time.

• state (Any) – True state of the system (e.g. state vector).

• measurements (Any, optional) – Sensor measurements at this time step.

• estimates (Any, optional) – Filter estimates at this time step.

• commands (Any, optional) – Control commands sent to actuators.

save_csv() → None

Saves the log’s top-level keys to a CSV file.

save_hdf5() → None

Saves the logged history to an HDF5 file (requires h5py).

save_json() → None

Saves the logged history to a JSON file.