Skip to content

Atom-centered bases

An atom-centered basis specifies the functions associated with each atom and the ordering of their spherical components. The same basis definitions are used for atomic orbitals, auxiliary density expansions, and projector functions; their roles are assigned by the sample or calculation.

The base types describe shell structure. Numerical and Gaussian forms add radial functions so the basis can also be evaluated and integrated. Physical calculations use these complete basis definitions for overlaps, density projection, and related operations.

Shell structure

An atomic basis describes one element; a basis set collects elements in ascending atomic-number order.

AtomicBasis dataclass 

AtomicBasis(atomic_number: int, angmoms: ArrayLike, name: str | None = None)

Shell structure for one element.

Repeated angular quantum numbers represent distinct radial shells. Shells use ascending l; repeated l values retain their input order. Each shell contains magnetic components m = -l, ..., +l in normalized Wikipedia real spherical harmonic convention.

Parameters:

  • atomic_number (int) –

    Atomic number of the element using this basis.

  • angmoms (ArrayLike) –

    Angular quantum number l of each shell, stored as an int32 array with shape (n_shells,).

  • name (str | None, default: None ) –

    Optional source-level basis name.

n_orb property 

n_orb: int

Number of basis functions on one atomic center.

BasisSet dataclass 

BasisSet(atomic_bases: Sequence[AtomicBasisT])

Atomic bases in canonical ascending atomic-number order.

The base class stores the shell structure needed to interpret orbital axes. Numerical and Gaussian subclasses add complete radial functions. The position of an atomic basis in atomic_bases is the canonical species index for this basis set.

Parameters:

  • atomic_bases (Sequence[AtomicBasisT]) –

    Atomic bases with unique atomic numbers. Input order is ignored.

atomic_basis 

atomic_basis(atomic_number: int) -> AtomicBasisT

Return the basis for one atomic number.

atom_orb_counts 

atom_orb_counts(atomic_numbers: ArrayLike) -> NDArray[int32]

Return orbital counts in atom order.

orb_offsets 

orb_offsets(atomic_numbers: ArrayLike) -> NDArray[int64]

Return atom boundaries in the global orbital order.

n_orb 

n_orb(atomic_numbers: ArrayLike) -> int

Return the total orbital count for an atomic-number sequence.

merge_basis_sets 

merge_basis_sets(basis_sets: Iterable[BasisSet]) -> BasisSet

Merge compatible element subsets of one concrete basis-set type.

Shared atomic numbers must have equal complete atomic bases. The returned atomic bases are ordered by atomic number independently of input order.

Numerical radial functions

Spline and uniform numerical bases differ in how radial samples are stored and interpolated. Each atomic form has a corresponding basis-set type.

SplineNumericalAtomicBasis dataclass 

SplineNumericalAtomicBasis(
    atomic_number: int,
    angmoms: ArrayLike,
    radial_grid: ArrayLike,
    radial_values: ArrayLike,
    name: str | None = None,
)

Bases: AtomicBasis

Spline-interpolated numerical radial functions for one element.

All shells share radial_grid. radial_values[s] is the bare radial function for angmoms[s] in Å\(^{-3/2}\). r_max is the final radial-grid knot and therefore the largest shell cutoff. cutoff_index[s] is derived as the first knot of that shell's exact zero tail.

Parameters:

  • atomic_number (int) –

    Atomic number of the element using this basis.

  • angmoms (ArrayLike) –

    Angular quantum number of each shell.

  • radial_grid (ArrayLike) –

    Strictly increasing radial knots in Å, beginning at zero. At least four knots are required.

  • radial_values (ArrayLike) –

    Bare radial samples with shape [n_shells, n_grid].

  • name (str | None, default: None ) –

    Optional source-level basis name.

n_orb property 

n_orb: int

Number of basis functions on one atomic center.

r_max property 

r_max: float

Largest shell cutoff in Å.

evaluate_radial 

evaluate_radial(radius: ArrayLike) -> NDArray[float64]

Evaluate every radial shell at radii in Å.

Parameters:

  • radius (ArrayLike) –

    Non-negative radii with any shape.

Returns:

  • NDArray[float64] –

    Radial values with shape (n_shells, *radius.shape).

evaluate 

evaluate(relative_coordinates: ArrayLike) -> NDArray[float64]

