polish docs

Author: ciaranra

.typos.toml

@@ -25,3 +25,10 @@ arange = "arange"
 nd = "nd"
 # delocate is a macOS wheel repair tool (delocate-wheel command)
 delocate = "delocate"
+# Gate name breakdown notation uses partial words like C(ontrolled), R(otation)
+ontrolled = "ontrolled"
+otation = "otation"
+repare = "repare"
+easure = "easure"
+egative = "egative"
+agger = "agger"

docs/development/DEVELOPMENT.md

@@ -151,4 +151,3 @@ PECOS_HOME = { value = "/custom/path", force = true }
 For specific development topics, see:
 
 - [Parallel Blocks and Optimization](parallel-blocks-and-optimization.md) - Guide to using and extending the Parallel block construct and optimizer
-- [PECOS Home Directory Plan](PECOS_HOME_PLAN.md) - External dependency management architecture

docs/development/parallel-blocks-and-optimization.md

@@ -1,5 +1,7 @@
 # Parallel Blocks and Optimization
 
+<!--skip: SLR examples require specific qubit API-->
+
 This guide explains the `Parallel` block construct in PECOS's SLR (Structured Language Representation) and the optimization transformations available for parallel quantum operations.
 
 ## Overview
@@ -12,7 +14,7 @@ When using `SlrConverter`, parallel optimization is enabled by default. This mea
 
 ### Creating Parallel Blocks
 
-```python
+```python,skip
 from pecos.slr import Main, Parallel, QReg
 from pecos.qeclib import qubit as qb
 
