Simplify orchestrator

Author: ciaranra

crates/pecos-neo/README.md

@@ -6,26 +6,26 @@ This crate provides a composable approach to quantum simulation with:
 
 - **Typed Commands**: `GateCommand` and `CommandQueue` replacing `ByteMessage`
 - **Composable Noise**: Event-driven noise channels that can be freely combined
-- **Plugin System**: Bevy-inspired architecture for bundling functionality
+- **Plugin System**: ECS-inspired architecture for bundling functionality
 - **Simple Runner**: Direct simulator execution via `ShotRunner`
 
 ## Architecture
 
-The key insight is **composition over configuration**. Instead of a monolithic noise model with dozens of parameters, you compose small, focused channels:
+The key insight is **configuration via composition**. Instead of a monolithic noise model with dozens of parameters, you compose small, focused channels:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                   ComposableNoiseModel                       │
+│                   ComposableNoiseModel                      │
 │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
 │  │ SingleQubit │ │  TwoQubit   │ │ Measurement │  ...       │
 │  │   Channel   │ │   Channel   │ │   Channel   │            │
 │  └─────────────┘ └─────────────┘ └─────────────┘            │
-│         │               │               │                    │
-│         └───────────────┴───────────────┘                    │
-│                         │                                    │
-│                    NoiseEvent                                │
-│              (BeforeGate, AfterGate,                         │
-│               AfterMeasurement, etc.)                        │
+│         │               │               │                   │
+│         └───────────────┴───────────────┘                   │
+│                         │                                   │
+│                    NoiseEvent                               │
+│              (BeforeGate, AfterGate,                        │
+│               AfterMeasurement, etc.)                       │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -161,8 +161,8 @@ use pecos_qsim::StateVec;
 
 let commands = CommandBuilder::new()
     .pz(0)
-    .rx(0, Angle64::HALF_TURN)  // RX(pi) = X gate
-    .rzz(0, 1, Angle64::QUARTER_TURN)  // RZZ(pi/2)
+    .rx(Angle64::HALF_TURN, 0)  // RX(pi) = X gate
+    .rzz(Angle64::QUARTER_TURN, 0, 1)  // RZZ(pi/2)
     .mz(0)
     .build();
 
@@ -177,8 +177,8 @@ CCX and CRZ are automatically decomposed into supported gates.
 ## Idle Time Modeling
 
 The `IdleChannel` models T1/T2 decay during idle periods.
-Time is specified in abstract time units - the interpretation (nanoseconds, clock cycles, etc.)
-is defined by the noise model configuration.
+Time is specified in abstract time units - the interpretation (nanoseconds,
+clock cycles, etc.) is defined by the noise model configuration.
 
 ```rust
 use pecos_neo::prelude::*;
@@ -213,6 +213,7 @@ Available time scales: `NANOSECONDS`, `MICROSECONDS`, `MILLISECONDS`, `SECONDS`,
 or custom via `TimeScale::from_cycle_time_ns(50.0)` for gate-cycle-based timing.
 
 You can also add precision to coarse units:
+
 ```rust
 // Think in seconds, but with nanosecond precision (9 decimal places)
 let scale = TimeScale::SECONDS.with_precision(9);
@@ -346,7 +347,7 @@ See the `large_scale` example for a benchmark.
 
 ## Design Philosophy
 
-1. **Composition over Configuration**: Build complex models from simple pieces
+1. **Configuration via Composition**: Build complex models from simple pieces
 2. **Explicit over Implicit**: See exactly what channels are active
 3. **Flexible Foundation**: The composable system supports any noise model
 4. **Convenience Wrappers**: Builders provide familiar APIs for common patterns

crates/pecos-neo/docs/README.md

@@ -188,12 +188,17 @@ The `sim_neo` API supports different execution strategies via orchestrators:
 
 | Orchestrator | Use Case |
 |--------------|----------|
-| `Sequential` (default) | Simple sequential execution |
-| `MonteCarlo { workers }` | Parallel execution (noiseless or noisy) |
-| `ImportanceSampling` | Biased sampling for rare event estimation |
+| `MonteCarlo { workers: 1 }` (default) | Single-worker execution via Tool schedule |
+| `MonteCarlo { workers: n }` | Parallel execution across n workers |
+| `ImportanceSampling` | Biased sampling for rare event estimation (via Tool schedule) |
+
+All orchestrators run through the Tool/Schedule/Plugin system, so user-registered
+plugins fire correctly regardless of orchestrator. `ImportanceSampling` uses
+`ImportanceSamplingSimPlugin` (which replaces `UnifiedSimulationPlugin`) to run
+`ImportanceSamplingRunner` inside the standard Stage pipeline.
 
 ```rust
-// Sequential (default)
+// Default (single worker)
 sim_neo(circuit).shots(1000).run();
 
 // Parallel Monte Carlo (works with or without noise)

crates/pecos-neo/src/tool/mod.rs crates/pecos-neo/src/tool.rscrates/pecos-neo/src/tool/mod.rs renamed to crates/pecos-neo/src/tool.rs

@@ -97,9 +97,9 @@ pub use plugin::{Plugin, PluginGroup};
 pub use resource::{Resource, Resources};
 pub use simulation::{
     Circuit, CustomBackendBuilder, ImportanceSamplingBuilder, NoiseResource, Orchestrator,
-    QuantumBackend, SimConfig, SimNeoBuilder, SimNeoInput, Simulation, SimulationPlugin,
-    SimulationResults, SimulatorFactory, SparseStabBuilder, StateVecBuilder, custom_backend,
-    importance_sampling, sim_neo, sim_neo_builder, sparse_stab, state_vector,
+    QuantumBackend, SimConfig, SimNeoBuilder, SimNeoInput, Simulation, SimulationResults,
+    SimulatorFactory, SparseStabBuilder, StateVecBuilder, custom_backend, importance_sampling,
+    sim_neo, sim_neo_builder, sparse_stab, state_vector,
 };
 #[cfg(feature = "engines-adapter")]
 pub use simulation::{PendingEngineBuilder, TypedProgram};

crates/pecos-neo/src/tool/core.rs

@@ -238,6 +238,15 @@ impl Tool {
         self.schedule.run_stage(Stage::Finish, &mut self.resources);
     }
 
+    /// Run the complete shot loop using the schedule directly on provided resources.
+    ///
+    /// Unlike `run_shots()`, this always runs Startup (no `has_run_startup` guard)
+    /// and operates on the provided resources rather than the Tool's own resources.
+    /// Used by parallel workers that each have their own Resources.
+    pub fn run_shots_on(&self, resources: &mut Resources, shots: usize) {
+        self.schedule.run_shots(resources, shots);
+    }
+
     /// Reset the tool for another run.
     ///
     /// This clears the startup flag, allowing `Startup` systems to run again.
@@ -256,6 +265,12 @@ impl Tool {
     pub fn resources_mut(&mut self) -> &mut Resources {
         &mut self.resources
     }
+
+    /// Get a reference to the schedule (for advanced use).
+    #[must_use]
+    pub fn schedule(&self) -> &Schedule {
+        &self.schedule
+    }
 }
 
 #[cfg(test)]

crates/pecos-neo/src/tool/design.md

@@ -123,7 +123,6 @@ pub struct Circuit(pub CommandQueue);
 pub struct SimConfig {
     pub shots: usize,
     pub seed: Option<u64>,
-    pub workers: usize,
 }
 pub struct SimulationResults { ... }
 ```
