Line Calculations

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

class z2pack.line.EigenstateLineData(*args, **kwargs)[source]

Data container for a line constructed from periodic eigenstates \(|u_{n, \mathbf{k}} \rangle\). This has all attributes that OverlapLineData has, and the following additional ones:

  • eigenstates : The eigenstates of the Hamiltonian, given as a list of arrays which contain the eigenstates as row vectors.

class z2pack.line.LineResult(data, stateful_ctrl, convergence_ctrl)[source]

Container for the data, state and convergence status of a line calculation. The attributes / properties of the data object (WccLineData or EigenstateLineData) can be accessed directly from the LineResult object.

property convergence_report

Convergence report (as a dict) for the result. The keys of the dictionary indicate the type of convergence test, and the values are booleans which are True if the test converged.

class z2pack.line.OverlapLineData(*args, **kwargs)[source]

Data container for Line Data constructred from overlap matrices. This has all attributes that WccLineData has, and the following additional ones:

  • overlaps : A list containing the overlap matrix for each step of k-points, as numpy array.

  • wilson : An array containing the Wilson loop (product of overlap matrices) for the line. The Wilson loop is given in the basis of the eigenstates at the start / end of the line.

  • wilson_eigenstates : Eigenstates of the Wilson loop, given as a list of 1D - arrays.

class z2pack.line.WccLineData(*args, **kwargs)[source]

Data container for a line constructed directly from the WCC. The following attributes and properties can be accessed:

  • wcc : A list of Wannier charge centers.

  • pol : The total polarization (sum of WCC) along the line.

  • gap_pos : The position of the largest gap between any two WCC.

  • gap_size: The size of the largest gap between any two WCC.


The WCC are given in reduced coordinates, which means the possible values range from 0 to 1. The same is true for all values derived from the WCC.*, system, line, pos_tol=0.01, iterator=range(8, 27, 2), save_file=None, init_result=None, load=False, load_quiet=True, serializer='auto')

Calculates the Wannier charge centers for a given system and line, automatically converging w.r.t. the number of k-points along the line.

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

  • line – Line along which the WCC should be calculated. The argument should be a callable which parametrizes the line \(\mathbf{k}(t)\), in reduced coordinates. It should take one argument (float) and return a list of float describing the point in k-space. Note that the line must be closed, that is \(\mathbf{k}(0) = \mathbf{k}(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.

  • 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, msgpack is used.


LineResult instance.

Example usage:

system = ... # Refer to the various ways of creating a System instance.
result =
    line=lambda t: [t, 0, 0] # Line along kx for ky, kz = 0.
print(result.wcc) # Prints the list of WCC.