@@ -31,7 +33,7 @@ prog = Main(
 
 Parallel blocks can contain other blocks for logical grouping:
 
-```python
+```python,skip
 prog = Main(
     q := QReg("q", 6),
     Parallel(
@@ -60,7 +62,7 @@ The `ParallelOptimizer` transformation pass analyzes operations within `Parallel
 ### Example Transformation
 
 **Before optimization:**
-```python
+```python,skip
 Parallel(
     Block(H(q[0]), CX(q[0], q[1])),
     Block(H(q[2]), CX(q[2], q[3])),
@@ -69,7 +71,7 @@ Parallel(
 ```
 
 **After optimization:**
-```python
+```python,skip
 Block(
     Parallel(H(q[0]), H(q[2]), H(q[4])),  # All H gates
     Parallel(CX(q[0], q[1]), CX(q[2], q[3]), CX(q[4], q[5])),  # All CX gates
@@ -82,7 +84,7 @@ Block(
 
 The simplest way to use the optimizer is through `SlrConverter`:
 
-```python
+```python,skip
 from pecos.slr import SlrConverter
 
 # With optimization (default)
@@ -96,7 +98,7 @@ qasm_unoptimized = SlrConverter(prog, optimize_parallel=False).qasm()
 
 For more control, use the optimizer directly:
 
-```python
+```python,skip
 from pecos.slr.transforms import ParallelOptimizer
 
 optimizer = ParallelOptimizer()
@@ -135,7 +137,7 @@ The optimizer is conservative to ensure correctness:
 
 Parallel blocks containing control flow (`If`, `Repeat`) are not optimized:
 
-```python
+```python,skip
 Parallel(
     qb.H(q[0]),
     If(c[0] == 1).Then(qb.X(q[1])),  # Control flow prevents optimization
@@ -147,7 +149,7 @@ Parallel(
 
 Operations with qubit dependencies maintain their order:
 
-```python
+```python,skip
 Parallel(
     qb.H(q[0]),
     qb.CX(q[0], q[1]),  # Depends on H(q[0])
@@ -202,7 +204,7 @@ Comprehensive tests are available in:
 
 Here's a more complex example showing parallel phase gates:
 
-```python
+```python,skip
 from pecos.slr import Main, Parallel, QReg
 from pecos.qeclib import qubit as qb
 

docs/user-guide/circuit-representation.md

@@ -1,5 +1,7 @@
 # Circuit Representation
 
+<!--skip: Circuit examples require Guppy and specific circuit APIs-->
+
 PECOS provides several ways to represent and work with quantum circuits, from high-level program formats to low-level data structures.
 
 ## Quick Guide: What Should I Use?
@@ -29,7 +31,7 @@ When using PECOS's `sim()` API, you wrap your program in one of these types:
 ### Example: Different Program Types
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     from pecos import sim, Guppy, Qasm, Hugr
 
     # Guppy - recommended for new code
@@ -110,7 +112,7 @@ A directed acyclic graph representation where nodes are gates and edges are qubi
 ### Quick Start
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     from pecos.quantum import DagCircuit
 
     # Fluent builder API
@@ -142,7 +144,7 @@ A directed acyclic graph representation where nodes are gates and edges are qubi
 The fluent API automatically wires gates on the same qubit:
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     from pecos.quantum import DagCircuit
 
     circuit = DagCircuit()
@@ -214,7 +216,7 @@ The fluent API automatically wires gates on the same qubit:
 Gates can have arbitrary metadata attached:
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     from pecos.quantum import DagCircuit, Attribute
 
     circuit = DagCircuit()
@@ -248,7 +250,7 @@ Gates can have arbitrary metadata attached:
 ### Circuit Analysis
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     circuit = DagCircuit()
     circuit.h(0).cx(0, 1).h(1).cx(1, 2).mz(0).mz(1).mz(2)
 
@@ -305,7 +307,7 @@ Gates can have arbitrary metadata attached:
 For advanced use cases, you can manually add gates and wire them:
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     from pecos.quantum import DagCircuit, Gate, QubitId
 
     circuit = DagCircuit()
@@ -348,7 +350,7 @@ A time-sliced circuit representation where gates are organized into discrete tim
 ### Quick Start
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     from pecos.quantum import TickCircuit
 
     circuit = TickCircuit()
@@ -390,7 +392,7 @@ A time-sliced circuit representation where gates are organized into discrete tim
 TickCircuit prevents scheduling conflicting gates in the same tick:
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     from pecos.quantum import TickCircuit
 
     circuit = TickCircuit()
@@ -420,7 +422,7 @@ TickCircuit prevents scheduling conflicting gates in the same tick:
 ### Tick Metadata
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     circuit = TickCircuit()
 
     # Add metadata to a tick
@@ -450,7 +452,7 @@ TickCircuit prevents scheduling conflicting gates in the same tick:
 TickCircuit can be converted to and from DagCircuit:
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     from pecos.quantum import DagCircuit, TickCircuit
 
     # TickCircuit -> DagCircuit
@@ -488,7 +490,7 @@ For general graph algorithms beyond quantum circuits, PECOS provides `DiGraph` (
 A general directed graph with weighted edges and attributes:
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     from pecos.graph import DiGraph
 
     graph = DiGraph()
@@ -538,7 +540,7 @@ A general directed graph with weighted edges and attributes:
 A directed acyclic graph with topological ordering and cycle prevention:
 
 === ":fontawesome-brands-python: Python"
-    ```python
+    ```python,skip
     from pecos.graph import DAG
 
     dag = DAG()

docs/user-guide/cuda-setup.md

@@ -1,5 +1,7 @@
 # CUDA Setup Guide for GPU Simulators
 
+<!--skip: CUDA examples require cupy and NVIDIA GPU-->
+
 This guide provides detailed instructions for setting up NVIDIA CUDA support to use GPU-accelerated quantum simulators in PECOS, specifically **CuStateVec** and **MPS** (Matrix Product State).
 
 ## Overview
@@ -143,7 +145,7 @@ uv pip install -e "./python/quantum-pecos[all,cuda]"
 
 ### Test CUDA Installation
 
-```python
+```python,skip
 # Test CuPy
 import cupy as cp
 
@@ -158,7 +160,7 @@ print(f"cuStateVec available: {custatevec is not None}")
 
 ### Test PECOS Simulators
 
-```python
+```python,skip
 from pecos.simulators import CuStateVec, MPS
 
 # Test CuStateVec
@@ -243,7 +245,7 @@ uv pip install cupy-cuda12x cuquantum-python-cu12
 
 **Solution**: GPU memory is limited. Use smaller circuits or the MPS simulator for larger systems.
 
-```python
+```python,skip
 # MPS can handle larger systems with less memory
 from pecos.simulators import MPS
 
@@ -348,7 +350,7 @@ To use GPU simulators in PECOS:
    just build-cuda
    ```
 5. **Verify GPU simulators**:
-   ```python
+   ```python,skip
    from pecos.simulators import CuStateVec, MPS
 
    sim = CuStateVec(2)  # Should work!