Switch examples to explicit flush(); add eventBased examples and docs

## Examples: use explicit flush() instead of with-block for multi-round programs

All new-sdk examples now open  explicitly, call
to execute queued operations, read measurement results, then call  —
rather than wrapping everything in a  block.

The  pattern works for single-round programs but makes it hard for
students to extend to more realistic applications.  To do classical processing
between quantum rounds — measure, read the result, and apply a correction gate
based on it — students need to call  mid-circuit before the
connection closes.  The explicit pattern teaches this from the start, and
scales naturally to multi-round protocols:

    sim_conn = NetQASMConnection("Alice", epr_sockets=[epr_socket])
    q = Qubit(sim_conn)
    m = q.measure()
    sim_conn.flush()   # executes all queued operations; m is now readable
    result = int(m)    # classical decision — more quantum ops can follow
    sim_conn.close()

The  example demonstrates this end-to-end: it measures a
qubit mid-circuit, makes a classical decision, and applies a correction gate
based on the result — a pattern that is impossible with the plain  block.

## New: event-based examples

Four new examples in  implement a state-machine pattern
for protocols that interleave classical negotiation with quantum operations:

-  — basic quantum ping-pong between two nodes
-  — adds a classical handshake before each quantum round
-  — correlated random number generation via entanglement
-  — same, with classical verification of correlations

**nativeMode/graphState**: added  selecting the
 backend; the default stabilizer backend raises
for  (used for Rz(−π/2) = S†).  Updated  accordingly.

## Documentation

-  reorganised into three levels (new-sdk, event-based,
  native-mode) with a short description of when to use each, and toctrees
  for all example families including the new event-based ones
-  (new): RST pages for all four event-based examples
-  (new): RST pages for all new-sdk examples
- : removed stale warnings, updated config snippets from
  the old .cfg format to the current JSON format

## Tests

-  (new): verifies that  makes
  measurement results readable mid-circuit, including multi-round programs
  with classical branching between flush calls
- : added a clarifying comment explaining
  why merge tests belong in SimulaQron (not NetQASM) and what the tests
  actually exercise

## Core simulator fixes

**flush() / _wait_for_done now works correctly**
-  gains a  field so the client's
  loop can unblock for the right subroutine instead of spinning forever
- Errors are deferred via  and raised after
  exits, so  can still run cleanly
-  and  populate  from ,
  which  sets before each subroutine

**Shutdown race condition fixed**
- Removed  from  in ; the
  decorator was triggering a premature reactor shutdown (causing
   mid-measurement) while also raising a

**ProjectQ backend: numpy serialization**
-  now wraps values with ; Twisted PB cannot
  serialize  and was silently producing
  objects on the receiving end, breaking nativeMode/teleport

**QuTiP backend: probability clamping**
-  clamps and renormalises probabilities before
   to prevent  from floating-point rounding
  after multi-qubit gate sequences (affected nativeMode/graphState)

**Network process management**
- Fixed typo  →  in
-  no longer hangs:  then  as
  fallback; removed duplicate  call in

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Stephanie Wehner

CLAUDE.md

@@ -0,0 +1,26 @@
+# SimulaQron Development Conventions
+
+## Hard Requirements
+
+### Examples
+- Examples MUST always use separate files per node (e.g. `nodeTest-client.py`, `nodeTest-server.py`), never single-file programs. Students must be able to run each node on a separate machine.
+- Follow the `new-sdk/template-client-server` structure: two node scripts + `run.sh` + `terminate.sh` + config JSONs.
+- All nodes should print their own output (not rely on return values visible only to the test harness).
+
+### Connection Pattern
+- Prefer creating a `NetQASMConnection` once and reusing it with `flush()` for multi-round quantum programs, rather than opening/closing with `with` each round.
+- `conn.flush()` is the sync point that makes measurement results readable via `int(m)`.
+
+### Backends
+- Use `stabilizer` backend by default in examples and tests unless non-Clifford gates are needed.
+- `projectq` is deprecated / hard to install. Prefer `qutip` when full state simulation is needed.
+
+## File Conventions
+- **Examples:** `examples/new-sdk/` — all new examples use the new SDK
+- **Tests:** `tests/slow/sdk/` — SDK-level integration tests
+- **Core code:** `simulaqron/` — simulator source
+- **Docs:** `docs/` — Sphinx documentation (currently outdated, being rewritten)
+
+## Virtual Environment
+- The project venv is at `.venv/` — activate with `source .venv/bin/activate`
+- Install with `pip install -e .` (skip `[test]` if projectq build fails)

docs/Examples.rst

@@ -1,21 +1,45 @@
-Programming via SimulaQron's native Python Twisted Interface (specific to SimulaQron)
-=====================================================================================
+SimulaQron Programming Examples
+================================
 
-One way to program SimulaQron is directly via its 'native interface' using Twisted. 
-This means writing a client program connecting directly to the local virtual quantum node, and issuing instructions
-to such simulated quantum hardware. Programming SimulaQron in its native interface is evidently Python specific, and
-meant primarily as an internal interface allowing one to explore higher level abstractions built on top of it.
-One such abstraction is the NetQASM interface.For programming in a universal, i.e., not Python specific interface
-see :doc:`NetQASM`.
+SimulaQron offers three ways to write quantum network programs, from highest-level to lowest-level:
 
