Averaging functor or parameter¶

The escape.core.average module provides numerical integration techniques to compute moving averages (in the statistical sense) of functors or parameters.

The module provides:

A general average() function that can compute moving averages using any user-defined distribution function
Specialized averaging methods for common distribution functions defined in escape.core.distribution: - average_normal() - Normal/Gaussian distribution - average_gamma() - Gamma distribution - average_schulz() - Schulz distribution - average_lognorm() - Log-normal distribution - average_uniform() - Uniform distribution - average_triangular() - Triangular distribution

The averaging is performed using Gauss-Kronrod quadrature with adaptive error control.

Examples¶

Average of x over a Gaussian distribution:

Compute \(\int_{-\infty}^{\infty} x G(x, x_0) dx = x_0\) where \(G(x, x_0)\) is a Gaussian:

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

Average of x*p over a Gaussian distribution in p:

Compute \(\int_{-\infty}^{\infty} xp G(p, p_0) dp = xp_0\):

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

Average of p over a Gaussian distribution:

Compute \(\int_{-\infty}^{\infty} p G(p, p_0) dp = p_0\):

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

Definite integral over a Gaussian distribution:

Compute \(\int_x^y p G(p, p_0) dp = I(x, y)\):

>>> x, y = esc.var(("x", "y"))
>>> p = esc.par("p", 1)
>>> p0 = esc.par("p0", 1.2)
>>> sigma = 1.0
>>> G = 1/(np.sqrt(2*np.pi)*sigma)*esc.exp(-(p-p0)**2/(2*sigma**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*sigma, p0.value+5*sigma)  # I = p0
1.1999993148713521

The same result can be achieved more concisely using the specialized normal distribution helper:

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

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

Returns functor which calculates a moving average (in statistics terms) of a functor or parameter in the following form \(F(mean)=\int_a^b f(t)G(t, mean)dt\), where \(mean\) is the output variable or parameter the result depends on, \(x\) is the integration variable, \(G(t, mean)\) is the distribution function, and \(t\) is the integration variable.

Parameters:

funf: functor_obj with variable or parameter ‘x’

averaged functor

fung: functor_obj with variable or parameter

distribution functor

x: variable or independent parameter

integration variable

mean: variable or independent parameter

output variable (the distribution center)

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: