Documentation

Welcome to the documentation webpage of LibAMI. Please inform the authors of errors or omissions.

class AmiBase

The primary class of libami.

Contact: jleblanc@mun.ca

Note

See https://github.com/jpfleblanc/libami

Author

JPF LeBlanc

Version

Revision: 0.61

Date

Date: 2022/01/11

Public Types

enum stat_type

Indicator for statistics. A future version might use this more frequently. Current version presumes all integration frequencies are Fermionic.

Values:

enumerator Bose
enumerator Fermi
enum graph_type

Graph types will be removed in a future release. Current support is limited to Sigma and Pi_phuu graph types.

Values:

enumerator Sigma
enumerator Pi_phuu
enumerator Pi_phud
enumerator Hartree
enumerator Bare
enumerator Greens
enumerator density
enumerator doubleocc
enumerator Pi_ppuu
enumerator Pi_ppud
enumerator DOS
enumerator ENERGY
enumerator FORCE
enum int_type

To be removed in a future release.

Values:

enumerator hubbard
enumerator coulomb
enum disp_type

To be removed in a future release.

Values:

enumerator tb
enumerator fp
enumerator hf
enum ext_type

To be removed in a future release.

Values:

enumerator matsubara
enumerator real
typedef std::vector<std::complex<double>> energy_t

The energy of each denominator will always appear as a linear combination of these initial (pre integration) energies, \(\epsilon_1, \epsilon_2\) ..etc By convention, the energy_t contains the NEGATIVE of the energy of a given green’s function line, \( 1/(\omega+E) \) where \( E=-\epsilon \)

typedef std::vector<std::complex<double>> frequency_t

This is the list of internal and external frequencies values. Typically only the last elements for external frequencies are non-zero - but one can evaluate intermediate steps where multiple external frequencies are non-zero.

typedef std::vector<int> epsilon_t

Vector of type int. This is the symbolic representation of the energy \(-\epsilon\) described in Ref[AMI]. We use the convention \(G=\frac{1}{\omega+\epsilon}\). It is the coefficients for a linear combination of a set of possible values.

typedef std::vector<int> alpha_t

Vector of type int. This is the symbolic representation of the frequency, as a linear combination of possible entries. Typically contains only values of 0, -1 and +1. Other values at intermediate steps typically represent an error. \(X=\sum\limits_{i} i\nu_i \alpha_i\).

typedef int species_t

Indicator for multi-species green’s function or energy dispersions (spin-up vs spin-dn, multiband, etc). Technically this is not relevant for libami, but may be useful.

typedef std::vector<double> sign_t

Basic element of the S array in SPR notation.

typedef std::vector<g_struct> g_prod_t

Basic element of the R array in SPR notation.

typedef std::vector<pole_struct> pole_array_t

Basic element of the P array in SPR notation.

typedef std::vector<g_prod_t> Ri_t

R result after each integration step.

typedef std::vector<pole_array_t> Pi_t

P result after each integration step.

typedef std::vector<sign_t> Si_t

S result after each integration step.

typedef std::vector<Ri_t> R_t

final output R arrays.

typedef std::vector<Pi_t> P_t

final output P arrays.

typedef std::vector<Si_t> S_t

final output S arrays.

typedef std::vector<term> terms

The storage for the term-by-term construction. Each term struct is an element of the terms vector.

typedef std::vector<std::vector<std::complex<double>>> SorF_t

Although perhaps strangely named - represents the multiplication of sign and pole arrays defined in Equation (19)

Public Functions

template<typename T>
inline int sgn(T val)

Returns the sign of a value - or zero if it is uniquely zero.

int factorial(int n)

Simple factorial function - Nothing special.

void construct(int N_INT, g_prod_t R0, terms &terms_out)

Construction function for term-by-term construction.

This is a simplified AMI symbolic integration function. It takes a starting integrand defined by g_prod_t R0 and ami_parms object, and returns the terms for symbolic evaluation in a simple terms structure.

Parameters

  • parms – [in] : ami_parms object, basic parameters for AMI.

  • R0 – [in] : g_prod_t integrand to be processed.

  • terms_out – [out] Resultant terms containing separate AMI terms for later evaluation.

void construct(ami_parms &parms, g_prod_t R0, terms &terms_out)