-The examples below assume that you have already made your way through :doc:`GettingStarted`: you have the virtual
-node servers up and running, and ran the simple example of generating correlated randomness. Further examples can
-also be found in examples/nativeMode.
+1. **New SDK** (``examples/new-sdk/``) — The recommended approach using the NetQASM SDK.
+   Programs use ``NetQASMConnection`` and ``EPRSocket`` for quantum operations, and
+   ``SimulaQronClassicalClient``/``SimulaQronClassicalServer`` for classical messaging.
+   Start here if you are new to SimulaQron.
 
-.. warning:: Update the link to the CQC interface.
+2. **Event-based** (``examples/eventBased/``) — Builds on the new SDK by adding a state-machine
+   pattern for classical messaging.  Each node defines states, message handlers, and a dispatch
+   table.  This is the recommended pattern for protocols that interleave classical negotiation
+   with quantum operations.
 
-.. note:: The 'native' mode is not the recommended way to program applications for SimulaQron, instead use the
-    `NetQASM <https://softwarequtech.github.io/CQC-Python/index.html>`_ interface.
+3. **Native mode** (``examples/nativeMode/``) — The low-level Twisted interface that talks
+   directly to SimulaQron's virtual quantum nodes.  This is Python-specific and more verbose,
+   but gives full control over the simulation backend.
+
+The examples below assume that you have already made your way through :doc:`GettingStarted`:
+you have the virtual node servers up and running.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: New SDK examples:
+
+    new-sdk/Overview
+    new-sdk/Template
+    new-sdk/CorrRNG
+    new-sdk/Teleport
+    new-sdk/ExtendGHZ
+    new-sdk/MidCircuitLogic
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Event-based examples:
+
+    event-based/Overview
+    event-based/PingPong
+    event-based/PolitePingPong
+    event-based/QuantumCorrRNG
+    event-based/QuantumCorrRNGVerified
 
 .. toctree::
     :maxdepth: 2
@@ -25,6 +49,3 @@ also be found in examples/nativeMode.
     native-mode/Template
     native-mode/Teleport
     native-mode/GraphState
-
-
-

docs/event-based/Overview.rst

@@ -0,0 +1,78 @@
+Event-Based Programming Overview
+================================
+
+The event-based examples show how to structure quantum network protocols using
+a **state machine** pattern.  This is the recommended approach for protocols that
+interleave classical negotiation with quantum operations.
+
+Prerequisites: you should understand the :doc:`../new-sdk/Overview` first.
+
+The state machine pattern
+-------------------------
+
+Each node's behaviour is defined by:
+
+1. **States** — string constants naming each phase of the protocol
+2. **Handlers** — async functions that execute when a specific message arrives in
+   a specific state.  Each handler performs an action and returns the next state.
+3. **Dispatch table** — a dictionary mapping ``(current_state, message)`` to handler.
+   This *is* the state machine.
+4. **Event loop** — reads messages, looks up the transition, calls the handler.
+
+Example structure::
+
+    # States
+    STATE_WAITING_ACCEPT = "WAITING_ACCEPT"
+    STATE_DONE           = "DONE"
+
+    # Handler
+    async def handle_yes(writer: StreamWriter) -> str:
+        # ... do something ...
+        return STATE_DONE
+
+    # Dispatch table
+    DISPATCH = {
+        (STATE_WAITING_ACCEPT, "yes"): handle_yes,
+    }
+
+    # Event loop
+    async def run_alice(reader, writer):
+        state = STATE_WAITING_ACCEPT
+        while state != STATE_DONE:
+            data = await reader.read(255)
+            msg = data.decode("utf-8")
+            handler = DISPATCH.get((state, msg))
+            if handler is None:
+                continue  # ignore unknown messages
+            state = await handler(writer)
+
+Why this pattern?
+-----------------
+
+- **Clear protocol structure**: the dispatch table maps directly to a state
+  transition diagram, making the protocol easy to read and verify.
+- **Extensible**: adding a new state or message is just adding a handler and
+  a dispatch entry — no changes to the event loop.
+- **Quantum integration**: handlers can create ``NetQASMConnection``, perform
+  quantum operations, and ``flush()`` — keeping quantum code isolated in
+  focused handler functions.
+
+Examples
+--------
+
+The examples progress from purely classical to quantum:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 30 70
+
+    * - Example
+      - What it teaches
+    * - :doc:`PingPong`
+      - Basic event loop with simple if/else message handling
+    * - :doc:`PolitePingPong`
+      - Full state machine pattern with dispatch table
+    * - :doc:`QuantumCorrRNG`
+      - Adding quantum operations (EPR + measure) to event handlers
+    * - :doc:`QuantumCorrRNGVerified`
+      - Multi-state protocol: negotiate, quantum, then classical verification

docs/event-based/PingPong.rst

