Problem definitions

The design of AutoBZCore.jl is heavily influenced by the SciML package Integrals.jl and may eventually become implemented in it.

SciML interface

AutoBZCore.jl replicates the Integrals.jl interface, but does not export it in order to avoid name conflicts with other SciML packages.


using AutoBZCore: IntegralProblem, init, solve!

prob = IntegralProblem((x,p) -> sin(p*x), 0, 1, 0.3)
cache = init(prob, QuadGKJL())
solve!(cache)   # 0.14887836958131329

# solve again at a new parameter
cache.p = 0.4
solve!(cache)   # 0.1973475149927873


IntegralProblem(f, domain, [p=NullParameters])
IntegralProblem(f, a::T, b::T, [p=NullParameters]) where {T}

Collects the data need to define an integral of a function f(x, p) over a domain containing the points, x, and set with parameters p (default: NullParameters). If the domain is an interval or hypercube, it can also be specified by its endpoints a, b, and it gets converted to a PuncturedInterval or HyperCube.

solve(::IntegralProblem, ::IntegralAlgorithm; kws...)::IntegralSolution

Compute the solution to the given IntegralProblem using the given IntegralAlgorithm for the given keyword arguments to the solver (i.e. abstol, reltol, or maxiters).


  • abstol: an absolute error tolerance to get the solution to a specified number of absolute digits, e.g. 1e-3 requests accuracy to 3 decimal places. Note that this number must have the same units as the integral. (default: nothing)
  • reltol: a relative error tolerance equivalent to specifying a number of significant digits of accuracy, e.g. 1e-4 requests accuracy to roughly 4 significant digits. (default: nothing)
  • maxiters: a soft upper limit on the number of integrand evaluations (default: typemax(Int))

Solvers typically converge only to the weakest error condition. For example, a relative tolerance can be used in combination with a smaller-than necessary absolute tolerance so that the solution is resolved up to the requested significant digits, unless the integral is smaller than the absolute tolerance.

init(::IntegralProblem, ::IntegralAlgorithm; kws...)::IntegralCache

Construct a cache for an IntegralProblem, IntegralAlgorithm, and the keyword arguments to the solver (i.e. abstol, reltol, or maxiters) that can be reused for solving the problem for multiple different parameters of the same type.

Functor interface

As shown in the quickstart of the AutoBZCore page, AutoBZCore.jl also defines a functor interface to solving integrals

IntegralSolver(f, dom, alg; [abstol, reltol, maxiters])
IntegralSolver(f, lb, ub, alg::AbstractIntegralAlgorithm; [abstol, reltol, maxiters])

Returns a functor, fun, that accepts input parameters p and solves the corresponding integral fun(p) -> solve(IntegralProblem(f, lb, ub, p), alg).u. See solve for details on the keywords.

If f is a ParameterIntegrand or FourierIntegrand, then the functor interface is modified to accept parameters as function arguments, and the following is done: fun(args...; kwargs...) -> solve(IntegralProblem(f, lb, ub, merge(f.p, MixedParameters(args...; kwargs...))), alg).u where f.p are the preset parameters of f.

The functor interface is also extended by ParameterIntegrand and FourierIntegrand to allow a more flexible interface for passing (partial) positional and keyword arguments to user-defined integrands.

MixedParameters(args::Tuple, kwargs::NamedTuple)
MixedParameters(args...; kwargs...)

A struct to store the arguments and keyword arguments to a function. Indicies access args, i.e. MixedParameters(args...; kwargs...)[i] == args[i] and properties access kwargs, i.e. MixedParameters(args...; kwargs...).name ==

Used internally to store partially complete collections of function arguments or parameters.

paramzip(args...; kwargs...)

Behaves similarly to zip(zip(args...), zip(kwargs...)) with MixedParameters return values so that paramzip(args...; kwargs...)[i][j] == args[j][i] and paramzip(args...; kwargs...)[i].name ==[i].

paramproduct(args...; kwargs...)

Behaves similarly to product(args..., kwargs...) with MixedParameters return values so that paramzip(args...; kwargs...)[i1, ...,ij, il,] == MixedParameters(args[begin][i1], ..., args[end][ij]; kwargs[begin][il], ..., kwargs[end][in])

Batched evaluation

The routine batchsolve allows multi-threaded evaluation of an IntegralSolver at many parameter points.

batchsolve(f::IntegralSolver, ps::AbstractArray, [T]; nthreads=Threads.nthreads())

Evaluate the IntegralSolver f at each of the parameters ps in parallel. Returns an array similar to ps containing the evaluated integrals I. This is a form of multithreaded broadcasting. Providing the return type f(eltype(ps))::T is optional, but will help in case inference of that type fails.