Tutorial 2 — Monte Carlo Ensemble

Objective: Run simulate() over 1,000 trials to measure success rate, mean latency, and fidelity distributions across a quantum repeater network.

A single simulation run gives one stochastic outcome. To understand your network's performance reliably, you need an ensemble of many runs — this is what Monte Carlo simulation provides.

Setup: Define a 4-Node Repeater Chain

from qnet_core import QNetEngine, NodeDefinition, LinkDefinition, StrategyType

engine = QNetEngine()

nodes = [
    NodeDefinition(id="Alice",   memory_lifetime_t2=1.0),
    NodeDefinition(id="R1",     memory_lifetime_t2=0.8),
    NodeDefinition(id="R2",     memory_lifetime_t2=0.8),
    NodeDefinition(id="Bob",    memory_lifetime_t2=1.0),
]

links = [
    LinkDefinition("Alice",  "R1", distance_km=15.0, base_fidelity=0.92, generation_rate_hz=500.0),
    LinkDefinition("R1",     "R2", distance_km=15.0, base_fidelity=0.90, generation_rate_hz=500.0),
    LinkDefinition("R2",     "Bob", distance_km=15.0, base_fidelity=0.88, generation_rate_hz=500.0),
]

engine.define_network(nodes, links)

Run the Ensemble

stats = engine.simulate(
    from_node="Alice",
    to="Bob",
    fidelity_target=0.85,
    max_latency_ms=10_000.0,
    runs=1_000,             # number of Monte Carlo trials
    strategy=StrategyType.HighestFidelity,
    seed=42,                # deterministic for reproducibility
)

Deterministic Reproducibility

Pass seed to get identical results across runs. Without a seed, each call produces different stochastic outcomes. The seed parameter is passed through to the internal RNG.

Inspect Results

print(f"Total runs:       {stats.total_runs}")
print(f"Success rate:     {stats.empirical_success_rate:.1%}")
print(f"Mean latency:     {stats.mean_latency_ms:.1f} ms")
print(f"Mean fidelity:    {stats.mean_fidelity:.4f}")
print(f"Congestion drops: {stats.aggregate_congestion_drops}")

print("\nLink utilization (hit counts):")
for link_key, count in sorted(stats.link_utilization_heatmap.items()):
    print(f"  {link_key}: {count} hits")

The ensemble result (MonteCarloStats) provides:

Field	Description
total_runs	Number of trials executed
empirical_success_rate	Fraction of successful runs [0, 1]
mean_latency_ms	Average latency across successful runs
mean_fidelity	Average final fidelity across successful runs
aggregate_congestion_drops	Total drops due to memory expiry
link_utilization_heatmap	Per-link usage counts for profiling bottlenecks

What's next

• Routing Strategy Comparison — compare different strategies on the same ensemble
• Tuning Physical Constants — sweep parameters to find optimization targets