FatBandstructure¶

class FatBandstructure(configuration, route=None, points_per_segment=None, kpoints=None, bands_above_fermi_level=None, projections=None, diagonalization_method=None)¶

Analysis class for calculating the fat band structure (or projected band structure) for a bulk configuration.

Parameters:

configuration (BulkConfiguration) – The bulk configuration with an attached calculator for which to calculate the fat band structure.
route (list of str) – The route to take through the Brillouin-zone as a list of symmetry points of the unit cell, e.g. ['G', 'X', 'G']. This option is mutually exclusive to kpoints.
Default: Unit-cell dependent route.
points_per_segment (int) – The number of points per segment of the route given as a positive integer. This option is mutually exclusive to kpoints.
Default: 20.
kpoints (list of lists of floats) – A list of 3-dimensional fractional k-points at which to calculate the energies of the bands e.g. [[0.0, 0.0, 0.0], [0.0, 0.0, 0.1], ...]. The shape is (K, 3) where K is the number of k-points. This option is mutually exclusive to route, and points_per_segment.
Default: Unit-cell dependent route.
bands_above_fermi_level –
Deprecated: from v2023.09, see diagonalization_method and FullDiagonalizationSolver instead.
projections (list of Projection | Projection | ProjectionGenerator) – The projections used for calculating the weights.
Default: ProjectOnUpDownSpin.
diagonalization_method –
Method used for diagonalizing the hamiltonian.

This parameter allows to choose between a full diagonalization solver and an iterative subspace solver. The full diagonalization solver evaluates all bands from the lowest energy one to a given number of bands above fermi level. The iterative subspace solver allows to evaluate a given number of bands around fermi level, or around an energy of choice.

The full diagonalization solver is more robust, but can be proibitively expensive for very large systems.

The iterative solver can deal with very large systems (tens of thousands atoms and beyond) and greatly outperforms when calculating a small number of eigenvalues, but it is also inherently less robust.

Note: the exact method used when selecting FullDiagonalizationSolver is defined by the calculator (see AlgorithmParameters). IterativeDiagonalizationSolver is not supported for PlaneWaveCalculator

Default: FullDiagonalizationSolver

Type:

FullDiagonalizationSolver | IterativeDiagonalizationSolver

conductionBandEdge()¶

Calculate the conduction band edge.

Returns:: The conduction band edge.
Return type:: PhysicalQuantity of type energy

directBandGap()¶

Calculate the direct band gap.

Returns:: The direct band gap.
Return type:: PhysicalQuantity of type energy

energyZero()¶

The energy zero is equal to the Fermi level. For fixed spin moment calculations it is the average of the Fermi level for spin up and spin down.

Returns:: The energy zero.
Return type:: PhysicalQuantity of type energy

evaluate()¶

Get the eigenvalues.

Returns:: The eigenvalues. The shape is (K, B), where K is the number of k-points and B the number of bands. B also includes the spin channel for polarized AND unpolarized calculations. Spin up and spin down solutions are interleaved, i.e. up and down bands alternate. In contrast to the behavior of the Bandstructure class, an unpolarized calculation is treated as a polarized one with identical up and down components. This is done, since different projections could be chosen for the up and down states even for unpolarized calculations (see Projection).
Return type:: list of PhysicalQuantity of type energy

fermiLevel(spin=None)¶

Parameters:: spin (Spin.Up | Spin.Down | Spin.All) – The spin the Fermi level should be returned for. Must be either Spin.Up, Spin.Down, or Spin.All. Only when the band structure is calculated with a fixed spin moment will the Fermi level depend on spin.
Default: Spin.All
Returns:: The Fermi level in absolute energy.
Return type:: PhysicalQuantity of type energy

fermiTemperature()¶

Returns:: The Fermi temperature used in this bandstructure.
Return type:: PhysicalQuantity of type temperature

indirectBandGap()¶

Calculate the indirect band gap.

Returns:: The indirect band gap.
Return type:: PhysicalQuantity of type energy

kpoints()¶

Returns:: The list of 3-dimensional fractional k-points at which the energies of the bands are calculated. The shape is (K, 3) where K is the number of k-points.
Return type:: list of lists of floats

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

projections()¶

Returns:: The projections.
Return type:: list of Projection

route()¶

Returns:: The route through the Brillouin-zone as a list of symmetry points of the unit cell.
Return type:: list of str

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.

valenceBandEdge()¶

Calculate the valence band edge.

Returns:: The valence band edge.
Return type:: PhysicalQuantity of type energy

weights()¶

