StraWBerryPy API

StraWBerryPy API#

StraWBerryPy’s API is organized in several modules, which are described in the following sections. The main module is strawberrypy, which provides the main classes and functions to define models, compute topological invariants, and perform post-processing. The strawberrypy.example_models module contains predefined example models that can be used as templates to define custom models and to test the code. The strawberrypy.postprocessing module includes tools for post-processing the results of the calculations, such as plotting functions and correlation functions.

The central class of the code is the Model class, which represents a tight-binding model in its unit cell. This can then be used to define finite or supercell models, which are represented by the FiniteModel and Supercell classes, respectively. These classes provide methods to compute both single-point topological invariants and local geometrical and topological quantities, as well as to add disorder and perform other operations on the model. The following sections provide a detailed description of the main modules and classes of StraWBerryPy.

Model class#

Model

A Model class describing a tight-binding model in its unit cell.

Model.add_disorder_bernoulli

Add on-site Bernoulli disorder to the model.

Model.add_disorder_uniform

Add on-site uniform Anderson disorder to the model.

Model.add_vacancies

Add vacancies in the system by removing a site in the lattice.

Model.from_wannier90

Create a Model instance from Wannier90 output files.

Model.make_finite

Create a finite system given of the current model by repeating the unit cell, allowing to compute single-point invariants and local geometrical and topological markers.

Model.make_heterostructure

Create a heterostructure starting from another model.

Model.make_supercell

Create a supercell given of the current model by repeating the unit cell, allowing to compute single-point invariants and local geometrical and topological markers.
class strawberrypy.Model(model, spinful=False, n_occ=None, **kwargs)[source]#

Bases: object

A Model class describing a tight-binding model in its unit cell.

Create a model with a given tight-binding Hamiltonian in its unit cell. Supercells and finite models can be constructed from it, and global topological invariants can be computed. The class can be initialized from a tight-binding model defined in TBmodels, PythTB or WannierBerri, or via the appropriate constructor it is able to read Wannier90 files generated from an ab initio calculation.

Parameters:

  • model –

    The tight-binding model from which the Model instance is generated. This can be obtained from either a TBmodels, a PythTB, or a WannierBerri model instance.

  • spinful (bool) – Whether the model is spinful or not. Default is False.

  • n_occ (int) – Number of occupied states. This information is required if the model is obtained from Wannier functions generated by Wannier90 code starting an ab initio calculation. In all the other cases the number of occupied states can is optional and if None half-filling is automatically assumed.

  • kwargs –

    Additional keyword arguments. Available keyword arguments are:

    • file_spn (bool, default = False): whether the file seedname.spn is provided if the model is obtained from Wannier functions generated by Wannier90 code starting from a \(\Gamma\)-only ab initio calculation. This file contains the spin matrix elements in the basis of Wannier functions, which are needed to compute the spin Bott index for models with non-trivial spin textures. If this file is not provided, the spin matrix elements are computed in the basis of tight-binding orbitals, which are diagonal in the spin operator \(S_z\). This can lead to incorrect results for models with non-trivial spin textures.

    • Lx (int, default = 1): number of unit cells along the \(\mathbf{a}_1\) direction.

    • Ly (int, default = 1): number of unit cells along the \(\mathbf{a}_2\) direction.

    • debug_info (bool, default = False): whether to print debug information during initialization. This can be useful for large models to track the progress of the initialization.

    Some keyword arguments are automatically set during the initialization and should not be overridden in general, as they are needed for the correct functioning of the class. These are:

    • states_uc (int, default = None): number of states in the unit cell.

    • disordered (bool, default = False): whether the model is disordered or not. This is automatically set to True when disorder is added to the model.

    • has_vacancies (bool, default = False): whether the model has vacancies or not. This is automatically set to True when vacancies are added to the model.

add_disorder_bernoulli(w=0, on_site=True, seed=None)[source]#

Add on-site Bernoulli disorder to the model. Bernoulli disorder consists in a diagonal term in the Hamiltonian \(\mathcal H_{Bernoulli}=\sum_i w_i c_i^{\dagger}c_i\) where \(w_i\) are random variables with random sign of the strength frac{W}{2}.

Parameters:

  • w (float) – Disorder amplitude for the random variables with random signs. The random number can only take two values, pm frac{W}{2}. Default is 0.

  • seed (int | None) – Seed to be used in the random number generation. Default is None, which result in the default Numpy seed.

  • on_site (bool) – Whether to apply same random disorder on orbitals located on the same physical site. Default is True.

Returns:

Array containing the random disorder values added to the Hamiltonian.

Return type:

np.ndarray

Warning

The current instance of the model will be modified.

add_disorder_uniform(w=0, on_site=True, seed=None)[source]#

Add on-site uniform Anderson disorder to the model. Anderson disorder consists in a diagonal term in the Hamiltonian \(\mathcal H_{Anderson}=\sum_i w^{}_i c_i^{\dagger}c^{}_i\) where \(w^{}_i\) are random variables uniformly distributed in the interval \(\bigl[-\frac{W}{2},\frac{W}{2} \bigr]\).

Parameters:

  • w (float) – Disorder amplitude, defining the extrema of the interval \(\bigl[-\frac{W}{2},\frac{W}{2} \bigr]\). Default is 0.

  • seed (int | None) – Seed to be used in the random number generation. Default is None, which result in the default Numpy seed.

  • on_site (bool) – Whether to apply same random disorder on orbitals located on the same physical site. Default is True.

Returns:

Array containing the random disorder values added to the Hamiltonian.

Return type:

np.ndarray

Warning

The current instance of the model will be modified.

add_vacancies(vacancies_list)[source]#

Add vacancies in the system by removing a site in the lattice.

Parameters:

vacancies_list (tuple | list) – A list of [cell_x, cell_y, basis] pointing to the cell and atom to be removed. Multiple values at once are allowed. For instance, consider a \(L_x\times L_y\) lattice with a basis of \(N_b\) atoms, and \(M\) sites to be removed. Then, the list [[np.random.randint(L_x), np.random.randint(L_y), np.random.randint(N_b)] for _ in range(M)] can be given as argument. See also utils.unique_vacancies() for a function that returns a list of unique vacancies.

Return type:

None

Note

If the model is not spinful, an even number of vacancies may be required for the system to be gapped.

Warning

The current instance of the model will be modified.

classmethod from_wannier90(seedname, path='.', engine='tbmodels', n_occ=None, **kwargs)[source]#

Create a Model instance from Wannier90 output files. The Wannier90 seedname (without extension) and the path to the files must be provided. The engine used to read the Wannier90 files can be specified via the engine argument, which can take values wannierberri, tbmodels or pythtb. The default is tbmodels.

Parameters:

  • seedname (str) – Wannier90 seedname.

  • path (str) – Path to the Wannier90 output files.

  • engine (str) – Engine used to read the Wannier90 files. Can be either wannierberri, tbmodels or pythtb. Default is tbmodels.

  • n_occ (int) – Number of occupied states. If None, the number of occupied states is read from the model, if available (half-filling is usually assumed). If the model does not contain information about the number of occupied states, a RuntimeError is raised and the number of occupied states must be provided as input here. This is the case in TBmodels for instance.

  • kwargs – Additional keyword arguments passed to the constructor of Model and to the WannierBerri’s System_w90 when engine is set to wannierberri.

Returns:

A Model instance generated from the Wannier90 output files.

Return type:

Model

make_finite(Lx, Ly, n_occ=None)[source]#

Create a finite system given of the current model by repeating the unit cell, allowing to compute single-point invariants and local geometrical and topological markers.

Parameters:

  • Lx (int) – Number of unit cells repeated along the \(\mathbf{a}_1\) direction in the supercell.

  • Ly (int) – Number of unit cells repeated along the \(\mathbf{a}_2\) direction in the supercell.

  • n_occ (int) – Number of occupied states. If None, this is rescaled from the currently stored value depending on the size of the supercell, otherwise it is overridden by the provided value.

Returns:

A FiniteModel instance generated from the current model.

Return type:

FiniteModel

make_heterostructure(model2, direction=0, start=0, stop=0)[source]#

Create a heterostructure starting from another model. The system will be split in the direction direction starting from the unit cell whose index is start and stopping at the cell indexed as end. The two models must have the same lattice parameters and lattice sites.

Parameters:

  • model2 (Model) – An instance of strawberrypy.Model representing the mdoel whose Hamiltonian has to be used when constructing the heterostructure.

  • direction (int) – Direction in which the splitting is realized, allowed values are 0 for the \(\mathbf{a}_1\) direction or 1 for the \(\mathbf{a}_2\) direction. Default is 0.

  • start (int) – Starting point for the splitting in the direction direction. Default is 0.

  • end – End point of the splitting in the direction direction. Default is 0.

  • stop (int)

Return type:

None

Warning

The current instance of the model will be modified.

make_supercell(Lx, Ly, n_occ=None)[source]#

Create a supercell given of the current model by repeating the unit cell, allowing to compute single-point invariants and local geometrical and topological markers.

Parameters:

  • Lx (int) – Number of unit cells repeated along the \(\mathbf{a}_1\) direction in the supercell.

  • Ly (int) – Number of unit cells repeated along the \(\mathbf{a}_2\) direction in the supercell.

  • n_occ (int) – Number of occupied states. If None, this is rescaled from the currently stored value depending on the size of the supercell, otherwise it is overridden by the provided value.

Returns:

A Supercell instance generated from the current model.

Return type:

Supercell

Finite model subclass#

FiniteModel

A class describing a finite (OBC) model.

FiniteModel.local_chern_marker

Evaluate the local Chern marker provided in Ref. Bianco-Resta (2011).

FiniteModel.local_spin_chern_marker

Evaluate the local spin-Chern marker provided in Ref. Baù-Marrazzo (2024b).

FiniteModel.local_z2_marker

FiniteModel.localization_marker

Evaluate the localization marker provided in Ref. Marrazzo-Resta (2019).
class strawberrypy.finite_model.FiniteModel(model, Lx=1, Ly=1, n_occ=None, **kwargs)[source]#

Bases: Model

A class describing a finite (OBC) model.

Create a finite model of a given strawberrypy.Model, allowing the calculation of local geometrical and topological markers within open boundary conditions.

Parameters:

  • model (Model) – A strawberrypy.Model instance.

  • Lx (int) – Number of unit cells repeated along the \(\mathbf{a}_1\) direction in the finite sample.

  • Ly (int) – Number of unit cells repeated along the \(\mathbf{a}_1\) direction in the finite sample.

  • n_occ (int) – Number of occupied states. If None, this is determined based on the original model.

  • kwargs – Additional keyword arguments of the parent class Model.

local_chern_marker(direction=None, start=0, return_projector=False, input_projector=None, macroscopic_average=False, cutoff=0.8, bare_marker=False, smearing_temperature=0.0, fermidirac_cutoff=0.1, n_tba=0)[source]#

