Skip to content

feat: add analytical derivative to all 1D shapes#92

Open
lpatiny wants to merge 2 commits into
mainfrom
add-shape-derivatives
Open

feat: add analytical derivative to all 1D shapes#92
lpatiny wants to merge 2 commits into
mainfrom
add-shape-derivatives

Conversation

@lpatiny

@lpatiny lpatiny commented Jun 19, 2026

Copy link
Copy Markdown
Member

What

Adds an analytical derivative(x) to every Shape1D class plus standalone <shape>Derivative(...) functions, so consumers can build an exact Jacobian instead of approximating it with finite differences.

  • New required Shape1DClass.derivative(x) returning { fct, dx, parameters }, where parameters are the partials w.r.t. each shape parameter in getParameters() order. Exposed via the new exported Shape1DDerivative type.
  • Standalone functions next to each fct: gaussianDerivative, lorentzianDerivative, pseudoVoigtDerivative, lorentzianDispersiveDerivative, generalizedLorentzianDerivative, pseudoVoigtTCHDerivative.
  • pseudoVoigtDerivative and pseudoVoigtTCHDerivative inline their component math so the hot path allocates a single object (instead of 3 / 2).

Why

ml-spectra-fitting's optimize() can pass these as an analytical jacobianFunction to Levenberg–Marquardt. Measured end-to-end speedup vs the current finite-difference behavior: ~4× (mixed shapes, 42 params) to ~5.8× (all pseudoVoigt, 48 params), same iteration count and final error.

Tests

Each derivative is validated against central finite differences, and each class's derivative() is checked to return parameters in getParameters() order. npm test passes (108 tests, lint, types, prettier).

Note: requires a release of ml-levenberg-marquardt with jacobianFunction support for the downstream analytical-Jacobian path to take effect.

Every Shape1D class now implements a required `derivative(x)` method
returning the value `fct`, the partial derivative with respect to `x`,
and the partial derivatives with respect to each shape parameter (in
`getParameters()` order), exposed via the new `Shape1DDerivative` type.

Standalone `<shape>Derivative(...)` functions are added next to each
`fct` (gaussian, lorentzian, pseudoVoigt, lorentzianDispersive,
generalizedLorentzian, pseudoVoigtTCH). The pseudoVoigt and
pseudoVoigtTCH derivatives inline their component math so the hot path
allocates a single object. Each derivative is validated against central
finite differences.

This lets consumers (e.g. ml-spectra-fitting curve fitting) build an
analytical Jacobian instead of approximating it numerically.

Assisted-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@codecov

codecov Bot commented Jun 19, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.18%. Comparing base (0ce4bd1) to head (b96b738).

Additional details and impacted files
@@            Coverage Diff             @@
##             main      #92      +/-   ##
==========================================
+ Coverage   91.88%   93.18%   +1.29%     
==========================================
  Files          23       23              
  Lines         813      968     +155     
  Branches      194      206      +12     
==========================================
+ Hits          747      902     +155     
  Misses         65       65              
  Partials        1        1              

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

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@lpatiny lpatiny requested a review from jobo322 June 19, 2026 18:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant