Skip to content

Add Boson and Fermion quantum systems (kata #sqdq, #cqv1) - #53

Open
ellisonbg wants to merge 3 commits into
mainfrom
fermions-bosons
Open

Add Boson and Fermion quantum systems (kata #sqdq, #cqv1)#53
ellisonbg wants to merge 3 commits into
mainfrom
fermions-bosons

Conversation

@ellisonbg

Copy link
Copy Markdown
Owner

Adds two built-in production quantum systems, mirrored across the Rust core and the Python package, implementing kata issues #sqdq (Boson) and #cqv1 (Fermion) under parent #5yzk.

Both follow the established two-layer pattern: a pure-data QuantumSystem builder plus a Namespace-implementing handle.

Boson — abstract single bosonic mode (#sqdq)

The ladder-operator algebra a/a†/N on a bosonic Fock space — not the harmonic oscillator (no x/p).

  • Action: a|n⟩=√n|n−1⟩ (incl. a|0⟩=0), a†|n⟩=√(n+1)|n+1⟩, N|n⟩=n|n⟩, plus bra-side rules.
  • ⟨m|n⟩=δ, dagger (a↔a†, N Hermitian), completeness Σ|n⟩⟨n|.
  • [a,a†]=1, [N,a]=−a, [N,a†]=a† in the commutator table; ByHead([a†, a]) policy.

Fermion — single fermionic mode (#cqv1)

Occupation basis c/c†/N, states |0⟩/|1⟩, mirroring sympy physics.quantum.fermion.

  • Pauli action: c|0⟩=0, c|1⟩=|0⟩, c†|0⟩=|1⟩, c†|1⟩=0, N|k⟩=k|k⟩.
  • ⟨i|j⟩=δ, dagger, completeness Σ_{k=0}^1|k⟩⟨k|.
  • Anticommutators {c,c†}=1, {c,c}=0, {c†,c†}=0 stored in the algebra table as data ({c,c} stays a symbolic Anticommutator).

What's where

  • Rust: crates/uhlenbeck/src/systems/{mod,boson,fermion}.rs, re-exported as uhlenbeck::{Boson, Fermion}; tests in tests/systems_{boson,fermion}.rs.
  • Python: uhlenbeck.systems.{Boson,Fermion} (build + register on init, with notebook-re-run safety), also top-level uhlenbeck.{Boson,Fermion}; tests in tests/test_systems_{boson,fermion}.py.
  • Notebooks: notebooks/systems/{bosons,fermions}.ipynb (executed).

Notes / scope

  • Per qapply spec §1.2, qapply leaves ⟨m|n⟩ symbolic; the matrix element ⟨2|a†a|2⟩ reduces to 2·⟨2|2⟩ and inner-product collapse is tested via eval_inner_product_once.
  • The Boson docs were corrected (2nd commit) to state that normal_order does consume the bosonic commutator (a·a†→a†·a+1), while the fermionic anticommutator is not yet consumed.
  • Follow-ups tracked as kata issues, intentionally not in this PR:
    • #g13f — derive normal_order swaps from anticommutators (fermion support).
    • #3zrd — Rust dagger-rule construction is unsafe when rebuilding an already-registered namespace.

Verification

cargo fmt --all --check clean, cargo clippy --workspace --tests clean, full Rust workspace tests pass, Python suite 819 passed, both notebooks execute end-to-end.

🤖 Generated with Claude Code

ellisonbg and others added 3 commits May 25, 2026 14:15
Production single-mode bosonic and fermionic systems, each as a pure-data
QuantumSystem builder plus a Namespace-implementing handle, mirrored in
Rust and Python.

Boson (#sqdq): abstract ladder algebra a/adag/N on a bosonic Fock space —
not the harmonic oscillator (no x/p). Ladder + N action rules (incl.
bra-side), <m|n>=delta, dagger, ByHead([adag, a]); [a,adag]=1, [N,a]=-a,
[N,adag]=adag stored in commutator_rules as declarative data.

Fermion (#cqv1): single fermionic mode in the occupation basis. Pauli
action rules + N, <i|j>=delta for {0,1}, dagger, OrderingPolicy::None;
anticommutators {c,cdag}=1, {c,c}=0, {cdag,cdag}=0 stored in
commutator_rules as data ({c,c} stays a symbolic Anticommutator).

No engine behavior changed: the algebra relations are stored data only;
triggering them (and inner-product collapse) is future work, as specified.

- Rust: crates/uhlenbeck/src/systems/{mod,boson,fermion}.rs, re-exported
  as uhlenbeck::{Boson, Fermion}; tests in tests/systems_{boson,fermion}.rs.
- Python: uhlenbeck.systems.{Boson,Fermion} (build + register on init with
  notebook-re-run safety), also exposed top-level; tests in
  tests/test_systems_{boson,fermion}.py.
- Notebooks: notebooks/systems/{bosons,fermions}.ipynb (executed).

fmt/clippy clean; full Rust + Python suites green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Boson docs claimed `[a, a†]` was inert "future work", but with
`OrderingPolicy::ByHead([a†, a])` registered, `normal_order` actively
reorders `a·a† → a†·a + 1` via the commutator. Correct the description
(addressing review #506, finding 1) to state the current situation:

- normal_order DOES consume the bosonic commutator; the `[N, ·]` rules are
  stored but never reached (N isn't in the ByHead list).
- There is no explicit user-facing commutator-simplification trigger:
  qapply / evaluate* do not consult the algebra table — only normal_order's
  reordering does.
- The fermionic anticommutator is not yet consumed by anything (follow-up).

Updates the boson.rs module docs, the boson.py module docstring, and the
bosons notebook (new normal_order demo cell showing a·a† → a†·a + 1). No
behavior change. (fermions.ipynb: benign language_info metadata only.)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Review #507 (finding, Low): the prior doc update left three spots still
saying the algebra is "stored as data" with "triggering future work",
contradicting the corrected prose that normal_order consumes [a, a†].

Update to match: the algebra table is stored, normal_order consumes the
bosonic commutator (a·a† → a†·a + 1), and the [N, ·] rules are stored but
unreached (N not in the ByHead list).

- boson.rs / boson.py: the inline comment above commutator_rules.
- bosons.ipynb: the Summary "Algebra" bullet.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant