qdk_chemistry.migrate._orbitals module

Migrate the Orbitals serialization schema to the current version.

The only fields whose representation changed are coefficients and energies (dense per-spin arrays -> SymmetryBlockedTensor). Everything else (active/inactive index sets, AO overlap, basis set, scalar metadata) is schema-stable and carried through unchanged.

class qdk_chemistry.migrate._orbitals.BasisSet

Bases: DataClass

Represents an atomic orbital basis set using shell-based organization.

This class stores and manages atomic orbital basis set information using shells as the primary organizational unit. A shell represents a group of atomic orbitals with the same atom, angular momentum, and primitives.

Examples

Create a simple basis set:

>>> from qdk_chemistry.data import BasisSet, OrbitalType
>>> basis = BasisSet("STO-3G")
>>> basis.add_shell(0, OrbitalType.S, 1.0, 1.0)  # s orbital on atom 0
>>> print(f"Number of atomic orbitals: {basis.get_num_atomic_orbitals()}")

__init__(*args, **kwargs)

Overloaded function.

__init__(self: qdk_chemistry.data.BasisSet, name: str, shells: list, structure: qdk_chemistry.data.Structure, ao_symmetries: qdk_chemistry.data.symmetry.SymmetryProduct, ao_extents: collections.abc.Mapping[qdk_chemistry.data.symmetry.SymmetryLabel, typing.SupportsInt | typing.SupportsIndex] = {}, atomic_orbital_type: qdk_chemistry.data.AOType = <AOType.Spherical: 0>) -> None

Constructor with explicit AO symmetries.

Creates a basis set whose atomic orbitals are blocked under a caller-provided single-particle SymmetryProduct.

Parameters:

name (str) – Name of the basis set
shells (list[Shell]) – Vector of shell objects defining the atomic orbitals
structure (Structure) – Molecular structure to associate with this basis set
ao_symmetries (SymmetryProduct) – SymmetryProduct the AO basis is blocked under
ao_extents (dict[SymmetryLabel, int] | None) – Per-label AO extents; if empty, each admissible label defaults to the total atomic-orbital count
atomic_orbital_type (AOType | None) – Whether to use spherical or Cartesian atomic orbitals. Default is Spherical

Examples

>>> from qdk_chemistry.data.symmetry import SymmetryProduct, axes
>>> sym = SymmetryProduct([axes.spin(1, True)])
>>> basis = BasisSet("custom", shells, structure, sym)

__init__(self: qdk_chemistry.data.BasisSet, name: str, structure: qdk_chemistry.data.Structure, atomic_orbital_type: qdk_chemistry.data.AOType = <AOType.Spherical: 0>) -> None

Constructor with basis set name, structure, and basis type.

Creates a basis set associated with a molecular structure.

Parameters:

name (str) – Name of the basis set
structure (Structure) – Molecular structure to associate with this basis set
atomic_orbital_type (AOType | None) – Whether to use spherical or Cartesian atomic orbitals. Default is Spherical

Examples

>>> from qdk_chemistry.data import Structure
>>> structure = Structure.from_xyz_file("water.xyz")
>>> basis = BasisSet("cc-pVDZ", structure, AOType.Spherical)
>>> print(f"Basis set for {structure.get_num_atoms()} atoms")

__init__(self: qdk_chemistry.data.BasisSet, name: str, shells: collections.abc.Sequence[qdk_chemistry.data.Shell], atomic_orbital_type: qdk_chemistry.data.AOType = <AOType.Spherical: 0>) -> None

Constructor with basis set name, shells, and basis type.

Creates a basis set with predefined shells.

Parameters:

name (str) – Name of the basis set
shells (list[Shell]) – Vector of shell objects defining the atomic orbitals
atomic_orbital_type (AOType | None) – Whether to use spherical or Cartesian atomic orbitals. Default is Spherical.

Examples

>>> shells = [Shell(0, OrbitalType.S), Shell(0, OrbitalType.P)]
>>> basis = BasisSet("custom", shells)
>>> print(f"Created basis with {len(shells)} shells")

__init__(self: qdk_chemistry.data.BasisSet, name: str, shells: collections.abc.Sequence[qdk_chemistry.data.Shell], structure: qdk_chemistry.data.Structure, atomic_orbital_type: qdk_chemistry.data.AOType = <AOType.Spherical: 0>) -> None

Constructor with basis set name, shells, structure, and basis type.

Creates a complete basis set with shells and molecular structure.

Parameters:

name (str) – Name of the basis set
shells (list[Shell]) – Vector of shell objects defining the atomic orbitals
structure (Structure) – Molecular structure to associate with this basis set
atomic_orbital_type (AOType | None) – Whether to use spherical or Cartesian atomic orbitals. Default is Spherical

Examples

>>> from qdk_chemistry.data import Structure
>>> structure = Structure.from_xyz_file("water.xyz")
>>> shells = [Shell(0, OrbitalType.S), Shell(1, OrbitalType.S)]
>>> basis = BasisSet("custom", shells, structure)
>>> print(f"Complete basis set with {len(shells)} shells")

__init__(self: qdk_chemistry.data.BasisSet, name: str, shells: collections.abc.Sequence[qdk_chemistry.data.Shell], ecp_shells: collections.abc.Sequence[qdk_chemistry.data.Shell], structure: qdk_chemistry.data.Structure, atomic_orbital_type: qdk_chemistry.data.AOType = <AOType.Spherical: 0>) -> None

Constructor with basis set name, shells, ECP shells, structure, and basis type.

Creates a complete basis set with regular shells, ECP shells, and molecular structure.

Parameters:

name (str) – Name of the basis set
shells (list[Shell]) – Vector of shell objects defining the atomic orbitals
ecp_shells (list[Shell]) – Vector of ECP shell objects
structure (Structure) – Molecular structure to associate with this basis set
atomic_orbital_type (AOType | None) – Whether to use spherical or Cartesian atomic orbitals. Default is Spherical

Examples

>>> from qdk_chemistry.data import Structure
>>> structure = Structure.from_xyz_file("water.xyz")
>>> shells = [Shell(0, OrbitalType.S), Shell(1, OrbitalType.S)]
>>> ecp_shells = [Shell(0, OrbitalType.S, exp, coeff, rpow)]
>>> basis = BasisSet("custom-ecp", shells, ecp_shells, structure)
>>> print(f"Basis with {len(shells)} shells and {len(ecp_shells)} ECP shells")

__init__(self: qdk_chemistry.data.BasisSet, name: str, shells: collections.abc.Sequence[qdk_chemistry.data.Shell], ecp_name: str, ecp_shells: collections.abc.Sequence[qdk_chemistry.data.Shell], ecp_electrons: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex], structure: qdk_chemistry.data.Structure, atomic_orbital_type: qdk_chemistry.data.AOType = <AOType.Spherical: 0>) -> None

Constructor with basis set name, shells, ECP name, ECP shells, ECP electrons, structure, and basis type.

Creates a complete basis set with regular shells, ECP shells, ECP metadata, and molecular structure.

Parameters:

name (str) – Name of the basis set
shells (list[Shell]) – Vector of shell objects defining the atomic orbitals
ecp_name (str) – Name of the ECP (basis set)
ecp_shells (list[Shell]) – Vector of ECP shell objects
ecp_electrons (list[int]) – Number of ECP electrons for each atom
structure (Structure) – Molecular structure to associate with this basis set
atomic_orbital_type (AOType | None) – Whether to use spherical or Cartesian atomic orbitals. Default is Spherical

Examples

>>> from qdk_chemistry.data import Structure
>>> structure = Structure.from_xyz_file("water.xyz")
>>> shells = [Shell(0, OrbitalType.S), Shell(1, OrbitalType.S)]
>>> ecp_shells = [Shell(0, OrbitalType.S, exp, coeff, rpow)]
>>> ecp_electrons = [10, 10, 0]
>>> basis = BasisSet("custom-ecp", shells, "custom-ecp", ecp_shells, ecp_electrons, structure)
>>> print(f"Basis with {len(shells)} shells, {len(ecp_shells)} ECP shells, ECP: {basis.get_ecp_name()}")

__init__(self: qdk_chemistry.data.BasisSet, arg0: qdk_chemistry.data.BasisSet) -> None

Copy constructor.

Creates a deep copy of another basis set.

Parameters:: other (BasisSet) – Basis set to copy

Examples

>>> original = BasisSet("cc-pVDZ")
>>> copy = BasisSet(original)
>>> print(f"Copied basis set: {copy.get_name()}")

ao_extents(self: qdk_chemistry.data.BasisSet) → dict[qdk_chemistry.data.symmetry.SymmetryLabel, int]

Get the per-label AO extents.

Returns:

Mapping from SymmetryLabel: to the number of atomic orbitals carried by that symmetry block.

Return type:

dict[SymmetryLabel, int]

Examples

>>> extents = basis_set.ao_extents()

ao_symmetries(self: qdk_chemistry.data.BasisSet) → qdk_chemistry.data.symmetry.SymmetryProduct

Get the single-particle SymmetryProduct the AO basis is blocked under.

Returns:

The AO SymmetryProduct. Defaults to a: restricted spin axis when not specified at construction.

Return type:

SymmetryProduct

Examples

>>> sym = basis_set.ao_symmetries()

static atomic_orbital_type_to_string(atomic_orbital_type: qdk_chemistry.data.AOType) → str

Convert basis type enum to string representation.

Parameters:: atomic_orbital_type (AOType) – The basis type enum value
Returns:: String representation (“Spherical” or “Cartesian”);
Return type:: str

Examples

>>> basis_str = BasisSet.atomic_orbital_type_to_string(AOType.Spherical)
>>> print(f"Basis type: {basis_str}")  # Prints "Spherical"

basis_to_shell_index(self: qdk_chemistry.data.BasisSet, atomic_orbital_index: SupportsInt | SupportsIndex) → tuple[int, int]

Convert atomic orbital index to shell index and local function index.

Parameters:: atomic_orbital_index (int) – Global atomic orbital index
Returns:: Shell index and local function index within that shell
Return type:: tuple[int, int]

Examples

>>> shell_idx, local_idx = basis_set.basis_to_shell_index(7)
>>> print(f"atomic orbital 7: shell {shell_idx}, local index {local_idx}")

custom_ecp_name = 'custom_ecp'

custom_name = 'custom_basis_set'

static from_basis_name(basis_name: str, structure: qdk_chemistry.data.Structure, atomic_orbital_type: qdk_chemistry.data.AOType = <AOType.Spherical: 0>) → qdk_chemistry.data.BasisSet

Create a basis set by name for a molecular structure.

Loads a standard basis set (e.g., “sto-3g”, “cc-pvdz”) for all atoms in the structure.

Parameters:

basis_name (str) – Name of the basis set (e.g., “sto-3g”, “cc-pvdz”, “6-31g”);
structure (Structure) – Molecular structure
atomic_orbital_type (AOType, optional) – Whether to use spherical or Cartesian atomic orbitals. Default is Spherical

Returns:

New basis set instance

Return type:

BasisSet

Raises:

ValueError – If basis set name is not recognized or structure is invalid

Examples

>>> from qdk_chemistry.data import Structure
>>> structure = Structure.from_xyz_file("water.xyz")
>>> basis = BasisSet.from_basis_name("sto-3g", structure)
>>> print(f"Created {basis.get_name()} basis with {basis.get_num_shells()} shells")

static from_element_map(element_to_basis_map: collections.abc.Mapping[str, str], structure: qdk_chemistry.data.Structure, atomic_orbital_type: qdk_chemistry.data.AOType = <AOType.Spherical: 0>) → qdk_chemistry.data.BasisSet

Create a basis set with different basis sets per element.

Allows specifying different basis sets for different elements in the structure.

Parameters:

element_to_basis_map (dict[str, str]) – Dictionary mapping element symbols to basis set names. Example: {“H”: “sto-3g”, “O”: “cc-pvdz”}
structure (Structure) – Molecular structure
atomic_orbital_type (AOType, optional) – Whether to use spherical or Cartesian atomic orbitals. Default is Spherical

Returns:

New basis set instance with custom name “custom_basis_set”

Return type:

BasisSet

Raises:

ValueError – If any element in structure is not in the map or basis set names are invalid

Examples

>>> from qdk_chemistry.data import Structure
>>> structure = Structure.from_xyz_file("water.xyz")
>>> basis_map = {"H": "sto-3g", "O": "cc-pvdz"}
>>> basis = BasisSet.from_element_map(basis_map, structure)
>>> print(f"Created custom basis with {basis.get_num_shells()} shells")

static from_file(filename: object, type: str) → qdk_chemistry.data.BasisSet

Load basis set from file with specified format.

Generic method to load basis set data from a file. The format is determined by the ‘type’ parameter.

Parameters:

filename (str | pathlib.Path) – Path to the file to read. Must have ‘.basis_set’ before the file extension (e.g., sto-3g.basis_set.json, cc-pvdz.basis_set.h5);
type (str) – File format type (“json” or “hdf5”);

Returns:

New BasisSet instance loaded from file

Return type:

BasisSet

Raises:

RuntimeError – If the file cannot be opened/read, invalid data format, or unsupported type

Examples

>>> basis_set = BasisSet.from_file("sto-3g.basis_set.json", "json")
>>> basis_set = BasisSet.from_file("cc-pvdz.basis_set.h5", "hdf5")

static from_hdf5_file(filename: object) → qdk_chemistry.data.BasisSet

Load basis set from HDF5 file (with validation).

Reads basis set data from an HDF5 file and returns a new BasisSet instance. The file should contain data in the format produced by to_hdf5_file().

Parameters:

filename (str | pathlib.Path) – Path to the HDF5 file to read. Must have ‘.basis_set’ before the file extension (e.g., sto-3g.basis_set.h5, cc-pvdz.basis_set.hdf5);

Returns:

New BasisSet instance loaded from file

Return type:

BasisSet

Raises:

ValueError – If filename doesn’t follow the required naming convention
RuntimeError – If the file cannot be opened, read, or contains invalid basis set data

Examples

