GBasis Tutorial - Basis Sets

In gbasis, a basis is defined as a list of GeneralizedContractionShell objects, each one representing a linear combination of primitives. Each GeneralizedContractionShell instances contains information about the angular momentum and center of the shell as well as the exponents and the contraction coefficients of the primitives and their normalization coefficients.

This notebook showcases the different ways to define a basis set for a molecule using gabsis.

1. Building Basis Sets from Basis Set File Formats

Basis set information is typically accessible in text format, such as those provided by the the Basis Set Exchange. gbasis supports two of the most popular formats: Gaussian94 (.gbs) and NWChem (.nw). The following examples show how to load a basis set from these files, and how to build a basis set instance from them.

1.1. Loading Gaussian94 Basis Set File Formats: parse_gbs

from gbasis.parsers import parse_gbs

# load hydrogen atom def2-SVP basis set information with the Gaussian94 format
gbs_basis_dict = parse_gbs("hydrogen_def2-svp.1.gbs")

# basis set information is stored as
# {'Atom Symbol': [(Angular Momentum, [Exponents], [Coefficients]), ...]}
print("def2-SVP Basis Set Loaded from Gaussian94 Format:")
for atom in gbs_basis_dict:
    print(f"Atom: {atom}")
    print(f"   Number of shells: {len(gbs_basis_dict[atom])}")
    for i, shell in enumerate(gbs_basis_dict[atom]):
        print(f"   Shell {i} has angular momentum {shell[0]}")
        print(f"   Shell {i} has exponents {shell[1]}")
        print(f"   Shell {i} has coefficients {shell[2].flatten()}")

def2-SVP Basis Set Loaded from Gaussian94 Format:
Atom: H
   Number of shells: 3
   Shell 0 has angular momentum 0
   Shell 0 has exponents [13.010701    1.9622572   0.44453796]
   Shell 0 has coefficients [0.01968216 0.13796524 0.47831935]
   Shell 1 has angular momentum 0
   Shell 1 has exponents [0.12194962]
   Shell 1 has coefficients [1.]
   Shell 2 has angular momentum 1
   Shell 2 has exponents [0.8]
   Shell 2 has coefficients [1.]

1.2. Loading NWChem Basis Set File Formats: parse_nwchem

Checking that the basis set information loaded from Gaussian and NWChem are the same.

import numpy as np
from gbasis.parsers import parse_nwchem

print("def2-SVP Basis Set Loaded from NwChem Format:")
nw_basis_dict = parse_nwchem("hydrogen_def2-svp.1.nw")

print("\nChecking that the Gaussian94 and NWChem loaded basis sets are the same:")
for atom, value in gbs_basis_dict.items():
    print(f"Atom {atom} exist in NWChem basis: {atom in nw_basis_dict}")
    print(f"Are the number of shells the same? {len(value) == len(nw_basis_dict[atom])}")

    # check that the angular momentum, exponents, and coefficients are the same for each shell
    contractions_pair = enumerate(zip(value, nw_basis_dict[atom]))
    for i, (gb_shell, nw_shell) in contractions_pair:
        print(f"Shell {i} has the same angular momentum: {gb_shell[0] == nw_shell[0]}")
        print(f"Shell {i} has the same exponents: {np.allclose(gb_shell[1], nw_shell[1])}")
        print(f"Shell {i} has the same coefficients: {np.allclose(gb_shell[2], nw_shell[2])}")
        print("")

def2-SVP Basis Set Loaded from NwChem Format:

Checking that the Gaussian94 and NWChem loaded basis sets are the same:
Atom H exist in NWChem basis: True
Are the number of shells the same? True
Shell 0 has the same angular momentum: True
Shell 0 has the same exponents: True
Shell 0 has the same coefficients: True

Shell 1 has the same angular momentum: True
Shell 1 has the same exponents: True
Shell 1 has the same coefficients: True

Shell 2 has the same angular momentum: True
Shell 2 has the same exponents: True
Shell 2 has the same coefficients: True

