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, name: str = 'Convolution', notes: str = '') → 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()). name: Short label stored on the built convolution object notes: Optional longer description stored on the built convolution object

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, name: str = 'Convolution', notes: str = '') → 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) name: Short label stored on the built integral object notes: Optional longer description stored on the built integral object
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, name: str = 'Multivariate integral', notes: str = '') → 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.

name: Short label stored on the built integral object notes: Optional longer description stored on the built integral object

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.