Skip to main content

Crate qmbed

Crate qmbed 

Source
Expand description

§QMBED

MATRIX / SIM · Quantum Many-Body Exact Diagonalization

Rust core Language bindings Python wheels Documentation Paper workflows Release crates.io PyPI License

QMBED is a Rust-native exact-diagonalization toolkit for quantum many-body workflows. Rust, Python, and Julia all reach the same basis, operator, solver, and measurement implementation. Optimized routes are selected from mathematical capabilities—such as sparse storage, conserved sectors, or finite symmetry orbits—rather than model names.

Documentation · Rust API · Python API · Julia API · Benchmarks

§Choose an interface

InterfaceIntended useAPI policy
RustNative applications and reusable simulation componentsOne canonical typed API
PythonPython workflows and QuSpin migrationNative qmbed API plus versioned quspin compatibility
JuliaJulia-native scientific workflowsNative QMBED API only

All site indices are zero based. Python and Julia bindings are thin request builders over qmbed-capi; they do not reimplement assembly or solvers.

§Rust quick start

Install the current release from crates.io:

[dependencies]
qmbed = "0.2.0"
use qmbed::basis::SpinBasis1D;
use qmbed::operator::{
    Coupling, LocalOperator, MatrixFormat, OpProduct, OperatorBuilder, OperatorSpec,
};
use qmbed::solve::{eigsh, EigshOptions};

let basis = SpinBasis1D::builder(12).up(6).momentum(0).build()?;
let bonds = (0..12).map(|site| Coupling::new(1.0, vec![site, (site + 1) % 12]));
let zz = OpProduct::new([LocalOperator::Z, LocalOperator::Z])?;
let hamiltonian = OperatorBuilder::on(&basis)
    .term(OperatorSpec::from_product(zz, bonds)?)
    .build(MatrixFormat::Csc)?;
let low_energy = eigsh(&hamiltonian, EigshOptions::smallest_algebraic(4))?;

Python 3.10–3.14 wheels are available from PyPI with python -m pip install "qmbed==0.2.0". Julia source-install instructions and equivalent examples are in the getting-started guide while the initial General-registry submission is pending.

Rust intentionally has no migration namespace or duplicate compatibility aliases. See the Rust API stability policy for the canonical names and extension rules.

§What is implemented

  • Spin, boson, spinless/spinful fermion, photon, tensor, callback-defined, symmetry-reduced, and fixed-width wide-state bases.
  • Dense, CSC, CSR, DIA, and matrix-free operators, including rectangular operators between particle or symmetry sectors.
  • Dense Hermitian eigensolvers, shift-invert, restarted Lanczos, reusable eigensolver workspaces, Krylov evolution, FTLM/LTLM, and exponential-action plans.
  • Floquet spectra, spectral and dynamical response, expectation values, subsystem density matrices, entanglement, diagonal ensembles, state tracking, and Lindblad generators.
  • Matrix-free selected Floquet quasienergies, sector-native wide-state entanglement contractions, and portable ordered basis manifests.
  • Reusable parameter-scan operator plans and shared symmetry-orbit caches.
  • Rust-native exact JVP/VJP rules for parameterized operator actions and gap-aware Hellmann–Feynman ground-state energy gradients; an optional chainrules feature adapts the same rules to chainrules-core 0.2.

The four fixed-width state types (U256, U1024, U4096, and U16384) are independent of the small-system u128 path. Fixed-particle enumeration scales with the requested sector instead of scanning the full parent Hilbert space. See the capability guide for module-level details and current boundaries.

Native AD is operation based: iterative solvers and sparse assembly are not traced instruction by instruction. See the AD guide for formulas, diagnostics, examples, and explicit gaps. The benchmark repository separately checks gradients against finite differences and reports both end-to-end time and eigensolve counts across real ED workflows.

§Architecture

Rust API ───────────────────────────────┐
                                       │
Python native / QuSpin compatibility ─ C ABI ─ QMBED core ─ LinearOperator
                                       │                    ├─ stored sparse/dense
Julia native API ───────────────────── C ABI                └─ matrix-free

The physics-facing narrow waist is LinearOperator. A second Runtime boundary owns vectors and coarse operations. The built-in runtime is single-rank CPU; GPU and MPI profiles fail explicitly until a backend implementing that same contract is installed. Dense eigendecomposition, matrix products, and shifted sparse factorization remain isolated behind the numerical backend. More detail is available in Architecture.

§Verification and benchmarks

The repository CI checks formatting, Clippy, Rust 1.85, macOS/Windows portability, public-API semver compatibility, crates.io packaging, unit and integration tests, paper-scale visible contracts, the shared C boundary, Python compatibility, Julia bindings, and all three documentation builds.

Independent verification lives in QMBED Benchmark. It runs twelve medium-size, paper-shaped workflows on the same single-thread runner, with one warm-up, five measured samples, and workflow-specific residual, norm, or unitarity checks. The benchmark times basis construction, Hamiltonian assembly, solver or evolution, and observable evaluation end to end; it is not a microbenchmark or a claim of reproducing every paper.

See Verification for the exact test boundary and local commands.

§Contributing

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets
cargo test --release --test visible_contract -- --ignored --test-threads=1

Documentation build commands are documented in Contributing to the docs.

§License

QMBED is available under the MIT License. The frozen upstream QuSpin compatibility tests and compatibility package retain their upstream BSD-3-Clause notices.

Re-exports§

pub use error::QmbedError;
pub use error::Result;

Modules§

ad
Rust-native automatic-differentiation primitives and optional rule adapters. Rust-native differentiation primitives for QMBED scientific operations.
archive
Versioned dense and sparse operator serialization.
basis
Hilbert-space bases, sectors, symmetries, and projectors.
block
Static and time-dependent block operators.
dynamics
Time-dependent, Floquet, spectral, and correlation workflows.
error
Structured public error and result types.
interop
Runtime-owned models used by language frontends. Runtime-owned exact-diagonalization model shared by language frontends.
measure
Observables, reduced states, entanglement, and ensemble analysis.
operator
Typed local terms, universal assembly, and linear-operator storage.
runtime
Execution profiles, vector buffers, and backend extension points. Execution and vector-storage boundary.
solve
Hermitian eigensolvers, Krylov evolution, and thermal Lanczos methods.
workflow
Composite workflows such as state tracking and Lindblad generators.

Constants§

VERSION
Crate version used by verification adapters.

Type Aliases§

Complex64
Alias for a Complex<f64>