calculateLCAOBasisSpilling(configuration, k_point_sampling=None, basis=None, bands_above_fermi_level=<class 'NL.ComputerScienceUtilities.NLFlag._NLFlag.All'>, processes_per_kpoint=None)

Method for calculating the spilling factors per band (and spin) for a given configuration with an attached plane wave calculator and a given LCAO basis.

param configuration:
 The configuration with an attached plane wave calculator.
type configuration:
param k_point_sampling:
 The k-point sampling to use in the sum over k. By default, the k-points of the ground state configuration are used. The eigensystem is solved again, if different k-points are requested.
Default: None.
type k_point_sampling:
 None | MonkhorstPackGrid
param basis:The LCAO basis to project onto. It must contain basis functions for the elements in the configuration. If it is set to None, the LCAO basis attached to the calculator of the configuration is used.
Default: None.
type basis:None | BasisSet
param bands_above_fermi_level:
 The number of bands above the Fermi level to include in the sum. By default all unoccupied bands present in the ground state calculation are used. The eigensystem is solved again, if more unoccupied bands are requested.
Default: All
type bands_above_fermi_level:
 All | int
param processes_per_kpoint:
 The number of processes used for one k-point.
Default: None.
type processes_per_kpoint:
 None | int | Automatic
returns:The spilling factors per band as a numpy array of floats. In the case of a spin-polarized calculation, the shape is (2, N), otherwise its shape is (1, N).

Usage Examples

Calculate the average spilling factor for a Medium and High silicon basis set.

# Set up lattice
lattice = FaceCenteredCubic(5.4306 * Angstrom)

# Define elements
elements = [Silicon, Silicon]

# Define coordinates
fractional_coordinates = [[ 0.  ,  0.  ,  0.  ],
                          [ 0.25,  0.25,  0.25]]

# Set up configuration
bulk_configuration = BulkConfiguration(

k_point_sampling = MonkhorstPackGrid(

numerical_accuracy_parameters = NumericalAccuracyParameters(

# PlaneWaveCalculator with a high wave function cutoff to get a complete plane wave basis.
calculator = PlaneWaveCalculator(


# For each band get the LCAO basis spilling factor for a Medium basis.
# Only include the occupied states.
spilling_per_band_medium = calculateLCAOBasisSpilling(

# Total averaged spilling.
spilling_medium = spilling_per_band_medium.sum() / spilling_per_band_medium.size

# For each band get the LCAO basis spilling factor for a High basis.
# Only include the occupied states.
spilling_per_band_high = calculateLCAOBasisSpilling(

# Total averaged spilling.
spilling_high = spilling_per_band_high.sum() / spilling_per_band_high.size

print('Spilling per band, Medium (%) : ', spilling_per_band_medium * 100)
print('Spilling per band, High   (%) : ', spilling_per_band_high * 100)
# Print the average spilling factors
print('Average spilling, Medium (%) : ', spilling_medium * 100)
print('Average spilling, High   (%) : ', spilling_high * 100)

The final output of the script is:

Spilling per band, Medium (%) :  [[ 0.07159806  0.04691684  0.04034596  0.04223707]]
Spilling per band, High   (%) :  [[ 0.03255014  0.01255693  0.02256928  0.0250443 ]]

Average spilling, Medium (%) :  0.0502744832443
Average spilling, High   (%) :  0.0231801630042

showing that the Medium basis set has a spilling factor of 0.050 % while the High basis has a smaller spilling of 0.023 %. The printed spillings per band show that the lowest band (first index) has the largest spilling factor for both the Medium and High basis sets.


Following [SPAS95], we define the spilling factor for band \(i\) as

\[S_i = \frac{1}{N_k} \sum_k^{N_k} w_k \langle \psi_i(k) | 1 - P(k) |\psi_i(k)\rangle,\]

where \(w_k\) is the weight of k-point \(k\) and the projection operator \(P\) is defined as

\[P(k) = \sum_{\mu\nu} |\phi_\mu(k)\rangle (O(k)^{-1})_{\mu\nu}\langle \phi_\nu(k)|\]

with \(|\phi_\mu(k)\rangle\) being the Fourier transform of the basis orbital \(\mu\) and \(O\) being the basis orbital overlap matrix defined as

\[O_{\mu\nu}(k)=\langle \phi_\mu(k)|\phi_\nu(k)\rangle.\]

The total spilling factor is given by the average over the considered bands, i.e.

\[S = \frac{1}{N_b}\sum_i^{N_b}S_i.\]

The function calculateLCAOBasisSpilling can be used to calculate the completeness of a a particular basis set. The smaller the spilling factor, the more complete is the basis set.

It also allows for a per band analysis since calculateLCAOBasisSpilling returns the spilling factor for each band. The number of unoccupied bands included in the calculation can be set in the function call as:

spilling_per_band_high = calculateLCAOBasisSpilling(

where five unoccupied bands above the Fermi level would be included.


[SPAS95]D. Sanchez-Portal, E. Artacho, and J. M. Soler. Projection of plane-wave calculations into atomic orbitals. Solid State Communications, 95(10):685 – 690, 1995. URL:, doi: