fast-spicerack 0.1.1__tar.gz

fast_spicerack-0.1.1/.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      actions:
+        patterns: ["*"]

fast_spicerack-0.1.1/.github/workflows/docs.yaml

@@ -0,0 +1,66 @@
+name: Documentation
+
+# Builds the site from docs/*.md with MkDocs (pinned by flake.lock through
+# `nix develop .#docs`). Every pull request builds it in strict mode, so a
+# broken link or anchor fails the check; a push to main also deploys it.
+
+"on":
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "flake.nix"
+      - "flake.lock"
+      - ".github/workflows/docs.yaml"
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "flake.nix"
+      - "flake.lock"
+      - ".github/workflows/docs.yaml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@9383ce2bf08796b65508822f5982f49151badc4e # main
+
+      - name: Build the site (strict)
+        run: nix develop .#docs --command mkdocs build --strict --site-dir site
+
+      - name: Upload artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

fast_spicerack-0.1.1/.github/workflows/publish.yaml

@@ -0,0 +1,122 @@
+name: Publish
+
+# Releasing a version, start to finish:
+#   1. Actions -> Publish -> Run workflow, pick the bump (patch/minor/major or
+#      an explicit X.Y.Z). This opens a pull request that moves the version in
+#      Cargo.toml, pyproject.toml and Cargo.lock; bots never push to main.
+#   2. Merge it once the merge gate passes.
+#   3. The merge changes pyproject.toml on main, which runs this workflow
+#      again. If that version has no tag yet, the Release workflow
+#      (tags.yaml) tests, builds the wheels and sdist, and creates the tag and
+#      the GitHub release; then the same files go to PyPI.
+#
+# One-time setup:
+#   - PyPI: a trusted publisher for project "fast-spicerack": owner OpenFAT,
+#     repository SpiceRack, workflow publish.yaml, environment pypi.
+#   - GitHub: an environment named "pypi", and Settings -> Actions -> General
+#     -> "Allow GitHub Actions to create and approve pull requests".
+#   - Secret RELEASE_TOKEN (fine-grained PAT, contents + pull requests write).
+#     Without it the bump pull request is opened with the default token, and
+#     GitHub starts no CI for it: close and reopen it to run the checks.
+
+"on":
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: patch, minor, major, or an explicit X.Y.Z
+        required: true
+        default: patch
+  push:
+    branches: [main]
+    paths: [pyproject.toml]
+
+permissions: {}
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  # ── Step 1: the version bump, as a pull request ──
+  bump:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          token: ${{ secrets.RELEASE_TOKEN || github.token }}
+
+      - name: Bump Cargo.toml, pyproject.toml and Cargo.lock
+        id: bump
+        env:
+          BUMP: ${{ inputs.bump }}
+        run: python3 tools/bump_version.py "$BUMP" >> "$GITHUB_OUTPUT"
+
+      - name: Open the release pull request
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || github.token }}
+          VERSION: ${{ steps.bump.outputs.version }}
+        run: |
+          branch="release/v$VERSION"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git switch -c "$branch"
+          git commit -am "release: v$VERSION"
+          git push origin "$branch"
+          gh pr create --base main --head "$branch" --title "release: v$VERSION" \
+            --body "Moves the version to $VERSION. Merging it publishes v$VERSION to PyPI and GitHub (publish.yaml)."
+
+  # ── Step 3: a merged bump becomes a release ──
+  check:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      tag: ${{ steps.version.outputs.tag }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: A version this push moved, and not yet tagged?
+        id: version
+        env:
+          BEFORE: ${{ github.event.before }}
+        run: |
+          version() { sed -n 's/^version = "\(.*\)"$/\1/p' | head -1; }
+          v=$(version < pyproject.toml)
+          git fetch -q --depth=1 origin "$BEFORE"
+          was=$(git show "$BEFORE:pyproject.toml" | version)
+          if [ "$v" = "$was" ]; then
+            echo "pyproject.toml changed but the version is still $v; nothing to publish"
+          elif git ls-remote --exit-code --tags origin "refs/tags/v$v" >/dev/null; then
+            echo "v$v is already released; nothing to publish"
+          else
+            echo "tag=v$v" >> "$GITHUB_OUTPUT"
+          fi
+
+  release:
+    needs: check
+    if: needs.check.outputs.tag != ''
+    permissions:
+      contents: write
+    uses: ./.github/workflows/tags.yaml
+    with:
+      tag: ${{ needs.check.outputs.tag }}
+
+  pypi:
+    needs: release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/fast-spicerack/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

fast_spicerack-0.1.1/.github/workflows/tags.yaml

@@ -0,0 +1,115 @@
+name: Release
+
+"on":
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+  # publish.yaml calls this with the tag to create once a version bump merges.
+  workflow_call:
+    inputs:
+      tag:
+        description: Tag to release, vX.Y.Z; created on the commit being built
+        type: string
+        required: true
+
+permissions:
+  contents: write
+
+jobs:
+  # ── Refuse a tag that disagrees with the manifests, then run the merge gate ──
+  version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Tag matches Cargo.toml and pyproject.toml
+        if: github.ref_type == 'tag' || inputs.tag != ''
+        env:
+          TAG: ${{ inputs.tag || github.ref_name }}
+        run: |
+          tag="${TAG#v}"
+          for f in Cargo.toml pyproject.toml; do
+            v=$(sed -n 's/^version = "\(.*\)"$/\1/p' "$f" | head -1)
+            [ "$v" = "$tag" ] || { echo "::error::$f is $v, tag is $tag"; exit 1; }
+          done
+
+  test:
+    needs: version
+    uses: ./.github/workflows/test.yaml
+
+  # ── Python wheels (maturin) ──
+  python:
+    needs: test
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64
+          - os: macos-latest
+            target: aarch64
+          - os: windows-latest
+            target: x64
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: |
+            3.10
+            3.11
+            3.12
+            3.13
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1
+        with:
+          target: ${{ matrix.target }}
+          # One wheel per interpreter: the extension is not abi3. 3.14 needs pyo3 >= 0.25.
+          args: --release --out dist --interpreter 3.10 3.11 3.12 3.13
+          manylinux: auto
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.target }}
+          path: dist/*.whl
+
+  # ── Python sdist ──
+  sdist:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Build sdist
+        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  # ── GitHub Release ──
+  release:
+    needs: [python, sdist]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          path: artifacts
+
+      - name: Collect release assets
+        run: |
+          mkdir release
+          find artifacts -type f \( -name '*.tar.gz' -o -name '*.whl' \) -exec cp {} release/ \;
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
+        with:
+          tag_name: ${{ inputs.tag || github.ref_name }}
+          target_commitish: ${{ github.sha }}
+          files: release/*
+          generate_release_notes: true
+          prerelease: ${{ contains(inputs.tag || github.ref_name, '-') }}

fast_spicerack-0.1.1/.github/workflows/test.yaml

@@ -0,0 +1,36 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@9383ce2bf08796b65508822f5982f49151badc4e # main
+
+      - name: Setup Nix cache
+        uses: DeterminateSystems/magic-nix-cache-action@f69a2d3e148e90223fe63ab6e3f6331f2e7e33dc # main
+
+      - name: Cargo tests
+        run: nix develop .#testing --command cargo test
+
+      - name: Python tests
+        run: |
+          nix develop .#testing --command bash -c '
+            python3 -m venv .venv --system-site-packages
+            source .venv/bin/activate
+            maturin develop
+            python3 -m pytest -v
+          '

fast_spicerack-0.1.1/.gitignore

@@ -0,0 +1,31 @@
+# Build artifacts
+/target/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+python/spicerack/_native*.so
+dist/
+build/
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*~
+
+# OS
+.DS_Store
+
+# Test/cache
+.pytest_cache/
+.tox/
+
+# Nix build output
+target_nix/
+result
+result-*
+site/

fast_spicerack-0.1.1/AGENTS.md

@@ -0,0 +1,166 @@
+# AGENTS.md
+
+SpiceRack: build SPICE circuits in Python, netlist them for any simulator
+(ngspice, HSPICE, LTspice, VACASK, Spectre, ESPice), run them and read the
+results back. The core is a Rust crate (edition 2024) with PyO3 bindings
+shipped as the `spicerack` Python package. `README.md` is the overview;
+`grammar/README.md` is the dialect readers' contract.
+
+## Skills to load first
+
+Load each with the Skill tool (other agents: read
+`~/.claude/skills/<name>/SKILL.md` and the companion files it names). Source:
+https://github.com/OmarSiwy/NixOSConfig/tree/main/skills
+
+| Skill | Use it for here |
+|---|---|
+| `data-oriented-design` | `CircuitIR` (`src/ir`), the import AST and result tables: the six questions, SoA, narrowest widths, handles |
+| `codebase-clean-code` | Owners: `import` reads, `ir` holds, `codegen` writes one dialect each, `backend` runs one simulator each; one spine per direction |
+| `api-design` | Every `pub` item and the Python API (PySpice-close, backend neutral): usage code first, caller owns memory and flow |
+| `code-style` | File order, ≤500 code lines per file, `check_style.py` |
+| `simd-loops` | Hot loops over raw-file columns (`src/rawfile.rs`): the plain-loop forms, or explicit SIMD with a scalar oracle |
+| `doc-comments` | Every `pub` item |
+| `ponytail` (ultra) | How little code; never what shape the data takes |
+| `assertions` | Contracts, capacities, bounded loops |
+| `test-plan`, `tdd` | The oracles below, the gates, a feature's definition of done |
+
+Language:
+
+| Skill | Use it for here |
+|---|---|
+| `rust` | Types, memory, `zero-cost.md`: an abstraction enters a hot loop only with an `asm_probe` verdict; explicit SIMD is `fearless_simd` |
+
+Project-specific:
+
+| Skill | Use it for here |
+|---|---|
+| `compiler-construction` | `grammar/*.peg`, `src/import` and `src/codegen`: one schema every dialect captures into, lowering to `CircuitIR`, coded diagnostics, goldens |
+| `spice-engine` | Reading a simulator's result: which oracle (ngspice, VACASK, analytic) and at what tolerance |
+
+## The method
+
+Binding on every change, in every project.
+
+### Code
+
+- Five commitments: lean storage, no runtime residue, cheap change,
+  contained failure, proof by test.
+- Answer the six data questions before writing code. Then: one array per
+  field, the narrowest width the stated range allows, typed `u32` handles
+  with a sentinel, existence tables instead of flags, hot/cold split, tables
+  sized once from a named capacity, a compile-time size assertion on every
+  hot struct.
+- An abstraction on a hot path carries an assembly probe: FOLDED, IDENTICAL,
+  EQUIVALENT or NEGATIVE pass; RESIDUE fails the build. A "no residue" claim
+  cites the probe, a speed claim cites a benchmark. Dispatch per batch, never
+  per element.
+- A seam names what varies and needs a second case today; it sits on the
+  cheapest rung (concrete, free function, table, closed enum with exhaustive
+  switch, comptime, request table, function-pointer table, `dyn`, plugin).
+- Tables, transforms, one spine per pipeline (ifs up, fors down), one owner
+  writes each table and everyone else appends requests. Three likely changes
+  each have a change radius of zero; the compiler lists every other site.
+- APIs start from the caller's code. The caller owns memory and flow:
+  requests instead of callbacks, an immediate twin for anything retained.
+  Factor at the second real instance.
+- Branches: delete, then branchless, then vectorize along a lane axis. The
+  `W == 1` instantiation is the scalar oracle; vectorization is verified in
+  the assembly.
+- GPU: SoA always, the roofline ceiling named with its arithmetic before
+  tuning, data kept on the device, fixed-order reductions, the dependency DAG
+  recovered before porting. "This belongs on the CPU" is a valid verdict.
+- An operating error returns to the caller that can decide; a bug hits an
+  assertion. Two or more split, paired assertions per function, a bound on
+  every loop, input validated once at the edge, fallible work before the
+  commit.
+- Pass order: boundary, placement, data, zero-cost proof, contracts, tests,
+  branches, lanes. Data layout beats brevity. Every pass keeps NaN gates,
+  allocation-failure paths, `errdefer`s, trust-boundary validation and
+  tolerances.
+
+### Testing
+
+- The oracle is named before the code and never recomputes the answer the
+  way the code does. Cheapest first: assertions, a reference
+  implementation, a round trip, a certificate, a metamorphic relation, a
+  model, a golden with recorded provenance, a spec example.
+- The main bug class is a wrong number with no crash, which coverage and
+  fuzzing cannot see. A bug found by a person is a hole in the oracle set:
+  it lands with its regression test and the oracle or generator that would
+  have caught its class.
+- A new test goes red on the bug before it is trusted green.
+- Unsupported fails and never skips. A known failure is a named marker in
+  the tree; an unexpected pass fails until the marker goes. Name lists are
+  compared, never counts.
+- A tolerance follows the oracle's own accuracy. Determinism is a test:
+  1 job and N jobs give the same bytes, and the order is fixed, not the test.
+- A flaky test is fixed or quarantined the same day, never retried
+  silently.
+- Tiers: pre-commit under 10 s, merge under 15 min, nightly, release. A
+  release ships on numbers a script checks. The map lives in `TESTING.md`.
+
+### Builds
+
+- A build is a cache keyed on its declared inputs. Every producing step has
+  an output argument, every checking step an exit-code check, every file
+  read at run time is declared (`addFileInput`) or the step says
+  `has_side_effects`. Keys hash contents, never absolute paths.
+- Cut the artifact graph where edits land: one object per generated unit,
+  narrow imports for shared ones, kernels out of host graphs.
+- Zig edit loop: `zig build check --watch -fincremental`, one watch per
+  artifact across all worktrees; the result that counts comes from a plain
+  build. One global cache per toolchain store path; a worktree symlinks its
+  `.zig-cache` to the main checkout's.
+- Rust: flags live in `.cargo/config.toml`, never a one-off `RUSTFLAGS`;
+  `check`, `build`, `test` and rust-analyzer agree on features, profile and
+  target directory (rust-analyzer gets its own).
+- Nothing collects a cache. Keep a byte budget per cache and delete old
+  entries only while no build runs (the `long-term-garbage-collection`
+  skill); a warm cache is kept, never wiped by routine.
+- Gate on the exit code: `cmd | tail` swallows it, so use
+  `exit "${PIPESTATUS[0]}"`.
+
+### Maintaining
+
+- `main` is green by machine: work lands through a pull request whose merge
+  result passed the required checks. No `dev` branch; topic branches are
+  deleted after the merge.
+- Bots never push to `main`. Generated output ships as a release asset or
+  through a gated pull request.
+- Every dependency is pinned by commit and content hash, the toolchain by
+  `flake.lock`, actions by SHA. A third-party input you hash is mirrored
+  somewhere you control.
+- The changelog is written by hand, one line per change citing its issue,
+  every number in it measured. A release refuses a version mismatch, builds
+  every target, checks every artifact and smokes the bundle.
+- CI holds: the merge gate, every target compiled, docs that execute,
+  reference suites gated by name, a nightly, the downstream contracts, the
+  release job.
+
+## Building
+
+- Every build runs inside `nix develop -c …`; `nix develop .#testing` adds
+  ngspice, OpenVAF, VACASK and the sky130/gf180 PDKs the integration tests
+  run against. CI runs both suites in `.#testing`.
+- Rust: `cargo test` (name one test target with `--test <file>` while
+  iterating). Python: in a venv with `--system-site-packages`,
+  `maturin develop` then `python3 -m pytest`.
+- A change to the public Python API updates `docs/` and the user-facing
+  skill in `skills/spicerack/` in the same commit.
+- Run one cargo process per agent, and don't build while `free -g` shows
+  under 6 GB available.
+
+## Testing
+
+- Every test names its oracle: the independent thing that says the output is
+  wrong. A netlist is checked by running it on the real simulator or against
+  a golden with provenance, never by re-deriving it the way codegen does.
+- Unsupported fails and never skips: a missing simulator in `.#testing` is a
+  failure.
+- A golden that disagrees with an independent oracle is a bug in the code
+  that wrote it. Fix the code, regenerate the golden, and say so in the commit.
+
+## Committing
+
+Commit at every green step: both suites passing, `cargo fmt --check` clean.
+The message says what changed and in which owner. Never commit red to `main`.