util.rst

.. cpp:namespace:: secdecutil

SecDecUtil

SecDecUtil is a standalone autotools-c++ package, that collects common helper classes and functions needed by the c++ code generated using :func:`loop_package <pySecDec.loop_integral.loop_package>` or :func:`make_package <pySecDec.code_writer.make_package>`. Everything defined by the SecDecUtil is put into the c++ namepace secdecutil.

Series

A class template for containing (optionally truncated) Laurent series. Multivariate series can be represented as series of series.

This class overloads the arithmetic operators (+, -, *, /) and the comparator operators (==, !=). A string representation can be obtained using the << operator. The at(i) and [i] operators return the coefficient of the i^th power of the expansion parameter. Otherwise elements can be accessed identically to :cpp:class:`std::vector`.

.. cpp:class:: template <typename T> Series

    .. cpp:var:: std::string expansion_parameter

        A string representing the expansion parameter of the series (default ``x``)

    .. cpp:function:: int get_order_min() const

        Returns the lowest order in the series.

    .. cpp:function:: int get_order_max() const

        Returns the highest order in the series.

    .. cpp:function:: bool get_truncated_above() const

        Checks whether the series is truncated from above.

    .. cpp:function:: bool has_term(int order) const

        Checks whether the series has a term at order ``order``.

    .. cpp:function:: Series(int order_min, int order_max, std::vector<T> content, bool truncated_above = true, const std::string expansion_parameter = "x")

Example:

.. literalinclude:: cpp_doctest/series_doctest_basic_usage.cpp
   :language: cpp

Compile/Run:

.. literalinclude:: cpp_doctest/compile_and_run.txt

Output:

.. literalinclude:: cpp_doctest/series_doctest_basic_usage.txt
   :language: sh

Deep Apply

A general concept to apply a :cpp:class:`std::function` to a nested data structure. If the applied :cpp:class:`std::function` is not void then :cpp:func:`deep_apply` returns a nested data structure of the return values. Currently secdecutil implements this for :cpp:class:`std::vector` and :cpp:class:`Series`.

This concept allows, for example, the elements of a nested series to be edited without knowing the depth of the nested structure.

.. cpp:function:: template<typename Tout, typename Tin, template<typename...> class Tnest> Tnest<Tout> deep_apply(Tnest<Tin>& nest, std::function<Tout(Tin)>& func)

Example (complex conjugate a :cpp:class:`Series`):

.. literalinclude:: cpp_doctest/deep_apply_doctest_basic_usage.cpp
   :language: cpp

Compile/Run:

.. literalinclude:: cpp_doctest/compile_and_run.txt

Output:

.. literalinclude:: cpp_doctest/deep_apply_doctest_basic_usage.txt
   :language: sh

Uncertainties

A class template which implements uncertainty propagation for uncorrelated random variables by overloads of the +, -, * and partially /. Division by :cpp:class:`UncorrelatedDeviation` is not implemented as it is not always defined. It has special overloads for :cpp:class:`std::complex\<T\>`.

Note

Division by :cpp:class:`UncorrelatedDeviation` is not implemented as this operation is not always well defined. Specifically, it is ill defined in the case that the errors are Gaussian distributed as the expectation value,

\mathrm{E}\left[\frac{1}{X}\right] = \int_{-\infty}^{\infty} \frac{1}{X} p(X)\ \mathrm{d}X,

where

p(X) = \frac{1}{\sqrt{2 \pi \sigma^2 }} \exp\left( -\frac{(x-\mu)^2}{2\sigma^2} \right),

is undefined in the Riemann or Lebesgue sense. The rule \delta(a/b) = |a/b| \sqrt{ (\delta a/a)^2 + (\delta b/b)^2 } can not be derived from the first principles of probability theory.

The rules implemented for real valued error propagation are:

\delta(a+b) = \sqrt{(\delta a)^2 + (\delta b)^2},

\delta(a-b) = \sqrt{(\delta a)^2 + (\delta b)^2},

\delta(ab) = \sqrt{ (\delta a)^2 b^2 + (\delta b)^2 a^2 + (\delta a)^2 (\delta b)^2 }.

For complex numbers the above rules are implemented for the real and imaginary parts individually.

.. cpp:class:: template <typename T> UncorrelatedDeviation

    .. cpp:var:: T value

        The expectation value.

    .. cpp:var:: T uncertainty

        The standard deviation.

Example:

.. literalinclude:: cpp_doctest/uncertainties_doctest_basic_usage.cpp
   :language: cpp

