Merge branch 'main' of https://github.com/QuEraComputing/bloqade-lanes

Author: weinbe58

.github/workflows/docs.yml

@@ -0,0 +1,78 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Serialize the entire workflow (build + deploy) to prevent race conditions.
+# If two runs trigger concurrently (e.g. a push to main and a tag), the second
+# queues until the first finishes. This ensures the gh-pages checkout always
+# reflects the latest deployed state.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - uses: extractions/setup-just@v3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.5.1"
+
+      - name: Download existing site from gh-pages
+        uses: actions/checkout@v6
+        with:
+          ref: gh-pages
+          path: target/site
+        continue-on-error: true
+
+      # actions/checkout creates a .git/ directory inside target/site.
+      # Remove it so deploy-pages doesn't upload git metadata — the full
+      # site replacement only needs the built files, not the repo history.
+      - name: Remove git metadata from site checkout
+        run: rm -rf target/site/.git
+
+      - name: Determine version
+        id: version
+        run: |
+          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
+            echo "version=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+          else
+            echo "version=dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build versioned documentation
+        run: just doc-deploy ${{ steps.version.outputs.version }}
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: target/site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CLAUDE.md

@@ -43,7 +43,12 @@ just coverage          # Run Python tests with coverage + generate XML report
 just coverage-run      # Run Python tests only
 just coverage-html     # Generate HTML coverage report
 just demo              # Run all demo scripts
-just doc               # Serve mkdocs locally
+just doc               # Build and open documentation site in browser
+just doc-all           # Build documentation site (book + Rust API)
+just doc-book          # Build mdBook only
+just doc-rust          # Build Rust API docs only
+just doc-deploy <ver>  # Deploy versioned docs (e.g. dev, v0.5.0)
+just install-mdbook    # Install pinned mdBook version
 just test-python       # Run Python tests via pytest
 
 # Rust
@@ -70,7 +75,9 @@ Direct test run: `uv run coverage run -m pytest python/tests`
 
 ## Linting & Formatting
 
-Pre-commit hooks enforce all checks. The CI lint pipeline runs:
+Pre-commit hooks enforce all checks. When hooks must be bypassed (e.g. committing on orphan branches like `gh-pages` that lack `.pre-commit-config.yaml`), use `git commit -n`.
+
+The CI lint pipeline runs:
 
 ### Python
 - **isort** (profile=black, src_paths=python/bloqade)
@@ -111,7 +118,8 @@ bloqade-lanes/
 ├── Cargo.toml              # Rust workspace root
 ├── Cargo.lock
 ├── pyproject.toml           # Maturin build config + Python project metadata
-├── justfile                 # Task automation
+├── justfile                 # Task automation (pinned tool versions + all recipes)
+├── book.toml                # mdBook configuration
 ├── crates/                  # Rust workspace
 │   ├── bloqade-lanes-bytecode-core/     # Pure Rust: bytecode format, arch spec, validation
 │   ├── bloqade-lanes-bytecode-python/   # PyO3 bindings (cdylib → _native module)
@@ -139,8 +147,12 @@ bloqade-lanes/
 │   ├── bytecode/            # Bytecode-specific tests
 │   └── ...                  # Tests mirror python/bloqade/lanes structure
 ├── tests/                   # Rust integration tests
+├── docs/
+│   ├── src/                 # mdBook source (SUMMARY.md, arch/, bytecode/)
+│   ├── theme/               # Custom mdBook theme assets (version-switcher.js)
+│   └── scripts/             # Documentation deploy scripts (deploy_docs.py)
 ├── examples/                # Architecture specs and sample bytecode programs
