Basis Pointers¶

Basis pointer files (formerly called bfinfo files) provide the mapping between atomic orbitals and the radial basis functions stored in the numerical basis files. They specify how to construct atomic orbitals from radial shells and angular momentum functions, enabling CHAMP to build molecular orbitals from the atomic basis.

Overview¶

The basis pointer file acts as an instruction manual for assembling atomic orbitals:

• Maps radial shells to angular momentum components
• Defines the number and type of atomic orbitals per atom
• Links atomic orbitals to columns in the radial grid files
• Organizes basis functions by angular momentum quantum numbers

Key Concepts¶

• Atomic orbital (AO): A single-atom basis function with specific angular character
• Radial shell: A radial basis function from the .basis file
• Angular momentum index: Specifies real solid harmonics \(S_l^m\)
• Column mapping: Links AOs to specific columns in the radial basis file

File Format¶

Basis pointer files are stored in the pool/ directory and are automatically generated by the trex2champ converter.

File Structure¶

# Format of the new basis information file champ_v3
# num_ao_per_center, n(s), n(p), n(d), n(f), n(g)
# Index of Slm (Range 1 to 35)
# Index of column from numerical basis file
qmc_bf_info 1
54 4 4 3 2 0
1 1 1 1 2 3 4 2 3 4 2 3 4 2 3 4 5 6 7 8 9 10 5 6 7 8 9 10 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 11 12 13 14 15 16 17 18 19 20
1 2 3 4 5 5 5 6 6 6 7 7 7 8 8 8 9 9 9 9 9 9 10 10 10 10 10 10 11 11 11 11 11 11 12 12 12 12 12 12 12 12 12 12 13 13 13 13 13 13 13 13 13 13
35 4 3 2 1 0
1 1 1 1 2 3 4 2 3 4 2 3 4 5 6 7 8 9 10 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
1 2 3 4 5 5 5 6 6 6 7 7 7 8 8 8 8 8 8 9 9 9 9 9 9 10 10 10 10 10 10 10 10 10 10
end

Format Specification¶

Header line: Format identifier

qmc_bf_info 1

For each unique atom type: Three consecutive lines

Line 1: Angular momentum composition

54 4 4 3 2 0

• num_ao_per_center = 54: Total number of atomic orbitals for this atom
• n(s) = 4: Number of s-type radial shells (l=0)
• n(p) = 4: Number of p-type radial shells (l=1)
• n(d) = 3: Number of d-type radial shells (l=2)
• n(f) = 2: Number of f-type radial shells (l=3)
• n(g) = 0: Number of g-type radial shells (l=4)

Total AOs = n(s)×1 + n(p)×3 + n(d)×6 + n(f)×10 + n(g)×15 = 4×1 + 4×3 + 3×6 + 2×10 + 0×15 = 54

Line 2: Angular momentum indices

1 1 1 1 2 3 4 2 3 4 2 3 4 2 3 4 5 6 7 8 9 10 5 6 7 8 9 10 ...

The AOs can be expressed using real solid harmonics or polynomials in Cartesian coordinates. In the case of real solid harmonics, the AOs are ordered as (\(0, 1, -1, 2, -2, \dots\)). In the case of polynomials, the canonical (or alphabetical) ordering is used:

The sequence maps each AO to its angular component.

Line 3: Radial shell column indices

1 2 3 4 5 5 5 6 6 6 7 7 7 8 8 8 9 9 9 9 9 9 10 10 10 10 10 10 ...

Each number specifies which column (radial shell) from the .basis file to use for the corresponding AO:

• Column indices start at 1 (after the radius column)
• Multiple AOs can share the same radial shell (different angular components)
• The length of this line equals num_ao_per_center

Final line:

end

Examples¶

Example 1: Hydrogen Atom (Simple)¶

Basis pointer file (basis_pointers):

qmc_bf_info 1
5 2 1 0 0 0
1 1 2 3 4
1 2 3 3 3
end

Explanation:

• Line 1: 5 2 1 0 0 0
• 5 total AOs
• 2 s-type shells (1s, 2s)
• 1 p-type shell (2p)

• No d, f, or g shells

• Line 2: 1 1 2 3 4

• AOs 1-2: s-type (index 1)
• AO 3: px (index 2)
• AO 4: py (index 3)

• AO 5: pz (index 4)

• Line 3: 1 2 3 3 3

• AO 1: uses radial shell 1 (1s)
• AO 2: uses radial shell 2 (2s)
• AO 3: uses radial shell 3 (2p with different angular parts)

Example 2: Carbon Atom (BFD-Da Basis)¶

Basis pointer file:

qmc_bf_info 1 
18 3 3 1 0 0 
1 1 1 2 3 4 2 3 4 2 3 4 5 6 7 8 9 10 
1 2 3 4 4 4 5 5 5 6 6 6 7 7 7 7 7 7
end

Explanation:

