Mathematical functions and numerical integration¶

The escape.core.math module provides mathematical functions and numerical integration capabilities for working with functors, parameters, and variables.

Mathematical Functions¶

The module includes common mathematical functions that can operate on various input types (float, int, parameter_obj, functor_obj, cplx_functor_obj, or variable_obj):

Trigonometric: sin, cos, tan
Hyperbolic: sinh, cosh, tanh
Exponential and Logarithmic: exp, log, log10
Other: sqrt, abs, erf
Special Functions: tgamma, gamma_p, gamma_q, cyl_bessel_j

Each function returns an appropriate type (parameter_obj, functor_obj, or cplx_functor_obj) based on the input type.

Numerical Integration¶

The module provides numerical integration capabilities through the integral() function, which supports:

Definite integration with fixed or variable limits
Gauss-Kronrod quadrature with configurable points (7, 15, 21, 31, 51, or 61)
Adaptive integration with error control
Integration of both real and complex functions

Convolution-type quadrature uses the same options via convolution() (finite limits) and convolution_infinite() (whole real line), mirroring the type dispatch of integral().

Interpolation¶

Linear interpolation is available through the linterp() function, which creates piecewise linear interpolants from discrete data points.

Examples¶

Basic mathematical operations: >>> x = Variable(‘x’) >>> f = sin(x) # Creates a functor representing sin(x) >>> g = exp(x) # Creates a functor representing exp(x)

Integration: >>> result = integral(f, x, 0, 1) # Integrates sin(x) from 0 to 1

Oscillatory/Fourier integration: >>> I_cos = filon_cos(f, x, 0, 10, omega=1.0) # ∫_0^{10} f(x) cos(ωx) dx >>> Fw = fourier_cos(f, x, omega=1.0) # ∫_0^{∞} f(x) cos(ωx) dx

See Also¶

escape.core.functor : Core functor functionality escape.core.entities : Basic entity definitions

Returns a functor or parameter which computes an absolute value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj, cplx_functor_obj or variable
Returns:: parameter_obj or functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

