afqmctools.hamiltonian.model package#

Submodules#

afqmctools.hamiltonian.model.builder module#

class afqmctools.hamiltonian.model.builder.HamiltonianBuilder(lattice=None, **kwargs)#

Bases: object

Builder class for constructing a Hamiltonian.

Parameters:

  • lattice (Lattice) – the Lattice instance which describes the geometry of the lattice. If not specified, the derived class is responsible for generating a Lattice instance.

  • nbands (int, optional, default=1) – the number of bands to use in the Hamiltonian.

  • spin_symm (afqmctools.hamiltonian.model.ham_class.SpinSymm, optional, default=None) – the spin symmetry to use in the Hamiltonian. Possible values are: SpinSymm.CLOSED, SpinSymm.COLLINEAR, or SpinSymm.NONCOLLINEAR.

lattice#

a reference to the Lattice instance which the Hamiltonian is defined on

Type:

afqmctools.systems.lattice.Lattice

hamiltonian#

the Hamiltonian which is built.

Type:

afqmctools.hamiltonian.model.ham_class.Hamiltonian

Raises:

  • ValueError – raised when any build step is invoked using an invalid amplitude

  • ValueError – raised when no hst_type can be unambiguously inferred

Notes

see the User Documentation for more information on the definition an input conventions for each Hamiltonian term.

afm_pinning(h_afm_pin, axis=0, spin_symm=None, pin_type=None)#

adds anti-ferromagnetic (AFM) pinning to the Hamiltonian

Builds an anti-ferromagnetic (AFM) pinning term of the type: \(\sum_{i \sigma} v_{i\sigma} \hat{n}_{i\sigma}\), where \(v_{i \downarrow} = - v_{i \uparrow} = 1/2(-1)^(h)(i)) h_afm_pin\) and h_afm_pin is the pinning field strength, and adds it to the Hamiltonian.

Parameters:

  • h_afm_pin (float) – the amplitude of the pinning field

  • axis (int, optional, default = 0) – the axis to apply pinning along

  • spin_symm (afqmctools.hamiltonian.model.ham_class.SpinSymm, optional) – an override for the default spin symmetry enumerate type for the hopping matrix. If not given, the spin symmetry of the Hamiltonian will be used.

Raises:

RuntimeError – when the Hamiltonian as an invalid afm_pin_type

Notes

available pinning functions: - staggered: \(h(i) = i_1+i_2\) - fm: \(h(i) = i_2\)

pinning is applied to an edge, with lattice coordinate 0 or L-1, on the given axis.

charge_pinning(h_charge_pin, axis=0, spin_symm=None)#

Adds charge pinning to the Hamiltonian

builds a charge pinning term of the type: :math`sum_{i sigma} v_{isigma} hat{n}_{isigma}`, where \(v_{i downarrow} = v_{i uparrow} = h_charge_pin\) and h_charge_pin is the pinning field strength.

Parameters:

  • h_afm_pin (float) – the amplitude of the pinning field

  • axis (int, optional, default = 0) – the axis to apply pinning along

  • spin_symm (afqmctools.hamiltonian.model.ham_class.SpinSymm, optional) – an override for the default spin symmetry enumerate type for the hopping matrix. If not given, the spin symmetry of the Hamiltonian will be used.

Notes

pinning is applied to an edge, with lattice coordinate 0 or L-1, on the given axis.

custom_one_body(in_mat, spin_symm=None)#

add a custom one-body term to the Hamiltonian

Parameters:

  • in_mat (ndarray) – the one-body term to add to the Hamiltonian

  • spin_symm (afqmctools.hamiltonian.model.ham_class.SpinSymm, optional) – an override for the default spin symmetry enumerated type for the hopping matrix. If not given, the spin symmetry of the Hamiltonian will be used.

Notes

The in_mat must have the correct shape for the Hamiltonian and spin symmetry. For

COLLINEAR spin symmetry, the matrix must have shape (nbasis,nbasis) or (2*nbasis, nbasis), and for NONCOLLINEAR spin symmetry, the matrix must have shape (2*nbasis, 2*nbasis).

Examples

>>> import numpy as np
    from afqmctools.systems.lattice import get_lattice
    from afqmctools.hamiltonian.model.builder import HamiltonianBuilder
    lattice = get_lattice(
    params=dict(
            L1 = 3,
            L2 = 2,
            boundary1 = "PBC",
            boundary2 = "PBC"
        )
    )
    builder = HamiltonianBuilder(lattice=lattice)
    # make a custom one-body term - random symetrix noise
    one_body_matrix = 0.0001*np.random.rand(nbasis,nbasis)
    one_body_matrix = 0.5*(one_body_matrix + one_body_matrix.T)
    builder.custom_one_body(one_body_matrix)
    builder.finalize()
edge_pinning(pinning_func, h_pin, same_sign=False, axis=0, spin_symm=None)#

Add general pinning, at the edge, to the Hamiltonian

Generalized pinning function, apply pinning_func to sites at the edge pinning_func takes a (i,j) coordinate

Parameters:

  • pinning_func (function(i:int, j:int) -> float) – a modulation function for the pinning field. Should compute

  • h_pin (float) – the amplitude of the pinning field

  • same_sign (bool) – if True, spin up and spin down sectors have the same sign. if False, spin up and spin down sectors have opposite signs.

  • axis (int, optional, default = 0) – the axis to apply pinning along

  • spin_symm (afqmctools.hamiltonian.model.ham_class.SpinSymm, optional) – an override for the default spin symmetry enumerate type for the hopping matrix. If not given, the spin symmetry of the Hamiltonian will be used.

Notes

pinning is applied to an edge, with lattice coordinate 0 or L-1, on the given axis.

finalize(verbose=False)#

Combine Hamiltonian terms wherever possible, keeping terms with different hst_type separate.

Parameters:

verbose (bool) – if True, print verbose information

fm_pinning(h_fm_pin, axis=0, spin_symm=None, pin_type=None)#

adds ferromagnetic (FM) pinning to the Hamiltonian

builds an FM pinning term of the type: \(\sum_{i \sigma} v_{i\sigma} \hat{n}_{i\sigma}\), where \(v_{i downarrow} = - v_{i uparrow} = 1/2 h(i) h_fm_pin\) and h_fm_pin is the pinning field strength.

Parameters:

  • h_fm_pin (float) – the amplitude of the pinning field

  • axis (int, optional, default = 0) – the axis to apply pinning along

  • spin_symm (afqmctools.hamiltonian.model.ham_class.SpinSymm, optional) – an override for the default spin symmetry enumerate type for the hopping matrix. If not given, the spin symmetry of the Hamiltonian will be used.

Raises:

RuntimeError – when the Hamiltonian as an invalid fm_pin_type

Notes

available functions: - staggered: \(h(i) = (-1)^{(i_1==0)}\) - fm: \(h(i) = +0.5\)

pinning is applied to an edge, with lattice coordinate 0 or L-1, on the given axis.

heisenberg_J(J, hst_type=None, nth_neighbor=1)#

Adds an isotropic Heisenberg spin-term.

The isotropic Heisenberg Hamiltonian can be expressed in terms of the Hubbard-Kanamori terms as:

\[H_{Heisenberg}[J] = H_U1[-J/2] + H_U2[J/2] - J \sum_{i < j}( C^\dagger_{i \uparrow}C^\dagger_{j \downarrow} C_{i \downarrow}C_{j \uparrow} + C^\dagger_{i \downarrow}C^\dagger_{j \uparrow} C_{i \uparrow}C_{j \downarrow} )\]

The last two terms are two of the four terms of the Hund’s J.

hubbard_Jij(J, hst_type=None, nth_neighbor=0)#

Adds a Hund’s J term to the Hamiltonian.

The general form of the Hund’s J term is:

\[\sum_{i<j} J_{ij} ( \hat{c}^\dagger_{i\uparrow}\hat{c}^\dagger_{j\downarrow}\hat{c}_{i\downarrow}\hat{c}_{j\uparrow} +\hat{c}^\dagger_{i\uparrow}\hat{c}^\dagger_{i\downarrow}\hat{c}_{j\downarrow}\hat{c}_{j\uparrow} +\hat{c}^\dagger_{j\uparrow}\hat{c}^\dagger_{i\downarrow}\hat{c}_{j\downarrow}\hat{c}_{i\uparrow} +\hat{c}^\dagger_{j\uparrow}\hat{c}^\dagger_{j\downarrow}\hat{c}_{i\downarrow}\hat{c}_{i\uparrow} ),\]

where i,j are combined site and band indices.

Here, we generate the $J_{ij}$ matrix which will be interpreted as above.

hubbard_U1_density_density(U1, hst_type=None, nth_neighbor=0)#

Adds a density-density Hubbard U1 term to the Hamiltonian.

\[H_{U_1} = \sum_{ij} U^1_{ij} (n_{i\uparrow} n_{j\downarrow} + n_{i\downarrow} n_{j\uparrow})\]
Parameters:

  • U1 (float | numpy.ndarray) – the amplitude of the Hubbard U1 term. See Notes for conventions.

  • hst_type (str, optional) – the type of Hubbard-Stratonovich transformation (HST) to use in AFQMC. If not specified, an appropriate HST type will be inferred based on U1.

  • nth_neighbor (int, optional) – the order of neighbor to use for the interaction term. If not given, the interaction is assumed to be on-site.

Notes

conventions:

  • a single number given for U1 implies the same U1 for all sites, and is uniform across bands

hubbard_U2_spin_spin(U2, hst_type=None, nth_neighbor=0)#

Adds a spin-spin Hubbard U2 term to the Hamiltonian.

\[H_{U_2} = \sum_{ij} U^2_{ij} (n_{i\uparrow} n_{j\uparrow} + n_{i\downarrow} n_{j\downarrow})\]
Parameters:

  • U2 (float | numpy.ndarray) – the amplitude of the Hubbard U2 term. See Notes for conventions.

  • hst_type (str, optional) – the type of Hubbard-Stratonovich transformation (HST) to use in AFQMC. If not specified, an appropriate HST type will be inferred based on U2.

  • nth_neighbor (int, optional) – the order of neighbor to use for the interaction term. If not given, the interaction is assumed to be on-site.

Notes

conventions:

  • a single number given for U2 implies the same U2 for all sites, and is uniform across bands

nth_neighbor_hopping(t=1.0, nth_neighbor=1, spin_symm=None, opposite_twists=False)#

adds an nth-order neighbor hopping term to the Hamiltonian

\[\sum_{\langle ij\rangle^n} (-t) \hat{c}^\dagger_i \hat{c}_j\]
Parameters:

  • t (float | numpy.ndarray, default: 1.0) – the hopping strength. By convention a minus sign (-) is applied to the hopping. i.e. \(\sum_{<ij>} (-t) \hat{c}^\dagger_i \hat{c}_j\) If t is a float, hoping between sites but not between bands, is used. If t is an numpy.ndarray, it must have shape nbands x nbands and is interpreted as a band dependent hopping.

  • nth_neighbor (int) – the order of neighbor to use for hopping. nth_neighbor equal to 1 is nearest-neighbors. If nth_neighbor is not given, and t is an iterable, t is iterated over and nth_neighbor is inferred from the array index, i, of each entry in t as nth_neighbor=i+1

  • spin_symm (afqmctools.hamiltonian.model.ham_class.SpinSymm, optional) – an override for the default spin symmetry enumerated type for the hopping matrix. If not given, the spin symmetry of the Hamiltonian will be used.

  • opposite_twists (bool, optional, default: False) – if True, the hopping matrix is constructed using opposite twists, for the up and down spins (i.e. twist_down = -twist_up ) If False, the hopping matrix is constructed using the same twist for both spins.

Raises:

ValueError – when the hopping matrix can’t be constructed for the combination of t and nth_neighbor

Examples

adds default hopping (nearest-neighbor with t=1.0)

>>> HamiltonianBuilder.nth_neighbor_hopping()

add nearest-, and next-nearest-neighbor hopping

>>> HamiltonianBuilder.nth_neighbor_hopping(t=[1.0,0.5])
nth_order_hubbard_Vij(V, hst_type=None, nth_neighbor=1)#
TODO: Be careful about the conventions on defining ‘V’, there could be a

factor of 2 (or 1/2)

Builds an extended Hubbard model V term and adds it to the Hamiltonian.

The conventions used are, if i = (mu, m) is a combined lattice and band index,

\[H_V = \sum_{\langle(i<j)\rangle} \sum_{\sigma \sigma'} V_{n m} ( \hat{n}_{i \sigma \sigma'} \hat{n}_{j \sigma \sigma'} )\]

which is equivalent to: \(H_V = H_{U_1}(U_1=V)\) and \(H_{U_2}($U_2$=V)\)

onebody_onsite(epsilon, spin_symm=None)#
Adds an onsite one-body term to the Hamiltonian (for example, a chemical potential,

band energies, interband hopping, etc.)

\[\hat{H}_{onsite} = \sum_i \sum_{m m'} \epsilon_{m m'} \hat{c}^\dagger_{i,m} \hat{c}_{i,m'}\]

where \(\hat{c}^\dagger_{i,m}\)/\(\hat{c}_{i,m}\) are the creation / annihilation operator for site i and band m.

Parameters:

epsilon (float | numpy.ndarray) – the onsite energy. If epsilon is a float, it is interpreted as a band-independent onsite energy. If epsilon is a numpy.ndarray, it must have shape (nbands,nbands) and is interpreted as a band-dependent onsite energy. In all cases, epsilon is applied uniformly to all sites.

onsite_hubbard(U, hst_type=None)#

adds onsite Hubbard U to the Hamiltonian with possibly band-dependent amplitude U. See Notes for conventions.

Parameters:

  • U (float | iterable | numpy.ndarray) – the amplitude of the onsite Hubbard interaction. See Notes for the conventions on how U is interpreted.

  • hst_type (str, optional) – the type of Hubbard-Stratonovich transformation (HST) to use in AFQMC. If not specified, an appropriate HST type will be inferred based on U.

Notes

conventions:

  • a single number given for U implies the same U for all sites

  • a 1-Dimensional array with length nbands gives a different U for each

    band, but U is independent of site index.

Advanced Notes:
  • in case of a 1-D array of U values, the U values are separated into

    positive and negative values. Up to two terms may be generated (i.e. one positive and one negative) to allow different Hubbard-Stratonovich Transformations to be used for each case.

print_components(verbose=False)#

Individually print each current Hamiltonian component

rashba_soc(rashba_lambda=1.0, t=1.0, n=1, spin_symm=None)#

Builds a Rashba spin-orbit coupling term of the form:

\[\hat{H}_{rashba SOC} = i \lambda_{rashba} \sum_{ij,\sigma\sigma'} t_{ij} (\vec{\sigma} \times \hat{r}_{ij})^{\sigma\sigma'}_z \hat{c}^\dagger_{i\sigma} \hat{c}_{j\sigma'}\]

where \(\vec{\sigma}\) is the vector of Pauli matrices, and \(\vec{r}_{ij}\) is the relative position between sites i and j.

afqmctools.hamiltonian.model.builder.iterate_nth_order(start_n=1)#

Decorator to iterate over a list of parameters, calling the method of the object, obj, with each parameter in params.

decorates functions with the signature:

func(self,params,nth_neighbor=n,*args,**kwargs)

where params is an iterable of parameters to iterate over or a single parameter, args are additional arguments to pass to the method, and kwargs are additional keyword arguments to pass to the func.

Note specifically that only functions that accept the nth_neighbor keyword arguments can be decorated with this function.

Parameters:

  • func (function) – the function to decorate

  • start_n (int, optional, default=1) – the starting index for the nth_neighbor parameter

afqmctools.hamiltonian.model.builder.skip_empty_params(func)#

Decorator to skip over a function if the parameters are all zero. None is interpreted as zero.

Parameters:

func (function) – the function to decorate

Notes

This decorator is useful for functions that would attempt to build an empty Hamiltonian component if the parameters are all zero. None is interpreted as zero. This decorator preserves the original docstring of the decorated function.

afqmctools.hamiltonian.model.director module#

class afqmctools.hamiltonian.model.director.HamiltonianDirector(source=None, lattice=None, builder=None)#

Bases: _HamiltonianDirector

Directs building a model Hamiltonian based on a source input file or dict.

Parameters:

  • source (str | Path | dict) – a description of the Hamiltonian (and possibly lattice) parameters. See Notes for details on Hamiltonian parameter syntax and conventions. If a str is given, it is interpreted as the name of an input file in .toml format and parameters are read from that file. If a dict is given, then parameters are read directly from the dict.

  • lattice (Lattice) – the Lattice instance which describes the geometry of the lattice. If not specified, the lattice will be built from the source input.

  • builder (HamiltonianBuilder) – the builder that will be directed by HamiltonianDirector. If not specified, a default HamiltonianBuilder will be used (this is what almost all users will want).

build()#

builds and returns a Hamilton instance based on the build steps defined in the source input.

release_builder()#

releases the HamiltonianBuilder instance to the caller. This disables the build() method until a HamiltonianBuilder is bound to the director. A HamiltonianBuilder can be bound to the director using the bind_builder() method.

bind_builder(builder: HamiltonianBuilder, force=False)#

binds a HamiltonianBuilder to the director. If force is True, then the current HamiltonianBuilder is replaced with the new builder. If force is False, then an error is raised if a HamiltonianBuilder is already bound to the director.

Notes

The Hamiltonian is built by a sequence of build steps which are specified in the source input. Build steps are specified as key-value pairs in the ‘hamiltonian’ section of the input file or in the source dict. By default, nearest-neighbor hopping is included in the Hamiltonian; but all interaction terms must be explicitly included in the input.

The following build steps are supported, and are listed as key : description. Also see the HamiltonianBuilder class for more details on the build steps, and for finer control over Hamiltonian construction. The acceptable input dimensions are also listed for each build step; other input dimensions will raise an error.

  • t : nth-order neighbor hopping term; input convention are as follows:

    • if t is a scalar, then nearest-neighbor hopping is included with strength t

    • if t is a 1-dimensional list (i.e. [t1,t2,…,tn]), then up to nth-order hopping is included

    • if t is a 2-dimensional with shape (nbands, nbands), then the t is interpreted as an on-site inter-band hopping matrix

    • if t is a list of 2-dimensional arrays, then each element is interpreted as an on-site inter-band hopping matrix. This is functionally the same as \(t_{mn} = \sum t^{(i)}_{mn}\) where \(t^{(i)}\) is the ith element of the list and \(m,n\) are band indices.

  • U : onsite Hubbard interaction term; input convention are as follows:

    • if U is a scalar, then the onsite Hubbard interaction term is included with strength U and applied to all sites and bands.

    • if U is 1-dimensional with length nbands (i.e. [U1,U2,…,Um] where for an m-band model), then the onsite Hubbard interaction term is included with strength U_i applied to band i and uniformly across sites.

    • if U is 1-dimensional with length nsites (i.e. [U1,U2,…,Un] where n is the number of sites), then the onsite Hubbard interaction term is included with strength U_i applied to site i and uniformly across bands.

  • U1 : Hubbard density-density interaction term. Input convention are as follows:

    • if U1 is a scalar, then the Hubbard density-density interaction term is included with strength U1 and is applied to all sites, and is uniform across bands.

    • if U1 is a 2-dimensional with shape (nbands, nbands), then U1 is used as an intrasite density-density interaction, and is applied uniformly across sites.

  • U2 : Hubbard spin-spin interaction term. Input convention are as follows:

    • if U2 is a scalar, then the Hubbard spin-spin interaction term is included with strength U2 and is applied to all sites, and is uniform across bands.

    • if U2 is a 2-dimensional with shape (nbands, nbands), then U2 is used as an intrasite spin-spin interaction, and is applied uniformly across sites.

  • J : Hund’s coupling interaction term. Input convention are as follows:

    • if J is a scalar, then the Hund’s coupling interaction term is included with strength J and is applied to all sites, and is uniform across bands.

    • if J is a 2-dimensional with shape (nbands, nbands), then J is used as an intrasite Hund’s coupling interaction, and is applied uniformly across sites.

afqmctools.hamiltonian.model.director.InputFileDirector#

alias of HamiltonianDirector

afqmctools.hamiltonian.model.ham_class module#

class afqmctools.hamiltonian.model.ham_class.Hamiltonian#

Bases: object

A container for Hamiltonian terms. Terms are stored by the naming conventions used in the afqmc code.

An example of the internal structure is as follows:

terms = {
    'tij' : [tij_csr_1,tij_csr_2,...],
    'Ui' : [U_csr],
    'U1ij' : [U1ij_csr],
    'U2ij' : [U2ij_csr],
    'Jij' : [Jij_csr_1,Jij_csr_2]
}

A dictionary with keys corresponding to the standard generalized Hamiltonian term names stores a list of terms of the same type. The list of terms can be collapsed into a single term if desired; however, keeping terms separate provides more flexibility, especially regarding the Hubbard-Stratonovich transformation. Each entry in the list should be a scipy.sparse.csr_array instance.

By default, assigning terms to the Hamiltonian will append an additional term to the relevant list.

Design notes for Developers:

  • should serve only as a container for Hamiltonian terms

    which are built via the Director-Builder pattern.

  • this class should not directly reference the underlying lattice.

get(value, default=None)#
get_J()#

return the J part of the Hamiltonian as a single scipy sparse csr matrix.

get_U()#

return the U part of the Hamiltonian as a single scipy sparse csr matrix. This includes U, U1, and U2

Uij is separated into U+U1, and U2 to

avoid issues with shape consistency while summing below.

get_heisenberg()#

return the get_heisenberg part of the Hamiltonian as a single scipy sparse csr matrix.

get_one_body()#

return the one-body part of the Hamiltonian as a single scipy sparse csr matrix

keys()#
property nbands#
recount_components()#
property spin_symm#
class afqmctools.hamiltonian.model.ham_class.HamiltonianComponent(csr_array, model_type, spin_symm=<SpinSymm.CLOSED: 1>, **kwargs)#

Bases: object

Class to encapsulate the CSR representation,

and metadata corresponding to individual Hamiltonian components.

property shape#
toarray()#

Module contents#