Evaluate the local Chern marker provided in Ref. Bianco-Resta (2011). This can be evaluated on the whole lattice if direction == None or along direction starting from start, where directions can be 0 (\(\mathbf{a}_1\) direction), or 1 (\(\mathbf{a}_2\) direction).

Parameters:

  • direction (int) – Direction along which the local Chern marker is computed. Default is None (returns the marker on the whole lattice). Allowed directions are 0 (\(\mathbf{a}_1\) direction), and 1 (\(\mathbf{a}_2\) direction).

  • start (int) – If direction is not None, indicates the coordinate of the unit cell from which the evaluation of the local Chern marker starts. For instance, if interested on the value of the local marker along the \(\mathbf{a}_1\) direction at half height, it should be set direction = 0 and start = Ly // 2.

  • return_projector (bool) – If True, returns the ground state projector. Default is False.

  • input_projector (ndarray) – Possibility to provide the ground state projector to be used in the calculation as input. Default is None, which means that the ground state projector is computed from the model.

  • macroscopic_average (bool) – If True, returns the local Chern marker averaged in real space over a radius equal to cutoff. Default is False.

  • cutoff (float) – Cutoff set for the calculation of the macroscopic average in real space of the local Chern marker.

  • bare_marker (bool) – If True returns the bare local Chern marker, without taking local trace and averaging. Default is False.

  • smearing_temperature (float) – Set a fictitious temperature \(T_s\) to be used when weighting the eigenstates of the Hamiltonian comprising the ground state projector. In particular, the ground state projector is computed as \(\mathcal P=\sum_{n}f(\epsilon_n, T_s, \mu)|u_n\rangle\langle u_n|\) where \(f(\epsilon_n, T_s, \mu)\) is the Fermi-Dirac distribution, \(\mu\) is the chemical potential and \(\mathcal{H} |u_n\rangle=\epsilon_n|u_n\rangle\). Introducing some smearing is particularly useful when dealing with heterojunctions or inhomogeneous models whose insulating gap is small in order to improve the convergence of the local marker. Default is 0, so that no smearing is introduced.

  • fermidirac_cutoff (float) – Cutoff imposed on the Fermi-Dirac distribution to further improve the convergence, mostly when \(T_s\neq0\). Default is 0.1, which is appropriate in most cases.

  • n_tba (int) – Number of states to be added relative to the a priori set filling (defined by the n_occ parameter or the default half-filling) when applying smearing.

Returns:

  • lattice_chern – Local Chern marker evaluated on the whole lattice if direction == None.

  • lcm_direction – Local Chern marker evaluated along direction starting from start.

  • gs_projector – Ground state projector, returned if return_projector == True.

  • local_c – The bare local Chern marker \(C(\mathbf{r})\) returned without averaging if bare_marker == True.

local_spin_chern_marker(direction=None, start=0, return_projector=None, input_projector=None, macroscopic_average=False, cutoff=0.8, bare_marker=False, smearing_temperature=0, fermidirac_cutoff=0.1, n_tba=0)[source]#

Evaluate the local spin-Chern marker provided in Ref. Baù-Marrazzo (2024b). This can be evaluated on the whole lattice if direction == None or along direction starting from start, where directions can be 0 (\(\mathbf{a}_1\) direction), or 1 (\(\mathbf{a}_2\) direction).

Parameters:

  • direction (int) – Direction along which the local spin-Chern marker is computed. Default is None (returns the marker on the whole lattice). Allowed directions are 0 (\(\mathbf{a}_1\) direction), and 1 (\(\mathbf{a}_2\) direction).

  • start (int) – If direction is not None, indicates the coordinate of the unit cell from which the evaluation of the local spin-Chern marker starts. For instance, if interested on the value of the local marker along the \(\mathbf{a}_1\) direction at half height, it should be set direction = 0 and start = Ly // 2.

  • return_projector (bool) – If True, returns the list of projectors \([\mathcal P_+, \mathcal P_-]\) used in the calculation. Default is False.

  • input_projector – Possibility to provide the list of projectors \([\mathcal P_+, \mathcal P_-]\) to be used in the calculation as input. Default is None, which means that they are computed from the model.

  • macroscopic_average (bool) – If True, returns the local spin-Chern marker averaged in real space over a radius equal to cutoff. Default is False.

  • cutoff (float) – Cutoff set for the calculation of the macroscopic average in real space of the local spin-Chern marker.

  • bare_marker (bool) – If True returns the bare local individual Chern markers, without taking local trace and averaging. Default is False.

  • smearing_temperature (float) – Set a fictitious temperature \(T_s\) to be used when weighting the eigenstates of \(\mathcal PS_z\mathcal P\) comprising the projectors \(\mathcal P_{\pm}\). In particular, the projectors \(\mathcal P_{\pm}\) are computed as \(\mathcal P_{\pm}=\sum_{m:\sigma=\pm}c_m^{\sigma}(T_s) |\phi_m^{\sigma}\rangle\langle \phi_m^{\sigma}|\) where \(|\phi_m^{\sigma}\rangle\) are the eigenstates of \(\mathcal PS_z\mathcal P\) with eigenvalue \(\lambda_m^{\sigma}\) whose sign is \(\sigma=\pm\). Introducing some smearing is particularly useful when dealing with heterojunctions or inhomogeneous models whose insulating gap is small in order to improve the convergence of the local marker. Default is 0, so that no smearing is introduced.

  • fermidirac_cutoff (float) – Cutoff imposed on the Fermi-Dirac distribution to further improve the convergence, mostly when \(T_s\neq0\). Default is 0.1, which is appropriate in most cases.

  • n_tba (int) – Number of states to be added relative to the a priori set filling (defined by the n_occ parameter or the default half-filling) when applying smearing.

Returns:

  • lattice_lscm – Local spin-Chern marker evaluated on the whole lattice if direction == None.

  • lscm_direction – Local spin-Chern marker evaluated along direction starting from start.

  • gs_projector – The list of projectors \([\mathcal P_+, \mathcal P_-]\), returned if return_projector == True.

  • local_cp, local_cm – The list of bare local individual Chern markers [\(C_+(\mathbf{r})\), \(C_-(\mathbf{r})\)], returned if bare_marker == True.

local_z2_marker(direction=None, start=0, return_projector=None, input_projector=None, macroscopic_average=False, cutoff=0.8, bare_marker=False, smearing_temperature=0, fermidirac_cutoff=0.1, trial_projections=None, n_tba=0)[source]#

Evaluate the local \(\mathbb{Z}_2\) marker provided in Ref. Baù-Marrazzo (2024b). This can be evaluated on the whole lattice if direction == None or along direction starting from start, where directions can be 0 (\(\mathbf{a}_1\) direction), or 1 (\(\mathbf{a}_2\) direction).

Parameters:

  • direction (int) – Direction along which the local \(\mathbb{Z}_2\) marker is computed. Default is None (returns the marker on the whole lattice). Allowed directions are 0 (\(\mathbf{a}_1\) direction), and 1 (\(\mathbf{a}_2\) direction).

  • start (int) – If direction is not None, indicates the coordinate of the unit cell from which the evaluation of the local \(\mathbb{Z}_2\) marker starts. For instance, if interested on the value of the local marker along the \(\mathbf{a}_1\) direction at half height, it should be set direction = 0 and start = Ly // 2.

  • return_projector (bool) – If True, returns the list of projectors \([\mathcal P_1, \Theta\mathcal P_1\Theta^{-1}]\) used in the calculation, where \(\Theta\) is the time reversa operator. Default is False.

  • input_projector – Possibility to provide the list of projectors \([\mathcal P_1, \Theta\mathcal P_1\Theta^{-1}]\) to be used in the calculation as input. Default is None, which means that they are computed from the model.

  • macroscopic_average (bool) – If True, returns the local \(\mathbb{Z}_2\) marker averaged in real space over a radius equal to cutoff. Default is False.

  • cutoff (float) – Cutoff set for the calculation of the macroscopic average in real space of the local \(\mathbb{Z}_2\) marker.

  • bare_marker (bool) – If True returns the bare local individual Chern markers, without taking local trace and averaging. Default is False.

  • smearing_temperature (float) – Set a fictitious temperature \(T_s\) to be used when weighting the quasi Wannier functions comprising the projector \(\mathcal P_{1}\). In particular, the projector \(\mathcal P_{1}\) is computed as \(\mathcal P_{1}=\sum_{m}c_m(T_s)|w_m\rangle\langle w_m|\) where \(|w_m\rangle\) are the quasi-Wannier functions. These are obtained minimizing the spillage between \(\mathcal P=\sum_n f(\epsilon_n, T_s, \mu)|u_n\rangle\langle u_n|\) and \(\mathcal P_{\Theta}=\mathcal P_1+\Theta\mathcal P_1\Theta^{-1}\), where \(|u_n\rangle\) is the periodic part of the n-th Bloch function and \(f(\epsilon, T, \mu)\) is the Fermi-Dirac distribution. Introducing some smearing is particularly useful when dealing with heterojunctions or inhomogeneous models whose insulating gap is small in order to improve the convergence of the local marker. Default is 0, so that no smearing is introduced.

  • fermidirac_cutoff (float) – Cutoff imposed on the Fermi-Dirac distribution to further improve the convergence, mostly when \(T_s\neq0\). Default is 0.1, which is appropriate in most cases.

  • trial_projections – The \(N\times N\) matrix of trial projections to be used when computing the quasi-Wannier functions, where \(N\) is the number of states per primitive cell. Default is None, meaning a default choice projecting on spin-up and spin-down states is employed.

  • n_tba (int) – Number of states to be added relative to the a priori set filling (defined by the n_occ parameter or the default half-filling) when applying smearing.

Returns:

  • lattice_lz2m – Local \(\mathbb{Z}_2\) marker evaluated on the whole lattice if direction == None.

  • lz2m_direction – Local \(\mathbb{Z}_2\) marker evaluated along direction starting from start.

  • gs_projector – The list of projectors \([\mathcal P_1, \Theta\mathcal P_1\Theta^{-1}]\), returned if return_projector == True.

  • local_c1, local_c2 – The bare local individual Chern markers \(C_1(\mathbf{r})\) and \(C_2(\mathbf{r})\), returned if bare_marker == True.

localization_marker(direction=None, start=0, return_projector=None, input_projector=None, macroscopic_average=False, cutoff=0.8, bare_marker=False, n_tba=0)[source]#

Evaluate the localization marker provided in Ref. Marrazzo-Resta (2019). This can be evaluated on the whole lattice if direction == None or along direction starting from start, where directions can be 0 (\(\mathbf{a}_1\) direction), or 1 (\(\mathbf{a}_2\) direction).

Parameters:

  • direction (int) – Direction along which the localization marker is computed. Default is None (returns the marker on the whole lattice). Allowed directions are 0 (\(\mathbf{a}_1\) direction), and 1 (\(\mathbf{a}_2\) direction).

  • start (int) – If direction is not None, indicates the coordinate of the unit cell from which the evaluation of the localization marker starts. For instance, if interested on the value of the local marker along the \(\mathbf{a}_1\) direction at half height, it should be set direction = 0 and start = Ly // 2.

  • return_projector (bool) – If True, returns the ground state projector. Default is False.

  • input_projector (ndarray) – Possibility to provide the ground state projector to be used in the calculation as input. Default is None, which means that the ground state projector is computed from the model.

  • macroscopic_average (bool) – If True, returns the localization marker averaged in real space over a radius equal to cutoff. Default is False.

  • cutoff (float) – Cutoff set for the calculation of the macroscopic average in real space of the localization marker.

  • bare_marker (bool) – If True returns the bare localization marker, without taking local trace and averaging. Default is False.

  • n_tba (int) – Number of states to be added relative to the a priori set filling (defined by the n_occ parameter or the default half-filling).

Returns:

  • lattice_loc – Localization marker evaluated on the whole lattice if direction == None.

  • loc_direction – Localization marker evaluated along direction starting from start.

  • gs_projector – Ground state projector, returned if return_projector == True.

Note

This function is implemented only for TBmodels and PythTB up to now.

Supercell model subclass#

Supercell

A class describing a supercell (PBC) of a given model.

Supercell.pbc_local_chern_marker

Evaluate the PBC local Chern marker provided in Ref. Baù-Marrazzo (2024a).

Supercell.pbc_local_spin_chern_marker

Supercell.pbc_local_z2_marker

Supercell.single_point_chern

Evaluate the single-point Chern number provided in Ref.Ceresoli-Resta (2007).

Supercell.single_point_spin_chern

Evaluate the single-point spin Chern number derived in Ref. Favata-Marrazzo (2023).
class strawberrypy.supercell.Supercell(model, Lx=1, Ly=1, n_occ=None, **kwargs)[source]#

Bases: Model

A class describing a supercell (PBC) of a given model.

Create a supercell of a given strawberrypy.Model, allowing the calculation of single-point invariants and local geometrical and topological markers within periodic boundary conditions.

Parameters:

  • model (Model) – A strawberrypy.Model instance.

  • Lx (int) – Number of unit cells repeated along the \(\mathbf{a}_1\) direction in the supercell.

  • Ly (int) – Number of unit cells repeated along the \(\mathbf{a}_2\) direction in the supercell.

  • n_occ (int) – Number of occupied states. If None, this is determined based on the original model.

  • kwargs – Additional keyword arguments of the parent class Model.

pbc_local_chern_marker(direction=None, start=0, return_projector=False, input_projector=None, formula='symmetric', macroscopic_average=False, cutoff=0.8, bare_marker=False, smearing_temperature=0, fermidirac_cutoff=0.1, n_tba=0, until_gap=False, gap_tol=1e-08)[source]#

Evaluate the PBC local Chern marker provided in Ref. Baù-Marrazzo (2024a). This can be evaluated on the whole lattice if direction == None or along direction starting from start, where directions can be 0 (\(\mathbf{a}_1\) direction), or 1 (\(\mathbf{a}_2\) direction).

Parameters:

  • direction (int) – Direction along which to compute the PBC local Chern marker. Default is None (returns the marker on the whole supercell). Allowed directions are 0 (\(\mathbf{a}_1\) direction), and 1 (\(\mathbf{a}_2\) direction).

  • start (int) – If direction is not None, is the coordinate of the unit cell from which the evaluation of the PBC local Chern marker starts. For instance, if interested on the value of the PBC local marker along the \(\mathbf{a}_1\) direction at half height, it should be set direction = 0 and start = Ly // 2.

  • return_projector (bool) – If True, returns the ground state projector at the end of the calculation. Default is False.

  • input_projector – Input the list of projectors \([\mathcal{P}_{\mathbf{b}_1}, \mathcal{P}_{\mathbf{b}_2},\mathcal{P}_{\Gamma}]\) (or \([\mathcal{P}_{\mathbf{b}_1}, \mathcal{P}_{\mathbf{b}_2},\mathcal{P}_{-\mathbf{b}_1},\mathcal{P}_{-\mathbf{b}_2}, \mathcal{P}_{\Gamma}]\) if formula == 'symmetric') to be used in the calculation. Default is None, which means that it is computed from the model.

  • formula (str) – Formula to be used. Default is 'symmetric', which is computationally more demanding but converges faster. Any other input will result in the 'asymmetric' formulation.

  • macroscopic_average (bool) – If True, returns the PBC local Chern marker averaged in real space over a radius equal to cutoff. Default is False.

  • cutoff (float) – Cutoff set for the calculation of the macroscopic average in real space of the PBC local Chern marker.

  • bare_marker (bool) – If True returns the bare PBC local Chern marker, without taking local trace and averaging. Default is False.

  • smearing_temperature (float) – Set a fictitious temperature \(T_s\) to be used when weighting the eigenstates of the Hamiltonian comprising the ground state projector. In particular, the ground state projector is computed as \(\mathcal P=\sum_{n}f(\epsilon_n, T_s, \mu)|u_n\rangle\langle u_n|\) where \(f(\epsilon_n, T_s, \mu)\) is the Fermi-Dirac distribution, \(\mu\) is the chemical potential and \(\mathcal{H}_{\Gamma}|u_n\rangle=\epsilon_n |u_n\rangle\). Introducing some smearing is particularly useful when dealing with heterojunctions o inhomogeneous models whose insulating gap is small in order to improve the convergence of the local marker. Default is 0, so no smearing is introduced.

  • fermidirac_cutoff (float) – Cutoff imposed on the Fermi-Dirac distribution to further improve the convergence, mostly when \(T_s\neq0\). Default is 0.1, which is appropriate in most cases.

  • n_tba (int) – Number of states to be added relative to the a priori set filling (defined by the n_occ parameter or the default half-filling) when applying smearing.

  • until_gap (bool) – If True, the minimum number of states in order to have an energy gap larger than gap_tol is added to n_occ in the calculation of the marker. Default is False.

  • gap_tol (float) – Minimum value of the gap when adding states to n_occ in the calculation of the marker if until_gap == True. Default is python:1e-8.