Compile/Run:

.. literalinclude:: cpp_doctest/compile_and_run.txt

Output:

.. literalinclude:: cpp_doctest/uncertainties_doctest_basic_usage.txt
   :language: sh

Integrand Container

A class template for containing integrands. It stores the number of integration variables and the integrand as a :cpp:class:`std::function`.

This class overloads the arithmetic operators (+, -, *, /) and the call operator (()).

.. cpp:class:: template <typename T, typename ...Args> IntegrandContainer

    .. cpp:var:: int number_of_integration_variables

        The number of integration variables that the integrand depends on.

    .. cpp:var:: std::function<T(Args...)> integrand

        The integrand function. The call operator forwards to this function.

Example (add two :cpp:class:`IntegrandContainer` and evaluate one point):

.. literalinclude:: cpp_doctest/integrand_container_doctest_basic_usage.cpp
   :language: cpp

Compile/Run:

.. literalinclude:: cpp_doctest/compile_and_run.txt

Output:

.. literalinclude:: cpp_doctest/integrand_container_doctest_basic_usage.txt
   :language: sh

Integrator

A base class template from which integrator implementations inherit. It defines the minimal API available for all integrators.

.. cpp:class:: template<typename return_t, typename input_t, typename container_t = secdecutil::IntegrandContainer<return_t, input_t const * const>> Integrator

    .. cpp::type:: container_t

        The type of the integrand. It must have the field ``number_of_integration_variables`` and be callable.

    .. cpp:var:: bool together

        (Only available if ``return_t`` is a :cpp:class:`std::complex` type)
        If ``true`` after each call of the function both the real and imaginary parts are passed to the underlying integrator.
        If ``false`` after each call of the function only the real or imaginary part is passed to the underlying integrator.
        For some adaptive integrators considering the real and imaginary part of a complex function separately can improve the sampling.
        Default: ``false``.

    .. cpp:function:: UncorrelatedDeviation<return_t> integrate(const IntegrandContainer<return_t, input_t const * const>&)

        Integrates the :cpp:class:`IntegrandContainer` and returns the value and uncertainty as an :cpp:class:`UncorrelatedDeviation`.

An integrator that chooses another integrator based on the dimension of the integrand.

.. cpp:class:: template<typename return_t, typename input_t> MultiIntegrator

    .. cpp:var:: Integrator<return_t,input_t>& low_dimensional_integrator

        Reference to the integrator to be used if the integrand has a lower dimension than :cpp:var:`critical_dim`.

    .. cpp:var:: Integrator<return_t,input_t>& high_dimensional_integrator

        Reference to the integrator to be used if the integrand has dimension :cpp:var:`critical_dim` or higher.

    .. cpp:var:: int critical_dim

        The dimension below which the :cpp:var:`low_dimensional_integrator` is used.

CQuad

For one dimensional integrals, we wrap the cquad integrator form the GNU scientifc library (gsl).

CQuad takes the following options:

• epsrel - The desired relative accuracy for the numerical evaluation. Default: 0.01.
• epsabs - The desired absolute accuracy for the numerical evaluation. Default: 1e-7.
• n - The size of the workspace. This value can only be set in the constructor. Changing this attribute of an instance is not possible. Default: 100.
• verbose - Whether or not to print status information. Default: false.
• zero_border - The minimal value an integration variable can take. Default: 0.0. (new in version 1.3)

Qmc

.. cpp:namespace:: secdecutil::integrators

The quasi-monte carlo integrator as described in [PSD18]_. Using a quasi-monte integrator to compute sector decomposed integrals was pioneered in [LWY+15]_.

.. cpp:class:: template<typename return_t, ::integrators::U maxdim, template<typename,typename,::integrators::U> class transform_t,typename container_t = secdecutil::IntegrandContainer<return_t, typename remove_complex<return_t>::type const * const>,template<typename,typename,::integrators::U> class fitfunction_t = void_template> Qmc : Integrator<return_t,return_t,container_t>, public ::integrators::Qmc<return_t,return_t,maxdim,transform_t,fitfunction_t>

    Derived from :cpp:class:`secdecutil::Integrator` and :cpp:class:`::integrators::Qmc` - the
    underlying standalone implementation of the Qmc.

The most important fields and template argments of :cpp:class:`Qmc` are:

• minn - The minimal number of points in the Qmc lattice. Will be augmented to the next larger available n.
• minm - The minimal number of random shifts.
• maxeval - The maximal number of integrand evaluations.
• epsrel - The desired relative accuracy for the numerical evaluation.
• epsabs - The desired absolute accuracy for the numerical evaluation.
• maxdim - The highest dimension the :cpp:class:`Qmc` instance can be used for.
• transform_t - The periodizing transform to apply prior to integration.
• fitfunction_t - The fit function transform to apply for adaptive integration.
• verbosity - Controls the amount of status messages during integration. Can be 0, 1, 2, or 3.
• devices - A :cpp:class:`std::set` of devices to run on. -1 denotes the CPU, positive integers refer to GPUs.

Refer to the documentation of the standalone Qmc for the default values and additional information.

An integral transform has to be chosen by setting the template argument :cpp:type:`transform_t`. Available transforms are e.g. Korobov<r0,r1> and Sidi<r0>, please refer to the underlying Qmc implementation for a complete list. The fit function for adaptive integration can be set by the :cpp:type:`fitfunction_t`, e.g. PolySingular. If not set, the default of the underlying Qmc implementation is used.

Examples how to use the Qmc :ref:`on the CPU<example_set_qmc_transform_cpp>` and on :ref:`both, CPU and GPU<example_cuda_qmc>` are shown below.

.. cpp:namespace:: secdecutil

Cuba

Currently we wrap the following Cuba integrators:

• Vegas
• Suave
• Divonne
• Cuhre

The Cuba integrators all implement:

• epsrel - The desired relative accuracy for the numerical evaluation. Default: 0.01.
• epsabs - The desired absolute accuracy for the numerical evaluation. Default: 1e-7.
• flags - Sets the Cuba verbosity flags. The flags=2 means that the Cuba input parameters and the result after each iteration are written to the log file of the numerical integration. Default: 0.
• seed - The seed used to generate random numbers for the numerical integration with Cuba. Default: 0.
• mineval - The number of evaluations which should at least be done before the numerical integrator returns a result. Default: 0.
• maxeval - The maximal number of evaluations to be performed by the numerical integrator. Default: 1000000.
• zero_border - The minimal value an integration variable can take. Default: 0.0. (new in version 1.3)

The available integrator specific parameters and their default values are:

Vegas	Suave	Divonne	Cuhre
nstart (1000)	nnew (1000)	key1 (2000)	key (0)
nincrease (500)	nmin (10)	key2 (1)
nbatch (500)	flatness (25.0)	key3 (1)
		maxpass (4)
		border (0.0)
		maxchisq (1.0)
		mindeviation (0.15)

For the description of these more specific parameters we refer to the Cuba manual.

Examples

Integrate Real Function with Cuba Vegas

Example:

.. literalinclude:: cpp_doctest/integrator_doctest_basic_usage.cpp
   :language: cpp

Compile/Run:

.. literalinclude:: cpp_doctest/compile_and_run_cuba.txt

Output:

.. literalinclude:: cpp_doctest/integrator_doctest_basic_usage.txt
   :language: sh

Integrate Complex Function with Cuba Vegas

Example:

.. literalinclude:: cpp_doctest/integrator_doctest_complex.cpp
   :language: cpp

Compile/Run:

.. literalinclude:: cpp_doctest/compile_and_run_cuba.txt

Output:

.. literalinclude:: cpp_doctest/integrator_doctest_complex.txt
   :language: sh

Integrate Real Function with Cuba Vegas or CQuad

Example:

.. literalinclude:: cpp_doctest/integrator_doctest_Vegas_CQuad.cpp
   :language: cpp

Compile/Run:

.. literalinclude:: cpp_doctest/compile_and_run_cuba_gsl.txt

Output:

.. literalinclude:: cpp_doctest/integrator_doctest_Vegas_CQuad.txt
   :language: sh

Set the integral transform of the Qmc

Example:

.. literalinclude:: cpp_doctest/integrator_doctest_set_transform_qmc.cpp
   :language: cpp

Compile/Run:

.. literalinclude:: cpp_doctest/compile_and_run_set_transform_qmc.txt

Output:

.. literalinclude:: cpp_doctest/integrator_doctest_set_transform_qmc.txt
   :language: sh

Run the Qmc on GPUs

Example:

.. literalinclude:: cpp_doctest/integrator_doctest_cuda_qmc.cu
   :language: cpp

Compile/Run:

.. literalinclude:: cpp_doctest/compile_and_run_cuda_qmc.txt

Output:

.. literalinclude:: cpp_doctest/integrator_doctest_cuda_qmc.txt
   :language: sh