>>> basis_set = BasisSet.from_hdf5_file("sto-3g.basis_set.h5")
>>> basis_set = BasisSet.from_hdf5_file("cc-pvdz.basis_set.hdf5")

static from_index_map(index_to_basis_map: collections.abc.Mapping[typing.SupportsInt | typing.SupportsIndex, str], structure: qdk_chemistry.data.Structure, atomic_orbital_type: qdk_chemistry.data.AOType = <AOType.Spherical: 0>) → qdk_chemistry.data.BasisSet

Create a basis set with different basis sets per atom index.

Allows specifying different basis sets for individual atoms by their index.

Parameters:

index_to_basis_map (dict[int, str]) – Dictionary mapping atom indices to basis set names. Example: {0: “sto-3g”, 1: “cc-pvdz”, 2: “sto-3g”}
structure (Structure) – Molecular structure
atomic_orbital_type (AOType, optional) – Whether to use spherical or Cartesian atomic orbitals. Default is Spherical

Returns:

New basis set instance with custom name “custom_basis_set”

Return type:

BasisSet

Raises:

ValueError – If any atom index in structure is not in the map or basis set names are invalid

Examples

>>> from qdk_chemistry.data import Structure
>>> structure = Structure.from_xyz_file("water.xyz")
>>> basis_map = {0: "cc-pvdz", 1: "sto-3g", 2: "sto-3g"}  # O at 0, H at 1 and 2
>>> basis = BasisSet.from_index_map(basis_map, structure)
>>> print(f"Created custom basis with {basis.get_num_shells()} shells")

static from_json(json_str: str) → qdk_chemistry.data.BasisSet

Load basis set from JSON string.

Parses basis set data from a JSON string and returns a new BasisSet instance. The string should contain JSON data in the format produced by to_json().

Parameters:: json_str (str) – JSON string containing basis set data
Returns:: New BasisSet instance loaded from JSON
Return type:: BasisSet
Raises:: RuntimeError – If the JSON string is malformed or contains invalid basis set data

Examples

>>> basis_set = BasisSet.from_json('{"name": "STO-3G", "shells": [...]}')

static from_json_file(filename: object) → qdk_chemistry.data.BasisSet

Load basis set from JSON file (with validation).

Reads basis set data from a JSON file and returns a new BasisSet instance. The file should contain JSON data in the format produced by to_json_file().

Parameters:

filename (str) – Path to the JSON file to read. Must have ‘.basis_set’ before the file extension (e.g., sto-3g.basis_set.json, cc-pvdz.basis_set.json);

Returns:

New BasisSet instance loaded from file

Return type:

BasisSet

Raises:

ValueError – If filename doesn’t follow the required naming convention
RuntimeError – If the file cannot be opened, read, or contains invalid basis set data

Examples

>>> basis_set = BasisSet.from_json_file("sto-3g.basis_set.json")
>>> basis_set = BasisSet.from_json_file("my_basis.basis_set.json")

static get_angular_momentum(orbital_type: qdk_chemistry.data.OrbitalType) → int

Get angular momentum quantum number for orbital type.

Parameters:: orbital_type (OrbitalType) – The orbital type
Returns:: Angular momentum quantum number l (0=s, 1=p, 2=d, etc.);
Return type:: int

Examples

>>> l = BasisSet.get_angular_momentum(OrbitalType.D)
>>> print(f"D orbital has l = {l}")  # l = 2

get_atom_index_for_atomic_orbital(self: qdk_chemistry.data.BasisSet, atomic_orbital_index: SupportsInt | SupportsIndex) → int

Get the atom index for a given atomic orbital.

Parameters:

atomic_orbital_index (int) – Global index of the atomic orbital

Returns:

Index of the atom to which this atomic orbital belongs.: Index of the atom to which this atomic orbital belongs

Return type:

int

Examples

>>> atom_idx = basis_set.get_atom_index_for_atomic_orbital(3)
>>> print(f"atomic orbital 3 belongs to atom {atom_idx}")

get_atomic_orbital_indices_for_atom(self: qdk_chemistry.data.BasisSet, atom_index: SupportsInt | SupportsIndex) → list[int]

Get all atomic orbital indices for a specific atom.

Parameters:: atom_index (int) – Index of the atom
Returns:: Vector of global atomic orbital indices for the atom
Return type:: list[int]

Examples

>>> atomic_orbital_indices = basis_set.get_atomic_orbital_indices_for_atom(0)
>>> print(f"Atom 0 has atomic orbitals: {atomic_orbital_indices}")

get_atomic_orbital_info(self: qdk_chemistry.data.BasisSet, atomic_orbital_index: SupportsInt | SupportsIndex) → tuple[int, int]

Get shell index and magnetic quantum number for a atomic orbital.

