Documentation

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

class TamiBase

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 c10::complex<double> complex_double

Typedef for the type of complex numbers to be used throughout - c10 has torch’s complex scalar class c10::complex<T> is the prefered complex datatype to build tensors with and therefore the better option to use throughout

typedef at::Tensor 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 \). The energy_t is a tensor of sets of appropriate energy lists, allowing for batch evaluation. This is particularly useful for lattice problems where one wants to sum over sets of momenta which convert to energies.

typedef at::Tensor frequency_t

This is the list of internal and external frequencies values (each column) and batches of such values to be evalated simultaneously (each row). Typically only the last elements for external frequencies are non-zero - but one can evaluate intermediate steps where multiple external frequencies are non-zero. (Warning: the fermi/bose statistics are not generalized to multiple internal Matsubara frequencies. If this functionality is needed please contact the authors.)

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, but may be useful.

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<ft_term> ft_terms

The result of an integrand is this vector of ft_term structs. This is the main output of the construct function and the main object to pass to the evaluate function. See examples.

Public Functions

void construct(int N_INT, TamiBase::g_prod_t &R0, ft_terms &terms_out)

Following the notation from libami the construct function performs a number of Matsubara sums, and places the result into a ft_terms type.

Parameters:

  • N_INT – - the number of summations to perform (beginning from the zero index frequency and going to N_INT-1)

  • R0 – - The starting integrand. R0 is a product of green’s functions

  • terms_out – - The resulting analytic integrand.

void factorize(ft_terms &in_terms, ft_terms &out_terms)

Internal function to the construction. After each step attempts to combine terms into factorized form. Can be slow for high order integrands, and can be disabled by setting factorize=false.

Parameters:

  • in_terms – - terms to be factorized.

  • out_terms – - factorized terms.

void print_terms(ft_terms &t)

Screen IO for debugging.

void print_term(ft_term &t)

Screen IO for debugging.

std::string pretty_print_ft_term(ft_term &ft)

Experimental attempt for visualizing the post AMI integrand. Outputs string representing LaTeX formatted equation.

at::Tensor eval_ft(TamiBase::ami_parms &parms, TamiBase::FermiTree::fermi_tree_t &ft1, TamiBase::FermiTree::vertex_t &v, TamiBase::ami_vars &external)

Evaluate just the fermi-tree.

at::Tensor evaluate_term(TamiBase::ami_parms &parms, ft_term &ft_term, TamiBase::ami_vars &external)

Evaluation of single term.

at::Tensor evaluate(TamiBase::ami_parms &parms, ft_terms &ft_terms, TamiBase::ami_vars &external)

Standard evaluate function. See examples.

Returns:

at::Tensor of shape \(N_f \times N_e\), so that in practice one can sum the columns in a Monte Carlo integration

inline TamiBase()

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

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.

at::Tensor 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.

This is the central evaluation of the fermi and bose functions. It also includes evaluating arbitrary derivatives of the functions. See frk function that is rather complicated . This function is also the MOST challenging function for numerical evaluation.

at::Tensor fermi_bose(int m, double sigma, double beta, at::Tensor E)

Recursive construction of fermi_bose derivatives.

This is the original fermi_bose function that is not necessarily numerically stable.

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.

at::Tensor fermi_bose_mlte2(int m, double sigma, double beta, at::Tensor E)

This is a version that should be numerically stable based on stable primitives.

at::Tensor get_energy_from_pole(pole_struct pole, ami_vars external)

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

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.

void print_pole_struct_info(pole_struct g)

Primarily debugging function.

Parameters:

<tt>pole_struct</tt> –

void print_alpha_info(alpha_t alpha)

Primarily debugging function.

Parameters:

<tt>alpha_t</tt> –

void print_epsilon_info(epsilon_t eps)

Primarily debugging function.

Parameters:

<tt>epsilon_t</tt> –

void factorize_Rn(Ri_t &Rn, g_prod_t &unique_g, R_ref_t &Rref, ref_eval_t &Eval_list)

Optimize function for old SPR notation. Possibly Depricated.

Public Members

at::TensorOptions options = at::TensorOptions().dtype(at::kComplexDouble).device(at::kCPU)

Hold the device options inside the base class - specifically the options.dtype and options.device

ext_type ext_freq_type = matsubara

currently not used - to be removed

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. - at::Tensor = {e1_vector, e2_vector, … } columns of length batch_size to be evaluated. Allows multiple energies to be evaluated simultaneously to then numerically evaluate spatial integrals.

frequency_t frequency_

Numerical Values of frequencies stored in a at::Tensor. Follows convention that external frequency is stored in last element of rows. Then frequency_t object is a stack of objects of the form \((0, 0, \cdot\cdot\cdot, \nu_{ext})\).

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.

class FermiTree

The FermiTree class is a graph representation of sums and products of Fermi and Bose functions. It allows for a more natural factorization of the AMI integrand after each integration step. It provides additional numerical stability compared to the fully expanded product of Fermi/Bose functions as used in the libami implementation. It is not expected that a user should interact with the FermiTree, since it is not a pretty structure to look at and the detailed structure will depend on the labelling of a diagram.

Public Types

typedef boost::adjacency_list<boost::vecS, boost::listS, boost::bidirectionalS, vertex_info, edge_info, graph_info> fermi_tree_t

Boost Adjacency list used to manage fermi tree structure.

struct edge_info
struct graph_info
struct vertex_info
struct ft_term

Both the initial integrand and intermediate steps can be written as a fermi-tree_term ft_term. Non-factorizable terms will spawn additional terms. Includes a prefactor, a fermi_tree_t and a g_prod_t.

Public Members

double sign_ = 1

Sign prefactor.

TamiBase::FermiTree::fermi_tree_t ft_

List of poles, \( \prod{f(p_i)}\).

TamiBase::g_prod_t g_prod_

List of Green’s functions, \( \prod{G_j}\).

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. Nearly equivalent to g_struct, but given its own struct for clarity. 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}\).

class TamiGraph

Class for loading, labelling and converting a Feynman diagram to input for torchami. See examples for usage.

Public Functions

void graph_read(std::string filename, graph_t &g)

The graph read function is an example that can be used to generate graphs based on source-target format files. See examples for usage.

void sys_label(graph_t &g, bool &result)

The most robust labelling tool - recommended to use this directly and not ggm_label function.

void generate_sigma_ct(graph_t &g_in, std::vector<graph_t> &ct_vec, int maxdots)

Function to generate self energy counter-term diagrams for renormalized PT problems.

void find_external_vertices(graph_t &g, vertex_vector_t &v, edge_vector_t &edges)

This finds the vertices that are external - use with caution.

struct bubble
struct edge_info
struct git_pair
struct graph_group
struct graph_info
struct trojan_graph

This is a graph structure needed for compatibility with pybind11. See pyami_src directory.

struct vertex_info