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.

Quickstart

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

Reference

AutoBZCore.IntegralProblemType
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.

AutoBZCore.solveFunction
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).

Keywords

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

AutoBZCore.initFunction
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

AutoBZCore.IntegralSolverType
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.

AutoBZCore.MixedParametersType
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 == kwargs.name.

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

AutoBZCore.paramzipFunction
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 == kwargs.name[i].

AutoBZCore.paramproductFunction
paramproduct(args...; kwargs...)

Behaves similarly to product(args..., kwargs...) with MixedParameters return values so that paramzip(args...; kwargs...)[i1, ...,ij, il, ...in] == 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.

AutoBZCore.batchsolveFunction
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.