NcmIntegralND: NumCosmo Reference Manual

NcmIntegralND

NcmIntegralND — N-dimensional integration object.

Stability Level

Stable, unless otherwise indicated

Functions

void	(*NcmIntegralNDF) ()
void	(*NcmIntegralNDGetDimensions) ()
NcmIntegralND *	ncm_integral_nd_ref ()
void	ncm_integral_nd_free ()
void	ncm_integral_nd_clear ()
void	ncm_integral_nd_set_method ()
void	ncm_integral_nd_set_error ()
void	ncm_integral_nd_set_maxeval ()
void	ncm_integral_nd_set_reltol ()
void	ncm_integral_nd_set_abstol ()
NcmIntegralNDMethod	ncm_integral_nd_get_method ()
NcmIntegralNDError	ncm_integral_nd_get_error ()
guint	ncm_integral_nd_get_maxeval ()
gdouble	ncm_integral_nd_get_reltol ()
gdouble	ncm_integral_nd_get_abstol ()
void	ncm_integral_nd_eval ()
#define	NCM_INTEGRAL_ND_DEFINE_TYPE_WITH_FREE()
#define	NCM_INTEGRAL_ND_DEFINE_TYPE()

Properties

double	abstol	Read / Write / Construct
NcmIntegralNDError	error	Read / Write / Construct
guint	maxeval	Read / Write / Construct
NcmIntegralNDMethod	method	Read / Write / Construct
double	reltol	Read / Write / Construct

Types and Values

#define	NCM_TYPE_INTEGRAL_ND
struct	NcmIntegralNDClass
enum	NcmIntegralNDMethod
enum	NcmIntegralNDError
#define	NCM_INTEGRAL_ND_DEFAULT_RELTOL
#define	NCM_INTEGRAL_ND_DEFAULT_ABSTOL
	NcmIntegralND

Object Hierarchy

    GEnum
    ├── NcmIntegralNDError
    ╰── NcmIntegralNDMethod
    GObject
    ╰── NcmIntegralND

Includes

#include <numcosmo/math/ncm_integral_nd.h>

Description

This object is used to perform n-dimensional integration of a function using different methods.

The integration can be performed using the cubature library. The cubature library is a library for adaptive multidimensional integration. The original code can be found at https://github.com/stevengj/cubature.

To use this object, the user must initialize a child object that implements two functions: get_dimensions and integrand. To do so, the user must first define these two functions as the prototypes described in ncm_integral_nd.h. The get dimensions function should return the dimension of the arguments to be integrated and the function dimension. For instance, if the integrand is given by $F(x,y) = x + y$, the get dimensions function must return $(2,1)$, such that it will compute \begin{align} \int \int F(x, y) dxdy ,\end{align} returning a scalar for the integral evaluated in the given intervals.

This object can also be used with multi-dimensional functions that return an array instead of a scalar. Considering the integrand $F(x,y,z) = [x^2, y+z ]$, the get dimensions method should return $(3,2)$ and the object will compute the integral \begin{align} \int \int \int F(x,y,z) dxdy = [\frac{yzx^3}{3}, frac{x(y^2+z^2)}{2}] \end{align} for the given intervals.

Having the functions, the user must instantiate an object of the type NcmIntegralNDClass defined with these functions. To do so, one must call the macro NCM_INTEGRAL_ND_DEFINE_TYPE to define the new object type, which will later be instantiable. Examples of how to define the objects containing the integrand can be found in the test folder under test\textunderscore ncm\textunderscore integral\textunderscore nd.c. For an example of the Python implementation of the integrand in a class, check test\textunderscore py\textunderscore integralnd.py in the same folder. This object cannot be used without the child object containing the cited functions.

After defining the child class with the necessary functions, the user may use the integration object with the prefered method from the cubature library.

The user may provide the input values for: rel_tol - ncm_integral_nd_set_reltol(), abs_tol - ncm_integral_nd_set_abstol(), integ_method - ncm_integral_nd_set_method(), max_eval - ncm_integral_nd_set_maxeval(), error - ncm_integral_nd_set_error(). If these functions are not called, default parameters are chosen.

