# 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.ExponentiatedPolynomial(expolist, coeffs, exponent=1, polysymbols='x', copy=True)

Like Polynomial, but with a global 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 paramater 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 paramater 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 paramater 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 paramater 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.

derive(index)

Generate the derivative by the parameter indexed index.

Parameters

index – integer; The index of the paramater 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:

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 paramater 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 to be interpreted as product .

Parameters
• factors – arbitrarily many instances of Polynomial; The factors .

• copy – bool; Whether or not to copy the factors.

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 paramater 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

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 .

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 paramater 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 to be interpreted as product .

Parameters
• summands – arbitrarily many instances of Polynomial; The summands .

• copy – bool; Whether or not to copy the summands.

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 paramater 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
• polyprodalgebra.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 . 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 is included in self.Gamma_factor.

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 or )

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 , 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.

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.

parameter numerator

• Lorentz_indices

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

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 .

• 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 or )

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 , 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=2, decomposition_method='iterative', normaliz_executable='normaliz', 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.

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

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

Parameters
• name – string; The name of the c++ namespace and the output directory.

• loop_integralpySecDec.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: 2.

• decomposition_method

string, optional; The strategy for decomposing the polynomials. The following strategies are available:

• ’iterative’ (default)

• ’geometric’

• ’geometric_ku’

Note

For ‘geometric’ and ‘geometric_ku’, the third-party program “normaliz” is needed. See The Geomethod and Normaliz.

• normaliz_executable – string, optional; The command to run normaliz. normaliz is only required if decomposition_method is set to ‘geometric’ or ‘geometric_ku’. Default: ‘normaliz’

• 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 to . 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().

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

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

• korobov<i>x<j> for 1 <= i,j <= 6

• korobov<i> for 1 <= i <= 6 (same as korobov<i>x<i>)

• sidi<i> 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', add_monomial_regulator_power=None, decomposition_method='iterative', normaliz_executable='normaliz', 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.

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

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

Parameters
• name – string; The name of the c++ namespace and the output directory.

• loop_integralpySecDec.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.

• add_monomial_regulator_power – string or sympy symbol; 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.

• decomposition_method

string, optional; The strategy for decomposing the polynomials. The following strategies are available:

• ’iterative’ (default)

• ’geometric’

• ’geometric_ku’

Note

For ‘geometric’ and ‘geometric_ku’, the third-party program “normaliz” is needed. See The Geomethod and Normaliz.

• normaliz_executable – string, optional; The command to run normaliz. normaliz is only required if decomposition_method is set to ‘geometric’ or ‘geometric_ku’. Default: ‘normaliz’

• 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 to . 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().

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 . A row in facets is interpreted as one normal vector with additionally the constant in the last column. The points of the polytope obey

complete_representation(normaliz='normaliz', 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]. See The Geomethod and Normaliz for installation and a list of tested versions.

Parameters
• normaliz – string; The shell command to run normaliz.

• 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 dictonary). The keys of the output dictonary 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 – abritrarily many instances of Polynomial where all of these have an equal number of variables; The polynomials to calculate the convex hull for.

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

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

Note

This function calls the command line executable of normaliz [BIR]. See The Geomethod and Normaliz for installation and a list of tested versions.

Parameters
• cone – two dimensional array; The defining rays of the cone.

• normaliz – string; The shell command to run normaliz.

• 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
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 inteval), 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

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 polynomials 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.

• 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
• sectorSector; 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
• sectorSector; 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
• sectorSector; 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.

Parameters
• sectorSector; The container holding the polynomials (typically and ) 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.

Parameters
• polynomialalgebra.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 such that at least one of polynomials becomes zero if all .

• JacobianPolynomial; The Jacobian determinant is multiplied to this polynomial.

• polynomials – abritrarily 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 and .

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
• sectorSector; The container holding the polynomials (typically and ) 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 (-) dimensional cones in need to be considered.

Parameters

