# 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 A 2-tuple of 1D numpy.arrays containing the axis values and the projected data. 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. 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. 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. 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. 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. 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. 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. 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. The Cartesian coordinate of the given grid index. PhysicalQuantity of type length.
metatext()
Returns: The metatext of the object or None if no metatext is present. 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. 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. 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. tuple of three int.
spin()
Returns: The spin the STM image is calculated for, always Spin.Sum. 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. A new GridValues object for the specified spin. GridValues
temperature()
Returns: The temperature for the thermal smearing of the Fermi distribution. 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. PhysicalQuantity of type inverse length
toArray()
Returns: The values of the grid as a numpy array slicing off any units. numpy.array
unit()
Returns: The unit of the data in the grid. A physical unit.
unitCell()
Returns: The unit cell of the grid. PhysicalQuantity of type length.
voltage()
Returns: Voltage between tip and sample. PhysicalQuantity of type electric potential
volumeElement()
Returns: The volume element of the grid represented by three vectors. PhysicalQuantity of type length.