5. Reference Guide¶

This section describes all public functions and classes in pySecDec.

5.1. Algebra¶

Implementation of a simple computer algebra system.

class pySecDec.algebra.Exp(arg, copy=True)¶

The real valued exponential function. Store the expressions exp(arg).

Parameters:

arg – _Expression; The argument of the exponential function.
copy – bool; Whether or not to copy the arg.

copy()¶: Return a copy of a Exp.

derive(index)¶

Generate the derivative by the parameter indexed index.

Parameters:: index – integer; The index of the parameter to derive by.

replace(index, value, remove=False)¶

Replace a variable in an expression by a number or a symbol. The entries in all expolist of the underlying Polynomial are set to zero. The coefficients are modified according to value and the powers indicated in the expolist.

Parameters:

expression – _Expression; The expression to replace the variable.
index – integer; The index of the variable to be replaced.
value – number or sympy expression; The value to insert for the chosen variable.
remove – bool; Whether or not to remove the replaced parameter from the parameters in the expression.

simplify()¶: Apply exp(0) = 1.

class pySecDec.algebra.ExponentiatedPolynomial(expolist, coeffs, exponent=1, polysymbols='x', copy=True)¶

Like Polynomial, but with a global exponent. $polynomial^{exponent}$

Parameters:

expolist – iterable of iterables; The variable’s powers for each term.
coeffs – iterable; The coefficients of the polynomial.
exponent – object, optional; The global exponent.
polysymbols –
iterable or string, optional; The symbols to be used for the polynomial variables when converted to string. If a string is passed, the variables will be consecutively numbered.
For example: expolist=[[2,0],[1,1]] coeffs=[“A”,”B”]
- polysymbols=’x’ (default) <-> “A*x0**2 + B*x0*x1”
- polysymbols=[‘x’,’y’] <-> “A*x**2 + B*x*y”
copy –
bool; Whether or not to copy the expolist, the coeffs, and the exponent.

Note

If copy is False, it is assumed that the expolist, the coeffs and the exponent have the correct type.

copy()¶: Return a copy of a Polynomial or a subclass.

derive(index)¶

Generate the derivative by the parameter indexed index.

Parameters:: index – integer; The index of the parameter to derive by.

static from_expression(*args, **kwargs)¶

Alternative constructor. Construct the polynomial from an algebraic expression.

Parameters:

expression – string or sympy expression; The algebraic representation of the polynomial, e.g. “5*x1**2 + x1*x2”
polysymbols – iterable of strings or sympy symbols; The symbols to be interpreted as the polynomial variables, e.g. “[‘x1’,’x2’]”.

refactorize(*parameters)¶

Returns a product of the greatest factor that could be pulled out and the factorised polynomial.

Parameters:: parameter – arbitrarily many integers;

simplify()¶: Apply the identity <something>**0 = 1 or <something>**1 = <something> or 1**<something> = 1 if possible, otherwise call the simplify method of the base class. Convert exponent to symbol if possible.

pySecDec.algebra.Expression(expression, polysymbols, follow_functions=False)¶

Convert a sympy expression to an expression in terms of this module.

Parameters:

expression – string or sympy expression; The expression to be converted
polysymbols – iterable of strings or sympy symbols; The symbols to be stored as expolists (see Polynomial) where possible.
follow_functions – bool, optional (default = False); If true, return the converted expression and a list of Function that occur in the expression.

class pySecDec.algebra.Function(symbol, *arguments, **kwargs)¶

Symbolic function that can take care of parameter transformations. It keeps track of all taken derivatives: When derive() is called, save the multiindex of the taken derivative.

The derivative multiindices are the keys in the dictionary self.derivative_tracks. The values are lists with two elements: Its first element is the index to derive the derivative indicated by the multiindex in the second element by, in order to abtain the derivative indicated by the key:

>>> from pySecDec.algebra import Polynomial, Function
>>> x = Polynomial.from_expression('x', ['x','y'])
>>> y = Polynomial.from_expression('y', ['x','y'])
>>> poly = x**2*y + y**2
>>> func = Function('f', x, y)
>>> ddfuncd0d1 = func.derive(0).derive(1)
>>> func
Function(f( + (1)*x, + (1)*y), derivative_tracks = {(1, 0): [0, (0, 0)], (1, 1): [1, (1, 0)]})
>>> func.derivative_tracks
{(1, 0): [0, (0, 0)], (1, 1): [1, (1, 0)]}
>>> func.compute_derivatives(poly)
{(1, 0):  + (2)*x*y, (1, 1):  + (2)*x}

Parameters:

symbol – string; The symbol to be used to represent the Function.
arguments – arbitrarily many _Expression; The arguments of the Function.
copy – bool; Whether or not to copy the arguments.

compute_derivatives(expression=None)¶

Compute all derivatives of expression that are mentioned in self.derivative_tracks. The purpose of this function is to avoid computing the same derivatives multiple times.

Parameters:: expression – _Expression, optional; The expression to compute the derivatives of. If not provided, the derivatives are shown as in terms of the function’s derivatives dfd<index>.

copy()¶: Return a copy of a Function.

derive(index)¶

Generate the derivative by the parameter indexed index. The derivative of a function with symbol f by some index is denoted as dfd<index>.

Parameters:: index – integer; The index of the parameter to derive by.

replace(index, value, remove=False)¶

Replace a variable in an expression by a number or a symbol. The entries in all expolist of the underlying Polynomial are set to zero. The coefficients are modified according to value and the powers indicated in the expolist.

Parameters:

expression – _Expression; The expression to replace the variable.
index – integer; The index of the variable to be replaced.
value – number or sympy expression; The value to insert for the chosen variable.
remove – bool; Whether or not to remove the replaced parameter from the parameters in the expression.

simplify()¶: Simplify the arguments.

class pySecDec.algebra.Log(arg, copy=True)¶

The (natural) logarithm to base e (2.718281828459..). Store the expressions log(arg).

Parameters:

arg – _Expression; The argument of the logarithm.
copy – bool; Whether or not to copy the arg.

copy()¶: Return a copy of a Log.

derive(index)¶

Generate the derivative by the parameter indexed index.

Parameters:: index – integer; The index of the parameter to derive by.

replace(index, value, remove=False)¶

Replace a variable in an expression by a number or a symbol. The entries in all expolist of the underlying Polynomial are set to zero. The coefficients are modified according to value and the powers indicated in the expolist.

Parameters:

expression – _Expression; The expression to replace the variable.
index – integer; The index of the variable to be replaced.
value – number or sympy expression; The value to insert for the chosen variable.
remove – bool; Whether or not to remove the replaced parameter from the parameters in the expression.

simplify()¶: Apply log(1) = 0.

class pySecDec.algebra.LogOfPolynomial(expolist, coeffs, polysymbols='x', copy=True)¶

The natural logarithm of a Polynomial.

Parameters:

expolist – iterable of iterables; The variable’s powers for each term.
coeffs – iterable; The coefficients of the polynomial.
exponent – object, optional; The global exponent.
polysymbols –
iterable or string, optional; The symbols to be used for the polynomial variables when converted to string. If a string is passed, the variables will be consecutively numbered.
For example: expolist=[[2,0],[1,1]] coeffs=[“A”,”B”]
- polysymbols=’x’ (default) <-> “A*x0**2 + B*x0*x1”
- polysymbols=[‘x’,’y’] <-> “A*x**2 + B*x*y”

derive(index)¶

Generate the derivative by the parameter indexed index.

Parameters:: index – integer; The index of the parameter to derive by.

static from_expression(expression, polysymbols)¶

Alternative constructor. Construct the LogOfPolynomial from an algebraic expression.

Parameters:

expression – string or sympy expression; The algebraic representation of the polynomial, e.g. “5*x1**2 + x1*x2”
polysymbols – iterable of strings or sympy symbols; The symbols to be interpreted as the polynomial variables, e.g. “[‘x1’,’x2’]”.

simplify()¶: Apply the identity log(1) = 0, otherwise call the simplify method of the base class.

class pySecDec.algebra.Polynomial(expolist, coeffs, polysymbols='x', copy=True)¶

Container class for polynomials. Store a polynomial as list of lists counting the powers of the variables. For example the polynomial “x1**2 + x1*x2” is stored as [[2,0],[1,1]].

Coefficients are stored in a separate list of strings, e.g. “A*x0**2 + B*x0*x1” <-> [[2,0],[1,1]] and [“A”,”B”].

Parameters:

expolist –
iterable of iterables; The variable’s powers for each term.

Hint

Negative powers are allowed.
coeffs – 1d array-like with numerical or sympy-symbolic (see http://www.sympy.org/) content, e.g. [x,1,2] where x is a sympy symbol; The coefficients of the polynomial.
polysymbols –
iterable or string, optional; The symbols to be used for the polynomial variables when converted to string. If a string is passed, the variables will be consecutively numbered.
For example: expolist=[[2,0],[1,1]] coeffs=[“A”,”B”]
- polysymbols=’x’ (default) <-> “A*x0**2 + B*x0*x1”
- polysymbols=[‘x’,’y’] <-> “A*x**2 + B*x*y”
copy –
bool; Whether or not to copy the expolist and the coeffs.

Note

If copy is False, it is assumed that the expolist and the coeffs have the correct type.

becomes_zero_for(zero_params)¶

Return True if the polynomial becomes zero if the parameters passed in zero_params are set to zero. Otherwise, return False.

Parameters:: zero_params – iterable of integers; The indices of the parameters to be checked.

copy()¶: Return a copy of a Polynomial or a subclass.

denest()¶: Returns a flattened version of a nested Polynomial of Polynomials.

derive(index)¶

Generate the derivative by the parameter indexed index.

Parameters:: index – integer; The index of the parameter to derive by.

static from_expression(expression, polysymbols)¶

Alternative constructor. Construct the polynomial from an algebraic expression.

Parameters:

expression – string or sympy expression; The algebraic representation of the polynomial, e.g. “5*x1**2 + x1*x2”
polysymbols – iterable of strings or sympy symbols; The symbols to be interpreted as the polynomial variables, e.g. “[‘x1’,’x2’]”.

has_constant_term(indices=None)¶

Return True if the polynomial can be written as:

$const + ...$

Otherwise, return False.

Parameters:: indices – list of integers or None; The indices of the polysymbols to consider. If None (default) all indices are taken into account.

refactorize(*parameters)¶

Returns a product of the greatest factor that could be pulled out and the factorised polynomial.

Parameters:: parameter – arbitrarily many integers;

replace(index, value, remove=False)¶

Replace a variable in an expression by a number or a symbol. The entries in all expolist of the underlying Polynomial are set to zero. The coefficients are modified according to value and the powers indicated in the expolist.

Parameters:

expression – _Expression; The expression to replace the variable.
index – integer; The index of the variable to be replaced.
value – number or sympy expression; The value to insert for the chosen variable.
remove – bool; Whether or not to remove the replaced parameter from the parameters in the expression.

simplify(deep=True)¶

Combine terms that have the same exponents of the variables.

Parameters:: deep – bool; If True (default) call the simplify method of the coefficients if they are of type _Expression.

class pySecDec.algebra.Pow(base, exponent, copy=True)¶

Exponential. Store two expressions A and B to be interpreted as the exponential A**B.

Parameters:

base – _Expression; The base A of the exponential.
exponent – _Expression; The exponent B.
copy – bool; Whether or not to copy base and exponent.

copy()¶: Return a copy of a Pow.

derive(index)¶

Generate the derivative by the parameter indexed index.

Parameters:: index – integer; The index of the parameter to derive by.

replace(index, value, remove=False)¶

Replace a variable in an expression by a number or a symbol. The entries in all expolist of the underlying Polynomial are set to zero. The coefficients are modified according to value and the powers indicated in the expolist.

Parameters:

expression – _Expression; The expression to replace the variable.
index – integer; The index of the variable to be replaced.
value – number or sympy expression; The value to insert for the chosen variable.
remove – bool; Whether or not to remove the replaced parameter from the parameters in the expression.

simplify()¶: Apply the identity <something>**0 = 1 or <something>**1 = <something> or 1**<something> = 1 if possible. Convert to ExponentiatedPolynomial or Polynomial if possible.

class pySecDec.algebra.Product(*factors, **kwargs)¶

Product of polynomials. Store one or polynomials $p_i$ to be interpreted as product $\prod_i p_i$ .

Parameters:

factors – arbitrarily many instances of Polynomial; The factors $p_i$ .
copy – bool; Whether or not to copy the factors.

$p_i$ can be accessed with self.factors[i].

Example:

p = Product(p0, p1)
p0 = p.factors[0]
p1 = p.factors[1]

copy()¶: Return a copy of a Product.

derive(index)¶

Generate the derivative by the parameter indexed index. Return an instance of the optimized ProductRule.

Parameters:: index – integer; The index of the parameter to derive by.

replace(index, value, remove=False)¶

Replace a variable in an expression by a number or a symbol. The entries in all expolist of the underlying Polynomial are set to zero. The coefficients are modified according to value and the powers indicated in the expolist.

Parameters:

expression – _Expression; The expression to replace the variable.
index – integer; The index of the variable to be replaced.
value – number or sympy expression; The value to insert for the chosen variable.
remove – bool; Whether or not to remove the replaced parameter from the parameters in the expression.

simplify()¶: If one or more of self.factors is a Product, replace it by its factors. If only one factor is present, return that factor. Remove factors of one and zero.

class pySecDec.algebra.ProductRule(*expressions, **kwargs)¶

Store an expression of the form

$\sum_i c_i \prod_j \prod_k \left( \frac{d}{dx_k} \right)^{n_{ijk}} f_j \left( \lbrace x_k \rbrace \right)$

The main reason for introducing this class is a speedup when calculating derivatives. In particular, this class implements simplifications such that the number of terms grows less than exponentially (scaling of the naive implementation of the product rule) with the number of derivatives.

Parameters:: expressions – arbitrarily many expressions; The expressions $f_j$ .

copy()¶: Return a copy of a ProductRule.

derive(index)¶

Generate the derivative by the parameter indexed index. Note that this class is particularly designed to hold derivatives of a product.

Parameters:: index – integer; The index of the parameter to derive by.

replace(index, value, remove=False)¶

Replace a variable in an expression by a number or a symbol. The entries in all expolist of the underlying Polynomial are set to zero. The coefficients are modified according to value and the powers indicated in the expolist.

Parameters:

expression – _Expression; The expression to replace the variable.
index – integer; The index of the variable to be replaced.
value – number or sympy expression; The value to insert for the chosen variable.
remove – bool; Whether or not to remove the replaced parameter from the parameters in the expression.

simplify()¶: Combine terms that have the same derivatives of the expressions.

to_sum()¶: Convert the ProductRule to Sum

class pySecDec.algebra.Sum(*summands, **kwargs)¶

Sum of polynomials. Store one or polynomials $p_i$ to be interpreted as product $\sum_i p_i$ .

Parameters:

summands – arbitrarily many instances of Polynomial; The summands $p_i$ .
copy – bool; Whether or not to copy the summands.

$p_i$ can be accessed with self.summands[i].

Example:

p = Sum(p0, p1)
p0 = p.summands[0]
p1 = p.summands[1]

copy()¶: Return a copy of a Sum.

derive(index)¶

Generate the derivative by the parameter indexed index.

Parameters:: index – integer; The index of the parameter to derive by.

replace(index, value, remove=False)¶

Replace a variable in an expression by a number or a symbol. The entries in all expolist of the underlying Polynomial are set to zero. The coefficients are modified according to value and the powers indicated in the expolist.

Parameters:

expression – _Expression; The expression to replace the variable.
index – integer; The index of the variable to be replaced.
value – number or sympy expression; The value to insert for the chosen variable.
remove – bool; Whether or not to remove the replaced parameter from the parameters in the expression.

simplify()¶: If one or more of self.summands is a Sum, replace it by its summands. If only one summand is present, return that summand. Remove zero from sums.

pySecDec.algebra.refactorize(polyprod, *parameters)¶

In a algebra.Product of the form <monomial> * <polynomial>, check if a parameter in <polynomial> can be shifted to the <monomial>. If possible, modify polyprod accordingly.

Parameters:

polyprod – algebra.Product of the form <monomial> * <polynomial>`; The product to refactorize.
parameter – integer, optional; Check only the parameter with this index. If not provided, all parameters are checked.

5.2. Loop Integral¶

This module defines routines to Feynman parametrize a loop integral and build a c++ package that numerically integrates over the sector decomposed integrand.

5.2.1. Feynman Parametrization¶

Routines to Feynman parametrize a loop integral.

class pySecDec.loop_integral.LoopIntegral(*args, **kwargs)¶

Container class for loop integrals. The main purpose of this class is to convert a loop integral from the momentum representation to the Feynman parameter representation.

It is possible to provide either the graph of the loop integrals as adjacency list, or the propagators.

The Feynman parametrized integral is a product of the following expressions that are accessible as member properties:

self.Gamma_factor
self.exponentiated_U
self.exponentiated_F
self.numerator
self.measure,

where self is an instance of either LoopIntegralFromGraph or LoopIntegralFromPropagators.

When inverse propagators or nonnumerical propagator powers are present (see powerlist), some Feynman_parameters drop out of the integral. The variables to integrate over can be accessed as self.integration_variables.

While self.numerator describes the numerator polynomial generated by tensor numerators or inverse propagators, self.measure contains the monomial associated with the integration measure in the case of propagator powers $\neq 1$ . The Gamma functions in the denominator belonging to the measure, however, are multiplied to the overall Gamma factor given by self.Gamma_factor.

Changed in version 1.2.2: The overall sign $(-1)^{N_\nu}$ is included in self.Gamma_factor.

See also

input as graph: LoopIntegralFromGraph
input as list of propagators: LoopIntegralFromPropagators

class pySecDec.loop_integral.LoopIntegralFromGraph(internal_lines, external_lines, replacement_rules=[], Feynman_parameters='x', regulators=None, regulator=None, dimensionality='4-2*eps', powerlist=[])¶

Construct the Feynman parametrization of a loop integral from the graph using the cut construction method.

Example:

>>> from pySecDec.loop_integral import *
>>> internal_lines = [['0',[1,2]], ['m',[2,3]], ['m',[3,1]]]
>>> external_lines = [['p1',1],['p2',2],['-p12',3]]
>>> li = LoopIntegralFromGraph(internal_lines, external_lines)
>>> li.exponentiated_U
( + (1)*x0 + (1)*x1 + (1)*x2)**(2*eps - 1)
>>> li.exponentiated_F
( + (m**2)*x2**2 + (2*m**2 - p12**2)*x1*x2 + (m**2)*x1**2 + (m**2 - p1**2)*x0*x2 + (m**2 - p2**2)*x0*x1)**(-eps - 1)

Parameters:

internal_lines – iterable of internal line specification, consisting of string or sympy expression for mass and a pair of strings or numbers for the vertices, e.g. [['m', [1,2]], ['0', [2,1]]].
external_lines – iterable of external line specification, consisting of string or sympy expression for external momentum and a strings or number for the vertex, e.g. [['p1', 1], ['p2', 2]].
replacement_rules – iterable of iterables with two strings or sympy expressions, optional; Symbolic replacements to be made for the external momenta, e.g. definition of Mandelstam variables. Example: [('p1*p2', 's'), ('p1**2', 0)] where p1 and p2 are external momenta. It is also possible to specify vector replacements, for example [('p4', '-(p1+p2+p3)')].
Feynman_parameters – iterable or string, optional; The symbols to be used for the Feynman parameters. If a string is passed, the Feynman parameter variables will be consecutively numbered starting from zero.
regulators –
list of strings or sympy symbol, optional; The symbols to be used for the regulators (typically $\epsilon$ or $\epsilon_D$ )

Note

If you change the dimensional regulator symbol, you have to adapt the dimensionality accordingly.
regulator – a string or a sympy symbol, optional; Deprecated; same as setting regulators to a list of a single element.
dimensionality – string or sympy expression, optional; The dimensionality; typically $4-2\epsilon$ , which is the default value.
powerlist – iterable, optional; The powers of the propergators, possibly dependent on the regulators. In case of negative powers, the numerator is constructed by taking derivatives with respect to the corresponding Feynman parameters as explained in Section 3.2.4 of Ref. [BHJ+15]. If negative powers are combined with a tensor numerator, the derivatives act on the Feynman-parametrized tensor numerator as well, which leads to a consistent result.

class pySecDec.loop_integral.LoopIntegralFromPropagators(propagators, loop_momenta, external_momenta=[], Lorentz_indices=[], numerator=1, metric_tensor='g', replacement_rules=[], Feynman_parameters='x', regulators=None, regulator=None, dimensionality='4-2*eps', powerlist=[])¶

Construct the Feynman parametrization of a loop integral from the algebraic momentum representation.

See also

[Hei08], [GKR+11]

Example:

>>> from pySecDec.loop_integral import *
>>> propagators = ['k**2', '(k - p)**2']
>>> loop_momenta = ['k']
>>> li = LoopIntegralFromPropagators(propagators, loop_momenta)
>>> li.exponentiated_U
( + (1)*x0 + (1)*x1)**(2*eps - 2)
>>> li.exponentiated_F
( + (-p**2)*x0*x1)**(-eps)

The 1st (U) and 2nd (F) Symanzik polynomials and their exponents can also be accessed independently:

>>> li.U
 + (1)*x0 + (1)*x1
>>> li.F
 + (-p**2)*x0*x1
>>>
>>> li.exponent_U
2*eps - 2
>>> li.exponent_F
-eps

Parameters:

propagators – iterable of strings or sympy expressions; The propagators, e.g. ['k1**2', '(k1-k2)**2 - m1**2'].
loop_momenta – iterable of strings or sympy expressions; The loop momenta, e.g. ['k1','k2'].
external_momenta –
iterable of strings or sympy expressions, optional; The external momenta, e.g. ['p1','p2']. Specifying the external_momenta is only required when a numerator is to be constructed.

See also

parameter numerator
Lorentz_indices –
iterable of strings or sympy expressions, optional; Symbols to be used as Lorentz indices in the numerator.

See also

parameter numerator
numerator –
string or sympy expression, optional; The numerator of the loop integral. Scalar products must be passed in index notation e.g. k1(mu)*k2(mu). The numerator must be a sum of products of exclusively:
- numbers
- scalar products (e.g. p1(mu)*k1(mu)*p1(nu)*k2(nu))
- symbols (e.g. s, eps)
Examples:
- p1(mu)*k1(mu)*p1(nu)*k2(nu) + 4*s*eps*k1(mu)*k1(mu)
- p1(mu)*(k1(mu) + k2(mu))*p1(nu)*k2(nu)
- p1(mu)*k1(mu)
Note

In order to use the resulting LoopIntegral as an argument to the function pySecDec.loop_integral.loop_package(), the resulting Feynman parametrized self.numerator must be expressible as a pySecDec.algebra.Polynomial such that all coefficients are purely numeric. In addition, all scalar products of the external momenta must be expressed in terms of Mandelstam variables using the replacement_rules.

Warning

All Lorentz indices (including the contracted ones and also including the numbers that have been used) must be explicitly defined using the parameter Lorentz_indices.

Hint

It is possible to use numbers as indices, for example p1(mu)*p2(mu)*k1(nu)*k2(nu) = p1(1)*p2(1)*k1(2)*k2(2).

Hint

The numerator may have uncontracted indices, e.g. k1(mu)*k2(nu). If indices are left open, however, the LoopIntegral cannot be used with the package generator pySecDec.loop_integral.loop_package().
metric_tensor – string or sympy symbol, optional; The symbol to be used for the (Minkowski) metric tensor $g^{\mu\nu}$ .
replacement_rules – iterable of iterables with two strings or sympy expressions, optional; Symbolic replacements to be made for the external momenta, e.g. definition of Mandelstam variables. Example: [('p1*p2', 's'), ('p1**2', 0)] where p1 and p2 are external momenta. It is also possible to specify vector replacements, for example [('p4', '-(p1+p2+p3)')].
Feynman_parameters – iterable or string, optional; The symbols to be used for the Feynman parameters. If a string is passed, the Feynman parameter variables will be consecutively numbered starting from zero.
regulators –
list of strings or sympy symbol, optional; The symbols to be used for the regulators (typically $\epsilon$ or $\epsilon_D$ )

Note

If you change the dimensional regulator symbol, you have to adapt the dimensionality accordingly.
regulator – a string or a sympy symbol, optional; Deprecated; same as setting regulators to a list of a single element.
dimensionality – string or sympy expression, optional; The dimensionality; typically $4-2\epsilon$ , which is the default value.
powerlist – iterable, optional; The powers of the propergators, possibly dependent on the regulators. In case of negative powers, the numerator is constructed by taking derivatives with respect to the corresponding Feynman parameters as explained in Section 3.2.4 of Ref. [BHJ+15]. If negative powers are combined with a tensor numerator, the derivatives act on the Feynman-parametrized tensor numerator as well, which leads to a consistent result.

5.2.2. Loop Package¶

This module contains the function that generates a c++ package.

pySecDec.loop_integral.loop_package(name, loop_integral, requested_orders=None, requested_order=None, real_parameters=[], complex_parameters=[], contour_deformation=True, additional_prefactor=1, form_optimization_level=2, form_work_space='50M', form_memory_use=None, form_threads=1, decomposition_method='geometric', normaliz_executable=None, enforce_complex=False, split=False, ibp_power_goal=-1, use_iterative_sort=True, use_light_Pak=True, use_dreadnaut=False, use_Pak=True, processes=None, pylink_qmc_transforms=['korobov3x3'], package_generator=<function make_package>)¶

Decompose, subtract and expand a Feynman parametrized loop integral. Return it as c++ package.

See also

This function is a wrapper around pySecDec.make_package() (default).

See also

The generated library is described in Generated C++ Libraries.

Parameters:

name – string; The name of the c++ namespace and the output directory.
loop_integral – pySecDec.loop_integral.LoopIntegral; The loop integral to be computed.
requested_orders – iterable of integers; Compute the expansion in the regulators to these orders.
requested_order – integer; Deprecated; same as requested_orders set to a list of one item.
real_parameters – iterable of strings or sympy symbols, optional; Parameters to be interpreted as real numbers, e.g. Mandelstam invariants and masses.
complex_parameters – iterable of strings or sympy symbols, optional; Parameters to be interpreted as complex numbers. To use the complex mass scheme, define the masses as complex parameters.
contour_deformation – bool, optional; Whether or not to produce code for contour deformation. Default: True.
additional_prefactor – string or sympy expression, optional; An additional factor to be multiplied to the loop integral. It may depend on the regulators, the real_parameters, and the complex_parameters.
form_optimization_level – integer out of the interval [0,4], optional; The optimization level to be used in FORM. Default: 2.
form_work_space –
string, optional; The FORM WorkSpace. Default: '50M'.

Setting this to smaller values will reduce FORM memory usage (without affecting performance), but each problem has some minimum value below which FORM will refuse to work: it will fail with error message indicating that larger WorkSpace is needed, at which point WorkSpace will be adjusted and FORM will be re-run.
form_memory_use –
string, optional; The target FORM memory usage. When specified, form.set parameters will be adjusted so that FORM uses at most approximately this much resident memory.

The minimum is approximately to 600M + 350M per worker thread if form_work_space is left at '50M'. if form_work_space is increased to '500M', then the minimum is 2.5G + 2.5G per worker thread. Default: None, meaning use the default FORM values.
form_threads – integer, optional; Number of threads (T)FORM will use. Default: 1.
decomposition_method –
string, optional; The strategy for decomposing the polynomials. The following strategies are available:
- ’iterative’
- ’geometric’ (default)
- ’geometric_ku’
enforce_complex – bool, optional; Whether or not the generated integrand functions should have a complex return type even though they might be purely real. The return type of the integrands is automatically complex if contour_deformation is True or if there are complex_parameters. In other cases, the calculation can typically be kept purely real. Most commonly, this flag is needed if log(<negative real>) occurs in one of the integrand functions. However, pySecDec will suggest setting this flag to True in that case. Default: False
split – bool, optional; Whether or not to split the integration domain in order to map singularities from $1$ to $0$ . Set this option to True if you have singularties when one or more integration variables are one. Default: False
ibp_power_goal –
number or iterable of number, optional; The power_goal that is forwarded to integrate_by_parts().

This option controls how the subtraction terms are generated. Setting it to -numpy.inf disables integrate_by_parts(), while 0 disables integrate_pole_part().

See also

To generate the subtraction terms, this function first calls integrate_by_parts() for each integration variable with the give ibp_power_goal. Then integrate_pole_part() is called.

Default: -1
use_iterative_sort – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with iterative_sort() to find sector symmetries. Default: True
use_light_Pak – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with light_Pak_sort() to find sector symmetries. Default: True
use_dreadnaut – bool or string, optional; Whether or not to use squash_symmetry_redundant_sectors_dreadnaut() to find sector symmetries. If given a string, interpret that string as the command line executable dreadnaut. If True, try $SECDEC_CONTRIB/bin/dreadnaut and, if the environment variable $SECDEC_CONTRIB is not set, dreadnaut. Default: False
use_Pak – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with Pak_sort() to find sector symmetries. Default: True
processes – integer or None, optional; The maximal number of processes to be used. If None, the number of CPUs multiprocessing.cpu_count() is used. New in version 1.3. Default: None
pylink_qmc_transforms –
list or None, optional; Required qmc integral transforms, options are:
- none
- baker
- korobovx<j> for 1 <= i,j <= 6
- korobov for 1 <= i <= 6 (same as korobovx)
- sidi for 1 <= i <= 6
New in version 1.5. Default: ['korobov3x3']
package_generator –
function; The generator function for the integral, either pySecDec.make_package() or pySecDec.code_writer.make_package().

Default: pySecDec.make_package().

5.2.3. Drawing Feynman Diagrams¶

Use the following function to draw Feynman diagrams.

pySecDec.loop_integral.draw.plot_diagram(internal_lines, external_lines, filename, powerlist=None, neato='neato', extension='pdf', Gstart=0)¶

Draw a Feynman diagram using Graphviz (neato).

Thanks to Viktor Papara <papara@mpp.mpg.de> for his major contributions to this function.

Note

This function requires the command line tool neato. See also Drawing Feynman Diagrams with neato.

Warning

The target is overwritten without prompt if it exists already.

Parameters:

internal_lines – list; Adjacency list of internal lines, e.g. [['m',['a',4]],['m',[4,5]], ['m',['a',5]],[0,[1,2]],[0,[4,1]],[0,[2,5]]]
external_lines – list; Adjacency list of external lines, e.g. [[‘p1’,1],[‘p2’,2],[‘p3’,’a’]]
filename – string; The name of the output file. The generated file gets this name plus the file extension.
powerlist – list, optional; The powers of the propagators defined by the internal_lines.
neato – string, default: “neato”; The shell command to call “neato”.
extension – string, default: “pdf”; The file extension. This also defines the output format.
Gstart – nonnegative int; The is value is passed to “neato” with the “-Gstart” option. Try changing this value if the visualization looks bad.

5.2.4. Loop Regions¶

Applies the expansion by regions method to a loop integral.

pySecDec.loop_integral.loop_regions(name, loop_integral, smallness_parameter, expansion_by_regions_order=0, contour_deformation=True, additional_prefactor=1, form_optimization_level=2, form_work_space='500M', form_memory_use=None, form_threads=1, extra_regulator_name=None, extra_regulator_exponent=None, decomposition_method='iterative', normaliz_executable=None, enforce_complex=False, split=False, ibp_power_goal=-1, use_iterative_sort=True, use_light_Pak=True, use_dreadnaut=False, use_Pak=True, processes=None)¶

Apply expansion by regions method to the loop integral using the function.

See also

This function is a wrapper around pySecDec.make_regions().

See also

The generated library is described in Generated C++ Libraries.

Parameters:

name – string; The name of the c++ namespace and the output directory.
loop_integral – pySecDec.loop_integral; The loop integral to which the expansion by regions method is applied.
smallness_parameter – string or sympy symbol; The symbol of the variable in which the expression is expanded.
expansion_by_regions_order – integer; The order up to which the expression is expanded in the smallness_parameter. Default: 0
contour_deformation – bool, optional; Whether or not to produce code for contour deformation. Default: True.
additional_prefactor – string or sympy expression, optional; An additional factor to be multiplied to the loop integral. It may depend on the regulators, the real_parameters, and the complex_parameters.
form_optimization_level – integer out of the interval [0,4], optional; The optimization level to be used in FORM. Default: 2.
form_work_space –
string, optional; The FORM WorkSpace. Default: '50M'.

Setting this to smaller values will reduce FORM memory usage (without affecting performance), but each problem has some minimum value below which FORM will refuse to work: it will fail with error message indicating that larger WorkSpace is needed, at which point WorkSpace will be adjusted and FORM will be re-run.
form_memory_use –
string, optional; The target FORM memory usage. When specified, form.set parameters will be adjusted so that FORM uses at most approximately this much resident memory.

The minimum is approximately to 600M + 350M per worker thread if form_work_space is left at '50M'. if form_work_space is increased to '500M', then the minimum is 2.5G + 2.5G per worker thread. Default: None, meaning use the default FORM values.
form_threads – integer, optional; Number of threads (T)FORM will use. Default: 2.
extra_regulator_name – string or sympy symbol, optional; Name of the regulator using which monomial factors of the form $x_i**(n*p_i)$ are added, to regulate the integrals arising from the expansion by regions.
extra_regulator_exponent – list of integers or sympy rationals, optional; List of the $p_i$ factors of the extra regulator.
decomposition_method –
string, optional; The strategy for decomposing the polynomials. The following strategies are available:
- ’iterative’ (default)
- ’geometric’
- ’geometric_ku’
normaliz_executable – string, optional; The command to run normaliz. normaliz is only required if decomposition_method starts with ‘geometric’. Default: use normaliz from pySecDecContrib
enforce_complex – bool, optional; Whether or not the generated integrand functions should have a complex return type even though they might be purely real. The return type of the integrands is automatically complex if contour_deformation is True or if there are complex_parameters. In other cases, the calculation can typically be kept purely real. Most commonly, this flag is needed if log(<negative real>) occurs in one of the integrand functions. However, pySecDec will suggest setting this flag to True in that case. Default: False
split – bool, optional; Whether or not to split the integration domain in order to map singularities from $1$ to $0$ . Set this option to True if you have singularties when one or more integration variables are one. Default: False
ibp_power_goal –
number or iterable of number, optional; The power_goal that is forwarded to integrate_by_parts().

This option controls how the subtraction terms are generated. Setting it to -numpy.inf disables integrate_by_parts(), while 0 disables integrate_pole_part().

See also

To generate the subtraction terms, this function first calls integrate_by_parts() for each integration variable with the give ibp_power_goal. Then integrate_pole_part() is called.

Default: -1
use_iterative_sort – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with iterative_sort() to find sector symmetries. Default: True
use_light_Pak – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with light_Pak_sort() to find sector symmetries. Default: True
use_dreadnaut – bool or string, optional; Whether or not to use squash_symmetry_redundant_sectors_dreadnaut() to find sector symmetries. If given a string, interpret that string as the command line executable dreadnaut. If True, try $SECDEC_CONTRIB/bin/dreadnaut and, if the environment variable $SECDEC_CONTRIB is not set, dreadnaut. Default: False
use_Pak – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with Pak_sort() to find sector symmetries. Default: True
processes – integer or None, optional; The maximal number of processes to be used. If None, the number of CPUs multiprocessing.cpu_count() is used. New in version 1.3. Default: None

5.3. Polytope¶

The polytope class as required by pySecDec.make_regions and pySecDec.decomposition.geometric.

class pySecDec.polytope.Polytope(vertices=None, facets=None)¶

Representation of a polytope defined by either its vertices or its facets. Call complete_representation() to translate from one to the other representation.

Parameters:

vertices – two dimensional array; The polytope in vertex representation. Each row is interpreted as one vertex.
facets –
two dimensional array; The polytope in facet representation. Each row represents one facet $F$ . A row in facets is interpreted as one normal vector $n_F$ with additionally the constant $a_F$ in the last column. The points $v$ of the polytope obey

$\bigcap_F \left( {\langle n_F, v \rangle} + a_F \right) \ge 0$
equations – two dimensional array; Equations defining the hyperplanes the polytope is contained in. Only non-empty for polytopes that are not full-dimensional.

complete_representation(normaliz=None, workdir='normaliz_tmp', keep_workdir=False)¶

Transform the vertex representation of a polytope to the facet representation or the other way round. Remove surplus entries in self.facets or self.vertices.

Note

This function calls the command line executable of normaliz [BIR].

Parameters:

normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an OSError is raised.

Note

The communication with normaliz is done via files.
keep_workdir – bool; Whether or not to delete the workdir after execution.

vertex_incidence_lists()¶: Return for each vertex the list of facets it lies in (as dictionary). The keys of the output dictionary are the vertices while the values are the indices of the facets in self.facets.

pySecDec.polytope.convex_hull(*polynomials)¶

Calculate the convex hull of the Minkowski sum of all polynomials in the input. The algorithm sets all coefficients to one first and then only keeps terms of the polynomial product that have coefficient 1. Return the list of these entries in the expolist of the product of all input polynomials.

Parameters:: polynomials – arbitrarily many instances of Polynomial where all of these have an equal number of variables; The polynomials to calculate the convex hull for.

pySecDec.polytope.normaliz_runcard(data, keyword, dimension)¶

Returns string containing normaliz input file.

Parameters:

data – two dimensional array; Input data.
keyword – string; Keyword specifying the type of input data. For options see normaliz documentation.
dimension – integer; Dimension of the ambient space.

pySecDec.polytope.read_normaliz_file(filepath, nofoutputs=1)¶

Read normaliz output.

Parameters:

filepath – string; Normaliz output file to be read.
nofoutputs – integer; Number of different types of output in the file to be read in.

pySecDec.polytope.run_normaliz(normaliz=None, workdir='normaliz_tmp', run_card_filename='normaliz.in', normaliz_args=[])¶

Run normaliz.

Parameters:

normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an OSError is raised.

Note

The communication with normaliz is done via files.
run_card_filename – string; File name of normaliz input file.
normaliz_args – list of strings; Normaliz command line arguments.

pySecDec.polytope.triangulate(cone, normaliz=None, workdir='normaliz_tmp', keep_workdir=False, switch_representation=False)¶

Split a cone into simplicial cones; i.e. cones defined by exactly $D$ rays where $D$ is the dimensionality.

Note

This function calls the command line executable of normaliz [BIR].

Parameters:

cone – two dimensional array; The defining rays of the cone.
normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an OSError is raised.

Note

The communication with normaliz is done via files.
keep_workdir – bool; Whether or not to delete the workdir after execution.
switch_representation – bool; Whether or not to switch between facet and vertex/ray representation.

5.4. Decomposition¶

The core of sector decomposition. This module implements the actual decomposition routines.

5.4.1. Common¶

This module collects routines that are used by multiple decompition modules.

class pySecDec.decomposition.Sector(cast, other=[], Jacobian=None)¶

Container class for sectors that arise during the sector decomposition.

Parameters:

cast – iterable of algebra.Product or of algebra.Polynomial; The polynomials to be cast to the form <monomial> * (const + …)
other – iterable of algebra.Polynomial, optional; All variable transformations are applied to these polynomials but it is not attempted to achieve the form <monomial> * (const + …)
Jacobian – algebra.Polynomial with one term, optional; The Jacobian determinant of this sector. If not provided, the according unit monomial (1*x0^0*x1^0…) is assumed.

pySecDec.decomposition.squash_symmetry_redundant_sectors_sort(sectors, sort_function, indices=None)¶

Reduce a list of sectors by squashing duplicates with equal integral.

If two sectors only differ by a permutation of the polysymbols (to be interpreted as integration variables over some interval), then the two sectors integrate to the same value. Thus we can drop one of them and count the other twice. The multiple counting of a sector is accounted for by increasing the coefficient of the Jacobian by one.

Equivalence up to permutation is established by applying the sort_function to each sector, this brings them into a canonical form. Sectors with identical canonical forms differ only by a permutation.

Note: whether all symmetries are found depends on the choice of sort_function. The sort function pySecDec.matrix_sort.Pak_sort() should find all symmetries whilst the sort functions pySecDec.matrix_sort.iterative_sort() and pySecDec.matrix_sort.light_Pak_sort() are faster but do not identify all symmetries.

Example:

>>> from pySecDec.algebra import Polynomial
>>> from pySecDec.decomposition import Sector
>>> from pySecDec.decomposition import squash_symmetry_redundant_sectors_sort
>>> from pySecDec.matrix_sort import Pak_sort
>>>
>>> poly = Polynomial([(0,1),(1,0)], ['a','b'])
>>> swap = Polynomial([(1,0),(0,1)], ['a','b'])
>>> Jacobian_poly = Polynomial([(1,0)], [3]) # three
>>> Jacobian_swap = Polynomial([(0,1)], [5]) # five
>>> sectors = (
...               Sector([poly],Jacobian=Jacobian_poly),
...               Sector([swap],Jacobian=Jacobian_swap)
...           )
>>>
>>> reduced_sectors = squash_symmetry_redundant_sectors_sort(sectors,
...                   Pak_sort)
>>> len(reduced_sectors) # symmetry x0 <--> x1
1
>>> # The Jacobians are added together to account
>>> # for the double counting of the sector.
>>> reduced_sectors[0].Jacobian
 + (8)*x0

Parameters:

sectors – iterable of Sector; the sectors to be reduced.
sort_function – pySecDec.matrix_sort.iterative_sort(), pySecDec.matrix_sort.light_Pak_sort(), or pySecDec.matrix_sort.Pak_sort(); The function to be used for finding a canonical form of the sectors.
indices – iterable of integers, optional; The indices of the variables to consider. If not provided, all indices are taken into account.

pySecDec.decomposition.squash_symmetry_redundant_sectors_dreadnaut(sectors, indices=None, dreadnaut='dreadnaut', workdir='dreadnaut_tmp', keep_workdir=False)¶

Reduce a list of sectors by squashing duplicates with equal integral.

Each Sector is converted to a Polynomial which is represented as a graph following the example of [MP+14] (v2.6 Figure 7, Isotopy of matrices).

We first multiply each polynomial in the sector by a unique tag then sum the polynomials of the sector, this converts a sector to a polynomial. Next, we convert the expolist of the resulting polynomial to a graph where each unique exponent in the expolist is considered to be a different symbol. Each unique coefficient in the polynomial`s coeffs is assigned a vertex and connected to the row vertex of any term it multiplies. The external program dreadnaut is then used to bring the graph into a canonical form and provide a hash. Sectors with equivalent hashes may be identical, their canonical graphs are compared and if they are identical the sectors are combined.

Note

This function calls the command line executable of dreadnaut [MP+14]. It has been tested with dreadnaut version nauty26r7.

Parameters:

sectors – iterable of Sector; the sectors to be reduced.
indices – iterable of integers, optional; The indices of the variables to consider. If not provided, all indices are taken into account.
dreadnaut – string; The shell command to run dreadnaut.
workdir –
string; The directory for the communication with dreadnaut. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an OSError is raised.

Note

The communication with dreadnaut is done via files.
keep_workdir – bool; Whether or not to delete the workdir after execution.

5.4.2. Iterative¶

The iterative sector decomposition routines.

exception pySecDec.decomposition.iterative.EndOfDecomposition¶: This exception is raised if the function iteration_step() is called although the sector is already in standard form.

pySecDec.decomposition.iterative.find_singular_set(sector, indices=None)¶

Function within the iterative sector decomposition procedure which heuristically chooses an optimal decomposition set. The strategy was introduced in arXiv:hep-ph/0004013 [BH00] and is described in 4.2.2 of arXiv:1410.7939 [Bor14]. Return a list of indices.

Parameters:

sector – Sector; The sector to be decomposed.
indices – iterable of integers or None; The indices of the parameters to be considered as integration variables. By default (indices=None), all parameters are considered as integration variables.

pySecDec.decomposition.iterative.iteration_step(sector, indices=None)¶

Run a single step of the iterative sector decomposition as described in chapter 3.2 (part II) of arXiv:0803.4177v2 [Hei08]. Return an iterator of Sector - the arising subsectors.

Parameters:

sector – Sector; The sector to be decomposed.
indices – iterable of integers or None; The indices of the parameters to be considered as integration variables. By default (indices=None), all parameters are considered as integration variables.

pySecDec.decomposition.iterative.iterative_decomposition(sector, indices=None)¶

Run the iterative sector decomposition as described in chapter 3.2 (part II) of arXiv:0803.4177v2 [Hei08]. Return an iterator of Sector - the arising subsectors.

Parameters:

sector – Sector; The sector to be decomposed.
indices – iterable of integers or None; The indices of the parameters to be considered as integration variables. By default (indices=None), all parameters are considered as integration variables.

pySecDec.decomposition.iterative.primary_decomposition(sector, indices=None)¶

Perform the primary decomposition as described in chapter 3.2 (part I) of arXiv:0803.4177v2 [Hei08]. Return a list of Sector - the primary sectors. For N Feynman parameters, there are N primary sectors where the i-th Feynman parameter is set to 1 in sector i.

See also

primary_decomposition_polynomial()

Parameters:

sector – Sector; The container holding the polynomials (typically $U$ and $F$ ) to eliminate the Dirac delta from.
indices – iterable of integers or None; The indices of the parameters to be considered as integration variables. By default (indices=None), all parameters are considered as integration variables.

pySecDec.decomposition.iterative.primary_decomposition_polynomial(polynomial, indices=None)¶

Perform the primary decomposition on a single polynomial.

See also

primary_decomposition()

Parameters:

polynomial – algebra.Polynomial; The polynomial to eliminate the Dirac delta from.
indices – iterable of integers or None; The indices of the parameters to be considered as integration variables. By default (indices=None), all parameters are considered as integration variables.

pySecDec.decomposition.iterative.remap_parameters(singular_parameters, Jacobian, *polynomials)¶

Remap the Feynman parameters according to eq. (16) of arXiv:0803.4177v2 [Hei08]. The parameter whose index comes first in singular_parameters is kept fix.

The remapping is done in place; i.e. the polynomials are NOT copied.

Parameters:

singular_parameters – list of integers; The indices $\alpha_r$ such that at least one of polynomials becomes zero if all $t_{\alpha_r} \rightarrow 0$ .
Jacobian – Polynomial; The Jacobian determinant is multiplied to this polynomial.
polynomials – arbitrarily many instances of algebra.Polynomial where all of these have an equal number of variables; The polynomials of Feynman parameters to be remapped. These are typically $F$ and $U$ .

Example:

remap_parameters([1,2], Jacobian, F, U)

5.4.3. Geometric¶

The geometric sector decomposition routines.

pySecDec.decomposition.geometric.Cheng_Wu(sector, index=-1)¶

Replace one Feynman parameter by one. This means integrating out the Dirac delta according to the Cheng-Wu theorem.

Parameters:

sector – Sector; The container holding the polynomials (typically $U$ and $F$ ) to eliminate the Dirac delta from.
index – integer, optional; The index of the Feynman parameter to eliminate. Default: -1 (the last Feynman parameter)

pySecDec.decomposition.geometric.generate_fan(*polynomials)¶

Calculate the fan of the polynomials in the input. The rays of a cone are given by the exponent vectors after factoring out a monomial together with the standard basis vectors. Each choice of factored out monomials gives a different cone. Only full ( $N$ -) dimensional cones in $R^N_{\geq 0}$ need to be considered.

Parameters:: polynomials – arbitrarily many instances of Polynomial where all of these have an equal number of variables; The polynomials to calculate the fan for.

pySecDec.decomposition.geometric.geometric_decomposition(sector, indices=None, normaliz=None, workdir='normaliz_tmp')¶

Run the sector decomposition using the geomethod as described in [BHJ+15].

Note

This function calls the command line executable of normaliz [BIR].

Parameters:

sector – Sector; The sector to be decomposed.
indices – list of integers or None; The indices of the parameters to be considered as integration variables. By default (indices=None), all parameters are considered as integration variables.
normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an OSError is raised.

Note

The communication with normaliz is done via files.

pySecDec.decomposition.geometric.geometric_decomposition_ku(sector, indices=None, normaliz=None, workdir='normaliz_tmp')¶

Run the sector decomposition using the original geometric decomposition strategy by Kaneko and Ueda as described in [KU10].

Note

This function calls the command line executable of normaliz [BIR].

Parameters:

sector – Sector; The sector to be decomposed.
indices – list of integers or None; The indices of the parameters to be considered as integration variables. By default (indices=None), all parameters are considered as integration variables.
normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an OSError is raised.

Note

The communication with normaliz is done via files.

pySecDec.decomposition.geometric.transform_variables(polynomial, transformation, polysymbols='y')¶

Transform the parameters $x_i$ of a pySecDec.algebra.Polynomial,

$x_i \rightarrow \prod_j x_j^{T_{ij}}$

, where $T_{ij}$ is the transformation matrix.

Parameters:

polynomial – pySecDec.algebra.Polynomial; The polynomial to transform the variables in.
transformation – two dimensional array; The transformation matrix $T_{ij}$ .
polysymbols – string or iterable of strings; The symbols for the new variables. This argument is passed to the default constructor of pySecDec.algebra.Polynomial. Refer to the documentation of pySecDec.algebra.Polynomial for further details.

5.4.4. Splitting¶

Routines to split the integration between $0$ and $1$ . This maps singularities from $1$ to $0$ .

pySecDec.decomposition.splitting.find_singular_sets_at_one(polynomial)¶

Find all possible sets of parameters such that the polynomial’s constant term vanishes if these parameters are set to one.

Example:

>>> from pySecDec.algebra import Polynomial
>>> from pySecDec.decomposition.splitting import find_singular_sets_at_one
>>> polysymbols = ['x0', 'x1']
>>> poly = Polynomial.from_expression('1 - 10*x0 - x1', polysymbols)
>>> list(find_singular_sets_at_one(poly))
[(1,)]

Parameters:: polynomial – Polynomial; The polynomial to search in.

pySecDec.decomposition.splitting.remap_one_to_zero(polynomial, *indices)¶

Apply the transformation $x \rightarrow 1 - x$ to polynomial for the parameters of the given indices.

Parameters:

polynomial – Polynomial; The polynomial to apply the transformation to.
indices – arbitrarily many int; The indices of the polynomial.polysymbols to apply the transformation to.

Example:

>>> from pySecDec.algebra import Polynomial
>>> from pySecDec.decomposition.splitting import remap_one_to_zero
>>> polysymbols = ['x0']
>>> polynomial = Polynomial.from_expression('x0', polysymbols)
>>> remap_one_to_zero(polynomial, 0)
 + (1) + (-1)*x0

pySecDec.decomposition.splitting.split(sector, seed, *indices)¶

Split the integration interval $[0,1]$ for the parameters given by indices. The splitting point is fixed using numpy’s random number generator.

Return an iterator of Sector - the arising subsectors.

Parameters:: sector – Sector; The sector to be split.

:param seed;: integer; The seed for the random number generator that is used to fix the splitting point.

Parameters:: indices – arbitrarily many integers; The indices of the variables to be split.

pySecDec.decomposition.splitting.split_singular(sector, seed, indices=[])¶

Split the integration interval $[0,1]$ for the parameters that can lead to singularities at one for the polynomials in sector.cast.

Return an iterator of Sector - the arising subsectors.

Parameters:

sector – Sector; The sector to be split.
seed – integer; The seed for the random number generator that is used to fix the splitting point.
indices – iterables of integers; The indices of the variables to be split if required. An empty iterator means that all variables may potentially be split.

5.5. Matrix Sort¶

Algorithms to sort a matrix when column and row permutations are allowed.

pySecDec.matrix_sort.Pak_sort(matrix, *indices)¶

Inplace modify the matrix to some canonical ordering, when permutations of rows and columns are allowed.

The indices parameter can contain a list of lists of column indices. Only the columns present in the same list are swapped with each other.

The implementation of this function is described in chapter 2 of [Pak11].

Note

If not all indices are considered the resulting matrix may not be canonical.

See also

iterative_sort(), light_Pak_sort()

Parameters:

matrix – 2D array-like; The matrix to be canonicalized.
indices – arbitrarily many iterables of non-negative integers; The groups of columns to permute. Default: range(1,matrix.shape[1])

pySecDec.matrix_sort.iterative_sort(matrix)¶

Inplace modify the matrix to some ordering, when permutations of rows and columns (excluding the first) are allowed.

Note

This function may result in different orderings depending on the initial ordering.

See also

Pak_sort(), light_Pak_sort()

Parameters:: matrix – 2D array-like; The matrix to be canonicalized.

pySecDec.matrix_sort.light_Pak_sort(matrix)¶

Inplace modify the matrix to some ordering, when permutations of rows and columns (excluding the first) are allowed. The implementation of this function is described in chapter 2 of [Pak11]. This function implements a lightweight version: In step (v), we only consider one, not all table copies with the minimized second column.

Note

This function may result in different orderings depending on the initial ordering.

See also

iterative_sort(), Pak_sort()

Parameters:: matrix – 2D array-like; The matrix to be canonicalized.

5.6. Subtraction¶

Routines to isolate the divergencies in an $\epsilon$ expansion.

pySecDec.subtraction.integrate_by_parts(polyprod, power_goals, indices)¶

Repeatedly apply integration by parts,

$\int_0^1 { dt_j t_j^{(a_j - b_j \epsilon_1 - c \epsilon_2 + ...)} \mathcal{I} (t_j,\{t_{i \neq j}\}, \epsilon_1, \epsilon_2, ...) } = \frac{1}{a_j + 1 - b_j \epsilon_1 - c \epsilon_2 - ...} \left( \mathcal{I} (1,\{t_{i \neq j}\}, \epsilon_1, \epsilon_2, ...) - \int_0^1 { dt_j t_j^{(a_j + 1 - b_j \epsilon_1 - c \epsilon_2 + ...)} \mathcal{I}^{\prime} (t_j,\{t_{i \neq j}\}, \epsilon_1, \epsilon_2, ...) } \right)$

, where $\mathcal{I}^{\prime}$ denotes the derivative of $\mathcal{I}$ with respect to $t_j$ . The iteration stops, when $a_j>=$ power_goal_j.

See also

This function provides an alternative to integrate_pole_part().

Parameters:

polyprod – algebra.Product of the form <product of <monomial>**(a_j + ...)> * <regulator poles of cal_I> * <cal_I>; The input product as described above. The <product of <monomial>**(a_j + …)> should be a pySecDec.algebra.Product of <monomial>**(a_j + …). as described below. The <monomial>**(a_j + …) should be an pySecDec.algebra.ExponentiatedPolynomial with exponent being a Polynomial of the regulators $\epsilon_1, \epsilon_2, ...$ . Although no dependence on the Feynman parameters is expected in the exponent, the polynomial variables should be the Feynman parameters and the regulators. The constant term of the exponent should be numerical. The polynomial variables of monomial and the other factors (interpreted as $\mathcal{I}$ ) are interpreted as the Feynman parameters and the epsilon regulators. Make sure that the last factor (<cal_I>) is defined and finite for $\epsilon = 0$ . All poles for $\epsilon \rightarrow 0$ should be made explicit by putting them into <regulator poles of cal_I> as pySecDec.algebra.Pow with exponent = -1 and the base of type pySecDec.algebra.Polynomial.
power_goals – number or iterable of numbers, e.g. float, integer, …; The stopping criterion for the iteration.
indices – iterable of integers; The index/indices of the parameter(s) to partially integrate. $j$ in the formulae above.

Return the pole part and the numerically integrable remainder as a list. Each returned list element has the same structure as the input polyprod.

pySecDec.subtraction.integrate_pole_part(polyprod, *indices)¶

Transform an integral of the form

$\int_0^1 { dt_j t_j^{(a - b \epsilon_1 - c \epsilon_2 + ...)} \mathcal{I} (t_j,\{t_{i \neq j}\}, \epsilon_1, \epsilon_2, ...) }$

into the form

$\sum_{p=0}^{|a|-1} { \frac{1}{a + p + 1 - b \epsilon_1 - c \epsilon_2 - ...} \frac{\mathcal{I}^{(p)} (0,\{t_{i \neq j}\}, \epsilon_1, \epsilon_2, ...)}{p!} + \int_0^1 { dt_j t_j^{(a - b \epsilon_1 - c \epsilon_2 + ...)} R(t_j,\{t_{i \neq j}\}, \epsilon_1, \epsilon_2, ...) } }$

, where $\mathcal{I}^{(p)}$ denotes the p-th derivative of $\mathcal{I}$ with respect to $t_j$ . The equations above are to be understood schematically.

See also

This function implements the transformation from equation (19) to (21) as described in arXiv:0803.4177v2 [Hei08].

Parameters:

polyprod – algebra.Product of the form <product of <monomial>**(a_j + ...)> * <regulator poles of cal_I> * <cal_I>; The input product as described above. The <product of <monomial>**(a_j + …)> should be a pySecDec.algebra.Product of <monomial>**(a_j + …). as described below. The <monomial>**(a_j + …) should be an pySecDec.algebra.ExponentiatedPolynomial with exponent being a Polynomial of the regulators $\epsilon_1, \epsilon_2, ...$ . Although no dependence on the Feynman parameters is expected in the exponent, the polynomial variables should be the Feynman parameters and the regulators. The constant term of the exponent should be numerical. The polynomial variables of monomial and the other factors (interpreted as $\mathcal{I}$ ) are interpreted as the Feynman parameters and the epsilon regulators. Make sure that the last factor (<cal_I>) is defined and finite for $\epsilon = 0$ . All poles for $\epsilon \rightarrow 0$ should be made explicit by putting them into <regulator poles of cal_I> as pySecDec.algebra.Pow with exponent = -1 and the base of type pySecDec.algebra.Polynomial.
indices – arbitrarily many integers; The index/indices of the parameter(s) to partially integrate. $j$ in the formulae above.

Return the pole part and the numerically integrable remainder as a list. That is the sum and the integrand of equation (21) in arXiv:0803.4177v2 [Hei08]. Each returned list element has the same structure as the input polyprod.

pySecDec.subtraction.pole_structure(monomial_product, *indices)¶

Return a list of the unregulated exponents of the parameters specified by indices in monomial_product.

Parameters:

monomial_product – pySecDec.algebra.ExponentiatedPolynomial with exponent being a Polynomial; The monomials of the subtraction to extract the pole structure from.
indices – arbitrarily many integers; The index/indices of the parameter(s) to partially investigate.

5.7. Expansion¶

Routines to series expand singular and nonsingular expressions.

exception pySecDec.expansion.OrderError¶: This exception is raised if an expansion to a lower than the lowest order of an expression is requested.

pySecDec.expansion.expand_Taylor(expression, indices, orders)¶

Series/Taylor expand a nonsingular expression around zero.

Return a algebra.Polynomial - the series expansion.

Parameters:

expression – an expression composed of the types defined in the module algebra; The expression to be series expanded.
indices – integer or iterable of integers; The indices of the parameters to expand. The ordering of the indices defines the ordering of the expansion.
order – integer or iterable of integers; The order to which the expansion is to be calculated.

pySecDec.expansion.expand_ginac(expression, variables, orders)¶: Same as expand_sympy(), but using GiNaC (via ginsh).

pySecDec.expansion.expand_singular(product, indices, orders)¶

Series expand a potentially singular expression of the form

${ \frac{a_N \epsilon_0 + b_N \epsilon_1 + ...} {a_D \epsilon_0 + b_D \epsilon_1 + ...} }$

Return a algebra.Polynomial - the series expansion.

See also

To expand more general expressions use expand_sympy().

Parameters:

product – algebra.Product with factors of the form <polynomial> and <polynomial> ** -1; The expression to be series expanded.
indices – integer or iterable of integers; The indices of the parameters to expand. The ordering of the indices defines the ordering of the expansion.
order – integer or iterable of integers; The order to which the expansion is to be calculated.

pySecDec.expansion.expand_sympy(expression, variables, orders)¶

Expand a sympy expression in the variables to given orders. Return the expansion as nested pySecDec.algebra.Polynomial.

See also

This function is a generalization of expand_singular().

Parameters:

expression – string or sympy expression; The expression to be expanded
variables – iterable of strings or sympy symbols; The variables to expand the expression in.
orders – iterable of integers; The orders to expand to.

5.8. Code Writer¶

This module collects routines to create a c++ library.

5.8.1. Make Package¶

This is the main function of pySecDec.

pySecDec.code_writer.make_package(name, integration_variables, regulators, requested_orders, polynomials_to_decompose, polynomial_names=[], other_polynomials=[], prefactor=1, remainder_expression=1, functions=[], real_parameters=[], complex_parameters=[], form_optimization_level=2, form_work_space='50M', form_memory_use=None, form_threads=1, form_insertion_depth=5, contour_deformation_polynomial=None, positive_polynomials=[], decomposition_method='geometric_no_primary', normaliz_executable=None, enforce_complex=False, split=False, ibp_power_goal=-1, use_iterative_sort=True, use_light_Pak=True, use_dreadnaut=False, use_Pak=True, processes=None, pylink_qmc_transforms=['korobov3x3'])¶

Decompose, subtract and expand an expression. Return it as c++ package.

See also

In order to decompose a loop integral, use the function pySecDec.loop_integral.loop_package().

See also

The generated library is described in Generated C++ Libraries.

Parameters:

name – string; The name of the c++ namespace and the output directory.
integration_variables – iterable of strings or sympy symbols; The variables that are to be integrated. The integration region depends on the chosen decomposition_method.
regulators – iterable of strings or sympy symbols; The UV/IR regulators of the integral.
requested_orders – iterable of integers; Compute the expansion in the regulators to these orders.
polynomials_to_decompose – iterable of strings or sympy expressions or pySecDec.algebra.ExponentiatedPolynomial or pySecDec.algebra.Polynomial; The polynomials to be decomposed.
polynomial_names – iterable of strings; Assign symbols for the polynomials_to_decompose. These can be referenced in the other_polynomials; see other_polynomials for details.
other_polynomials –
iterable of strings or sympy expressions or pySecDec.algebra.ExponentiatedPolynomial or pySecDec.algebra.Polynomial; Additional polynomials where no decomposition is attempted. The symbols defined in polynomial_names can be used to reference the polynomials_to_decompose. This is particularly useful when computing loop integrals where the “numerator” can depend on the first and second Symanzik polynomials.

Example (1-loop bubble with numerator):
```
>>> polynomials_to_decompose = ["(x0 + x1)**(2*eps - 4)",
...                             "(-p**2*x0*x1)**(-eps))"]
>>> polynomial_names = ["U", "F"]
>>> other_polynomials = ["""   (eps - 1)*s*U**2
...                          + (eps - 2)*F
...                          - (eps - 1)*2*s*x0*U
...                          + (eps - 1)*s*x0**2"""]
```
See also

pySecDec.loop_integral

Note that the polynomial_names refer to the polynomials_to_decompose without their exponents.
prefactor – string or sympy expression, optional; A factor that does not depend on the integration variables.
remainder_expression –
string or sympy expression or pySecDec.algebra._Expression, optional; An additional factor.

Dummy function must be provided with all arguments, e.g. remainder_expression='exp(eps)*f(x0,x1)'. In addition, all dummy function must be listed in functions.
functions –
iterable of strings or sympy symbols, optional; Function symbols occurring in remainder_expression, e.g.``[‘f’]``.

Note

Only user-defined functions that are provided as c++-callable code should be mentioned here. Listing basic mathematical functions (e.g. log, pow, exp, sqrt, …) is not required and considered an error to avoid name conflicts.

Note

The power function pow and the logarithm log use the nonstandard continuation with an infinitesimal negative imaginary part on the negative real axis (e.g. log(-1) = -i*pi).
real_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as real variables.
complex_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as complex variables.
form_optimization_level – integer out of the interval [0,4], optional; The optimization level to be used in FORM. Default: 2.
form_work_space –
string, optional; The FORM WorkSpace. Default: '50M'.

Setting this to smaller values will reduce FORM memory usage (without affecting performance), but each problem has some minimum value below which FORM will refuse to work: it will fail with error message indicating that larger WorkSpace is needed, at which point WorkSpace will be adjusted and FORM will be re-run.
form_memory_use –
string, optional; The target FORM memory usage. When specified, form.set parameters will be adjusted so that FORM uses at most approximately this much resident memory.

The minimum is approximately to 600M + 350M per worker thread if form_work_space is left at '50M'. if form_work_space is increased to '500M', then the minimum is 2.5G + 2.5G per worker thread. Default: None, meaning use the default FORM values.
form_threads – integer, optional; Number of threads (T)FORM will use. Default: 1.
form_insertion_depth – nonnegative integer, optional; How deep FORM should try to resolve nested function calls. Default: 5.
contour_deformation_polynomial – string or sympy symbol, optional; The name of the polynomial in polynomial_names that is to be continued to the complex plane according to a $- i\delta$ prescription. For loop integrals, this is the second Symanzik polynomial F. If not provided, no code for contour deformation is created.
positive_polynomials – iterable of strings or sympy symbols, optional; The names of the polynomials in polynomial_names that should always have a positive real part. For loop integrals, this applies to the first Symanzik polynomial U. If not provided, no polynomial is checked for positiveness. If contour_deformation_polynomial is None, this parameter is ignored.
decomposition_method –
string, optional; The strategy to decompose the polynomials. The following strategies are available:
- ’iterative_no_primary’: integration region $[0,1]^N$ .
- ’geometric_no_primary’(default): integration region $[0,1]^N$ .
- ’geometric_infinity_no_primary’: integration region $[0,\infty]^N$ .
- ’iterative’: primary decomposition followed by integration over $[0,1]^{N-1}$ .
- ’geometric’: $x_N$ is set to one followed by integration over $[0,\infty]^{N-1}$ .
- ’geometric_ku’: primary decomposition followed by integration over $[0,1]^{N-1}$ .
’iterative’, ‘geometric’, and ‘geometric_ku’ are only valid for loop integrals. An end user should use ‘iterative_no_primary’, ‘geometric_no_primary’, or ‘geometric_infinity_no_primary’ here. In order to compute loop integrals, please use the function pySecDec.loop_integral.loop_package().
normaliz_executable – string, optional; The command to run normaliz. normaliz is only required if decomposition_method starts with ‘geometric’. Default: use normaliz from pySecDecContrib
enforce_complex – bool, optional; Whether or not the generated integrand functions should have a complex return type even though they might be purely real. The return type of the integrands is automatically complex if contour_deformation is True or if there are complex_parameters. In other cases, the calculation can typically be kept purely real. Most commonly, this flag is needed if log(<negative real>) occurs in one of the integrand functions. However, pySecDec will suggest setting this flag to True in that case. Default: False
split – bool or integer, optional; Whether or not to split the integration domain in order to map singularities from $1$ to $0$ . Set this option to True if you have singularties when one or more integration variables are one. If an integer is passed, that integer is used as seed to generate the splitting point. Default: False
ibp_power_goal –
number or iterable of number, optional; The power_goal that is forwarded to integrate_by_parts().

This option controls how the subtraction terms are generated. Setting it to -numpy.inf disables integrate_by_parts(), while 0 disables integrate_pole_part().

See also

To generate the subtraction terms, this function first calls integrate_by_parts() for each integration variable with the give ibp_power_goal. Then integrate_pole_part() is called.

Default: -1
use_iterative_sort – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with iterative_sort() to find sector symmetries. Default: True
use_light_Pak – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with light_Pak_sort() to find sector symmetries. Default: True
use_dreadnaut – bool or string, optional; Whether or not to use squash_symmetry_redundant_sectors_dreadnaut() to find sector symmetries. If given a string, interpret that string as the command line executable dreadnaut. If True, use dreadnaut from pySecDecContrib. Default: False
use_Pak – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with Pak_sort() to find sector symmetries. Default: True
processes – integer or None, optional; Parallelize the package generation using at most this many processes. If None, use the total number of logical CPUs on the system (that is, os.cpu_count()), or the number of CPUs allocated to the current process (len(os.sched_getaffinity(0))), on platforms where this information is available (i.e. Linux+glibc). New in version 1.3. Default: None
pylink_qmc_transforms –
list or None, optional; Required qmc integral transforms, options are:
- none
- baker
- korobovx<j> for 1 <= i,j <= 6
- korobov for 1 <= i <= 6 (same as korobovx)
- sidi for 1 <= i <= 6
New in version 1.5. Default: ['korobov3x3']

5.8.2. Sum Package¶

Computing weighted sums of integrals, e.g. amplitudes.

class pySecDec.code_writer.sum_package.Coefficient(numerators, denominators=(), parameters=())¶

Store a coefficient expressed as a product of terms in the numerator and a product of terms in the denominator.

Parameters:

numerators – str, or iterable of str; The numerator, or the terms in the numerator.
denominators – str, or iterable of str; The denominator, or the terms in the denominator.
parameters – iterable of strings or sympy symbols; The symbols other parameters.

leading_orders(regulators, maxorder=999999)¶

Calculate and return the lowest orders of the coefficients in the regulators. If the whole coefficient is zero, return a list of the maximal orders.

Parameters:

regulators – iterable of strings or sympy symbols; The symbols denoting the regulators.
maxorder – int; The maximum order of the regulators; if the actual order is higher, this value is used instead.

write(file)¶: Write the coefficient into a given file object.

pySecDec.code_writer.sum_package.sum_package(name, package_generators, regulators, requested_orders, real_parameters=[], complex_parameters=[], coefficients=None, form_executable=None, pylink_qmc_transforms=['korobov3x3'], processes=1)¶

Decompose, subtract and expand a list of expressions of the form

$\sum_j c_{ij} \ \int f_j$

Generate a c++ package with an optimized algorithm to evaluate the integrals numerically. It writes the names of the integrals in the file “integral_names.txt”. For the format of the file see Parser.

Parameters:

name – string; The name of the c++ namespace and the output directory.
package_generators –
iterable of pySecDec.code_writer.MakePackage and/or pySecDec.loop_integral.LoopPackage namedtuples; The generator functions for the integrals $\int f_i$

Note

The pySecDec.code_writer.MakePackage and pySecDec.loop_integral.LoopPackage objects have the same argument list as their respective parent functions pySecDec.code_writer.make_package() and pySecDec.loop_integral.loop_package().
regulators – iterable of strings or sympy symbols; The UV/IR regulators of the integral.
requested_orders – iterable of integers; Compute the expansion in the regulators to these orders.
real_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as real variables.
complex_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as complex variables.
coefficients –
dict of str -> list of strings, optional; A map from the (unique) names of the sums to coefficient vectors $c_{i}$ defining them.

For backward compatibility, iterable of iterable of Coefficient, and iterable of dict of int -> Coefficient are accepted as well, with names of the sums names set to default values.
pylink_qmc_transforms –
list or None, optional; Required qmc integral transforms, options are:
- none
- baker
- korobovx<j> for 1 <= i,j <= 6
- korobov for 1 <= i <= 6 (same as korobovx)
- sidi for 1 <= i <= 6
Default: ['korobov3x3']
processes –
integer or None, optional; Parallelize the generation of terms in a sum using this many processes.

When set to a value larger than 1, this will override the processes argument of the terms in a sum, meaning that each term will not use parallelization, but rather different terms will be generated in parallel.

Default: 1

5.8.3. Template Parser¶

Functions to generate c++ sources from template files.

pySecDec.code_writer.template_parser.generate_pylink_qmc_macro_dict(macro_function_name)¶

Generate translation from transform short names ‘korobov#x#’ and ‘sidi#’ to C++ macros

Parameters:: macro_function_name – string; Name of the macro function to consider
Returns:: dict; A mapping between the transform short names and C++ macros

pySecDec.code_writer.template_parser.parse_template_file(src, dest, replacements={})¶

Copy a file from src to dest replacing %(...) instructions in the standard python way.

Warning

If the file specified in dest exists, it is overwritten without prompt.

See also

parse_template_tree()

Parameters:

src – str; The path to the template file.
dest – str; The path to the destination file.

replacements –

dict; The replacements to be performed. The standard python replacement rules apply:

>>> '%(var)s = %(value)i' % dict(
...     var = 'my_variable',
...     value = 5)
'my_variable = 5'

pySecDec.code_writer.template_parser.parse_template_tree(src, dest, replacements_in_files={}, filesystem_replacements={})¶

Copy a directory tree from src to dest using parse_template_file() for each file and replacing the filenames according to filesystem_replacements.

See also

parse_template_file()

Parameters:

src – str; The path to the template directory.
dest – str; The path to the destination directory.

replacements_in_files –

dict; The replacements to be performed in the files. The standard python replacement rules apply:

>>> '%(var)s = %(value)i' % dict(
...     var = 'my_variable',
...     value = 5)
'my_variable = 5'

filesystem_replacements – dict; Renaming rules for the destination files. and directories. If a file or directory name in the source tree src matches a key in this dictionary, it is renamed to the corresponding value. If the value is None, the corresponding file is ignored.

pySecDec.code_writer.template_parser.validate_pylink_qmc_transforms(pylink_qmc_transforms)¶

Check if pylink_qmc_transforms are valid options and remove duplicates

Parameters:

pylink_qmc_transforms –

list or None; Required qmc integral transforms, options are:

none
baker
korobovx<j> for 1 <= i,j <= 6
korobov for 1 <= i <= 6 (same as korobovx)
sidi for 1 <= i <= 6

Returns:

List of pylink_qmc_transforms

5.9. Generated C++ Libraries¶

A C++ Library to numerically compute a given integral/ loop integral can be generated by the sum_package(), loop_package() functions. The name passed to the make_package() or loop_package() function will be used as the C++ namespace of the generated library. A program demonstrating the use of the C++ library is generated for each integral and written to name/integrate_name.cpp. Here we document the C++ library API.

See also

C++ Interface

5.9.1. Amplitude/Sum libraries¶

New in version 1.5.

Generated by sum_package() in the folder name.

const unsigned long long number_of_integrals¶: The number of integrals in the library.

const unsigned int number_of_amplitudes¶: The number of amplitudes in the library.

const unsigned int number_of_real_parameters¶: The number of real parameters on which the integral depends.

const std::vector<std::string> names_of_real_parameters¶: An ordered vector of string representations of the names of the real parameters.

const unsigned int number_of_complex_parameters¶: The number of complex parameters on which the integral depends.

const std::vector<std::string> names_of_complex_parameters¶: An ordered vector of string representations of the names of the complex parameters.

const unsigned int number_of_regulators¶: The number of regulators on which the integral depends.

const std::vector<std::string> names_of_regulators¶: A vector of the names of the regulators.

const std::vector<int> requested_orders¶: A vector of the requested orders of each regulator used to generate the C++ library, i.e. the requested_orders parameter passed to make_package(), loop_package() or sum_package().

typedef double real_t¶: The real type used by the library.

typedef std::complex<real_t> complex_t¶

The complex type used by the library.

const unsigned int maximal_number_of_integration_variables = 2;

type integrand_return_t¶: The return type of the integrand function. If the integral has complex parameters or uses contour deformation or if enforce_complex is set to True in the call to make_package() or loop_package() then integrand_return_t is complex_t. Otherwise integrand_return_t is real_t.

template<typename T> nested_series_t = secdecutil::Series<secdecutil::Series<...<T>>>: A potentially nested secdecutil::Series representing the series expansion in each of the regulators. If the integral depends on only one regulator (for example, a loop integral generated with loop_package()) this type will be a secdecutil::Series. For integrals that depend on multiple regulators then this will be a series of series representing the multivariate series. This type can be used to write code that can handle integrals depending on arbitrarily many regulators.

See also

secdecutil::Series

template<typename T> using amplitudes_t = std::vector<nested_series_t<T>>: A vector of nested secdecutil::Series representing the amplitudes.

typedef secdecutil::IntegrandContainer<integrand_return_t, real_t const * const, real_t> integrand_t: The type of the integrands. Within the generated C++ library integrands are stored in a container along with the number of integration variables upon which they depend. These containers can be passed to an integrator for numerical integration.

type cuda_integrand_t¶: The type of a single integrand (sector) usable on a CUDA device (GPU). This container can be passed to an integrator for numerical integration.

See also

secdecutil::IntegrandContainer, secdecutil::Integrator, and secdecutil::integrators::Qmc.

typedef integrand_t user_integrand_t: A convenience type of referring to either an integrand_t or cuda_integrand_t if the library was built with a CUDA compatible compiler.

typedef secdecutil::amplitude::Integral<integrand_return_t,real_t> integral_t: The type of the amplitude integral wrapper.

Warning

The precise definition and usage of secdecutil::amplitude::Integral is likely to change in future versions of pySecDec.

typedef secdecutil::amplitude::WeightedIntegral<integral_t,integrand_return_t> weighted_integral_t: The type of the weighted integral. Weighted integrals consist of an integral, I, and the coefficient of the integral, C. A WeightedIntegral is interpreted as the product C*I and can be used to represent individual terms in an amplitude.

typedef std::vector<weighted_integral_t> sum_t: The type of a sum of weighted integrals.

template<template<typename...> class container_t> using handler_t = secdecutil::amplitude::WeightedIntegralHandler<integrand_return_t,real_t,integrand_return_t,container_t>: The type of the weighted integral handler. A WeightedIntegralHandler defines an algorithm for evaluating a sum of weighted integrals.

std::vector<nested_series_t<sum_t>> make_amplitudes(const std::vector<real_t> &real_parameters, const std::vector<complex_t> &complex_parameters, const std::string &lib_path, const integrator_t &integrator)¶: (without contour deformation)

std::vector<nested_series_t<sum_t>> make_amplitudes(const std::vector<real_t> &real_parameters, const std::vector<complex_t> &complex_parameters, const std::string &lib_path, const integrator_t &integrator, unsigned number_of_presamples = 100000, real_t deformation_parameters_maximum = 1., real_t deformation_parameters_minimum = 1.e-5, real_t deformation_parameters_decrease_factor = 0.9)¶

(with contour deformation)

Constructs and returns a vector of amplitudes ready to be passed to a WeightedIntegralHandler for evaluation. Each element of the vector contains an amplitude (weighted sum of integrals). The real and complex parameters are bound to the values passed in real_parameters and complex_parameters. The lib_path parameter is used to specify the path to the coefficients and individual integral libraries. The integrator parameter is used to specify which integrator should be used to evaluate the integrals. If enabled, contour deformation is controlled by the parameters number_of_presamples, deformation_parameters_maximum, deformation_parameters_minimum, deformation_parameters_decrease_factor which are documented in pySecDec.integral_interface.IntegralLibrary.

5.9.2. Integral libraries¶

Generated by make_package() in the folder name or by sum_package() in the folder name/name_integral.

typedef double real_t: The real type used by the library.

typedef std::complex<real_t> complex_t: The complex type used by the library.

type integrand_return_t: The return type of the integrand function. If the integral has complex parameters or uses contour deformation or if enforce_complex is set to True in the call to make_package() or loop_package() then integrand_return_t is complex_t. Otherwise integrand_return_t is real_t.

template<typename T> nested_series_t = secdecutil::Series<secdecutil::Series<...<T>>>: A potentially nested secdecutil::Series representing the series expansion in each of the regulators. If the integral depends on only one regulator (for example, a loop integral generated with loop_package()) this type will be a secdecutil::Series. For integrals that depend on multiple regulators then this will be a series of series representing the multivariate series. This type can be used to write code that can handle integrals depending on arbitrarily many regulators.

See also

secdecutil::Series

typedef secdecutil::IntegrandContainer<integrand_return_t, real_t const*const> integrand_t¶: The type of the integrand. Within the generated C++ library integrands are stored in a container along with the number of integration variables upon which they depend. These containers can be passed to an integrator for numerical integration.

See also

secdecutil::IntegrandContainer and secdecutil::Integrator.

type cuda_integrand_t: New in version 1.4.

The type of a single integrand (sector) usable on a CUDA device (GPU). This container can be passed to an integrator for numerical integration.

See also

secdecutil::IntegrandContainer, secdecutil::Integrator, and secdecutil::integrators::Qmc.

type cuda_together_integrand_t¶: New in version 1.4.

The type of a sum of integrands (sectors) usable on a CUDA device (GPU). This container can be passed to an integrator for numerical integration.

See also

secdecutil::IntegrandContainer, secdecutil::Integrator, and secdecutil::integrators::Qmc.

const unsigned long long number_of_sectors¶: The number of sectors generated by the sector decomposition.

Changed in version 1.3.1: Type was unsigned int in earlier versions of pySecDec.

const unsigned int maximal_number_of_integration_variables¶: The number of integration variables after primary decomposition. This provides an upper bound in the number of integration variables for all integrand functions. The actual number of integration variables may be lower for a given integrand.

const unsigned int number_of_regulators: The number of regulators on which the integral depends.

const unsigned int number_of_real_parameters: The number of real parameters on which the integral depends.

const std::vector<std::string> names_of_real_parameters: An ordered vector of string representations of the names of the real parameters.

const unsigned int number_of_complex_parameters: The number of complex parameters on which the integral depends.

const std::vector<std::string> names_of_complex_parameters: An ordered vector of string representations of the names of the complex parameters.

const std::vector<int> lowest_orders¶: A vector of the lowest order of each regulator which appears in the integral, not including the prefactor.

const std::vector<int> highest_orders¶: A vector of the highest order of each regulator which appears in the integral, not including the prefactor. This depends on the requested_orders and prefactor/additional_prefactor parameter passed to make_package() or loop_package(). In the case of loop_package() it also depends on the $\Gamma$ -function prefactor of the integral which appears upon Feynman parametrization.

const std::vector<int> lowest_prefactor_orders¶: A vector of the lowest order of each regulator which appears in the prefactor of the integral.

const std::vector<int> highest_prefactor_orders¶: A vector of the highest order of each regulator which appears in the prefactor of the integral.

const std::vector<int> requested_orders: A vector of the requested orders of each regulator used to generate the C++ library, i.e. the requested_orders parameter passed to make_package() or loop_package().

const std::vector<nested_series_t<sector_container_t>> &get_sectors()¶: Changed in version 1.3.1: The variable sectors has been replaced by this function.

A low level interface for obtaining the underlying integrand C++ functions.

Warning

The precise definition and usage of get_sectors() is likely to change in future versions of pySecDec.

nested_series_t<integrand_return_t> prefactor(const std::vector<real_t> &real_parameters, const std::vector<complex_t> &complex_parameters)¶: The series expansion of the integral prefactor evaluated with the given parameters. If the library was generated using make_package() it will be equal to the prefactor passed to make_package(). If the library was generated with loop_package() it will be the product of the additional_prefactor passed to loop_package() and the $\Gamma$ -function prefactor of the integral which appears upon Feynman parametrization.

const std::vector<std::vector<real_t>> pole_structures¶

A vector of the powers of the monomials that can be factored out of each sector of the polynomial during the decomposition.

Example: an integral depending on variables $x$ and $y$ may have two sectors, the first may have a monomial $x^{-1} y^{-2}$ factored out and the second may have a monomial $x^{-1}$ factored out during the decomposition. The resulting pole_structures would read { {-1,-2}, {-1,0} }. Poles of type $x^{-1}$ are known as logarithmic poles, poles of type $x^{-2}$ are known as linear poles.

std::vector<nested_series_t<integrand_t>> make_integrands(const std::vector<real_t> &real_parameters, const std::vector<complex_t> &complex_parameters)¶: (without contour deformation)

std::vector<nested_series_t<cuda_integrand_t>> make_cuda_integrands(const std::vector<real_t> &real_parameters, const std::vector<complex_t> &complex_parameters)¶: New in version 1.4.

(without contour deformation) (CUDA only)

std::vector<nested_series_t<integrand_t>> make_integrands(const std::vector<real_t> &real_parameters, const std::vector<complex_t> &complex_parameters, unsigned number_of_presamples = 100000, real_t deformation_parameters_maximum = 1., real_t deformation_parameters_minimum = 1.e-5, real_t deformation_parameters_decrease_factor = 0.9)¶: (with contour deformation)

std::vector<nested_series_t<cuda_integrand_t>> make_cuda_integrands(const std::vector<real_t> &real_parameters, const std::vector<complex_t> &complex_parameters, unsigned number_of_presamples = 100000, real_t deformation_parameters_maximum = 1., real_t deformation_parameters_minimum = 1.e-5, real_t deformation_parameters_decrease_factor = 0.9)¶

New in version 1.4.

(with contour deformation) (CUDA only)

Gives a vector containing the series expansions of individual sectors of the integrand after sector decomposition with the specified real_parameters and complex_parameters bound. Each element of the vector contains the series expansion of an individual sector. The series consists of instances of integrand_t (cuda_integrand_t) which contain the integrand functions and the number of integration variables upon which they depend. The real and complex parameters are bound to the values passed in real_parameters and complex_parameters. If enabled, contour deformation is controlled by the parameters number_of_presamples, deformation_parameters_maximum, deformation_parameters_minimum, deformation_parameters_decrease_factor which are documented in pySecDec.integral_interface.IntegralLibrary. In case of a sign check error (sign_check_error), manually set number_of_presamples, deformation_parameters_maximum, and deformation_parameters_minimum.

Passing the integrand_t to the secdecutil::Integrator::integrate() function of an instance of a particular secdecutil::Integrator will return the numerically evaluated integral. To integrate all orders of all sectors secdecutil::deep_apply() can be used.

Note

This is the recommended way to access the integrand functions.

5.10. Integral Interface¶

An interface to libraries generated by pySecDec.code_writer.make_package() or pySecDec.loop_integral.loop_package().

class pySecDec.integral_interface.CPPIntegrator¶: Abstract base class for integrators to be used with an IntegralLibrary. This class holds a pointer to the c++ integrator and defines the destructor.

class pySecDec.integral_interface.CQuad(integral_library, epsrel=0.01, epsabs=1e-07, n=100, verbose=False, zero_border=0.0)¶

Wrapper for the cquad integrator defined in the gsl library.

Parameters:: integral_library – IntegralLibrary; The integral to be computed with this integrator.

The other options are defined in Section 4.6.1 and in the gsl manual.

class pySecDec.integral_interface.CudaQmc(integral_library, transform='korobov3', fitfunction='default', generatingvectors='default', epsrel=0.01, epsabs=1e-07, maxeval=4611686018427387903, errormode='default', evaluateminn=0, minn=10000, minm=0, maxnperpackage=0, maxmperpackage=0, cputhreads=None, cudablocks=0, cudathreadsperblock=0, verbosity=0, seed=0, devices=[], lattice_candidates=0, standard_lattices=False, keep_lattices=False)¶

Wrapper for the Qmc integrator defined in the integrators library for GPU use.

Parameters:

integral_library – IntegralLibrary; The integral to be computed with this integrator.
errormode – string; The errormode parameter of the Qmc, can be "default", "all", and "largest". "default" takes the default from the Qmc library. See the Qmc docs for details on the other settings.
transform – string; An integral transform related to the parameter P of the Qmc. The possible choices correspond to the integral transforms of the underlying Qmc implementation. Possible values are, "none", "baker", sidi#, "korobov#", and korobov#x# where any # (the rank of the Korobov/Sidi transform) must be an integer between 1 and 6.
fitfunction – string; An integral transform related to the parameter F of the Qmc. The possible choices correspond to the integral transforms of the underlying Qmc implementation. Possible values are "default", "none", "polysingular".
generatingvectors – string; The name of a set of generating vectors. The possible choices correspond to the available generating vectors of the underlying Qmc implementation. Possible values are "default", "cbcpt_dn1_100", "cbcpt_dn2_6", "cbcpt_cfftw1_6", and "cbcpt_cfftw2_10".
lattice_candidates – int; Number of generating vector candidates used for median QMC rule. If standard_lattices=True, the median QMC is only used once the standard lattices are exhausted lattice_candidates=0 disables the use of the median QMC rule. Default: "0"
standard_lattices – bool; Use pre-computed lattices instead of median QMC. Setting this parameter to "False" is equal to setting "generatingvectors=none" Default: "False"
keep_lattices – bool; Specifies if list of generating vectors generated using median Qmc rule should be kept for other integrals Default: "False"
cputhreads –
int; The number of CPU threads that should be used to evaluate the integrand function.

The default is the number of logical CPUs allocated to the current process (that is, len(os.sched_getaffinity(0))) on platforms that expose this information (i.e. Linux+glibc), or os.cpu_count() .

If GPUs are used, one additional CPU thread per device will be launched for communicating with the device. One can set cputhreads to zero to disable CPU evaluation in this case.

See also

The most important options are described in Section 4.6.2.

The other options are defined in the Qmc docs. If an argument is omitted then the default of the underlying Qmc implementation is used.

class pySecDec.integral_interface.Cuhre(integral_library, epsrel=0.01, epsabs=1e-07, flags=0, mineval=10000, maxeval=4611686018427387903, zero_border=0.0, key=0, real_complex_together=False)¶

Wrapper for the Cuhre integrator defined in the cuba library.

Parameters:: integral_library – IntegralLibrary; The integral to be computed with this integrator.

The other options are defined in Section 4.6.3 and in the cuba manual.

class pySecDec.integral_interface.DistevalLibrary(specification_path, workers=None, verbose=True)¶

Interface to the integration library produced by code_writer.make_package() or loop_package() and built by make disteval.

Parameters:

specification_path –
str; The path to the file disteval/<name>.json that can be built by the command
```
$ make disteval
```
in the root directory of the integration library.
workers – list of string or list of list of string, optional; List of commands that start pySecDec workers. Default: one "nice python3 -m pySecDecContrib pysecdec_cpuworker" per available CPU, or one "nice python3 -m pySecDecContrib pysecdec_cudaworker -d " for each available GPU.
verbose – bool, optional; Print the set up and the integration log. Default: True.

Instances of this class can be called with the following arguments:

Parameters:

parameters – dict of str to object, optional; A map from parameter names to their values. A value can be any object that can be converted to complex() and to str(). To make sure floating point imprecision does not spoil the results, it is best to pass the values of the parameters as integers, strings, sympy expressions, or fractions.Fraction() objects. Floating point numbers are supported, but not encouraged.
real_parameters – iterable of float, optional; The values of the real parameters of the library in the same order as the real_parameters argument of code_writer.make_package(). (Not needed if parameters are provided).
complex_parameters – iterable of complex, optional; The values of the complex parameters of the library in the same order as the complex_parameters argument of code_writer.make_package(). (Not needed if parameters are provided).
number_of_presamples – unsigned int, optional; The number of samples used for the contour optimization. This option is ignored if the integral library was created without deformation. Default: 10000.
epsrel – float, optional; The desired relative accuracy for the numerical evaluation of the weighted sum of the sectors. Default: 1e-4.
epsabs – float, optional; The desired absolute accuracy for the numerical evaluation of the weighted sum of the sectors. Default: epsabs of integrator (default 1e-10).
timeout – float, optional; The maximal integration time (in seconds) after which the integration will stop, and the current result will be returned (no matter which precision is reached). Default: None.
points – unsigned int, optional; The initial QMC lattice size. Default: 1e4.
shifts – unsigned int, optional; The number of shifts of the QMC lattice. Default: 32.
lattice_candidates – unsigned int, optional; The number of generating vector candidates used for median QMC rule. lattice_candidates=0 disables the use of the median QMC rule. Default: 0.
verbose – bool, optional; Print the integration log. Default: whatever was used in the __init__() call.
coefficients – string, optional; Alternative path to the directory with the files containing the coefficients for the evaluated amplitude. Default: the coefficients/ directory next to the specification file.
format – string; The format of the returned result, "sympy", "mathematica", or "json". Default: "sympy".

The call operator returns a single string with the resulting value as a series in the regulator powers.

close()¶: Shutdown the workers and release all resources.

class pySecDec.integral_interface.Divonne(integral_library, epsrel=0.01, epsabs=1e-07, flags=0, seed=0, mineval=10000, maxeval=4611686018427387903, zero_border=0.0, key1=2000, key2=1, key3=1, maxpass=4, border=0.0, maxchisq=1.0, mindeviation=0.15, real_complex_together=False)¶

Wrapper for the Divonne integrator defined in the cuba library.

Parameters:: integral_library – IntegralLibrary; The integral to be computed with this integrator.

The other options are defined in Section 4.6.3 and in the cuba manual.

class pySecDec.integral_interface.IntegralLibrary(shared_object_path)¶

Interface to a c++ library produced by code_writer.make_package() or loop_package().

Parameters:

shared_object_path –

str; The path to the file “<name>_pylink.so” that can be built by the command

$ make pylink

in the root directory of the c++ library.

Instances of this class can be called with the following arguments:

Parameters:

real_parameters – iterable of float; The real_parameters of the library.
complex_parameters – iterable of complex; The complex parameters of the library.
together – bool, optional; Whether to integrate the sum of all sectors or to integrate the sectors separately. Default: True.
number_of_presamples – unsigned int, optional; The number of samples used for the contour optimization. A larger value here may resolve a sign check error (sign_check_error). This option is ignored if the integral library was created without deformation. Default: 100000.
deformation_parameters_maximum – float, optional; The maximal value the deformation parameters $\lambda_i$ can obtain. Lower this value if you get a sign check error (sign_check_error). If number_of_presamples=0, all $\lambda_i$ are set to this value. This option is ignored if the integral library was created without deformation. Default: 1.0.
deformation_parameters_minimum – float, optional; The minimal value the deformation parameters $\lambda_i$ can obtain. Lower this value if you get a sign check error (sign_check_error). If number_of_presamples=0, all $\lambda_i$ are set to this value. This option is ignored if the integral library was created without deformation. Default: 1e-5.
deformation_parameters_decrease_factor – float, optional; If the sign check with the optimized $\lambda_i$ fails during the presampling stage, all $\lambda_i$ are multiplied by this value until the sign check passes. We recommend to rather change number_of_presamples, deformation_parameters_maximum, and deformation_parameters_minimum in case of a sign check error. This option is ignored if the integral library was created without deformation. Default: 0.9.
epsrel – float, optional; The desired relative accuracy for the numerical evaluation of the weighted sum of the sectors. Default: epsrel of integrator (default 0.2).
epsabs – float, optional; The desired absolute accuracy for the numerical evaluation of the weighted sum of the sectors. Default: epsabs of integrator (default 1e-7).
maxeval – unsigned int, optional; The maximal number of integrand evaluations for each sector. Default: maxeval of integrator (default 2**62-1).
mineval – unsigned int, optional; The minimal number of integrand evaluations for each sector. Default: mineval/minn of integrator (default 10000).
maxincreasefac – float, optional; The maximum factor by which the number of integrand evaluations will be increased in a single refinement iteration. Default: 20.
min_epsrel – float, optional; The minimum relative accuracy required for each individual sector. Default: 0.2
min_epsabs – float, optional; The minimum absolute accuracy required for each individual sector. Default: 1.e-4.
max_epsrel – float, optional; The maximum relative accuracy assumed possible for each individual sector. Any sector known to this precision will not be refined further. Note: if this condition is met this means that the expected precision will not match the desired precision. Default: 1.e-14.
max_epsabs – float, optional; The maximum absolute accuracy assumed possible for each individual sector. Any sector known to this precision will not be refined further. Note: if this condition is met this means that the expected precision will not match the desired precision. Default: 1.e-20.
min_decrease_factor – float, optional; If the next refinement iteration is expected to make the total time taken for the code to run longer than wall_clock_limit then the number of points to be requested in the next iteration will be reduced by at least min_decrease_factor. Default: 0.9.
decrease_to_percentage – float, optional; If remaining_time * decrease_to_percentage > time_for_next_iteration then the number of points requested in the next refinement iteration will be reduced. Here: remaining_time = wall_clock_limit - elapsed_time and time_for_next_iteration is the estimated time required for the next refinement iteration. Note: if this condition is met this means that the expected precision will not match the desired precision. Default: 0.7.
wall_clock_limit – float, optional; If the current elapsed time has passed wall_clock limit and a refinement iteration finishes then a new refinement iteration will not be started. Instead, the code will return the current result and exit. Default: DBL_MAX (1.7976931348623158e+308).
number_of_threads – int, optional; The number of threads used to compute integrals concurrently. Note: The integrals themselves may also be computed with multiple threads irrespective of this option. Default: 0.
reset_cuda_after – int, optional; The cuda driver does not automatically remove unnecessary functions from the device memory such that the device may run out of memory after some time. This option controls after how many integrals cudaDeviceReset() is called to clear the memory. With the default 0, cudaDeviceReset() is never called. This option is ignored if compiled without cuda. Default: 0 (never).
verbose – bool, optional; Controls the verbosity of the output of the amplitude. Default: False.
errormode – str, optional; Allowed values: abs, all, largest, real, imag. Defines how epsrel and epsabs should be applied to complex values. With the choice largest, the relative uncertainty is defined as max( |Re(error)|, |Im(error)|)/max( |Re(result)|, |Im(result)|). Choosing all will apply epsrel and epsabs to both the real and imaginary part separately. Note: If either the real or imaginary part integrate to 0, the choices all, real or imag might prevent the integration from stopping since the requested precision epsrel cannot be reached. Default: abs.
format – string; The format of the returned result, "series", "ginac", "sympy", "mathematica", "maple", or "json". Default: "series".

See also

A more detailed description of these parameters and how they affect timing/precision is given in Section 4.1.

The call operator returns three strings: * The integral without its prefactor * The prefactor * The integral multiplied by the prefactor

The integrator can be configured by calling the member methods use_Vegas(), use_Suave(), use_Divonne(), use_Cuhre(), use_CQuad(), and use_Qmc(). The available options are listed in the documentation of Vegas, Suave, Divonne, Cuhre, CQuad, Qmc (CudaQmc for GPU version), respectively. CQuad can only be used for one dimensional integrals. A call to use_CQuad() configures the integrator to use CQuad if possible (1D) and the previously defined integrator otherwise. By default, CQuad (1D only) and Vegas are used with their default arguments. For details about the options, refer to the cuba and the gsl manual.

Further information about the library is stored in the member variable info of type dict.

class pySecDec.integral_interface.MultiIntegrator(integral_library, low_dim_integrator, high_dim_integrator, critical_dim)¶

New in version 1.3.1.

Wrapper for the secdecutil::MultiIntegrator.

Parameters:

integral_library – IntegralLibrary; The integral to be computed with this integrator.
low_dim_integrator – CPPIntegrator; The integrator to be used if the integrand is lower dimensional than critical_dim.
high_dim_integrator – CPPIntegrator; The integrator to be used if the integrand has dimension critical_dim or higher.
critical_dim – integer; The dimension below which the low_dimensional_integrator is used.

Use this class to switch between integrators based on the dimension of the integrand when integrating the integral_ibrary. For example, “CQuad for 1D and Vegas otherwise” is implemented as:

integral_library.integrator = MultiIntegrator(integral_library,CQuad(integral_library),Vegas(integral_library),2)

MultiIntegrator can be nested to implement multiple critical dimensions. To use e.g. CQuad for 1D, Cuhre for 2D and 3D, and Vegas otherwise, do:

integral_library.integrator = MultiIntegrator(integral_library,CQuad(integral_library),MultiIntegrator(integral_library,Cuhre(integral_library),Vegas(integral_library),4),2)

Warning

The integral_library passed to the integrators must be the same for all of them. Furthermore, an integrator can only be used to integrate the integral_library it has been constructed with.

Warning

The MultiIntegrator cannot be used with CudaQmc.

class pySecDec.integral_interface.Qmc(integral_library, transform='korobov3', fitfunction='default', generatingvectors='default', epsrel=0.01, epsabs=1e-07, maxeval=4611686018427387903, errormode='default', evaluateminn=0, minn=10000, minm=0, maxnperpackage=0, maxmperpackage=0, cputhreads=None, cudablocks=0, cudathreadsperblock=0, verbosity=0, seed=0, devices=[], lattice_candidates=0, standard_lattices=False, keep_lattices=False)¶

Wrapper for the Qmc integrator defined in the integrators library.

Parameters:

integral_library – IntegralLibrary; The integral to be computed with this integrator.
errormode – string; The errormode parameter of the Qmc, can be "default", "all", and "largest". "default" takes the default from the Qmc library. See the Qmc docs for details on the other settings.
transform – string; An integral transform related to the parameter P of the Qmc. The possible choices correspond to the integral transforms of the underlying Qmc implementation. Possible values are, "none", "baker", sidi#, "korobov#", and korobov#x# where any # (the rank of the Korobov/Sidi transform) must be an integer between 1 and 6.
fitfunction – string; An integral transform related to the parameter F of the Qmc. The possible choices correspond to the integral transforms of the underlying Qmc implementation. Possible values are "default", "none", "polysingular".
generatingvectors –
string; The name of a set of generating vectors. The possible choices correspond to the available generating vectors of the underlying Qmc implementation. Possible values are "default", "cbcpt_dn1_100", "cbcpt_dn2_6", "cbcpt_cfftw1_6", and "cbcpt_cfftw2_10", "none".

The "default" value will use all available generating vectors suitable for the highest dimension integral appearing in the library.
lattice_candidates – int; Number of generating vector candidates used for median QMC rule. If standard_lattices=True, the median QMC is only used once the standard lattices are exhausted lattice_candidates=0 disables the use of the median QMC rule. Default: "0"
standard_lattices – bool; experimental Use pre-computed lattices instead of median QMC. Setting this parameter to "False" is equal to setting "generatingvectors=none" Default: "False"
keep_lattices – bool; experimental Specifies if list of generating vectors generated using median Qmc rule should be kept for other integrals Default: "False"
cputhreads –
int; The number of CPU threads that should be used to evaluate the integrand function.

The default is the number of logical CPUs allocated to the current process (that is, len(os.sched_getaffinity(0)) ) on platforms that expose this information (i.e. Linux+glibc), or os.cpu_count().

If GPUs are used, one additional CPU thread per device will be launched for communicating with the device. One can set cputhreads to zero to disable CPU evaluation in this case.

See also

The most important options are described in Section 4.6.2.

The other options are defined in the Qmc docs. If an argument is omitted then the default of the underlying Qmc implementation is used.

class pySecDec.integral_interface.Suave(integral_library, epsrel=0.01, epsabs=1e-07, flags=0, seed=0, mineval=10000, maxeval=4611686018427387903, zero_border=0.0, nnew=1000, nmin=10, flatness=25.0, real_complex_together=False)¶

Wrapper for the Suave integrator defined in the cuba library.

Parameters:: integral_library – IntegralLibrary; The integral to be computed with this integrator.

The other options are defined in Section 4.6.3 and in the cuba manual.

class pySecDec.integral_interface.Vegas(integral_library, epsrel=0.01, epsabs=1e-07, flags=0, seed=0, mineval=10000, maxeval=4611686018427387903, zero_border=0.0, nstart=10000, nincrease=5000, nbatch=1000, real_complex_together=False)¶

Wrapper for the Vegas integrator defined in the cuba library.

Parameters:: integral_library – IntegralLibrary; The integral to be computed with this integrator.

The other options are defined in Section 4.6.3 and in the cuba manual.

pySecDec.integral_interface.series_to_ginac(series)¶

Convert a textual representation of a series into GiNaC format.

Parameters:

series (str) – Any of the series obtained by calling an IntegralLibrary object.

Returns:

Two strings: the series of mean values, and the series of standard deviations. The format of each returned value may look like this:

(0+0.012665*I)/eps + (0+0.028632*I) + Order(eps)

If there are multiple series specified, return a list of string pairs.

pySecDec.integral_interface.series_to_json(series, name='sum')¶

Convert a textual representation of a series into json format.

Parameters:

series – str; Any of the series obtained by calling an IntegralLibrary object.
name – str; The name of the series. Default: "sum".

Returns:

A dictionary containing the 'regulators' and the value of the series stored as (exponent, value) key-value pairs.

pySecDec.integral_interface.series_to_maple(series)¶

Convert a textual representation of a series into Maple format.

Parameters:

series (str) – Any of the series obtained by calling an IntegralLibrary object.

Returns:

Two strings: the series of mean values, and the series of standard deviations. The format of each returned value may look like this:

(0+0.012665*I)/eps + (0+0.028632*I) + O(eps)

If there are multiple series specified, return a list of string pairs.

pySecDec.integral_interface.series_to_mathematica(series)¶

Convert a textual representation of a series into Mathematica format.

Parameters:

series (str) – Any of the series obtained by calling an IntegralLibrary object.

Returns:

Two strings: the series of mean values, and the series of standard deviations. The format of each returned value may look like this:

(0+0.012665*I)/eps + (0+0.028632*I) + O[eps]

If there are multiple series specified, return a list of string pairs.

pySecDec.integral_interface.series_to_sympy(series)¶

Convert a textual representation of a series into SymPy format.

Parameters:

series (str) – Any of the series obtained by calling an IntegralLibrary object.

Returns:

Two strings: the series of mean values, and the series of standard deviations. The format of each returned value may look like this:

(0+0.012665*I)/eps + (0+0.028632*I) + O(eps)

If there are multiple series specified, return a list of string pairs.

5.11. Miscellaneous¶

Collection of general-purpose helper functions.

pySecDec.misc.adjugate(M)¶

Calculate the adjugate of a matrix.

Parameters:: M – a square-matrix-like array;

pySecDec.misc.all_pairs(iterable)¶

Return all possible pairs of a given set. all_pairs([1,2,3,4]) --> [(1,2),(3,4)] [(1,3),(2,4)] [(1,4),(2,3)]

Parameters:: iterable – iterable; The set to be split into all possible pairs.

pySecDec.misc.argsort_2D_array(array)¶

Sort a 2D array according to its row entries. The idea is to bring identical rows together.

See also

If your array is not two dimensional use argsort_ND_array().

Example:

input		sorted
1 2 3		1 2 3
2 3 4		1 2 3
1 2 3		2 3 4

Return the indices like numpy’s argsort() would.

Parameters:: array – 2D array; The array to be argsorted.

pySecDec.misc.argsort_ND_array(array)¶

Like argsort_2D_array(), this function groups identical entries in an array with any dimensionality greater than (or equal to) two together.

Return the indices like numpy’s argsort() would.

See also

argsort_2D_array()

Parameters:: array – ND array, $N>=2$ ; The array to be argsorted.

pySecDec.misc.assert_degree_at_most_max_degree(expression, variables, max_degree, error_message)¶: Assert that expression is a polynomial of degree less or equal max_degree in the variables.

pySecDec.misc.cached_property(method)¶

Like the builtin property to be used as decorator but the method is only called once per instance.

Example:

class C(object):
    'Sum up the numbers from one to `N`.'
    def __init__(self, N):
        self.N = N
    @cached_property
    def sum(self):
        result = 0
        for i in range(1, self.N + 1):
            result += i
        return result

pySecDec.misc.chunks(lst, n)¶

Yield successive n-sized chunks from lst.

Parameters:

lst – list; The list from which to produce chunks.
n – integer; The size of the chunks to produce.

Returns:

A list of at most length n.

pySecDec.misc.det(M)¶

Calculate the determinant of a matrix.

Parameters:: M – a square-matrix-like array;

pySecDec.misc.doc(docstring)¶

Decorator that replaces a function’s docstring with docstring.

Example:

@doc('documentation of `some_funcion`')
def some_function(*args, **kwargs):
    pass

pySecDec.misc.flatten(polynomial, depth=inf)¶

Convert nested polynomials; i.e. polynomials that have polynomials in their coefficients to one single polynomial.

Parameters:

polynomial – pySecDec.algebra.Polynomial; The polynomial to “flatten”.
depth – integer; The maximum number of recursion steps. If not provided, stop if the coefficient is not a pySecDec.algebra.Polynomial.

pySecDec.misc.lowest_order(expression, variable)¶

Find the lowest order of expression’s series expansion in variable.

Example:

>>> from pySecDec.misc import lowest_order
>>> lowest_order('exp(eps)', 'eps')
0
>>> lowest_order('gamma(eps)', 'eps')
-1

Parameters:

expression – string or sympy expression; The expression to compute the lowest expansion order of.
variable – string or sympy expression; The variable in which to expand.

pySecDec.misc.make_cpp_list(python_list)¶

Convert a python list to a string to be used in c++ initializer list.

Example: ['a', 'b', 'c'] --> '"a","b","c"'

pySecDec.misc.missing(full, part)¶

Return the elements in full that are not contained in part. Raise ValueError if an element is in part but not in full. missing([1,2,3], [1]) --> [2,3] missing([1,2,3,1], [1,2]) --> [3,1] missing([1,2,3], [1,'a']) --> ValueError

Parameters:

full – iterable; The set of elements to complete part with.
part – iterable; The set to be completed to a superset of full.

pySecDec.misc.parallel_det(M, pool)¶

Calculate the determinant of a matrix in parallel.

Parameters:

M – a square-matrix-like array;
pool – multiprocessing.Pool; The pool to be used.

Example:

>>> from pySecDec.misc import parallel_det
>>> from multiprocessing import Pool
>>> from sympy import sympify
>>> M = [['m11','m12','m13','m14'],
...      ['m21','m22','m23','m24'],
...      ['m31','m32','m33','m34'],
...      ['m41','m42','m43','m44']]
>>> M = sympify(M)
>>> parallel_det(M, Pool(2)) # 2 processes
m11*(m22*(m33*m44 - m34*m43) - m23*(m32*m44 - m34*m42) + m24*(m32*m43 - m33*m42)) - m12*(m21*(m33*m44 - m34*m43) - m23*(m31*m44 - m34*m41) + m24*(m31*m43 - m33*m41)) + m13*(m21*(m32*m44 - m34*m42) - m22*(m31*m44 - m34*m41) + m24*(m31*m42 - m32*m41)) - m14*(m21*(m32*m43 - m33*m42) - m22*(m31*m43 - m33*m41) + m23*(m31*m42 - m32*m41))

pySecDec.misc.powerset(iterable, min_length=0, stride=1)¶

Return an iterator over the powerset of a given set. powerset([1,2,3]) --> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)

