StraWBerryPy package#

Model class module#

class strawberrypy.classes.Model(tbmodel=None, spinful: bool = False, states_uc: int | None = None, Lx: int = 1, Ly: int = 1, file_spn: bool = False, n_occ: int | None = None)[source]#

Bases: object

Generic Model class from which Supercell and FiniteModel classes are constructed. Contains the functions which are needed to load spin, positions, Hamiltonian matrices, and other useful information.

Parameters:

  • tbmodel – Model instance.

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

  • states_uc – Number of states per unit cell (if the model is spinful, this should be twice the dimension of the basis). Default is None, which means it is computed from tbmodel.

  • Lx – Number of unit cells repeated along the \(\mathbf{a}_1\) direction. Default is 1.

  • Ly – Number of unit cells repeated along the \(\mathbf{a}_2\) direction. Default is 1.

  • file_spn – Whether the file .spn is provided if the model is obtained from Wannier functions generated by Wannier90 code starting from a \(\Gamma\)-only ab initio calculation. Default is False.

  • n_occ – Number of occupied states. This information is required only if the model is obtained from Wannier functions generated by Wannier90 code starting from a \(\Gamma\)-only ab initio calculation. Otherwise, half-filling is automatically assumed.

Warning

This class should not be called explicitly by the user since it is already called from both Supercell and FiniteModel upon creation.

add_onsite_disorder(w: float = 0, seed: int | None = None)[source]#

Add on-site 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 – Disorder amplitude, defining the extrema of the interval \(\bigl[-\frac{W}{2},\frac{W}{2} \bigr]\). Default is 0.

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

add_vacancies(vacancies_list)[source]#

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

Parameters:

vacancies_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.

Note

In order to enforce half-filling, if the model is not spinful, an even number of vacancies is required.

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

Create a heterostructure starting from model2. 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.

Parameters:

  • model2 – The model whose Hamiltonian has to be used when constructing the heterostructure.

  • direction – 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 – 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.

Warning

The current instance of the model will be modified.

Finite model class module#

class strawberrypy.finite_model.FiniteModel(tbmodel, Lx: int = 1, Ly: int = 1, spinful: bool = False)[source]#

Bases: Model

A class describing a finite (OBC) model built from either TBmodels or PythTB instances. It contains methods to add disorder and vacancies to the finite model, calculate local topological markers and the localization marker.

Parameters:

  • tbmodel – Tight-binding model constructed from TBmodels or PythTB.

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

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

  • spinful – Whether the model should be interpreted as spinful or not. Default is False.

local_chern_marker(direction: int | None = None, start: int = 0, return_projector: bool = False, input_projector: ndarray | None = None, macroscopic_average: bool = False, cutoff: float = 0.8, smearing_temperature: float = 0.0, fermidirac_cutoff: float = 0.1)[source]#

Evaluate the local Chern marker provided in Ref. Bianco-Resta (2011) on the whole lattice if direction == None. If :python:direction is not None, evaluate the local Chern marker along direction starting from start. Allowed directions are 0 (meaning along \(\mathbf{a}_1\)), and 1 (meaning along \(\mathbf{a}_2\)).

Parameters:

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

  • start – 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 – If True, returns the ground state projector. Default is False.

  • input_projector – 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 stored in the class.

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

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

  • smearing_temperature – 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}_{\mathbf{k}}|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 that no smearing is introduced and a half-filled model is assumed.

  • fermidirac_cutoff – 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.

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.

localization_marker(direction: int | None = None, start: int = 0, return_projector: bool | None = None, input_projector: ndarray | None = None, macroscopic_average: bool = False, cutoff: float = 0.8)[source]#

Evaluate the localization marker provided in Ref. Marrazzo-Resta (2019) on the whole lattice if direction == None. If direction is not None, evaluate the localization marker along direction starting from start. Allowed directions are 0 (meaning along \(\mathbf{a}_1\)), and 1 (meaning along \(\mathbf{a}_2\)).

Parameters:

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

  • start – 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 – If True, returns the ground state projector. Default is False.

  • input_projector – 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 stored in the class.

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

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

Returns:

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

  • loc_direction – Local Chern 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 class module#

class strawberrypy.supercell.Supercell(tbmodel, Lx: int, Ly: int, spinful: bool = False, file_spn: bool = False, n_occ: int | None = None)[source]#

Bases: Model

A class creating a supercell given a model built from either TBmodels or PythTB instances. It also can receive as input a model which is initialized as WannierBerri instance wannierberri.System_w90 from the Wannier functions generated by Wannier90 code starting from a \(\Gamma\)-only ab initio calculation. It contains methods to add disorder and vacancies to the supercell and to calculate single-point topological invariants and local topological markers.

Parameters:

  • tbmodel – Tight-binding model constructed from TBmodels or PythTB, or ab initio tight-binding model inizialized as wannierberri.System_w90 from WannierBerri.

  • Lx – Number of unit cells repeated along the \(\mathbf{a}_1\) direction in the supercell. In case of wannierberri.System_w90 instance, please set Lx = 1.

  • Ly – Number of unit cells repeated along the \(\mathbf{a}_2\) direction in the supercell. In case of wannierberri.System_w90 instance, please set Ly = 1.

  • spinful – Whether the model should be interpreted as spinful or not. Default is False.

  • file_spn – 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. Default is False.

  • n_occ – Number of occupied states. This information is required only if the model is obtained from Wannier functions generated by Wannier90 code starting from a \(\Gamma\)-only ab initio calculation. Otherwise, half-filling is automatically assumed.

pbc_local_chern_marker(direction: int | None = None, start: int = 0, return_projector: bool = False, input_projector=None, formula: str = 'symmetric', macroscopic_average: bool = False, cutoff: float = 0.8, smearing_temperature: float = 0, fermidirac_cutoff: float = 0.1)[source]#

Evaluate the local Chern marker provided in Ref. Baù-Marrazzo (2023) on the whole supercell if direction == None. If direction is not None evaluates the PBC local Chern marker along direction starting from start. Allowed directions are 0 (meaning along \(\mathbf{a}_1\)), and 1 (meaning along \(\mathbf{a}_2\)).

Parameters:

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

  • start – 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 – 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}_{\Gamma},\mathcal{P}_{\mathbf{b}_1},\mathcal{P}_{\mathbf{b}_2}]\) (or \([\mathcal{P}_{\Gamma},\mathcal{P}_{\mathbf{b}_1},\mathcal{P}_{\mathbf{b}_2},\mathcal{P}_{-\mathbf{b}_1},\mathcal{P}_{-\mathbf{b}_2}]\) if formula == 'symmetric') to be used in the calculation. Default is None, which means that it is computed from the model stored in the class.

  • formula – 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 – If True, returns the PBC local Chern marker averaged in real space over a radius equal to cutoff. Default is False.

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

  • smearing_temperature – 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}_{\mathbf{k}}|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 and a model half-filled is implied.

  • fermidirac_cutoff – 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.

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}_{\Gamma},\mathcal{P}_{\mathbf{b}_1},\mathcal{P}_{\mathbf{b}_2}]\) (or \([\mathcal{P}_{\Gamma},\mathcal{P}_{\mathbf{b}_1},\mathcal{P}_{\mathbf{b}_2},\mathcal{P}_{-\mathbf{b}_1},\mathcal{P}_{-\mathbf{b}_2}]\) if formula == 'symmetric') used in the calculation if return_projector == True.

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

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

Parameters:

  • formula – 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 – 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: str = 'down', formula: str = 'both', return_pszp_gap: bool = False, return_ham_gap: bool = False)[source]#

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

Parameters:

  • spin – 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 – 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 – 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 – 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.

Subpackages#