-├── scripts/                 # Build/test utility scripts
+├── scripts/                 # Build/test utility scripts (non-docs)
 ├── demo/                    # Python demo scripts
 └── dist-data/               # Staged artifacts for wheel packaging (gitignored)
 ```

book.toml

@@ -0,0 +1,14 @@
+[book]
+title = "Bloqade Lanes"
+authors = ["QuEra Computing"]
+language = "en"
+src = "docs/src"
+
+[build]
+build-dir = "target/book"
+
+[output.html]
+git-repository-url = "https://github.com/QuEraComputing/bloqade-lanes"
+edit-url-template = "https://github.com/QuEraComputing/bloqade-lanes/edit/main/{path}"
+# Note: version-switcher.js is injected by deploy_docs.py for deployed builds only.
+# Local builds (just doc / just doc-all) do not include the version switcher.

crates/bloqade-lanes-bytecode-core/src/arch/addr.rs

@@ -1,29 +1,48 @@
+//! Bit-packed address types for bytecode instructions.
+//!
+//! These types encode device-level addresses into compact integer
+//! representations used in the 16-byte instruction format.
+
+/// Atom movement direction along a transport bus.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[repr(u8)]
 pub enum Direction {
+    /// Movement from source to destination (value 0).
     Forward = 0,
+    /// Movement from destination to source (value 1).
     Backward = 1,
 }
 
+/// Type of transport bus used for an atom move operation.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[repr(u8)]
 pub enum MoveType {
+    /// Moves atoms between sites within a word (value 0).
     SiteBus = 0,
+    /// Moves atoms between words (value 1).
     WordBus = 1,
 }
 
+/// Bit-packed atom location address (word + site).
+///
+/// Encodes `word_id` (16 bits) and `site_id` (16 bits) into a 32-bit word.
+///
+/// Layout: `[word_id:16][site_id:16]`
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct LocationAddr {
     pub word_id: u32,
     pub site_id: u32,
 }
 
 impl LocationAddr {
-    // Layout: [word_id:16][site_id:16]
+    /// Encode to a 32-bit packed integer.
+    ///
+    /// Layout: `[word_id:16][site_id:16]`
     pub fn encode(&self) -> u32 {
         ((self.word_id as u16 as u32) << 16) | (self.site_id as u16 as u32)
     }
 
+    /// Decode a 32-bit packed integer into a `LocationAddr`.
     pub fn decode(bits: u32) -> Self {
         Self {
             word_id: (bits >> 16) & 0xFFFF,
@@ -32,6 +51,14 @@ impl LocationAddr {
     }
 }
 
+/// Bit-packed lane address for atom move operations.
+///
+/// Encodes direction (1 bit), move type (1 bit), word_id (16 bits),
+/// site_id (16 bits), and bus_id (16 bits) across two 32-bit data words.
+///
+/// Layout:
+/// - data0: `[word_id:16][site_id:16]`
+/// - data1: `[dir:1][mt:1][pad:14][bus_id:16]`
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct LaneAddr {
     pub direction: Direction,
@@ -42,9 +69,7 @@ pub struct LaneAddr {
 }
 
 impl LaneAddr {
-    // Layout across two u32 words:
-    //   data0: [word_id:16][site_id:16]
-    //   data1: [dir:1][mt:1][pad:14][bus_id:16]
+    /// Encode to two 32-bit data words `(data0, data1)`.
     pub fn encode(&self) -> (u32, u32) {
         let data0 = ((self.word_id as u16 as u32) << 16) | (self.site_id as u16 as u32);
         let data1 = ((self.direction as u32) << 31)
@@ -53,11 +78,13 @@ impl LaneAddr {
         (data0, data1)
     }
 
+    /// Encode to a single 64-bit packed integer (`data0 | (data1 << 32)`).
     pub fn encode_u64(&self) -> u64 {
         let (d0, d1) = self.encode();
         (d0 as u64) | ((d1 as u64) << 32)
     }
 
+    /// Decode two 32-bit data words into a `LaneAddr`.
     pub fn decode(data0: u32, data1: u32) -> Self {
         let direction = if (data1 >> 31) & 1 == 0 {
             Direction::Forward
@@ -78,22 +105,29 @@ impl LaneAddr {
         }
     }
 
+    /// Decode a 64-bit packed integer into a `LaneAddr`.
     pub fn decode_u64(bits: u64) -> Self {
         Self::decode(bits as u32, (bits >> 32) as u32)
     }
 }
 
+/// Bit-packed zone address.
+///
+/// Encodes a zone identifier (16 bits) into a 32-bit value.
+///
+/// Layout: `[pad:16][zone_id:16]`
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ZoneAddr {
     pub zone_id: u32,
 }
 
 impl ZoneAddr {
-    // Layout: [pad:16][zone_id:16]
+    /// Encode to a 32-bit packed integer.
     pub fn encode(&self) -> u32 {
         self.zone_id as u16 as u32
     }
 
+    /// Decode a 32-bit packed integer into a `ZoneAddr`.
     pub fn decode(bits: u32) -> Self {
         Self {
             zone_id: bits & 0xFFFF,
@@ -163,6 +197,19 @@ mod tests {
         assert_eq!(LaneAddr::decode(data0, data1), addr);
     }
 
+    #[test]
+    fn test_lane_addr_u64_round_trip() {
+        let addr = LaneAddr {
+            direction: Direction::Backward,
+            move_type: MoveType::WordBus,
+            word_id: 1,
+            site_id: 0,
+            bus_id: 0,
+        };
+        let packed = addr.encode_u64();
+        assert_eq!(LaneAddr::decode_u64(packed), addr);
+    }
+
     #[test]
     fn test_zone_addr_round_trip() {
         let addr = ZoneAddr { zone_id: 42 };

crates/bloqade-lanes-bytecode-core/src/arch/mod.rs

@@ -1,3 +1,17 @@
+//! Architecture specification types, address encoding, and validation.
+//!
+//! This module defines the physical topology of a Bloqade quantum device:
+//! words, grids, transport buses, zones, and the `ArchSpec` that ties them
+//! together. It also provides bit-packed address types used by bytecode
+//! instructions and comprehensive structural validation.
+//!
+//! # Key types
+//!
+//! - [`ArchSpec`] — top-level device specification (loadable from JSON)
+//! - [`Word`], [`Grid`], [`Bus`], [`Zone`] — building blocks
+//! - [`LocationAddr`], [`LaneAddr`], [`ZoneAddr`] — bit-packed addresses
+//! - [`Direction`], [`MoveType`] — transport enums
+
 pub mod addr;
 pub mod query;
 pub mod types;

crates/bloqade-lanes-bytecode-core/src/arch/query.rs

@@ -1,3 +1,6 @@
+//! Arch spec queries: JSON loading, position lookup, lane resolution,
+//! and group-level address validation.
+
 use std::collections::HashSet;
 use std::fmt;
 
@@ -7,6 +10,7 @@ use super::addr::{LaneAddr, LocationAddr, MoveType};
 use super::types::{ArchSpec, Bus, Word};
 use super::validate::ArchSpecError;
 
+/// Error returned when loading an arch spec from JSON fails.
 #[derive(Debug, Error)]
 pub enum ArchSpecLoadError {
     #[error("JSON parse error: {0}")]