less skips

Author: ciaranra

.gitignore

@@ -15,6 +15,9 @@ junit/
 # Generated doc tests (from scripts/docs/generate_doc_tests.py)
 python/quantum-pecos/tests/docs/generated/
 
+# Generated WASM binaries (compile from .wat source)
+*.wasm
+
 # Cython
 *.pyc
 *.pyd

docs/assets/test-data/math.wat

@@ -0,0 +1,59 @@
+(module
+  ;; Global state for accumulator example
+  (global $accumulator (mut i32) (i32.const 0))
+
+  ;; Required init function
+  (func $init)
+
+  ;; Optional shot reset - resets accumulator to 0
+  (func $shot_reinit
+    i32.const 0
+    global.set $accumulator)
+
+  ;; Add two numbers
+  (func $add (param i32 i32) (result i32)
+    local.get 0
+    local.get 1
+    i32.add)
+
+  ;; Subtract two numbers
+  (func $sub (param i32 i32) (result i32)
+    local.get 0
+    local.get 1
+    i32.sub)
+
+  ;; Multiply two numbers
+  (func $mul (param i32 i32) (result i32)
+    local.get 0
+    local.get 1
+    i32.mul)
+
+  ;; Accumulate a value and return the total
+  (func $accumulate (param i32) (result i32)
+    local.get 0
+    global.get $accumulator
+    i32.add
+    global.set $accumulator
+    global.get $accumulator)
+
+  ;; Compute threshold (example from docs)
+  (func $compute_threshold (param i32 i32) (result i32)
+    local.get 0
+    local.get 1
+    i32.add
+    i32.const 2
+    i32.div_s)
+
+  ;; Memory (required for some WASM operations)
+  (memory (;0;) 1)
+
+  ;; Exports
+  (export "init" (func $init))
+  (export "shot_reinit" (func $shot_reinit))
+  (export "add" (func $add))
+  (export "sub" (func $sub))
+  (export "mul" (func $mul))
+  (export "accumulate" (func $accumulate))
+  (export "compute_threshold" (func $compute_threshold))
+  (export "memory" (memory 0))
+)

docs/development/QIS_ARCHITECTURE.md

@@ -1,5 +1,7 @@
 # QIS Architecture: Interface, Runtime, and Engine
 
+<!--skip: Internal architecture documentation with illustrative code snippets-->
+
 This document describes the architecture of the Quantum Instruction Set (QIS) system in PECOS, focusing on how quantum programs are compiled, executed, and simulated.
 
 ## Overview

docs/development/circuit-representations.md

@@ -1,5 +1,7 @@
 # Circuit Representations (Internal)
 
+<!--skip: Internal architecture documentation with illustrative code snippets-->
+
 This document covers the internal circuit representations used in PECOS's Rust core. For user-facing documentation on building and manipulating circuits, see the [User Guide: Circuit Representation](../user-guide/circuit-representation.md).
 
 ## Overview

docs/user-guide/circuit-representation.md

