STM

class STM(tip_configuration, sample_configuration, voltage=None, temperature=None, wigner_seitz_radius=None, cutoff_distance=None, k_point=None, energy_step=None, infinitesimal=None, z_cut_tip=None, z_cut_sample=None)

Constructor for the STM object.

Parameters:
  • tip_configuration (BulkConfiguration) – Configuration representing the STM tip. The unit cell of the configuration must be rectangular.
  • sample_configuration (BulkConfiguration) – Configuration representing the STM sample. The unit cell of the configuration must be rectangular.
  • voltage (PhysicalQuantity of type electric potential) – Voltage between tip and sample.
    Default: 1 * Volt
  • temperature (PhysicalQuantity of type temperature) – The temperature for the thermal smearing of the Fermi distribution.
    Default: 300 * Kelvin
  • wigner_seitz_radius (PhysicalQuantity of type length) – The Wigner-Seitz radius giving the reference electron density.
    Default: 8 * Bohr
  • cutoff_distance (PhysicalQuantity of type length) – The cutoff distance for the Gaussian filter of high k vectors.
    Default: 0.25 * Bohr
  • k_point (PhysicalQuantity of type inverse length) – The k-point at which the STM image is calculated.
    Default: [0.0, 0.0, 0.0] * Bohr**-1
  • energy_step (PhysicalQuantity of type energy) – The energy step in energy integral.
    Default: 1.0e-4 * eV
  • infinitesimal (PhysicalQuantity of type energy) – The broadening parameter of the energy levels.
    Default: 0.05 * eV
  • z_cut_tip (list(2) of ints) – Two z-indices defining the region within the bulkside electron density to be removed from the tip system.
    Default: [0, 0]
  • z_cut_sample (list(2) ints) – Two z-indices defining the region within the bulkside electron density to be removed from the sample system.
    Default: [0, 0]
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 Cartesian 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.

Return type:

tuple.

currentSTMDisplacementMatrix()
Returns:The current STM displacement matrix. The shape of the matrix is (N_a, N_b, N_c), where N_a, N_b and N_c are the number of grid points in different Cartesian directions.
Return type:PhysicalQuantity of type current
derivatives(x, y, z, spin=None)

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

Parameters:
  • x (PhysicalQuantity with type length.) – The Cartesian x coordinate.
  • y (PhysicalQuantity with type length.) – The Cartesian y coordinate.
  • z (PhysicalQuantity with type length.) – The Cartesian z coordinate.
  • spin (Spin.All | Spin.Sum | Spin.X | Spin.Y | Spin.Z) – The spin component to project on.
    Default: The spin that the object was constructed with.
Returns:

The gradient at the specified point for the given spin. For Spin.All, a tuple with (Spin.Sum, Spin.X, Spin.Y, Spin.Z) components is returned.

Return type:

PhysicalQuantity

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

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

Parameters:
  • x (PhysicalQuantity with type length) – The Cartesian x coordinate.
  • y (PhysicalQuantity with type length) – The Cartesian y coordinate.
  • z (PhysicalQuantity with type length) – The Cartesian z coordinate.
  • spin (Spin.All | Spin.Sum | Spin.X | Spin.Y | Spin.Z) – The spin component to project on.
    Default: The spin that the object was constructed with.
Returns:

The value at the specified point for the given spin. For Spin.All, a tuple with (Spin.Sum, Spin.X, Spin.Y, Spin.Z) components is returned.

Return type:

PhysicalQuantity

evaluateSTMImage(constant_z=None, constant_current=None, spin=None)

Evaluate the STM data in a given operation mode: Constant height or constant current.

Parameters:
  • constant_z (PhysicalQuantity of type length) – Select the STM operation mode to be constant height.
    Default: None
  • constant_current (PhysicalQuantity of type current) – Select the STM operation mode to be constant current.
    Default: None
  • spin (Spin.All | Spin.Sum | Spin.X | Spin.Y | Spin.Z) – The spin component to project on.
    Default: The spin that the object was constructed with.
Returns:

In constant height mode, a 2D array with the unit Ampere. In constant current mode, a 3D image with the data given as a NLEngine.RealGrid3D object, is returned.

Return type:

PhysicalQuantity with the unit Ampere | NLEngine.RealGrid3D

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 | 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()
primitiveVectors()
Returns:The primitive vectors of the grid.
Return type:PhysicalQuantity of type length.
sampleConstraintFunction()
Returns:The sample constraint function. The shape of the returned array is (3, N_a, N_b, N_c), where N_a, N_b and N_c are the number of grid points in different Cartesian directions.
Return type:PhysicalQuantity of type inverse length
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 | unicode | 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 STM image is calculated for, always Spin.Sum.
Return type:Spin.Sum
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
temperature()
Returns:The temperature for the thermal smearing of the Fermi distribution.
Return type:PhysicalQuantity of type temperature
tipConstraintFunction()
Returns:The tip constraint function. The shape of the returned array is (3, N_a, N_b, N_c), where N_a, N_b and N_c are the number of grid points in different Cartesian directions.
Return type:PhysicalQuantity of type inverse length
toArray()
Returns:The values of the grid as a numpy array slicing off any units.
Return type:numpy.array
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.
voltage()
Returns:Voltage between tip and sample.
Return type:PhysicalQuantity of type electric potential
volumeElement()
Returns:The volume element of the grid represented by three vectors.
Return type:PhysicalQuantity of type length.

Usage Examples