Initializing a System
The first step in the wannierberri
calculation is initialising the System. This is done by means of child classes System
described below.
They all have an important common method set_symmetry()
.
The system may come either from Wanier functions constructed by Wannier90, or from ref:tight binding <sec-tb-models> models.
- class wannierberri.system.System(frozen_max=-inf, periodic=(True, True, True), NKFFT=None, force_internal_terms_only=False, name='wberri')[source]
Bases:
object
The base class for describing a system. Does not have its own constructor, please use the child classes, e.g
System_w90
orSystem_tb
- Parameters:
periodic ([bool,bool,bool]) – set
True
for periodic directions andFalse
for confined (e.g. slab direction for 2D systems). If less then 3 values provided, the rest are treated asFalse
.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
- set_symmetry(symmetry_gen=())[source]
Set the symmetry group of the
System
- Parameters:
symmetry_gen (list of
symmetry.Symmetry
or str) – The generators of 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 allOnly the point group operations are important. Hence, for non-symmorphic operations, only the rotational part should be given, neglecting the translation.
Real-space systems
- class wannierberri.system.System_R(berry=False, morb=False, spin=False, SHCryoo=False, SHCqiao=False, OSD=False, use_ws=True, use_wcc_phase=True, npar=None, _getFF=False, **parameters)[source]
Bases:
System
The base class for describing a system. Does not have its own constructor, please use the child classes, e.g
System_w90
orSystem_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 andFalse
for confined (e.g. slab direction for 2D systems). If less then 3 values provided, the rest are treated asFalse
.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).use_ws (bool) – minimal distance replica selection method Minimal-distance replica selection method. equivalent of
use_ws_distance
in Wannier90. (Note: forSystem_tb
the method is not employed in the constructor. use do_ws_dist() if needed)_getFF (bool) – generate the FF_R matrix based on the uIu file. May be used for only testing so far. Default :
{_getFF}
use_wcc_phase (bool) – using wannier centers in Fourier transform. Corresponding to Convention I (True), II (False) in Ref.”Tight-binding formalism in the context of the PythTB package”. Default:
{use_wcc_phase}
npar (int) – number of nodes used for parallelization in the __init__ method. Default: multiprocessing.cpu_count()
- set_R_mat(key, value, diag=False, R=None, reset=False, add=False, Hermitian=False)[source]
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(num_wann,num_wann,nRvec,…) 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)[source]
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_code()
- 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)[source]
set SS_R, assuming that each Wannier function is an eigenstate of Sz, :param pairs: list of pairs of indices of bands
[(up1,down1), (up2,down2), ..]
:type pairs: list of tupleNotes
For abinitio calculations this is a rough approximation, that may be used on own risk.
See also
set_spin_from_code()
- set_spin_from_code(DFT_code='qe')[source]
- set SS_R, assuming that each Wannier function is an eigenstate of Sz,
according to the ordering of the ab-initio code
- Parameters:
DFT_code (str) –
- DFT code used :
'qe'
: if bands are grouped by orbital type, in each pair first comes spin-up,then spin-down'vasp'
: if bands are grouped by spin : first come all spin-up, then all spin-down
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
if your DFT code has a different name, but uses the same spin ordering as qe or vasp - set DFT_code=’qe’ or DFT_code=’vasp’ correspondingly
if your DFT code has a different spin ordering, use
set_spin_pairs()
- set_structure(positions, atom_labels, magnetic_moments=None)[source]
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()[source]
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
- System_R.symmetrize(proj, positions, atom_name, soc=False, magmom=None, DFT_code='qe')[source]
Symmetrize Wannier matrices in real space: Ham_R, AA_R, BB_R, SS_R,… , as well as Wannier centers
- 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 heresoc (bool) – Spin orbital coupling.
magmom (2D array) – Magnetic momens of each atoms.
DFT_code (str) – DFT code used :
'qe'
or'vasp'
. This is needed, because vasp and qe have different orbitals arrangement with SOC.(grouped by spin or by orbital type)
Notes
Works only with phase convention I (use_wcc_phase=True)
From Wannier functions
Wannier90
- class wannierberri.system.System_w90(seedname='wannier90', w90data=None, transl_inv=True, transl_inv_JM=False, guiding_centers=False, fftlib='fftw', npar=2, kmesh_tol=1e-07, bk_complete_tol=1e-05, wcc_phase_fin_diff=True, read_npz=True, write_npz_list=('eig', 'mmn'), write_npz_formatted=True, overwrite_npz=False, formatted=(), **parameters)[source]
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 (bool) – Use Eq.(31) of Marzari&Vanderbilt PRB 56, 12847 (1997) for band-diagonal position matrix elements
transl_inv_JM (bool) – translational-invariant scheme for diagonal and off-diagonal matrix elements for all matrices. Follows method of Jae-Mo Lihm
guiding_centers (bool) – If True, enable overwriting the diagonal elements of the AA_R matrix at R=0 with the Wannier centers calculated from Wannier90.
npar (int) – number of processes used in the constructor
fft (str) – library used to perform the fast Fourier transform from q to R.
fftw
ornumpy
. (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)
Notes
see also parameters of the
System
for npz and formatted parameters see see ~wannierberri.system.w90_files.Wannier90data
Wanierisation inside WannierBerri
- system.disentangle(froz_min=inf, froz_max=-inf, num_iter=100, conv_tol=1e-09, num_iter_converge=10, mix_ratio=0.5, print_progress_every=10)
Performs disentanglement of the bands recorded in w90data, following the procedure described in Souza et al., PRB 2001 At the end writes w90data.chk.v_matrix and sets w90data.wannierised = True
- Parameters:
w90data (
Wannier90data
) – the datafroz_min (float) – lower bound of the frozen window
froz_max (float) – upper bound of the frozen window
num_iter (int) – maximal number of iteration for disentanglement
conv_tol (float) – tolerance for convergence of the spread functional (in \(\mathring{\rm A}^{2}\))
num_iter_converge (int) – the convergence is achieved when the standard deviation of the spread functional over the num_iter_converge iterations is less than conv_tol
mix_ratio (float) – 0 <= mix_ratio <=1 - mixing the previous itertions. 1 for max speed, smaller values are more stable
print_progress_every – frequency to print the progress
- Returns:
w90data.chk.v_matrix
- Return type:
numpy.ndarray
Example:
import wannierberri as wberri
# assume that files are in folder ./path/to and the seedname is `Fe` (files `Fe.win`, `Fe.chk`, etc)
w90data = wberri.system.Wannier90data(sedname="path/to/Fe")
wberri.system.disentangle(w90data,
froz_min=-8,
froz_max=20,
num_iter=2000,
conv_tol=5e-7,
mix_ratio=0.9,
print_progress_every=100
)
system=wberri.system.System_w90(w90data=w90data,berry=True, morb=True)
del w90data # recommended to save memory, we may not need it anymore
FPLO
- class wannierberri.system.System_fplo(hamdata='+hamdata', mp_grid=None, **parameters)[source]
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 when use_ws=True, which is default and highly recommended
Notes
see also parameters of the
System
ASE
- class wannierberri.system.System_ASE(ase_wannier, ase_R_vectors=False, **parameters)[source]
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', **parameters)[source]
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
Notes
see also parameters of the
System
PythTB
- class wannierberri.system.System_PythTB(ptb_model, **parameters)[source]
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)[source]
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)[source]
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)[source]
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