Problem definitions

The design of AutoBZCore.jl is heavily influenced by SciML packages and uses the CommonSolve.jl interface. Eventually, this package may contribute to Integrals.jl.

Problem interface

AutoBZCore.jl replicates the Integrals.jl interface, using an IntegralProblem type to setup an integral from an integrand, a domain, and parameters.

using AutoBZCore

f = (x,p) -> sin(p*x)
dom = (0, 1)
p = 0.3
prob = IntegralProblem(f, dom, p)
IntegralProblem{IntegralFunction{Main.var"#1#2", Nothing}, Tuple{Int64, Int64}, Float64, @NamedTuple{}}(IntegralFunction{Main.var"#1#2", Nothing}(Main.var"#1#2"(), nothing), (0, 1), 0.3, NamedTuple())
AutoBZCore.IntegralProblem — Type
IntegralProblem(f, domain, [p=NullParameters]; kwargs...)

Arguments

  • f::AbstractIntegralFunction: The function to integrate
  • domain: The domain to integrate over, e.g. (lb, ub)
  • p: Parameters to pass to the integrand

Keywords

Additional keywords are passed directly to the solver

solve

To solve an integral problem, pick an algorithm and call solve

alg = QuadGKJL()
solve(prob, alg)
AutoBZCore.IntegralSolution{Float64, @NamedTuple{error::Float64}}(0.14887836958131329, AutoBZCore.Success, (error = 2.7755575615628914e-17,))
CommonSolve.solve — Function
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.

solve(::AutoBZProblem, ::AutoBZAlgorithm; kws...)::IntegralSolution
solve(::DOSProblem, ::DOSAlgorithm; kws...)::DOSSolution

init and solve!

To solve many problems with the same integrand but different domains or parameters, use init to allocate a solver and solve! to get the solution

solver = init(prob, alg)
solve!(solver).value
0.14887836958131329

To solve again, update the parameters of the solver in place and solve! again

# solve again at a new parameter
solver.p = 0.4
solve!(solver).value
0.1973475149927873
CommonSolve.init — Function
init(::IntegralProblem, ::IntegralAlgorithm; kws...)::IntegralSolver

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.

init(::DOSProblem, ::DOSAlgorithm; kwargs...)::DOSCache

Create a cache of the data used by an algorithm to solve the given problem.

CommonSolve.solve! — Function
solve!(::IntegralSolver)::IntegralSolution

Compute the solution to an IntegralProblem constructed from init.

solve!(::IntegralCache)::IntegralSolution

Compute the solution to an IntegralProblem constructed from init.

solve!(::DOSCache)::DOSSolution

Compute the solution of a problem from the initialized cache

Additional problems

AutoBZCore.AutoBZProblem — Type
AutoBZProblem([rep], f, bz, [p]; kwargs...)

Construct a BZ integration problem.

Arguments

  • rep::AbstractSymRep: The symmetry representation of f (default: UnknownRep())
  • f::AbstractIntegralFunction: The integrand
  • bz::SymmetricBZ: The Brillouin zone to integrate over
  • p: parameters for the integrand (default: NullParameters())

Keywords

Additional keywords are passed directly to the solver

AutoBZCore.DOSProblem — Type
DOSProblem(H, domain, [p=NullParameters()])

Define a problem for the density of states of a Hermitian or self-adjoint operator depending on a parameter, H(p), on a given domain in its spectrum. The mathematical definition we use is

\[D(E) = \sum_{k \in p} \sum_{\lambda \in \text{spectrum}(H(k))} \delta(E - \lambda)\]

where $E \in \text{domain}$ and $\delta$ is the Dirac Delta distribution.

Arguments

  • H: a linear operator depending on a parameter, H(p), that is finite dimensional (e.g: tight binding model) or infinite dimensional (e.g. DFT data)
  • domain: a set in the spectrum for which an approximation of the density-of-states is desired. Can be a single point, in which case the solution will return the estimated density of states at that eigenvalue, or an interval, in which case the solution will return a function approximation to the density of states on that interval in the spectrum that should be understood as a distribution or measure.
  • p: optional parameters on which H depends for which the density of states should sum over. Can be discrete (e.g. for H a Hamiltonian with spin degrees of freedom) or continuous (e.g. for H a Hamiltonian parameterized by crystal momentum).