Returns:

  • lattice_chern – PBC local Chern marker evaluated on the whole lattice if direction == None.

  • lcm_direction – PBC local Chern marker evaluated along direction starting from start.

  • return_proj – List of projectors \([\mathcal{P}_{\mathbf{b}_1},\mathcal{P}_{\mathbf{b}_2}, \mathcal{P}_{\Gamma}]\) (or \([\mathcal{P}_{\mathbf{b}_1}, \mathcal{P}_{\mathbf{b}_2},\mathcal{P}_{-\mathbf{b}_1}, \mathcal{P}_{-\mathbf{b}_2}, \mathcal{P}_{\Gamma}]\) if formula == 'symmetric') used in the calculation if return_projector == True.

  • local_c – The bare PBC local Chern marker \(C(\mathbf{r})\) not averaged, returned if bare_marker == True.

pbc_local_spin_chern_marker(direction=None, start=0, return_projector=False, input_projector=None, formula='symmetric', macroscopic_average=False, cutoff=0.8, bare_marker=False, smearing_temperature=0, fermidirac_cutoff=0.1, n_tba=0, until_gap=False, gap_tol=1e-08)[source]#

Evaluate the PBC local spin-Chern marker provided in Ref. Baù-Marrazzo (2024b). This can be evaluated on the whole lattice if direction == None or along direction starting from start, where directions can be 0 (\(\mathbf{a}_1\) direction), or 1 (\(\mathbf{a}_2\) direction).

Parameters:

  • direction (int) – Direction along which to compute the PBC local spin-Chern marker. Default is None (returns the marker on the whole supercell). Allowed directions are 0 (\(\mathbf{a}_1\) direction), and 1 (\(\mathbf{a}_2\) direction).

  • start (int) – If direction is not None, is the coordinate of the unit cell from which the evaluation of the PBC local spin-Chern marker starts. For instance, if interested on the value of the PBC local marker along the \(\mathbf{a}_1\) direction at half height, it should be set direction = 0 and start = Ly // 2.

  • return_projector (bool) – If True, returns the projectors \(\mathcal P_{\mathbf b_{1,2}}^{\pm}\) at the end of the calculation. Default is False.

  • input_projector – List of projectors \([\mathcal{P}_{\mathbf{b}_1}^-,\mathcal{P}_{\mathbf{b}_2}^-, \mathcal{P}_{\mathbf{b}_1}^+,\mathcal{P}_{\mathbf{b}_2}^+,\mathcal{P}_{\Gamma}^-, \mathcal{P}_{\Gamma}^+]\) (or \([\mathcal{P}_{\mathbf{b}_1}^-, \mathcal{P}_{\mathbf{b}_2}^-,\mathcal{P}_{\mathbf{b}_1}^+,\mathcal{P}_{\mathbf{b}_2}^+, \mathcal{P}_{-\mathbf{b}_1}^-,\mathcal{P}_{-\mathbf{b}_2}^-,\mathcal{P}_{-\mathbf{b}_1}^+, \mathcal{P}_{-\mathbf{b}_2}^+,\mathcal{P}_{\Gamma}^-,\mathcal{P}_{\Gamma}^+]\) if formula == 'symmetric') to be used in the calculation. Default is None, which means that it is computed from the model.

  • formula (str) – Formula to be used. Default is 'symmetric', which is computationally more demanding but converges faster. Any other input will result in the 'asymmetric' formulation.

  • macroscopic_average (bool) – If True, returns the PBC local spin-Chern marker averaged in real space over a radius equal to cutoff. Default is False.

  • cutoff (float) – Cutoff set for the calculation of the macroscopic average in real space of the PBC local spin-Chern marker.

  • bare_marker (bool) – If True returns the bare PBC local individual Chern markers, without taking local trace and averaging. Default is False.

  • smearing_temperature (float) – Set a fictitious temperature \(T_s\) to be used when weighting the eigenstates of \(\mathcal PS_z\mathcal P\) comprising the projectors \(\mathcal P_{\pm}\). In particular, the projectors \(\mathcal P_{\pm}\) are computed as \(\mathcal P_{\pm}=\sum_{m:\sigma=\pm}c_m^{\sigma}(T_s) |\phi_m^{\sigma}\rangle\langle \phi_m^{\sigma}|\) where \(|\phi_m^{\sigma}\rangle\) are the eigenstates of \(\mathcal PS_z\mathcal P\) with eigenvalue \(\lambda_m^{\sigma}\) whose sign is \(\sigma=\pm\). Introducing some smearing is particularly useful when dealing with heterojunctions or inhomogeneous models whose insulating gap is small in order to improve the convergence of the local marker. Default is 0, so that no smearing is introduced.

  • fermidirac_cutoff (float) – Cutoff imposed on the Fermi-Dirac distribution to further improve the convergence, mostly when \(T_s\neq0\). Default is 0.1, which is appropriate in most cases.

  • n_tba (int) – Number of states to be added relative to the a priori set filling (defined by the n_occ parameter or the default half-filling) when applying smearing.

  • until_gap (bool) – If True, the minimum number of states in order to have an energy gap larger than gap_tol is added to n_occ in the calculation of the marker. Default is False.

  • gap_tol (float) – Minimum value of the gap when adding states to n_occ in the calculation of the marker if until_gap == True. Default is 1e-8.

Returns:

  • lattice_spinchern – PBC local spin-Chern marker evaluated on the whole lattice if direction == None.

  • lscm_direction – PBC local spin-Chern marker evaluated along direction starting from start.

  • return_proj – List of projectors \([\mathcal{P}_{\mathbf{b}_1}^-,\mathcal{P}_{\mathbf{b}_2}^-, \mathcal{P}_{\mathbf{b}_1}^+,\mathcal{P}_{\mathbf{b}_2}^+,\mathcal{P}_{\Gamma}^-, \mathcal{P}_{\Gamma}^+]\) (or \([\mathcal{P}_{\mathbf{b}_1}^-,\mathcal{P}_{\mathbf{b}_2}^-, \mathcal{P}_{-\mathbf{b}_1}^-,\mathcal{P}_{-\mathbf{b}_2}^-,\mathcal{P}_{\mathbf{b}_1}^+, \mathcal{P}_{\mathbf{b}_2}^+,\mathcal{P}_{-\mathbf{b}_1}^+,\mathcal{P}_{-\mathbf{b}_2}^+, \mathcal{P}_{\Gamma}^-, \mathcal{P}_{\Gamma}^+]\) if formula == 'symmetric') used in the calculation if return_projector == True.

  • local_cp, local_cm – The list of bare PBC local individual Chern markers \(C_+(\mathbf{r})\) and \(C_-(\mathbf{r})\), returned if bare_marker == True.

pbc_local_z2_marker(direction=None, start=0, return_projector=False, input_projector=None, formula='symmetric', macroscopic_average=False, cutoff=0.8, bare_marker=False, smearing_temperature=0, fermidirac_cutoff=0.1, trial_projections=None)[source]#

Evaluate the local PBC \(\mathbb{Z}_2\) marker provided in Ref. Baù-Marrazzo (2024b). This can be evaluated on the whole lattice if direction == None or along direction starting from start, where directions can be 0 (\(\mathbf{a}_1\) direction), or 1 (\(\mathbf{a}_2\) direction).

Parameters:

  • direction (int) – Direction along which the local \(\mathbb{Z}_2\) marker is computed. Default is None (returns the marker on the whole lattice). Allowed directions are 0 (\(\mathbf{a}_1\) direction), and 1 (\(\mathbf{a}_2\) direction).

  • start (int) – If direction is not None, indicates the coordinate of the unit cell from which the evaluation of the local \(\mathbb{Z}_2\) marker starts. For instance, if interested on the value of the local marker along the \(\mathbf{a}_1\) direction at half height, it should be set direction = 0 and start = Ly // 2.

  • return_projector (bool) – If True, returns the list of projectors \([\mathcal{P}_{1,\Gamma}, \Theta\mathcal{P}_{1,\Gamma}\Theta^{-1}, \mathcal{P}_{1,\mathbf{b}_1}, \mathcal{P}_{1,\mathbf{b}_2}, \Theta\mathcal{P}_{1,\mathbf{b}_1}\Theta^{-1}, \Theta\mathcal{P}_{1,\mathbf{b}_2}\Theta^{-1}]\) (or \([\mathcal{P}_{1,\Gamma}, \Theta\mathcal{P}_{1,\Gamma}\Theta^{-1}, \mathcal{P}_{1,\mathbf{b}_1}, \mathcal{P}_{1,\mathbf{b}_2}, \Theta\mathcal{P}_{1,\mathbf{b}_1}\Theta^{-1}, \Theta\mathcal{P}_{1,\mathbf{b}_2}\Theta^{-1}, \mathcal{P}_{1,-\mathbf{b}_1}, \mathcal{P}_{1, -\mathbf{b}_2}, \Theta\mathcal{P}_{1, -\mathbf{b}_1}\Theta^{-1}, \Theta\mathcal{P}_{1, -\mathbf{b}_2}\Theta^{-1}]\) if formula == 'symmetric') used in the calculation, where \(\Theta\) is the time reversal operator. Default is False.

  • input_projector – List of projectors \([\mathcal{P}_{1,\Gamma}, \Theta\mathcal{P}_{1,\Gamma}\Theta^{-1}, \mathcal{P}_{1,\mathbf{b}_1}, \mathcal{P}_{1,\mathbf{b}_2}, \Theta\mathcal{P}_{1,\mathbf{b}_1}\Theta^{-1}, \Theta\mathcal{P}_{1,\mathbf{b}_2}\Theta^{-1}]\) (or \([\mathcal{P}_{1,\Gamma}, \Theta\mathcal{P}_{1,\Gamma}\Theta^{-1}, \mathcal{P}_{1,\mathbf{b}_1}, \mathcal{P}_{1,\mathbf{b}_2}, \Theta\mathcal{P}_{1,\mathbf{b}_1}\Theta^{-1}, \Theta\mathcal{P}_{1,\mathbf{b}_2}\Theta^{-1}, \mathcal{P}_{1,-\mathbf{b}_1}, \mathcal{P}_{1, -\mathbf{b}_2}, \Theta\mathcal{P}_{1, -\mathbf{b}_1}\Theta^{-1}, \Theta\mathcal{P}_{1, -\mathbf{b}_2}\Theta^{-1}]\) if formula == 'symmetric') to be used in the calculation. Default is None, which means that it is computed from the model.

  • formula (str) – Formula to be used. Default is 'symmetric', which is computationally more demanding but converges faster. Any other input will result in the 'asymmetric' formulation.

  • macroscopic_average (bool) – If True, returns the local \(\mathbb{Z}_2\) marker averaged in real space over a radius equal to cutoff. Default is False.

  • cutoff (float) – Cutoff set for the calculation of the macroscopic average in real space of the local \(\mathbb{Z}_2\) marker.

  • bare_marker (bool) – If True returns the bare PBC local individual Chern markers, without taking local trace and averaging. Default is False.

  • smearing_temperature (float) – Set a fictitious temperature \(T_s\) to be used when weighting the quasi Wannier functions comprising the projector \(\mathcal P_{1}\). In particular, the projector \(\mathcal P_{1}\) is computed as \(\mathcal P_{1}=\sum_{m}c_m(T_s)|w_m\rangle\langle w_m|\) where \(|w_m\rangle\) are the quasi Wannier functions. These are obtained minimizing the spillage between \(\mathcal P=\sum_n f(\epsilon_n, T_s, \mu) |u_n\rangle\langle u_n|\) and \(\mathcal P_{\Theta}=\mathcal P_1+\Theta\mathcal P_1\Theta^{-1}\), where \(|u_n\rangle\) is the periodic part of the n-th Bloch function and \(f(\epsilon, T, \mu)\) is the Fermi-Dirac distribution. Introducing some smearing is particularly useful when dealing with heterojunctions or inhomogeneous models whose insulating gap is small in order to improve the convergence of the local marker. Default is 0, so that no smearing is introduced.

  • fermidirac_cutoff (float) – Cutoff imposed on the Fermi-Dirac distribution to further improve the convergence, mostly when \(T_s\neq0\). Default is 0.1, which is appropriate in most cases.

  • trial_projections – The \(N\times N\) matrix of trial projections to be used when computing the quasi-Wannier functions, where \(N\) is the number of states per primitive cell. Default is None, meaning a default choice projecting on spin-up and spin-down states is employed.

