ElectronicInverseParticipationRatio¶

class ElectronicInverseParticipationRatio(configuration, kpoints=None, energy_zero_parameter=None)¶

Class for calculating the electronic inverse participation ratio.

Parameters:

configuration (BulkConfiguration | MoleculeConfiguration) – The configuration for which to calculate the electronic inverse participation ratio.
kpoints (sequence (size 3) of int | MonkhorstPackGrid | KpointDensity | RegularKpointGrid | sequence of sequence (size 3) of float) – The k-points on which to calculate the electronic inverse participation ratio.
Default: The Gamma point (0.0, 0.0, 0.0).
energy_zero_parameter (FermiLevel | AbsoluteEnergy) – Specifies the choice for the energy zero.
Default: FermiLevel

energies(spin=None)¶

Parameters:: spin (Spin.Up | Spin.Down | Spin.All) – The spin the energies should be returned for.
Default: Spin.All
Returns:: The energies for each orbital.
Return type:: PhysicalQuantity of type energy

energyZero()¶

Returns:: The energy reference in absolute energy.
Return type:: PhysicalQuantity of type energy.

fermiLevel(spin=None)¶

Parameters:: spin (Spin.Up | Spin.Down | Spin.All) – The spin the Fermi level should be returned for.
Default: Spin.All
Returns:: The Fermi level in absolute energy.
Return type:: PhysicalQuantity of type energy

inverseParticipationRatio(spin=None)¶

Parameters:: spin (Spin.Up | Spin.Down | Spin.All) – The spin the inverse participation ratio should be returned for.
Default: Spin.All
Returns:: The electronic inverse participation ratio for each orbital and k-point. The array has size (n_spins, n_kpoints, n_orbitals)
Return type:: ndarray

kpoints()¶

Returns:: The k-points on which to calculate the electronic inverse participation ratio.
Return type:: ndarray

metatext()¶

Returns:: The metatext of the object or None if no metatext is present.
Return type:: str | None

nlprint(stream=None)¶

Print a string containing an ASCII table useful for plotting the AnalysisSpin object.

Parameters:: stream (python stream) – The stream the table should be written to.
Default: NLPrintLogger()

printTable(stream=None, energy_min=None, energy_max=None)¶

Print a string containing an ASCII table with the electronic inverse participation ratio data, restricted in an energy window.

Parameters:

stream (A stream that supports strings being written to using 'write'.) – The stream to write to.
energy_min (PhysicalQuantity of type energy) – Lower limit of the energy window with respect to the energy reference.
Default: -5 * eV
energy_max (PhysicalQuantity of type energy) – Upper limit of the energy window with respect to the energy reference.
Default: +5 * eV

setMetatext(metatext)¶

Set a given metatext string on the object.

Parameters:: metatext (str | None) – The metatext string that should be set. A value of “None” can be given to remove the current metatext.

uniqueString()¶: Return a unique string representing the state of the object.

Usage Examples¶

Calculate the ElectronicInverseParticipationRatio at the Gamma point for silicon bulk with a vacancy defect and print out information for the most localized state:

# 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
unit_configuration = BulkConfiguration(
    bravais_lattice=lattice,
    elements=elements,
    fractional_coordinates=fractional_coordinates
    )
reps = 3
bulk_configuration = unit_configuration.repeat(reps, reps, reps)
bulk_configuration = bulk_configuration.copyAndDeleteAtoms(5)

# Setup the calculator.
calculator = LCAOCalculator(
    exchange_correlation=GGA.PBE,
    numerical_accuracy_parameters=NumericalAccuracyParameters(
        k_point_sampling=MonkhorstPackGrid(1, 1, 1))
    )

bulk_configuration.setCalculator(calculator)
bulk_configuration.update()

# Compute the electronic inverse participation ratio
electronic_ipr = ElectronicInverseParticipationRatio(
    configuration=bulk_configuration
    )

print('\nNumber of atoms N:', bulk_configuration.numberOfAtoms())
print(f'Expected IPR for delocalized states 1/N: {1 / bulk_configuration.numberOfAtoms():.3f}')

# Obtain results
energies = electronic_ipr.energies().inUnitsOf(eV)
ipr = electronic_ipr.inverseParticipationRatio()
idx = numpy.argmax(ipr)
print(f'State at energy {energies.ravel()[idx]:.2f} eV',
      f'has the highest IPR: {ipr.ravel()[idx]:.3f}')

electronic_ipr.py

Notes¶

The following definition is used to calculate the electronic inverse participation ratio for a system of \(N\) atoms [1]

\[ \begin{align}\begin{aligned}p^{(n)}_{i} = \sum^{N}_{i=1} |q^{(n)}_{i}|^2,\\q^{(n)}_{i} = \sum_{\mu \in i, \nu} \mathrm{Re}[S_{\mu \nu} c^{*}_{\mu n} c_{\nu n}]\end{aligned}\end{align} \]

where \(\mathbf{S}\) is the overlap matrix and \(c_{\mu n}\) are the \(n\)-th wavefunction coefficients in the LCAO basis. The inverse participation ratio is \(1/N\) for completely delocalized states and greater for localized states. The current definition does not pose an upper limit to the value of the inverse participation ratio.

Note

The electronic inverse participation ratio can only be computed for configurations with LCAOCalculator or SemiEmpiricalCalculator, since the current definition is based on a localized basis orbital representation.