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]

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.

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 | Spin.Up | Spin.Down | Spin.RealUpDown | Spin.ImagUpDown) – 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. An error is raised, if the underlying data does not contain the spin projection of the requested type. In case that Spin.All is used, a tuple with (Spin.Sum, Spin.X, Spin.Y, Spin.Z) components is returned. Note that in the spin unpolarized case the Spin.X, Spin.Y and Spin.Z entries are zero, and for the spin polarized case the Spin.X and Spin.Y are zero.

Return type:

PhysicalQuantity

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 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 | Spin.Up | Spin.Down | Spin.RealUpDown | Spin.ImagUpDown) – 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. An error is raised, if the underlying data does not spin projection of the requested type. In case Spin.All is used, a tuple with (Spin.Sum, Spin.X, Spin.Y, Spin.Z) components is returned. Note that in the spin unpolarized case the Spin.X, Spin.Y and Spin.Z entries are zero, and for the spin polarized case the Spin.X and Spin.Y are zero.

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

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.

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.

STM¶

Usage Examples¶