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
(seePolynomial
) where possible.follow_functions – bool, optional (default =
False
); If true, return the converted expression and a list ofFunction
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 inself.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 derivativesdfd<index>
.
 derive(index)¶
Generate the derivative by the parameter indexed index. The derivative of a function with symbol
f
by some index is denoted asdfd<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 underlyingPolynomial
are set to zero. The coefficients are modified according to value and the powers indicated in theexpolist
. 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.
 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 underlyingPolynomial
are set to zero. The coefficients are modified according to value and the powers indicated in theexpolist
. 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 arraylike with numerical or sympysymbolic (see http://www.sympy.org/) content, e.g. [x,1,2] where x is a sympy symbol; The coefficients of the polynomial.
polysymbols –
iterable or string, optional; The symbols to be used for the polynomial variables when converted to string. If a string is passed, the variables will be consecutively numbered.
 For example: expolist=[[2,0],[1,1]] coeffs=[“A”,”B”]
polysymbols=’x’ (default) <> “A*x0**2 + B*x0*x1”
polysymbols=[‘x’,’y’] <> “A*x**2 + B*x*y”
copy –
bool; Whether or not to copy the expolist and the coeffs.
Note
If copy is
False
, it is assumed that the expolist and the coeffs have the correct type.
 becomes_zero_for(zero_params)¶
Return True if the polynomial becomes zero if the parameters passed in zero_params are set to zero. Otherwise, return False.
 Parameters
zero_params – iterable of integers; The indices of the parameters to be checked.
 copy()¶
Return a copy of a
Polynomial
or a subclass.
 denest()¶
Returns a flattened version of a nested
Polynomial
ofPolynomial
s.
 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 underlyingPolynomial
are set to zero. The coefficients are modified according to value and the powers indicated in theexpolist
. 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
andB
to be interpreted as the exponentialA**B
. Parameters
base –
_Expression
; The baseA
of the exponential.exponent –
_Expression
; The exponentB
.copy – bool; Whether or not to copy base and exponent.
 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 underlyingPolynomial
are set to zero. The coefficients are modified according to value and the powers indicated in theexpolist
. 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
orPolynomial
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]
 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 underlyingPolynomial
are set to zero. The coefficients are modified according to value and the powers indicated in theexpolist
. 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.
 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 underlyingPolynomial
are set to zero. The coefficients are modified according to value and the powers indicated in theexpolist
. 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
toSum
 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]
 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 underlyingPolynomial
are set to zero. The coefficients are modified according to value and the powers indicated in theexpolist
. 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.
 pySecDec.algebra.refactorize(polyprod, *parameters)¶
