System

The first step in the wannierberri calculation is initialising the System. This is done by means of child classes System described below. The system may either be constructed bu wannierisation in WannierBerri, or come either from Wanier functions constructed by Wannier90, or from ref:tight binding <sec-tb-models> models. Also k.p models are supported, see SystemKP.

class wannierberri.system.System(frozen_max=-inf, periodic=(True, True, True), NKFFT=None, force_internal_terms_only=False, name='wberri', silent=False)

Bases: object

The base class for describing a system. Does not have its own constructor, please use the child classes, e.g System_w90 or System_tb

Parameters:

• periodic ([bool,bool,bool]) – set True for periodic directions and False for confined (e.g. slab direction for 2D systems). If less then 3 values provided, the rest are treated as False .

• frozen_max (float) – position of the upper edge of the frozen window. Used in the evaluation of orbital moment. But not necessary.

• NKFFT – the FFT grid which further will be used in calculations by default

• force_internal_terms_only (bool) – only internal terms will be evaluated in all formulae, the external or cross terms will be excluded. the internal terms are defined only by the Hamiltonian and spin

• name (str) – name that will be used by default in names of output files

• silent (bool) – if True, the code will not print any information about the system

Notes

• The system is described by its real lattice, symmetry group, and Hamiltonian.

• The lattice is given by the lattice vectors in the Cartesian coordinates.

• The symmetry group is given by the generators of the group. The group is further evaluated by the code.

• The Hamiltonian is given by the hopping terms between the orbitals. The hopping terms are given in the real space.

• The system can be either periodic or confined in some directions..

property recip_lattice

returns: The reciprocal lattice vectors in the Cartesian coordinates :rtype: np.ndarray(3,3)

set_pointgroup(symmetry_gen=(), pointgroup=None, spacegroup=None)

Set the symmetry group of the System, which will be used for symmetrization in k-space and for reducing the number of k-points in the BZ.

Parameters:

• symmetry_gen (list of symmetry.Symmetry or str) – The generators of the symmetry group.

• spacegroup (irrep.spacegroup.SpaceGroup) – The space group of the system. The point group will be evaluated by the space group.

• pointgroup (PointGroup) – The point group of the system. If provided, the code will use it as the symmetry group.

Notes

• Only the generators of the symmetry group are essential. However, no problem if more symmetries are provided. The code further evaluates all possible products of symmetry operations, until the full group is restored.

• Providing Identity is not needed. It is included by default

• Operations are given as objects of symmetry.Symmetry or by name as str, e.g. 'Inversion' , 'C6z', or products like 'TimeReversal*C2x'.

• symetyry_gen=[] is equivalent to not calling this function at all

• Only the point group operations are important. Hence, for non-symmorphic operations, only the rotational part should be given, neglecting the translation.

property cell_volume

returns: The volume of the unit cell in Angstrom^3 :rtype: float

Real-space systems

class wannierberri.system.System_R(berry=False, morb=False, spin=False, SHCryoo=False, SHCqiao=False, OSD=False, _getFF=False, ws_dist_tol=0.05, **parameters)

Bases: System

The base class for describing a system. Does not have its own constructor, please use the child classes, e.g System_w90 or System_tb

Parameters:

• berry (bool) – set True to enable evaluation of external term in Berry connection or Berry curvature and their derivatives.

• spin (bool) – set True if quantities derived from spin will be used.

• morb (bool) – set True to enable calculation of external terms in orbital moment and its derivatives. Requires the .uHu file.

• OSD (bool) – set True to enable calculation of external terms in orbital contribution to Optical Spatial dispersion Requires the uIu` and .uHu files.

• periodic ([bool,bool,bool]) – set True for periodic directions and False for confined (e.g. slab direction for 2D systems). If less then 3 values provided, the rest are treated as False .

• SHCryoo (bool) – set True if quantities derived from Ryoo’s spin-current elements will be used. (RPS 2019)

• SHCqiao (bool) – set True if quantities derived from Qiao’s approximated spin-current elements will be used. (QZYZ 2018).

• _getFF (bool) – generate the FF_R matrix based on the uIu file. May be used for only testing so far. Default : {_getFF}

• npar (int) – number of nodes used for parallelization in the __init__ method. Default: multiprocessing.cpu_count()

• ws_dist_tol (float) – the tolerance for the Wigner-Seitz distance. Default: 1e-5

Notes

• The system is described by its real lattice, symmetry group, and Hamiltonian and other real-space matrices.

• The lattice is given by the lattice vectors in the Cartesian coordinates.

• The system can be either periodic or confined in some directions.

needed_R_matrices

the set of matrices that are needed for the current calculation. The matrices are set in the constructor.

Type:

set

npar

number of nodes used for parallelization in the __init__ method. Default: multiprocessing.cpu_count()

Type:

int

_XX_R

dictionary of real-space matrices. The keys are the names of the matrices, the values are the matrices themselves.

Type:

dict(str:array)

wannier_centers_cart

the positions of the Wannier centers in the Cartesian coordinates.

Type:

array(float)

wannier_centers_red

the positions of the Wannier centers in the reduced coordinates.

Type:

array(float)

num_wann

the number of Wannier functions.

Type:

int

real_lattice

the lattice vectors of the model.

Type:

array(float, shape=(3,3))

NKFFT_recommended

the recommended size of the FFT grid to be used in the interpolation.

Type:

int

set_R_mat(key, value, diag=False, R=None, reset=False, add=False, Hermitian=False)

Set real-space matrix specified by key. Either diagonal, specific R or full matrix. Useful for model calculations

Parameters:

• key (str) – ‘SS’, ‘AA’ , etc

• value (array) –

  • array(num_wann,…) if diag=True . Sets the diagonal part ( if R not set, R=[0,0,0])

  • array(num_wann,num_wann,..) matrix for R (R should be set )

  • array(Rvec, num_wann,num_wann,…) full spin matrix for all R

  … denotes the vector/tensor cartesian dimensions of the matrix element

• diag (bool) – set only the diagonal for a specific R-vector (if specified), or fpr R=[0,0,0]

• R (list(int)) – list of 3 integer values specifying R. if

• reset (bool) – allows to reset matrix if it is already set

• add (bool) – add matrix to the already existing

• Hermitian (bool) – force the value to be Hermitian (only if all vectors are set at once)

set_spin(spins, axis=(0, 0, 1), **kwargs)

Set spins along axis in SS(R=0). Useful for model calculations. Note : The spin matrix is purely diagonal, so that <up | sigma_x | down> = 0 For more cversatility use set_R_mat() set_spin_pairs(), set_spin_from_projections()

Parameters:

• spin (one on the following) – 1D array(num_wann) of +1 or -1 spins are along axis

• axis (array(3)) – spin quantization axis (if spin is a 1D array)

• **kwargs – optional arguments ‘R’, ‘reset’, ‘add’ see set_R_mat()

set_spin_pairs(pairs)

set SS_R, assuming that each Wannier function is an eigenstate of Sz,

Parameters:

pairs (list of tuple) – list of pairs of indices of bands [(up1,down1), (up2,down2), ..]

Notes

• For abinitio calculations this is a rough approximation, that may be used on own risk.

• See also set_spin_from_projections()

set_spin_from_projections()

set SS_R, assuming that each Wannier function is an eigenstate of Sz,

with interlaced spin ordering, which means that the orbitals of the two spins are interlaced. (like in the amn file of QE and new versions of VASP)

Notes

• This is a rough approximation, that may be used on own risk

• The pure-spin character may be broken by maximal localization. Recommended to use num_iter=0 in Wannier90

also see set_spin_pairs()

set_structure(positions, atom_labels, magnetic_moments=None)

Set atomic structure of the system.

Parameters:

• positions ((num_atom, 3) array_like of float) – Atomic positions in fractional coordinates.

• atom_labels ((num_atom,) list) – labels (integer, string, etc.) to distinguish species.

• magnetic_moments ((num_atom, 3) array_like of float (optional)) – Magnetic moment vector of each atom.

set_symmetry_from_structure()

Set the symmetry group of the System. Requires spglib to be installed. System.set_structure() must be called in advance.

For magnetic systems, symmetries involving time reversal are not detected because spglib does not support time reversal symmetry for noncollinear systems.

Symmetrization of the system

There are two interfaces: one with explicit specification of the struvcture (old interface) and one with SymmetrizerSAWF (new interface).

System_R.symmetrize(proj, positions, atom_name, soc=False, magmom=True, silent=True, reorder_back=False)

Symmetrize Wannier matrices in real space: Ham_R, AA_R, BB_R, SS_R,… , as well as Wannier centers Also sets the pointgroup (with method “new”)

Parameters:

• positions (array) – Positions of each atom.

• atom_name (list) – Name of each atom.

• proj (list) –

  Should be the same with projections card in relative Wannier90.win.

  eg: ['Te: s','Te:p']

  If there is hybrid orbital, grouping the other orbitals.

  eg: ['Fe':sp3d2;t2g] Plese don’t use ['Fe':sp3d2;dxz,dyz,dxy]

  ['X':sp;p2] Plese don’t use ['X':sp;pz,py]

  Note: If in wannier90.win file one sets several projections in one line like ['Fe':d;sp3] the actual order (as written to the wannier90.nnkp file) may be different. It is ordered by the orbital number l, and the hybrids are assigned negative numbers (e.g. for sp3 l=-3, see Wannier90 user guide chapter 3). So, the actual order will be ['Fe':sp3;d]. To avoid confusion, it is recommended to put the different groups of projectons as separate lines of the wannier90.win file. See also here

• soc (bool) – Spin orbital coupling.

• magmom (2D array) – Magnetic momens of each atoms.

• store_symm_wann (bool) – Store the (temporary) SymWann object in the sym_wann attribute of the System object. Can be useful for evaluating symmetry eigenvalues of wavefunctions, etc.

• rotations (array-like (shape=(N,3,3))) – Rotations of the symmetry operations. (optional)

• translations (array-like (shape=(N,3))) – Translations of the symmetry operations. (optional)

• silent (bool) – If True, do not print the symmetrization process.

• reorder_back (bool) – If True, reorder the wannier functions back to the original order after symmetrization. (if the order happened to be changed (see note below))

Returns:

symmetrizer – the symmetrizer object that was used for symmetrization. Can be used for further analysis of the symmetry properties of the system.

Return type:

wanierberri.symmetry.sawf.SymmetrizerSAWF

Notes

• after symmetrization, the wannier functions may be reordered, to group the atoms

by same wyckoff positions. In this case, the symmetrizer is not returned, because it would be inconsistent with the order of the projections.

• Works only with phase convention I (use_wcc_phase=True) (which anyway is now the ONLY option)

Spin ordering is assumed to be interlaced (like in the amn file of QE and new versions of VASP). If it is not, use spin_block2interlace() to convert it.

System_R.symmetrize2(symmetrizer, silent=True)

Symmetrize the system according to the Symmetrizer object.

Parameters:

• symmetrizer (wanierberri.symmetry.sawf.SymmetrizerSAWF) – The symmetrizer object that will be used for symmetrization. (make sure it is consistent with the order of projections)

• silent (bool) – If True, do not print the symmetrization process. (set to False to see more debug information)

From Wannier functions

Wanierisation inside WannierBerri

Now WannierBerri can construct wannier functions on its own.see Wannierisation inside WannierBerri

Wannier90

class wannierberri.system.System_w90(seedname='wannier90', w90data=None, transl_inv_MV=False, transl_inv_JM=False, fftlib='fftw', npar=None, kmesh_tol=1e-07, bk_complete_tol=1e-05, wannier_centers_from_chk=True, read_npz=True, write_npz_list=('eig', 'mmn'), write_npz_formatted=True, overwrite_npz=False, formatted=(), symmetrize=True, **parameters)

Bases: System_R

System initialized from the Wannier functions generated by Wannier90 code. Reads the .chk, .eig and optionally .mmn, .spn, .uHu, .sIu, and .sHu files

Parameters:

• seedname (str) – the seedname used in Wannier90

• w90data (~wannierberri.system.Wannier90data) – object that contains all Wannier90 input files and chk all together. If provided, overrides the seedname

• transl_inv_JM (bool) – translational-invariant scheme for diagonal and off-diagonal matrix elements for all matrices. Follows method of Jae-Mo Lihm

• wannier_centers_from_chk (bool) – If True, the centers of the Wannier functions are read from the .chk file. If False, the centers are recalculated from the .mmn file.

• npar (int) – number of processes used in the constructor

• fft (str) – library used to perform the fast Fourier transform from q to R. fftw or numpy. (practically does not affect performance, anyway mostly time of the constructor is consumed by reading the input files)

• kmesh_tol (float) – tolerance to consider the b_k vectors (connecting to neighbouring k-points on the grid) belonging to the same shell

• bk_complete_tol (float) – tolerance to consider the set of b_k shells as complete.

• read_npz (bool)

• write_npz_list (tuple(str))

• write_npz_formatted (bool) – see ~wannierberri.system.w90_files.Wannier90data

• overwrite_npz (bool) – see ~wannierberri.system.w90_files.Wannier90data

• formatted (tuple(str)) – see ~wannierberri.system.w90_files.Wannier90data

• symmetrize (bool) – if True, the R-matrices and wannier centers are symmetrized (highly recommended, False is for debugging only) works only if initialized from the w90data object, and that object has the symmetrizer

• transl_inv_MV (bool) – Use Eq.(31) of Marzari&Vanderbilt PRB 56, 12847 (1997) for band-diagonal position matrix elements Note : it applies only to the AA matrix for R+!=[0,0,0] and only if transl_inv_JM is False Kept for legacy reasons, as it is not used recommended to use.

• **parameters – see ~wannierberri.system.System_R and ~wannierberri.system.system.System for the rest of the parameters

Notes

The R-matrices are evaluated in the nearest-neighbor vectors of the finite-difference scheme chosen.

seedname

the seedname used in Wannier90

Type:

str

_NKFFT_recommended

recommended size of the FFT grid in the interpolation

Type:

int

See also

None

FPLO

class wannierberri.system.System_fplo(hamdata='+hamdata', mp_grid=None, **parameters)

Bases: System_R

System initialized from the +hamdata file written by FPLO code,

Parameters:

• hamdata (str) – name (and path) of the “+hamdata” file to be read

• mp_grid ([nk1,nk2,nk3]) – size of Monkhorst-Pack frid used in ab initio calculation. Needed for MDRS

Notes

see also parameters of the System

ASE

class wannierberri.system.System_ASE(ase_wannier, **parameters)

Bases: System_R

System initialized from the Wannier functions generated by ASE .

Parameters:

ase_wannier – An object of ASE Wannier .

Notes

see also parameters of the System

From tight-binding models

wannier90_tb.dat file

class wannierberri.system.System_tb(tb_file='wannier90_tb.dat', convention_II_to_I=True, wannier_centers_cart=None, **parameters)

Bases: System_R

System initialized from the *_tb.dat file, which can be written either by Wannier90 code, or composed by the user based on some tight-binding model. See Wannier90 code for details of the format.

Parameters:

• tb_file (str) – name (and path) of file to be read

• convention_II_to_I (bool) – By default, the tb file in wannier90 format is in the convention II, which is different from the convention I used in wannierberri. If the file is already in the convention I, set this parameter to False.

• wannier_centers_cart (np.ndarray(num_wann, 3)) – If provided, will override the wannier centers read from the file. (and hence they will be subtracted from the AA_R matrix if convention_II_to_I is True)

Notes

see also parameters of the System

PythTB

class wannierberri.system.System_PythTB(ptb_model, **parameters)

Bases: System_tb_py

This interface is a way to initialize the System class from a tight-binding model created with PythTB. It defines the Hamiltonian matrix Ham_R (from hoppings matrix elements) and the AA_R matrix (from orbital coordinates) used to calculate Berry related quantities.

Parameters:

ptb_model (class) – name of the PythTB tight-binding model class.

Notes

see also parameters of the System_tb_py

TBmodels

class wannierberri.system.System_TBmodels(tbmodel, **parameters)

Bases: System_tb_py

This interface initializes the System class from a tight-binding model created with TBmodels. It defines the Hamiltonian matrix Ham_R (from hoppings matrix elements) and the AA_R matrix (from orbital coordinates) used to calculate Berry related quantities.

Parameters:

tbmodel – name of the TBmodels tight-binding model object.

Notes

see also parameters of the System_tb_py

Randomly generated

class wannierberri.system.SystemRandom(num_wann, nRvec=10, real_lattice=None, max_R=5, **parameters)

Bases: System_R

Randomly generated system. Mainly for testing. Further can be symmetrized to get generic system with certain symmetries.

Parameters:

num_wannint

number of Wannier functions

real_latticearray( (3,3) )

real lattice vectors. inf None - generated randomly

nRvecint

number of R-space vectors

max_R:

maximal coordinate in the R-vectors

k-space systems

\(\mathbf{k}\cdot\mathbf{p}\) models

class wannierberri.system.SystemKP(Ham, derHam=None, der2Ham=None, der3Ham=None, kmax=1.0, real_lattice=None, recip_lattice=None, k_vector_cartesian=True, finite_diff_dk=0.0001, **parameters)

Bases: System_k

A system to describe k.p Hamiltonians. Technically, it is concodered as a periodic system with k-vector limited to the box defined by the reciprocal lattice. a k-vector is always translated to have reduced coordinates between [-1/2,1/2) (In future : translate to the 1BZ for non-simple-cubic lattices)

Parameters:

• Ham (function) – The Hamiltonian - a function of 3D k-vector that returns a (num_waan x num_wann) Hermitean matrix

• derHam (function) – The cartesian k-derivative of the Hamiltonian - a function of 3D k-vector that returns a (num_waan x num_wann x 3) Hermitean (in mn) matrix. If not specified, it will be evaluated numerically from Ham with a finite-difference scheme using the finite_diff_dk parameter.

• der2Ham (function) – The cartesian second k-derivative of the Hamiltonian - a function of 3D k-vector that returns a (num_waan x num_wann x 3 x 3) Hermitean (in mn) matrix If not specified, it will be evaluated numerically from derHam with a finite-difference scheme using the finite_diff_dk parameter.

• der3Ham (function) – The cartesian second k-derivative of the Hamiltonian - a function of 3D k-vector that returns a (num_waan x num_wann x 3 x 3 x 3) Hermitean (in mn) matrix If not specified, it will be evaluated numerically from der2Ham with a finite-difference scheme using the finite_diff_dk parameter.

• kmax (float) – maximal k-vector (in \(\mathring{\rm A}^{-1}\)) In this case the reciprocal lattice is cubic with size 2*kmax

• real_lattice (array(3,3)) – the lattice vectors of the model (iif kmax is not set)

• recip_lattice (array(3,3)) – the reciprocal lattice vectors of the model (if ‘kmax’,’real_lattice’ are not set)

• k_vector_cartesian (bool) – if True, the k-vector in Ham, derHar, der2Ham is given in cartesian coordinates. if False - it is in reduced coordinates (Note : the derivatives are always assumed w.r.t. cartesian coordinates)

• finite_diff_dk (float) – defines the dk in taking derivatives (in fraction of the reciprocal lattice)

Notes

• if derivatives of hamiltonian are not provided, they are computed with finite diifferences

• internally, self.Ham and derivatives (self.Ham_cart, self_derHam_cart …) accept k in reduced coordinated.

• the derivatives are always assumed w.r.t. cartesian coordinates