Evaluate all three-dimensional basis functions about one center.

Parameters:

  • relative_coordinates (ArrayLike) –

    Cartesian coordinates relative to the center in Å, with shape (..., 3).

Returns:

  • NDArray[float64] –

    Values with shape (..., n_orb) in shell order and then

  • NDArray[float64] –

    m = -l, ..., l order within each shell.

SplineNumericalBasisSet dataclass 

SplineNumericalBasisSet(
    atomic_bases: Sequence[SplineNumericalAtomicBasis], name: str | None = None
)

Bases: BasisSet[SplineNumericalAtomicBasis]

Spline numerical atomic bases keyed by atomic number.

atomic_basis 

atomic_basis(atomic_number: int) -> AtomicBasisT

Return the basis for one atomic number.

atom_orb_counts 

atom_orb_counts(atomic_numbers: ArrayLike) -> NDArray[int32]

Return orbital counts in atom order.

orb_offsets 

orb_offsets(atomic_numbers: ArrayLike) -> NDArray[int64]

Return atom boundaries in the global orbital order.

n_orb 

n_orb(atomic_numbers: ArrayLike) -> int

Return the total orbital count for an atomic-number sequence.

UniformNumericalAtomicBasis dataclass 

UniformNumericalAtomicBasis(
    atomic_number: int,
    angmoms: ArrayLike,
    radial_spacing: float,
    radial_values: ArrayLike,
    name: str | None = None,
)

Bases: AtomicBasis

Numerical radial functions on a uniform grid beginning at the origin.

radial_values[:, i] samples all shells at i * radial_spacing. cutoff_index[s] is derived as the first knot of shell s's exact zero tail. One common zero knot may follow the largest shell cutoff to make the Simpson grid odd. The full radial grid and global spline coefficients are not stored.

Parameters:

  • atomic_number (int) –

    Atomic number of the element using this basis.

  • angmoms (ArrayLike) –

    Angular quantum number of each shell.

  • radial_spacing (float) –

    Positive spacing between radial knots in Å.

  • radial_values (ArrayLike) –

    Bare radial samples with shape [n_shells, n_grid].

  • name (str | None, default: None ) –

    Optional source-level basis name.

n_orb property 

n_orb: int

Number of basis functions on one atomic center.

n_grid_points property 

n_grid_points: int

Number of uniform radial knots.

r_max property 

r_max: float

Largest shell cutoff in Å.

cutoffs property 

cutoffs: NDArray[float64]

Exact shell cutoffs in Å.

evaluate_radial 

evaluate_radial(radius: ArrayLike) -> NDArray[float64]

Evaluate every radial shell at radii in Å.

Parameters:

  • radius (ArrayLike) –

    Non-negative radii with any shape.

Returns:

  • NDArray[float64] –

    Radial values with shape (n_shells, *radius.shape).

evaluate 

evaluate(relative_coordinates: ArrayLike) -> NDArray[float64]

Evaluate all three-dimensional basis functions about one center.

Parameters:

  • relative_coordinates (ArrayLike) –

    Cartesian coordinates relative to the center in Å, with shape (..., 3).

Returns:

  • NDArray[float64] –

    Values with shape (..., n_orb) in shell order and then

  • NDArray[float64] –

    m = -l, ..., l order within each shell.

UniformNumericalBasisSet dataclass 

UniformNumericalBasisSet(
    atomic_bases: Sequence[UniformNumericalAtomicBasis], name: str | None = None
)

Bases: BasisSet[UniformNumericalAtomicBasis]

Uniform numerical atomic bases sharing one radial spacing.

atomic_basis 

atomic_basis(atomic_number: int) -> AtomicBasisT

Return the basis for one atomic number.

atom_orb_counts 

atom_orb_counts(atomic_numbers: ArrayLike) -> NDArray[int32]

Return orbital counts in atom order.

orb_offsets 

orb_offsets(atomic_numbers: ArrayLike) -> NDArray[int64]

Return atom boundaries in the global orbital order.

n_orb 

n_orb(atomic_numbers: ArrayLike) -> int

Return the total orbital count for an atomic-number sequence.

Gaussian radial functions

Gaussian bases represent each radial shell as a contraction of primitive Gaussian functions.

GaussianAtomicBasis dataclass 