@@ -299,7 +299,10 @@ Gates can have arbitrary metadata attached:
 === ":fontawesome-brands-rust: Rust"
     ```rust
     let mut circuit = DagCircuit::new();
-    circuit.h(0).cx(0, 1).h(1).cx(1, 2).mz(0).mz(1).mz(2);
+    circuit.h(0).cx(0, 1).h(1).cx(1, 2);
+    circuit.mz(0);
+    circuit.mz(1);
+    circuit.mz(2);
 
     // Basic metrics
     println!("Total gates: {}", circuit.gate_count());
@@ -399,13 +402,13 @@ A time-sliced circuit representation where gates are organized into discrete tim
     let mut circuit = TickCircuit::new();
 
     // First tick: parallel gates
-    circuit.tick().h(0).h(1).h(2);
+    circuit.tick().h(&[0, 1, 2]);
 
     // Second tick: entangling layer
-    circuit.tick().cx(0, 1).cx(2, 3);
+    circuit.tick().cx(&[(0, 1), (2, 3)]);
 
     // Third tick: measurements
-    circuit.tick().mz(0).mz(1);
+    circuit.tick().mz(&[0, 1]);
 
     println!("Number of ticks: {}", circuit.num_ticks());
     println!("Total gates: {}", circuit.gate_count());
@@ -434,9 +437,9 @@ TickCircuit prevents scheduling conflicting gates in the same tick:
     let mut circuit = TickCircuit::new();
     let mut tick = circuit.tick();
 
-    tick.h(0);
+    tick.h(&[0]);
     // This would error: qubit 0 already used
-    // tick.cx(0, 1);
+    // tick.cx(&[(0, 1)]);
 
     // Use try_add_gate for fallible operations
     if let Err(e) = tick.try_add_gate(Gate::cx(&[(0, 1)])) {
@@ -466,7 +469,7 @@ TickCircuit prevents scheduling conflicting gates in the same tick:
     // Add metadata to a tick
     let mut tick = circuit.tick();
     tick.meta("round", Attribute::Int(1));
-    tick.h(0).meta("error_rate", Attribute::Float(0.001));
+    tick.h(&[0]).meta("error_rate", Attribute::Float(0.001));
 
     // Circuit-level metadata
     circuit.set_meta("name", Attribute::String("Bell state".into()));
@@ -497,8 +500,8 @@ TickCircuit can be converted to and from DagCircuit:
 
     // TickCircuit -> DagCircuit
     let mut tick_circuit = TickCircuit::new();
-    tick_circuit.tick().h(0).h(1);
-    tick_circuit.tick().cx(0, 1);
+    tick_circuit.tick().h(&[0, 1]);
+    tick_circuit.tick().cx(&[(0, 1)]);
 
     let dag_circuit = DagCircuit::from(tick_circuit);
 
@@ -542,7 +545,7 @@ A general directed graph with weighted edges and attributes:
 
 === ":fontawesome-brands-rust: Rust"
     ```rust
-    use pecos::graph::DiGraph;
+    use pecos::digraph::DiGraph;
 
     let mut graph = DiGraph::new();
 
@@ -600,7 +603,7 @@ A directed acyclic graph with topological ordering and cycle prevention:
 
 === ":fontawesome-brands-rust: Rust"
     ```rust
-    use pecos::graph::DAG;
+    use pecos::dag::DAG;
 
     let mut dag = DAG::new();
 

docs/user-guide/decoders.md

@@ -1,5 +1,30 @@
 # Decoders
 
+```hidden-rust
+use pecos_decoders::{
+    CssCode, SparseMatrix, Decoder, BpMethod, OsdMethod, UfMethod, BpSchedule,
+    BpOsdDecoder, BpLsdDecoder, BeliefFindDecoder, FlipDecoder, UnionFindDecoder,
+    SoftInfoBpDecoder, SoftDecoder, LdpcError,
+};
+
+fn create_css_code() -> Result<CssCode, Box<dyn std::error::Error>> {
+    let hx_rows: Vec<u32> = vec![0, 1, 0, 1];
+    let hx_cols: Vec<u32> = vec![0, 2, 1, 3];
+    let hx = SparseMatrix::from_coo(2, 4, hx_rows, hx_cols)?;
+    let hz_rows: Vec<u32> = vec![0, 1, 0, 1];
+    let hz_cols: Vec<u32> = vec![0, 1, 2, 3];
+    let hz = SparseMatrix::from_coo(2, 4, hz_rows, hz_cols)?;
+    Ok(CssCode::new(hx, hz)?)
+}
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let css_code = create_css_code()?;
+    let syndrome = vec![1u8, 0, 1, 0];
+    // CODE
+    Ok(())
+}
+```
+
 PECOS provides quantum error correction decoders through both Python and Rust APIs. The availability of specific decoders varies by language.
 
 ## Overview
@@ -114,19 +139,20 @@ decoder = DummyDecoder()
 
 Before using decoders, you need a quantum error correction code:
 
+<!--skip: standalone function definition - included in preamble-->
 ```rust
 use pecos_decoders::{CssCode, SparseMatrix};
 
 // Create a CSS code from parity check matrices
 fn create_css_code() -> Result<CssCode, Box<dyn std::error::Error>> {
-    // Define Hx and Hz matrices
-    let hx_rows = vec![0, 1, 0, 1];
-    let hx_cols = vec![0, 2, 1, 3];
-    let hx = SparseMatrix::new(2, 4, hx_rows, hx_cols)?;
+    // Define Hx and Hz matrices as COO format sparse matrices
+    let hx_rows: Vec<u32> = vec![0, 1, 0, 1];
+    let hx_cols: Vec<u32> = vec![0, 2, 1, 3];
+    let hx = SparseMatrix::from_coo(2, 4, hx_rows, hx_cols)?;
 
-    let hz_rows = vec![0, 1, 0, 1];
-    let hz_cols = vec![0, 1, 2, 3];
-    let hz = SparseMatrix::new(2, 4, hz_rows, hz_cols)?;
+    let hz_rows: Vec<u32> = vec![0, 1, 0, 1];
+    let hz_cols: Vec<u32> = vec![0, 1, 2, 3];
+    let hz = SparseMatrix::from_coo(2, 4, hz_rows, hz_cols)?;
 
     Ok(CssCode::new(hx, hz)?)
 }
