added documentation

CHANGELOG.md

@@ -16,11 +16,11 @@ to oldest and aligned to the 10 beta tags (`0.0.4` to `v0.0.13`).
   and cooling model readers (default remains disabled).
 - New feature: Added sanitisation for extrapolated values to avoid aphysical
   outputs (`NaN`, `inf`, and impossible negatives) in affected paths.
-- Behavior: Kept in-range interpolation and boundary behavior unchanged when
+- Behaviour: Kept in-range interpolation and boundary behaviour unchanged when
   extrapolation is disabled.
 - API change (breaking): Removed legacy fit inputs `mags`, `mag_errors`,
   `fluxes`, and `flux_errors`.
-- API change (breaking): Standardized `self.fitting_params` to only
+- API change (breaking): Standardised `self.fitting_params` to only
   `photometry`, `photometry_errors`, and `photometry_space`.
 - API change (breaking): Removed legacy output aliases `best_fit_mag` and
   `best_fit_flux`.
@@ -35,10 +35,11 @@ to oldest and aligned to the 10 beta tags (`0.0.4` to `v0.0.13`).
 - Tests: Added deterministic flux-vs-magnitude parity tests.
 - Tests: Added deterministic regression checks against `origin/main`.
 - Tests: Reduced runtime for the new parity/regression matrix.
-- Tests: Added extrapolation safety and boundary-behavior coverage for
+- Tests: Added extrapolation safety and boundary-behaviour coverage for
   atmosphere/cooling interpolators.
 - Examples: Updated example scripts for the new API/workflow expectations and
-  checked near-identical behavior against `v0.0.13` where deterministic.
+  checked near-identical behaviour against `v0.0.13` where deterministic.
+- Documentation: Added interpolation scheme explanation
 
 ## [v0.0.13] - 2026-01-14
 
@@ -91,9 +92,9 @@ to oldest and aligned to the 10 beta tags (`0.0.4` to `v0.0.13`).
 - Fix: Corrected fitting-mass bug.
 - Fix: Corrected independent-variable name comparison robustness.
 - Fix: Migrated from deprecated `interp2d` to RBF interpolation.
-- Fix: Standardized fitter method outputs to scalar floats.
+- Fix: Standardised fitter method outputs to scalar floats.
 - Documentation: Updated README and RTD content plus citation references.
-- Documentation: Added clarifications on uncertainty/error estimation behavior.
+- Documentation: Added clarifications on uncertainty/error estimation behaviour.
 
 ## [v0.0.7] - 2022-12-04
 
@@ -130,7 +131,7 @@ to oldest and aligned to the 10 beta tags (`0.0.4` to `v0.0.13`).
 
 - Compatibility: Adapted to SciPy 1.9 stricter data-type requirements.
 - Compatibility: Added SciPy-version handling for RegularGridInterpolator
-  behavior.
-- Fix: Corrected NaN-extinction behavior when reddening is not fitted.
+  behaviour.
+- Fix: Corrected NaN-extinction behaviour when reddening is not fitted.
 - Fix: Corrected K01 IMF normalization bug.
 - Fix: Corrected README/docs typos and fitter docstrings.

docs/source/background/interpolation_scheme.rst

@@ -0,0 +1,70 @@
+=================================
+Interpolation Scheme Diagnostics
+=================================
+
+The ``kernel`` argument used with ``extinction_convolved=False`` selects the
+radial-basis interpolation scheme for the tabulated reddening profile. The
+available ``linear``, ``cubic``, and ``quintic`` kernels are useful numerical
+approximations. They do not make pivot-wavelength extinction equivalent to
+filter-by-filter extinction convolution.
+
+Higher-order kernels need particular care. Cubic and quintic kernels introduce
+more curvature into the fitted surface than the linear kernel. Combined with a
+non-linear photometric fit, this can make a poor starting point converge to a
+different local minimum.
+
+Fixed Starting Point Diagnostic
+===============================
+
+The diagnostic below fitted 10,000 extinction-stratified GF21 DA candidates
+with a fixed initial point of ``(Teff, logg) = (10000 K, 8.0)``. Each panel
+compares a convolved-extinction fit with an interpolated-extinction fit using
+the named RBF kernel. The linear result follows the reference relation closely.
+The cubic result has a broader high-temperature branch and the quintic result
+has a pronounced low-temperature branch. Their reported Pearson correlations
+with the GF21 temperatures are 0.9416 and 0.5338, respectively, compared with
+0.9863 for the linear fit.
+
+.. figure:: ../_static/interpolation_rbf_fixed_start.png
+   :width: 100%
+   :alt: Fixed-start comparison of convolved and RBF-interpolated reddening fits.
+
+   Fixed-start RBF diagnostic. Cubic and quintic interpolated fits can select
+   erroneous solution branches when fitting starts far from the best solution.
+
+This diagnostic is a failure-mode check, not a measurement of a kernel-only
+effect. High-order RBF profile shape, sparse reddening-table sampling, and
+optimizer initialization can all contribute. It does show that a single,
+generic starting point is insufficient validation for cubic or quintic fits.
+
+Multiple Starting Points
+========================
+
+For each source, use several physically plausible starting points and retain
+the finite solution with the lowest :math:`\chi^2`. For example, the diagnostic
+used ``(10000 K, 8.0)``, ``(25000 K, 7.0)``, and ``(70000 K, 8.0)``. This is a
+deterministic multistart search, not posterior sampling.
+
+The 1,000-source diagnostic below applies that procedure. The selected
+solutions give closely matched temperature relations for the three kernels.
+This does not prove that interpolated extinction is equivalent to convolved
+extinction; it shows that the obvious incorrect local-minimum solutions were
+removed before comparing interpolation schemes.
+
+.. figure:: ../_static/interpolation_rbf_multistart.png
+   :width: 100%
+   :alt: Multistart comparison of convolved and RBF-interpolated reddening fits.
+
+   RBF diagnostic after choosing the lowest finite :math:`\chi^2` solution from
+   three starting points per source and kernel.
+
+Recommended Practice
+====================
+
+* Prefer ``extinction_convolved=True`` for science results. It evaluates
+  extinction through the model spectrum and passband.
+* Treat ``extinction_convolved=False`` as a pivot-wavelength approximation.
+* For cubic or quintic RBF kernels, evaluate multiple initial guesses and
+  inspect both fitted parameters and :math:`\chi^2` before accepting a result.
+
+

docs/source/index.rst

@@ -28,6 +28,7 @@ User Guide
    background/atmosphere
    background/cooling
    background/extrapolation
+   background/interpolation_scheme
    background/photometric_fit
    background/wdlf