Parameters:: atomic_orbital_index (int) – Global index of the atomic orbital
Returns:: Shell index and magnetic quantum number (m_l) for the atomic orbital
Return type:: tuple[int, int]

Examples

>>> shell_idx, m_l = basis_set.get_atomic_orbital_info(5)
>>> print(f"atomic orbital 5: shell {shell_idx}, m_l = {m_l}")

get_atomic_orbital_type(self: qdk_chemistry.data.BasisSet) → qdk_chemistry.data.AOType

Get the basis type.

Returns:: Current basis type (Spherical or Cartesian)
Return type:: AOType

Examples

>>> atomic_orbital_type = basis_set.get_atomic_orbital_type()
>>> print(f"Basis type: {atomic_orbital_type}")

get_ecp_electrons(self: qdk_chemistry.data.BasisSet) → list[int]

Get the ECP (Effective Core Potential) electrons vector.

Returns:: Number of ECP electrons for each atom
Return type:: list[int]

Examples

>>> ecp_electrons = basis_set.get_ecp_electrons()
>>> print(f"ECP electrons per atom: {ecp_electrons}")

get_ecp_name(self: qdk_chemistry.data.BasisSet) → str

Get the ECP (Effective Core Potential) name.

Returns:: Name of the ECP (basis set);
Return type:: str

Examples

>>> ecp_name = basis_set.get_ecp_name()
>>> print(f"ECP: {ecp_name}")

get_ecp_shell(self: qdk_chemistry.data.BasisSet, shell_index: SupportsInt | SupportsIndex) → qdk_chemistry.data.Shell

Get a specific ECP shell by global index.

Parameters:: shell_index (int) – Global index of the ECP shell
Returns:: Reference to the specified ECP shell
Return type:: Shell
Raises:: IndexError – If ECP shell index is out of range

Examples

>>> ecp_shell = basis_set.get_ecp_shell(0)
>>> print(f"First ECP shell has {ecp_shell.get_num_primitives()} primitives")

get_ecp_shell_indices_for_atom(self: qdk_chemistry.data.BasisSet, atom_index: SupportsInt | SupportsIndex) → list[int]

Get ECP shell indices for a specific atom.

Parameters:: atom_index (int) – Index of the atom
Returns:: Vector of ECP shell indices for this atom
Return type:: list[int]

Examples

>>> ecp_indices = basis_set.get_ecp_shell_indices_for_atom(0)
>>> print(f"Atom 0 ECP shell indices: {ecp_indices}")

get_ecp_shell_indices_for_atom_and_orbital_type(self: qdk_chemistry.data.BasisSet, atom_index: SupportsInt | SupportsIndex, orbital_type: qdk_chemistry.data.OrbitalType) → list[int]

Get ECP shell indices for a specific atom and orbital type.

Parameters:

atom_index (int) – Index of the atom
orbital_type (OrbitalType) – Type of orbital (S, P, D, F, etc.);

Returns:

Vector of ECP shell indices matching both criteria

Return type:

list[int]

Examples

>>> p_ecp_indices = basis_set.get_ecp_shell_indices_for_atom_and_orbital_type(0, OrbitalType.P)
>>> print(f"P-type ECP shells on atom 0: {p_ecp_indices}")

get_ecp_shell_indices_for_orbital_type(self: qdk_chemistry.data.BasisSet, orbital_type: qdk_chemistry.data.OrbitalType) → list[int]

Get ECP shell indices for a specific orbital type.

Parameters:: orbital_type (OrbitalType) – Type of orbital (S, P, D, F, etc.);
Returns:: Vector of ECP shell indices of this type
Return type:: list[int]

Examples

>>> s_ecp_indices = basis_set.get_ecp_shell_indices_for_orbital_type(OrbitalType.S)
>>> print(f"S-type ECP shell indices: {s_ecp_indices}")

get_ecp_shells(self: qdk_chemistry.data.BasisSet) → list[qdk_chemistry.data.Shell]

Get all ECP shells (flattened from per-atom storage).

Returns:: Vector of all ECP shells in the basis set
Return type:: list[Shell]

Examples

>>> ecp_shells = basis_set.get_ecp_shells()
>>> print(f"Total ECP shells: {len(ecp_shells)}")

get_ecp_shells_for_atom(self: qdk_chemistry.data.BasisSet, atom_index: SupportsInt | SupportsIndex) → list[qdk_chemistry.data.Shell]

Get ECP shells for a specific atom.

Parameters:: atom_index (int) – Index of the atom
Returns:: Vector of ECP shells for the specified atom
Return type:: list[Shell]

Examples

>>> ecp_atom_shells = basis_set.get_ecp_shells_for_atom(0)
>>> print(f"Atom 0 has {len(ecp_atom_shells)} ECP shells")

get_name(self: qdk_chemistry.data.BasisSet) → str

