v0.14-DEV: Remove derivative and unitdirection from exports

[mikeingold]

Completed

• Removed derivative and unitdirection from exports. These functions were developed early on when the direction of this package wasn't fully clear, and only BezierCurve-specific methods were added. In the long-term, I'd like to implement a more robust system for calculating derivatives and Jacobians, ideally using automatic differentiation. I'm removing these from the public API to facilitate future experimentation but won't remove them from the package entirely.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.50%. Comparing base (d27fa22) to head (9c2cd91).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #88   +/-   ##
=======================================
  Coverage   90.50%   90.50%           
=======================================
  Files          16       16           
  Lines         316      316           
=======================================
  Hits          286      286           
  Misses         30       30           

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

[JoshuaLampert]

Why is jacobian still exported?

[mikeingold]

Why is jacobian still exported?

The derivative and unitdirection (unit vector in same direction as derivative) methods are only defined for Bézier curves and seem mostly like a half-baked idea that we’re never fully implemented. I think my plan was to define these methods for all geometries, but it became obvious to me that plan would be fragile to any upstream changes in how geometries are parameterized. Ideally we could use AD as a general solution for partial derivatives of all geometry types, but I’ve had no luck yet in getting that working out-of-the-box despite some enthusiastic declarations upstream.

For now, I wound up just implementing an inelegant but reasonably effective finite difference approximation within jacobian. I was also going to drop jacobian but decided that it was at least usable for different geometry types, interesting enough that people might be interested in using it directly, and had a reasonably-stable API. There’s definitely room for improvement, but I figured this one could stick around.

[JoshuaLampert]

Ok, thanks for the explanation. If you think jacobian is reasonably stable and could be useful in its own, I'm fine exporting it (although I think it's a bit tangential to the goal of the package).