# LocalBandstructure¶

class LocalBandstructure(configuration, symmetry_label=None, kpoint_cartesian=None, kpoint_fractional=None, directions_cartesian=None, directions_fractional=None, bands_below_fermi_level=None, bands_above_fermi_level=None, band_index=None, points_per_segment=None, effective_mass_method=None, stencil_order=None, delta=None)

Analysis class for representing the local properties of the bandstructure for specified k-point, bands, and directions.

Parameters: configuration (BulkConfiguration) – The bulk configuration with an attached calculator for which to calculate the local bandstructure. symmetry_label (str) – The k-point (as a symmetry point) for which to calculate the local bandstructure. This options is mutually exclusive with kpoint_cartesian and kpoint_fractional. Default: 'G' (the Gamma-point (0.0, 0.0, 0.0)) kpoint_cartesian (PhysicalQuantity of type inverse length) – The k-point (in Cartesian coordinates) for which to calculate the local bandstructure. This option is mutually exclusive with symmetry_label and kpoint_fractional. This should be given as a length 3 PhysicalQuantity. Default: The Gamma-point (0.0, 0.0, 0.0) * Angstrom**-1 kpoint_fractional (list of float) – The k-point (in fractional coordinates) for which to calculate the local bandstructure as three floats. This option is mutually exclusive with kpoint_cartesian and symmetry_label. Default: The Gamma-point [0.0, 0.0, 0.0] directions_cartesian (PhysicalQuantity of type inverse length) – Direction vectors along which to calculate the local bandstructure. This should be given as a PhysicalQuantity of shape (N, 3) where N is the number of directions. This option is mutually exclusive with directions_fractional, but either option should be specified. Note: The bandstructure is calculated in the extent of the direction vectors so their length has significance for the range of the parabolic and non-parabolic fits. directions_fractional (list of lists of floats) – Direction vectors along which to calculate the local bandstructure. This should be given as a list of N lists where N is the number of directions and each list contains 3 floats. This option is mutually exclusive with directions_cartesian, but either option should be specified. Note: The bandstructure is calculated in the extent of the direction vectors so their length has significance for the range of the parabolic and non-parabolic fits. bands_below_fermi_level (int) – The number of bands below the Fermi level per principal spin channel to include. This option is mutually exclusive with band_index. If both bands_below_fermi_level and bands_above_fermi_level are given, at least one must be non-zero. This value should be non-negative. Default: 1 bands_above_fermi_level (int) – The number of bands above the Fermi level per principal spin channel to include. This option is mutually exclusive with band_index. If both bands_below_fermi_level and bands_above_fermi_level are given, at least one must be non- zero. This value should be non-negative. Default: 1 band_index (int) – The band index for which to calculate the local bandstructure. This option is mutually exclusive with bands_below_fermi_level and bands_above_fermi_level. This value must be non-negative. points_per_segment (int) – The number of k-points that is calculated from the given k-point or symmetry point along the extent of the given direction vectors. These k-points along the segments are available for the regression of the non-parabolicity parameter. This value must be larger than or equal to 2. Default: 20 effective_mass_method (Analytical | Numerical) – The method used when calculating the effective masses. Default: Numerical stencil_order (int) – The number of points to use in the second order derivative stencil. This value should be larger than or equal to 2. Default: 5 delta (PhysicalQuantity of type inverse length) – The spacing between the k-points used for the stencil. This value must be positive. Default: 0.001 * Angstrom**-1
cartesianDirections()
Returns: The cartesian directions as an (N, 3) array where N is the number of directions. PhysicalQuantity of type inverse length
effectiveMassMethod()
Returns: The method used to calculate the effective masses. Analytical | Numerical
energies()
Returns: The energies at the k-point as a PhysicalQuantity of shape (directions, bands, spins, 2) where directions is the number of directions, bands is the number of bands, and spins is the number of spins. Note: self.energies()[:, :, :, 0] contains energies exactly at the given k-point whereas for self.energies()[:, :, :, 1] the evaluations are done at the nearest extrema for each band. PhysicalQuantity of type energy
evaluate(spin=None, band=None, direction=None, points_in_regression=None, extremum_correction=None)

Evaluate the bandstructure properties at the k-point of the object.

Parameters: spin (Spin.Up | Spin.Down | Spin.All) – The spin for which to return the effective masses and the non-parabolicity parameters. For Noncollinear calculations only Spin.All is accepted. Default: Spin.All band (int) – The band for which to return the effective masses and the non-parabolicity parameters. Must be non-negative. Default: All bands that were specified when the LocalBandstructure was created. direction (int) – The direction for which to return the effective masses and the non-parabolicity parameters. Must be non-negative. Default: All directions that were specified when the LocalBandstructure was created. points_in_regression (int) – The number of k-points in the fit of the non-parabolicity parameter. Must be larger than or equal to 2 and smaller than or equal to points_per_segment. Default: 2 extremum_correction (ExtremumCorrection.No | ExtremumCorrection.Nearest | ExtremumCorrection.All) – The extremum correction method of the k-point to evaluate for. ExtremumCorrection.No: There is no extremum correction of the user specified k-point. ExtremumCorrection.Nearest: The user specified k-point is corrected to the nearest extremum in each band for the given segment. ExtremumCorrection.All: The returned PhysicalQuantity arrays of the effective masses and non-parabolicity parameters contains the results of ExtremumCorrection.No (in index 0) and ExtremumCorrection.Nearest (in index 1) in the last axis. Default: ExtremumCorrection.Nearest A tuple of two PhysicalQuantity arrays. Both have shape (directions, bands, spins, 1) or (directions, bands, spins, 2) depending on the extremum_correction flag. Here directions is the number of directions, bands is the number of bands, and spins is the number of spins. The first PhysicalQuantity array is of type mass and contains effective masses. The second is of type inverse energy and contains non-parabolicity parameters. tuple of PhysicalQuantity arrays
fitBands(spin=None, band=None, direction=None, points_in_regression=None, extremum_correction=None)