1.3. Making Contraction Shells: make_contractions

Once the data for a basis set are loaded as a dictionary, the make_contractions function is used to build the basis set given a list of atoms, their atomic coordinates, and coord_types. The latter specifies the coordinate system for building the contraction shells. Setting the coord_types='cartesian' or coord_types='c' uses a Cartesian coordinate system, and setting coord_types='spherical' or coord_types='p' (for pure), the contraction shells are built in the spherical coordinate system.

The following example shows how to use this function to build a basis set for \(\mathrm{H}_{2}\) with different contraction shells.

Example: Cartesian Contraction Shells

Setting coord_types='cartesian' or coord_types='c' uses a Cartesian coordinate system for all contraction shells.

import numpy as np
from gbasis.parsers import make_contractions

# Define atomic symbols and coordinates
atoms = ["H", "H"]
atcoords = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 1.0]])

# Make contractions at def2-SVP basis set
gbs_basis = make_contractions(gbs_basis_dict, atoms, atcoords, coord_types="cartesian")

print("Number of contracted basis functions:", len(gbs_basis))  # 3 for each H atom
print(f"Types of contractions: {[i.coord_type for i in gbs_basis]}", end="\n\n")
print("Showing the first three contraction shells:\n")
for i, shell in enumerate(gbs_basis[:3]):
    print(f"Contraction shell #{i}")
    print(f"   Center: {shell.coord}")
    print(f"   Angular momentum: {shell.angmom}")
    print(f"   Primitive coefficients {shell.coeffs.T}")
    print(f"   Primitive exponents {shell.exps}")
    print(f"   Primitive normalization constant {shell.norm_cont}")

Number of contracted basis functions: 6
Types of contractions: ['cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian']

Showing the first three contraction shells:

Contraction shell #0
   Center: [0. 0. 0.]
   Angular momentum: 0
   Primitive coefficients [[0.01968216 0.13796524 0.47831935]]
   Primitive exponents [13.010701    1.9622572   0.44453796]
   Primitive normalization constant [[1.70131166]]
Contraction shell #1
   Center: [0. 0. 0.]
   Angular momentum: 0
   Primitive coefficients [[1.]]
   Primitive exponents [0.12194962]
   Primitive normalization constant [[1.]]
Contraction shell #2
   Center: [0. 0. 0.]
   Angular momentum: 1
   Primitive coefficients [[1.]]
   Primitive exponents [0.8]
   Primitive normalization constant [[1. 1. 1.]]

Example: Spherical Contraction Shells

Setting coord_types='spherical' or coord_types='p' (where "p" stands for pure) uses a Spherical coordinate system for all contraction shells.

# make contractions for the hydrogen def2-SVP basis set
gbs_basis = make_contractions(gbs_basis_dict, atoms, atcoords, coord_types="spherical")

print("Number of contracted basis functions:", len(gbs_basis))  # 3 for each H atom
print(f"Types of contractions: {[i.coord_type for i in gbs_basis]}", end="\n\n")
print("Showing the first three contraction shells:\n")
for i, shell in enumerate(gbs_basis[:3]):
    print(f"Contraction shell #{i}")
    print(f"   Center: {shell.coord}")
    print(f"   Angular momentum: {shell.angmom}")
    print(f"   Primitive coefficients {shell.coeffs.T}")
    print(f"   Primitive exponents {shell.exps}")
    print(f"   Primitive normalization constant {shell.norm_cont}")

Number of contracted basis functions: 6
Types of contractions: ['spherical', 'spherical', 'spherical', 'spherical', 'spherical', 'spherical']

Showing the first three contraction shells:

Contraction shell #0
   Center: [0. 0. 0.]
   Angular momentum: 0
   Primitive coefficients [[0.01968216 0.13796524 0.47831935]]
   Primitive exponents [13.010701    1.9622572   0.44453796]
   Primitive normalization constant [[1.70131166]]