In a
algebra.Product
of the form <monomial> * <polynomial>, check if a parameter in <polynomial> can be shifted to the <monomial>. If possible, modify polyprod accordingly. Parameters
polyprod –
algebra.Product
of the form <monomial> * <polynomial>`; The product to refactorize.parameter – integer, optional; Check only the parameter with this index. If not provided, all parameters are checked.
5.2. Loop Integral¶
This module defines routines to Feynman parametrize a loop integral and build a c++ package that numerically integrates over the sector decomposed integrand.
5.2.1. Feynman Parametrization¶
Routines to Feynman parametrize a loop integral.
 class pySecDec.loop_integral.LoopIntegral(*args, **kwargs)¶
Container class for loop integrals. The main purpose of this class is to convert a loop integral from the momentum representation to the Feynman parameter representation.
It is possible to provide either the graph of the loop integrals as adjacency list, or the propagators.
The Feynman parametrized integral is a product of the following expressions that are accessible as member properties:
self.Gamma_factor
self.exponentiated_U
self.exponentiated_F
self.numerator
self.measure
,
where
self
is an instance of eitherLoopIntegralFromGraph
orLoopIntegralFromPropagators
.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 byself.Gamma_factor
.Changed in version 1.2.2: The overall sign is included in
self.Gamma_factor
.See also
input as graph:
LoopIntegralFromGraph
input as list of propagators:
LoopIntegralFromPropagators
 class pySecDec.loop_integral.LoopIntegralFromGraph(internal_lines, external_lines, replacement_rules=[], Feynman_parameters='x', regulators=None, regulator=None, dimensionality='42*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)]
wherep1
andp2
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 Feynmanparametrized 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='42*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', '(k1k2)**2  m1**2']
.loop_momenta – iterable of strings or sympy expressions; The loop momenta, e.g.
['k1','k2']
.external_momenta –
iterable of strings or sympy expressions, optional; The external momenta, e.g.
['p1','p2']
. Specifying the external_momenta is only required when a numerator is to be constructed.See also
parameter numerator
Lorentz_indices –
iterable of strings or sympy expressions, optional; Symbols to be used as Lorentz indices in the numerator.
See also
parameter numerator
numerator –
string or sympy expression, optional; The numerator of the loop integral. Scalar products must be passed in index notation e.g.
k1(mu)*k2(mu)
. The numerator must be a sum of products of exclusively:numbers
scalar products (e.g.
p1(mu)*k1(mu)*p1(nu)*k2(nu)
)symbols (e.g.
s
,eps
)
Examples:
p1(mu)*k1(mu)*p1(nu)*k2(nu) + 4*s*eps*k1(mu)*k1(mu)
p1(mu)*(k1(mu) + k2(mu))*p1(nu)*k2(nu)
p1(mu)*k1(mu)
Note
In order to use the resulting LoopIntegral as an argument to the function
pySecDec.loop_integral.loop_package()
, the resulting Feynman parametrizedself.numerator
must be expressible as apySecDec.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 generatorpySecDec.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)]
wherep1
andp2
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 Feynmanparametrized tensor numerator as well, which leads to a consistent result.
5.2.2. Loop Package¶
This module contains the function that generates a c++ package.
 pySecDec.loop_integral.loop_package(name, loop_integral, requested_orders=None, requested_order=None, real_parameters=[], complex_parameters=[], contour_deformation=True, additional_prefactor=1, form_optimization_level=2, form_work_space='50M', form_memory_use=None, form_threads=1, decomposition_method='geometric', normaliz_executable=None, enforce_complex=False, split=False, ibp_power_goal=1, use_iterative_sort=True, use_light_Pak=True, use_dreadnaut=False, use_Pak=True, processes=None, pylink_qmc_transforms=['korobov3x3'], package_generator=<function make_package>)¶
Decompose, subtract and expand a Feynman parametrized loop integral. Return it as c++ package.
See also
This function is a wrapper around
pySecDec.make_package()
(default).See also
The generated library is described in Generated C++ Libraries.
 Parameters
name – string; The name of the c++ namespace and the output directory.
loop_integral –
pySecDec.loop_integral.LoopIntegral
; The loop integral to be computed.requested_orders – iterable of integers; Compute the expansion in the regulators to these orders.
requested_order – integer; Deprecated; same as requested_orders set to a list of one item.
real_parameters – iterable of strings or sympy symbols, optional; Parameters to be interpreted as real numbers, e.g. Mandelstam invariants and masses.
complex_parameters – iterable of strings or sympy symbols, optional; Parameters to be interpreted as complex numbers. To use the complex mass scheme, define the masses as complex parameters.
contour_deformation – bool, optional; Whether or not to produce code for contour deformation. Default:
True
.additional_prefactor – string or sympy expression, optional; An additional factor to be multiplied to the loop integral. It may depend on the regulators, the real_parameters, and the complex_parameters.
form_optimization_level – integer out of the interval [0,4], optional; The optimization level to be used in FORM. Default:
2
.form_work_space –
string, optional; The FORM WorkSpace. Default:
'50M'
.Setting this to smaller values will reduce FORM memory usage (without affecting performance), but each problem has some minimum value below which FORM will refuse to work: it will fail with error message indicating that larger WorkSpace is needed, at which point WorkSpace will be adjusted and FORM will be rerun.
form_memory_use –
string, optional; The target FORM memory usage. When specified, form.set parameters will be adjusted so that FORM uses at most approximately this much resident memory.
The minimum is approximately to 600M + 350M per worker thread if
form_work_space
is left at'50M'
. if form_work_space is increased to'500M'
, then the minimum is 2.5G + 2.5G per worker thread. Default:None
, meaning use the default FORM values.form_threads – integer, optional; Number of threads (T)FORM will use. Default:
1
.decomposition_method –
string, optional; The strategy for decomposing the polynomials. The following strategies are available:
’iterative’
’geometric’ (default)
’geometric_ku’
enforce_complex – bool, optional; Whether or not the generated integrand functions should have a complex return type even though they might be purely real. The return type of the integrands is automatically complex if contour_deformation is
True
or if there are complex_parameters. In other cases, the calculation can typically be kept purely real. Most commonly, this flag is needed iflog(<negative real>)
occurs in one of the integrand functions. However, pySecDec will suggest setting this flag toTrue
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
disablesintegrate_by_parts()
, while0
disablesintegrate_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. Thenintegrate_pole_part()
is called.Default:
1
use_iterative_sort – bool; Whether or not to use
squash_symmetry_redundant_sectors_sort()
withiterative_sort()
to find sector symmetries. Default:True
use_light_Pak – bool; Whether or not to use
squash_symmetry_redundant_sectors_sort()
withlight_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. IfTrue
, 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()
withPak_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 CPUsmultiprocessing.cpu_count()
is used. New in version 1.3. Default:None
pylink_qmc_transforms –
list or None, optional; Required qmc integral transforms, options are:
none
baker
korobov<i>x<j>
for 1 <= i,j <= 6korobov<i>
for 1 <= i <= 6 (same askorobov<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()
orpySecDec.code_writer.make_package()
.Default:
pySecDec.make_package()
.
5.2.3. Drawing Feynman Diagrams¶
Use the following function to draw Feynman diagrams.
 pySecDec.loop_integral.draw.plot_diagram(internal_lines, external_lines, filename, powerlist=None, neato='neato', extension='pdf', Gstart=0)¶
Draw a Feynman diagram using Graphviz (neato).
Thanks to Viktor Papara <papara@mpp.mpg.de> for his major contributions to this function.
Note
This function requires the command line tool neato. See also Drawing Feynman Diagrams with neato.
Warning
The target is overwritten without prompt if it exists already.
 Parameters
internal_lines – list; Adjacency list of internal lines, e.g.
[['m',['a',4]],['m',[4,5]], ['m',['a',5]],[0,[1,2]],[0,[4,1]],[0,[2,5]]]
external_lines – list; Adjacency list of external lines, e.g. [[‘p1’,1],[‘p2’,2],[‘p3’,’a’]]
filename – string; The name of the output file. The generated file gets this name plus the file extension.
powerlist – list, optional; The powers of the propagators defined by the internal_lines.
neato – string, default: “neato”; The shell command to call “neato”.
extension – string, default: “pdf”; The file extension. This also defines the output format.
Gstart – nonnegative int; The is value is passed to “neato” with the “Gstart” option. Try changing this value if the visualization looks bad.
5.2.4. Loop Regions¶
Applies the expansion by regions method to a loop integral.
 pySecDec.loop_integral.loop_regions(name, loop_integral, smallness_parameter, expansion_by_regions_order=0, contour_deformation=True, additional_prefactor=1, form_optimization_level=2, form_work_space='500M', form_memory_use=None, form_threads=1, extra_regulator_name=None, extra_regulator_exponent=None, decomposition_method='iterative', normaliz_executable=None, enforce_complex=False, split=False, ibp_power_goal=1, use_iterative_sort=True, use_light_Pak=True, use_dreadnaut=False, use_Pak=True, processes=None)¶
Apply expansion by regions method to the loop integral using the function.
See also
This function is a wrapper around
pySecDec.make_regions()
.See also
The generated library is described in Generated C++ Libraries.
 Parameters
name – string; The name of the c++ namespace and the output directory.
loop_integral –
pySecDec.loop_integral
; The loop integral to which the expansion by regions method is applied.smallness_parameter – string or sympy symbol; The symbol of the variable in which the expression is expanded.
expansion_by_regions_order – integer; The order up to which the expression is expanded in the smallness_parameter. Default: 0
contour_deformation – bool, optional; Whether or not to produce code for contour deformation. Default:
True
.additional_prefactor – string or sympy expression, optional; An additional factor to be multiplied to the loop integral. It may depend on the regulators, the real_parameters, and the complex_parameters.
form_optimization_level – integer out of the interval [0,4], optional; The optimization level to be used in FORM. Default:
2
.form_work_space –
string, optional; The FORM WorkSpace. Default:
'50M'
.Setting this to smaller values will reduce FORM memory usage (without affecting performance), but each problem has some minimum value below which FORM will refuse to work: it will fail with error message indicating that larger WorkSpace is needed, at which point WorkSpace will be adjusted and FORM will be rerun.
form_memory_use –
string, optional; The target FORM memory usage. When specified, form.set parameters will be adjusted so that FORM uses at most approximately this much resident memory.
The minimum is approximately to 600M + 350M per worker thread if
form_work_space
is left at'50M'
. if form_work_space is increased to'500M'
, then the minimum is 2.5G + 2.5G per worker thread. Default:None
, meaning use the default FORM values.form_threads – integer, optional; Number of threads (T)FORM will use. Default:
2
.extra_regulator_name – string or sympy symbol, optional; Name of the regulator using which monomial factors of the form $x_i**(n*p_i)$ are added, to regulate the integrals arising from the expansion by regions.
extra_regulator_exponent – list of integers or sympy rationals, optional; List of the $p_i$ factors of the extra regulator.
decomposition_method –
string, optional; The strategy for decomposing the polynomials. The following strategies are available:
’iterative’ (default)
’geometric’
’geometric_ku’
normaliz_executable – string, optional; The command to run normaliz. normaliz is only required if decomposition_method starts with ‘geometric’. Default: use normaliz from pySecDecContrib
enforce_complex – bool, optional; Whether or not the generated integrand functions should have a complex return type even though they might be purely real. The return type of the integrands is automatically complex if contour_deformation is
True
or if there are complex_parameters. In other cases, the calculation can typically be kept purely real. Most commonly, this flag is needed iflog(<negative real>)
occurs in one of the integrand functions. However, pySecDec will suggest setting this flag toTrue
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
disablesintegrate_by_parts()
, while0
disablesintegrate_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. Thenintegrate_pole_part()
is called.Default:
1
use_iterative_sort – bool; Whether or not to use
squash_symmetry_redundant_sectors_sort()
withiterative_sort()
to find sector symmetries. Default:True
use_light_Pak – bool; Whether or not to use
squash_symmetry_redundant_sectors_sort()
withlight_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. IfTrue
, 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()
withPak_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 CPUsmultiprocessing.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
equations – two dimensional array; Equations defining the hyperplanes the polytope is contained in. Only nonempty for polytopes that are not fulldimensional.
 complete_representation(normaliz=None, workdir='normaliz_tmp', keep_workdir=False)¶
Transform the vertex representation of a polytope to the facet representation or the other way round. Remove surplus entries in
self.facets
orself.vertices
.Note
This function calls the command line executable of normaliz [BIR].
 Parameters
normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an
OSError
is raised.Note
The communication with normaliz is done via files.
keep_workdir – bool; Whether or not to delete the workdir after execution.
 vertex_incidence_lists()¶
Return for each vertex the list of facets it lies in (as 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.normaliz_runcard(data, keyword, dimension)¶
Returns string containing normaliz input file.
 Parameters
data – two dimensional array; Input data.
keyword – string; Keyword specifying the type of input data. For options see normaliz documentation.
dimension – integer; Dimension of the ambient space.
 pySecDec.polytope.read_normaliz_file(filepath, nofoutputs=1)¶
Read normaliz output.
 Parameters
filepath – string; Normaliz output file to be read.
nofoutputs – integer; Number of different types of output in the file to be read in.
 pySecDec.polytope.run_normaliz(normaliz=None, workdir='normaliz_tmp', run_card_filename='normaliz.in', normaliz_args=[])¶
Run normaliz.
 Parameters
normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an
OSError
is raised.Note
The communication with normaliz is done via files.
run_card_filename – string; File name of normaliz input file.
normaliz_args – list of strings; Normaliz command line arguments.
 pySecDec.polytope.triangulate(cone, normaliz=None, workdir='normaliz_tmp', keep_workdir=False, switch_representation=False)¶
Split a cone into simplicial cones; i.e. cones defined by exactly rays where is the dimensionality.
Note
This function calls the command line executable of normaliz [BIR].
 Parameters
cone – two dimensional array; The defining rays of the cone.
normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an
OSError
is raised.Note
The communication with normaliz is done via files.
keep_workdir – bool; Whether or not to delete the workdir after execution.
switch_representation – bool; Whether or not to switch between facet and vertex/ray representation.
5.4. Decomposition¶
The core of sector decomposition. This module implements the actual decomposition routines.
5.4.1. Common¶
This module collects routines that are used by multiple decompition modules.
 class pySecDec.decomposition.Sector(cast, other=[], Jacobian=None)¶
Container class for sectors that arise during the sector decomposition.
 Parameters
cast – iterable of
algebra.Product
or ofalgebra.Polynomial
; The polynomials to be cast to the form <monomial> * (const + …)other – iterable of
algebra.Polynomial
, optional; All variable transformations are applied to these polynomials but it is not attempted to achieve the form <monomial> * (const + …)Jacobian –
algebra.Polynomial
with one term, optional; The Jacobian determinant of this sector. If not provided, the according unit monomial (1*x0^0*x1^0…) is assumed.
 pySecDec.decomposition.squash_symmetry_redundant_sectors_sort(sectors, sort_function, indices=None)¶
Reduce a list of sectors by squashing duplicates with equal integral.
If two sectors only differ by a permutation of the polysymbols (to be interpreted as integration variables over some 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 functionspySecDec.matrix_sort.iterative_sort()
andpySecDec.matrix_sort.light_Pak_sort()
are faster but do not identify all symmetries.See also:
squash_symmetry_redundant_sectors_dreadnaut()
Example:
>>> from pySecDec.algebra import Polynomial >>> from pySecDec.decomposition import Sector >>> from pySecDec.decomposition import squash_symmetry_redundant_sectors_sort >>> from pySecDec.matrix_sort import Pak_sort >>> >>> poly = Polynomial([(0,1),(1,0)], ['a','b']) >>> swap = Polynomial([(1,0),(0,1)], ['a','b']) >>> Jacobian_poly = Polynomial([(1,0)], [3]) # three >>> Jacobian_swap = Polynomial([(0,1)], [5]) # five >>> sectors = ( ... Sector([poly],Jacobian=Jacobian_poly), ... Sector([swap],Jacobian=Jacobian_swap) ... ) >>> >>> reduced_sectors = squash_symmetry_redundant_sectors_sort(sectors, ... Pak_sort) >>> len(reduced_sectors) # symmetry x0 <> x1 1 >>> # The Jacobians are added together to account >>> # for the double counting of the sector. >>> reduced_sectors[0].Jacobian + (8)*x0
 Parameters
sectors – iterable of
Sector
; the sectors to be reduced.sort_function –
pySecDec.matrix_sort.iterative_sort()
,pySecDec.matrix_sort.light_Pak_sort()
, orpySecDec.matrix_sort.Pak_sort()
; The function to be used for finding a canonical form of the sectors.indices – iterable of integers, optional; The indices of the variables to consider. If not provided, all indices are taken into account.
 pySecDec.decomposition.squash_symmetry_redundant_sectors_dreadnaut(sectors, indices=None, dreadnaut='dreadnaut', workdir='dreadnaut_tmp', keep_workdir=False)¶
Reduce a list of sectors by squashing duplicates with equal integral.
Each
Sector
is converted to aPolynomial
which is represented as a graph following the example of [MP+14] (v2.6 Figure 7, Isotopy of matrices).We first multiply each polynomial in the sector by a unique tag then sum the polynomials of the sector, this converts a sector to a polynomial. Next, we convert the expolist of the resulting polynomial to a graph where each unique exponent in the expolist is considered to be a different symbol. Each unique coefficient in the polynomial`s coeffs is assigned a vertex and connected to the row vertex of any term it multiplies. The external program dreadnaut is then used to bring the graph into a canonical form and provide a hash. Sectors with equivalent hashes may be identical, their canonical graphs are compared and if they are identical the sectors are combined.
Note
This function calls the command line executable of dreadnaut [MP+14]. It has been tested with dreadnaut version nauty26r7.
See also:
squash_symmetry_redundant_sectors_sort()
 Parameters
sectors – iterable of
Sector
; the sectors to be reduced.indices – iterable of integers, optional; The indices of the variables to consider. If not provided, all indices are taken into account.
dreadnaut – string; The shell command to run dreadnaut.
workdir –
string; The directory for the communication with dreadnaut. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an
OSError
is raised.Note
The communication with dreadnaut is done via files.
keep_workdir – bool; Whether or not to delete the workdir after execution.
5.4.2. Iterative¶
The iterative sector decomposition routines.
 exception pySecDec.decomposition.iterative.EndOfDecomposition¶
This exception is raised if the function
iteration_step()
is called although the sector is already in standard form.
 pySecDec.decomposition.iterative.find_singular_set(sector, indices=None)¶
Function within the iterative sector decomposition procedure which heuristically chooses an optimal decomposition set. The strategy was introduced in arXiv:hepph/0004013 [BH00] and is described in 4.2.2 of arXiv:1410.7939 [Bor14]. Return a list of indices.
 Parameters
sector –
Sector
; The sector to be decomposed.indices – iterable of integers or None; The indices of the parameters to be considered as integration variables. By default (
indices=None
), all parameters are considered as integration variables.
 pySecDec.decomposition.iterative.iteration_step(sector, indices=None)¶
Run a single step of the iterative sector decomposition as described in chapter 3.2 (part II) of arXiv:0803.4177v2 [Hei08]. Return an iterator of
Sector
 the arising subsectors. Parameters
sector –
Sector
; The sector to be decomposed.indices – iterable of integers or None; The indices of the parameters to be considered as integration variables. By default (
indices=None
), all parameters are considered as integration variables.
 pySecDec.decomposition.iterative.iterative_decomposition(sector, indices=None)¶
Run the iterative sector decomposition as described in chapter 3.2 (part II) of arXiv:0803.4177v2 [Hei08]. Return an iterator of
Sector
 the arising subsectors. Parameters
sector –
Sector
; The sector to be decomposed.indices – iterable of integers or None; The indices of the parameters to be considered as integration variables. By default (
indices=None
), all parameters are considered as integration variables.
 pySecDec.decomposition.iterative.primary_decomposition(sector, indices=None)¶
Perform the primary decomposition as described in chapter 3.2 (part I) of arXiv:0803.4177v2 [Hei08]. Return a list of
Sector
 the primary sectors. For N Feynman parameters, there are N primary sectors where the ith Feynman parameter is set to 1 in sector i.See also
 Parameters
sector –
Sector
; 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.
See also
 Parameters
polynomial –
algebra.Polynomial
; The polynomial to eliminate the Dirac delta from.indices – iterable of integers or None; The indices of the parameters to be considered as integration variables. By default (
indices=None
), all parameters are considered as integration variables.
 pySecDec.decomposition.iterative.remap_parameters(singular_parameters, Jacobian, *polynomials)¶
Remap the Feynman parameters according to eq. (16) of arXiv:0803.4177v2 [Hei08]. The parameter whose index comes first in singular_parameters is kept fix.
The remapping is done in place; i.e. the polynomials are NOT copied.
 Parameters
singular_parameters – list of integers; The indices such that at least one of polynomials becomes zero if all .
Jacobian –
Polynomial
; 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 ChengWu theorem.
 Parameters
sector –
Sector
; 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=None, workdir='normaliz_tmp')¶
Run the sector decomposition using the geomethod as described in [BHJ+15].
Note
This function calls the command line executable of normaliz [BIR].
 Parameters
sector –
Sector
; The sector to be decomposed.indices – list of integers or None; The indices of the parameters to be considered as integration variables. By default (
indices=None
), all parameters are considered as integration variables.normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an
OSError
is raised.Note
The communication with normaliz is done via files.
 pySecDec.decomposition.geometric.geometric_decomposition_ku(sector, indices=None, normaliz=None, workdir='normaliz_tmp')¶
Run the sector decomposition using the original geometric decomposition strategy by Kaneko and Ueda as described in [KU10].
Note
This function calls the command line executable of normaliz [BIR].
 Parameters
sector –
Sector
; The sector to be decomposed.indices – list of integers or None; The indices of the parameters to be considered as integration variables. By default (
indices=None
), all parameters are considered as integration variables.normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an
OSError
is raised.Note
The communication with normaliz is done via files.
 pySecDec.decomposition.geometric.transform_variables(polynomial, transformation, polysymbols='y')¶