Method for calculating the parabolic and non-parabolic fits to the bandstructure.

Parameters: spin (Spin.Up | Spin.Down | Spin.All) – The spin for which to calculate the effective mass and the non- parabolicity parameter. For Noncollinear calculations only Spin.All is accepted. For this method Spin.All is not accepted for Polarized calculations since only one spin species can be queried at a time. Default: Spin.All (Spin.Up for Polarized calculations) band (int) – The band index for which to calculate the effective mass and the non-parabolicity parameter. Must be non-negative. Default: 0 direction (int) – The direction index for which to calculate the effective mass and the non-parabolicity parameter. Must be non-negative. Default: 0 points_in_regression (int) – The number of k-points for which to fit the non-parabolicity parameter. Must be larger than or equal to 2 and smaller than or equal to points_per_segment Default: 2 extremum_correction (ExtremumCorrection.No | ExtremumCorrection.Nearest) – The extremum correction method of the k-point to evaluate for. ExtremumCorrection.No: There is no extremum correction of the user specified k-point. ExtremumCorrection.Nearest: The user specified k-point is corrected to the nearest extremum. Default: ExtremumCorrection.Nearest A tuple of five quantities. The norm of the distances from the k-point where the subsequent quantities are evaluated as a PhysicalQuantity of type inverse length. The calculated band as a PhysicalQuantity of type energy. The effective-mass (parabolic) band as a PhysicalQuantity of type energy. The non-parabolic band as a PhysicalQuantity of type energy. The deviation of the non-parabolic band from the calculated band as a PhysicalQuantity of type energy. tuple
kpoint()
Returns: The k-point in fractional coordinates. numpy.array
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()
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.

## Usage Examples¶

Calculate the effective mass and non-parabolicity parameter of silicon for a k-point, 3 directions, and one band below the Fermi level:

# -------------------------------------------------------------
# Bulk configuration
# -------------------------------------------------------------

# 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
bulk_configuration = BulkConfiguration(
bravais_lattice=lattice,
elements=elements,
fractional_coordinates=fractional_coordinates
)

# -------------------------------------------------------------
# Calculator
# -------------------------------------------------------------
numerical_accuracy_parameters = NumericalAccuracyParameters(
k_point_sampling=(7, 7, 7),
density_mesh_cutoff=75.0*Hartree,
)

calculator = LCAOCalculator(
numerical_accuracy_parameters=numerical_accuracy_parameters,
)

bulk_configuration.setCalculator(calculator)
nlprint(bulk_configuration)
bulk_configuration.update()

# -------------------------------------------------------------
# Local bandstructure
# -------------------------------------------------------------
directions_cartesian = [[0.0, 0.0, 1.0],
[1.0, 1.0, 0.0],
[1.0, 1.0, 1.0]]*Angstrom**-1

local_bandstructure = LocalBandstructure(
configuration=bulk_configuration,
directions_cartesian=directions_cartesian,
kpoint_fractional=[0.5, 0.5, 0.5],
bands_below_fermi_level=1,
bands_above_fermi_level=0,
stencil_order=5,
delta=0.001*Angstrom**-1,
points_per_segment=20
)

nlprint(local_bandstructure)

# Evaluation of the local bandstructure parameters.
effective_mass, nonparabolicity_parameter = local_bandstructure.evaluate(
spin=Spin.Up,
band=0,
direction=2
)

eff_mass = effective_mass[0,0,0].inUnitsOf(electron_mass)
nonpara = nonparabolicity_parameter[0,0,0].inUnitsOf(eV**-1)

print('Effective mass: %.2f me' % (eff_mass))
print('Non-parabolicity parameter: %.4f 1/eV' % (nonpara))


local_bandstructure.py

## Notes¶

• The non-parabolic dispersion model is given by

$E(\mathbf{k}) \left( 1 + \alpha E(\mathbf{k}) \right) = \frac{\hbar^2 |\mathbf{k}|^2}{2 m^*},$

where $$\alpha$$ and $$m^*$$ are the non-parabolicity parameter and the effective mass respectively. The non-parabolic band dispersion is explicitly expressed as

$E(\mathbf{k}) = \frac{-1 + \sqrt{1 + \frac{2 \alpha \hbar^2}{m^*} |\mathbf{k}|^2}}{2 \alpha}.$
• The non-parabolicity parameter is fitted for a number of points along the length and direction of the given direction vector.

• The behavior of bands_above_fermi_level and bands_below_fermi_level with regard to the spin type unpolarized, polarized, and noncollinear is described in Notes of the EffectiveMass analysis object.