Contraction shell #1
   Center: [0. 0. 0.]
   Angular momentum: 0
   Primitive coefficients [[1.]]
   Primitive exponents [0.12194962]
   Primitive normalization constant [[1.]]
Contraction shell #2
   Center: [0. 0. 0.]
   Angular momentum: 1
   Primitive coefficients [[1.]]
   Primitive exponents [0.8]
   Primitive normalization constant [[1. 1. 1.]]

Example: Mixed Contraction Shells

The coord_type can be specified as a list of strings, each representing the coord_type of a contraction shell, which allows mixed contraction shell types. Obviously, the length of this list must be equal to the number of contraction shells in the molecule.

The following example shows how to build mixed contraction shells for \(\mathrm{H}_{2}\) molecule. The first 3 contraction shells (corresponding to the first atom) are built in the Cartesian coordinate system, while the last 3 contraction shells (corresponding to the second atom) are built in the spherical coordinate system.

# list of coordinate types, one for each shell
coord_types = ["cartesian", "cartesian", "cartesian", "spherical", "spherical", "spherical"]

# make contractions for the hydrogen def2-SVP basis set
gbs_basis = make_contractions(gbs_basis_dict, atoms, atcoords, coord_types=coord_types)

print("Number of contracted basis functions:", len(gbs_basis))  # 3 for each H atom
print(f"Types of contractions: {[i.coord_type for i in gbs_basis]}", end="\n\n")

print(f"Number of Contracted Basis Functions: {len(gbs_basis)}\n")

print("Showing the first three contraction shells:\n")
for i, shell in enumerate(gbs_basis[:3]):
    print(f"Contraction Shell #{i}")
    print(f"   Center: {shell.coord}")
    print(f"   Angular momentum: {shell.angmom}")
    print(f"   Primitive coefficients {shell.coeffs.T}")
    print(f"   Primitive exponents {shell.exps}")
    print(f"   Primitive normalization constant {shell.norm_cont}\n")
    print(f"   Coordinate type: {shell.coord_type}")

Number of contracted basis functions: 6
Types of contractions: ['cartesian', 'cartesian', 'cartesian', 'spherical', 'spherical', 'spherical']

Number of Contracted Basis Functions: 6

Showing the first three contraction shells:

Contraction Shell #0
   Center: [0. 0. 0.]
   Angular momentum: 0
   Primitive coefficients [[0.01968216 0.13796524 0.47831935]]
   Primitive exponents [13.010701    1.9622572   0.44453796]
   Primitive normalization constant [[1.70131166]]

   Coordinate type: cartesian
Contraction Shell #1
   Center: [0. 0. 0.]
   Angular momentum: 0
   Primitive coefficients [[1.]]
   Primitive exponents [0.12194962]
   Primitive normalization constant [[1.]]

   Coordinate type: cartesian
Contraction Shell #2
   Center: [0. 0. 0.]
   Angular momentum: 1
   Primitive coefficients [[1.]]
   Primitive exponents [0.8]
   Primitive normalization constant [[1. 1. 1.]]

   Coordinate type: cartesian

2. Building Basis Sets from Quantum Chemistry Calculations

gbasis supports obtaining basis function information from quantum chemistry calculations by interfacing with iodata and pySCF.

2.1. Interfacing with IOData Library: from_iodata

IOData supports parsing various quantum chemistry file formats, like Gaussian formatted checkpoint files (.fchk), molden (.molden), and wave-function files (.wfn and .wfx), and provides a unified interface to access the data in these files through IOData object. This object is passed to from_iodata function to obtain the basis set information.

The following example loads basis functions from a FCHK file, but other formats supported by iodata can also be used.

from iodata import load_one
from gbasis.wrappers import from_iodata

# load basis functions from a fchk file of water at uwB97XD/def2-TZVPD level
iodata_mol = load_one("water.fchk")
iodata_basis = from_iodata(iodata_mol)

# print the basis set information
print(f"Number of Contracted Basis Functions: {len(iodata_basis)}")
print(f"Types of contractions: {[b.coord_type for b in iodata_basis]}", end="\n\n")
print("Showing the first three contraction shells:", end="\n\n")