Parameters:

iterable – iterable; The set to generate the powerset for.
min_length – integer, optional; Only generate sets with minimal given length. Default: 0.
stride – integer; Only generate sets that have a multiple of stride elements. powerset([1,2,3], stride=2) --> () (1,2) (1,3) (2,3)

pySecDec.misc.rangecomb(low, high)¶

Return an iterator over the occurring orders in a multivariate series expansion between low and high.

Parameters:

low – vector-like array; The lowest orders.
high – vector-like array; The highest orders.

Example:

>>> from pySecDec.misc import rangecomb
>>> all_orders = rangecomb([-1,-2], [0,0])
>>> list(all_orders) == [(-1, -2), (-1, -1), (-1, 0), (0, -2), (0, -1), (0, 0)]
True

pySecDec.misc.rec_subs(expr, repl, n=200)¶

Substitute repl in expr and expand until expr stops changing or depth n is reached.

Parameters:

expr – sympy expression; Expression to which the replacement rules are applied.
repl – list; List of replacement rules.
n – integer; Maximal number of repl applications.

Returns:

Expression after substitutions.

pySecDec.misc.sympify_expression(a)¶

A helper function for converting objects to sympy expressions.

First try to convert object to a sympy expression, if this fails, then try to convert str(object) to a sympy expression

Parameters:: a – The object to be converted to a sympy expression.
Returns:: A sympy expression representing the object.

pySecDec.misc.sympify_symbols(iterable, error_message, allow_number=False)¶: sympify each item in iterable and assert that it is a symbol.

This module provides a make_package like interface to code_writer.sum_package make_sum_package().

pySecDec.make_package.make_package(name, integration_variables, regulators, requested_orders, polynomials_to_decompose, polynomial_names=[], other_polynomials=[], prefactor=1, remainder_expression=1, functions=[], real_parameters=[], complex_parameters=[], form_optimization_level=2, form_work_space='50M', form_memory_use=None, form_threads=1, form_insertion_depth=5, contour_deformation_polynomial=None, positive_polynomials=[], decomposition_method='geometric_no_primary', normaliz_executable=None, enforce_complex=False, split=False, ibp_power_goal=-1, use_iterative_sort=True, use_light_Pak=True, use_dreadnaut=False, use_Pak=True, processes=None, form_executable=None, pylink_qmc_transforms=['korobov3x3'])¶

Decompose, subtract and expand an expression. Return it as c++ package.

See also

In order to decompose a loop integral, use the function pySecDec.loop_integral.loop_package().

See also

The generated library is described in Generated C++ Libraries.

See also

pySecDec.code_writer.make_package()

Parameters:

name – string; The name of the c++ namespace and the output directory.
integration_variables – iterable of strings or sympy symbols; The variables that are to be integrated. The integration region depends on the chosen decomposition_method.
regulators – iterable of strings or sympy symbols; The UV/IR regulators of the integral.
requested_orders – iterable of integers; Compute the expansion in the regulators to these orders.
polynomials_to_decompose – iterable of strings or sympy expressions or pySecDec.algebra.ExponentiatedPolynomial or pySecDec.algebra.Polynomial; The polynomials to be decomposed.
polynomial_names – iterable of strings; Assign symbols for the polynomials_to_decompose. These can be referenced in the other_polynomials; see other_polynomials for details.
other_polynomials –
iterable of strings or sympy expressions or pySecDec.algebra.ExponentiatedPolynomial or pySecDec.algebra.Polynomial; Additional polynomials where no decomposition is attempted. The symbols defined in polynomial_names can be used to reference the polynomials_to_decompose. This is particularly useful when computing loop integrals where the “numerator” can depend on the first and second Symanzik polynomials.

Example (1-loop bubble with numerator):
```
>>> polynomials_to_decompose = ["(x0 + x1)**(2*eps - 4)",
...                             "(-p**2*x0*x1)**(-eps))"]
>>> polynomial_names = ["U", "F"]
>>> other_polynomials = ["""   (eps - 1)*s*U**2
...                          + (eps - 2)*F
...                          - (eps - 1)*2*s*x0*U
...                          + (eps - 1)*s*x0**2"""]
```
See also

