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 kpoint, bands, and directions.
Parameters:  configuration (
BulkConfiguration
) – The bulk configuration with an attached calculator for which to calculate the local bandstructure.  symmetry_label (str) – The kpoint (as a symmetry point) for which to calculate the local
bandstructure. This options is mutually exclusive with
kpoint_cartesian
andkpoint_fractional
.
Default:'G'
(the Gammapoint(0.0, 0.0, 0.0)
)  kpoint_cartesian (PhysicalQuantity of type inverse length) – The kpoint (in Cartesian coordinates) for which to calculate the local
bandstructure. This option is mutually exclusive with
symmetry_label
andkpoint_fractional
. This should be given as a length 3 PhysicalQuantity.
Default: The Gammapoint(0.0, 0.0, 0.0) * Angstrom**1
 kpoint_fractional (list of float) – The kpoint (in fractional coordinates) for which to calculate the
local bandstructure as three floats. This option is mutually
exclusive with
kpoint_cartesian
andsymmetry_label
.
Default: The Gammapoint[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 nonparabolic 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 nonparabolic 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 bothbands_below_fermi_level
andbands_above_fermi_level
are given, at least one must be nonzero. This value should be nonnegative.
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 bothbands_below_fermi_level
andbands_above_fermi_level
are given, at least one must be non zero. This value should be nonnegative.
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
andbands_above_fermi_level
. This value must be nonnegative.  points_per_segment (int) – The number of kpoints that is calculated from the given kpoint or symmetry point along
the extent of the given direction vectors. These kpoints along the segments are
available for the regression of the nonparabolicity 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 kpoints 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. Return type: PhysicalQuantity of type inverse length

effectiveMassMethod
()¶ Returns: The method used to calculate the effective masses. Return type: Analytical
Numerical

energies
()¶ Returns: The energies at the kpoint 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 kpoint whereas forself.energies()[:, :, :, 1]
the evaluations are done at the nearest extrema for each band.Return type: PhysicalQuantity of type energy

evaluate
(spin=None, band=None, direction=None, points_in_regression=None, extremum_correction=None)¶ Evaluate the bandstructure properties at the kpoint of the object.
Parameters:  spin (
Spin.Up
Spin.Down
Spin.All
) – The spin for which to return the effective masses and the nonparabolicity parameters. ForNoncollinear
calculations onlySpin.All
is accepted.
Default:Spin.All
 band (int) – The band for which to return the effective masses and the nonparabolicity
parameters. Must be nonnegative.
Default: All bands that were specified when theLocalBandstructure
was created.  direction (int) – The direction for which to return the effective masses and the
nonparabolicity parameters. Must be nonnegative.
Default: All directions that were specified when theLocalBandstructure
was created.  points_in_regression (int) – The number of kpoints in the fit of the nonparabolicity
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 kpoint to evaluate for.
ExtremumCorrection.No
: There is no extremum correction of the user specified kpoint.
ExtremumCorrection.Nearest
: The user specified kpoint is corrected to the nearest extremum in each band for the given segment.
ExtremumCorrection.All
: The returned PhysicalQuantity arrays of the effective masses and nonparabolicity parameters contains the results ofExtremumCorrection.No
(in index 0) andExtremumCorrection.Nearest
(in index 1) in the last axis.
Default:ExtremumCorrection.Nearest
Returns: 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 nonparabolicity parameters.
Return type: tuple of PhysicalQuantity arrays
 spin (

fitBands
(spin=None, band=None, direction=None, points_in_regression=None, extremum_correction=None)¶ Method for calculating the parabolic and nonparabolic 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. ForNoncollinear
calculations only Spin.All is accepted. For this method Spin.All is not accepted forPolarized
calculations since only one spin species can be queried at a time.
Default:Spin.All
(Spin.Up
forPolarized
calculations)  band (int) – The band index for which to calculate the effective mass and the
nonparabolicity parameter. Must be nonnegative.
Default:0
 direction (int) – The direction index for which to calculate the effective mass and the
nonparabolicity parameter. Must be nonnegative.
Default:0
 points_in_regression (int) – The number of kpoints for which to fit the nonparabolicity 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 kpoint to evaluate for.
ExtremumCorrection.No
: There is no extremum correction of the user specified kpoint.
ExtremumCorrection.Nearest
: The user specified kpoint is corrected to the nearest extremum.
Default:ExtremumCorrection.Nearest
Returns: A tuple of five quantities.
 The norm of the distances from the kpoint where the subsequent quantities are evaluated as a PhysicalQuantity of type inverse length.
 The calculated band as a PhysicalQuantity of type energy.
 The effectivemass (parabolic) band as a PhysicalQuantity of type energy.
 The nonparabolic band as a PhysicalQuantity of type energy.
 The deviation of the nonparabolic band from the calculated band as a PhysicalQuantity of type energy.
Return type: tuple
 spin (

kpoint
()¶ Returns: The kpoint in fractional coordinates. Return type: numpy.array

metatext
()¶ Returns: The metatext of the object or None if no metatext is present. Return type: 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.
 configuration (
Usage Examples¶
Calculate the effective mass and nonparabolicity parameter of silicon for a kpoint, 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('Nonparabolicity parameter: %.4f 1/eV' % (nonpara))
Notes¶
The nonparabolic 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 nonparabolicity parameter and the effective mass respectively. The nonparabolic 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 nonparabolicity 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
andbands_below_fermi_level
with regard to the spin type unpolarized, polarized, and noncollinear is described in Notes of the EffectiveMass analysis object.