Transform the parameters of a
pySecDec.algebra.Polynomial
,, where is the transformation matrix.
 Parameters
polynomial –
pySecDec.algebra.Polynomial
; The polynomial to transform the variables in.transformation – two dimensional array; The transformation matrix .
polysymbols – string or iterable of strings; The symbols for the new variables. This argument is passed to the default constructor of
pySecDec.algebra.Polynomial
. Refer to the documentation ofpySecDec.algebra.Polynomial
for further details.
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
polynomial –
Polynomial
; 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
polynomial –
Polynomial
; The polynomial to apply the transformation to.indices – arbitrarily many int; The indices of the
polynomial.polysymbols
to apply the transformation to.
Example:
>>> from pySecDec.algebra import Polynomial >>> from pySecDec.decomposition.splitting import remap_one_to_zero >>> polysymbols = ['x0'] >>> polynomial = Polynomial.from_expression('x0', polysymbols) >>> remap_one_to_zero(polynomial, 0) + (1) + (1)*x0
 pySecDec.decomposition.splitting.split(sector, seed, *indices)¶
Split the integration interval for the parameters given by indices. The splitting point is fixed using numpy’s random number generator.
Return an iterator of
Sector
 the arising subsectors. Parameters
sector –
Sector
; The sector to be split.
 :param seed;
integer; The seed for the random number generator that is used to fix the splitting point.
 Parameters
indices – arbitrarily many integers; The indices of the variables to be split.
 pySecDec.decomposition.splitting.split_singular(sector, seed, indices=[])¶
Split the integration interval for the parameters that can lead to singularities at one for the polynomials in
sector.cast
.Return an iterator of
Sector
 the arising subsectors. Parameters
sector –
Sector
; The sector to be split.seed – integer; The seed for the random number generator that is used to fix the splitting point.
indices – iterables of integers; The indices of the variables to be split if required. An empty iterator means that all variables may potentially be split.
5.5. Matrix Sort¶
Algorithms to sort a matrix when column and row permutations are allowed.
 pySecDec.matrix_sort.Pak_sort(matrix, *indices)¶
Inplace modify the matrix to some canonical ordering, when permutations of rows and columns are allowed.
The indices parameter can contain a list of lists of column indices. Only the columns present in the same list are swapped with each other.
The implementation of this function is described in chapter 2 of [Pak11].
Note
If not all indices are considered the resulting matrix may not be canonical.
See also
 Parameters
matrix – 2D arraylike; The matrix to be canonicalized.
indices – arbitrarily many iterables of nonnegative integers; The groups of columns to permute. Default:
range(1,matrix.shape[1])
 pySecDec.matrix_sort.iterative_sort(matrix)¶
Inplace modify the matrix to some ordering, when permutations of rows and columns (excluding the first) are allowed.
Note
This function may result in different orderings depending on the initial ordering.
See also
 Parameters
matrix – 2D arraylike; The matrix to be canonicalized.
 pySecDec.matrix_sort.light_Pak_sort(matrix)¶
Inplace modify the matrix to some ordering, when permutations of rows and columns (excluding the first) are allowed. The implementation of this function is described in chapter 2 of [Pak11]. This function implements a lightweight version: In step (v), we only consider one, not all table copies with the minimized second column.
Note
This function may result in different orderings depending on the initial ordering.
See also
 Parameters
matrix – 2D arraylike; 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.
See also
This function provides an alternative to
integrate_pole_part()
. Parameters
polyprod –
algebra.Product
of the form<product of <monomial>**(a_j + ...)> * <regulator poles of cal_I> * <cal_I>
; The input product as decribed above. The <product of <monomial>**(a_j + …)> should be apySecDec.algebra.Product
of <monomial>**(a_j + …). as described below. The <monomial>**(a_j + …) should be anpySecDec.algebra.ExponentiatedPolynomial
withexponent
being aPolynomial
of the regulators . Although no dependence on the Feynman parameters is expected in theexponent
, the polynomial variables should be the Feynman parameters and the regulators. The constant term of the exponent should be numerical. The polynomial variables ofmonomial
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>
aspySecDec.algebra.Pow
withexponent = 1
and thebase
of typepySecDec.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 pth derivative of with respect to . The equations above are to be understood schematically.
See also
This function implements the transformation from equation (19) to (21) as described in arXiv:0803.4177v2 [Hei08].
 Parameters
polyprod –
algebra.Product
of the form<product of <monomial>**(a_j + ...)> * <regulator poles of cal_I> * <cal_I>
; The input product as decribed above. The <product of <monomial>**(a_j + …)> should be apySecDec.algebra.Product
of <monomial>**(a_j + …). as described below. The <monomial>**(a_j + …) should be anpySecDec.algebra.ExponentiatedPolynomial
withexponent
being aPolynomial
of the regulators . Although no dependence on the Feynman parameters is expected in theexponent
, the polynomial variables should be the Feynman parameters and the regulators. The constant term of the exponent should be numerical. The polynomial variables ofmonomial
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>
aspySecDec.algebra.Pow
withexponent = 1
and thebase
of typepySecDec.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
monomial_product –
pySecDec.algebra.ExponentiatedPolynomial
withexponent
being aPolynomial
; The monomials of the subtraction to extract the pole structure from.indices – arbitrarily many integers; The index/indices of the parameter(s) to partially investigate.
5.7. Expansion¶
Routines to series expand singular and nonsingular expressions.
 exception pySecDec.expansion.OrderError¶
This exception is raised if an expansion to a lower than the lowest order of an expression is requested.
 pySecDec.expansion.expand_Taylor(expression, indices, orders)¶
Series/Taylor expand a nonsingular expression around zero.
Return a
algebra.Polynomial
 the series expansion. Parameters
expression – an expression composed of the types defined in the module
algebra
; The expression to be series expanded.indices – integer or iterable of integers; The indices of the parameters to expand. The ordering of the indices defines the ordering of the expansion.
order – integer or iterable of integers; The order to which the expansion is to be calculated.
 pySecDec.expansion.expand_ginac(expression, variables, orders)¶
Same as
expand_sympy()
, but using GiNaC (viaginsh
).
 pySecDec.expansion.expand_singular(product, indices, orders)¶
Series expand a potentially singular expression of the form
Return a
algebra.Polynomial
 the series expansion.See also
To expand more general expressions use
expand_sympy()
. Parameters
product –
algebra.Product
with factors of the form<polynomial>
and<polynomial> ** 1
; The expression to be series expanded.indices – integer or iterable of integers; The indices of the parameters to expand. The ordering of the indices defines the ordering of the expansion.
order – integer or iterable of integers; The order to which the expansion is to be calculated.
 pySecDec.expansion.expand_sympy(expression, variables, orders)¶
Expand a sympy expression in the variables to given orders. Return the expansion as nested
pySecDec.algebra.Polynomial
.See also
This function is a generalization of
expand_singular()
. Parameters
expression – string or sympy expression; The expression to be expanded
variables – iterable of strings or sympy symbols; The variables to expand the expression in.
orders – iterable of integers; The orders to expand to.
5.8. Code Writer¶
This module collects routines to create a c++ library.
5.8.1. Make Package¶
This is the main function of pySecDec.
 pySecDec.code_writer.make_package(name, integration_variables, regulators, requested_orders, polynomials_to_decompose, polynomial_names=[], other_polynomials=[], prefactor=1, remainder_expression=1, functions=[], real_parameters=[], complex_parameters=[], form_optimization_level=2, form_work_space='50M', form_memory_use=None, form_threads=1, form_insertion_depth=5, contour_deformation_polynomial=None, positive_polynomials=[], decomposition_method='geometric_no_primary', normaliz_executable=None, enforce_complex=False, split=False, ibp_power_goal=1, use_iterative_sort=True, use_light_Pak=True, use_dreadnaut=False, use_Pak=True, processes=None, pylink_qmc_transforms=['korobov3x3'])¶
Decompose, subtract and expand an expression. Return it as c++ package.
See also
In order to decompose a loop integral, use the function
pySecDec.loop_integral.loop_package()
.See also
The generated library is described in Generated C++ Libraries.
 Parameters
name – string; The name of the c++ 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
orpySecDec.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
orpySecDec.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 (1loop bubble with numerator):
>>> polynomials_to_decompose = ["(x0 + x1)**(2*eps  4)", ... "(p**2*x0*x1)**(eps))"] >>> polynomial_names = ["U", "F"] >>> other_polynomials = [""" (eps  1)*s*U**2 ... + (eps  2)*F ...  (eps  1)*2*s*x0*U ... + (eps  1)*s*x0**2"""]
See also
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 userdefined 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 rerun.
form_memory_use –
string, optional; The target FORM memory usage. When specified, form.set parameters will be adjusted so that FORM uses at most approximately this much resident memory.
The minimum is approximately to 600M + 350M per worker thread if
form_work_space
is left at'50M'
. if form_work_space is increased to'500M'
, then the minimum is 2.5G + 2.5G per worker thread. Default:None
, meaning use the default FORM values.form_threads – integer, optional; Number of threads (T)FORM will use. Default:
1
.form_insertion_depth – nonnegative integer, optional; How deep FORM should try to resolve nested function calls. Default:
5
.contour_deformation_polynomial – string or sympy symbol, optional; The name of the polynomial in polynomial_names that is to be continued to the complex plane according to a 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 isNone
, this parameter is ignored.decomposition_method –
string, optional; The strategy to decompose the polynomials. The following strategies are available:
’iterative_no_primary’: integration region .
’geometric_no_primary’(default): 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: use normaliz from pySecDecContrib
enforce_complex – bool, optional; Whether or not the generated integrand functions should have a complex return type even though they might be purely real. The return type of the integrands is automatically complex if contour_deformation is
True
or if there are complex_parameters. In other cases, the calculation can typically be kept purely real. Most commonly, this flag is needed iflog(<negative real>)
occurs in one of the integrand functions. However, pySecDec will suggest setting this flag toTrue
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
disablesintegrate_by_parts()
, while0
disablesintegrate_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. Thenintegrate_pole_part()
is called.Default:
1
use_iterative_sort – bool; Whether or not to use
squash_symmetry_redundant_sectors_sort()
withiterative_sort()
to find sector symmetries. Default:True
use_light_Pak – bool; Whether or not to use
squash_symmetry_redundant_sectors_sort()
withlight_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. IfTrue
, use dreadnaut from pySecDecContrib. Default:False
use_Pak – bool; Whether or not to use
squash_symmetry_redundant_sectors_sort()
withPak_sort()
to find sector symmetries. Default:True
processes – integer or None, optional; Parallelize the package generation using at most this many processes. If
None
, use the total number of logical CPUs on the system (that is,os.cpu_count()
), or the number of CPUs allocated to the current process (len(os.sched_getaffinity(0))
), on platforms where this information is available (i.e. Linux+glibc). New in version 1.3. Default:None
pylink_qmc_transforms –
list or None, optional; Required qmc integral transforms, options are:
none
baker
korobov<i>x<j>
for 1 <= i,j <= 6korobov<i>
for 1 <= i <= 6 (same askorobov<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 – str, or iterable of str; The numerator, or the terms in the numerator.
denominators – str, or iterable of str; The denominator, or the terms in the denominator.
parameters – iterable of strings or sympy symbols; The symbols other parameters.
 leading_orders(regulators, maxorder=999999)¶
Calculate and return the lowest orders of the coefficients in the regulators. If the whole coefficient is zero, return a list of the maximal orders.
 Parameters
regulators – iterable of strings or sympy symbols; The symbols denoting the regulators.
maxorder – int; The maximum order of the regulators; if the actual order is higher, this value is used instead.
 write(file)¶
Write the coefficient into a given file object.
 pySecDec.code_writer.sum_package.sum_package(name, package_generators, regulators, requested_orders, real_parameters=[], complex_parameters=[], coefficients=None, form_executable=None, pylink_qmc_transforms=['korobov3x3'], processes=1)¶
Decompose, subtract and expand a list of expressions of the form
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()
andpySecDec.loop_integral.loop_package()
.regulators – iterable of strings or sympy symbols; The UV/IR regulators of the integral.
requested_orders – iterable of integers; Compute the expansion in the regulators to these orders.
real_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as real variables.
complex_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as complex variables.
coefficients –
dict of str > list of strings, optional; A map from the (unique) names of the sums to coefficient vectors defining them.
For backward compatibility, iterable of iterable of
Coefficient
, and iterable of dict of int >Coefficient
are accepted as well, with names of the sums names set to default values.pylink_qmc_transforms –
list or None, optional; Required qmc integral transforms, options are:
none
baker
korobov<i>x<j>
for 1 <= i,j <= 6korobov<i>
for 1 <= i <= 6 (same askorobov<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.
 pySecDec.code_writer.template_parser.generate_pylink_qmc_macro_dict(macro_function_name)¶
Generate translation from transform short names ‘korobov#x#’ and ‘sidi#’ to C++ macros
 Parameters
macro_function_name – string; Name of the macro function to consider
 Returns
dict; A mapping between the transform short names and C++ macros
 pySecDec.code_writer.template_parser.parse_template_file(src, dest, replacements={})¶
Copy a file from src to dest replacing
%(...)
instructions in the standard python way.Warning
If the file specified in dest exists, it is overwritten without prompt.
See also
 Parameters
src – str; The path to the template file.
dest – str; The path to the destination file.
replacements –
dict; The replacements to be performed. The standard python replacement rules apply:
>>> '%(var)s = %(value)i' % dict( ... var = 'my_variable', ... value = 5) 'my_variable = 5'
 pySecDec.code_writer.template_parser.parse_template_tree(src, dest, replacements_in_files={}, filesystem_replacements={})¶
Copy a directory tree from src to dest using
parse_template_file()
for each file and replacing the filenames according to filesystem_replacements.See also
 Parameters
src – str; The path to the template directory.
dest – str; The path to the destination directory.
replacements_in_files –
dict; The replacements to be performed in the files. The standard python replacement rules apply:
>>> '%(var)s = %(value)i' % dict( ... var = 'my_variable', ... value = 5) 'my_variable = 5'
filesystem_replacements – dict; Renaming rules for the destination files. and directories. If a file or directory name in the source tree src matches a key in this dictionary, it is renamed to the corresponding value. If the value is
None
, the corresponding file is ignored.
 pySecDec.code_writer.template_parser.validate_pylink_qmc_transforms(pylink_qmc_transforms)¶
Check if pylink_qmc_transforms are valid options and remove duplicates
 Parameters
pylink_qmc_transforms –
list or None; Required qmc integral transforms, options are:
none
baker
korobov<i>x<j>
for 1 <= i,j <= 6korobov<i>
for 1 <= i <= 6 (same askorobov<i>x<i>
)sidi<i>
for 1 <= i <= 6
 Returns
List of pylink_qmc_transforms
5.9. Generated C++ Libraries¶
A C++ Library to numerically compute a given integral/ loop integral can be generated by the sum_package()
, loop_package()
functions.
The name passed to the make_package()
or loop_package()
function will be used as the C++ namespace of the generated library.
A program demonstrating the use of the C++ library is generated for each integral and written to name/integrate_name.cpp
. Here we document the C++ library API.
See also
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()
orsum_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 tomake_package()
orloop_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 withloop_package()
) this type will be asecdecutil::Series
. For integrals that depend on multiple regulators then this will be a series of series representing the multivariate series. This type can be used to write code that can handle integrals depending on arbitrarily many regulators.See also
 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.e5, 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 tomake_package()
orloop_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 withloop_package()
) this type will be asecdecutil::Series
. For integrals that depend on multiple regulators then this will be a series of series representing the multivariate series. This type can be used to write code that can handle integrals depending on arbitrarily many regulators.See also

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

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()
orloop_package()
. In the case ofloop_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()
orloop_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 tomake_package()
. If the library was generated withloop_package()
it will be the product of the additional_prefactor passed toloop_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.e5, 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.e5, 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 inpySecDec.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 particularsecdecutil::Integrator
will return the numerically evaluated integral. To integrate all orders of all sectorssecdecutil::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=1e07, n=100, verbose=False, zero_border=0.0)¶
Wrapper for the cquad integrator defined in the gsl library.
 Parameters
integral_library –
IntegralLibrary
; The integral to be computed with this integrator.
The other options are defined in Section 4.6.1 and in the gsl manual.
 class pySecDec.integral_interface.CudaQmc(integral_library, transform='korobov3', fitfunction='default', generatingvectors='default', epsrel=0.01, epsabs=1e07, maxeval=4611686018427387903, errormode='default', evaluateminn=0, minn=10000, minm=0, maxnperpackage=0, maxmperpackage=0, cputhreads=None, cudablocks=0, cudathreadsperblock=0, verbosity=0, seed=0, devices=[], lattice_candidates=0, standard_lattices=False, keep_lattices=False)¶
