qdk_chemistry.plugins.pyscf.conversion module

Utilities for converting between QDK/Chemistry and PySCF data structures.

This module provides conversion functions to bridge between QDK/Chemistry and PySCF data structures. It enables integration between the two quantum chemistry libraries by handling the conversion of molecular structures, basis sets, and Hamiltonians.

The main functionality includes:

  • Converting QDK/Chemistry Structure objects to PySCF atom format.

  • Converting QDK/Chemistry BasisSet objects to PySCF Mole objects.

  • Converting PySCF Mole objects back to QDK/Chemistry BasisSet objects.

  • Converting QDK/Chemistry Hamiltonian objects to PySCF SCF objects.

These utilities are essential for workflows that need to leverage both QDK/Chemistry’s data management capabilities and PySCF’s quantum chemistry calculations.

Note

Currently supports spherical atomic orbitals only. Cartesian basis set support is planned for future versions, and the helper routines assume atomic numbers do not exceed 200.

Examples

>>> from qdk_chemistry.plugins.pyscf.conversion import structure_to_pyscf_atom_labels, basis_to_pyscf_mol
>>> # Convert structure to PySCF format
>>> atoms, pyscf_symbols, elements = structure_to_pyscf_atom_labels(structure)
>>> # Convert basis set to PySCF Mole object
>>> pyscf_mol = basis_to_pyscf_mol(basis_set)
qdk_chemistry.plugins.pyscf.conversion.basis_to_pyscf_mol(basis, charge=0, multiplicity=1)[source]

Convert QDK/Chemistry BasisSet instance to PySCF Mole object.

This function extracts the structure and basis information from the QDK/Chemistry BasisSet instance and uses it to initialize a PySCF Mole object. If the BasisSet contains ECP shells, they are converted to PySCF’s ECP format.

Return type:

Mole

Parameters:

  • basis (BasisSet) – QDK/Chemistry BasisSet instance with populated basis set.

  • charge (int) – Total charge of the molecule (default: 0).

  • multiplicity (int) – Spin multiplicity (2S + 1) of the molecule (default: 1).

Returns:

PySCF Mole object initialized with the QDK/Chemistry basis set data, including ECP shells if present.

Note

When ECP shells are present, the function reconstructs the full PySCF ECP structure from QDK’s ECP shells with radial powers, preserving all exponents, coefficients, and r^n terms for each angular momentum channel.

Examples

>>> pyscf_mol = basis_to_pyscf_mol(basis, charge=0, multiplicity=1)
>>> print(pyscf_mol.atom)
qdk_chemistry.plugins.pyscf.conversion.hamiltonian_to_scf(hamiltonian, alpha_occ, beta_occ)[source]

Convert QDK/Chemistry Hamiltonian to PySCF SCF object.

This function creates a PySCF SCF object from a QDK/Chemistry Hamiltonian object, making it possible to use QDK/Chemistry Hamiltonian data with PySCF’s post-HF methods such as Coupled Cluster. It extracts one- and two-body integrals, core energy, and electron counts from the Hamiltonian and configures them in a PySCF SCF object without performing an actual SCF calculation.

Return type:

RHF

Parameters:

  • hamiltonian (Hamiltonian) –

    QDK/Chemistry Hamiltonian object.

    Contains the electronic structure information including one- and two-body integrals, core energy, and orbital data.

  • alpha_occ (ndarray) – Occupation numbers for alpha (spin-up) electrons.

  • beta_occ (ndarray) – Occupation numbers for beta (spin-down) electrons.

Returns:

PySCF RHF object initialized with the Hamiltonian data, ready for post-HF calculations. This is a “fake” SCF object that provides the necessary interfaces for post-HF methods without having performed an SCF calculation.

Raises:

ValueError – If the Hamiltonian uses unsupported features like model Hamiltonian with unrestricted orbitals, open-shell systems, or active spaces.

