Tutorials#

General Tutorial#

This section provides an overview of the implemented Hamiltonians, unit cells, and Bravais lattices. It explains how they are built, what can be done with them, and which restrictions must be considered.

Hamiltonian

We currently allow for four different site types: The input variable site_type can be spinless_fermions, spinful_fermions, tJ and spins. In the following we provide an overview over the parameters defining the Hamiltonian for each site type.

Please note that depending on user feedback the specific form of the Hamiltonian may change during the beta release cycles. Specifically we may switch to a fully charge compensated version.

spinless fermions

\[{\cal H} = \sum_{j} \epsilon_{j} \hat{n}_j \; + \; \sum_{j, k} t^{}_{jk} \, \hat{c}^\dagger_j \hat{c}^{}_k \;+\; \sum_{j < k} U^{}_{jk} \, \left(\hat{n}^{}_j - 1/2 \right) \, \left(\hat{n}^{}_k - 1/2 \right) \;+\; \sum_{j < k} D^{}_{jk} \, \hat{c}^{}_j \hat{c}^{}_k \,+\, D^{*}_{jk} \, \hat{c}^{\dagger}_k \hat{c}^{\dagger}_j\; ,\]

where \(j, k\) are site indices and we define the site occupation \(\hat{n}_j = \hat{c}^\dagger_j \hat{c}^{}_j\) . The first term corresponds to the energy cost of putting an electron on site \(j\) , the second term denotes the energy associated with an electron hopping from site \(j\) to site \(k\) and the third terms represents the interaction energy for having an electron on site \(j\) and another electron on site \(k\). Finally, the fourth term corresponds to the anomalous pairing terms as in BCS theory.

spinful fermions

\[\begin{split}{\cal H} & = \sum_{j} \Big[ \epsilon_j \hat{n}_j - \vec{B}_j \cdot \hat{\vec{S}}_j \Big] \; + \; \sum_{j \sigma, k\tau} t_{j \sigma, k \tau} \,\hat{c}^\dagger_{j \sigma} \hat{c}^{}_{k \tau} \; + \; \sum_{j} U_{jj} \, \left(\hat{n}{}_{j \uparrow} - 1/2 \right) \, \left(\hat{n}{}_{j \downarrow} - 1/2 \right) \nonumber \\ & \phantom{=} {} \; + \; \sum_{j < k} \bigg[ U_{jk} \, \hat{n}^{}_j \hat{n}^{}_k \; - \; J_{z, jk} \hat{S}_{z, j} \hat{S}_{z, k} \; - \; \frac{1}{2} \Big( J_{jk} \hat{S}_{+, j} \hat{S}_{-, k} \; + \; J_{jk}^\star \hat{S}_{-, j} \hat{S}_{+, k} \Big) \bigg] \nonumber \\ & \phantom{=} {} %%\;+\; \sum_{jk} D^{\uparrow\downarrow}_{jk} \, \hat{c}^{}_{j \uparrow} \hat{c}^{}_{k \downarrow} \,+\, D^{\uparrow\downarrow*}_{jk} \, \hat{c}^{\dagger}_{k \downarrow} \hat{c}^{\dagger}_{j \uparrow} \;+\; \sum_{j<k,\sigma,\tau} D^{\sigma\tau}_{jk} \, \hat{c}^{}_{j \sigma} \hat{c}^{}_{k \tau} \,+\, D^{\sigma\tau*}_{jk} \, \hat{c}^{\dagger}_{k \sigma} \hat{c}^{\dagger}_{j \tau} \nonumber \;,\end{split}\]

where \(\sigma, \tau\) are spin indices running over \(\uparrow, \downarrow\) and the on-site occupation is given by \(\hat{n}_j = \hat{n}_{j \uparrow} + \hat{n}_{j \downarrow}\). Similarly, the local spin magnetization is define by

\[\begin{split}\hat{\vec{S}}_j = \frac{1}{2} \begin{pmatrix} \hat{c}^\dagger_{j \uparrow} & \hat{c}^\dagger_{j \downarrow} \end{pmatrix} \cdot \vec{\sigma} \cdot \begin{pmatrix} \hat{c}^{}_{j \uparrow} \\ \hat{c}^{}_{j \downarrow} \end{pmatrix} \;,\end{split}\]

with \(\vec{\sigma}\) being the vector composed of the Pauli matrices. Note the explicit minus sign in front of the Zeeman coupling. This implies that the spin magnetization prefers to align (as oposed to to anti-align) with the external magnetic field \(\vec{B}\). The spin raising and lowering operators are defined as \(S_{+, j} = S_{x, j} + i S_{y, j}\) and \(S_{-, j} = S_{x, j} - i S_{y, j}\), respectively. The spin-dependent inter-site interaction is specified in terms of \(J_{z, jk}\) and the complex-valued \(J_{jk} = J_{\perp, jk} + i J_{\times, jk}\). Accordingly, it can also be written as

\[\begin{split}& \sum_{j < k} \bigg[ J_{z, jk} \hat{S}_{z, j} \hat{S}_{z, k} \; + \; \frac{1}{2} \Big( J_{jk} \hat{S}_{+, j} \hat{S}_{-, k} \; + \; J_{jk}^\star \hat{S}_{-, j} \hat{S}_{+, k} \Big) \bigg] \nonumber \\ = & \sum_{j < k} \bigg[ J_{z, jk} \hat{S}_{z, j} \hat{S}_{z, k} \; + \; J_{\perp, jk} \Big(\hat{S}_{x, j} \hat{S}_{x, k} \; + \; \hat{S}_{y, j} \hat{S}_{y, k} \Big) \; + \; J_{\times, jk} \boldsymbol{e}_z \cdot \Big( \hat{\boldsymbol{S}}_j \times \hat{\boldsymbol{S}}_k \Big) \bigg] \; ,\end{split}\]

which highlights that \(\mathrm{Re}[J_{jk}] = J_{\perp, jk}\) encodes anisotropy and \(\mathrm{Im}[J_{jk}] = J_{\times, jk}\) represents a Dzyaloshinskii-Moriya interaction. The explicit minus sign in front of the inter-site spin-spin interactions implies that for isotropic spin-spin interactions (\(J_{z, jk} = J_{\perp, jk}\) and \(J_{\times, jk} = 0\)) neighboring spins align.

NOTE: In the presence of transverse magnetic fields (\(B_x \neq 0\) and/or \(B_y \neq 0\)) \(S_z\) is no longer a good quantum number. In order to allow for states to break this symmetry please specify the input parameter mod_Sz to be non-zero. mod_Sz has to be a positive even integer. For example, mod_Sz: 2 allows eigenstates to be a superposition of states differing by single or multiple spin flips.

tJ-model

The tJ model corresponds to the \(U_{jj} \rightarrow \infty\) limit of the spinful model. In our implementation this is achieved by resticting the local space to empty and single occupied sites. In result the on-site interaction \(U_{jj}\) is ignored in the input, as there are no sites with double occupancy. There are no further changes with respect to the spinful fermions with double occupancy.

spins

\[{\cal H} & = {} - \sum_{i} \vec{B}_j \cdot \hat{\vec{S}}_j \; - \; \sum_{j < k} \bigg[ J_{z, jk} \hat{S}_{z, j} \hat{S}_{z, k} \; + \; J_{\perp, jk} \Big(\hat{S}_{x, j} \hat{S}_{x, k} \; + \; \hat{S}_{y, j} \hat{S}_{y, k} \Big) \; + \; J_{\times, jk} \boldsymbol{e}_z \cdot \Big( \hat{\boldsymbol{S}}_j \times \hat{\boldsymbol{S}}_k \Big) \bigg]\]

For the site type spins, the representation of the spin operators can be controlled using the spin_representation input variable. spin_representation has to be a positive integer \(n\). \(n\) determines the spin quantum number, \(s = n/2\).

Unitcell#

A unit cell is the smallest building block of a Bravais lattice. It is composed of atoms and bonds, which represent the physical system. The complete Bravais lattice is generated by repeating the unit cell along integer multiples of the lattice vectors.

Atoms

Atoms are specified by an ID (which must be unique), a name (e.g. 'C' or 'H'), and a position. Furthermore, atoms are characterized by an on-site energy and and on-site interaction.

The parameters of an atom:

ID: Must be unique
Name: Name of the atom, which can be chosen freely and can be repeated
Position: Location of the atom in Cartesian coordinates
On-site Energy (e): Energy associated with creating one electron at this site
On-site Interaction (U): "Hubbard U", i.e. the interaction energy between electrons on the same site (only relevant for spinful fermions - note that the default is spinless electrons)
On-site BCS pairing (D): The on-site BCS pairing

# code not executable
atoms:
    - ['0','Na',[ 0.0, 0.0, 0], 0, 0]
    - ['1','Cl',[ 0.5, 0.5, 0], 0, 0]
#       ^   ^          ^        ^  ^
#      ID  Name     Position    E  U

Spin-dependent on-site energy

WARNING: spin-dependent input is an experimental feature and currently only allowed for system_size = [1, 1, 1]!

For spinful electrons the on-site energy can be spin-dependent. For spins an external magnetic field can be applied to each site.

Possible inputs for on-site energy:

e: spin-independent on-site energy.
[eup, edown]: spin-dependent on-site energy.
[e, Bx, By, Bz]: on-site energy depends on the site occupation, coupled to the local potential \(e\), and the on-site spin magnetization, coupled to the on-site magnetic field \(\vec{B} = \begin{pmatrix} B_x & B_y & B_z \end{pmatrix}\).

For spinful electrons the input [eup, edown] is equivalent to the input [1/2(eup + edown), 0, 0, edown - eup]. For spins the value of the on-site potential \(e\) is ignored.

Note: The on-site interaction for spinful electrons is a single real number.

Lattice Vectors

Lattice vectors describe the translation of a unit cell in space. A cluster (see below) is also translated by the same lattice vectors.

Lattice vectors for a 2D square lattice:

# code not executable
lattice_vectors: [ [1, 0, 0], [0, 1, 0], [0, 0, 0]]
#                      ^          ^          ^
#                     # 1        # 2        # 3

Lattice vectors are not unique; there are several sets of lattice vectors which generate the same Bravais lattice.

For example, a 2D square lattice can also be generated by the following lattice vectors:

# code not executable
lattice_vectors: [ [-1, 0, 0], [0, -1, 0], [0, 0, 0]]

Bonds

Bonds describe connections between atoms, either within a unit cell or between unit cells. Bonds are defined by the ID of the two atoms they connect. Each bond has a single-particle hopping energy (t) and an interaction energy (U) associated with it. For spinless fermions we also allow for an anomalous pairing (D) on a bond.

The parameters of a bond:

Atom ID From: ID of the first atom.
Atom ID To: ID of the second atom.
reduced coordinates: Additional shift for the second atom by integer multiples of the lattice vectors.
Hopping terms (t): Energy cost associated with moving one electron along the bond.
Interaction terms (U): Energy cost of having one electron each on the atoms connected by the bond.
Anomalous paring (D): the anomalos BCS like paring on a bond.

In order to define bonds between unit cells, it is not enough to specify the IDs of the two connected atoms. Therefore, in addition to the IDs of the connected atoms, we also must provide the so-called "reduced_coordinates", a list of three integers which define the number of lattice vectors by which the second atom is displaced from its original position in the elementary unit cell. If the bond is inside the unit cell, the reduced coordinates are simply "[0,0,0]". Below is a concrete example:

NaCl lattice with unit cell and reduced coordinates#

Similar to lattice vectors, the bonds between unit cells are not unique. For example, we can generate an equivalent unit cell using the following bonds:

# code not executable
bonds:
    - ['0', '1', [ 0, 0, 0], -1.0,   1]
    - ['0', '0', [ 1, 0, 0], -0.2, 0.5]
    - ['0', '0', [ 0, 1, 0], -0.2, 0.5]
    - ['1', '0', [ 0, 1, 0], -0.2, 0.5]
    - ['1', '0', [ 1, 0, 0], -0.2, 0.5]
    - ['1', '0', [ 1, 1, 0], -0.2, 0.5]
#       ^    ^        ^        ^    ^
#       ID   ID    reduced     t    U
#      From  To     coords

# code not executable
bonds:
    - ['0', '1', [ 0, 0, 0], -1.0,   1]
    - ['0', '0', [ 1, 0, 0], -0.2, 0.5]
    - ['0', '0', [ 0, 1, 0], -0.2, 0.5]
    - ['0', '1', [ 0,-1, 0], -0.2, 0.5]
    - ['0', '1', [-1, 0, 0], -0.2, 0.5]
    - ['0', '1', [-1,-1, 0], -0.2, 0.5]