for i, shell in enumerate(iodata_basis[:3]):
    print(f"Contraction Shell #{i}")
    print(f"   Center: {shell.coord}")
    print(f"   Angular momentum: {shell.angmom}")
    print(f"   Primitive coefficients: {shell.coeffs.T}")
    print(f"   Primitive exponents: {shell.exps}")
    print(f"   Primitive normalization constant: {shell.norm_cont}\n")

Number of Contracted Basis Functions: 24
Types of contractions: ['cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'spherical', 'spherical', 'spherical', 'spherical', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian']

Showing the first three contraction shells:

Contraction Shell #0
   Center: [ 0.01418428  0.01049743 -0.00741906]
   Angular momentum: 0
   Primitive coefficients: [[5.72273352e-04 4.43532335e-03 2.30201077e-02 9.28224907e-02
  2.93785000e-01 6.74016045e-01]]
   Primitive exponents: [27032.3826     4052.38714     922.327227    261.24071      85.3546414
    31.0350352]
   Primitive normalization constant: [[1.]]

Contraction Shell #1
   Center: [ 0.01418428  0.01049743 -0.00741906]
   Angular momentum: 0
   Primitive coefficients: [[0.63839937 0.39534587]]
   Primitive exponents: [12.2608607  4.9987076]
   Primitive normalization constant: [[1.]]

Contraction Shell #2
   Center: [ 0.01418428  0.01049743 -0.00741906]
   Angular momentum: 0
   Primitive coefficients: [[1.]]
   Primitive exponents: [1.17031082]
   Primitive normalization constant: [[1.]]

2.2. Interfacing with pySCF Library: from_pyscf

The from_pyscf function supports building basis functions directly from pyscf.gto.mole.Mole object. Setting cart=False when creating an instance of Mole, spherical coordinates are used.

from pyscf import gto
from gbasis.wrappers import from_pyscf

# build an STO-3G basis for water using PySCF
molecule = """
O 0 0 0;
H 0 1 0;
H 0 0 1
"""
pyscf_mol = gto.Mole(cart=True)
pyscf_mol.build(atom=molecule, basis="sto-3g")
pyscf_basis = from_pyscf(pyscf_mol)

print(f"Number of contracted basis functions: {len(pyscf_basis)}")
print(f"Types of contractions: {[shell.coord_type for shell in pyscf_basis]}", end="\n\n")
print("Showing the first three contraction shells:", end="\n\n")

for i, shell in enumerate(pyscf_basis[:3]):
    print(f"Contraction Shell #{i}")
    print(f"   Center: {shell.coord}")
    print(f"   Angular momentum: {shell.angmom}")
    print(f"   Primitive coefficients {shell.coeffs.T}")
    print(f"   Primitive exponents {shell.exps}")
    print(f"   Primitive normalization constant {shell.norm_cont}\n")

Number of contracted basis functions: 5
Types of contractions: ['cartesian', 'cartesian', 'cartesian', 'cartesian', 'cartesian']

Showing the first three contraction shells:

Contraction Shell #0
   Center: [0. 0. 0.]
   Angular momentum: 0
   Primitive coefficients [[0.15432897 0.53532814 0.44463454]]
   Primitive exponents [130.70932    23.808861    6.4436083]
   Primitive normalization constant [[0.99999999]]

Contraction Shell #1
   Center: [0. 0. 0.]
   Angular momentum: 0
   Primitive coefficients [[-0.09996723  0.39951283  0.70011547]]
   Primitive exponents [5.0331513 1.1695961 0.380389 ]
   Primitive normalization constant [[0.99999999]]

Contraction Shell #2
   Center: [0. 0. 0.]
   Angular momentum: 1
   Primitive coefficients [[0.15591627 0.60768372 0.39195739]]
   Primitive exponents [5.0331513 1.1695961 0.380389 ]
   Primitive normalization constant [[0.99999999 0.99999999 0.99999999]]