@@ -0,0 +1,76 @@
+Ping-Pong: Basic Event Loop
+===========================
+
+The simplest event-based example.  Alice sends a sequence of messages to Bob,
+who replies to each one.  No state machine — just a simple if/else to choose
+the reply.  Found in ``examples/eventBased/pingPong/``.
+
+This is purely classical (no quantum operations).  It demonstrates the basic
+async event loop pattern before adding state machines and quantum in later examples.
+
+Alice (client)
+--------------
+
+Alice sends a list of messages and prints Bob's replies::
+
+    async def run_alice(reader: StreamReader, writer: StreamWriter):
+        messages = ["ping", "ping", "hello", "ping"]
+
+        for msg in messages:
+            print(f"Alice: sending  '{msg}'")
+            writer.write(msg.encode("utf-8"))
+            await writer.drain()
+
+            reply_data = await reader.read(255)
+            reply = reply_data.decode("utf-8")
+            print(f"Alice: received '{reply}'")
+
+Bob (server)
+------------
+
+Bob replies "pong" to "ping" and "no way!" to anything else::
+
+    async def run_bob(reader: StreamReader, writer: StreamWriter):
+        while True:
+            data = await reader.read(255)
+            if not data:
+                break  # Alice disconnected
+
+            message = data.decode("utf-8")
+            if message == "ping":
+                reply = "pong"
+            else:
+                reply = "no way!"
+
+            writer.write(reply.encode("utf-8"))
+            await writer.drain()
+
+Key concepts
+------------
+
+- **reader/writer**: The async streams for classical TCP communication.
+  ``writer.write()`` sends bytes, ``await reader.read(N)`` receives up to N bytes.
+- **await writer.drain()**: Ensures the write buffer is flushed to the network.
+- **Connection lifecycle**: Bob's loop exits when ``reader.read()`` returns empty
+  bytes, meaning Alice has disconnected.
+
+Running
+-------
+
+::
+
+    cd examples/eventBased/pingPong
+    sh run.sh
+
+Expected output::
+
+    Alice: sending  'ping'
+    Bob: received 'ping'
+    Bob: sending  'pong'
+    Alice: received 'pong'
+    Alice: sending  'ping'
+    ...
+    Alice: sending  'hello'
+    Bob: received 'hello'
+    Bob: sending  'no way!'
+    Alice: received 'no way!'

docs/event-based/PolitePingPong.rst

@@ -0,0 +1,94 @@
+Polite Ping-Pong: The State Machine Pattern
+============================================
+
+Extends the basic ping-pong into a proper state machine with dispatch tables.
+Alice and Bob have a polite exchange: ping, pong, thank you, you're welcome.
+Found in ``examples/eventBased/politePingPong/``.
+
+This is still purely classical, but introduces the **state machine pattern**
+that all subsequent quantum examples will use.
+
+Alice's state diagram
+---------------------
+
+::
+
+    (connect)
+       │ send "ping"
+       ▼
+    WAITING_PONG
+       │ recv "pong" → send "thank you"
+       ▼
+    WAITING_YOURE_WELCOME
+       │ recv "you're welcome"
+       ▼
+      DONE
+
+Alice's dispatch table
+----------------------
+
+::
+
+    ALICE_DISPATCH = {
+        (STATE_WAITING_PONG,          "pong"):           handle_pong,
+        (STATE_WAITING_YOURE_WELCOME, "you're welcome"): handle_youre_welcome,
+    }
+
+Each handler is a focused function that performs one action and returns the next state::
+
+    async def handle_pong(writer: StreamWriter) -> str:
+        reply = "thank you"
+        writer.write(reply.encode("utf-8"))
+        await writer.drain()
+        return STATE_WAITING_YOURE_WELCOME
+
+The event loop
+--------------
+
+The event loop is generic — it works for any protocol by just changing the dispatch
+table and initial state::
+
+    async def run_alice(reader: StreamReader, writer: StreamWriter):
+        # Initial action (before the loop)
+        writer.write(b"ping")
+        await writer.drain()
+
+        state = STATE_WAITING_PONG
+
+        while state != STATE_DONE:
+            data = await reader.read(255)
+            if not data:
+                break
+            msg = data.decode("utf-8")
+
+            handler = ALICE_DISPATCH.get((state, msg))
+            if handler is None:
+                print(f"no transition for '{msg}' — ignoring.")
+                continue
+
+            state = await handler(writer)
+
+Key concepts
+------------
+
+- **Dispatch table = state machine**: the ``(state, message) → handler`` mapping
+  *is* the protocol definition.  Every valid transition is listed; anything not
+  listed is automatically rejected.
+- **Handlers are independent**: each handler only knows about its own transition,
+  making the code modular and easy to extend.
+- **The event loop is reusable**: the same loop structure works for every example
+  that follows.
+
+Bob's side
+----------
+
+Bob uses the same pattern with his own states (``WAITING_PING``, ``WAITING_THANKS``,
+``DONE``) and dispatch table.  See ``politeBob.py`` for the full code.
+
+Running
+-------
+
+::
+
+    cd examples/eventBased/politePingPong
+    sh run.sh