VibrationalInverseParticipationRatio¶

class VibrationalInverseParticipationRatio(configuration, dynamical_matrix, qpoints=None)¶

Class for calculating the vibrational inverse participation ratio.

Parameters:

configuration (BulkConfiguration | MoleculeConfiguration) – The configuration for which to calculate the vibrational inverse participation ratio.
dynamical_matrix (DynamicalMatrix) – The dynamical matrix from which to calculate the vibrational inverse participation ratio.
qpoints (sequence (size 3) of int | MonkhorstPackGrid | KpointDensity | RegularKpointGrid | sequence of sequence (size 3) of float) – The q-points on which to calculate the vibrational inverse participation ratio.
Default: The Gamma point (0.0, 0.0, 0.0).

energies()¶

Returns:: The energies for each vibrational mode.
Return type:: PhysicalQuantity of type energy

inverseParticipationRatio()¶

Returns:: The vibrational inverse participation ratio for each vibrational mode and q-point. The array has size (n_qpoints, n_modes)
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 vibrational 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.
Default: 0 * meV
energy_max – Upper limit of the energy window.
Default: 20 * meV

qpoints()¶

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

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 VibrationalInverseParticipationRatio 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)

# Set up calculator
potentialSet = Tersoff_Si_2005()
calculator = TremoloXCalculator(parameters=potentialSet)
calculator.setVerletListsDelta(1.0*Angstrom)

bulk_configuration.setCalculator(calculator)
bulk_configuration.update()

# Set up density matrix
dynamical_matrix = DynamicalMatrix(
    bulk_configuration,
    filename='Silicon_defect.hdf5',
    object_id='dynamical_matrix',
    repetitions=Automatic,
    atomic_displacement=0.01*Angstrom,
    acoustic_sum_rule=True,
    finite_difference_method=Central,
    force_tolerance=1e-08*Hartree/Bohr**2,
    processes_per_displacement=None,
    log_filename_prefix='forces_displacement_',
    use_wigner_seitz_scheme=False,
    )
dynamical_matrix.update()

# Compute the vibrational inverse participation ratio
vibrational_ipr = VibrationalInverseParticipationRatio(
    configuration=bulk_configuration,
    dynamical_matrix=dynamical_matrix
    )

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 = vibrational_ipr.energies().inUnitsOf(meV)
ipr = vibrational_ipr.inverseParticipationRatio()
idx = numpy.argmax(ipr)
print(f'Mode at energy {energies.ravel()[idx]:.2f} meV',
      f'has the highest IPR: {ipr.ravel()[idx]:.3f}')

vibrational_ipr.py

Notes¶

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

\[p^{(n)}_{i} = \frac{\sum^{N}_{i=1}|\mathbf{u}^{(n)}_i|^4}{\left(\sum^{N}_{i=1}|\mathbf{u}^{(n)}_i|^2\right)^2}\]

where \(\mathbf{u}^{(n)}_i\) are the displacements eigenvectors for the \(n\)-th mode from the DynamicalMatrix. The inverse participation ratio is \(1\) for completely localized states and \(1/N\) for completely delocalized states.