add eval_segbuf and quadgk_segbuf options

[stevengj]

This adds a new keyword eval_segbufs, which allows you to specify the initial integrand evaluation intervals via an array of Segments, e.g. the segbuf cache from a previous call to quadgk.

If you also pass maxevals=0, this allows you to exactly re-use the quadrature points and weights from a previous quadgk call, even for a different integrand. This is useful for automatic differentiation as discussed in EnzymeAD/Enzyme.jl#1599.

Also adds a new function quadgk_segbuf(...), which is identical to quadgk(...) but returns a tuple (I, E, segbuf) with an additional segbuf output: the array of integration segments used for the quadrature. (This saves you from having to call alloc_segbuf, which required you to know the return value of the integrand and so is painful to use in contexts where the integrand is an arbitrary function.)

Another benefit of this API is that it will allow us to support integration over an array of points (rather than an argument list … arrays can be splatted, but this is problematic for large arrays) or even an array of tuples $(a,b)$ representing line segments (which could even be disjoint), both of which can be efficiently converted into a Vector{Segment{T,Nothing,Nothing}} for passing via eval_segbuf.

To do:

• Tests
• API supporting array of points / segments

Not sure if we need tutorial examples? The new functionality is documented in the docstrings, but the cases where it is useful are pretty technical.

[codecov]

Codecov Report

Attention: Patch coverage is 98.26087% with 2 lines in your changes missing coverage. Please review.

Project coverage is 98.53%. Comparing base (a86aaf0) to head (f9c75aa).

Files	Patch %	Lines
src/api.jl	95.55%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #108      +/-   ##
==========================================
+ Coverage   98.03%   98.53%   +0.50%     
==========================================
  Files           6        7       +1     
  Lines         610      682      +72     
==========================================
+ Hits          598      672      +74     
+ Misses         12       10       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.