# Averaging functor or parameter¶

The escape.core.average module provides integration technique to find average value of a functor or parameter.

In addition to general method average which allows to find average using user defined distribution function, this sub package has also methods specific for distribution functions, defined in the escape.core.distribution module.

## Examples¶

1. $$\int_{-\infty}^{\infty} x G(x, x_0) dx = x_0$$, where $$G(x, x0)$$ is a Gaussian.

>>> x = esc.var("x")
>>> x0 = esc.var("x0")
>>> sig = 1.0
>>> G = 1/(np.sqrt(2*np.pi)*sig)*esc.exp(-(x-x0)**2/(2*sig**2))
>>> I = esc.average(x, G, x, x0, x0 - 5*sig, x0 + 5*sig, maxiter=10)
>>> I(1.2)
1.1999993148713521

1. $$\int_{-\infty}^{\infty} xp G(p, p_0) dp = xp_0$$, where $$G(p, p0)$$ is a Gaussian.

>>> x = esc.var("x")
>>> p = esc.par("p", 1)
>>> p0 = esc.par("p0", 1.2)
>>> sig = 1.0
>>> G = 1/(np.sqrt(2*np.pi)*sig)*esc.exp(-(p-p0)**2/(2*sig**2))
>>> I = esc.average(x*p, G, p, p0, x0 - 5*sig, x0 + 5*sig, maxiter=10)
>>> type(I)
<class 'escape.core.objects.functor_obj'>
>>> I(1)#I(x)=x*p0=1.2
1.1999993148713521

1. $$\int_{-\infty}^{\infty} p G(p, p_0) dp = p_0$$, where $$G(p, p0)$$ is a Gaussian.

>>> p = esc.par("p", 1)
>>> p0 = esc.par("p0", 1.2)
>>> sig = 1.0
>>> G = 1/(np.sqrt(2*np.pi)*sig)*esc.exp(-(p-p0)**2/(2*sig**2))
>>> I = esc.average(p, G, p, p0, p0 - 5*sig, p0 + 5*sig, maxiter=10)
>>> type(I)
<class 'escape.core.objects.parameter_obj'>
>>> I.value #I=p0=1.2
1.1999993148713521

1. $$\int_x^y p G(p, p_0) dp = I(x, y)$$, where $$G(p, p0)$$ is a Gaussian.

>>> x, y = esc.var(("x", "y"))
>>> p = esc.par("p", 1)
>>> p0 = esc.par("p0", 1.2)
>>> sig = 1.0
>>> G = 1/(np.sqrt(2*np.pi)*sig)*esc.exp(-(p-p0)**2/(2*sig**2))
>>> F = esc.func("p", x, p)
>>> I = esc.average(F, G, p, p0, x, y, maxiter=10)
>>> type(I)
<class 'escape.core.objects.functor_obj'>
>>> I.variables
[variable(name='x'), variable(name='y')]
>>> I(p0.value-5*sig, p0.value+5*sig)#I=p0
1.1999993148713521


The same result can be achieved using helper method for the normal distribution function as following:

>>> x = esc.var("x")
>>> x0 = esc.var("x0")
>>> fwhm = 2.355 #sigma=1
>>> I = esc.average_normal(x, fwhm, x, x0, maxiter=10)
>>> I(1.2)
1.1999993135018503

escape.core.average.average(funf, fung, x, mean, a, b, int numpoints=7, epsabs=None, epsrel=None, maxiter=None)

Returns functor which calculates an average value of a functor or parameter in the following form $$F(x_0)=\int_a^b f(x)G(x, x_0)dx$$, where $$x_0$$ - is a variable or parameter which correspond to the mean value, $$G(x, x_0)$$ - distribution function of two variables or parameters $$x$$ and $$x_0$$. $$x$$ and $$x_0$$ can be variables or parameters.

Parameters:
funf: functor_obj with variable or parameter ‘x’

averaged functor

fung: functor_obj with variables or parameters, ‘x’ and ‘x_0’

distribution functor

x: variable or independent parameter

integration variable

mean: variable or independent parameter

mean value of distribution function

a: functor_obj or parameter_obj
• lower integration limit

b: functor_obj or parameter_obj
• upper integration limit

numpoints - integer

number of points of Gauss-Kronrod quadratures method. Supported values are [7, 15, 21, 31, 51, 61]

epsabs: float value or None

absolute tolerance of integration result, used only for adaptive integration. If set to None, Default value of 1e-5 is used

epsrel: float value or None

relative tolerance of integration result, used only for adaptive integration. If set to None, Default value of 0 is used’

maxiter: positive integer value or None

maximum number of iterations of adaptive integration. If set to None or zero adaptive integration is not used.

Returns:

object of type functor_obj

escape.core.average.average_gamma(funf, sigma, x, mean, int numpoints=7, epsabs=None, epsrel=None, maxiter=None, int numstd=5)

Returns functor which calculates an average value of a functor or a parameter F(x) with Gamma distribution function.

Parameters:
funf: functor_obj with variable or parameter ‘x’

averaged functor

sigma: functor_obj with variable ‘x_0’, parameter or numeric

parameter of distribution function

x: variable or independent parameter

integration variable

mean: variable or independent parameter

mean value of distribution function

numpoints - integer

number of points of Gauss-Kronrod quadratures method. Supported values are [7, 15, 21, 31, 51, 61]

epsabs: float value or None

absolute tolerance of integration result, used only for adaptive integration. If set to None, Default value of 1e-5 is used

epsrel: float value or None

relative tolerance of integration result, used only for adaptive integration. If set to None, Default value of 0 is used

maxiter: positive integer value or None

maximum number of iterations of adaptive integration. If set to None or zero adaptive integration is not used.

numstd: integer

number of standard deviation points, used to calculate integration limits

Returns:

object of type functor_obj

escape.core.average.average_schulz(funf, sigma, x, mean, int numpoints=7, epsabs=None, epsrel=None, maxiter=None, int numstd=5)

Returns functor which calculates an average value of a functor or a parameter F(x) with Schulz distribution function.

Parameters:
funf: functor_obj with variable or parameter ‘x’

averaged functor

sigma: functor_obj with variable ‘x_0’, parameter or numeric

parameter of distribution function

x: variable or independent parameter

integration variable

mean: variable or independent parameter

mean value of distribution function

numpoints - integer

number of points of Gauss-Kronrod quadratures method. Supported values are [7, 15, 21, 31, 51, 61]

epsabs: float value or None

absolute tolerance of integration result, used only for adaptive integration. If set to None, Default value of 1e-5 is used

epsrel: float value or None

relative tolerance of integration result, used only for adaptive integration. If set to None, Default value of 0 is used

maxiter: positive integer value or None

maximum number of iterations of adaptive integration. If set to None or zero adaptive integration is not used.

numstd: integer

number of standard deviation points, used to calculate integration limits

Returns:

object of type functor_obj

escape.core.average.average_lognorm(funf, sigma, x, mean, int numpoints=7, epsabs=None, epsrel=None, maxiter=None, int numstd=5)

Returns functor which calculates an average value of a functor or a parameter F(x) with Lognorm distribution function.

Parameters:
funf: functor_obj with variable or parameter ‘x’

averaged functor

sigma: functor_obj with variable ‘x_0’, parameter or numeric

parameter of distribution function

x: variable or independent parameter

integration variable

mean: variable or independent parameter

mean value of distribution function

numpoints - integer

number of points of Gauss-Kronrod quadratures method. Supported values are [7, 15, 21, 31, 51, 61]

epsabs: float value or None

absolute tolerance of integration result, used only for adaptive integration. If set to None, Default value of 1e-5 is used

epsrel: float value or None

relative tolerance of integration result, used only for adaptive integration. If set to None, Default value of 0 is used

maxiter: positive integer value or None

maximum number of iterations of adaptive integration. If set to None or zero adaptive integration is not used.

numstd: integer

number of standard deviation points, used to calculate integration limits

Returns:

object of type functor_obj

escape.core.average.average_normal(funf, fwhm, x, mean, int numpoints=7, epsabs=None, epsrel=None, maxiter=None, int numstd=5)

Returns functor which calculates an average value of a functor or a parameter F(x) with normal distribution function.

Parameters:
funf: functor_obj with variable or parameter ‘x’

averaged functor

fwhm: functor_obj with variable ‘x_0’, parameter or numeric

parameter of distribution function

x: variable or independent parameter

integration variable

mean: variable or independent parameter

mean value of distribution function

numpoints - integer

number of points of Gauss-Kronrod quadratures method. Supported values are [7, 15, 21, 31, 51, 61]

epsabs: float value or None

absolute tolerance of integration result, used only for adaptive integration. If set to None, Default value of 1e-5 is used

epsrel: float value or None

relative tolerance of integration result, used only for adaptive integration. If set to None, Default value of 0 is used

maxiter: positive integer value or None

maximum number of iterations of adaptive integration. If set to None or zero adaptive integration is not used.

numstd: integer

number of standard deviation points, used to calculate integration limits

Returns:

object of type functor_obj

escape.core.average.average_uniform(funf, fwhm, x, mean, int numpoints=7, epsabs=None, epsrel=None, maxiter=None)

Returns functor which calculates an average value of a functor or a parameter F(x) with uniform distribution function.

Parameters:
funf: functor_obj with variable or parameter ‘x’

averaged functor

fwhm: functor_obj with variable ‘x_0’, parameter or numeric

parameter of distribution function

x: variable or independent parameter

integration variable

mean: variable or independent parameter

mean value of distribution function

numpoints - integer

number of points of Gauss-Kronrod quadratures method. Supported values are [7, 15, 21, 31, 51, 61]

epsabs: float value or None

absolute tolerance of integration result, used only for adaptive integration. If set to None, Default value of 1e-5 is used

epsrel: float value or None

relative tolerance of integration result, used only for adaptive integration. If set to None, Default value of 0 is used

maxiter: positive integer value or None

maximum number of iterations of adaptive integration. If set to None or zero adaptive integration is not used.

Returns:

object of type functor_obj

escape.core.average.average_triangular(funf, fwhm, x, mean, int numpoints=7, epsabs=None, epsrel=None, maxiter=None)

Returns functor which calculates an average value of a functor or a parameter F(x) with triangular distribution function.

Parameters:
funf: functor_obj with variable or parameter ‘x’

averaged functor

fwhm: functor_obj with variable ‘x_0’, parameter or numeric

parameter of distribution function

x: variable or independent parameter

integration variable

mean: variable or independent parameter

mean value of distribution function

numpoints - integer

number of points of Gauss-Kronrod quadratures method. Supported values are [7, 15, 21, 31, 51, 61]

epsabs: float value or None

absolute tolerance of integration result, used only for adaptive integration. If set to None, Default value of 1e-5 is used

epsrel: float value or None

relative tolerance of integration result, used only for adaptive integration. If set to None, Default value of 0 is used

maxiter: positive integer value or None

maximum number of iterations of adaptive integration. If set to None or zero adaptive integration is not used.

Returns:

object of type functor_obj