polynomials – abritrarily 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='normaliz', 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]. See The Geomethod and Normaliz for installation and a list of tested versions.

Parameters
• sectorSector; 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.

• 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='normaliz', 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]. See The Geomethod and Normaliz for installation and a list of tested versions.

Parameters
• sectorSector; 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.

• 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 of a pySecDec.algebra.Polynomial,

, where is the transformation matrix.

Parameters

### 5.4.4. Splitting¶

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

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)
>>> find_singular_sets_at_one(poly)
[(1,)]

Parameters

polynomialPolynomial; The polynomial to search in.

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

Apply the transformation to polynomial for the parameters of the given indices.

Parameters
• polynomialPolynomial; 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 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

sectorSector; 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 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
• sectorSector; 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.

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.

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.

Parameters

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

## 5.6. Subtraction¶

Routines to isolate the divergencies in an expansion.

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

Repeatedly apply integration by parts,

, where denotes the derivative of with respect to . The iteration stops, when power_goal_j.

This function provides an alternative to integrate_pole_part().

Parameters
• polyprodalgebra.Product of the form <product of <monomial>**(a_j + ...)> * <regulator poles of cal_I> * <cal_I>; The input product as decribed 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 . 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 ) are interpreted as the Feynman parameters and the epsilon regulators. Make sure that the last factor (<cal_I>) is defined and finite for . All poles for 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. 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

into the form

, where denotes the p-th derivative of with respect to . The equations above are to be understood schematically.

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

Parameters
• polyprodalgebra.Product of the form <product of <monomial>**(a_j + ...)> * <regulator poles of cal_I> * <cal_I>; The input product as decribed 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 . 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 ) are interpreted as the Feynman parameters and the epsilon regulators. Make sure that the last factor (<cal_I>) is defined and finite for . All poles for 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. 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

## 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_singular(product, indices, orders)

Series expand a potentially singular expression of the form

Return a algebra.Polynomial - the series expansion.

To expand more general expressions use expand_sympy().

Parameters
• productalgebra.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.

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=2, form_insertion_depth=5, contour_deformation_polynomial=None, positive_polynomials=[], decomposition_method='iterative_no_primary', normaliz_executable='normaliz', 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.

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

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

Parameters
• name – string; The name of the c++ namepace and the output directory.

• integration_variables – iterable of strings or sympy symbols; The variables that are to be integrated. The intgration 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"""]


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 occuring 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: 2.

• 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 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’ (default): integration region .

• ’geometric_no_primary’: integration region .

• ’geometric_infinity_no_primary’: integration region .

• ’iterative’: primary decomposition followed by integration over .

• ’geometric’: is set to one followed by integration over .

• ’geometric_ku’: primary decomposition followed by integration over .

’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: ‘normaliz’

• 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 to . 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().

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; 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

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

• korobov<i>x<j> for 1 <= i,j <= 6

• korobov<i> for 1 <= i <= 6 (same as korobov<i>x<i>)

• sidi<i> 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 – iterable of str; The terms in the numerator.

• denominators – iterable of str; The terms in the denominator.

• parameters – iterable of strings or sympy symbols; The symbols other parameters.

process(regulators, form=None, workdir='form_tmp', keep_workdir=False)

Calculate and return the lowest orders of the coefficients in the regulators and a string defining the expressions “numerator”, “denominator”, and “regulator_factor”.

Parameters
• regulators – iterable of strings or sympy symbols; The symbols denoting the regulators.

• form – string or None; If given a string, interpret that string as the command line executable form. If None, try $FORM (if the environment variable $FORM is set), $SECDEC_CONTRIB/bin/form (if $SECDEC_CONTRIB is set), and form.

• workdir

string; The directory for the communication with form. 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 form is done via files.

• keep_workdir – bool; Whether or not to delete the workdir after execution.

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

Generate a c++ package with an optmized 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++ namepace 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

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 – iterable of iterable of Coefficient, optional; The coefficients of the integrals. with is assumed if not provided.

• form_executable – string or None, optional; The path to the form exectuable. 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.

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

• korobov<i>x<j> for 1 <= i,j <= 6

• korobov<i> for 1 <= i <= 6 (same as korobov<i>x<i>)

• sidi<i> 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.

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.

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.

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.

Check if pylink_qmc_transforms are valid options and remove duplicates

Parameters

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

• korobov<i>x<j> for 1 <= i,j <= 6

• korobov<i> for 1 <= i <= 6 (same as korobov<i>x<i>)

• sidi<i> for 1 <= i <= 6

Returns

## 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.

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.

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.

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.

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.

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.

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.

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 -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 -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 and may have two sectors, the first may have a monomial factored out and the second may have a monomial factored out during the decomposition. The resulting pole_structures would read { {-1,-2}, {-1,0} }. Poles of type are known as logarithmic poles, poles of type 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_libraryIntegralLibrary; 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=[])

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

Parameters
• integral_libraryIntegralLibrary; 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".

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.

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_libraryIntegralLibrary; 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.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_libraryIntegralLibrary; 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 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 can obtain. Lower this value if you get a sign check error (sign_check_error). If number_of_presamples=0, all 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 can obtain. Lower this value if you get a sign check error (sign_check_error). If number_of_presamples=0, all 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 fails during the presampling stage, all 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. See also A more detailed description of these parameters and how they affect timing/precision is given in chapter_cpp_amplitude. 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_libraryIntegralLibrary; The integral to be computed with this integrator. • low_dim_integratorCPPIntegrator; The integrator to be used if the integrand is lower dimensional than critical_dim. • high_dim_integratorCPPIntegrator; 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 beeen 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=[]) Wrapper for the Qmc integrator defined in the integrators library. Parameters • integral_libraryIntegralLibrary; 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". The "default" value will use all available generating vectors suitable for the highest dimension integral appearing in the library. • 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_libraryIntegralLibrary; 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_libraryIntegralLibrary; 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)  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)  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]  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)  ## 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 dimesional 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. Parameters array – ND array, ; 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 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; • poolmultiprocessing.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 occuring 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)]  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=2, form_insertion_depth=5, contour_deformation_polynomial=None, positive_polynomials=[], decomposition_method='iterative_no_primary', normaliz_executable='normaliz', 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. Parameters • name – string; The name of the c++ namepace and the output directory. • integration_variables – iterable of strings or sympy symbols; The variables that are to be integrated. The intgration 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"""]  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 occuring 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: 2. • 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 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’ (default): integration region . • ’geometric_no_primary’: integration region . • ’geometric_infinity_no_primary’: integration region . • ’iterative’: primary decomposition followed by integration over . • ’geometric’: is set to one followed by integration over . • ’geometric_ku’: primary decomposition followed by integration over . ’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: ‘normaliz’ • 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 to . 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, 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 • form_executable – string or None, optional; The path to the form exectuable. 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.

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

• korobov<i>x<j> for 1 <= i,j <= 6

• korobov<i> for 1 <= i <= 6 (same as korobov<i>x<i>)

• sidi<i> 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(polynomials, region_vector, expansion_parameter_index)

Apply the region_vector to the input polynomials.

Note

Redefines the expansion_parameter as , where is given by the region_vector.

Note

apply_region modifies the input polynomials.

Parameters
• 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]

• expansion_parameter_index – integer; Index of the expansion parameter in the list of symbols.

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

Calculates the derivative of a product of polynomials using

where N’ is given by

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.

• numeratorPolynomial; 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.

• numeratorPolynomial; 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='normaliz', 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]. See The Geomethod and Normaliz for installation and a list of tested versions.

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.

• 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, expansion_by_regions_order=0, real_parameters=[], complex_parameters=[], normaliz='normaliz', 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++ namepace 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.

• 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: ‘normaliz’

• 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().