SQD: H₂, glycine, and embedding¶

Run these examples in order to test geometry input, integral input, and fixed-charge embedding. The Sample-based quantum diagonalization (SQD) explains installation limits, reference tiers, and result interpretation.

Prerequisites¶

Run from a Linux x86_64 checkout with Python 3.11 or newer. The production supervisor uses /proc and fork. Its calibrated resource model does not cover other platforms. The published benchmark profile used Python 3.12. Install the locked SQD and development environments:

uv sync --frozen --extra sqd --extra dev
export OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1
export NUMEXPR_NUM_THREADS=1 JAX_PLATFORMS=cpu

Set the thread variables before Python starts. SQD is CPU-based and does not need Catalyst or a GPU. The commands below use 512 shots for a quick walkthrough. The measured benchmark in examples/sqd/README.md uses 100,000 shots.

Note

Each command creates a new directory under data/output/examples/ and prints its path. Use --output NEW_PATH when you need a predictable location. The path must not already exist.

1. Establish the H₂ convention¶

Start with the smallest complete active space:

uv run --no-sync python -m examples.sqd.h2_ground_state --shots 512

The script calls q2m3.sqd.run_sqd for H₂/STO-3G with CAS(2e,2o), four system qubits, two LUCJ repetitions, and seed 31. Its four sampled determinants cover the full fixed-particle-number space. Expect a completed T0 exact_casci reference and SQD agreement near numerical precision.

This result verifies tensor conventions, energy constants, sampling conversion, and result serialization. Full-space recovery does not demonstrate a sampling advantage.

2. Run sparse glycine SQD¶

Use the smallest glycine space for the walkthrough:

uv run --no-sync python -m examples.sqd.glycine_ground_state \
  --active-space 6 --shots 512

The available glycine choices are CAS(6e,6o), CAS(8e,8o), and CAS(10e,10o), which use 12, 16, and 20 system qubits. Their full closed-shell determinant spaces contain 400, 4,900, and 63,504 alpha/beta pairs. Each choice constructs a different Hamiltonian and reference, so total energies across rows do not measure SQD convergence.

3. Measure seed spread¶

Run five consecutive seeds for CAS(6e,6o):

uv run --no-sync python -m examples.sqd.glycine_active_space_scan \
  --active-spaces 6 --shots 512

The scan starts each point in a fresh interpreter and runs the points serially. It saves every successful point immediately, records failures, and exits nonzero if any requested point fails. The default command without --active-spaces runs all three spaces and 15 calculations.

Use statistics.json for the mean, sample standard deviation, and range of the executed T0 rows. These are descriptive values for five deterministic seed choices, not confidence intervals. Missing or downgraded points never enter an exact-reference curve.

4. Verify the integral adapter¶

The lower-level entry accepts an already assembled Hamiltonian only with its authenticated frame and seed:

uv run --no-sync python -m examples.sqd.glycine_from_integrals \
  --active-space 6 --shots 512

The example creates IntegralData with build_integrals. It then creates a CCSDSeed in the same frame with build_ccsd_seed. It passes h1, chemist-order h2, e_core, IntegralContext, and the seed to run_sqd_from_integrals. The script also runs the geometry entry and compares six reported energy fields. Numerical values must agree within an absolute tolerance of 1e-8 Ha. A field may be None only if both results report None. The frame, Hamiltonian, and active-index identities must match exactly.

Both entries share the same SQD solver. Agreement verifies adapter and assembly consistency. It is not an independent numerical oracle. Do not transpose h2 or add e_core again. Bare t1 and t2 arrays cannot replace CCSDSeed.

Integral and CCSD preprocessing occurs before the lower-level engine call. It is therefore outside that call’s timings_s["total"] and embedded peak RSS. Use the complete-process monitor when that boundary matters:

uv run --no-sync python - <<'PY'
import sys
from pathlib import Path

from q2m3.profiling import measure_command

record = measure_command(
    [
        sys.executable,
        "-m",
        "examples.sqd.glycine_from_integrals",
        "--active-space",
        "6",
        "--shots",
        "512",
    ],
    Path("data/output/examples/tutorial-monitor"),
)
print(record)
if not (record["exit_code"] == 0 and record["reason"] is None):
    raise RuntimeError(f"Command failed: {record}")
PY

Run this example from the checkout root so that Python can import examples. The package API itself does not require a checkout. Choose a new monitor path for every run. To check the monitor without a scientific calculation, replace the command list with [sys.executable, "-c", "print('monitor check')"].