For user simplicity this is a wrapper function to make ami_terms and SPR calls similar.

std::complex<double> evaluate(ami_parms &parms, terms &ami_terms, ami_vars &external)

Evaluate Terms.

This is the primary AMI evaluation function for the term-by-term construction.

Parameters

  • parms – [in] : ami_parms object, basic parameters for AMI. Typically same as construction.

  • ami_terms – [in] : terms result from construction function

  • external – [in] : Input external variables in a ami_vars struct.

Returns

Result is returned as single value of type std::complex<double>

std::complex<double> evaluate_term(ami_parms &parms, term &ami_term, ami_vars &external)

Evaluate a single Term. Usage is identical to evaluate function.

std::complex<double> eval_fprod(ami_parms &parms, pole_array_t &p_list, ami_vars &external)

Evaluate the numerator of a term - product of fermi/bose functions.

Parameters

  • parms – [in] : ami_parms object, basic parameters for AMI.

  • p_list – [in] : pole_array_t a list of poles that is interpretted as \( \prod{f(p_i)} \). If poles contain derivatives then these are resolved at this stage.

  • external – [in] : Input external variables in a ami_vars struct.

Returns

Single value for product of fermi/bose functions

void integrate_step(int index, terms &in_terms, terms &out_terms)

Integrates a single matsubara index.

void terms_general_residue(term &this_term, pole_struct this_pole, terms &out_terms)

Primary residue function for term construction.

void take_term_derivative(term &in_term, pole_struct &pole, terms &out_terms)

Derivative for term construction.

void print_terms(terms &t)

Screen IO for debugging.

void print_term(term &t)

Screen IO for debugging.

void convert_terms_to_ri(terms &ami_terms, Ri_t &Ri)

Convert terms to Ri structure for optimization. This does not create a usable terms object. It is purely an intermediate step for the optimization functions.

pole_array_t find_poles(int index, g_prod_t &R)

Simple function to scan through g_prod_t and collect an std::vector of poles with respect to index.

g_prod_t simple_residue(g_prod_t G_in, pole_struct pole)

Used in pole multiplicity == 1 - aka, simple pole. Performs residue theorem on G_in and produces a new g_prod_t as output.

Parameters

  • G_in – [in] g_prod_t to evaluate residues with respect to pole.

  • pole – [in] pole_struct defining the pole.

Returns

is of type g_prod_t.

g_struct update_G_pole(g_struct g_in, pole_struct pole)

Manipulates a Green’s function to replace residue variable ‘z’ with complex pole.

pole_struct update_Z_pole(AmiBase::pole_struct p_in, AmiBase::pole_struct pole)

Manipulates a Pole_struct to replace residue variable ‘z’ with complex pole.

void update_gprod_simple(int index, R_t &R_array, P_t &P_array, S_t &S_array)

Depricated version of update_gprod for only simple poles. Replaced by update_gprod_general.

void update_gprod_general(int int_index, int array_index, R_t &R_array, P_t &P_array, S_t &S_array)

Primary loop. Takes R[n] as input and outputs R[n+1], P[n+1] and S[n+1].

Parameters

  • int_index – [in] indicator for which is the integration variable

  • array_index – [in] indicator for which element of alpha_t corresponds to that integration variable. Typically the same as int_index, unless you want to perform out of order.

  • R_array – [in] R[n] input

  • R_array – [out] updated with R[n+1] on output.

  • S_array – [out] updated with S[n+1] on output.

  • P_array – [out] updated with P[n+1] on output.

SorF_t fermi(ami_parms &parms, Pi_t pi, ami_vars external)

The fermi/bose operator. Translates a vector of poles, into a vector of Fermi/Bose functions (and their derivatives) with specific numerical values dependent upon input ami_vars.

std::complex<double> fermi_pole(ami_parms &parms, pole_struct pole, ami_vars external)

Evaluation of a single pole in Fermi/Bose functions for a given ami_vars.

SorF_t cross(SorF_t left, SorF_t right)

Evaluation cross operator from AMI paper.

SorF_t dot(Si_t Si, SorF_t fermi)

Evaluation dot-product from AMI paper.

std::complex<double> get_energy_from_pole(pole_struct pole, ami_vars external)

Given a set of external energies, beta, and frequencies, will evaluate the energy of a pole_struct.

std::complex<double> get_energy_from_g(g_struct g, ami_vars external)

Given a set of external energies, beta, and frequencies, will evaluate the energy of a g_struct.

std::complex<double> eval_gprod(ami_parms &parms, g_prod_t g_prod, ami_vars external)

Evaluates a product of green’s functions.

Numerical evaluation of a product of Green’s functions. Used both in terms and R_t constructions.

Parameters

  • parms – [in] : ami_parms object, basic parameters for AMI.

  • g_prod – [in] : g_prod_t a list of g_struct that is interpretted as \( \prod{G_i} \).

  • external – [in] : Input external variables in a ami_vars struct.

Returns

Single value for product of Green’s functions

bool pole_equiv(pole_struct pole1, pole_struct pole2)

Checks if two Poles have similar characteristics. These characteristics include epsilon_t size and alpha_t size. Additionally, it checks each value of epsilon_t vector and alpha_t vector are the same.

Parameters

  • pole1 – [in] First pole you want to check and of type pole_struct

  • pole2 – [in] Second pole you want to check and of type pole_struct

bool g_equiv(g_struct g1, g_struct g2)

Checks if two g_struct have similar characteristics. These characteristics include epsilon_t size and alpha_t size. Additionally, it checks each value of epsilon_t vector and alpha_t vector are the same.

Parameters

  • g1 – [in] First pole you want to check and of type pole_struct

  • g2 – [in] Second pole you want to check and of type pole_struct

void evaluate_general_residue(g_prod_t G_in, pole_struct pole, Ri_t &Ri_out, pole_array_t &poles, sign_t &signs)

Testing Priority: 1.

Void function takes a product of Green’s functions - an element of an Ri_t object - and obtains the residue for a specific pole. Output is an array of such elements, a full Ri_T object, along with the respective poles and signs for Pi_t and Si_t. Includes derivative.

Parameters

  • G_in – [in] : Product of green’s functions

  • pole – [in] : Pole to evaluate residue

  • Ri_out – [out] : Resultant g_prod_t

  • poles – [out] : Resultant pole_array_t

  • signs – [out] : Resultant sign_t.

void take_derivative_gprod(g_prod_t &g_prod, pole_struct pole, double start_sign, Ri_t &r_out, pole_array_t &poles, sign_t &signs)

Take derivative of g_prod_t with respect to index stored in pole_struct. This is accomplished via multiple applications of chain rule. This is described somewhat in PRB 99 035120 - though the notation changed somewhat. The prefactor of -1 is no longer absorbed into a green’s function, but instead is stored in the S_t array. What is omitted there is discussion of derivatives of the fermi functions. Here they are simply tracked by defining an integer der_ of the pole-struct that gets incremented.

double get_starting_sign(g_prod_t G_in, pole_struct pole)

As part of the construction of the Si_t arrays, the initial sign is extracted prior to taking derivatives. Also is multiplied by \(1/(M-1)!\) where M is the multiplicity_ of the respective pole.

Obtains the elements of S_t arrays, modified for poles with multiplicity!=1.

g_prod_t reduce_gprod(g_prod_t G_in, pole_struct pole)

Removes green’s functions from g_prod_t to account for numerator of residue (z-z0)^m

double frk(int r, int k)

In order to take arbitrary derivatives of fermi functions - we need to know the prefactor. The fermi/bose function is given in general by the function:

\[ \sum\limits_{k=0}^{m} f_{rk}(m,k) \sigma^k (-1.0)^{k+1} \frac{1}{\sigma e^{\beta E}+1.0} \frac{1}{[\sigma + e^{-\beta E}]^k} \]

The frk function itself returns

\[ f_{rk}(m,k)=\sum\limits_{m=0}^{k+1} binomialCoeff(k,m) m^r (-1)^{k-m} \]

Using notation to match 10.1103/PhysRevB.101.075113 They produced coefficients to the fermi functions and put them in a table. We derive a general expression for those coefficients - we believe this to be general but have only checked up to 6th order… I think

std::complex<double> fermi_bose(int m, double sigma, double beta, std::complex<double> E)

Recursive construction of fermi_bose derivatives.

This computes the mth order derivative of the fermi or bose distribution functions at beta, for energy E. sigma=1.0 for fermi and -1.0 for bose.

int binomialCoeff(int n, int k)

Returns value of Binomial Coefficient C(n, k)

AmiBase()

Default Constructor. Constructor is empty. Currently no initialization is required in most cases.

AmiBase(ami_parms &parms)

Constructor with ami_parms. Possible deprecated.

void construct(ami_parms &parms, g_prod_t R0, R_t &R_array, P_t &P_array, S_t &S_array)

This is the primary AMI symbolic integration function. It takes a starting integrand defined by g_prod_t R0 and ami_parms object, and returns the S, P and R arrays necessary for symbolic evaluation.

Parameters

  • parms – [in] : ami_parms object, basic parameters for AMI.

  • R0 – [in] : g_prod_t integrand to be processed.

  • R_array – [out] Resultant R_t

  • P_array – [out] : Resultant P_t

  • S_array – [out] : Resultant S_t.

std::complex<double> evaluate(ami_parms &parms, R_t &R_array, P_t &P_array, S_t &S_array, ami_vars &external)

This is a primary AMI symbolic evaluation function. It takes a solution defined by S, P, and R arrays and the external parameters and returns a complex<double> restult.

Parameters

  • parms – [in] : ami_parms object, basic parameters for AMI.

  • R_array – [in] Input R_t

  • P_array – [in] : Input P_t

  • S_array – [in] : Input S_t

  • external – [in] : Input ami_vars containing point to evaluate.

std::complex<double> evaluate(ami_parms &parms, R_t &R_array, P_t &P_array, S_t &S_array, ami_vars &external, g_prod_t &unique_g, R_ref_t &Rref, ref_eval_t &Eval_list)

This is an optimized version of the evaluate function. For simplicity if the new objects are empty the evaluate function is called directly.

struct ami_parms

Parameters for AMI construction/evaluation.

Public Members

int N_INT_

Number of integrations to perform.

int N_EXT_ = 1

Hardcoded as (1) in this version - represents number of external variables.

double E_REG_ = 0

Possible energy regulator for evaluation of Fermi/Bose functions to control divergences. Should be zero by default and switched on if needed.

struct ami_vars

the ami_vars struct is the basic information required for the evaluation stage of AMI result. It contains the variable internal/external quantities. Specifically it is a list of numerical values for energies of each line and values for each frequency. Also stored is the possibility of an overall prefactor. Also required is a value of \(\beta=\frac{1}{k_B T}\) needed for evaluation of Fermi/Bose distributions.

Public Members

energy_t energy_

Numerical values of energies.

frequency_t frequency_

Numerical Values of frequencies.

double prefactor

Overall prefactor - default(1)

double BETA_

Required value of inverse temperature, \(\beta\).

double gamma_ = 0

Experimental parameter for spectral representation.

struct g_struct

A Green’s function structure. This is a symbolic vector of epsilon_t and vector of alpha_t. Also needed is what the statistics of the line are. While this could be determined from alpha - it is better to store it. For multistate systems the species_ index might be useful.

Public Functions

inline g_struct(epsilon_t eps, alpha_t alpha, stat_type stat)

Constructor with state_type specified.

inline g_struct(epsilon_t eps, alpha_t alpha)

Constructor assumes fermi statistics if not specified for partially initialized structure.

inline g_struct()

uninitialized variant

Public Members

epsilon_t eps_

Symbolic coefficients for a linear combination of epsilons.

alpha_t alpha_

Symbolic coefficients for a linear combination of frequencies.

stat_type stat_

Mark Fermi/Bose stats - Fermi is required in current version.

int pp = -1

Experimental Spectral representation. Implementation incomplete.

struct pole_struct

Pole structure. Equivalent to g_struct, but kept separate. Tracks multiplicity, and which green’s function it is attached to. Also it tracks how many derivatives to take when evaluated at a fermi function.

Public Members

int index_

Index that specifies which frequency it is a pole with respect to.

int multiplicity_ = 1

The multiplicity of the pole, starts at 1 and increments as needed.

int der_ = 0

Counter for derivatives

std::vector<int> which_g_

Index to identify which g_struct a pole originated from.

alpha_t x_alpha_

experimental component of Spectral evaluation

struct term

Term Structure for term-by-term evaluation. Conceptually simpler than SPR construction. Storage translates to \( \prod{f(p_i)}_{i}\prod{G_j}_{j}*sign \)