Returns:

  • lattice_lz2m – Local \(\mathbb{Z}_2\) marker evaluated on the whole lattice if direction == None.

  • lz2m_direction – Local \(\mathbb{Z}_2\) marker evaluated along direction starting from start.

  • return_proj – The list of projectors \([\mathcal P_1, \Theta\mathcal P_1\Theta^{-1}]\), returned if return_projector == True.

  • local_c1, local_c2 – The bare PBC local individual Chern markers \(C_1(\mathbf{r})\) and \(C_2(\mathbf{r})\), returned if bare_marker == True.

Note

The local \(\mathbb{Z}_2\) marker does not currently support the until_gap and n_tba options as the other PBC local topological markers and it will updated in the future.

single_point_chern(formula='both', return_ham_gap=False)[source]#

Evaluate the single-point Chern number provided in Ref.Ceresoli-Resta (2007).

Parameters:

  • formula (str) – Two possible formulas are used for the calculation of the single-point Chern number: the 'asymmetric' one is the one originally derived in Ref. Ceresoli-Resta (2007) and uses right-hand discrete derivative; the 'symmetric' one uses symmetric derivative centered in \(\Gamma\)-point and converges faster to the exact value with the supercell size. Default value is 'both', which returns the invariants computed with both symmetric and asymmetric formulas.

  • return_ham_gap (bool) – If True, returns the value of the gap between the highest occupied and the lowest unoccupied eigenstates of the Hamiltonian at \(\Gamma\)-point. Default value is False.

Returns:

  • chern – Dictionary with results from 'asymmetric' and/or 'symmetric' formula for the single-point Chern number.

  • hamiltonian_gap – Gap between the lowest unoccupied and the highest occupied eigenstates of the Hamiltonian at \(\Gamma\)-point if return_ham_gap == True.

single_point_spin_chern(spin='down', formula='both', return_pszp_gap=False, return_ham_gap=False)[source]#

Evaluate the single-point spin Chern number derived in Ref. Favata-Marrazzo (2023).

Parameters:

  • spin (str) – Indicates which sector of the spin projected operator spectra is considered in the calculation of the single-point spin Chern number. If spin is 'up' ('down'), eigenstates of spin projected operator with positive (negative) eigevalues are considered. Default value is 'down'.

  • formula (str) – Two possible formulas are used for the calculation of the single-point spin Chern number: the 'asymmetric' one uses right-hand discrete derivative; the 'symmetric' one uses symmetric derivative centered in \(\Gamma\)-point and converges faster to the exact value with the supercell size. Default value is 'both', which returns the invariants computed with both symmetric and asymmetric formulas.

  • return_pszp_gap (bool) – If True, returns the value of the gap between positive and negative eigenvalues of the spin operator projected onto occupied states at \(\Gamma\)-point. Default value is False.

  • return_ham_gap (bool) – If True, returns the value of the gap between the lowest unoccupied and the highest occupied eigenstates of the Hamiltonian at \(\Gamma\)-point. Default value is False.

Returns:

  • spin_chern – Dictionary with results from 'asymmetric' and/or 'symmetric' formula for the single-point spin Chern number.

  • pszp_gap – Gap between positive and negative eigenvalues of the spin operator projected onto occupied states at \(\Gamma\)-point if return_pszp_gap == True.

  • hamiltonian_gap – Gap between the lowest unoccupied and the highest occupied eigenstates of the Hamiltonian at \(\Gamma\)-point if return_ham_gap == True.

 On this page