Chemistry Extension

Overview

UnitaryLab Chemistry provides molecular electronic-structure calculations, Jordan–Wigner mapping, DMRG ground-state solving, conversion of DMRG states to quantum circuits, and grouped Hamiltonian measurements. This functionality has been separated from unitarylab.library.chemistry into an independent Python package and import namespace, unitarylab_chemistry.

Chemistry dependencies are not included in the default installation of the main unitarylab simulator. The extension is not required to build or execute ordinary quantum circuits.

Installation and platform support

UnitaryLab Chemistry requires Python 3.10+ and can be installed through the main package’s optional dependency extra:

pip install "unitarylab[chemistry]"

The Windows limitation applies only to the Chemistry extension, not the main simulator. Chemistry workflows depend on PySCF, OpenFermion, OpenFermion-PySCF, TeNPy, NetworkX, SciPy, and the main simulator. The optional installation resolves the dependencies declared for the published release.

Verify the public imports after installation:

import unitarylab_chemistry
from unitarylab_chemistry import Molecule, MolecularDMRGWorkflow
 
print(unitarylab_chemistry.__all__)

Import paths and migration

New code should import from the independent namespace:

from unitarylab_chemistry import (
    Molecule,
    MolecularDMRGResult,
    MolecularDMRGWorkflow,
)

The old path remains available as a compatibility entry point:

# Compatibility for existing code; not recommended for new code.
from unitarylab.library.chemistry import Molecule, MolecularDMRGWorkflow

The compatibility layer forwards only Molecule, MolecularDMRGResult, and MolecularDMRGWorkflow. If the separate extension is not installed, accessing these names raises ImportError with instructions to run pip install "unitarylab[chemistry]". Code that imported DMRG, measurement, or circuit-conversion functions directly from unitarylab.library.chemistry submodules should use these paths:

Workflow interface

MolecularDMRGWorkflow(
    molecule,
    *,
    shots=10_000,
    dmrg_chi0=20,
    dmrg_maxdim=100,
    dmrg_max_sweeps=100,
    dmrg_cutoff=1e-8,
    layers=None,
    renyi_indices=None,
    cvd_maxiter=200,
    cvd_restarts=3,
    cvd_init_scale=0.5,
    workdir=None,
    seed=2077,
    backend="numpy",
    device="cpu",
    dtype=np.complex128,
)

molecule must be a Molecule. workdir=None uses the current working directory. shots=0 skips finite-shot sampling but still computes the exact energy. DMRG and CVD parameters control tensor-network solving and circuit-conversion resource use, respectively.

Minimal end-to-end workflow

MolecularDMRGWorkflow runs these stages in order:

Molecule
  -> electronic_structure
  -> dmrg
  -> cvd_dmrg
  -> measurement_QASM

The following example uses H₂. The full workflow runs electronic structure, DMRG, circuit optimization, and sampling; runtime depends on the active space and computing environment.

from unitarylab_chemistry import Molecule, MolecularDMRGWorkflow
 
molecule = Molecule(
    geometry=[
        ("H", (0.0, 0.0, 0.0)),
        ("H", (0.0, 0.0, 0.7414)),
    ],
    basis="sto-3g",
    charge=0,
    multiplicity=1,
    active_occupied=1,
    active_virtual=1,
)
 
workflow = MolecularDMRGWorkflow(
    molecule, shots=10_000, workdir="chemistry-output",
    backend="numpy", device="cpu",
)
result = workflow.run(target="measurement_QASM")
 
print(result.electronic_structure)
print(result.dmrg)
print(result.cvd.circuit)
print(result.measurement)

run(target="measurement_QASM") can stop after a selected stage. Valid values are "electronic_structure", "dmrg", "cvd_dmrg", and "measurement_QASM"; another value raises ValueError. The default runs through the last stage. MolecularDMRGResult always contains molecule and populates electronic_structure, dmrg, cvd, and measurement according to completed stages; fields for stages that have not run are None.

Stage-level interfaces

To control intermediate results, import the stage functions directly:

from unitarylab_chemistry.molecule import electronic_structure
from unitarylab_chemistry.dmrg import dmrg
from unitarylab_chemistry.quantum_circuit_from_dmrg import cvd_dmrg
from unitarylab_chemistry.measurement import measurement_QASM
 
electronic = electronic_structure(molecule, workdir="chemistry-output")
dmrg_result = dmrg(electronic)
cvd_result = cvd_dmrg(dmrg_result, pauli_terms=electronic.pauli_terms)
measurement = measurement_QASM(
    cvd_result.circuit,
    electronic.pauli_terms,
    electronic.n_qubits,
    shots=10_000,
    workdir="chemistry-output",
    backend="numpy",
    device="cpu",
)

Molecule.from_xyz() also creates a molecule from a standard XYZ file. DMRG parameters, active space, CVD layer count, and optimization iterations affect accuracy, memory, and runtime. Validate the environment with a small system such as H₂/sto-3g before increasing the problem size.

Notes

• Chemistry output directories may contain integral data, QASM, measurement groups, and result files; use an explicit workdir for each experiment.
• measurement_QASM sampling depends on shots and seed; pass seed=None for non-reproducible sampling.
• DMRG and electronic-structure dependencies belong to the Chemistry extension; manually installing scattered dependencies into the main simulator is not a substitute for the official optional extra.
• The CUDA C++ backend is a separate optional capability of the main simulator. It is independent of Chemistry platform support and dependencies. Install it with pip install "unitarylab[cuda]"; the extra installs the unitarylab-cu12 wheel matching the current Python and platform.

Related pages

• Algorithm Library Overview
• Fermi–Hubbard Utilities
• Executing Circuits and Reading Results
• Submitting Hardware Jobs