• 18 atomic orbitals total
• 3 s-shells: 1s, 2s and 3s
• 3 p-shells: 2p, 3p and 4p (or polarization p)
• 1 d-shell: 3d (polarization)

Angular momentum breakdown:

• 3 s-orbitals (indices 1)
• 6 p-orbitals (indices 2, 3, 4)
• 5 d-orbitals (indices 5, 6, 7, 8, 9)

Radial shell mapping:

• Columns 1-3: s-type radials
• Columns 4-6: p-type radials
• Column 7: d-type radials

Example 3: Water Molecule¶

Geometry: O, H, H (two unique atom types)

Basis pointer file:

qmc_bf_info 1 
14 2 2 1 0 0 
1 1 2 3 4 2 3 4 5 6 7 8 9 10 
1 2 3 3 3 4 4 4 5 5 5 5 5 5 
5 2 1 0 0 0 
1 1 2 3 4 
1 2 3 3 3
end

Explanation:

First atom type (Oxygen):

• 14 AOs: 2 s-shells + 2 p-shells + 1 d-shell
• s-orbitals use radial columns 1, 2
• p-orbitals use radial columns 3, 4
• d-orbitals use radial column 5

Second atom type (Hydrogen):

• 5 AOs: 2 s-shells + 1 p-shell
• s-orbitals use radial columns 1, 2
• p-orbitals use radial column 3

Example 4: Heavy Element with f-functions¶

Transition metal with extended basis:

qmc_bf_info 1
35 4 3 2 1 0 
1 1 1 1 2 3 4 2 3 4 2 3 4 5 6 7 8 9 10 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 
1 2 3 4 5 5 5 6 6 6 7 7 7 8 8 8 8 8 8 9 9 9 9 9 9 10 10 10 10 10 10 10 10 10 10 
end

Explanation:

• 35 total AOs
• 4 s-shells, 3 p-shells, 2 d-shells, 1 f-shell
• f-orbitals use indices 10-20
• Radial columns 1-10 used for all shells

Angular Momentum Indexing¶

Cartesian Gaussian Polynomials¶

CHAMP uses Cartesian Gaussian polynomials with canonical (alphabetical) ordering:

s-orbitals (\(l=0\)): - Index 1: \(1\) (s)

p-orbitals (\(l=1\)): - Indices 2-4: \(x, y, z\) (px, py, pz)

d-orbitals (\(l=2\)): - Indices 5-10: \(x^2, xy, xz, y^2, yz, z^2\) (dxx, dxy, dxz, dyy, dyz, dzz)

f-orbitals (\(l=3\)): - Indices 11-20: \(x^3, x^2y, x^2z, xy^2, xyz, xz^2, y^3, y^2z, yz^2, z^3\)

g-orbitals (\(l=4\)): - Indices 21-35: 15 functions (\(x^4\) to \(z^4\))

Counting Atomic Orbitals¶

Total AOs per atom using Cartesian components:

where \(n(l)\) is the number of radial shells for angular momentum \(l\) and the term \(\frac{(l+1)(l+2)}{2}\) represents the number of Cartesian components (\(N_{cart}\)).

Loading Basis Pointers in CHAMP¶

The basis pointer file is loaded automatically when you specify the basis set:

%module general
    title  'VMC calculation'
    pool   './pool/'
    basis  'BFD-T'
%endmodule

load trexio   $pool/molecule.hdf5

CHAMP looks for basis_pointers file in the pool/ directory.

Explicit Loading¶

You can also load the file explicitly:

load basis_num_info  $pool/basis_pointers

Generating Basis Pointer Files¶

Automatic Generation¶

The trex2champ converter creates basis pointer files automatically:

#!/bin/bash
python trex2champ.py \
            --trex molecule.hdf5 \
            --basis_prefix "cc-VDZ" \
            --geom \
            --basis

This generates: - basis_pointers file in correct format - Consistent with basis set files and molecular orbitals - Properly ordered for all atom types

Verification¶

Check that the basis pointer file:

1. Matches atom types: One set of 3 lines per unique atom
2. Consistent AO counts: Sum of angular components equals total AOs
3. Valid angular indices: All indices in range 1-35
4. Valid column indices: Don't exceed number of radial shells in .basis file

Best Practices¶

File Organization¶

• Keep basis_pointers in the pool/ directory
• Use trex2champ for cross checking.

Verification Checklist¶

• Total AO count matches angular momentum breakdown
• Column indices are within range for basis files
• Angular momentum indices are valid (1-35)
• Number of atom type entries matches geometry
• Atom type ordering matches geometry file

Debugging Strategy¶

1. Check basis pointer format line by line
2. Verify against basis set file structure
3. Count AOs manually and compare
4. Test with simple systems first
5. Use trex2champ output as reference

Related Topics¶

• Basis Sets - Radial grid files that pointers reference
• Molecular Orbitals - Built from atomic orbitals
• TREXIO Files - Source of basis set information
• Preparation Workflow - Complete input preparation