@@ -179,16 +178,12 @@ impl SimNeoBuilder {
     /// Build the simulation handle
     pub fn build(self) -> Simulation {
         let tool = Tool::new()
-            .add_plugin(SimulationPlugin)
-            .add_plugin(NoisePlugin::new(self.noise))
-            .insert_resource(Circuit(self.circuit))
-            .insert_resource(SimConfig {
-                shots: self.shots,
-                seed: self.seed,
-                workers: self.workers,
-            });
-
-        Simulation { tool }
+            .add_plugin(UnifiedSimulationPlugin { explicit_num_qubits: None })
+            .insert_resource(ProgramSourceResource(source))
+            .insert_resource(self.config)
+            .insert_resource(QuantumBackendResource(self.quantum_backend));
+
+        Simulation { tool, orchestrator: self.orchestrator, parallel_data }
     }
 }
 ```
@@ -200,6 +195,8 @@ Reusable handle that wraps a configured Tool:
 ```rust
 pub struct Simulation {
     tool: Tool,
+    orchestrator: Orchestrator,
+    parallel_data: Option<ParallelExecutionData>,
 }
 
 impl Simulation {
@@ -251,21 +248,26 @@ let results3 = sim.shots(5000).seed(456).run();
 
 ## Plugins
 
-### SimulationPlugin
+### UnifiedSimulationPlugin
 
-Core simulation functionality:
+Core simulation functionality. Handles both static circuits and classical engines
+via a unified `QuantumRunner` + `CommandSource` abstraction. The same systems run
+in both single-worker and parallel execution (each parallel worker gets its own
+`Resources` and runs the shared schedule).
 
 ```rust
-pub struct SimulationPlugin;
+struct UnifiedSimulationPlugin {
+    explicit_num_qubits: Option<usize>,
+}
 
-impl Plugin for SimulationPlugin {
+impl Plugin for UnifiedSimulationPlugin {
     fn build(&self, tool: &mut Tool) {
         tool.insert_resource(SimulationResults::new())
-            .add_system(Stage::Startup, initialize_simulator)
-            .add_system(Stage::PreShot, reset_and_seed)
-            .add_system(Stage::Execute, run_circuit)
-            .add_system(Stage::PostShot, collect_outcomes)
-            .add_system(Stage::Finish, aggregate_results);
+            .insert_resource(ExplicitNumQubits(self.explicit_num_qubits))
+            .add_system(Stage::Startup, unified_simulation_startup)
+            .add_system(Stage::PreShot, unified_simulation_pre_shot)
+            .add_system(Stage::Execute, unified_simulation_execute)
+            .add_system(Stage::PostShot, unified_simulation_post_shot);
     }
 }
 ```
@@ -289,25 +291,37 @@ impl Plugin for NoisePlugin {
 }
 ```
 
-### ImportanceSamplingPlugin
+### `ImportanceSamplingSimPlugin`
 
-Importance sampling for rare events:
+When the importance sampling orchestrator is selected, this plugin replaces
+`UnifiedSimulationPlugin`. It uses `ImportanceSamplingRunner` internally for
+biased noise with weight tracking, running through the same Stage/Schedule
+system as Monte Carlo execution.
 
 ```rust
-pub struct ImportanceSamplingPlugin {
-    config: ImportanceConfig,
+struct ImportanceSamplingSimPlugin {
+    is_config: ImportanceSamplingBuilder,
+    explicit_num_qubits: Option<usize>,
 }
 
-impl Plugin for ImportanceSamplingPlugin {
+impl Plugin for ImportanceSamplingSimPlugin {
     fn build(&self, tool: &mut Tool) {
-        tool.insert_resource(self.config.clone())
-            .insert_resource(WeightedStatistics::new())
-            .add_system(Stage::PostShot, update_weights)
-            .add_system(Stage::Finish, compute_importance_statistics);
+        // Registers IS-specific systems at Startup/PreShot/Execute/PostShot
+        // Uses ImportanceSamplingRunner<SparseStab> for execution
     }
 }
 ```
 
+This means user-registered plugins and hooks fire correctly during IS execution,
+just as they do for Monte Carlo.
+
+### `ImportanceSamplingPlugin`
+
+A standalone plugin for manual weight tracking (pre-shot reset, post-shot
+recording, finish statistics). Available for users building custom Tool
+configurations. Not used by the IS orchestrator path, which handles its own
+weight storage via `SimulationResults.weights`.
+
 ## Results
 
 ### SimulationResults
@@ -393,15 +407,15 @@ let results = tool.resource::<MyResults>();
 - [ ] Basic `run()` execution loop
 
 ### Phase 2: Simulation Support
-- [ ] `SimulationPlugin` with core systems
+- [x] `UnifiedSimulationPlugin` with core systems
 - [ ] `NoisePlugin` integration
-- [ ] `SimNeoBuilder` and `sim_neo()`
-- [ ] `Simulation` handle with reconfiguration
-- [ ] `SimulationResults` type
+- [x] `SimNeoBuilder` and `sim_neo()`
+- [x] `Simulation` handle with reconfiguration
+- [x] `SimulationResults` type
 
 ### Phase 3: Advanced Features
-- [ ] `ImportanceSamplingPlugin`
-- [ ] Parallel execution (workers)
+- [x] `ImportanceSamplingPlugin`
+- [x] Parallel execution (MonteCarlo orchestrator with workers > 1)
 - [ ] `FTValidatorBuilder` and FT validation
 
 ### Phase 4: Integration