@@ -138,6 +164,7 @@ fn create_css_code() -> Result<CssCode, Box<dyn std::error::Error>> {
 
 Combines belief propagation with ordered statistics decoding post-processing.
 
+<!--skip: API illustration - actual implementation uses different constructor signature-->
 ```rust
 use pecos_decoders::{BpOsdDecoder, Decoder, OsdMethod};
 
@@ -165,6 +192,7 @@ println!("Converged: {}", result.converged);
 
 Localized version of OSD for better scaling with large codes.
 
+<!--skip: API illustration-->
 ```rust
 use pecos_decoders::{BpLsdDecoder, Decoder};
 
@@ -179,6 +207,7 @@ let result = decoder.decode(&syndrome)?;
 
 Combines belief propagation with union-find algorithm.
 
+<!--skip: API illustration-->
 ```rust
 use pecos_decoders::{BeliefFindDecoder, Decoder, UfMethod};
 
@@ -193,6 +222,7 @@ let result = decoder.decode(&syndrome)?;
 
 Fast bit-flipping decoder suitable for real-time applications.
 
+<!--skip: API illustration-->
 ```rust
 use pecos_decoders::{FlipDecoder, Decoder, BpSchedule};
 
@@ -207,6 +237,7 @@ let result = decoder.decode(&syndrome)?;
 
 Graph-based decoder using union-find data structure.
 
+<!--skip: API illustration-->
 ```rust
 use pecos_decoders::{UnionFindDecoder, Decoder, UfMethod};
 
@@ -222,6 +253,7 @@ let result = decoder.decode(&syndrome)?;
 
 Use log-likelihood ratios for improved decoding performance.
 
+<!--skip: API illustration-->
 ```rust
 use pecos_decoders::{SoftInfoBpDecoder, SoftDecoder};
 
@@ -236,6 +268,7 @@ let result = decoder.decode_with_llrs(&syndrome, &llrs)?;
 
 Decode multiple syndromes efficiently.
 
+<!--skip: API illustration-->
 ```rust
 use pecos_decoders::BatchDecoder;
 
@@ -253,6 +286,7 @@ for (i, result) in results.iter().enumerate() {
 
 #### Performance Tuning
 
+<!--skip: API illustration-->
 ```rust
 let mut decoder = BpOsdDecoder::new(css_code);
 decoder.set_schedule(BpSchedule::Parallel);  // Use parallel BP updates
@@ -261,6 +295,7 @@ decoder.set_num_threads(4);  // Set thread count
 
 ### Error Handling
 
+<!--skip: API illustration-->
 ```rust
 match decoder.decode(&syndrome) {
     Ok(result) => {

docs/user-guide/hugr-simulation.md

@@ -65,6 +65,7 @@ Let's create a Bell state using Guppy. First, define a quantum function:
 
 === ":fontawesome-brands-rust: Rust"
 
+    <!--skip: requires pre-compiled bell_state.hugr file-->
     ```rust
     use pecos_hugr::{hugr_engine, hugr_sim};
     use pecos_engines::{ClassicalControlEngineBuilder, ClassicalEngine};
@@ -138,6 +139,7 @@ If you have HUGR files (compiled from Guppy or other tools), you can run them di
 
 === ":fontawesome-brands-rust: Rust"
 
+    <!--skip: requires pre-compiled circuit.hugr file-->
     ```rust
     use pecos_hugr::{hugr_engine, hugr_sim};
     use pecos_engines::{ClassicalControlEngineBuilder, ClassicalEngine};