Spin-dependent hopping

WARNING: spin-dependent input is an experimental feature and currently only allowed for system_size = [1, 1, 1]!

For spinful electrons the hopping terms can be spin-dependent. All four possible entries \(t_{\uparrow \uparrow}\), \(t_{\downarrow \downarrow}\), \(t_{\uparrow \downarrow}\) and \(t_{\downarrow \uparrow}\) can be complex (the hermitian conjugate terms in the Hamiltonian are automatically generated).

Possible inputs for hopping amplitude (t):

t: \(t_{\uparrow \uparrow}=t_{\downarrow \downarrow}=t\) and \(t_{\uparrow \downarrow}=t_{\downarrow \uparrow}=0\)
[t1, t2]: \(t_{\uparrow \uparrow}=t_1\), \(t_{\downarrow \downarrow}=t_2\) and \(t_{\uparrow \downarrow}=t_{\downarrow \uparrow}=0\)
[t1, t2, t3]: \(t_{\uparrow \uparrow}=t_1\), \(t_{\downarrow \downarrow}=t_2\) and \(t_{\uparrow \downarrow}=t_{\downarrow \uparrow}=t_3\)
[t1, t2, t3, t4]: \(t_{\uparrow \uparrow}=t_1\), \(t_{\downarrow \downarrow}=t_2\), \(t_{\uparrow \downarrow}=t_3\) and \(t_{\downarrow \uparrow}=t_4\)

Note: Every entry for t can be complex, which can be specified by tn = [Re tn, Im tn].

Spin-spin interactions

WARNING: spin-dependent input is currently only allowed for system_size = [1, 1, 1]!

For spinful electrons and spins we allow for a spin-dependent inter-site interaction.

In order to define a spin-spin inter-site interaction use [U, Jz, Jperp, Jcross] where U corresponds to the inter-site density-density interaction for spinful fermions (ignored for spins) and Jz, Jperp and Jcross determines the inter-site spin-sipn interactions.

Note: Unless specified, interactions are taken to be zero.

Anomalous pairing on a bond

WARNING: anomalous pairing input is currently only allowed for system_size = [1, 1, 1]!

For spinful electrons the anomalous pairing terms can be spin-dependent. All four possible entries \(D_{\uparrow \uparrow}\), \(D_{\downarrow \downarrow}\), \(D_{\uparrow \downarrow}\) and \(D_{\downarrow \uparrow}\) can be complex (the hermitian conjugate terms in the Hamiltonian are automatically generated). For spinless fermions only the first version possible.

Possible inputs for the anomalous pairing amplitude (D):

D: \(D_{\uparrow \uparrow}=D_{\downarrow \downarrow}=D\) and \(D_{\uparrow \downarrow}=D_{\downarrow \uparrow}=0\) (triplet pairing)
[D1, D2]: \(D_{\uparrow \uparrow}=D_1\), \(D_{\downarrow \downarrow}=D_2\) and \(D_{\uparrow \downarrow}=D_{\downarrow \uparrow}=0\)
[D1, D2, D3]: \(D_{\uparrow \uparrow}=D_1\), \(D_{\downarrow \downarrow}=D_2\) and \(D_{\uparrow \downarrow}=D_{\downarrow \uparrow}=D_3\)
[D1, D2, D3, D4]: \(D_{\uparrow \uparrow}=D_1\), \(D_{\downarrow \downarrow}=D_2\), \(D_{\uparrow \downarrow}=D_3\) and \(D_{\downarrow \uparrow}=D_4\)

Note: Every entry for D can be complex, which can be specified by Dn = [Re Dn, Im Dn].

NOTE: In the presence of anomalous pairing \(N\) is no longer a good quantum number. In order to allow for states to break this symmetry please specify the input parameter mod_N to be non-zero, usually mod_N=2. mod_N has to be a positive even integer. Depending on the model one may also have to set mod_Sz accordingly.

Example

The following example shows the unit cell of NaCl with its atoms, bonds, and lattice vectors:

unitcell:
    atoms:
        - ['0', 'Na', [0.0, 0.0, 0],0, 0]
        - ['1', 'Cl', [0.5, 0.5, 0], 0, 0 ]
    lattice_vectors: [[1, 0, 0],[0, 1, 0],[0,0,0]]
    bonds:
        - ['0', '1', [ 0, 0, 0], -1.0,   1]
        - ['0', '0', [ 1, 0, 0], -0.2, 0.5]
        - ['0', '0', [ 0, 1, 0], -0.2, 0.5]
        - ['1', '0', [ 0, 1, 0], -0.3, 0.6]
        - ['1', '0', [ 1, 0, 0], -0.3, 0.6]
        - ['1', '0', [ 1, 1, 0], -0.3, 0.6]

NOTE: This example is purely for displaying the input. For more interesting examples see Examples.

Lattice System#

A lattice system is assembled from clusters, which in turn are constructed from repetitions of unit cells. The parameters defining a lattice system are:

cluster_size: List defining the number of repetitions of unit cells along the directions defined by the lattice vectors

system_size: List defining the number of repetitions of clusters along the lattice vectors

For example, cluster_size : [2, 3, 1] implies that two unit cells in the direction of the first lattice vector and three unit cells in the direction of the second lattice vector define a cluster. Similarly, a system_size of [4, 4, 1] describes a lattice system with four clusters in the direction of the first lattice vector (eight unit cells) and four clusters in the direction of the second lattice vector (12 unit cells). Accordingly, this Bravais lattice system consists of 16 clusters, or equivalently 96 unit cells.

NOTE: 3D lattices are not currently implemented, thus any value different from "1" for the third component of cluster_size or system_size will result in an error.

Optional Parameters

Aside from the required parameters mentioned above, optional parameters can also be passed to the solver, allowing for fine-tuning of the lattice system.

Cluster Offset

The cluster is centered in the system by default. If any other position is desired, the offset can be specified explicitly. The offset is measured in repetitions of clusters.

For example, the default cluster offset for a system with system_size: [3,4,1] would be cluster_offset: [1,2,0] (non-integer divisions are rounded down).

Boundary Conditions

Boundary conditions can be specified with the parameter system_boundary_condition, which can take the values:

'hard-wall' (default)
'periodic'
'anti-periodic'

The Input can be either of type string, which results in the same boundary conditions in the x and y direction, or it can be of type list. In the latter case, it is possible to specify the boundary condition for each direction individually.

# [...]
# code not executable
#
# exmaple of string input:
system_boundary_condition = 'periodic'

# example of list input:
system_boundary_condition = ['periodic', 'hard-wall']

IMPORTANT: If the total system size (measured in repetitions of atoms) is less than [3,3,1] hard-wall boundary conditions will be applied for each direction with total system size < 3. The formula for total system size is: system_size * cluster_size * unitcell_size

Number of Particles

The parameter N fixes the number of fermions in the system. It takes an integer which must be:

= 0 (site_type: spins)
<= number of atoms (site_type: spinless_fermions, site_type: tJ)
<= 2 * number of atoms (site_type: spinful_fermions)

NOTE: The default is "half filling", which means that the number of particles is half the number of atoms for spinful fermions, or equal to the number of atoms for spinless fermions.

Spin Polarization

For spinful site_types you can fix the z-component of the total spin via the parameter Sz. This parameter accepts integer values corresponding to twice the physical spin projection along the z-axis. Accordingly, the values are constrained by:

Sz <= N for N <= M, where "M" is the number of atoms and "N" the number of fermions.
Sz <= 2 * M - N for N > M.

Run Parameters

The run parameters specify the fine-tuning of the DMRG calculation. You can specify the maximum number of iterations (max_iter), the tolerance for the mean-field (tol_mf), how many states should be considered (states), which inverse mean-field method should be used (iMF), and which format should be used for the output (output_type).

max_iter: default 20, max = 50

tol_mf: default 1e-6

states: default 1, max-values for spinless: \({M\choose N}\), max-value for spinful fermions: \({M\choose n_{\uparrow}}{M\choose n_{\downarrow}}\)

iMF: default iHF, [iMF, iHF, iDFT, ikDFT, ]

output_type: default hdf5 [hdf5, json, pandas, yaml ]