ADCS.mc.monte_carlo_runner module

class ADCS.mc.monte_carlo_runner.MonteCarloRunner(sim_func, config_generator, num_runs, max_workers=None)[source]

Bases: object

Parallel Monte Carlo simulation orchestrator with live Rich dashboard.

This class manages the execution of \(N\) independent Monte Carlo simulations across multiple CPU cores using concurrent.futures.ProcessPoolExecutor. It provides real-time visualization of per-core progress and global completion status.

Let \(f(\theta_i)\) denote a simulation function evaluated at configuration \(\theta_i\). The runner computes:

\[\mathcal{R} = \left\{ f(\theta_1), f(\theta_2), \dots, f(\theta_N) \right\}\]

subject to a maximum parallelism constraint \(P\), where:

\[P = \min(\text{CPU cores}, \text{max\_workers})\]

Progress is streamed asynchronously from workers to the main process via multiprocessing queues, ensuring minimal synchronization overhead.

Parameters:

  • sim_func (Callable[[Dict[str, Any]], Dict[str, Any]]) – Callable implementing a single Monte Carlo simulation.

  • config_generator (Callable[[int], Dict[str, Any]]) – Function mapping run indices to configuration dictionaries.

  • num_runs (int) – Total number of Monte Carlo runs.

  • max_workers (int) – Maximum number of worker processes.

run()[source]

Execute the Monte Carlo campaign and render the live dashboard.

This method performs the full simulation lifecycle:

  1. Initialize inter-process communication queues.

  2. Allocate UI slots corresponding to worker cores.

  3. Submit simulation jobs to the process pool.

  4. Continuously poll worker progress and completed futures.

  5. Update per-core and global progress bars in real time.

The execution proceeds until all \(N\) simulations complete, producing a result list:

\[\mathcal{R} = \left[ r_1, r_2, \dots, r_N \right]\]

where each \(r_i\) is the return value of sim_func for run \(i\). Failed runs yield None entries.

The overall progress bar advances according to:

\[C(t) = \sum_{i=1}^{N} \mathbf{1}_{\{f_i \text{ completed at } t\}}\]

where \(C(t)\) is the completed run count at time \(t\).

Returns:

List of simulation results in submission order.

Return type:

List[Dict[str, Any]]

ADCS.mc.monte_carlo_runner.claim_worker_slot()[source]

Claim an exclusive UI slot identifier for the calling worker.

Each worker retrieves a unique integer token from the shared slot queue \(Q_s\). This token corresponds to a dedicated row in the live Rich dashboard and remains reserved until explicitly released.

Formally, let \(S = \{0, 1, \dots, N-1\}\) be the set of available slots. Calling this function performs:

\[s \leftarrow \operatorname{pop}(Q_s), \quad s \in S\]

If the function is invoked outside a worker context (i.e., the global queue is uninitialized), the sentinel value \(-1\) is returned.

Returns:

Allocated slot identifier, or -1 if unavailable.

Return type:

int

ADCS.mc.monte_carlo_runner.release_worker_slot(slot_id)[source]

Release a previously claimed UI slot back to the pool.

This function returns the given slot identifier to the shared slot queue \(Q_s\), making it available for reuse by another worker. The operation is idempotent for invalid slot identifiers.

In queue-theoretic terms, this performs:

\[Q_s \leftarrow Q_s \cup \{s\}\]

where \(s\) is the released slot identifier.

Parameters:

slot_id (int) – Slot identifier obtained from claim_worker_slot().

Returns:

None

Return type:

None

ADCS.mc.monte_carlo_runner.update_worker_progress(slot_id, run_id, step, total)[source]

Send a progress update from a worker to the main dashboard.

This function emits a tuple describing the current simulation state into the shared progress queue \(Q_p\). The main process consumes these updates to refresh the corresponding Rich progress bar.

Each update is modeled as a discrete progress signal:

\[u = (s, r, k, K)\]

where

Term

Meaning

\(s\) | UI slot identifier

\(r\) | Monte Carlo run index

\(k\) | Current step

\(K\) | Total number of steps

Updates with an invalid slot identifier (-1) are silently ignored.

Parameters:

  • slot_id (int) – UI slot assigned to the worker.

  • run_id (int) – Unique Monte Carlo run identifier.

  • step (int) – Current simulation step.

  • total (int) – Total number of steps in the simulation.

Returns:

None

Return type:

None