Returns:: The weights for a given projection. Each projection provides a weight for all the eigenvalues. The shape is (P, K, B), where P is the number of projections, K is the number of k-points, and B is the number of spin-interleaved bands as in the output of the evaluate method.
Return type:: numpy.ndarray of doubles

Usage Example¶

Calculate the shell resolved fat band structure for bulk silicon.

lattice = FaceCenteredCubic(5.4306*Angstrom)
bulk_configuration = BulkConfiguration(
    bravais_lattice=lattice,
    elements=[Silicon, Silicon],
    fractional_coordinates=[(0.0, 0.0, 0.0), (0.25, 0.25, 0.25)])

# -------------------------------------------------------------
# Calculator
# -------------------------------------------------------------
k_point_sampling = MonkhorstPackGrid(7, 7, 7)

calculator = LCAOCalculator(
        numerical_accuracy_parameters=NumericalAccuracyParameters(
            k_point_sampling=k_point_sampling))

bulk_configuration.setCalculator(calculator)
bulk_configuration.update()

# -------------------------------------------------------------
# FatBandstructure
# -------------------------------------------------------------
fat_bandstructure = FatBandstructure(
    configuration=bulk_configuration,
    projections=ProjectOnShellsByElement
    )

In the example above we used an abbreviation to generate the list of projections (see Projection documentation). Alternatively, if we would obtain the same result by specifying:

# -------------------------------------------------------------
# FatBandstructure
# -------------------------------------------------------------
projections = [Projection(l_quantum_numbers=[0]),
               Projection(l_quantum_numbers=[1]),
               Projection(l_quantum_numbers=[2])]

fat_bandstructure = FatBandstructure(
        configuration=bulk_configuration,
        projections=projections)

If we want to build more complex projections we can use the algebraic operations, as documented in Projection. In the following example we calculate the fat band structure for bulk gallium arsenide, projecting on the s shells of gallium and p shells of arsenic

lattice = FaceCenteredCubic(5.6537*Angstrom)
elements = [Gallium, Arsenic]
fractional_coordinates = [[ 0.  ,  0.  ,  0.  ],
                          [ 0.25,  0.25,  0.25]]
bulk_configuration = BulkConfiguration(
    bravais_lattice=lattice,
    elements=elements,
    fractional_coordinates=fractional_coordinates
    )

# -------------------------------------------------------------
# Calculator
# -------------------------------------------------------------
k_point_sampling = MonkhorstPackGrid(7, 7, 7)

numerical_accuracy_parameters = NumericalAccuracyParameters(
    k_point_sampling=k_point_sampling,
    )

calculator = LCAOCalculator(
    numerical_accuracy_parameters=numerical_accuracy_parameters,
    )

bulk_configuration.setCalculator(calculator)
bulk_configuration.update()

# -------------------------------------------------------------
# FatBandstructure
# -------------------------------------------------------------
p1 = Projection(l_quantum_numbers=[0], atoms=[Gallium])
p2 = Projection(l_quantum_numbers=[1], atoms=[Arsenic])

fat_bandstructure = FatBandstructure(
    configuration=bulk_configuration,
    projections=p1+p2    
    )

Notes¶

The FatBandstructure (or Projected band structure) is used to visualize the contribution of different orbitals to the bandstructure of a bulk system. Given a projection on a subspace, for each eigenvalue we can calculate a weight associated to the projection. The weights are calculated as follows: the eigenstates and eigenvalues are calculated by solving the Schrödinger equation, similarly to an ordinary bandstructure calculation

\[H \psi_{n {\bf k}} = E \psi_{n {\bf k}}\]

We then define an operator \({\hat{\bf P}_M}\) which performs a projection onto the subspace \(M\). The weight \(\omega^{M}_{n {\bf k}}\) associated to this projection for the eigenpair \((E_{n {\bf k}}, \psi_{n {\bf k}})\) is given by

\[\omega^{M}_{n {\bf k}} = \langle \psi_{n {\bf k}} | \hat{\bf P}_M | \psi_{n {\bf k}} \rangle\]

It follows from the definition and form the normalization condition on \(\psi_{n {\bf k}}\) that the weight is \(1.0\) for any eigenpair if the projection operator is the identity. The projection operator is defined according to the description contained in the documentation for Projection.

Note

The FatBandstructure will return weights between \(0\) and \(1\) (unitless) for projections on up/down spin, and between \(-1\) to \(1\) (in units of \(\frac{\hbar}{2}\)) for projections involving the Pauli spin matrices. See the Usage Example in Projection for some more information.