pySecDec.loop_integral

Note that the polynomial_names refer to the polynomials_to_decompose without their exponents.
prefactor – string or sympy expression, optional; A factor that does not depend on the integration variables.
remainder_expression –
string or sympy expression or pySecDec.algebra._Expression, optional; An additional factor.

Dummy function must be provided with all arguments, e.g. remainder_expression='exp(eps)*f(x0,x1)'. In addition, all dummy function must be listed in functions.
functions –
iterable of strings or sympy symbols, optional; Function symbols occurring in remainder_expression, e.g.``[‘f’]``.

Note

Only user-defined functions that are provided as c++-callable code should be mentioned here. Listing basic mathematical functions (e.g. log, pow, exp, sqrt, …) is not required and considered an error to avoid name conflicts.

Note

The power function pow and the logarithm log use the nonstandard continuation with an infinitesimal negative imaginary part on the negative real axis (e.g. log(-1) = -i*pi).
real_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as real variables.
complex_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as complex variables.
form_optimization_level – integer out of the interval [0,4], optional; The optimization level to be used in FORM. Default: 2.
form_work_space –
string, optional; The FORM WorkSpace. Default: '500M'.

Setting this to smaller values will reduce FORM memory usage (without affecting performance), but each problem has some minimum value below which FORM will refuse to work: it will fail with error message indicating that larger WorkSpace is needed, at which point WorkSpace will be adjusted and FORM will be re-run.
form_memory_use –
string, optional; The target FORM memory usage. When specified, form.set parameters will be adjusted so that FORM uses at most approximately this much resident memory.