GaussianAtomicBasis(
    atomic_number: int,
    angmoms: ArrayLike,
    primitive_offsets: ArrayLike,
    primitive_exponents: ArrayLike,
    contraction_coefficients: ArrayLike,
    name: str | None = None,
)

Bases: AtomicBasis

Contracted Gaussian functions for one element.

Every shell contains one contracted radial function. General contractions are therefore expanded into repeated shells with the same angular momentum. Primitive exponents use Å\(^{-2}\) and coefficients multiply individually normalized primitive radial functions. The stored coefficients retain the actual scale of the contracted function.

Parameters:

  • atomic_number (int) –

    Atomic number of the element using this basis.

  • angmoms (ArrayLike) –

    Angular quantum number of each shell.

  • primitive_offsets (ArrayLike) –

    Boundaries of each shell's primitive data, with shape (n_shells + 1,).

  • primitive_exponents (ArrayLike) –

    Positive primitive exponents in Å\(^{-2}\).

  • contraction_coefficients (ArrayLike) –

    Dimensionless contraction coefficients.

  • name (str | None, default: None ) –

    Optional source-level basis name.

n_orb property 

n_orb: int

Number of basis functions on one atomic center.

evaluate 

evaluate(relative_coordinates: ArrayLike) -> NDArray[float64]

Evaluate all three-dimensional basis functions about one center.

Parameters:

  • relative_coordinates (ArrayLike) –

    Cartesian coordinates relative to the center in Å, with shape (..., 3).

Returns:

  • NDArray[float64] –

    Values with shape (..., n_orb) in shell order and then

  • NDArray[float64] –

    m = -l, ..., l order within each shell.

GaussianBasisSet dataclass 

GaussianBasisSet(atomic_bases: Sequence[GaussianAtomicBasis], name: str | None = None)

Bases: BasisSet[GaussianAtomicBasis]

Role-neutral Gaussian atomic bases keyed by atomic number.

atomic_basis 

atomic_basis(atomic_number: int) -> AtomicBasisT

Return the basis for one atomic number.

atom_orb_counts 

atom_orb_counts(atomic_numbers: ArrayLike) -> NDArray[int32]

Return orbital counts in atom order.

orb_offsets 

orb_offsets(atomic_numbers: ArrayLike) -> NDArray[int64]

Return atom boundaries in the global orbital order.

n_orb 

n_orb(atomic_numbers: ArrayLike) -> int

Return the total orbital count for an atomic-number sequence.

Evaluation and normalization

Basis evaluation places the functions on a finite geometry. Radial norm integrals and normalization operate on the radial shells.

evaluate_basis_for_geometry 

evaluate_basis_for_geometry(
    geometry: Geometry,
    basis_set: SplineNumericalBasisSet | UniformNumericalBasisSet | GaussianBasisSet,
    coordinates: ArrayLike,
) -> NDArray[float64]

Evaluate a basis set placed on a finite geometry at Cartesian points.

Parameters:

Returns:

  • NDArray[float64] –

    Values with shape (n_points, n_orb) in atom-major basis ordering.

radial_norm_integrals 

radial_norm_integrals(
    atomic_basis: SplineNumericalAtomicBasis | UniformNumericalAtomicBasis,
) -> NDArray[float64]

Integrate r^2 |R(r)|^2 for every radial shell.

Spline numerical bases use five-point Gauss–Legendre quadrature on each spline interval. Uniform numerical bases use composite Simpson quadrature on their stored samples.

normalize_radial_functions 

normalize_radial_functions(
    basis: SplineNumericalAtomicBasis,
) -> SplineNumericalAtomicBasis

normalize_radial_functions(
    basis: UniformNumericalAtomicBasis,
) -> UniformNumericalAtomicBasis

normalize_radial_functions(basis: SplineNumericalBasisSet) -> SplineNumericalBasisSet

normalize_radial_functions(basis: UniformNumericalBasisSet) -> UniformNumericalBasisSet

normalize_radial_functions(
    basis: SplineNumericalAtomicBasis
    | SplineNumericalBasisSet
    | UniformNumericalAtomicBasis
    | UniformNumericalBasisSet,
) -> (
    SplineNumericalAtomicBasis
    | SplineNumericalBasisSet
    | UniformNumericalAtomicBasis
    | UniformNumericalBasisSet
)

Return a new basis whose radial shells have unit radial norm.