Get the basis set name.

Returns:: Name of the basis set (e.g., “6-31G”, “cc-pVDZ”);
Return type:: str

Examples

>>> name = basis_set.get_name()
>>> print(f"Using basis set: {name}")

get_num_atomic_orbitals(self: qdk_chemistry.data.BasisSet) → int

Get total number of atomic orbitals in the basis set.

Returns:: Total number of atomic orbitals from all shells
Return type:: int

Examples

>>> n_basis = basis_set.get_num_atomic_orbitals()
>>> print(f"Total atomic orbitals: {n_basis}")

get_num_atomic_orbitals_for_atom(self: qdk_chemistry.data.BasisSet, atom_index: SupportsInt | SupportsIndex) → int

Get number of atomic orbitals for a specific atom.

Parameters:: atom_index (int) – Index of the atom
Returns:: Number of atomic orbitals on the specified atom
Return type:: int

Examples

>>> n_funcs = basis_set.get_num_atomic_orbitals_for_atom(0)
>>> print(f"Atom 0 has {n_funcs} atomic orbitals")

get_num_atomic_orbitals_for_orbital_type(self: qdk_chemistry.data.BasisSet, orbital_type: qdk_chemistry.data.OrbitalType) → int

Get total number of atomic orbitals for a specific orbital type.

Parameters:: orbital_type (OrbitalType) – Type of orbital (S, P, D, F, etc.);
Returns:: Total number of atomic orbitals of the specified type
Return type:: int

Examples

>>> n_p_funcs = basis_set.get_num_atomic_orbitals_for_orbital_type(OrbitalType.P)
>>> print(f"Total P-type atomic orbitals: {n_p_funcs}")

get_num_atoms(self: qdk_chemistry.data.BasisSet) → int

Get number of atoms that have shells.

Returns:: Number of atoms with shells
Return type:: int

Examples

>>> n_atoms = basis_set.get_num_atoms()
>>> print(f"Atoms with atomic orbitals: {n_atoms}")

get_num_ecp_shells(self: qdk_chemistry.data.BasisSet) → int

Get total number of ECP shells across all atoms.

Returns:: Total number of ECP shells
Return type:: int

Examples

>>> n_ecp_shells = basis_set.get_num_ecp_shells()
>>> print(f"Total ECP shells: {n_ecp_shells}")

static get_num_orbitals_for_l(l: SupportsInt | SupportsIndex, atomic_orbital_type: qdk_chemistry.data.AOType = <AOType.Spherical: 0>) → int

Get number of orbitals for given angular momentum.

Parameters:

l (int) – Angular momentum quantum number
atomic_orbital_type (AOType, optional) – Whether to use spherical (2l+1) or Cartesian functions Default is Spherical

Returns:

Number of orbital functions

Return type:

int

Examples

>>> # For d orbitals (l=2)
>>> n_sph = BasisSet.get_num_orbitals_for_l(2, AOType.Spherical)  # 5
>>> n_cart = BasisSet.get_num_orbitals_for_l(2, AOType.Cartesian)  # 6
>>> print(f"d orbitals: {n_sph} spherical, {n_cart} Cartesian")

get_num_shells(self: qdk_chemistry.data.BasisSet) → int

Get total number of shells across all atoms.

Returns:: Total number of shells
Return type:: int

Examples

>>> n_shells = basis_set.get_num_shells()
>>> print(f"Total shells: {n_shells}")

get_shell(self: qdk_chemistry.data.BasisSet, shell_index: SupportsInt | SupportsIndex) → qdk_chemistry.data.Shell

Get a specific shell by global index.

Parameters:: shell_index (int) – Global index of the shell
Returns:: Reference to the specified shell
Return type:: Shell
Raises:: IndexError – If shell index is out of range

Examples

>>> shell = basis_set.get_shell(0)
>>> print(f"First shell type: {shell.orbital_type}")

get_shell_indices_for_atom(self: qdk_chemistry.data.BasisSet, atom_index: SupportsInt | SupportsIndex) → list[int]

Get shell indices for a specific atom.

Parameters:: atom_index (int) – Index of the atom
Returns:: Vector of global shell indices for the atom
Return type:: list[int]

Examples

>>> shell_indices = basis_set.get_shell_indices_for_atom(0)
>>> print(f"Atom 0 has shells: {shell_indices}")

get_shell_indices_for_atom_and_orbital_type(self: qdk_chemistry.data.BasisSet, atom_index: SupportsInt | SupportsIndex, orbital_type: qdk_chemistry.data.OrbitalType) → list[int]

Get shell indices for a specific atom and orbital type.

Parameters:

atom_index (int) – Index of the atom
orbital_type (OrbitalType) – Type of orbital (S, P, D, F, etc.);

Returns:

Vector of shell indices matching both criteria

Return type:

