qslib command line

The qslib command is a thin interface over the validated Rust kernels. It lets a physicist inspect conventions, validate a Hamiltonian, calculate a tiny exact ground state or evolution, run a small TFIM SSE demonstration, and inspect an artifact directory without writing Rust.

Build it locally from the repository root:

cargo build --release -p qslib-quantum-cli
target/release/qslib inspect conventions

Use --json for scripts and notebooks. Without it, the command prints one labelled field per line. Errors are written to stderr and return exit status 2. They identify the physical field or convention that failed validation.

Configuration conventions

Configuration files are YAML or JSON. Dense coupling matrices are square, symmetric, zero-diagonal arrays in canonical row-major site order. Each upper triangle entry is one resolved pair coefficient, including zero coefficients. basis names the simulation basis (z, x, or y where the model supports it), while physical observable axes remain separate concepts.

Every configuration must declare the versioned scientific contract. The CLI rejects unknown fields and rejects convention metadata that does not match the selected model basis:

schema_version: qslib-model-input-v1
conventions:
  schema: qslib-conventions-v1
  site_order: row_major
  byte_order: little_endian
  basis: z

JSON results include a provenance object with this schema, the resolved model family, basis, interaction count, and operator-term count. This makes a result inspectable without guessing which convention was used.

For TFIM,

[ H=-\sum_{i<j}J_{ij}\sigma_i^z\sigma_j^z-\sum_i h_i\sigma_i^x ]

when basis: z. fields therefore contains one transverse field per site. Heisenberg configurations use the same pair matrix and represent J_ij S_i . S_j with S = sigma/2. Rydberg configurations use omega and detuning arrays in addition to the pair matrix. J1-J2 configurations use lx, ly, j1, and j2, with optional open or periodic boundaries.

Commands

qslib inspect conventions [--json]
qslib inspect environment [--json]
qslib model validate CONFIG [--json]
qslib exact ground-state CONFIG [--json]
qslib exact evolve CONFIG --t-max TIME [--imaginary] [--json]
qslib sse run CONFIG [--json]
qslib artifacts inspect PATH [--json]
qslib conformance self-test [--json]

exact ground-state reports the total energy, exact-basis dimension, and the residual norm (|H|\psi\rangle-E|\psi\rangle|). Degenerate ground spaces should be interpreted through the energy and residual, not a phase-sensitive individual eigenvector. exact evolve starts from canonical basis state zero; real time uses (e^{-iHt}), and imaginary time uses the normalized (e^{-H\tau}) convention.

The SSE command is a small-system TFIM demonstration. It reports the mean energy per site across independent logical chains. It does not claim an autocorrelation-corrected confidence interval; production studies must choose thermalization, sweep, chain, and uncertainty controls for the physical question.

artifacts inspect PATH accepts a qslib Parquet dataset directory. It validates the versioned manifest, exact completion marker, immutable part checksums, and returns the configuration checksum and convention schema. A directory that only happens to contain a file named COMPLETE is rejected.

conformance self-test reports smoke_pass for one independent one-site TFIM matrix fixture. It is an installation smoke test, not a replacement for the full conformance suite run by CI.

Worked examples

cargo run -p qslib-quantum-cli -- model validate examples/heisenberg_disordered_4.yaml
cargo run -p qslib-quantum-cli -- exact ground-state examples/tfim_4.yaml
cargo run -p qslib-quantum-cli -- exact evolve examples/tfim_4.yaml --t-max 0.1
cargo run -p qslib-quantum-cli -- sse run examples/tfim_thermal_4.yaml

The examples are executed by the CLI integration tests. The Python equivalent uses the qslib_quantum import documented in python.md.