The monitor polls Linux /proc every 10 ms. It measures the command and its descendants visible at each poll, including imports, serialization, and figures. The measurement excludes the observer process. Polling can miss short peaks.

The monitor copies the caller’s environment, sets the OMP, MKL, OpenBLAS, and NumExpr thread counts to 1, and sets JAX_PLATFORMS=cpu. An explicit env mapping overrides those defaults by key. The default cwd is the caller’s working directory. The default budgets are 900 seconds and 8192 decimal MB.

The return value and resources.json contain exactly these ten keys:

Key	Meaning
`command`	Command argument list
`exit_code`	Child process exit code
`reason`	Monitor termination reason, or `None`
`wall_s`	Observed elapsed time in seconds
`peak_tree_rss_mb`	Largest sampled process-tree RSS in decimal MB
`poll_s`	Poll interval in seconds: `0.01`
`rss_budget_mb`	RSS budget in decimal MB
`wall_budget_s`	Wall-time budget in seconds
`scope`	Process scope of the observation
`limitation`	Sampling limitation

The new directory also contains stdout.log, with stderr merged into stdout, and rss.jsonl, with [elapsed_seconds, rss_bytes] samples. Accept the scientific output only when both the exit code and the reason indicate success.

5. Compare fixed-MO embedding modes¶

The water validation uses two asymmetric synthetic point charges and compares diagonal with full one-electron embedding:

uv run --no-sync python -m examples.qmmm.h2o_sqd_validation --shots 512

The glycine example compares vacuum, diagonal, and full-one-electron treatments in one vacuum MO frame:

uv run --no-sync python -m examples.qmmm.glycine_sqd_embedding \
  --active-space 6 --shots 512

For embedded runs, coordinates are Å, point charges are elementary-charge units, and energies are Hartree. Both modes hold the vacuum MO frame and two-electron tensor fixed. diagonal adds only active-space Delta h_pp. full_oneelectron retains the complete Delta h_pq perturbation. e_core already contains the MM-induced nuclear and frozen-core correction.

Read two effects separately:

baseline_energy(mode) - baseline_energy(vacuum) is the fixed-Hamiltonian reference shift, to the quality of each reference.
delta_mHa(mode) - delta_mHa(vacuum) is the change in SQD solver residual.

The charges are fixed test environments. These examples do not include orbital relaxation, MM polarization, solvent sampling, correlated RDM feedback, an SQD-MC loop, or a solvation free energy.

Read the artifacts¶

The H₂, glycine, integral, and glycine-embedding runs write input.json, a complete result JSON, summary.json, summary.csv, and energy/cost plots in PNG and SVG. The H₂O validation instead writes report.json, per-mode result and downstream-wrapper JSON files, summaries, and comparison plots. Scans add one subdirectory and log per point plus statistics.json. The integral example adds assembly.json and consistency.json. Failures preserve completed artifacts and write failure.json.

The key result fields are:

Field	Interpretation
`status`	`completed` or the explicitly requested `reference_only` mode
`sqd_energy`	Sampled-subspace energy in Hartree (absent for reference-only runs)
`baseline_tier`, `baseline_method`	The actual reference path. Only T0 is exact in the active space
`delta_mHa`	`1000 * (E_SQD - E_baseline)`. Positive means SQD is higher
`subspace_dim`, `full_ci_dim`	Sampled Cartesian determinant space and complete fixed-particle space
`reference_attempts`	Ordered solver selection/execution audit
`provenance`	Configuration, orbital frame, Hamiltonian, seed, and input sources
`timings_s`	Stage timings with explicit reasons for stages that did not run
`diagnostics.resources`	Polled engine-process RSS scope, cap, and timing boundary
`null_reasons`, `warnings`	Required explanations for absent or downgraded values

Preserve the complete SQDResult or its serialized sqd.result.v1 object. An energy without its method, tier, active space, frame, Hamiltonian, units, and uncertainty semantics is not an auditable result.

Resource failures and reference-only runs¶

ReferenceConfig sets one shared wall deadline and decimal-MB RSS budget. The executor uses the lowest limit: the user budget, currently available host memory, or the 8192 MB hard component cap. Predictions at a cap reject before allocation. The supervisor terminates the run when observed process-tree RSS reaches a cap. allow_large=True can cross only a soft policy boundary and cannot bypass the calibrated domain, host availability, or hard caps.

For an intentional baseline without sampling, pass mode="reference_only". The result records absent sampling fields and their reasons. A failed full run never silently becomes reference-only or substitutes HF for SQD.

See SQD result fields for all 40 result fields. See SQD measured results for measured results and research status.