Implement differential and jacobian for Bezier curve integrals

[mikeingold]

Completed

• Merge derivative function into jacobian
• Use differential inside Bezier curve integral methods
• Add a new @testitem section for BezierCurve with analytic solution
• Add jacobian to the Documenter site API page

[JoshuaLampert]

I was just thinking: Could we rename derivative to jacobian, i.e. add a method to jacobian, such that we can reuse differential within the Bezier specialization instead of needing norm(derivative(...))? Then, of course, the new jacobian method (which is now derivative) would also get ts instead of t (where we would obtain t by t = only(ts)) and would need to return a one-element vector.

[mikeingold]

Didn't see you were making edits and just pushed a couple of commits. I have to step away but will check back in a bit to try to sort it out.

[JoshuaLampert]

Oh, I'm sorry. I didn't want to disturb your development 😬

[mikeingold]

No worries! I'm glad to have the help, just got distracted over in VS Code and was surprised to see help had arrived.

[mikeingold]

I just added a @testitem section with new tests that have an analytic solution. I think the core issue we see with test results being non-exact is that these Bezier curves are merely splined/interpolated approximations of the ideal curves. Depending on how the error tolerances stack up, I may need to just lax the rtol or atol a little.

[mikeingold]

I was just thinking: Could we rename derivative to jacobian, i.e. add a method to jacobian, such that we can reuse differential within the Bezier specialization instead of needing norm(derivative(...))? Then, of course, the new jacobian method (which is now derivative) would also get ts instead of t (where we would obtain t by t = only(ts)) and would need to return a one-element vector.

This is a really good idea. I think part of the trouble I had conceptually with extending (partial) derivative was in trying to generalize it past 1D geometries, i.e. what does the API look like to request the partial derivative w.r.t. the N'th parametric coordinate? Whereas for the 1D case you can just ignore that bit and return a simple Vec.

In my mind, then, we've got

jacobian(geometry::Meshes.Geometry, ts)  # finite-diff fallback
jacobian(curve::Meshes.BezierCurve, ts)  # analytic solution from today's derivative
# etc (as implemented)

and can interface them the same in all integral functions.

[mikeingold]

Pending this latest commit passing CI, this should be good to go.

[codecov]

Codecov Report

Attention: Patch coverage is 95.45455% with 1 line in your changes missing coverage. Please review.

Project coverage is 99.25%. Comparing base (d784136) to head (7d98fd2).
Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/differentiation.jl	92.30%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #92      +/-   ##
==========================================
+ Coverage   90.50%   99.25%   +8.75%     
==========================================
  Files          16       17       +1     
  Lines         316      269      -47     
==========================================
- Hits          286      267      -19     
+ Misses         30        2      -28     

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

[JoshuaLampert]

Looks good! Thanks @mikeingold!