iodata.basis module¶

Utility functions for working with basis sets.

Notes

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

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

Bases: object

A complete molecular orbital or density basis set.

__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_segmented()[source]¶: Unroll generalized contractions.

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 in a molecular basis representing (generalized) contractions.

__init__(icenter, angmoms, kinds, exponents, coeffs)¶: Method generated by attrs for class Shell.

angmoms: list[int]¶: An integer array of angular momentum quantum numbers, non-negative, with shape (ncon,).

coeffs: ndarray[Any, dtype[float]]¶: The array containing the coefficients of the normalized primitives in each contraction; shape = (nprim, ncon). These coefficients assume that the primitives are L2 (orbitals) or L1 (densities) normalized, but contractions are not necessarily normalized. (This depends on the code which generated the contractions.)

exponents: ndarray[Any, dtype[float]]¶: The array containing the exponents of the primitives, with shape (nprim,).

icenter: int¶: An integer index specifying the row in the atcoords array of IOData object.

kinds: list[str]¶: List 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 contractions. This is usually 1; e.g., it would be 2 for an SP shell.

property nprim: int¶: Number of primitives, also known as the contraction length.

angmom_its(angmom)[source]¶

Convert an angular momentum from integer to string representation.

Parameters:

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

Return type:

Union[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 (Union[str, list[str]]) – Character representation of angular momentum, (s, p, d, …)

Return type:

Union[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.

convert_convention_shell(conv1, conv2, reverse=False)[source]¶

Return a permutation vector and sign changes to convert from 1 to 2.

The transformation from convention 1 to convention 2 can be done applying the results of this function as follows:

vector2 = vector1[permutation]*signs

When using the option reverse=True, one can use the results to convert in the opposite sense:

vector1 = vector2[permutation]*signs

Parameters:

conv1 (list[str]) – Two lists, with the same strings (in different order), where each string may be prefixed with a ‘-‘.
conv2 (list[str]) – Two lists, with the same strings (in different order), where each string may be prefixed with a ‘-‘.
reverse – When, true the conversion from 2 to 1 is returned.

Return type:

tuple[ndarray[Any, dtype[int]], ndarray[Any, dtype[int]]]

Returns:

permutation – An integer array that permutes basis function from 1 to 2.
signs – Sign changes when going from 1 to 2, must be applied after permutation

convert_conventions(molbasis, new_conventions, reverse=False)[source]¶

Return a permutation vector and sign changes to convert from 1 to 2.

The transformation from molbasis.convention to the new convention can be done applying the results of this function as follows:

vector2 = vector1[permutation]*signs

When using the option reverse=True, one can use the results to convert in the opposite sense:

vector1 = vector2[permutation]*signs

Parameters:

molbasis (MolecularBasis) – The description of a molecular basis set.
new_conventions (dict[str, list[str]]) – The new conventions for ordering and signs, to which data for the orbital basis needs to be converted.
reverse – When, true the conversion from 2 to 1 is returned.

Return type:

tuple[ndarray[Any, dtype[int]], ndarray[Any, dtype[int]]]

Returns:

permutation – An integer array that permutes basis function from 1 to 2.
signs – Sign changes when going from 1 to 2, must be applied after permutation

get_default_conventions()[source]¶

Produce conventions dictionaries compatible with HORTON2 and CCA.

Do not change this! Both conventions are also used by several file formats from other QC codes.

Common Component Architecture (CCA) conventions are defined in appendix B of the following article:

Kenny, J. P.; Janssen, C. L.; Valeev, E. F.; Windus, T. L. Components for Integral Evaluation in Quantum Chemistry: Components for Integral Evaluation in Quantum Chemistry. J. Comput. Chem. 2008, 29 (4), 562-577. https://doi.org/10.1002/jcc.20815.

The ordering of the spherical harmonics within one shell is rather vague in appendix B and a more precise description is given on the LibInt Wiki:

https://github.com/evaleev/libint/wiki/using-modern-CPlusPlus-API

Return type:

tuple[dict, dict]

Returns:

horton2_conventions – A conventions dictionary for HORTON2, of which parts are used by various file formats.
cca_conventions – A conventions dictionary compatible with the Common Component Architecture (CCA).

iter_cart_alphabet(n)[source]¶

Loop over powers of Cartesian basis functions in alphabetical order.

See https://theochem.github.io/horton/2.1.1/tech_ref_gaussian_basis.html for details.

Parameters:: n (int) – The angular momentum, i.e. sum of Cartesian powers in this case.
Return type:: ndarray[Any, dtype[int]]