Quick Start

Run your first quantum network simulation in five steps: create an engine, define nodes and links, and simulate entanglement distribution.

Step 1: Import the Engine

from qnet_core import QNetEngine, StrategyType, NodeDefinition, LinkDefinition

engine = QNetEngine()

The QNetEngine is the main entry point for all simulations. It manages network topology, event scheduling, and protocol execution. By default it uses standard physical constants (fiber loss 0.22 dB/km at 1550 nm, light speed in fiber 200 km/ms).

Step 2: Define Network Topology

nodes = [
    NodeDefinition(id="Alice", memory_lifetime_t2=1.0),   # 1-second qubit coherence
    NodeDefinition(id="Bob",   memory_lifetime_t2=1.0),
]

links = [
    LinkDefinition(
        from_node="Alice",
        to="Bob",
        distance_km=10.0,            # 10 km fiber segment
        base_fidelity=0.95,          # high raw link fidelity
        generation_rate_hz=1_000.0,  # 1 kHz photon pair rate
    ),
]

engine.define_network(nodes=nodes, links=links)

NodeDefinition and LinkDefinition are the building blocks of any quantum network:

• memory_lifetime_t2: The T2 coherence time in seconds. Qubits decohere after this time — longer T2 is always better for multi-hop networks.
• distance_km: Physical distance between nodes, directly affecting fiber loss (exponential decay at α = 0.22 dB/km).
• base_fidelity: Raw entanglement fidelity per link generation event. Purification can recover lower fidelities if there's enough redundancy.
• generation_rate_hz: Stochastic photon pair generation rate — higher rates mean faster entanglement establishment.

Step 3: Run a Single Simulation

result = engine.request_entanglement(
    from_node="Alice",
    to="Bob",
    fidelity_target=0.9,           # minimum acceptable final fidelity
    max_latency_ms=100.0,          # timeout in milliseconds
    strategy=StrategyType.HighestFidelity,  # prefer quality over speed
)

print(f"Success: {result.success}")            # True/False
print(f"Fidelity: {result.final_fidelity:.4f}")  # e.g., 0.9512
print(f"Path: {' -> '.join(result.execution_path)}")  # ['Alice', 'Bob']

request_entanglement() returns a SimulationResult:

Field	Type	Description
success	bool	Entanglement was established within the latency budget
latency_ms	float	Total time from request to result (ms)
final_fidelity	float	Fidelity after purification (≥ fidelity_target if successful)
execution_path	List[str]	Node IDs traversed, inclusive of source and target

Step 4: Run a Monte Carlo Ensemble

stats = engine.simulate(
    from_node="Alice",
    to="Bob",
    fidelity_target=0.9,
    max_latency_ms=100.0,
    runs=1_000,                    # 1,000 stochastic trials
    seed=42,                       # deterministic output
)

print(f"Success rate: {stats.empirical_success_rate:.2%}")
print(f"Mean latency: {stats.mean_latency_ms:.1f} ms")
print(f"Link utilization: {stats.link_utilization_heatmap}")

Step 5: Try a Pre-built Topology

from qnet_core import generate_topology

# Generate a telecom backbone network instantly
payload = generate_topology("telecom_backbone")
engine.define_network(payload.nodes, payload.links)

# Or use the built-in satellite + fiber mix
hybrid = generate_topology("hybrid_satellite_fiber")

Three topologies are available out of the box:

Name	Description
telecom_backbone	Mesh-style urban fiber network
repeater_chain	Linear chain (default 4 nodes)
hybrid_satellite_fiber	Satellite uplink with fiber ground segments

What's Next

• Tutorial: Basic Entanglement — walk through each concept in depth
• Tutorial: Monte Carlo Ensemble — statistical analysis of network performance
• API Reference: QNetEngine — complete engine documentation