escape.core.math.acos(obj: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: Returns a functor or parameter which computes an inverse cosine value.

escape.core.math.acosh(obj: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: Returns a functor or parameter which computes an inverse hyperbolic cosine value.

Returns a functor which computes the arg value.

Args:: obj: Input argument - can be functor_obj, cplx_functor_obj or variable
Returns:: functor_obj
Raises:: TypeError: If obj is not one of the supported types

escape.core.math.asin(obj: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: Returns a functor or parameter which computes an inverse sine value.

escape.core.math.asinh(obj: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: Returns a functor or parameter which computes an inverse hyperbolic sine value.

escape.core.math.atan(obj: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: Returns a functor or parameter which computes an inverse tangent value.

escape.core.math.atan2(obj1: float | int | parameter_obj | functor_obj | variable_obj, obj2: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: Returns a functor or parameter which computes atan2(y, x) for two arguments.

escape.core.math.atanh(obj: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: Returns a functor or parameter which computes an inverse hyperbolic tangent value.

escape.core.math.conj(obj: functor_obj | cplx_functor_obj | variable_obj) → cplx_functor_obj¶

Returns a functor which computes conjugate of obj.

Args:: obj: Input argument - can be functor_obj, cplx_functor_obj or variable
Returns:: cplx_functor_obj
Raises:: TypeError: If obj is not one of the supported types

escape.core.math.convolution(f, g, x, a, b, numpoints: int = 7, epsabs: float | None = None, epsrel: float | None = None, maxiter: int | None = None) → functor_obj | parameter_obj¶

Numerical convolution of two expressions over a finite interval.

Builds a functor or parameter that evaluates the convolution of f and g with respect to the integration variable x over [a, b], using the same Gauss–Kronrod / adaptive machinery as integral().

Args:

f, g: Integrands (functor_obj, variable_obj, or parameter-like for the: all-parameter specialization).

x: Convolution/integration variable (variable_obj or parameter_obj). a, b: Interval limits (numeric, parameter_obj, or functor-like, same

conventions as integral()).

numpoints: Quadrature size in {7, 15, 21, 31, 51, 61}. epsabs, epsrel, maxiter: Adaptive tolerances (defaults match integral()).

Returns:

functor_obj or parameter_obj depending on arguments.

escape.core.math.convolution_infinite(f, g, x, numpoints: int = 7, epsabs: float | None = None, epsrel: float | None = None, maxiter: int | None = None) → functor_obj | parameter_obj¶: Convolution of two expressions over (-∞, ∞) (same quadrature choices as convolution()).

Returns a functor or parameter which computes a cosine value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj, cplx_functor_obj or variable
Returns:: parameter_obj, functor_obj or cplx_functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

Returns a functor or parameter which computes a hyperbolic cosine value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj, cplx_functor_obj or variable
Returns:: parameter_obj, functor_obj or cplx_functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

Returns a functor or parameter which computes the cylindrical Bessel function of the first kind.

Args:: a: Order of the Bessel function - can be float, int, parameter_obj, functor_obj, variable_obj or str z: Input argument - can be float, int, parameter_obj, functor_obj, variable_obj or str
Returns:: parameter_obj or functor_obj depending on input type
Raises:: TypeError: If inputs are not of supported types

Returns a functor or parameter which computes an error function value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj or variable
Returns:: parameter_obj or functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

escape.core.math.erfc(obj: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: Returns a functor or parameter which computes a complementary error function value.

Returns a functor or parameter which computes an exponential function value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj, cplx_functor_obj or variable
Returns:: parameter_obj, functor_obj or cplx_functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

escape.core.math.filon_cos(fun: functor_obj, x: variable_obj, a: int | float | parameter_obj, b: int | float | parameter_obj, omega: int | float | parameter_obj, numpoints: int = 51, epsabs: float = 1e-05, maxiter: int = 200, name: str = 'Filon Cosine', notes: str = '') → functor_obj¶

Filon cosine integration of a functor over finite limits.

Computes ∫_a^b f(x) cos(ω x) dx using an adaptive Filon scheme.

escape.core.math.filon_sin(fun: functor_obj, x: variable_obj, a: int | float | parameter_obj, b: int | float | parameter_obj, omega: int | float | parameter_obj, numpoints: int = 51, epsabs: float = 1e-05, maxiter: int = 200, name: str = 'Filon Sine', notes: str = '') → functor_obj¶

Filon sine integration of a functor over finite limits.

Computes ∫_a^b f(x) sin(ω x) dx using an adaptive Filon scheme.

escape.core.math.fourier_cos(fun: functor_obj, x: variable_obj, omega: int | float | parameter_obj, numpoints: int = 51, epsabs: float = 1e-05, maxiter: int = 200, name: str = 'Fourier Cosine', notes: str = '') → functor_obj¶

Fourier cosine transform using Filon-type integration.

Computes ∫_0^{∞} f(x) cos(ω x) dx.

escape.core.math.fourier_sin(fun: functor_obj, x: variable_obj, omega: int | float | parameter_obj, numpoints: int = 51, epsabs: float = 1e-05, maxiter: int = 200, name: str = 'Fourier Sine', notes: str = '') → functor_obj¶

Fourier sine transform using Filon-type integration.

Computes ∫_0^{∞} f(x) sin(ω x) dx.

Returns a functor or parameter which computes the lower incomplete gamma function.

Args:: a: Parameter a - can be float, int, parameter_obj, functor_obj, variable_obj or str z: Input argument - can be float, int, parameter_obj, functor_obj, variable_obj or str normalized: If True, output is normalized to [0,1] range
Returns:: parameter_obj or functor_obj depending on input type
Raises:: TypeError: If inputs are not of supported types

Returns a functor or parameter which computes the upper incomplete gamma function.

Args:: a: Parameter a - can be float, int, parameter_obj, functor_obj, variable_obj or str z: Input argument - can be float, int, parameter_obj, functor_obj, variable_obj or str normalized: If True, output is normalized to [0,1] range
Returns:: parameter_obj or functor_obj depending on input type
Raises:: TypeError: If inputs are not of supported types

Returns a functor which computes imaginary part of obj.

Args:: obj: Input argument - can be functor_obj, cplx_functor_obj or variable
Returns:: functor_obj
Raises:: TypeError: If obj is not one of the supported types

Returns functor which computes a result of definite integral.

Computes the definite integral:

\[I = \int_a^b f(x)dx\]

where x is a variable or parameter.

Args:: fun: The function to integrate - functor_obj or parameter_obj with variable/parameter x x: Integration variable - variable_obj or parameter_obj a: Lower integration limit - parameter_obj, functor_obj, variable_obj or numeric value b: Upper integration limit - parameter_obj, functor_obj, variable_obj or numeric value numpoints: Number of points for Gauss-Kronrod quadrature (7, 15, 21, 31, 51, or 61) epsabs: Absolute error tolerance for adaptive integration (default 1e-5) epsrel: Relative error tolerance for adaptive integration (default 0) maxiter: Maximum iterations for adaptive integration (default None = no adaptive integration)
Returns:: functor_obj or parameter_obj depending on input types
Raises:: TypeError: If inputs have unsupported types ValueError: If numpoints is not a supported value

escape.core.math.integral_mv(fun, vars, a, b, numpoints: int = 7, epsabs: float | None = None, epsrel: float | None = None, max_subregions: int | None = None) → functor_obj¶

Multivariate integration over a hyperrectangular domain.

Computes the definite integral:

\[I = \int_{a_0}^{b_0} \cdots \int_{a_{N-1}}^{b_{N-1}} f(x_0, \ldots, x_{N-1}) \, dx_0 \cdots dx_{N-1}\]

Uses tensor-product Gauss-Kronrod quadrature. When max_subregions is None (or 0), a single fixed-point evaluation is performed. When max_subregions is a positive integer, adaptive subdivision is used.

Args:

fun: The function to integrate (functor_obj or variable_obj expression) vars: List of integration variables (variable_obj), length 2-4 a: List of lower limits (numeric or parameter_obj), same length as vars b: List of upper limits (numeric or parameter_obj), same length as vars numpoints: Number of GK quadrature points per dimension (7, 15, 21, 31, 51, or 61) epsabs: Absolute error tolerance (default 1e-5) epsrel: Relative error tolerance (default 0) max_subregions: Maximum number of adaptive subregions.

None or 0 for fixed-point (non-adaptive) evaluation, positive integer for adaptive subdivision.

Returns:

functor_obj representing the multivariate integral

Raises:

TypeError: If inputs have unsupported types ValueError: If numpoints is unsupported or dimension is out of range

Examples:

Fixed-point 2D integration:

x = esc.var('x')
y = esc.var('y')
f = x * y
I = esc.integral_mv(f, [x, y], [0, 0], [1, 1], numpoints=15)
print(I())  # ~0.25

Adaptive 2D integration:

I = esc.integral_mv(f, [x, y], [0, 0], [1, 1],
                    numpoints=7, epsabs=1e-8, max_subregions=100)

Added in version 0.10.0.

escape.core.math.j1_over_x(obj: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: J_1(x)/x (cylindrical Bessel), limit 1/2 at x=0. Real only.

escape.core.math.linterp(x: variable_obj | functor_obj, xp: np.ndarray, yp: np.ndarray) → functor_obj¶

One-dimensional linear interpolation functor.

Creates a piecewise linear interpolant from discrete data points (xp, yp), evaluated at values returned by x.

Args:: x: The points to interpolate at - functor_obj or variable_obj xp: Array of x-coordinates of data points, must be sorted ascending yp: Array of y-coordinates of data points
Returns:: functor_obj representing the interpolated function
Raises:: TypeError: If x has unsupported type

Added in version 0.9.1.

Returns a functor or parameter which computes a natural logarithm value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj or variable
Returns:: parameter_obj or functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

Returns a functor or parameter which computes a decimal logarithm value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj or variable
Returns:: parameter_obj or functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

escape.core.math.log2(obj: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: Returns a functor or parameter which computes a binary logarithm value.

Returns a functor or parameter which computes the largest value for two arguments.

Args:: obj1: Input argument 1 - can be float, int, parameter_obj, functor_obj or variable obj2: Input argument 2 - can be float, int, parameter_obj, functor_obj or variable
Returns:: parameter_obj or functor_obj depending on input types
Raises:: TypeError: If obj1 or obj2 are not one of the supported types

escape.core.math.mean(*objs)¶: Returns a parameter/functor computing the arithmetic mean of all arguments.

Returns a functor or parameter which computes the smallest value for two arguments.

Args:: obj1: Input argument 1 - can be float, int, parameter_obj, functor_obj or variable obj2: Input argument 2 - can be float, int, parameter_obj, functor_obj or variable
Returns:: parameter_obj or functor_obj depending on input types
Raises:: TypeError: If obj1 or obj2 are not one of the supported types

Returns a functor which computes the norm value.

Args:: obj: Input argument - can be functor_obj, cplx_functor_obj or variable
Returns:: functor_obj
Raises:: TypeError: If obj is not one of the supported types

Returns a functor or parameter which computes the value of base obj1 raised to the power obj2.

Args:: obj1: Base - can be float, int, parameter_obj, functor_obj or variable obj2: Exponent - can be float, int, parameter_obj, functor_obj or variable
Returns:: parameter_obj or functor_obj depending on input types
Raises:: TypeError: If obj1 or obj2 are not one of the supported types

escape.core.math.product(*objs)¶: Returns a parameter/functor computing the product of all arguments.

Returns a functor which computes real part of obj.

Args:: obj: Input argument - can be functor_obj, cplx_functor_obj or variable
Returns:: functor_obj
Raises:: TypeError: If obj is not one of the supported types

Returns a functor or parameter which computes a sine value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj, cplx_functor_obj or variable
Returns:: parameter_obj, functor_obj or cplx_functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

escape.core.math.sinc(obj: float | int | parameter_obj | functor_obj | variable_obj) → parameter_obj | functor_obj¶: sin(x)/x with limit 1 at x=0 (numerically stable). Real scalar / parameter / functor only.

Returns a functor or parameter which computes a hyperbolic sine value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj, cplx_functor_obj or variable
Returns:: parameter_obj, functor_obj or cplx_functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

Returns a functor or parameter which computes a square root value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj, cplx_functor_obj or variable
Returns:: parameter_obj, functor_obj or cplx_functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

escape.core.math.stddev(*objs)¶: Returns a parameter/functor computing the population standard deviation.

escape.core.math.sum(*objs)¶: Returns a parameter/functor computing the sum of all arguments.

Returns a functor or parameter which computes a tangent value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj, cplx_functor_obj or variable
Returns:: parameter_obj, functor_obj or cplx_functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

Returns a functor or parameter which computes a hyperbolic tangent value.

Args:: obj: Input argument - can be float, int, parameter_obj, functor_obj, cplx_functor_obj or variable
Returns:: parameter_obj, functor_obj or cplx_functor_obj depending on input type
Raises:: TypeError: If obj is not one of the supported types

Returns a functor or parameter which computes the true gamma function.

Args:: z: Input argument - can be float, int, parameter_obj, variable_obj, functor_obj or str
Returns:: parameter_obj or functor_obj depending on input type
Raises:: TypeError: If inputs are not of supported types

escape.core.math.tgamma_lower(a: float | int | parameter_obj | functor_obj | variable_obj | str, z: float | int | parameter_obj | functor_obj | variable_obj | str) → parameter_obj | functor_obj¶: Returns a functor or parameter computing the unnormalized lower incomplete gamma function.

escape.core.math.tgamma_upper(a: float | int | parameter_obj | functor_obj | variable_obj | str, z: float | int | parameter_obj | functor_obj | variable_obj | str) → parameter_obj | functor_obj¶: Returns a functor or parameter computing the unnormalized upper incomplete gamma function.

escape.core.math.variance(*objs)¶: Returns a parameter/functor computing the population variance of all arguments.