Averaging functor or parameter

The escape.core.average module provides numerical integration techniques to compute averages of functors or parameters.

The module provides:

1. A general average() function that can compute averages using any user-defined distribution function

2. 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

1. 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
   

2. 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
   

3. 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
   

4. 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, x0, maxiter=10)
>>> I(1.2)
1.1999993135018503

escape.core.average.average(funf: Union[functor_obj, parameter_obj], fung: Union[functor_obj, parameter_obj], x: Union[variable_obj, parameter_obj], mean: Union[variable_obj, parameter_obj], a: Union[functor_obj, parameter_obj, float, int, str], b: Union[functor_obj, parameter_obj, float, int, str], numpoints: int = 7, epsabs: Optional[float] = None, epsrel: Optional[float] = None, maxiter: Optional[int] = None) → Union[functor_obj, parameter_obj]

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: Union['functor_obj', 'variable_obj', 'parameter_obj'], sigma: Union['functor_obj', 'parameter_obj', int, float, str], x: Union['variable_obj', 'parameter_obj'], mean: Union['variable_obj', 'parameter_obj'], numpoints: int = 7, epsabs: Optional[float] = None, epsrel: Optional[float] = None, maxiter: Optional[int] = None, numstd: int = 5) → Union[functor_obj, parameter_obj]

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: Union[functor_obj, parameter_obj], sigma: Union[functor_obj, parameter_obj], x: Union[variable_obj, parameter_obj], mean: Union[variable_obj, parameter_obj], numpoints: int = 7, epsabs: Optional[float] = None, epsrel: Optional[float] = None, maxiter: Optional[int] = None, numstd: int = 5) → Union[functor_obj, parameter_obj]

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: Union[functor_obj, variable_obj, parameter_obj], sigma: Union[functor_obj, parameter_obj, int, float, str], x: Union[variable_obj, parameter_obj], mean: Union[variable_obj, parameter_obj], numpoints: int = 7, epsabs: Optional[float] = None, epsrel: Optional[float] = None, maxiter: Optional[int] = None, numstd: int = 5) → Union[functor_obj, parameter_obj]

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: Union[functor_obj, variable_obj, parameter_obj], fwhm: Union[functor_obj, parameter_obj, int, float, str], x: Union[variable_obj, parameter_obj], mean: Union[variable_obj, parameter_obj], numpoints: int = 7, epsabs: Optional[float] = None, epsrel: Optional[float] = None, maxiter: Optional[int] = None, numstd: int = 5) → Union[functor_obj, parameter_obj]

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: Union[functor_obj, variable_obj, parameter_obj], fwhm: Union[functor_obj, parameter_obj, int, float, str], x: Union[variable_obj, parameter_obj], mean: Union[variable_obj, parameter_obj], numpoints: int = 7, epsabs: Optional[float] = None, epsrel: Optional[float] = None, maxiter: Optional[int] = None) → Union[functor_obj, parameter_obj]

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: Union[functor_obj, variable_obj, parameter_obj], fwhm: Union[functor_obj, parameter_obj, int, float, str], x: Union[variable_obj, parameter_obj], mean: Union[variable_obj, parameter_obj], numpoints: int = 7, epsabs: Optional[float] = None, epsrel: Optional[float] = None, maxiter: Optional[int] = None) → Union[functor_obj, parameter_obj]

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