Integrator wrapper-class

class integrator

Defines a functor wrapping the C-level functions Rdqags and Rdqagi for the numerical integration of univariate real functions declared in the R-header and implemented in .

Integration parameters can be configured via structs of type integratecpp::integrator::config_type, holding the maximal number of subdivisions, the required relative error, the required absolute error, and the size of the working array. Parameter preconditions are unchecked.
The operator integratecpp::integrator::operator()() is called with a Callable object invocable with arguments const double and returns double, a lower bound, and an upper bound. If the Callable returns infinite values, an exception is thrown. Internally, a callback function is generated and passed to the C-level functions Rdqag[is]; exceptions in the Callable are temporarily caught, stored, and rethrown after returning to C++ code.
Integration results are returned in structs of type integratecpp::integrator::return_type with the approximated integral value, an estimated error, the final number of subdivisions, and the number of function evaluations.
Issues regarding the configuration parameter throw an exception, deriving from integratecpp::integration_logic_error and issues during the integration may throw exceptions deriving from integratecpp::integration_runtime_error. Both have accessors to the result-state at error which can be used for error handling.

Public Functions

inline explicit constexpr integrator(const config_type &config) noexcept(std::is_nothrow_copy_constructible<config_type>::value)

A full constructor using integratecpp::integrator::config_type.

Parameters:: config – a integratecpp::integrator::config_type.

inline explicit constexpr integrator(const int max_subdivisions, const double relative_accuracy) noexcept

A partial constructor using max_subdivisions and relative_accuracy.

Warning

Preconditions for the configuration parameters are unchecked upon construction.

Parameters:

max_subdivisions – an int for the maximum number of subdivisions.
relative_accuracy – a double for the requested relative accuracy.

inline explicit constexpr integrator(const int max_subdivisions, const double relative_accuracy, const double absolute_accuracy) noexcept

A partial constructor using max_subdivisions, relative_accuracy, and absolute_accuracy.

Warning

Preconditions for the configuration parameters are unchecked upon construction.

Parameters:

max_subdivisions – an int for the maximum number of subdivisions.
relative_accuracy – a double for the requested relative accuracy.
absolute_accuracy – a double for the requested absolute accuracy.

inline explicit constexpr integrator(const int max_subdivisions, const double relative_accuracy, const double absolute_accuracy, const int work_size) noexcept

A full constructor using max_subdivisions, relative_accuracy, absolute_accuracy, and work_size.

Warning

Preconditions for the configuration parameters are unchecked upon construction.

Parameters:

max_subdivisions – an int for the maximum number of subdivisions.
relative_accuracy – a double for the requested relative accuracy.
absolute_accuracy – a double for the requested absolute accuracy.
work_size – an int for the size of the working array.

template<typename UnaryRealFunction_> inline return_type operator()(UnaryRealFunction_ &&fn, const double lower, const double upper) const

Approximates an integral numerically for a functor, lower, and upper bound, using Rdqags if both bounds are are finite and Rdqagi of at least one of the bounds is infinite.

Template Parameters:

UnaryRealFunction_ – A Callable type invocable with const double and returning double.

Parameters:

fn – a UnaryRealFunction_ functor compatible with a const double signature.
lower – a double for the lower bound.
upper – a double for the upper bound.

Throws:

throws – integratecpp::invalid_input_error if configuration parameters’ preconditions are not fulfilled.
throws – integratecpp::max_subdivision_error if the maximal number of subdivisions is reached without fulfilling required error conditions.
throws – integratecpp::roundoff_error if a roundoff error is detected which prevents the requested accuracy from being achieved.
throws – integratecpp::bad_integrand_error if extremely bad integrand behaviour is detected during integration.
throws – integratecpp::extrapolation_roundoff_error if a roundoff error is detected in the extrapolation table.
throws – integratecpp::divergence_error if the integral is deemed divergence (or slowly convergent).
throws – integratecpp::integration_runtime_error if the Callable returns infinite values.
rethrows – caught exceptions that occur during the evaluation of the Callable.

Returns:

a integratecpp::integrator::return_type with the integration results.

struct config_type

Defines a struct for the integration configuration parameters used in integratecpp::integrator::operator()(). Compare in R-source.

Warning

Preconditions for the configuration parameters are unchecked upon construction.

Public Functions

inline explicit constexpr config_type(const int max_subdivisions, const double relative_accuracy) noexcept

A partial constructor for max_subdivisions and relative_accuracy.

Warning

Preconditions for the configuration parameters are unchecked upon construction.

Parameters:

max_subdivisions – an int for the maximum number of subdivisions.
relative_accuracy – a double for the requested relative accuracy.

inline explicit constexpr config_type(const int max_subdivisions, const double relative_accuracy, const double absolute_accuracy) noexcept

A partial constructor for max_subdivisions, relative_accuracy, and absolute_accuracy.

Warning

Preconditions for the configuration parameters are unchecked upon construction.

Parameters:

max_subdivisions – an int for the maximum number of subdivisions.
relative_accuracy – a double for the requested relative accuracy.
absolute_accuracy – a double for the requested absolute accuracy.

inline explicit constexpr config_type(const int max_subdivisions, const double relative_accuracy, const double absolute_accuracy, const int work_size) noexcept

The full constructor.

Warning

Preconditions for the configuration parameters are unchecked upon construction.

Parameters:

max_subdivisions – an int for the maximum number of subdivisions.
relative_accuracy – a double for the requested relative accuracy.
absolute_accuracy – a double for the requested absolute accuracy.
work_size – an int for the size of the working array.

Public Members

int max_subdivisions = {100}

The maximum number of subdivisions.

Pre:: max_subdivisions >= 1.
Pre:: work_size >= 4 * max_subdivisions.

double relative_accuracy{std::pow(std::numeric_limits<double>::epsilon(), 0.25)}

The requested relative accuracy.

Pre:: relative_accuracy > 0 || relative_accuracy >= max(50. * rel.mach.acc., 0.5e-28).

double absolute_accuracy = {relative_accuracy}

The requested absolute accuracy.

Pre:: relative_accuracy > 0 || relative_accuracy >= max(50. * rel.mach.acc., 0.5e-28).

int work_size = {400}

The dimensioning parameter of the working array.

Pre:: work_size >= 4 * max_subdivisions.

struct return_type

Defines a struct for the integration results returned from integratecpp::integrator::operator()(). Compare in R-source):

Public Functions

inline explicit constexpr return_type(const double value, const double absolute_error, const int subdivisions, const int neval) noexcept

The full constructor.

Parameters:

value – a double with the approximated value.
absolute_error – a double with the estimated absolute error.
subdivisions – an int with the final number of subdivisions.
neval – an int with the number of neval.

Public Members

double value: The approximated value.

double absolute_error: The estimated absolute error.

int subdivisions: The final number of subdivisions.

int neval: The number of function evaluations.