Package API¶

Top-Level Package¶

Hybrid quantum-classical chemistry framework.

q2m3 provides QPE, QM/MM solvation, resource-estimation, and optional sample-based quantum diagonalization workflows.

Primary Exports¶

q2m3.QuantumQMMM
q2m3.QPEEngine
q2m3.QMMMSystem
q2m3.PySCFPennyLaneConverter
q2m3.UnifiedDensityMatrix
q2m3.MoleculeConfig
q2m3.load_xyz()
q2m3.save_json_results()
q2m3.run_sqd() (available with the sqd extra)

Optional SQD Exports¶

q2m3 loads q2m3.run_sqd on access. This export appears in q2m3.__all__ only when Python can locate both SQD backend modules. The integral entry point and typed contracts live under q2m3.sqd. See SQD API.

Constants¶

Centralized physical constants for quantum chemistry and QM/MM simulations.

All values are Python floats (NOT JAX scalars) for compatibility with both pure Python and @qjit compiled code.

Molecule Configuration¶

Molecular system configuration.

Provides a generic MoleculeConfig dataclass for configuring QM region parameters in hybrid quantum-classical simulations.

class q2m3.molecule.MoleculeConfig(name, symbols, coords, charge, active_electrons, active_orbitals, basis='sto-3g')[source]¶

Bases: object

Generic molecular system configuration.

This class supports any molecular system by specifying atomic symbols, coordinates, charge, and active space parameters.

Parameters:

name (str)
symbols (list[str])
coords (list[list[float]])
charge (int)
active_electrons (int)
active_orbitals (int)
basis (str)

name¶

Human-readable identifier for the molecule

Type:: str

symbols¶

List of atomic symbols (e.g., [“O”, “H”, “H”])

Type:: list[str]

coords¶

Atomic coordinates in Angstrom, shape (n_atoms, 3)

Type:: list[list[float]]

charge¶

Total molecular charge (0 for neutral, +1 for cation, etc.)

Type:: int

active_electrons¶

Number of active electrons for QPE active space

Type:: int

active_orbitals¶

Number of active orbitals for QPE active space

Type:: int

basis¶

Basis set name (default: “sto-3g”)

Type:: str

Example:

# Water molecule
water = MoleculeConfig(
    name="H2O",
    symbols=["O", "H", "H"],
    coords=[[0.0, 0.0, 0.117], [-0.756, 0.0, -0.469], [0.756, 0.0, -0.469]],
    charge=0,
    active_electrons=4,
    active_orbitals=4,
)

property n_atoms: int¶: Number of atoms in the molecule.

property coords_array: ndarray¶: Coordinates as numpy array.

property center: ndarray¶: Geometric center of the molecule.

validate()[source]¶

Validate configuration consistency.

Return type:: None