The minimum is approximately to 600M + 350M per worker thread if form_work_space is left at '50M'. if form_work_space is increased to '500M', then the minimum is 2.5G + 2.5G per worker thread. Default: None, meaning use the default FORM values.
form_threads – integer, optional; Number of threads (T)FORM will use. Default: 1.
form_insertion_depth – nonnegative integer, optional; How deep FORM should try to resolve nested function calls. Default: 5.
contour_deformation_polynomial – string or sympy symbol, optional; The name of the polynomial in polynomial_names that is to be continued to the complex plane according to a $- i\delta$ prescription. For loop integrals, this is the second Symanzik polynomial F. If not provided, no code for contour deformation is created.
positive_polynomials – iterable of strings or sympy symbols, optional; The names of the polynomials in polynomial_names that should always have a positive real part. For loop integrals, this applies to the first Symanzik polynomial U. If not provided, no polynomial is checked for positiveness. If contour_deformation_polynomial is None, this parameter is ignored.
decomposition_method –
string, optional; The strategy to decompose the polynomials. The following strategies are available:
- ’iterative_no_primary’: integration region $[0,1]^N$ .
- ’geometric_no_primary’ (default): integration region $[0,1]^N$ .
- ’geometric_infinity_no_primary’: integration region $[0,\infty]^N$ .
- ’iterative’: primary decomposition followed by integration over $[0,1]^{N-1}$ .
- ’geometric’: $x_N$ is set to one followed by integration over $[0,\infty]^{N-1}$ .
- ’geometric_ku’: primary decomposition followed by integration over $[0,1]^{N-1}$ .
’iterative’, ‘geometric’, and ‘geometric_ku’ are only valid for loop integrals. The functions ‘iterative_no_primary’, ‘geometric_no_primary’, or ‘geometric_infinity_no_primary’ should be used when decomposing a function with no overall Dirac delta function. In order to compute loop integrals, please use the function pySecDec.loop_integral.loop_package().
normaliz_executable – string, optional; The command to run normaliz. normaliz is only required if decomposition_method starts with ‘geometric’. Default: use normaliz from pySecDecContrib
enforce_complex – bool, optional; Whether or not the generated integrand functions should have a complex return type even though they might be purely real. The return type of the integrands is automatically complex if contour_deformation is True or if there are complex_parameters. In other cases, the calculation can typically be kept purely real. Most commonly, this flag is needed if log(<negative real>) occurs in one of the integrand functions. However, pySecDec will suggest setting this flag to True in that case. Default: False
split – bool or integer, optional; Whether or not to split the integration domain in order to map singularities from $1$ to $0$ . Set this option to True if you have singularties when one or more integration variables are one. If an integer is passed, that integer is used as seed to generate the splitting point. Default: False
ibp_power_goal –
number or iterable of number, optional; The power_goal that is forwarded to integrate_by_parts().