Wrapper for the Qmc integrator defined in the integrators library for GPU use.
 Parameters
integral_library –
IntegralLibrary
; The integral to be computed with this integrator.errormode – string; The errormode parameter of the Qmc, can be
"default"
,"all"
, and"largest"
."default"
takes the default from the Qmc library. See the Qmc docs for details on the other settings.transform – string; An integral transform related to the parameter P of the Qmc. The possible choices correspond to the integral transforms of the underlying Qmc implementation. Possible values are,
"none"
,"baker"
,sidi#
,"korobov#"
, andkorobov#x#
where any#
(the rank of the Korobov/Sidi transform) must be an integer between 1 and 6.fitfunction – string; An integral transform related to the parameter F of the Qmc. The possible choices correspond to the integral transforms of the underlying Qmc implementation. Possible values are
"default"
,"none"
,"polysingular"
.generatingvectors – string; The name of a set of generating vectors. The possible choices correspond to the available generating vectors of the underlying Qmc implementation. Possible values are
"default"
,"cbcpt_dn1_100"
,"cbcpt_dn2_6"
,"cbcpt_cfftw1_6"
, and"cbcpt_cfftw2_10"
.lattice_candidates – int; Number of generating vector candidates used for median QMC rule. If standard_lattices=True, the median QMC is only used once the standard lattices are exhausted lattice_candidates=0 disables the use of the median QMC rule. Default:
"0"
standard_lattices – bool; Use precomputed lattices instead of median QMC. Setting this parameter to
"False"
is equal to setting"generatingvectors=none"
Default:"False"
keep_lattices – bool; Specifies if list of generating vectors generated using median Qmc rule should be kept for other integrals Default:
"False"
cputhreads –
int; The number of CPU threads that should be used to evaluate the integrand function.
The default is the number of logical CPUs allocated to the current process (that is,
len(os.sched_getaffinity(0))
) on platforms that expose this information (i.e. Linux+glibc), oros.cpu_count()
.If GPUs are used, one additional CPU thread per device will be launched for communicating with the device. One can set
cputhreads
to zero to disable CPU evaluation in this case.
See also
The most important options are described in Section 4.6.2.
The other options are defined in the Qmc docs. If an argument is omitted then the default of the underlying Qmc implementation is used.
 class pySecDec.integral_interface.Cuhre(integral_library, epsrel=0.01, epsabs=1e07, flags=0, mineval=10000, maxeval=4611686018427387903, zero_border=0.0, key=0, real_complex_together=False)¶
Wrapper for the Cuhre integrator defined in the cuba library.
 Parameters
integral_library –
IntegralLibrary
; The integral to be computed with this integrator.
The other options are defined in Section 4.6.3 and in the cuba manual.
 class pySecDec.integral_interface.DistevalLibrary(specification_path, workers=None, verbose=True)¶
Interface to the integration library produced by
code_writer.make_package()
orloop_package()
and built bymake disteval
. Parameters
specification_path –
str; The path to the file
disteval/<name>.json
that can be built by the command$ make disteval
in the root directory of the integration library.
workers – list of string or list of list of string, optional; List of commands that start pySecDec workers. Default: one
"nice python3 m pySecDecContrib pysecdec_cpuworker"
per available CPU, or one"nice python3 m pySecDecContrib pysecdec_cudaworker d <i>"
for each available GPU.verbose – bool, optional; Print the set up and the integration log. Default:
True
.
Instances of this class can be called with the following arguments:
 Parameters
parameters – dict of float, optional; A map from parameter names to their values.
real_parameters – iterable of float, optional; The values of the real parameters of the library in the same order as the real_parameters argument of
code_writer.make_package()
. (Not needed if parameters are given).complex_parameters – iterable of complex, optional; The values of the complex parameters of the library in the same order as the complex_parameters argument of
code_writer.make_package()
. (Not needed if parameters are given).number_of_presamples – unsigned int, optional; The number of samples used for the contour optimization. This option is ignored if the integral library was created without deformation. Default:
10000
.epsrel – float, optional; The desired relative accuracy for the numerical evaluation of the weighted sum of the sectors. Default:
1e4
.epsabs – float, optional; The desired absolute accuracy for the numerical evaluation of the weighted sum of the sectors. Default: epsabs of integrator (default 1e10).
timeout – float, optional; The maximal integration time (in seconds) after which the integration will stop, and the current result will be returned (no matter which precision is reached). Default:
None
.points – unsigned int, optional; The initial QMC lattice size. Default:
1e4
.shifts – unsigned int, optional; The number of shifts of the QMC lattice. Default:
32
.lattice_candidates – unsigned int, optional; The number of generating vector candidates used for median QMC rule. lattice_candidates=0 disables the use of the median QMC rule. Default:
0
.verbose – bool, optional; Print the integration log. Default: whatever was used in the __init__() call.
coefficients – string, optional; Alternative path to the directory with the files containing the coefficients for the evaluated amplitude. Default: the
coefficients/
directory next to the specification file.format – string; The format of the returned result,
"sympy"
,"mathematica"
, or"json"
. Default:"sympy"
.
The call operator returns a single string with the resulting value as a series in the regulator powers.
 class pySecDec.integral_interface.Divonne(integral_library, epsrel=0.01, epsabs=1e07, flags=0, seed=0, mineval=10000, maxeval=4611686018427387903, zero_border=0.0, key1=2000, key2=1, key3=1, maxpass=4, border=0.0, maxchisq=1.0, mindeviation=0.15, real_complex_together=False)¶
Wrapper for the Divonne integrator defined in the cuba library.
 Parameters
integral_library –
IntegralLibrary
; The integral to be computed with this integrator.
The other options are defined in Section 4.6.3 and in the cuba manual.
 class pySecDec.integral_interface.IntegralLibrary(shared_object_path)¶
Interface to a c++ library produced by
code_writer.make_package()
orloop_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:1e5
.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
, anddeformation_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 1e7).
maxeval – unsigned int, optional; The maximal number of integrand evaluations for each sector. Default: maxeval of integrator (default 2**621).
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.e4
.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.e14
.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.e20
.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 leastmin_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
andtime_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 default0
,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 choicelargest
, the relative uncertainty is defined asmax( Re(error), Im(error))/max( Re(result), Im(result))
. Choosingall
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 choicesall
,real
orimag
might prevent the integration from stopping since the requested precision epsrel cannot be reached. Default:abs
.format – string; The format of the returned result,
"series"
,"ginac"
,"sympy"
,"mathematica"
,"maple"
, or"json"
. Default:"series"
.
See also
A more detailed description of these parameters and how they affect timing/precision is given in Section 4.1.
The call operator returns three strings: * The integral without its prefactor * The prefactor * The integral multiplied by the prefactor
The integrator can be configured by calling the member methods
use_Vegas()
,use_Suave()
,use_Divonne()
,use_Cuhre()
,use_CQuad()
, anduse_Qmc()
. The available options are listed in the documentation ofVegas
,Suave
,Divonne
,Cuhre
,CQuad
,Qmc
(CudaQmc
for GPU version), respectively.CQuad
can only be used for one dimensional integrals. A call touse_CQuad()
configures the integrator to useCQuad
if possible (1D) and the previously defined integrator otherwise. By default,CQuad
(1D only) andVegas
are used with their default arguments. For details about the options, refer to the cuba and the gsl manual.Further information about the library is stored in the member variable info of type
dict
.
 class pySecDec.integral_interface.MultiIntegrator(integral_library, low_dim_integrator, high_dim_integrator, critical_dim)¶
New in version 1.3.1.
Wrapper for the
secdecutil::MultiIntegrator
. Parameters
integral_library –
IntegralLibrary
; The integral to be computed with this integrator.low_dim_integrator –
CPPIntegrator
; The integrator to be used if the integrand is lower dimensional than critical_dim.high_dim_integrator –
CPPIntegrator
; The integrator to be used if the integrand has dimension critical_dim or higher.critical_dim – integer; The dimension below which the low_dimensional_integrator is used.
Use this class to switch between integrators based on the dimension of the integrand when integrating the integral_ibrary. For example, “
CQuad
for 1D andVegas
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, andVegas
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 withCudaQmc
.
 class pySecDec.integral_interface.Qmc(integral_library, transform='korobov3', fitfunction='default', generatingvectors='default', epsrel=0.01, epsabs=1e07, maxeval=4611686018427387903, errormode='default', evaluateminn=0, minn=10000, minm=0, maxnperpackage=0, maxmperpackage=0, cputhreads=None, cudablocks=0, cudathreadsperblock=0, verbosity=0, seed=0, devices=[], lattice_candidates=0, standard_lattices=False, keep_lattices=False)¶
Wrapper for the Qmc integrator defined in the integrators library.
 Parameters
integral_library –
IntegralLibrary
; The integral to be computed with this integrator.errormode – string; The errormode parameter of the Qmc, can be
"default"
,"all"
, and"largest"
."default"
takes the default from the Qmc library. See the Qmc docs for details on the other settings.transform – string; An integral transform related to the parameter P of the Qmc. The possible choices correspond to the integral transforms of the underlying Qmc implementation. Possible values are,
"none"
,"baker"
,sidi#
,"korobov#"
, andkorobov#x#
where any#
(the rank of the Korobov/Sidi transform) must be an integer between 1 and 6.fitfunction – string; An integral transform related to the parameter F of the Qmc. The possible choices correspond to the integral transforms of the underlying Qmc implementation. Possible values are
"default"
,"none"
,"polysingular"
.generatingvectors –
string; The name of a set of generating vectors. The possible choices correspond to the available generating vectors of the underlying Qmc implementation. Possible values are
"default"
,"cbcpt_dn1_100"
,"cbcpt_dn2_6"
,"cbcpt_cfftw1_6"
, and"cbcpt_cfftw2_10"
,"none"
.The
"default"
value will use all available generating vectors suitable for the highest dimension integral appearing in the library.lattice_candidates – int; Number of generating vector candidates used for median QMC rule. If standard_lattices=True, the median QMC is only used once the standard lattices are exhausted lattice_candidates=0 disables the use of the median QMC rule. Default:
"0"
standard_lattices – bool; experimental Use precomputed lattices instead of median QMC. Setting this parameter to
"False"
is equal to setting"generatingvectors=none"
Default:"False"
keep_lattices – bool; experimental Specifies if list of generating vectors generated using median Qmc rule should be kept for other integrals Default:
"False"
cputhreads –
int; The number of CPU threads that should be used to evaluate the integrand function.
The default is the number of logical CPUs allocated to the current process (that is,
len(os.sched_getaffinity(0))
) on platforms that expose this information (i.e. Linux+glibc), oros.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=1e07, flags=0, seed=0, mineval=10000, maxeval=4611686018427387903, zero_border=0.0, nnew=1000, nmin=10, flatness=25.0, real_complex_together=False)¶
Wrapper for the Suave integrator defined in the cuba library.
 Parameters
integral_library –
IntegralLibrary
; The integral to be computed with this integrator.
The other options are defined in Section 4.6.3 and in the cuba manual.
 class pySecDec.integral_interface.Vegas(integral_library, epsrel=0.01, epsabs=1e07, flags=0, seed=0, mineval=10000, maxeval=4611686018427387903, zero_border=0.0, nstart=10000, nincrease=5000, nbatch=1000, real_complex_together=False)¶
Wrapper for the Vegas integrator defined in the cuba library.
 Parameters
integral_library –
IntegralLibrary
; The integral to be computed with this integrator.
The other options are defined in Section 4.6.3 and in the cuba manual.
 pySecDec.integral_interface.series_to_ginac(series)¶
Convert a textual representation of a series into GiNaC format.
 Parameters
series (str) – Any of the series obtained by calling an
IntegralLibrary
object. Returns
Two strings: the series of mean values, and the series of standard deviations. The format of each returned value may look like this:
(0+0.012665*I)/eps + (0+0.028632*I) + Order(eps)
If there are multiple series specified, return a list of string pairs.
 pySecDec.integral_interface.series_to_json(series, name='sum')¶
Convert a textual representation of a series into json format.
 Parameters
series – str; Any of the series obtained by calling an
IntegralLibrary
object.name – str; The name of the series. Default:
"sum"
.
 Returns
A dictionary containing the
'regulators'
and the value of the series stored as (exponent, value) keyvalue pairs.
 pySecDec.integral_interface.series_to_maple(series)¶
Convert a textual representation of a series into Maple format.
 Parameters
series (str) – Any of the series obtained by calling an
IntegralLibrary
object. Returns
Two strings: the series of mean values, and the series of standard deviations. The format of each returned value may look like this:
(0+0.012665*I)/eps + (0+0.028632*I) + O(eps)
If there are multiple series specified, return a list of string pairs.
 pySecDec.integral_interface.series_to_mathematica(series)¶
Convert a textual representation of a series into Mathematica format.
 Parameters
series (str) – Any of the series obtained by calling an
IntegralLibrary
object. Returns
Two strings: the series of mean values, and the series of standard deviations. The format of each returned value may look like this:
(0+0.012665*I)/eps + (0+0.028632*I) + O[eps]
If there are multiple series specified, return a list of string pairs.
 pySecDec.integral_interface.series_to_sympy(series)¶
Convert a textual representation of a series into SymPy format.
 Parameters
series (str) – Any of the series obtained by calling an
IntegralLibrary
object. Returns
Two strings: the series of mean values, and the series of standard deviations. The format of each returned value may look like this:
(0+0.012665*I)/eps + (0+0.028632*I) + O(eps)
If there are multiple series specified, return a list of string pairs.
5.11. Miscellaneous¶
Collection of generalpurpose helper functions.
 pySecDec.misc.adjugate(M)¶
Calculate the adjugate of a matrix.
 Parameters
M – a squarematrixlike 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.See also
 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 nsized 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 squarematrixlike array;
 pySecDec.misc.doc(docstring)¶
Decorator that replaces a function’s docstring with docstring.
Example:
@doc('documentation of `some_funcion`') def some_function(*args, **kwargs): pass
 pySecDec.misc.flatten(polynomial, depth=inf)¶
Convert nested polynomials; i.e. polynomials that have polynomials in their coefficients to one single polynomial.
 Parameters
polynomial –
pySecDec.algebra.Polynomial
; The polynomial to “flatten”.depth – integer; The maximum number of recursion steps. If not provided, stop if the coefficient is not a
pySecDec.algebra.Polynomial
.
 pySecDec.misc.lowest_order(expression, variable)¶
Find the lowest order of expression’s series expansion in variable.
Example:
>>> from pySecDec.misc import lowest_order >>> lowest_order('exp(eps)', 'eps') 0 >>> lowest_order('gamma(eps)', 'eps') 1
 Parameters
expression – string or sympy expression; The expression to compute the lowest expansion order of.
variable – string or sympy expression; The variable in which to expand.
 pySecDec.misc.make_cpp_list(python_list)¶
Convert a python list to a string to be used in c++ initializer list.
Example:
['a', 'b', 'c'] > '"a","b","c"'
 pySecDec.misc.missing(full, part)¶
Return the elements in full that are not contained in part. Raise ValueError if an element is in part but not in full.
missing([1,2,3], [1]) > [2,3]
missing([1,2,3,1], [1,2]) > [3,1]
missing([1,2,3], [1,'a']) > ValueError
 Parameters
full – iterable; The set of elements to complete part with.
part – iterable; The set to be completed to a superset of full.
 pySecDec.misc.parallel_det(M, pool)¶
Calculate the determinant of a matrix in parallel.
 Parameters
M – a squarematrixlike array;
pool –
multiprocessing.Pool
; The pool to be used.
Example:
>>> from pySecDec.misc import parallel_det >>> from multiprocessing import Pool >>> from sympy import sympify >>> M = [['m11','m12','m13','m14'], ... ['m21','m22','m23','m24'], ... ['m31','m32','m33','m34'], ... ['m41','m42','m43','m44']] >>> M = sympify(M) >>> parallel_det(M, Pool(2)) # 2 processes m11*(m22*(m33*m44  m34*m43)  m23*(m32*m44  m34*m42) + m24*(m32*m43  m33*m42))  m12*(m21*(m33*m44  m34*m43)  m23*(m31*m44  m34*m41) + m24*(m31*m43  m33*m41)) + m13*(m21*(m32*m44  m34*m42)  m22*(m31*m44  m34*m41) + m24*(m31*m42  m32*m41))  m14*(m21*(m32*m43  m33*m42)  m22*(m31*m43  m33*m41) + m23*(m31*m42  m32*m41))
 pySecDec.misc.powerset(iterable, min_length=0, stride=1)¶