Functions

NcmIntegralNDF ()

void
(*NcmIntegralNDF) (NcmIntegralND *intnd,
                   NcmVector *x,
                   guint dim,
                   guint npoints,
                   guint fdim,
                   NcmVector *fval);

The type of the function that must be implemented by a subclass of NcmIntegralND.

This function receives npoints points in the array x (size dim * npoints ), and returns an array (size fdim * npoints ) of npoints values of the integrand at all points in x . The x is an array of doubles in row-major order (i.e. the first dim elements of x are the coordinates of the first point, the next dim elements are the coordinates of the second point, and so on). The return value is an array of fdim values of the integrand at all points in x (e.g. the first fdim elements are the values of the integrand at the first point, the next fdim elements are the values of the integrand at the second point, and so on).

Parameters

intnd	a NcmIntegralND
x	a NcmVector containing the value of the variable of integration
dim	the dimension of the integral argument
npoints	the number of points in the array `x`
fdim	the dimension of the function to be integrated
fval	a NcmVector containing the `fdim` values of the integrand at all points in `x`

NcmIntegralNDGetDimensions ()

void
(*NcmIntegralNDGetDimensions) (NcmIntegralND *intnd,
                               guint *dim,
                               guint *fdim);

The type of the function that must be implemented by a subclass of NcmIntegralND.

This function returns the dimension of the integral argument and the dimension of the function to be integrated.

Parameters

intnd	a NcmIntegralND
dim	the dimension of the integral argument.	[out]
fdim	the dimension of the function to be integrated.	[out]

ncm_integral_nd_ref ()

NcmIntegralND *
ncm_integral_nd_ref (NcmIntegralND *intnd);

Increases the reference count of intnd by one.

Parameters

intnd

a NcmIntegralND

Returns

intnd .

[transfer full]

ncm_integral_nd_free ()

void
ncm_integral_nd_free (NcmIntegralND *intnd);

Decreases the reference count of intnd by one.

Parameters

intnd

a NcmIntegralND

ncm_integral_nd_clear ()

void
ncm_integral_nd_clear (NcmIntegralND **intnd);

If *intnd is different from NULL, decreases the reference count of *intnd by one and sets *intnd to NULL.

Parameters

intnd

a NcmIntegralND

ncm_integral_nd_set_method ()

void
ncm_integral_nd_set_method (NcmIntegralND *intnd,
                            NcmIntegralNDMethod method);

Sets the integration method to use.

Parameters

intnd	a NcmIntegralND
method	a NcmIntegralNDMethod

ncm_integral_nd_set_error ()

void
ncm_integral_nd_set_error (NcmIntegralND *intnd,
                           NcmIntegralNDError error);

Sets the error measure to use.

Parameters

intnd	a NcmIntegralND
error	a NcmIntegralNDError

ncm_integral_nd_set_maxeval ()

void
ncm_integral_nd_set_maxeval (NcmIntegralND *intnd,
                             guint maxeval);

Sets the maximum number of function evaluations to use. Zero means unlimited.

Parameters

intnd	a NcmIntegralND
maxeval	maximum number of function evaluations

ncm_integral_nd_set_reltol ()

void
ncm_integral_nd_set_reltol (NcmIntegralND *intnd,
                            gdouble reltol);

Sets the relative tolerance reltol to use.

Parameters

intnd	a NcmIntegralND
reltol	relative tolerance

ncm_integral_nd_set_abstol ()

void
ncm_integral_nd_set_abstol (NcmIntegralND *intnd,
                            gdouble abstol);

Sets the absolute tolerance reltol to use.

Parameters

intnd	a NcmIntegralND
abstol	absolute tolerance

ncm_integral_nd_get_method ()

NcmIntegralNDMethod
ncm_integral_nd_get_method (NcmIntegralND *intnd);

Parameters

intnd

a NcmIntegralND

Returns

the integration method used.

ncm_integral_nd_get_error ()

NcmIntegralNDError
ncm_integral_nd_get_error (NcmIntegralND *intnd);

