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

Author: James P.F. LeBlanc
Version: Revision: 0.61
Date: Date: 2022/01/11

Note

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

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 likely be removed/replaced in a future release. Current support is limited to Sigma and Pi_phuu graph types. set graph_type=0 for Fermionic external line, and =1 for Bosonic.

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/(X+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 with elements \( a_i\). This is the symbolic representation of the energy \(E=-\sum\limits_{i}a_i\epsilon_i\) described in AMI paper (https://doi.org/10.1103/PhysRevB.99.035120). We use the convention \(G=\frac{1}{X+E}\). It is the coefficients for a linear combination of a set of possible values.

typedef std::vector<int> alpha_t: Vector of type int with elements \( \alpha_i\). 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). This indicator should propagate through the Matsubara sums to the final expression, and might have utility for evaluating energies. Technically this is not necessary 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) (https://doi.org/10.1103/PhysRevB.99.035120).

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. It is rarely called except for multipole problems, and typically for only small arguments.

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.

Cross operator ‘ \(\times \)‘ that is defined after equation (20) in the AMI paper (https://doi.org/10.1103/PhysRevB.99.035120).

SorF_t dot(Si_t Si, SorF_t fermi)

Evaluation dot-product from AMI paper.

Dot operator ‘ \( \cdot \)‘ that is defined after equation (20) in the AMI paper (https://doi.org/10.1103/PhysRevB.99.035120).

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 compare of type pole_struct.
pole2 – [in] Second pole you want to compare 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 Green’s function you want to compare of type g_struct.
g2 – [in] Second Green’s function you want to compare of type g_struct.

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

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 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 https://doi.org/10.1103/PhysRevB.99.035120. 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.

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 function or the negative of the Bose distribution functions given by \(\frac{1}{\sigma \exp^{\beta E}+1} \) 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.

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.

Returns:

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

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 additional arguments are empty the evaluate function is called directly.

void factorize_Rn(Ri_t &Rn, g_prod_t &unique_g, R_ref_t &Rref, ref_eval_t &Eval_list): Optimize function for SPR notation.

void factorize_terms(terms &ami_terms, g_prod_t &unique_g, R_ref_t &Rref, ref_eval_t &Eval_list): Optimize function for terms notation.

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.

double tol_ = 1e-12: Tolerence to determine equality.

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 = 1.0: Overall prefactor - default(1).

double BETA_ = 0.0: 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.

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)}\prod{G_j}\times sign \).

Public Members

double sign = 1: Sign prefactor.

pole_array_t p_list: List of poles, \( \prod{f(p_i)}\).

g_prod_t g_list: List of Green’s functions, \( \prod{G_j}\).