API Reference

Module documentation

DECUHR.DECUHR — Module

DECUHR

Pure-Julia port of the DECUHR algorithm (Espelid & Genz, 1994) for automatic integration of functions with vertex singularities over hyper-rectangular regions.

Exposed as a pluggable algorithm for the SciML Integrals.jl ecosystem through the SciMLBase.AbstractIntegralAlgorithm interface.

Quick start

using Integrals, DECUHR

# ∫∫₀¹ (x·y)^{-0.5} dx dy = π²/4
f = (u, p) -> (u[1]*u[2])^(-0.5)
prob = IntegralProblem(f, (zeros(2), ones(2)))
sol  = solve(prob, DecuhrAlgorithm(singul=2, alpha=-0.5); abstol=1e-8)

References

T.O. Espelid and A. Genz, DECUHR: An Algorithm for Automatic Integration of Singular Functions over a Hyperrectangular Region, Numerical Algorithms 8 (1994), pp. 201-220.
T.O. Espelid, On integrating Vertex Singularities using Extrapolation, BIT 34 (1994), pp. 62-79.

License

This package is released under the MIT License (LICENSE). As a port and modification of the Fortran 77 DECUHR routines, it additionally carries the upstream copyright notice of Espelid & Genz, reproduced verbatim in NOTICE. Both files MUST be shipped with every copy and every derivative work.

Algorithm type

DECUHR.DecuhrAlgorithm — Type

DecuhrAlgorithm(; key=0, singul=1, alpha=-2.0, logf=0,
                  wrksub=50000, emax=20, minpts=0)

DECUHR adaptive integration algorithm for functions with vertex singularities.

Keyword arguments

Argument	Default	Description
`key`	`0`	Rule selector: 0=auto, 1=2D deg-13 (65 pts), 2=3D deg-11 (127 pts), 3=deg-9 (nD), 4=deg-7 (nD)
`singul`	`1`	Dimension of the singularity: the vertex `(a[1],…,a[singul])` is singular
`alpha`	`-2.0`	Exponent of the homogeneous singularity. Auto-estimated when `alpha ≤ -singul`
`logf`	`0`	`1` if a logarithmic factor is present; `0` otherwise (auto-detected when `alpha ≤ -singul`)
`wrksub`	`50000`	Maximum number of stored subregions
`emax`	`20`	Maximum number of Richardson extrapolation steps
`minpts`	`0`	Minimum number of integrand evaluations

Notes

The singularity must be located at the lower-left vertex a[1:singul] of the integration domain. Shift the domain if necessary.
alpha must satisfy alpha > -singul. Setting alpha ≤ -singul (the default) triggers automatic estimation via DECALP.
For regular (non-singular) integrands set singul=1 and leave alpha at its default; the algorithm degrades gracefully to ordinary adaptive Gauss.

Return codes

`sol.retcode`	Meaning
`ReturnCode.Success`	All error estimates meet the requested tolerances
`ReturnCode.MaxIters`	Budget (`maxiters`) exhausted before convergence
`ReturnCode.Failure`	Invalid input parameters (see `sol.stats`)

Interpreting the result and MaxIters

DECUHR's error estimator is deliberately conservative (it inflates the pure extrapolation error by a heuristic factor, exactly as in the original Fortran DEXTHR). As a consequence a returned retcode = MaxIters does not mean the result is wrong: the value in sol.u is frequently accurate to far better than the requested tolerance even when the estimated error (sol.resid) has not dropped below it. When this happens, either raise maxiters/wrksub to let the estimate catch up, or simply trust sol.u and inspect sol.resid.

sol.stats exposes diagnostics:

Field	Meaning
`sol.stats.numevals`	Number of integrand evaluations performed
`sol.stats.ifail`	Raw DECUHR `IFAIL` code (0 = success, 1 = budget hit, …)

Automatic differentiation

solve is differentiable through ForwardDiff with respect to integrand parameters, including when alpha is auto-estimated: the exponent is estimated on the primal integrand (it is a structural property of the singularity) and the integration is then carried out in the dual number type.

Integrals.jl interface

DecuhrAlgorithm integrates with the standard SciML solve / init / solve! workflow. No additional API is needed beyond what Integrals.jl provides.

using Integrals, DECUHR

prob = IntegralProblem(f, (lb, ub))
sol  = solve(prob, DecuhrAlgorithm(; kwargs...);
             abstol=1e-8, reltol=1e-6, maxiters=100_000)

Keyword arguments to `solve`

Keyword	Default	Description
`abstol`	`1e-8`	Absolute error tolerance
`reltol`	`1e-6`	Relative error tolerance
`maxiters`	`100_000`	Maximum number of integrand evaluations

Solution fields

Field	Type	Description
`sol.u`	scalar or `Vector`	Integral estimate
`sol.resid`	scalar or `Vector`	Absolute error estimate
`sol.retcode`	`ReturnCode`	`Success`, `MaxIters`, or `Failure`

Usage examples

See the dedicated Examples page for complete, executable examples covering: singular integrands, vector-valued integrands, parameterised problems, automatic differentiation with ForwardDiff, and budget-limit behaviour.

Internal driver (advanced)

DECUHR._decuhr_driver — Function

_decuhr_driver(ndim, numfun, a, b, minpts, maxpts, funsub,
               singul, alpha_in, logf_in, epsabs, epsrel,
               key, wrksub, emax)

Low-level driver. Validates parameters, optionally estimates alpha, then calls _adaptive_integrate!. Returns (result, abserr, neval, ifail).

Note

_decuhr_driver is an internal function exposed for testing and debugging. Prefer the standard solve interface for everyday use.