Parameters

intnd

a NcmIntegralND

Returns

the error measure used.

ncm_integral_nd_get_maxeval ()

guint
ncm_integral_nd_get_maxeval (NcmIntegralND *intnd);

Parameters

intnd

a NcmIntegralND

Returns

the maximum number of function evaluations used.

ncm_integral_nd_get_reltol ()

gdouble
ncm_integral_nd_get_reltol (NcmIntegralND *intnd);

Parameters

intnd

a NcmIntegralND

Returns

the relative tolerance used.

ncm_integral_nd_get_abstol ()

gdouble
ncm_integral_nd_get_abstol (NcmIntegralND *intnd);

Parameters

intnd

a NcmIntegralND

Returns

the absolute tolerance used.

ncm_integral_nd_eval ()

void
ncm_integral_nd_eval (NcmIntegralND *intnd,
                      const NcmVector *xi,
                      const NcmVector *xf,
                      NcmVector *res,
                      NcmVector *err);

Evaluated the integral $I_F(x_i, x_f) = \int_{x_i}^{x_f}F(x)\mathrm{d}x$.

Parameters

intnd	a NcmIntegralND
xi	a NcmVector containing the inferior integration limit $x_i$
xf	a NcmVector containing the superior integration limit $x_f$
res	a NcmVector containing the result of the integration
err	a NcmVector containing the error of the integration

NCM_INTEGRAL_ND_DEFINE_TYPE_WITH_FREE()

#define             NCM_INTEGRAL_ND_DEFINE_TYPE_WITH_FREE(MODULE, OBJ_NAME, ModuleObjName, module_obj_name, method_get_dimensions, method_integrand, user_data, user_data_free)

A convenience macro to define a subclass of NcmIntegralND with a custom user data type and a custom method to free the user data.

Parameters

MODULE	the name of the module defining the type, all capitalized
OBJ_NAME	the name of the type to define, all capitalized
ModuleObjName	the name of the type to define, camel case
module_obj_name	the name of the type to define, sneake case
method_get_dimensions	the name of the method that returns the dimension of the integral argument and the dimension of the function to be integrated
method_integrand	the name of the method that returns the value of the integrand at all points in `x`
user_data	the type of the user data
user_data_free	the name of the method that frees the user data

NCM_INTEGRAL_ND_DEFINE_TYPE()

#define             NCM_INTEGRAL_ND_DEFINE_TYPE(MODULE, OBJ_NAME, ModuleObjName, module_obj_name, method_get_dimensions, method_integrand, user_data)

A convenience macro to define a subclass of NcmIntegralND with a custom user data type.

Parameters

MODULE	the name of the module defining the type, all capitalized
OBJ_NAME	the name of the type to define, all capitalized
ModuleObjName	the name of the type to define, camel case
module_obj_name	the name of the type to define, sneake case
method_get_dimensions	the name of the method that returns the dimension of the integral argument and the dimension of the function to be integrated
method_integrand	the name of the method that returns the value of the integrand at all points in `x`
user_data	the type of the user data

Types and Values

NCM_TYPE_INTEGRAL_ND

#define NCM_TYPE_INTEGRAL_ND (ncm_integral_nd_get_type ())

struct NcmIntegralNDClass

struct NcmIntegralNDClass {
};

enum NcmIntegralNDMethod

The type of the method used to perform the integral.

Members

NCM_INTEGRAL_ND_METHOD_CUBATURE_H	adapative integration by partitioning the integration domain ("h-adaptive") and using the same fixed-degree quadrature in each subdomain, recursively, until convergence is achieved.
NCM_INTEGRAL_ND_METHOD_CUBATURE_P	adaptive integration by increasing the degree of (tensor-product Clenshaw-Curtis) quadrature rules ("p-adaptive"), rather than subdividing the domain ("h-adaptive"). Possibly better for smooth integrands in low dimensions.
NCM_INTEGRAL_ND_METHOD_CUBATURE_H_V	same as `NCM_INTEGRAL_ND_METHOD_CUBATURE_H` with vectorized integrand
NCM_INTEGRAL_ND_METHOD_CUBATURE_P_V	same as `NCM_INTEGRAL_ND_METHOD_CUBATURE_P` with vectorized integrand