list[int]

Examples

>>> p_shell_indices = basis_set.get_shell_indices_for_atom_and_orbital_type(0, OrbitalType.P)
>>> print(f"P-shells on atom 0: {p_shell_indices}")

get_shell_indices_for_orbital_type(self: qdk_chemistry.data.BasisSet, orbital_type: qdk_chemistry.data.OrbitalType) → list[int]

Get shell indices for a specific orbital type.

Parameters:: orbital_type (OrbitalType) – Type of orbital (S, P, D, F, etc.);
Returns:: Vector of shell indices with the specified orbital type
Return type:: list[int]

Examples

>>> p_shells = basis_set.get_shell_indices_for_orbital_type(OrbitalType.P)
>>> print(f"P-shell indices: {p_shells}")

get_shells(self: qdk_chemistry.data.BasisSet) → list[qdk_chemistry.data.Shell]

Get all shells (flattened from per-atom storage).

Returns:: Vector of all shells in the basis set
Return type:: list[Shell]

Examples

>>> shells = basis_set.get_shells()
>>> print(f"Total shells: {len(shells)}")

get_shells_for_atom(self: qdk_chemistry.data.BasisSet, atom_index: SupportsInt | SupportsIndex) → list[qdk_chemistry.data.Shell]

Get shells for a specific atom.

Parameters:: atom_index (int) – Index of the atom
Returns:: Vector of shells for the specified atom
Return type:: list[Shell]

Examples

>>> atom_shells = basis_set.get_shells_for_atom(0)
>>> print(f"Atom 0 has {len(atom_shells)} shells")

get_structure(self: qdk_chemistry.data.BasisSet) → qdk_chemistry.data.Structure

Get the molecular structure.

Returns:: The molecular structure associated with this basis set
Return type:: Structure
Raises:: RuntimeError – If no structure is associated with this basis set

Examples

>>> structure = basis_set.get_structure()
>>> print(f"Number of atoms: {structure.get_num_atoms()}")

get_summary(self: qdk_chemistry.data.BasisSet) → str

Get summary string of basis set information.

Returns:: Human-readable summary of basis set properties
Return type:: str

Examples

>>> summary = basis_set.get_summary()
>>> print(summary)

static get_supported_basis_set_names() → list[str]

Get list of supported basis set names.

Returns:: Vector of supported basis set names
Return type:: list[str]

Examples

>>> supported = BasisSet.get_supported_basis_set_names()

static get_supported_elements_for_basis_set(basis_name: str) → list[qdk_chemistry.data.Element]

Get list of supported elements for a given basis set.

Returns all elements that are defined for the specified basis set.

Parameters:: basis_name (str) – Name of the basis set (e.g., “sto-3g”, “cc-pvdz”);
Returns:: Vector of supported elements as Element enum values
Return type:: list[Element]

Examples

>>> elements = BasisSet.get_supported_elements_for_basis_set("sto-3g")
>>> print(f"STO-3G supports: {[elem.name for elem in elements]}")

has_ecp_electrons(self: qdk_chemistry.data.BasisSet) → bool

Check if ECP (Effective Core Potential) electrons are present.

Returns:: True if ECP electrons are present, False otherwise
Return type:: bool

Examples

>>> if basis_set.has_ecp_electrons():
...     ecp_electrons = basis_set.get_ecp_electrons()
...     print(f"ECP electrons per atom: {ecp_electrons}")

has_ecp_shells(self: qdk_chemistry.data.BasisSet) → bool

Check if this basis set has ECP shells.

Returns:: True if there are any ECP shells
Return type:: bool

Examples

>>> if basis_set.has_ecp_shells():
...     print("This basis set includes ECP shells")

has_structure(self: qdk_chemistry.data.BasisSet) → bool

Check if a structure is associated with this basis set.

Returns:: True if a molecular structure is set, False otherwise
Return type:: bool

Examples

>>> if basis_set.has_structure():
...     structure = basis_set.get_structure()
... else:
...     print("No structure associated with basis set")

static l_to_orbital_type(l: SupportsInt | SupportsIndex) → qdk_chemistry.data.OrbitalType

Get orbital type for angular momentum quantum number.

Parameters:: l (int) – Angular momentum quantum number
Returns:: Corresponding orbital type (S, P, D, etc.);
Return type:: OrbitalType
Raises:: ValueError – If l is negative or exceeds supported range

Examples

>>> orbital_type = BasisSet.l_to_orbital_type(2)
>>> print(f"l=2 corresponds to orbital type: {orbital_type}")  # D

static orbital_type_to_string(orbital_type: qdk_chemistry.data.OrbitalType) → str

Convert orbital type enum to string representation.

Parameters:: orbital_type (OrbitalType) – The orbital type enum value
Returns:: String representation (e.g., “S”, “P”, “D”, “F”);
Return type:: str

