Molecules

The molecules subpackage provides a registry of pre-configured molecular systems and factory functions.

Registry

registry — Molecule registry and factory functions

Defines a registry of standard molecular benchmarks used in quantum chemistry. Each entry provides a factory function that computes molecular integrals and constructs a MolecularHamiltonian.

The registry covers a range of system sizes from H2 (4 qubits) to C2H4 (28 qubits), enabling systematic benchmarking of SQD/SKQD methods.

Constants

MOLECULE_REGISTRY

Dictionary mapping lowercase molecule names to factory metadata.

Functions

get_molecule

Instantiate a Hamiltonian for a named molecule.

list_molecules

Return sorted list of registered molecule names.

qvartools.molecules.registry.get_molecule(name, device='cpu')

Create a Hamiltonian and info dict for a named molecule.

Looks up the molecule in MOLECULE_REGISTRY, runs the PySCF integral computation, and constructs a MolecularHamiltonian.

Parameters:

• name (str) – Molecule name (case-insensitive). Must be a key in MOLECULE_REGISTRY.

• device (str, optional) – Torch device for the Hamiltonian (default "cpu").

Returns:

• hamiltonian (MolecularHamiltonian) – The molecular Hamiltonian ready for diagonalisation.

• info (dict) – Metadata dictionary with keys name, n_qubits, basis, geometry, charge, spin.

Raises:

KeyError – If name is not found in the registry.

Return type:

tuple[MolecularHamiltonian, dict[str, Any]]

Examples

>>> ham, info = get_molecule("H2")
>>> info["n_qubits"]
4
>>> ham.num_sites
4

qvartools.molecules.registry.get_molecule_info(name)

Return molecule metadata without constructing a Hamiltonian.

Parameters:

name (str) – Molecule name (case-insensitive). Must be a key in MOLECULE_REGISTRY.

Returns:

Metadata dictionary with keys name, n_qubits, basis, geometry, charge, spin.

Return type:

dict

Raises:

KeyError – If name is not found in the registry.

qvartools.molecules.registry.list_molecules()

Return a sorted list of available molecule names.

Returns:

Registered molecule names in alphabetical order.

Return type:

list of str

Examples

>>> names = list_molecules()
>>> "h2" in names
True

Functions

qvartools.molecules.get_molecule(name, device='cpu')

Create a Hamiltonian and info dict for a named molecule.

Looks up the molecule in MOLECULE_REGISTRY, runs the PySCF integral computation, and constructs a MolecularHamiltonian.

Parameters:

• name (str) – Molecule name (case-insensitive). Must be a key in MOLECULE_REGISTRY.

• device (str, optional) – Torch device for the Hamiltonian (default "cpu").

Returns:

• hamiltonian (MolecularHamiltonian) – The molecular Hamiltonian ready for diagonalisation.

• info (dict) – Metadata dictionary with keys name, n_qubits, basis, geometry, charge, spin.

Raises:

KeyError – If name is not found in the registry.

Return type:

tuple[MolecularHamiltonian, dict[str, Any]]

Examples

>>> ham, info = get_molecule("H2")
>>> info["n_qubits"]
4
>>> ham.num_sites
4

qvartools.molecules.list_molecules()

Return a sorted list of available molecule names.

Returns:

Registered molecule names in alphabetical order.

Return type:

list of str

Examples

>>> names = list_molecules()
>>> "h2" in names
True

Available Molecules

Name	Qubits	Basis Set	Description
H2	4	sto-3g	Hydrogen molecule (simplest benchmark)
LiH	12	sto-6g	Lithium hydride
BeH2	14	sto-6g	Beryllium dihydride
H2O	14	sto-6g	Water molecule
NH3	16	sto-6g	Ammonia
CH4	18	sto-6g	Methane
N2	20	cc-pvdz	Dinitrogen (strongly correlated)
C2H4	28	sto-3g	Ethylene (largest benchmark)