enum NcmIntegralNDError

The type of the error estimation used to perform the integral.

Members

NCM_INTEGRAL_ND_ERROR_INDIVIDUAL	error is estimated for each integrand separately
NCM_INTEGRAL_ND_ERROR_PAIRWISE	error is estimated for each pair of integrands
NCM_INTEGRAL_ND_ERROR_L2	error is estimated for the L2 norm of the vector of integrands
NCM_INTEGRAL_ND_ERROR_L1	error is estimated for the L1 norm of the vector of integrands
NCM_INTEGRAL_ND_ERROR_LINF	error is estimated for the L-infinity norm of the vector of integrands

NCM_INTEGRAL_ND_DEFAULT_RELTOL

#define NCM_INTEGRAL_ND_DEFAULT_RELTOL 1e-7

NCM_INTEGRAL_ND_DEFAULT_ABSTOL

#define NCM_INTEGRAL_ND_DEFAULT_ABSTOL 0.0

NcmIntegralND

typedef struct _NcmIntegralND NcmIntegralND;

Property Details

The `“abstol”` property

  “abstol”                   double

Integral absolute tolerance.

Owner: NcmIntegralND

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 0

The `“error”` property

  “error”                    NcmIntegralNDError

Error measure.

Owner: NcmIntegralND

Flags: Read / Write / Construct

Default value: NCM_INTEGRAL_ND_ERROR_INDIVIDUAL

The `“maxeval”` property

  “maxeval”                  guint

Maximum number of function evaluations (0 means unlimited).

Owner: NcmIntegralND

Flags: Read / Write / Construct

Default value: 0

The `“method”` property

  “method”                   NcmIntegralNDMethod

Integration method.

Owner: NcmIntegralND

Flags: Read / Write / Construct

Default value: NCM_INTEGRAL_ND_METHOD_CUBATURE_H

The `“reltol”` property

  “reltol”                   double

Integral relative tolerance.

Owner: NcmIntegralND

Flags: Read / Write / Construct

Allowed values: [0,1]

Default value: 1e-07

NcmIntegralND

Stability Level

Functions

Properties

Types and Values

Object Hierarchy

Includes

Description

Functions

NcmIntegralNDF ()

Parameters

NcmIntegralNDGetDimensions ()

Parameters

ncm_integral_nd_ref ()

Parameters

Returns

ncm_integral_nd_free ()

Parameters

ncm_integral_nd_clear ()

Parameters

ncm_integral_nd_set_method ()

Parameters

ncm_integral_nd_set_error ()

Parameters

ncm_integral_nd_set_maxeval ()

Parameters

ncm_integral_nd_set_reltol ()

Parameters

ncm_integral_nd_set_abstol ()

Parameters

ncm_integral_nd_get_method ()

Parameters

Returns

ncm_integral_nd_get_error ()

Parameters

Returns

ncm_integral_nd_get_maxeval ()

Parameters

Returns

ncm_integral_nd_get_reltol ()

Parameters

Returns

ncm_integral_nd_get_abstol ()

Parameters

Returns

ncm_integral_nd_eval ()

Parameters

NCM_INTEGRAL_ND_DEFINE_TYPE_WITH_FREE()

Parameters

NCM_INTEGRAL_ND_DEFINE_TYPE()

Parameters

Types and Values

NCM_TYPE_INTEGRAL_ND

struct NcmIntegralNDClass

enum NcmIntegralNDMethod

Members

enum NcmIntegralNDError

Members

NCM_INTEGRAL_ND_DEFAULT_RELTOL

NCM_INTEGRAL_ND_DEFAULT_ABSTOL

NcmIntegralND

Property Details

The “abstol” property

The “error” property

The “maxeval” property

The “method” property

The “reltol” property

The `“abstol”` property

The `“error”` property

The `“maxeval”` property

The `“method”` property

The `“reltol”` property