# Bandstructure¶

class Bandstructure(configuration, route=None, points_per_segment=None, kpoints=None, bands_above_fermi_level=None, projection_list=None, processes_per_kpoint=None)

Analysis class for calculating the bandstructure for a bulk configuration.

Parameters: configuration (BulkConfiguration) – The bulk configuration with an attached calculator for which to calculate the bandstructure. 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 (Positive int) – The number of points per segment of the route. 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 (Non-negative int | All) – The number of bands above the Fermi level per principal spin channel. Default: All (All bands are included), except for calculators of type PlaneWaveCalculator; in this case the default number of bands above the Fermi level is equal to the number of bands below the Fermi level. If more bands are included in the calculator, they will also be calculated as default. projection_list (ProjectionList) – A projection list object defining a projection. Default: If no projection list is specified all orbitals will be used. processes_per_kpoint (int | None) – The number of processes to use per kpoint. If None the same number of processes per k-point as used in the SCF calculation will be used. Default: None
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
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. PhysicalQuantity of type energy
evaluate(spin=None)

Return the bandstructure for a given spin.

Parameters: spin (Spin.Up | Spin.Down | Spin.All) – The spin the bandstructure should be returned for. Must be either Spin.Up or Spin.Down, or for noncollinear calculations Spin.All. Default: Spin.All The eigenvalues for the specified spin. The shape is (K, B) or (S, K, B) where S is the number of spins, K is the number of k-points, and B is the number of bands. PhysicalQuantity of type energy | 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()
processesPerKPoint()

Deprecated since version 2019.

Returns: The number of processes per k-point used in the calculation. int > 0
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

## Usage Examples¶

Calculate the bandstructure of silicon and save it to a file:

# -------------------------------------------------------------
# Bulk Configuration
# -------------------------------------------------------------
lattice = FaceCenteredCubic(5.4306*Angstrom)
elements = [Silicon, Silicon]
fractional_coordinates = [[ 0.  ,  0.  ,  0.  ],
[ 0.25,  0.25,  0.25]]
bulk_configuration = BulkConfiguration(
bravais_lattice=lattice,
elements=elements,
fractional_coordinates=fractional_coordinates
)

# -------------------------------------------------------------
# Calculator
# -------------------------------------------------------------
basis_set = [CerdaHuckelParameters.Silicon_GW_diamond_Basis]
hamiltonian_parametrization = HuckelHamiltonianParametrization(
basis_set=basis_set)
k_point_sampling = MonkhorstPackGrid(9,9,9)
numerical_accuracy_parameters = NumericalAccuracyParameters(
k_point_sampling=k_point_sampling,
density_mesh_cutoff=10.0*Hartree,
)
calculator = SemiEmpiricalCalculator(
hamiltonian_parametrization=hamiltonian_parametrization,
numerical_accuracy_parameters=numerical_accuracy_parameters,
)
bulk_configuration.setCalculator(calculator)
bulk_configuration.update()

# -------------------------------------------------------------
# Bandstructure
# -------------------------------------------------------------
bandstructure = Bandstructure(
configuration=bulk_configuration,
route=['G', 'X'],
points_per_segment=40,
bands_above_fermi_level=4
)

# Read the valence and conduction band edges wrt. the Fermi level
edge_valence = bandstructure.valenceBandEdge()
edge_conduction = bandstructure.conductionBandEdge()
print(edge_valence)
# Read the direct and indirect band gaps
gap_direct   = bandstructure.directBandGap()
gap_indirect = bandstructure.indirectBandGap()
print(gap_indirect)
# Print out results
print('Valence band maximum    = %.2f eV' % edge_valence.inUnitsOf(eV))
print('Conduction band minimum = %.2f eV' % edge_conduction.inUnitsOf(eV))
print('Direct band gap   = %.2f eV' % gap_direct.inUnitsOf(eV))
print('Indirect band gap = %.2f eV' % gap_indirect.inUnitsOf(eV))


si_band.py

## Notes¶

To export the data of a Bandstructure, use the method nlprint.

Note that the k-points are given in units of the reciprocal vectors $${\bf k}_A$$ , $${\bf k}_B$$ , and $${\bf k}_C$$. E.g. the symmetry point $$X$$ have the fractional k-point coordinates $$(\frac{1}{2}, 0, \frac{1}{2})$$ since it is described by $$X = \frac{1}{2}{\bf k}_A + \frac{1}{2}{\bf k}_C$$ .

A query method for the symmetry points of the Brillouin zone can be found in Common methods of the Bravais Lattices class.

For bands_above_fermi_level set to a valid integer $$N_{\text{ba}}$$, the total number of bands above the Fermi level will be $$N_{\text{ba}}$$ for the spin type unpolarized and $$2 N_{\text{ba}}$$ for polarized and noncollinear. This is because there is one spin channel in the former case and two spin channels in the latter two cases. Spin-orbit calculations are categorized as non-collinear calculations and therefore follow the same band selection as noncollinear. The case where bands_above_fermi_level is 1 is illustrated in Fig. 121. Note, that all bands below the Fermi level are always selected.

Fig. 121 The total number of bands selected (blue lines) by specifying 1 band above the Fermi level for (a) an unpolarized, (b) a polarized, and (c) a non-collinear calculation. The Fermi level $$E_{\text{F}}$$ is shown as a horizontal dashed gray line. The vertical separation line in (b) signifies that the bands can be categorized according to spin up or down since there is no coupling. The structure of the Hamiltonian for each of the 3 spin types is shown at the bottom.