AdaptiveGrid

class AdaptiveGrid(kA_range=None, kB_range=None, tolerance=None, error_measure=None, number_of_initial_levels=None, maximum_number_of_levels=None, kpoints=None, intervals=None, triangles=None, function_values=None, integral_value=None)
Parameters:
  • kA_range (list(2) of float | float) – Interval for k-points in the kA-direction given in fractional coordinates. If a single number is given there will be no k-points in this direction.
    Default: [-0.5, 0.5]

  • kB_range (list(2) of float | float) – Interval for k-points in the kA-direction given in fractional coordinates. If a single number is given there will be no k-points in this direction.
    Default: [-0.5, 0.5]

  • tolerance (Positive float) – Tolerance for integration.
    Default: 1e-3

  • error_measure (Absolute | Relative) – Method to calculate error. Either Absolute (absolute error) or Relative (relative error).
    Default: Absolute

  • number_of_initial_levels (Non-negative int) – Minimum number of refinement steps in the adaptive grid.
    Default: 3

  • maximum_number_of_levels (Non-negative int) – Maximum number of refinement steps in the adaptive grid.
    Default: 20

  • kpoints – List of initial k-point, e.g. [[0.0, 0.0], [0.1, 0.0]]. Mutually exclusive with kA_range and kB_range. Can be used for restarting from a previous calculation.
    Default: None

  • intervals (list(n_intervals) of list(2) of int) – List of intervals represented two integers, e.g. [(0, 1), (1, 2), (2, 3)]. The integers correspond to the indices of the k-points that are the end points of each interval. Mutually exclusive with kA_range and kB_range. Can be used for restarting from a previous calculation.
    Default: None

  • triangles (list(n_triangles) of list(3) of int) – List of triangles represented three integers, e.g. [(0, 1, 2), (0, 2, 3)]. The integers correspond to the indices of the k-points that are the corner points of each triangle. Mutually exclusive with kA_range and kB_range. Can be used for restarting from a previous calculation.
    Default: None

  • function_values (list(n_kpoints) of float) – List of function values corresponding to each k-point. Mutually exclusive with kA_range and kB_range. Can be used for restarting from a previous calculation.
    Default: None

dimension()
Returns:

The dimension of the k-point integration. Can be either 1 or 2.

Return type:

int

errorMeasure()
Returns:

The error_measure used for this AdaptiveGrid.

Return type:

Absolute or Relative

functionValues()
Returns:

The values of the integrated function in all the k-points.

Return type:

ndarray(n) where n is the number of k-points.

initialIntervals()
Returns:

A list of the initial intervals.

Return type:

list(n) of Intervals where n is the number of intervals.

initialKpoints()
Returns:

The list of initial k-points.

Return type:

ndarray(n, m) of floats where n is the number of k-points and m is the dimension.

initialTriangles()
Returns:

A list of the initial triangles.

Return type:

list(n) of Triangles where n is the number of triangles.

integralValue()
Returns:

The value of the integrated function.

Return type:

float

intervals()
Returns:

A list of the intervals once the integration is finished.

Return type:

list(n) of Intervals where n is the number of intervals.

kARange()
Returns:

The range of k-points in the kA-direction.

Return type:

list(2) of float.

kBRange()
Returns:

The range of k-points in the kB-direction.

Return type:

list(2) of float.

kpoints()
Returns:

All of the k-points used in the integration.

Return type:

list(n) of k-points where n is the number of k-points.

kpointsWeights()
Returns:

The weight of all the k-points used in the integration.

Return type:

list(n) of float where n is the number of k-points.

maximumNumberOfLevels()
Returns:

The number of maximum levels allowed in the adaptive integration.

Return type:

int

numberOfInitialLevels()
Returns:

The number of initial levels used in the adaptive integration.

Return type:

int

tolerance()
Returns:

The tolerance at which the adaptive integration should stop.

Return type:

float

triangles()
Returns:

A list of the triangles once the integration is finished.

Return type:

list(n) of Triangles where n is the number of triangles.

uniqueString()

Return a unique string representing the state of the object.

Usage Examples

Define an adaptive grid:


# Setup adaptive grid object.
adaptive_grid = AdaptiveGrid(
	kA_range=[-0.5, 0.5],
	kB_range=[-0.5, 0.5],
	tolerance=1e-2,
	error_measure=Absolute,
	number_of_initial_levels=2,
	maximum_number_of_levels=7)

# Use adaptive grid instead of kpoints in transmission spectrum.
transmission_spectrum = TransmissionSpectrum(device_configuration,
				             kpoints=adaptive_grid)


# Use adaptive grid instead of kpoints in spin transfer torque.
spin_transfer_torque = SpinTransferTorque(device_configuration,
                                          contributions=Left,
					  kpoints=adaptive_grid)

adaptive_grid.py

Notes

When using adaptive grids for integration, the integration domain is divided into triangles, as illustrated in Fig. 139. The integral over each triangle area is estimated as

\[I_0 = A_0 (F_1 + F_2 + F_3)/3,\]

where \(A_0\) is the area of the triangle, and \(F_1\), \(F_2\), \(F_3\) are the function values at the triangle corner points. In order to estimate whether the integral, \(I_0\), (left inset in Fig. 139) is converged or not, each triangle is divided into four smaller triangles with integral values \(I_1\), \(I_2\), \(I_3\), \(I_4\) (right inset in Fig. 139). The integral error, \(E_{I_0}\), for triangle integral \(I_0\) is computed as

\[E_{I_0}^{abs} = \frac{|I_0 - (I_1 + I_2 + I_3 + I_4)|}{A_0},\]

if the error_measure is Absolute and as

\[E_{I_0}^{rel} = \frac{|I_0 - (I_1 + I_2 + I_3 + I_4)|}{I_{tot}},\]

if the error_measure is Relative, where \(I_{tot}\) is the total integral over the entire integration domain at the present level of refinement.

It depends on the actual problem, if one should use the error_measure=Absolute or error_measure=Relative option. If one has some knowledge about the function values, e.g., the transmission spectrum, the use of Absolute may be more advantageous. On the other hand, if there is no information available on the function values, using Relative is a better option. This is also the case if spin.Up and spin.Down have rather different transmission spectra.

../../../_images/adaptive_triangles.png

Fig. 139 The integration domain is divided into triangle areas. In order to estimate whether the integral, \(I_0\), (left inset) is converged or not, each triangle is divided into four smaller triangles with integral values \(I_1\), \(I_2\), \(I_3\), \(I_4\) (right inset).

Fig. 140 illustrates schematically the data flow in the adaptive algorithm.

../../../_images/adaptive_algorithm.png

Fig. 140 Schematic drawing of the adaptive algorithm. If the error is larger than the tolerance, \(\epsilon\), the triangle is divided into four smaller triangles.

The AdaptiveGrid can be used as the kpoint keyword in the following analysis objects: