g2tools Module

Moments

The main tools for creating and manipulating moments are:

g2tools.moments(G, Z=1.0, ainv=1.0, periodic=True, tmin=None, nlist=[4, 6, 8, 10, 12, 14, 16, 18, 20])

Compute t**n moments of correlator G.

Compute sum_t t**n G(t) for n in nlist, where both positive and negative t are included.

Parameters:
  • G – Array of correlator values G[t] for t=0,1... (in lattice units).
  • Z – Renormalization factor for current (moments multiplied by Z**2). Defaul is 1.
  • ainv – Inverse lattice spacing used to convert moments to physical units (n-th moment multiplied by 1/ainv**(n-2)). Default is 1.
  • periodic – periodic=True implies G[-t] = G[t] (default); periodic=False implies no periodicity in array G[t] (and results doubled to account for negative t).
  • tmin – minimum t value included in moments; ignored if None (default).
  • nlist – List of moments to calculate. Default is nlist=[4,6,8...20].
Returns:

Dictionary Gmom where Gmom[n] is the n-th moment.
g2tools.mom2taylor(mom)

Convert moments in dictionary mom into Taylor series coefficients.

g2tools.taylor2mom(tayl)

Convert Taylor coefficients in array tayl to moments.

Subtracted Vacuum Polarization

A subtracted vacuum polarization function (Pi-hat) is represented by the following classes:

class g2tools.vacpol(g, order=None, scale=None, rtol=None, qth=0, warn=True, exceptions=True)

Subtracted vac. pol’n (Pi-hat(q2)) from correlator moments Gmon[n].

The current-current correlator is q2 * Pi(q2), where Pi-hat(q2) = Pi(q2) - Pi(0) is the subtracted (i.e., renormalized) vacuum polariztion function.

The vacuum polarization function is a Pade approximant to the Taylor series corresponding to the moments g[n]. The code estimates the precision of the moments and sets the tolerance for the Pade determination accordingly. The order (m,n) of the Pade can be specified, but might be reduced by the code if the data are noisy.

vacpol objects are used primarily as functions (of q2) but also have several attributes. Attribute pseries is a dictionary containing various powerseries (see gvar.powerseries) describing the function: the vacuum polarization function is q2 times a Pade approximant with a numerator given by pseries['num'] and a denominator given by pseries['den']. The Taylor series for this function is given by q2 times pseries['taylor'].

vacpol objects also have a method vacpol.badpoles() that tests the poles in the denomator of the Pade. badpoles(qth) returns False if any of the poles is complex or if any are located above -(qth ** 2). qth should be set equal to the threshold energy for the correlator. If it is unset, qth=0 is used. Lists of the poles and their residues (for Pi-hat(q2)) are available in attributes pole and residue, respectively.

vacpol has several static methods for creating specialized examples of vacuum polarizations (e.g., for testing):

  • vacpol.fermion(m) – 1-loop fermion (mass m) contribution;
  • vacpol.scalar(m) – 1-loop scalar (mass m) contribution;
  • vacpol.vector(m, f) – tree-level contribution from vector
    with mass m and decay constant f.
Parameters:
  • g – Dictionary containing moments where g[n] = sum_t t**n G(t), or array containing Taylor coefficients where Pi-hat(q2) = q2 * sum_j q2**j * g[j].
  • order – Tuple (m,n) specifying the order of the Pade approximant used to approximate Pi-hat(q2) (the function is approximated by q2 times an (m-1,n) approximant). The order may be reduced (automatically) if the data are too noisy. If the order is not specified, it is set automatically according to the number of entries in G.
  • scale – Scale factor used to rescale q2 so that the Taylor coefficients are more uniform in size. This is normally set automatically (from the first two moments), but the automatic value is overridden if scale is set.
  • rtol – Relative tolerance assumed when determining the Pade approximant. This is normally set automatically (from the standard deviations of the moments), but the automatic value is overridden if rtol is specified.
  • qth – Threshold for particle production: poles above -qth**2 are bad. Default is qth=0.
  • warnings – warnings=True (default) causes a warning to be issued when the order has been reduced automatically. warnings=False suppresses the warnings.
  • exceptions – If True (default), an exception is raised if there are bad poles in the vacpol. If False, exceptions are suppressed.

Methods include:

taylor(n=None)

Return Taylor coefficients for PI-hat(q2)/q2.

Parameters:n – Maximum number of coefficients returned. Returns all coefficents if None (default)/
badpoles(qth=None)

True if any pole is complex or above threshold.

Parameters:qth – Threshold for particle production: poles above -qth**2 are bad. (Default is qth=0.)
FT(t, ainv=1.0)

Fourier transform of q2 * PI-hat(q2).

The Pade approximant can be decomposed into a sum of poles (partial fractions), which give a sum of decaying exponentials when Fourier transformed back to t-space. The amplitudes and energies of these exponentials (for the transform of q2 * Pi-hat(q2)'') are stored in :class:`g2tools.vacpol` attributes ``E and ampl, respectively.

The decomposition into a sum of poles leaves a residual polynomial in q2 (zeroth-order for (n,n) Pades). This is ignored in the Fourier transform since it typically affects the transform only for very small t. These terms have a negligible effect (suppressed by a**2j on the Taylor coefficients Pi[j] of Pi-hat(q2) (for j>=1).

Optional parameter ainv can be used to convert the Fourier transform to lattice units (by multiplying it by 1/ainv**3) for comparison with simulation data. The times t are then assumed to be in lattice units.

Parameters:
  • t (number, array) – Time in physical units unless ainv is specified, in which case lattice units are assumed.
  • ainv – Inverse lattice spacing. The Fourier transform is in lattice units if ainv is specified (assuming the original Taylor coefficients are in physical units).
static scalar(m, n=10, use_pade=False)

1-loop subt. vac. pol’n from a scalar with mass m (and charge=1).

static fermion(m, n=19, use_pade=False)

1-loop subt. vac. pol’n from a fermion with mass m (and charge=1).

static vector(m, f=1.0, n=10, use_pade=False)

Vac. pol’n due to a vector with mass m and decay const. f.

The decay constant is defined such that the vacuum polarization function is Pi-hat = q2 * f**2/2/m**2 / (q2 + m**2). This corresponds in t space to ``m * f**2 * exp(-m * t) / 4’‘.

class g2tools.fourier_vacpol(G, Z=1.0, ainv=1.0, periodic=True)

Subtracted vac. pol’n (Pi-hat(q2)) from correlator G(t).

The correlator is Fourier transformed to produce a function Pi_hat of (Euclidean) q2 suitable for use in g2tools.a_mu().

See Bernecker & Meyer, EPJA47 (2011) 148 , arXiv:1107.4388 for details on the Fouier transformation.

Parameters:
  • G (array) – Current-current correlator in an array whose elements are [G(0),G(a),G(2*a),...,G(-2*a),G(-a)] if periodic=True or [G(0),G(a),...,G(T*a-1)] otherwise. G is assumed to be in lattice units.
  • Z – Renormalization factor for current (correlator multiplied by Z**2). Defaul is 1.
  • ainv – Inverse lattice spacing used to convert Fourier transform to physical units. Default is 1.
  • periodic – periodic=True implies G[-t] = G[t] (default); periodic=False implies G[t] is not periodic and is specified for only non-negative t values (results are doubled to account for negative t).

Padé Approximants

The following two functions are used for calculating Padé approximants from the Taylor coefficients of an arbitrary function. The first (g2tools.pade_svd()) implements an algorithm that uses svd cuts to address instabilities caused by uncertainties in the Taylor coefficients. The second function (g2tools.pade_gvar()) is built on the first but allows Taylor coefficients to have uncertainties (gvar.GVars). The statistical uncertainties and correlations between different coefficients are propagated through the analysis.

g2tools.pade_svd(f, m, n, rtol=1e-14)

[m,n] Pade approximant to sum_i f[i] x**i.

The [m,n] Pade approximant to a series given by sum_i f[i] * x**i is the ratio of polynomials of order m (numerator) and n (denominator) whose Taylor expansion agrees with that of the original series up to order m+n.

This code is adapted from P. Gonnet, S. Guttel, L. N. Trefethen, SIAM Review Vol 55, No. 1, 101 (2013). It uses an svd algorithm to deal with imprecision in the input data, here specified by the relative tolerance rtol for the input coefficients f[i]. It automatically reduces the order of the approximant if the extraction of Pade coefficients is too unstable given tolerance rtol.

Parameters:
  • f – Array f[i] of power series coefficients for i=0...n+m.
  • m – Maximum order of polynomial in numerator of Pade approximant (m>=0).
  • n – Maximum order of polynomial in denominator of Pade approximant (m>=0).
  • rtol – Relative accuracy of input coefficients. (Default is 1e-14.)
Returns:

Tuple of power series coefficients (p, q) such that sum_i p[i] x**i is the numerator of the approximant, and sum_i q[i] x**i is the denominator. q[0] is normalized to 1.
g2tools.pade_gvar(f, m, n, rtol='gavg')

[m,n] Pade approximant to sum_i f[i] x**i for GVars.

The [m,n] Pade approximant to a series given by sum_i f[i] * x**i is the ratio of polynomials of order m (numerator) and n (denominator) whose Taylor expansion agrees with that of the original series up to order m+n.

This code uses an SVD algorithm (see pade_svd()) to deal with imprecision in the input data. It automatically reduces the order of the approximant if the extraction of Pade coefficients is too unstable given noise in the input data.

Parameters:
  • f – Array f[i] of power series coefficients for i=0...n+m.
  • m – Maximum order of polynomial in numerator of Pade approximant (m>=0).
  • n – Maximum order of polynomial in denominator of Pade approximant (m>=0).
  • rtol (float or str) – If rtol is a string, it determines how the relative tolerance is determined from the relative uncertainties in the f[i]. Set rtol equal to: 'gavg' for the geometric mean (default); 'avg' for the average; 'min' for the minimum; or 'max' for the maximum. Otherwise a number can be specified, in which case the uncertainties in f[i] are ignored.
Returns:

Tuple of power series coefficients (p, q) such that sum_i p[i] x**i is the numerator of the approximant, and sum_i q[i] x**i is the denominator. q[0] is normalized to 1.