Surface Calculations

This module contains the functions and data / result containers for calculating the Wilson loop / Wannier charge centers on a surface in \(\mathbf{k}\)-space.

class z2pack.surface.SurfaceData(*args, **kwargs)[source]

Data container for a surface calculation. It contains the LineResult instances of all the lines on the surface which have been calculated.

The following properties / attributes can be accessed:

  • t : A tuple containing all current line positions.

  • lines : A sorted list of objects which have two attributes t (the position, which is the sorting key) and result (the line’s result).

The attributes of the underlying LineResult instances can be directly accessed from the SurfaceData object. This will create a list of attributes for all lines, in the order of their position.

add_line(t, result)[source]

Adds a line result to the list of lines.

Parameters
  • t (float) – Position of the line (\(t_1\)).

  • result (LineResult) – Result of the line calculation.

nearest_neighbour_dist(t)[source]

Returns the distance between \(t\) and the nearest existing line.

class z2pack.surface.SurfaceResult(data, stateful_ctrl, convergence_ctrl)[source]

Container for the data, state and convergence status of a surface calculation. The attributes / properties of the data object (SurfaceData) can be accessed directly from the SurfaceResult object.

Example:

result = z2pack.surface.run(...)
print(result.t) # prints the positions of the lines
print(result.pol) # prints the sum of WCC for each line
property convergence_report

Convergence report (as a dict) for the result. The keys of the dictionary indicate the type of convergence test. For each of the tests, a dictionary with keys ‘PASSED’, ‘FAILED’ and (optionally) ‘MISSING’ shows the number of tests of this kind which either passed, failed, or were not performed.

z2pack.surface.run(*, system, surface, pos_tol=0.01, gap_tol=0.3, move_tol=0.3, num_lines=11, min_neighbour_dist=0.01, iterator=range(8, 27, 2), init_result=None, save_file=None, load=False, load_quiet=True, serializer='auto')

Calculates the Wannier charge centers for a given system and surface.

  • automated convergence in string direction

  • automated check for distance between gap and wcc → add string

  • automated convergence check w.r.t. movement of the WCC between different k-strings.

Parameters
  • system (z2pack.system.EigenstateSystem or z2pack.system.OverlapSystem.) – System for which the WCC should be calculated.

  • surface – Surface on which the WCC / Wilson loops should be calculated. The argument should be a callable which parametrizes the surface \(\mathbf{k}(t_1, t_2)\), in reduced coordinates. It should take two arguments (float) and return a nested list of float describing the points in k-space. Note that the surface must be closed at least along the \(t_2\) - direction, that is \(\mathbf{k}(t_1, 0) = \mathbf{k}(t_1, 1) + \mathbf{G}\), where \(\mathbf{G}\) is an inverse lattice vector.

  • pos_tol (float) – The maximum movement of a WCC for the iteration w.r.t. the number of k-points in a single string to converge. The iteration can be turned off by setting pos_tol=None.

  • gap_tol (float) – Determines the smallest distance between a gap and its neighbouring WCC for the gap check to be satisfied. The distance must be larger than gap_tol times the size of the gap. This check is performed only for the largest gap in each string of WCC. The check can be turned off by setting gap_tol=None.

  • move_tol (float) – Determines the largest possible movement between WCC of neighbouring strings for the move check to be satisfied. The movement can be no larger than move_tol time the size of the largest gap between two WCC (from the two neighbouring strings, the smaller value is chosen). The check can be turned off by setting move_tol=None.

  • num_lines (int) – Initial number of strings.

  • min_neighbour_dist (float) – Minimum distance between two strings (no new strings will be added, even if the gap check or move check fails).

  • iterator – Generator for the number of points in a k-point string. The iterator should also take care of the maximum number of iterations. It is needed even when pos_tol=None, to provide a starting value.

  • save_file (str) – Path to a file where the result should be stored.

  • init_result (LineResult) – Initial result which is loaded at the start of the calculation.

  • load (bool) – Determines whether the initial result is loaded from save_file.

  • load_quiet (bool) – Determines whether errors / inexistent files are ignored when loading from save_file

  • serializer (module) – Serializer which is used to save the result to file. Valid options are msgpack, json and pickle. By default (serializer='auto'), the serializer is inferred from the file ending. If this fails, json is used.

Returns

SurfaceResult instance.

Example usage:

system = ... # Refer to the various ways of creating a System instance.
result = z2pack.surface.run(
    system=system,
    surface=lambda t1, t2: [t1, t2, 0] # kz=0 surface, with lines along ky.
)
print(result.wcc) # Prints a nested list of WCC (a list of WCC for each line in the surface).