Tutorial 1 — Basic Entanglement Request

Objective: Establish entanglement between two nodes connected by a single fiber link, demonstrating the minimal end-to-end simulation workflow.

This is the simplest possible qnet-core program: define a network topology with two nodes and one link, then call request_entanglement() to simulate establishing an entangled pair between them.

Step 1: Import and Create the Engine

from qnet_core import QNetEngine, NodeDefinition, LinkDefinition, StrategyType

engine = QNetEngine()

The QNetEngine is the main entry point for all simulations. By default it uses reasonable physical constants (fiber loss of 0.22 dB/km at 1550 nm). You can pass a custom SimulationConfig to override these.

Step 2: Define Network Topology

nodes = [
    NodeDefinition(id="Alice", memory_lifetime_t2=0.5),   # 500 ms coherence time
    NodeDefinition(id="Bob",   memory_lifetime_t2=0.5),
]

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

engine.define_network(nodes, links)

A NodeDefinition specifies the quantum node's T2 memory coherence time (in seconds). A LinkDefinition specifies the physical properties of the quantum link: distance, raw fidelity, and generation rate.

Understanding Parameters

• T2 = 0.5 s: Qubits survive for 500 ms in the quantum memory before decoherence. Longer T2 allows more time for multi-hop protocols.
• base_fidelity = 0.95: The raw entanglement fidelity of a direct link generation event, before purification.
• generation_rate_hz = 1000: The link attempts to generate entanglement 1,000 times per second (stochastically).

Step 3: Request Entanglement Distribution

result = engine.request_entanglement(
    from_node="Alice",
    to="Bob",
    fidelity_target=0.90,          # minimum acceptable final fidelity
    max_latency_ms=5_000.0,        # 5-second timeout
    strategy=StrategyType.HighestFidelity,
)

request_entanglement() runs a single Monte Carlo trial:

1. The engine routes from Alice to Bob using the chosen strategy (HighestFidelity)
2. It attempts link generation stochastically at each hop
3. BBPSSW purification is applied automatically when fidelity drops below target
4. Results are returned as a SimulationResult

Step 4: Inspect Results

print(f"Success:      {result.success}")
print(f"Latency:      {result.latency_ms:.1f} ms")
print(f"Fidelity:     {result.final_fidelity:.4f}")
print(f"Path:         {' → '.join(result.execution_path)}")

The result tells you whether entanglement was established, how long it took, the final fidelity after purification, and which nodes were traversed.

What's next

• Monte Carlo Ensemble — run 1,000 trials to get statistical insights
• Routing Strategy Comparison — see how different strategies affect outcomes