Volume Calculations

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

class z2pack.volume.VolumeData(*args, **kwargs)

Data container for a volume calculation. It contains the SurfaceResult instances of all the surfaces in the volume which have been calculated.

The following properties / attributes can be accessed:

  • s : A tuple containing all current surface positions.

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

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

add_surface(s, result)

Adds a surface result to the list of surfaces.

Parameters:

  • s (float) – Position of the surface.

  • result (SurfaceResult) – Result of the surface calculation.

nearest_neighbour_dist(s)

Returns the distance between \(s\) and the nearest existing surface.

class z2pack.volume.VolumeResult(data, stateful_ctrl, convergence_ctrl)

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

Example:

result = z2pack.volume.run(...)
print(result.s) # prints the positions of the surfaces
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.volume.run(*, system, volume, pos_tol=0.01, gap_tol=0.3, move_tol=0.3, num_surfaces=11, 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 volume.

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

  • volume – Volume in which the WCC / Wilson loops should be calculated. The argument should be a callable which parametrizes the volume \(\mathbf{k}(t_1, t_2, t_3)\), in reduced coordinates. It should take three 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_3\) - direction, that is \(\mathbf{k}(t_1, t_2, 0) = \mathbf{k}(t_1, t_2, 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.

  • num_surfaces (int) – Initial number of surfaces.

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

VolumeResult instance.

Example usage:

system = ... # Refer to the various ways of creating a System instance.
result = z2pack.volume.run(
    system=system,
    surface=lambda t1, t2, t3: [t1, t2, t3]
)
print(result.wcc) # Prints a nested list of WCC (a list for each surface, which each contains a list of WCC for each line).