Eigenstate

class Eigenstate(configuration=None, quantum_number=None, projection_list=None, spin=None, density_mesh_cutoff=None)

A class for calculating the wave function of a particular orbital in a configuration.

Parameters:

  • configuration (MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration) – The configuration for which the eigenstate should be calculated.

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

  • projection_list (ProjectionList) – Specifies the atoms and orbitals within the configuration to include in the calculation.
    Default: ProjectionList(All)

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

  • 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 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 the eigenstate was calculated for.

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.

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 the eigenstate was calculated for.

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.

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

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 eigenstate 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 an eigenstate for water molecule:

# Define elements
elements = [Oxygen, Hydrogen, Hydrogen]

# Define coordinates
cartesian_coordinates = [[  0.0,   0.000000000000,   1.20198000e-01],
                         [  0.0,   7.59572000e-01,  -4.86714000e-01],
                         [  0.0,  -7.59606000e-01,  -4.86721000e-01]]*Angstrom

# Set up configuration
molecule_configuration = MoleculeConfiguration(
    elements=elements,
    cartesian_coordinates=cartesian_coordinates
    )

# define a a calculator
molecule_configuration.setCalculator(LCAOCalculator())

# calculate and save the eigenstate with quantum number 0
eigenstate = Eigenstate(molecule_configuration, 0)
nlsave('eigenstate.nc', eigenstate)

eigenstate.py

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

Notes

Using a projection list means that only the part of the Hamiltonian involving the atoms in the projection list will be used in the diagonalization to find the eigenstates.

Notice that the Eigenstate method neglects interactions across the unit cell boundaries. This makes sense physically for a MoleculeConfiguration where the interactions are artifacts of the calculation. However, for a BulkConfiguration and a DeviceConfiguration, the interactions across cell boundaries represent something real and care should be taken when interpreting the results. For BulkConfiguration, see BlochState for an alternative analysis object. For DeviceConfiguration, see TransmissionEigenstate for an alternative analysis object.

Note

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