This option controls how the subtraction terms are generated. Setting it to -numpy.inf disables integrate_by_parts(), while 0 disables integrate_pole_part().

See also

To generate the subtraction terms, this function first calls integrate_by_parts() for each integration variable with the give ibp_power_goal. Then integrate_pole_part() is called.

Default: -1
use_iterative_sort – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with iterative_sort() to find sector symmetries. Default: True
use_light_Pak – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with light_Pak_sort() to find sector symmetries. Default: True
use_dreadnaut – bool or string, optional; Whether or not to use squash_symmetry_redundant_sectors_dreadnaut() to find sector symmetries. If given a string, interpret that string as the command line executable dreadnaut. If True, use dreadnaut from pySecDecContrib. Default: False
use_Pak – bool; Whether or not to use squash_symmetry_redundant_sectors_sort() with Pak_sort() to find sector symmetries. Default: True
processes – integer or None, optional; The maximal number of processes to be used. If None, the number of CPUs multiprocessing.cpu_count() is used. New in version 1.3. Default: None
form_executable – string or None, optional; The path to the form executable. The argument is passed to Coefficient.process(). If None, then either $FORM, $SECDEC_CONTRIB/bin/form, or just form is used, depending on which environment variable is set. Default: None.
pylink_qmc_transforms –
list or None, optional; Required qmc integral transforms, options are:
- none
- baker
- korobovx<j> for 1 <= i,j <= 6
- korobov for 1 <= i <= 6 (same as korobovx)
- sidi for 1 <= i <= 6
New in version 1.5. Default: ['korobov3x3']

5.12. Expansion by Regions¶

Routines to perform an expansion by regions, see e.g. [PS11].

pySecDec.make_regions.apply_region(exp_param_index, polynomials, region_vector)¶

Apply the region_vector to the input polynomials.

Note

Redefines the expansion_parameter as $\rho \rightarrow \rho ^ n$ , where $n$ is given by the region_vector.

Note

apply_region modifies the input polynomials.

Parameters:

exp_param_index – integer; Index of the expansion parameter in the list of symbols.
polynomials – iterable of polynomials; Polynomials to be computed in different regions.
region_vector – vector-like array; Region specified by the power of the expansion_parameter in the rescaled variables. The region vectors have to be specified in the same order as the symbols are specified in the polynomials. E.g. if symbols are specified as [‘x0’,’x1’,’rho’] and want rescaling x0 -> rho^i * x0, x1 -> rho^k * x1 and rho -> rho^n, then the region vector needs to be [i,k,n]

pySecDec.make_regions.derive_prod(poly_list, numerator, index, polynomial_name_indices)¶

Calculates the derivative of a product of polynomials using

$\frac{\partial}{\partial x_i} \left( \prod_j P_j^{\alpha_j} N \right) = \prod_j P_j^{\alpha_j-1} N'$

where N’ is given by

$N' = \left( \sum_j N \alpha_j \frac{\partial P_j}{\partial x_i} \prod_{k \neq j} P_k \right) + \left(\prod_l P_l \right) \left[ \left( \sum_k \frac{\partial N}{\partial P_k} \frac{\partial P_k}{\partial x_i} \right) + \frac{\partial N}{\partial x_i} \right] .$

Parameters:

poly_list – list of ExponentiatedPolynomial; The exponentiated polynomials that should be differentiated. They need to be defined in terms of the symbols x0,x1,x2,.. and p0,p1,p2.. where p0,p1,p2.. are the bases of the exponentiated polynomials.
numerator – Polynomial; The numerator also defined as an exponentiated polynomial with symbols = [x0,x1,...,p0,p1,...].
index – integer; Index of variable with respect to which the derivative is taken.
polynomial_name_indices – iterable; Indices of polynomial names in poly_symbols.

pySecDec.make_regions.expand_region(poly_list, numerator, index, order, polynomial_name_indices)¶

Expands the product of the polynomials in poly_list and the numerator with respect to the variable whose index is given to a desired order specified by order.

Parameters:

poly_list – list of ExponentiatedPolynomial; The exponentiated polynomials that should be expanded. They need to be defined in terms of the symbols x0,x1,x2,.. and p0,p1,p2.. where p0,p1,p2.. are the bases of the exponentiated polynomials.
numerator – Polynomial; The numerator also defined as an exponentiated polynomial with symbols = [x0,x1,...,p0,p1,...].
index – integer; Index of variable with respect to which the polynomials are expanded.
order – integer; Desired order of expansion.
polynomial_name_indices – list of int; Indices of polynomials in the symbols of the input polynomials.

pySecDec.make_regions.find_regions(exp_param_index, polynomial, indices=None, normaliz=None, workdir='normaliz_tmp')¶

Find regions for the expansion by regions as described in [PS11].

Note

This function calls the command line executable of normaliz [BIR].

Parameters:

exp_param_index – int; The index of the expansion parameter in the expolist.
polynomials – an instance of Polynomial, for which to calculate the regions for.
indices – list of integers or None; The indices of the parameters to be included in the asymptotic expansion. This should include all Feynman parameters (integration variables) and the expansion parameter. By default (indices=None), all parameters are considered.
normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an OSError is raised.

Note

The communication with normaliz is done via files.

pySecDec.make_regions.make_regions(name, integration_variables, regulators, requested_orders, smallness_parameter, polynomials_to_decompose, numerator='1', expansion_by_regions_order=0, real_parameters=[], complex_parameters=[], normaliz=None, polytope_from_sum_of=None, **make_package_args)¶

Applies the expansion by regions method (see e.g. [PS11]) to a list of polynomials.

Parameters:

name – string; The name of the c++ namespace and the output directory.
integration_variables – iterable of strings or sympy symbols; The variables that are to be integrated from 0 to 1.
regulators – iterable of strings or sympy symbols; The regulators of the integral.
requested_orders – iterable of integers; Compute the expansion in the regulators to these orders.
smallness_parameter – string or sympy symbol; The symbol of the variable in which the expression is expanded.
polynomials_to_decompose – iterable of strings or sympy expressions or pySecDec.algebra.ExponentiatedPolynomial or pySecDec.algebra.Polynomial; The polynomials to be decomposed.
numerator – String or pySecDec.algebra.Polynomial; Polynomial that is not included in the determination of the regions. The symbols defined in polynomial_names can be used to reference the polynomials_to_decompose. Default: ‘1’
expansion_by_regions_order – integer; The order up to which the expression is expanded in the smallness_parameter. Default: 0
real_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as real variables.
complex_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as complex variables.
normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
polytope_from_sum_of – iterable of integers; If this value is None, the product of all the polynomials polynomials_to_decompose is used to determine the Newton polytope and the normal vectors to it. Otherwise, the sum of the polynomials with the indices given by this parameter are used.
make_package_args – The arguments to be forwarded to pySecDec.code_writer.make_package().

5. Reference Guide¶

5.1. Algebra¶

5.2. Loop Integral¶

5.2.1. Feynman Parametrization¶

5.2.2. Loop Package¶

5.2.3. Drawing Feynman Diagrams¶

5.2.4. Loop Regions¶

5.3. Polytope¶

5.4. Decomposition¶

5.4.1. Common¶

5.4.2. Iterative¶

5.4.3. Geometric¶

5.4.4. Splitting¶

5.5. Matrix Sort¶

5.6. Subtraction¶

5.7. Expansion¶

5.8. Code Writer¶

5.8.1. Make Package¶

5.8.2. Sum Package¶

5.8.3. Template Parser¶

5.9. Generated C++ Libraries¶

5.9.1. Amplitude/Sum libraries¶

5.9.2. Integral libraries¶

5.10. Integral Interface¶

5.11. Miscellaneous¶

5.12. Expansion by Regions¶

Table of Contents

Previous topic

Next topic

This Page