Note

  • This function is intended for (restricted) model hamiltonian usage, since the orbitals are not used directly.

  • If a non-model Hamiltonian is passed, this function automatically re-routes to orbitals_to_scf.

  • Active spaces are not supported.

  • The function creates a “fake” SCF object with the necessary interfaces for post-HF methods without actually performing an SCF calculation.

  • The returned SCF object contains dummy molecular orbitals and occupations suitable for post-HF method initialization.

  • For an interface using n_electrons and multiplicity, see hamiltonian_to_scf_from_n_electrons_and_multiplicity.

Examples

>>> import numpy as np
>>> from qdk_chemistry.plugins.pyscf.conversion import hamiltonian_to_scf
>>> # Convert a QDK/Chemistry Hamiltonian to a PySCF SCF object
>>> # Example for 10-electron system with 5 doubly occupied orbitals
>>> norb = hamiltonian.get_orbitals().get_num_molecular_orbitals()
>>> alpha_occ = np.zeros(norb)
>>> beta_occ = np.zeros(norb)
>>> alpha_occ[:5] = 1.0  # 5 alpha electrons
>>> beta_occ[:5] = 1.0   # 5 beta electrons
>>> pyscf_scf = hamiltonian_to_scf(hamiltonian, alpha_occ, beta_occ)
>>> # Use with PySCF post-HF methods
>>> from pyscf import cc
>>> cc_calc = cc.CCSD(pyscf_scf)
>>> cc_calc.kernel()
qdk_chemistry.plugins.pyscf.conversion.pyscf_mol_to_qdk_basis(pyscf_mol, structure, basis_name=None)[source]

Convert PySCF Mole object to QDK/Chemistry BasisSet instance.

This function extracts the basis set information from a PySCF Mole object and returns a corresponding QDK/Chemistry BasisSet instance. Both regular basis shells and ECP (Effective Core Potential) shells are extracted and converted.

Return type:

BasisSet

Parameters:

  • pyscf_mol (Mole) – PySCF Mole object with basis set data.

  • structure (Structure) – QDK/Chemistry Structure instance that defines the atomic positions and types.

  • basis_name (str | None) –

    Name for the basis set.

    If None, attempts to derive from the PySCF molecule’s basis set or defaults to “pyscf_basis”.

Returns:

QDK/Chemistry BasisSet instance initialized with the PySCF basis set data, including both regular shells and ECP shells.

Note

ECP shells are extracted with their radial powers (r^n terms) preserved. Each combination of (atom, angular momentum, radial power) with non-empty primitives creates a separate ECP shell.

qdk_chemistry.plugins.pyscf.conversion.structure_to_pyscf_atom_labels(structure)[source]

Convert QDK/Chemistry Structure to PySCF atom labels format.

This function transforms a QDK/Chemistry Structure object into the format (a tuple) required by PySCF for molecular calculations. It extracts atomic information and formats it with unique labels for each atom.

Return type:

tuple

Parameters:

structure (Structure) – QDK/Chemistry Structure object containing molecular geometry and atomic information.

Returns:

A tuple containing three lists:

  • atoms: List of atom strings in PySCF format, where each string contains the atom label and its Cartesian coordinates (x, y, z) in Angstroms. Format: Symbol<count> x y z (e.g., H1 0.000000000000 0.000000000000 0.000000000000).

  • pyscf_symbols: List of unique atom labels used in PySCF, where each atom of the same element is numbered sequentially (e.g., ["H1", "H2", "O1"]).

  • elements: List of atomic symbols without numbering, preserving the original element symbols from the structure (e.g., ["H", "H", "O"]).

Return type:

tuple[list[str], list[str], list[str]]

Note

  • Coordinates are formatted with 12 decimal places for precision.

  • Each atom of the same element receives a unique numerical suffix starting from 1.

  • The function assumes atomic numbers do not exceed 200.

Examples

>>> structure = Structure(...)  # Create or load a structure (coords in Bohr)
>>> atoms, pyscf_symbols, elements = structure_to_pyscf_atom_labels(structure)
>>> print(atoms[0])
'H1 0.000000000000 0.757000000000 0.587000000000'