# FatBandstructure¶

class FatBandstructure(configuration, route=None, points_per_segment=None, kpoints=None, bands_above_fermi_level=None, projections=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 (int | All) – The number of bands above the Fermi level per principal spin channel. Must be a non-negative integer. Default: All (All bands are included). projections (list of Projection | Projection | ProjectionGenerator) – The projections used for calculating the weights. Default: [Projection(spin=Spin.Up), Projection(spin=Spin.Down)].
conductionBandEdge()

Calculate the conduction band edge.

Returns: The conduction band edge. PhysicalQuantity of type energy
directBandGap()

Calculate the direct band gap.

Returns: The direct band gap. 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). 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 The Fermi level in absolute energy. PhysicalQuantity of type energy
fermiTemperature()
Returns: The Fermi temperature used in this bandstructure. PhysicalQuantity of type temperature
indirectBandGap()

Calculate the indirect band gap.

Returns: The indirect band gap. 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. list of lists of floats
metatext()
Returns: The metatext of the object or None if no metatext is present. str | unicode | 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. list of Projection
route()
Returns: The route through the Brillouin-zone as a list of symmetry points of the unit cell. list of str
setMetatext(metatext)

Set a given metatext string on the object.

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

Calculate the valence band edge.

Returns: The valence band edge. 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. 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.