Examples

>>> orbital_str = BasisSet.orbital_type_to_string(OrbitalType.P)
>>> print(f"Orbital type: {orbital_str}")  # Prints "P"

static string_to_atomic_orbital_type(basis_string: str) → qdk_chemistry.data.AOType

Convert string to basis type enum.

Parameters:: basis_string (str) – String representation (“Spherical” or “Cartesian”);
Returns:: Corresponding basis type enum
Return type:: AOType
Raises:: ValueError – If the string does not correspond to a valid basis type

Examples

>>> atomic_orbital_type = BasisSet.string_to_atomic_orbital_type("Cartesian")
>>> print(atomic_orbital_type)  # AOType.Cartesian

static string_to_orbital_type(orbital_string: str) → qdk_chemistry.data.OrbitalType

Convert string to orbital type enum.

Parameters:: orbital_string (str) – String representation of orbital type (e.g., “S”, “P”, “D”);
Returns:: Corresponding orbital type enum
Return type:: OrbitalType
Raises:: ValueError – If the string does not correspond to a valid orbital type

Examples

>>> orbital_type = BasisSet.string_to_orbital_type("P")
>>> print(orbital_type)  # OrbitalType.P

to_file(self: qdk_chemistry.data.BasisSet, filename: object, type: str) → None

Save basis set to file with specified format.

Generic method to save basis set data to a file. The format is determined by the ‘type’ parameter.

Parameters:

filename (str | pathlib.Path) – Path to the file to write. Must have ‘.basis_set’ before the file extension (e.g., sto-3g.basis_set.json, cc-pvdz.basis_set.h5);
type (str) – File format type (“json” or “hdf5”);

Raises:

RuntimeError – If the basis set data is invalid, unsupported type, or file cannot be opened/written

Examples

>>> basis_set.to_file("sto-3g.basis_set.json", "json")
>>> basis_set.to_file("cc-pvdz.basis_set.h5", "hdf5")
>>> from pathlib import Path
>>> basis_set.to_file(Path("sto-3g.basis_set.json"), "json")

to_hdf5_file(self: qdk_chemistry.data.BasisSet, filename: object) → None

Save basis set to HDF5 file (with validation).

Writes all basis set data to an HDF5 file, preserving numerical precision. HDF5 format is efficient for large datasets and supports hierarchical data structures, making it ideal for storing basis set information.

Parameters:

filename (str | pathlib.Path) – Path to the HDF5 file to write. Must have ‘.basis_set’ before the file extension (e.g., sto-3g.basis_set.h5, cc-pvdz.basis_set.hdf5);

Raises:

ValueError – If filename doesn’t follow the required naming convention
RuntimeError – If the basis set data is invalid or the file cannot be opened/written

Examples

>>> basis_set.to_hdf5_file("sto-3g.basis_set.h5")
>>> basis_set.to_hdf5_file("cc-pvdz.basis_set.hdf5")
>>> from pathlib import Path
>>> basis_set.to_hdf5_file(Path("sto-3g.basis_set.h5"))

to_json(self: qdk_chemistry.data.BasisSet) → str

Convert basis set to JSON string.

Serializes all basis set information to a JSON string format. JSON is human-readable and suitable for debugging or data exchange.

Returns:: JSON string representation of the basis set data
Return type:: str
Raises:: RuntimeError – If the basis set data is invalid

Examples

>>> json_str = basis_set.to_json()
>>> print(json_str)  # Pretty-printed JSON

to_json_file(self: qdk_chemistry.data.BasisSet, filename: object) → None

Save basis set to JSON file (with validation).

Writes all basis set data to a JSON file with pretty formatting. The file will be created or overwritten if it already exists.

Parameters:

filename (str) – Path to the JSON file to write. Must have ‘.basis_set’ before the file extension (e.g., sto-3g.basis_set.json, cc-pvdz.basis_set.json);

Raises:

ValueError – If filename doesn’t follow the required naming convention
RuntimeError – If the basis set data is invalid or the file cannot be opened/written

Examples

>>> basis_set.to_json_file("sto-3g.basis_set.json")
>>> basis_set.to_json_file("my_basis.basis_set.json")

qdk_chemistry.migrate._orbitals.from_json_doc(doc)[source]

Normalize a parsed legacy orbitals JSON object into the internal old-doc.

Return type:: dict
Parameters:: doc (dict)

qdk_chemistry.migrate._orbitals.from_hdf5_group(group)[source]

Normalize a legacy orbitals HDF5 group into the internal old-doc.

Return type:: dict
Parameters:: group (h5py.Group)

qdk_chemistry.migrate._orbitals.to_new_json(old)[source]

Build the migrated orbitals JSON object from a normalized old-doc.

Return type:: dict
Parameters:: old (dict)