Return an iterator over the powerset of a given set.
powerset([1,2,3]) > () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)
 Parameters
iterable – iterable; The set to generate the powerset for.
min_length – integer, optional; Only generate sets with minimal given length. Default:
0
.stride – integer; Only generate sets that have a multiple of stride elements.
powerset([1,2,3], stride=2) > () (1,2) (1,3) (2,3)
 pySecDec.misc.rangecomb(low, high)¶
Return an iterator over the occuring orders in a multivariate series expansion between low and high.
 Parameters
low – vectorlike array; The lowest orders.
high – vectorlike 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=1, form_insertion_depth=5, contour_deformation_polynomial=None, positive_polynomials=[], decomposition_method='geometric_no_primary', normaliz_executable=None, enforce_complex=False, split=False, ibp_power_goal=1, use_iterative_sort=True, use_light_Pak=True, use_dreadnaut=False, use_Pak=True, processes=None, form_executable=None, pylink_qmc_transforms=['korobov3x3'])¶
Decompose, subtract and expand an expression. Return it as c++ package.
See also
In order to decompose a loop integral, use the function
pySecDec.loop_integral.loop_package()
.See also
The generated library is described in Generated C++ Libraries.
See also
 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
orpySecDec.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
orpySecDec.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 (1loop bubble with numerator):
>>> polynomials_to_decompose = ["(x0 + x1)**(2*eps  4)", ... "(p**2*x0*x1)**(eps))"] >>> polynomial_names = ["U", "F"] >>> other_polynomials = [""" (eps  1)*s*U**2 ... + (eps  2)*F ...  (eps  1)*2*s*x0*U ... + (eps  1)*s*x0**2"""]
See also
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 userdefined 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 rerun.
form_memory_use –
string, optional; The target FORM memory usage. When specified, form.set parameters will be adjusted so that FORM uses at most approximately this much resident memory.
The minimum is approximately to 600M + 350M per worker thread if
form_work_space
is left at'50M'
. if form_work_space is increased to'500M'
, then the minimum is 2.5G + 2.5G per worker thread. Default:None
, meaning use the default FORM values.form_threads – integer, optional; Number of threads (T)FORM will use. Default:
1
.form_insertion_depth – nonnegative integer, optional; How deep FORM should try to resolve nested function calls. Default:
5
.contour_deformation_polynomial – string or sympy symbol, optional; The name of the polynomial in polynomial_names that is to be continued to the complex plane according to a 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 isNone
, this parameter is ignored.decomposition_method –
string, optional; The strategy to decompose the polynomials. The following strategies are available:
’iterative_no_primary’: integration region .
’geometric_no_primary’ (default): 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. The functions ‘iterative_no_primary’, ‘geometric_no_primary’, or ‘geometric_infinity_no_primary’ should be used when decomposing a function with no overall Dirac delta function. In order to compute loop integrals, please use the function
pySecDec.loop_integral.loop_package()
.normaliz_executable – string, optional; The command to run normaliz. normaliz is only required if decomposition_method starts with ‘geometric’. Default: use normaliz from pySecDecContrib
enforce_complex – bool, optional; Whether or not the generated integrand functions should have a complex return type even though they might be purely real. The return type of the integrands is automatically complex if contour_deformation is
True
or if there are complex_parameters. In other cases, the calculation can typically be kept purely real. Most commonly, this flag is needed iflog(<negative real>)
occurs in one of the integrand functions. However, pySecDec will suggest setting this flag toTrue
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
disablesintegrate_by_parts()
, while0
disablesintegrate_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. Thenintegrate_pole_part()
is called.Default:
1
use_iterative_sort – bool; Whether or not to use
squash_symmetry_redundant_sectors_sort()
withiterative_sort()
to find sector symmetries. Default:True
use_light_Pak – bool; Whether or not to use
squash_symmetry_redundant_sectors_sort()
withlight_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. IfTrue
, use dreadnaut from pySecDecContrib. Default:False
use_Pak – bool; Whether or not to use
squash_symmetry_redundant_sectors_sort()
withPak_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 CPUsmultiprocessing.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()
. IfNone
, then either$FORM
,$SECDEC_CONTRIB/bin/form
, or justform
is used, depending on which environment variable is set. Default:None
.pylink_qmc_transforms –
list or None, optional; Required qmc integral transforms, options are:
none
baker
korobov<i>x<j>
for 1 <= i,j <= 6korobov<i>
for 1 <= i <= 6 (same askorobov<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(exp_param_index, polynomials, region_vector)¶
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
exp_param_index – integer; Index of the expansion parameter in the list of symbols.
polynomials – iterable of polynomials; Polynomials to be computed in different regions.
region_vector – vectorlike array; Region specified by the power of the expansion_parameter in the rescaled variables. The region vectors have to be specified in the same order as the symbols are specified in the polynomials. E.g. if symbols are specified as [‘x0’,’x1’,’rho’] and want rescaling x0 > rho^i * x0, x1 > rho^k * x1 and rho > rho^n, then the region vector needs to be [i,k,n]
 pySecDec.make_regions.derive_prod(poly_list, numerator, index, polynomial_name_indices)¶
Calculates the derivative of a product of polynomials using
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 symbolsx0,x1,x2,..
andp0,p1,p2..
wherep0,p1,p2..
are the bases of the exponentiated polynomials.numerator –
Polynomial
; The numerator also defined as an exponentiated polynomial withsymbols = [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 symbolsx0,x1,x2,..
andp0,p1,p2..
wherep0,p1,p2..
are the bases of the exponentiated polynomials.numerator –
Polynomial
; The numerator also defined as an exponentiated polynomial withsymbols = [x0,x1,...,p0,p1,...]
.index – integer; Index of variable with respect to which the polynomials are expanded.
order – integer; Desired order of expansion.
polynomial_name_indices – list of int; Indices of polynomials in the symbols of the input polynomials.
 pySecDec.make_regions.find_regions(exp_param_index, polynomial, indices=None, normaliz=None, workdir='normaliz_tmp')¶
Find regions for the expansion by regions as described in [PS11].
Note
This function calls the command line executable of normaliz [BIR].
 Parameters
exp_param_index – int; The index of the expansion parameter in the expolist.
polynomials – an instance of
Polynomial
, for which to calculate the regions for.indices – list of integers or None; The indices of the parameters to be included in the asymptotic expansion. This should include all Feynman parameters (integration variables) and the expansion parameter. By default (
indices=None
), all parameters are considered.normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
workdir –
string; The directory for the communication with normaliz. A directory with the specified name will be created in the current working directory. If the specified directory name already exists, an
OSError
is raised.Note
The communication with normaliz is done via files.
 pySecDec.make_regions.make_regions(name, integration_variables, regulators, requested_orders, smallness_parameter, polynomials_to_decompose, numerator='1', expansion_by_regions_order=0, real_parameters=[], complex_parameters=[], normaliz=None, polytope_from_sum_of=None, **make_package_args)¶
Applies the expansion by regions method (see e.g. [PS11]) to a list of polynomials.
 Parameters
name – string; The name of the c++ 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
orpySecDec.algebra.Polynomial
; The polynomials to be decomposed.numerator – String or
pySecDec.algebra.Polynomial
; Polynomial that is not included in the determination of the regions. The symbols defined in polynomial_names can be used to reference the polynomials_to_decompose. Default: ‘1’expansion_by_regions_order – integer; The order up to which the expression is expanded in the smallness_parameter. Default: 0
real_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as real variables.
complex_parameters – iterable of strings or sympy symbols, optional; Symbols to be interpreted as complex variables.
normaliz – string; The shell command to run normaliz. Default: use normaliz from pySecDecContrib
polytope_from_sum_of – iterable of integers; If this value is None, the product of all the polynomials polynomials_to_decompose is used to determine the Newton polytope and the normal vectors to it. Otherwise, the sum of the polynomials with the indices given by this parameter are used.
make_package_args – The arguments to be forwarded to
pySecDec.code_writer.make_package()
.