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)[source]¶ 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 attributess
(the position, which is the sorting key) andresult
(the surface’s result).
The attributes of the underlying
SurfaceResult
instances can be directly accessed from theVolumeData
object. This will create a list of attributes for all surfaces, in the order of their position.
add_surface
(s, result)[source]¶ Adds a surface result to the list of surfaces.
 Parameters
s (float) – Position of the surface.
result (
SurfaceResult
) – Result of the surface calculation.

class
z2pack.volume.
VolumeResult
(data, stateful_ctrl, convergence_ctrl)[source]¶ 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 theVolumeResult
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.

property

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 kstrings.
 Parameters
system (
z2pack.system.EigenstateSystem
orz2pack.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 offloat
describing the points in kspace. 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 kpoints 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 settinggap_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 settingmove_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 kpoint 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
andpickle
. 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).