BlochState

class BlochState(configuration=None, quantum_number=None, spin=None, k_point=None, density_mesh_cutoff=None)

A class for calculating the wave function of a Bloch state.

Parameters:

  • configuration (BulkConfiguration) – The configuration for which the Bloch state should be calculated.

  • quantum_number (int) – The quantum number of the desired Bloch state.
    Default: 0

  • spin (Spin.Up | Spin.Down | Spin.All) – The spin to calculate the Bloch state for.
    Default: Spin.All

  • k_point (list(3) of floats) – The k-point in fractional coordinates that the Bloch state should be calculated for.
    Default: [0.0, 0.0, 0.0]

  • density_mesh_cutoff (PhysicalQuantity of type energy | GridSampling | OptimizedFFTGridSampling) – The mesh cutoff to be used to determine the grid sampling. The mesh cutoff must be a positive energy or a GridSampling object.
    Default: Specific for each calculator.

absolute()
Returns:

A new grid containing the absolute values (or modulus) of the current field.

Return type:

GridValues

axisProjection(projection_type='sum', axis='c', spin=None, projection_point=None, coordinate_type=<class 'NL.ComputerScienceUtilities.NLFlag._NLFlag.Fractional'>)

Get the values projected on one of the grid axes.

Parameters:

  • projection_type (str) –

    The type of projection to perform. Should be either

    • ’sum’ for the sum over the plane spanned by the two other axes.

    • ’average’ or ‘avg’ for the average value over the plane spanned by the two other axes.

    • ’line’ for the value along a line parallel to the axis and through a point specified by the projection_point parameter.


    Default: ‘sum’

  • axis (str) – The axis to project the data onto. Should be either ‘a’, ‘b’ or ‘c’.
    Default: ‘c’

  • spin (Spin.Sum | Spin.Z | Spin.X | Spin.Y | Spin.Up | Spin.Down | Spin.RealUpDown | Spin.ImagUpDown) – Which spin component to project on.
    Default: Spin.All

  • projection_point (sequence, PhysicalQuantity) – Axis coordinates of the point through which to take a line if projection_type is ‘projection_point’. Must be given as a sequence of three coordinates [a, b, c]. It the numbers have units of length, they are first divided by the length of the respective primitive vectors [A, B, C], and then interpreted as fractional coordinates. Unitless coordinates are immidiately interpreted as fractional.

  • coordinate_type (Fractional | Cartesian) – Flag to toggle if the returned axis values should be given in units of Angstrom (NLFlag.Cartesian) or in units of the norm of the axis primitive vector (NLFlag.Fractional).
    Default: Fractional

Returns:

A 2-tuple of 1D numpy.arrays containing the axis values and the projected data. For Cartesian coordinate type the grid offset is added to the axis values.

Return type:

tuple.

derivatives(x, y, z, spin=None)

Calculate the derivative of the wave function in the point (x, y, z).

Parameters:

  • x (PhysicalQuantity of type length) – The Cartesian x coordinate.

  • y (PhysicalQuantity of type length) – The Cartesian y coordinate.

  • z (PhysicalQuantity of type length) – The Cartesian z coordinate.

  • spin (Spin.Up | Spin.Down | Spin.All) – The spin component to project on.
    Default: The spin of this Bloch state object.

Returns:

The gradient at the specified point for the given spin. For Spin.All, a tuple with (Spin.Up, Spin.Down) components is returned if the calculation is not unpolarized.

Return type:

PhysicalQuantity of type energy-3/2 × length-1

downsample(downsampling_a=None, downsampling_b=None, downsampling_c=None)

Generate a new GridValues object where the grid is downsampled. Along periodic directions an FFT downsampling is performed. Along non-periodic directions antialiasing and downsampling is performed.

Parameters:

  • downsampling_a (int) – The new number of grid points along the A direction.
    Default: No downsampling.

  • downsampling_b (int) – The new number of grid points along the B direction.
    Default: No downsampling.

  • downsampling_c (int) – The new number of grid points along the C direction.
    Default: No downsampling.

eigenvalue()

Returns the eigenvalue associated with the calculated eigenstate (as absolute energy).

Returns:

The eigenvalue associated with the calculated eigenstate (as absolute energy). For a polarized calculation with Spin.All, both Spin.Up and Spin.Down values are returned

Return type:

PhysicalQuantity of type energy | list of PhysicalQuantity of type energy.

evaluate(x, y, z, spin=None)

Evaluate the wave function in the point (x, y, z).

Parameters:

  • x (PhysicalQuantity of type length) – The Cartesian x coordinate.

  • y (PhysicalQuantity of type length) – The Cartesian y coordinate.

  • z (PhysicalQuantity of type length) – The Cartesian z coordinate.

  • spin (Spin.Up | Spin.Down | Spin.All) – The spin component to project on.
    Default: The spin of this Bloch state object.

Returns:

The value at the specified point for the given spin. For Spin.All, a tuple with (Spin.Up, Spin.Down) components is returned if the calculation is not unpolarized.

Return type:

PhysicalQuantity of type energy-3/2

gridCoordinate(i, j, k)

Return the coordinate for a given grid index.

Parameters:

  • i (int) – The grid index in the A direction.

  • j (int) – The grid index in the B direction.

  • k (int) – The grid index in the C direction.

Returns:

The Cartesian coordinate of the given grid index.

Return type:

PhysicalQuantity of type length.

kPoint()
Returns:

The k-point to calculate the Bloch state for.

Return type:

list(3) of floats

metatext()
Returns:

The metatext of the object or None if no metatext is present.

Return type:

str | None

nlinfo()
Returns:

The information.

Return type:

dict

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

primitiveVectors()
Returns:

The primitive vectors of the grid.

Return type:

PhysicalQuantity of type length.

quantumNumber()
Returns:

The quantum number of the desired eigenstate.

Return type:

int

quantumNumberReference()
Returns:

Whether the quantum number is counted starting from the lowest available state (Absolute), or from the first occupied state (Lumo).

Return type:

Absolute``|``Lumo

scale(scale)

Scale the field with a float.

Parameters:

scale (float) – The parameter to scale with.

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.

shape()
Returns:

The number of grid points in each direction.

Return type:

tuple of three int.

spin()
Returns:

The spin the Bloch state is calculated for.

Return type:

Spin.Up | Spin.Down | Spin.All

spinProjection(spin=None)

Construct a new GridValues object with the values of this object projected on a given spin component.

Parameters:

spin (Spin.All | Spin.Sum | Spin.X | Spin.Y | Spin.Z | Spin.Up | Spin.Down | Spin.RealUpDown | Spin.ImagUpDown) – The spin component to project on.
Default: The spin the object was created with. If the spin was Spin.All, Spin.Sum will be used for the projection.

Returns:

A new GridValues object for the specified spin.

Return type:

GridValues

toArray()
Returns:

The values of the grid as a numpy array slicing off any units.

Return type:

numpy.array

uniqueString()

Return a unique string representing the state of the object.

unit()
Returns:

The unit of the data in the grid.

Return type:

A physical unit.

unitCell()
Returns:

The unit cell of the grid.

Return type:

PhysicalQuantity of type length.

volumeElement()
Returns:

The volume element of the grid represented by three vectors.

Return type:

PhysicalQuantity of type length.

Usage Examples

Calculate and save a Bloch state for a gold FCC crystal:

# Define lattice
lattice = FaceCenteredCubic(4.08*Angstrom)

# Define elements
elements = [Gold]

# Define coordinates
coordinates = [[2.0, 2.0, 2.0]]*Angstrom

# Set up configuration
bulk_configuration = BulkConfiguration(
    lattice,
    elements,
    coordinates
    )

# Define a a calculator
bulk_configuration.setCalculator(LCAOCalculator())

# Calculate and save the Bloch state with quantum number 5
bloch_state = BlochState(bulk_configuration, quantum_number=5,
                         k_point=[0.0, 0.5, 0.5])
nlsave('bloch_state.nc', bloch_state)

blochstate.py

For examples on working with 3D grids, see HartreePotential and ElectronDensity.

Note

For more advanced options and calculating multiple BlochState objects calculateBlochStates() is advisable.