iodata.basis module

Utility functions for working with basis sets.

Notes

Basis set conventions and terminology are documented in Basis set conventions.

class BasisFunction(index, ishell, icon, icenter, angmom, kind, label, sign)[source]

Bases: object

The identity of a single basis function within a MolecularBasis.

__init__(index, ishell, icon, icenter, angmom, kind, label, sign)

Method generated by attrs for class BasisFunction.

angmom: int

The angular momentum quantum number.

icenter: int

The row in the atcoords array of the atom this function is centered on.

icon: int

The index of the generalized contraction within that shell.

index: int

The index of the basis function in the full basis set.

ishell: int

The index of the shell in MolecularBasis.shells holding this function.

kind: str

'c' for Cartesian or 'p' for pure.

label: str

The basis function label from MolecularBasis.conventions, without its sign.

A convention may flip the sign of a function by prefixing its label with a minus, e.g. '-c3'. That prefix is stripped here and reported through sign instead, so the label is always the plain name of the function.

sign: int

+1, or -1 when the convention flips the sign of this function.

class MolecularBasis(shells, conventions, primitive_normalization)[source]

Bases: object

A complete molecular orbital or density basis set, a collection of contracted shells.

__init__(shells, conventions, primitive_normalization)

Method generated by attrs for class MolecularBasis.

conventions: dict[tuple[int, str], list[str]]

A dictionary specifying the ordered basis functions for a given angular momentum and kind. The key is a tuple of angular momentum integer and kind character (‘c’ for Cartesian and ‘p’ for pure/spherical) and the value is a list of basis function strings. For example,

{
    ### Conventions for Cartesian functions
    # E.g., alphabetically ordered Cartesian functions.
    (0, 'c'): ['1'],
    (1, 'c'): ['x', 'y', 'z'],
    (2, 'c'): ['xx', 'xy', 'xz', 'yy', 'yz', 'zz'],
    ### Conventions for pure functions.
    # The notation is referring to real solid spherical harmonics.
    # See https://en.wikipedia.org/wiki/Solid_harmonics#Real_form
    # 'c{m}' = solid harmonic containing cos(m phi)
    # 's{m}' = solid harmonic containing sin(m phi)
    # where m is the magnetic quantum number and phi is the
    # azimuthal angle.
    # For example, wikipedia-ordered real spherical harmonics,
    # see https://en.wikipedia.org/wiki/Spherical_harmonics#Real_form
    (2, 'p'): ['s2', 's1', 'c0', 'c1', 'c2'],
    # Different quantum-chemistry codes may use incompatible
    # orderings and sign conventions. E.g. Molden files written
    # by ORCA use the following convention for pure f functions:
    (3, 'p'): ['c0', 'c1', 's1', 'c2', 's2', '-c3', '-s3'],
    # Note that the minus sign in the last two basis functions
    # denotes that the signs of these harmonics have been changed.
}

The basis function strings in the conventions dictionary are documented in Basis set conventions.

get_basis_functions()[source]

Describe all the basis functions, in the order used by this basis set.

This takes one pass over the shells. The function at a given index of the basis set is get_basis_functions()[index], so keep the list when it is needed often.

Return type:

list[BasisFunction]

Returns:

list[BasisFunction] – One item per basis function, with index equal to the position in the list.

index_basis_functions(keys=('icenter', 'angmom', 'label'))[source]

Group the indices of the basis functions by the values of some of their attributes.

This takes one pass over the basis set. After that, finding a basis function is a look-up in the dictionary, instead of a search.

Parameters:

keys (tuple[str, ...]) – The names of the attributes of BasisFunction that make up the keys of the dictionary. Different use cases group the basis functions differently. The default separates the functions by the atom they belong to, by their angular momentum and by their label. The angular momentum is part of it, because labels such as 'c0' are not unique to one angular momentum.

Return type:

dict[tuple, list[int]]

Returns:

dict[tuple, list[int]] – For each combination of values, a tuple in the order of keys, the indices of the basis functions with these values, in the order of the basis set. For example, with the default keys, index[icenter, angmom, label][0] is the index of the first function with that label on that atom.

Raises:

ValueError – If one of the keys is not the name of an attribute of BasisFunction.

property nbasis: int

Number of basis functions.

primitive_normalization: str

The normalization convention of primitives, which can be ‘L2’ (orbitals) or ‘L1’ (densities) normalized.

shells: list[Shell]

A list of objects of type Shell which can support generalized contractions.

class Shell(icenter, angmoms, kinds, exponents, coeffs)[source]

Bases: object

A shell of (generalized) contracted Gaussian basis functions with common primitive exponents.

The basis functions in a Shell instance are centered on a single atomic nucleus. However, an atom can be associated with multiple Shell instances.

Notes

Basis set conventions and terminology are documented in Basis set conventions.

__init__(icenter, angmoms, kinds, exponents, coeffs)

Method generated by attrs for class Shell.

angmoms: NDArray[int]

An integer array of angular momentum quantum numbers, non-negative, with shape (ncon,).

In the case of ordinary (not generalized) contractions, this array contains one element.

For generalized contractions, this array contains multiple elements. The same angular momentum may or may not appear multiple times.

The most common form of generalized contraction is the SP shell, e.g. as found in the Pople basis sets (6-31G and others), in which case this array is [0, 1].

Other forms of generalized contractions exist, but only some quantum chemistry codes have efficient implementations for them. For example, the ANO-RCC basis for carbon has 8 S-type basis functions, all different linear combinations of the same 14 Gaussian primitives. In this case, this array is [0, 0, 0, 0, 0, 0, 0, 0].

coeffs: NDArray[float]

The array containing the coefficients of the normalized primitives in each contraction; shape = (nexp, ncon). Each column represents one linear combination of basis functions. These coefficients assume that the primitives are L2 (orbitals) or L1 (densities) normalized, but contractions are not necessarily normalized. (This depends on the code that generated the contractions.)

exponents: NDArray[float]

The array containing the exponents of the primitives, with shape (nexp,).

icenter: int

An integer index specifying the row in the atcoords array of IOData object.

kinds: NDArray[str]

Array of strings describing the kind of contractions: 'c' for Cartesian and 'p' for pure. Pure functions are only allowed for angmom > 1. The length equals the number of contractions (ncon = len(kinds)).

property nbasis: int

Number of basis functions (e.g. 3 for a P shell and 4 for an SP shell).

property ncon: int

Number of generalized contractions.

This is the number of different linear combinations of Gaussian basis functions with the same set of exponents.

This is usually 1; e.g., it would be 2 for an SP shell.

property nexp: int

Number of exponents in the contracted shell, also known as the contraction length.

angmom_its(angmom)[source]

Convert an angular momentum from integer to string representation.

Parameters:

angmom (int | list[int]) – The integer representation of the angular momentum.

Return type:

str | list[str]

Returns:

The string representation of the angular momentum. If a list of integer angmom is given, a list of str is returned.

angmom_sti(char)[source]

Convert an angular momentum from string to integer format.

Parameters:

char (str | list[str]) – Character representation of angular momentum, (s, p, d, …)

Return type:

int | list[int]

Returns:

An integer representation of the angular momentum. If a list of str char is given, a list of integers in returned.