Merging dev into main, prepare for v0.0.14

.github/workflows/python-package.yml

@@ -52,9 +52,10 @@ jobs:
         flag-name: Unit Test
 
   upload_pypi:
-    if: github.event_name == 'push'
+    if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     permissions:
+      contents: read
       id-token: write
     # or, alternatively, upload to PyPI on every tag starting with 'v' (remove on: release above to use this)
     # if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
@@ -72,13 +73,6 @@ jobs:
           pip install -r requirements.txt
           pip install -e .
           python setup.py sdist bdist_wheel
-
-      - uses: actions/download-artifact@v4
-        with:
-          # unpacks all CIBW artifacts into dist/
-          path: dist
-          merge-multiple: true
-
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/

.markdownlint.json

@@ -0,0 +1,14 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD022": false,
+  "MD024": false,
+  "MD032": false,
+  "MD041": false,
+  "MD043": {
+    "headings": [
+      "# CHANGELOG",
+      "+"
+    ]
+  }
+}

.readthedocs.yml

@@ -16,6 +16,7 @@ build:
 sphinx:
   builder: html
   configuration: docs/source/conf.py
+  fail_on_warning: true
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
 # formats:
@@ -24,4 +25,6 @@ sphinx:
 # Optionally declare the Python requirements required to build your docs
 python:
   install:
-  - requirements: docs/source/requirements.txt
+    - requirements: docs/source/requirements.txt
+    - method: pip
+      path: .

CHANGELOG.md

@@ -0,0 +1,137 @@
+# CHANGELOG
+
+All notable changes to WDPhotTools are documented in this file.
+
+The 0.0.x line is treated as the beta series. Entries below are listed newest
+to oldest and aligned to the 10 beta tags (`0.0.4` to `v0.0.13`).
+
+## [Unreleased] - 2026-07-07
+
+- New feature: Added canonical photometry API support in `WDfitter.fit` with
+  `photometry`, `photometry_errors`, and `photometry_space`.
+- New feature: Added fitting in flux space alongside magnitude space.
+- New feature: Added `self.best_fit_photometry` in the selected
+  `photometry_space`.
+- New feature: Added opt-in interpolator extrapolation controls for atmosphere
+  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.
+- 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): 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`.
+- Logging: Replaced touched `print` calls with structured `logging`.
+- Logging: Added INFO/WARNING logs at fitter orchestration boundaries.
+- Documentation: Updated README, examples, and docstrings to the canonical
+  photometry API.
+- Documentation: Updated RTD configuration/build and migration guidance.
+- Documentation: Added extrapolation guidance and a success-rate table across
+  10% to 50% extrapolation levels.
+- Tests: Updated fitter tests to canonical API calls.
+- 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-behaviour coverage for
+  atmosphere/cooling interpolators.
+- Examples: Updated example scripts for the new API/workflow expectations and
+  checked near-identical behaviour against `v0.0.13` where deterministic.
+- Documentation: Added interpolation scheme explanation
+
+## [v0.0.13] - 2026-01-14
+
+- Release: Versioned release `v0.0.13` (tag commit `e81da92`).
+
+## [v0.0.12] - 2025-12-27
+
+- Fix: Corrected conversion constant usage in fitter-related numerical paths.
+- Fix: Ensured `_integrand` returns `float` for improved compatibility.
+- Compatibility: Improved posture for the NumPy 1/2 transition.
+- Compatibility: Marked Windows with Python 3.13/3.14 CI as allowed failures
+  during transition.
+- CI/tooling: Updated GitHub Actions workflow and checkout handling.
+- CI/tooling: Updated setup metadata and test-pypi workflow on `dev`.
+- CI/tooling: Performed general housekeeping before release.
+
+## [v0.0.11] - 2025-09-22
+
+- Performance: Significantly improved WDLF computation runtime.
+- Performance: Refactored basis interpolation and integration helper paths.
+- Fix: Corrected wrong-array update bug and additional minor defects.
+- Fix: Cleaned redundant `.keys()` usage.
+- Dependency/packaging: Replaced `pkg_resources` with `importlib`.
+- Documentation/tooling: Updated RTD configuration/docs plus formatting and CI.
+- Tests: Updated tests to use `Agg` backend where needed.
+- Tests: Fixed test filename issues.
+
+## [v0.0.10] - 2025-05-13
+
+- New feature: Added support for user-provided priors in fitting workflows.
+- Validation/fix: Added and updated tests for prior handling.
+- Validation/fix: Fixed missing `z_min` and `z_max` handling in reddening
+  cases.
+- Validation/fix: Decoupled objective functions from fitter orchestration.
+- Validation/fix: Avoided interpolation-grid breakage in log-scale age grids.
+- CI/tooling: Updated test environments and weekly build checks.
+- CI/tooling: Updated pre-commit line-length configuration to 120 chars.
+- CI/tooling: Applied multiple housekeeping, style, and markdown fixes.
+
+## [v0.0.9] - 2023-08-11
+
+- Fix: Corrected example script syntax issues.
+- Fix: Corrected interpolation variable-allowlist omissions.
+- Fix: Corrected plotting type and element-wise comparison edge cases.
+- Fix: Added `> 0` safety checks in density computation paths.
+
+## [v0.0.8] - 2023-05-07
+
+- New feature: Added and validated fitter mass-estimation test coverage.
+- Fix: Corrected fitting-mass bug.
+- Fix: Corrected independent-variable name comparison robustness.
+- Fix: Migrated from deprecated `interp2d` to RBF interpolation.
+- Fix: Standardised fitter method outputs to scalar floats.
+- Documentation: Updated README and RTD content plus citation references.
+- Documentation: Added clarifications on uncertainty/error estimation behaviour.
+
+## [v0.0.7] - 2022-12-04
+
+- New feature: Stored `number_density` as object properties before CSV export.
+- Fix: Corrected sign bug in `dL/dt` number-density computation.
+- Fix: Added protections for log-scale y-axis with non-positive data.
+- Fix: Corrected negative-zero and additional plotting/cleanup issues.
+- Fix: Corrected default `Rv` from `0.0` to `3.1`.
+- CI/tooling: Added Python 3.11 in tests.
+- CI/tooling: Added code-analysis workflow and broad tidying.
+
+## [v0.0.6] - 2022-10-24
+
+- New feature: Added linear fractional extinction model support.
+- New feature: Added RA/Dec-aware fitter updates for extinction workflows.
+- New feature: Extended reddening API for linearly interpolated extinction.
+- Compatibility: Lowered minimum `astropy` version to support Python 3.7.
+- Compatibility: Added Python 3.10 and Windows CI/test coverage.
+- Tests: Extended tests for new reddening/extinction paths.
+- Tests: Reduced MCMC test walkers/steps/burn-in and relaxed tolerance for
+  stability.
+- Fix: Corrected dependent-variable distance handling edge cases.
+
+## [v0.0.5] - 2022-09-12
+
+- Refactor: Moved package code to `src/` layout.
+- Refactor: Removed `autograd` usage.
+- Fix: Corrected minimization-function bug(s).
+- Fix: Updated outdated examples.
+- Documentation: Added docs and README notes for retrieving fitted solutions.
+- Documentation: Added uncertainty notes and plotting updates.
+
+## [v0.0.4] - 2022-08-09
+
+- Compatibility: Adapted to SciPy 1.9 stricter data-type requirements.
+- Compatibility: Added SciPy-version handling for RegularGridInterpolator
+  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.

README.md

@@ -38,6 +38,9 @@ For best performance with RBFInterpolator, use SciPy 1.9+.
 
 Documentation and more examples can be found at
 [Read the Docs](https://wdphottools.readthedocs.io/en/latest/).
+For extrapolation behaviour and success-rate estimates from 10%-50% beyond the
+grid span, see the
+[interpolator extrapolation table](https://wdphottools.readthedocs.io/en/latest/background/extrapolation.html).
 
 ## Attribution
 
@@ -241,8 +244,8 @@ ftr = WDfitter()
 ftr.fit(
     atmosphere="H",
     filters=["g_ps1", "r_ps1", "i_ps1", "z_ps1", "y_ps1", "G3", "G3_BP", "G3_RP", "J_mko", "H_mko", "K_mko"],
-    mags=[21.1437, 19.9678, 19.4993, 19.2981, 19.1478, 20.0533, 20.7883, 19.1868, 19.45-0.91, 19.96-1.39, 20.40-1.85],
-    mag_errors=[0.0321, 0.0229, 0.0083, 0.0234, 0.0187, 0.006322, 0.118615, 0.070880, 0.05, 0.03, 0.05],
+    photometry=[21.1437, 19.9678, 19.4993, 19.2981, 19.1478, 20.0533, 20.7883, 19.1868, 19.45-0.91, 19.96-1.39, 20.40-1.85],
+    photometry_errors=[0.0321, 0.0229, 0.0083, 0.0234, 0.0187, 0.006322, 0.118615, 0.070880, 0.05, 0.03, 0.05],
     independent=["Teff", "logg"],
     initial_guess=[4000.0, 7.5],
     distance=71.231,
@@ -264,6 +267,46 @@ ftr.show_corner_plot(
 )
 ```
 
+### Fitting in relative flux space
+
+`WDfitter.fit` also supports relative flux fitting through `photometry_space="flux"`.
+
+```python
+import numpy as np
+from WDPhotTools.fitter import WDfitter
+
+filters = ["G3", "G3_BP", "G3_RP"]
+magnitudes = np.array([10.882, 10.853, 10.946], dtype=float)
+magnitude_errors = np.array([0.02, 0.02, 0.02], dtype=float)
+flux_photometry = 10.0 ** (-0.4 * magnitudes)
+flux_photometry_errors = flux_photometry * np.log(10.0) / 2.5 * magnitude_errors
+
+ftr = WDfitter()
+ftr.fit(
+    atmosphere="H",
+    filters=filters,
+    photometry=flux_photometry,
+    photometry_errors=flux_photometry_errors,
+    photometry_space="flux",
+    independent=["Teff"],
+    initial_guess=[13000.0],
+    logg=7.5,
+    distance=10.0,
+    distance_err=0.1,
+)
+ftr.show_best_fit(display=False)
+```
+
+### API migration (v0.0.13 -> this branch)
+
+| Old API name | New canonical name |
+| --- | --- |
+| `mags` | `photometry` |
+| `mag_errors` | `photometry_errors` |
+| `fluxes` | `photometry` + `photometry_space="flux"` |
+| `flux_errors` | `photometry_errors` + `photometry_space="flux"` |
+| `best_fit_mag` / `best_fit_flux` | `best_fit_photometry` |
+
 ### Reddening model
 
 The default setup assumes the provided reddening is the total amount at the

docs/source/background/cooling.rst

@@ -2,6 +2,6 @@
 White Dwarf Cooling
 ===================
 
-Most of the internal energy of a WD is the residual heat from the progenitor once it passed the planetary nebula phase. However, there are various physical processes that can provide an appreciable amount of energy and govern the cooling rate of a WD at different stages. Following the time sequence in which the physical processes that has direct effects to the photo-luminosity: (1) in the first :math:`10^{8}-10^{9}` years, shell burning of hydrogen via pp-chain can contribute up to 30% of the total luminosity (`Renedo et al. 2010 <https://ui.adsabs.harvard.edu/abs/2010ApJ...717..183R/abstract>`_). (2) Neutrino losses -- contribute to a significant fraction of energy loss in the early time of WDs when they were still hot, in the case of massive WDs, neutrino bremsstrahlung effect must also be taken into account (`Martin, Georg \& Achim 1994 <https://ui.adsabs.harvard.edu/abs/1994ApJ...425..222H/abstract>`_, `Itoh et al. 1996 <https://ui.adsabs.harvard.edu/abs/1996ApJS..102..411I/abstract>`_). (3) Gravitational settling of :math:`^{22}`Ne in intermediate to massive WDs releases sufficient gravitational potential energy to prolong the cooling times (`Deloye \& Bildsten 2002 <https://ui.adsabs.harvard.edu/abs/2002ApJ...580.1077D/abstract>`_, `Althaus et al. 2010 <https://ui.adsabs.harvard.edu/abs/2010ApJ...719..612A/abstract>`_). The heavier :math:`^{22}`Ne relative to the environment that is dominated by carbon, oxygen and nitrogen leads to a slow settling towards the core. This effect is the most obvious in the old and metal-rich systems, such as NGC 6791 (`Bedin et al. 2008 <https://ui.adsabs.harvard.edu/abs/2008ApJ...678.1279B/abstract>`_, `Garvia-Berro et al. 2010 <https://ui.adsabs.harvard.edu/abs/2010Natur.465..194G/abstract>`_). (4) In the late time of the WD evolution, convection plays a significant role in slowing down the cooling. As temperature decreases, the convective zone grows deeper into the interior and eventually reaches the degenerate core (see Figure 11 from `Althaus, Corsico, Isern, & García-Berro, 2010 <https://ui.adsabs.harvard.edu/abs/2010A%26ARv..18..471A/abstract>`_). This efficiently replenish the energy radiated away from the photosphere, thus this process known as the convective coupling, modifies the relations between the WD luminosity and core temperature (`D'Antona \& Mazzitelli 1989 <https://ui.adsabs.harvard.edu/abs/1989ApJ...347..934D/abstract>`_, `Fontaine, Brassard \& Bergeron 2001 <https://ui.adsabs.harvard.edu/abs/2001PASP..113..409F/abstract>`_). (5) Crystallisation occurs as the non-degenerate ions evolve from gas to fluid and eventually solid. The liquid-solid transition releases latent heat that slows down the cooling process. This also couples with the release of gravitational energy associated with changes in the carbon-oxygen profile (`Salaris et al. 1997  <https://ui.adsabs.harvard.edu/abs/1997ApJ...486..413S/abstract>`_) when the heavier oxygen-rich crystals displace carbon as a result of gravitational settling. Depending on the changes in the carbon-oxygen abundance profile, and the choice of phase diagram of a carbon-oxygen mixture, it modifies the rate of cooling and this specific effect is colloquially known as the (6) Phase Separation effect. (7) Coulomb Interactions modify the thermodynamical properties of the ionic gas, in particular the specific heat. Its strength is determined by the Coulomb coupling parameters. At first, the parameter is small, it slowly increases as an WD cools and the ions begin to change from gas to liquid and eventually form lattice. This releases latent heat that contribute to ~5% of the total luminosity (`Shaviv \& Kovetz 1976 <https://ui.adsabs.harvard.edu/abs/1976A%26A....51..383S/abstract>`_). At late time, few modes of the lattice are excited, the heat capacity drops according to the Debye law, this results in enhanced cooling. This process kicks in after :math:`10^9` yr for a :math:`1.0\,\odot` WD and over a Hubble time for a :math:`0.5\,\odot` WD. See below the plot of the luminosity as a function of cooling age.
+Most of the internal energy of a WD is the residual heat from the progenitor once it passed the planetary nebula phase. However, there are various physical processes that can provide an appreciable amount of energy and govern the cooling rate of a WD at different stages. Following the time sequence in which the physical processes that has direct effects to the photo-luminosity: (1) in the first :math:`10^{8}-10^{9}` years, shell burning of hydrogen via pp-chain can contribute up to 30% of the total luminosity (`Renedo et al. 2010 <https://ui.adsabs.harvard.edu/abs/2010ApJ...717..183R/abstract>`_). (2) Neutrino losses -- contribute to a significant fraction of energy loss in the early time of WDs when they were still hot, in the case of massive WDs, neutrino bremsstrahlung effect must also be taken into account (`Martin, Georg and Achim 1994 <https://ui.adsabs.harvard.edu/abs/1994ApJ...425..222H/abstract>`_, `Itoh et al. 1996 <https://ui.adsabs.harvard.edu/abs/1996ApJS..102..411I/abstract>`_). (3) Gravitational settling of :math:`^{22}\mathrm{Ne}` in intermediate to massive WDs releases sufficient gravitational potential energy to prolong the cooling times (`Deloye and Bildsten 2002 <https://ui.adsabs.harvard.edu/abs/2002ApJ...580.1077D/abstract>`_, `Althaus et al. 2010 <https://ui.adsabs.harvard.edu/abs/2010ApJ...719..612A/abstract>`_). The heavier :math:`^{22}\mathrm{Ne}` relative to the environment that is dominated by carbon, oxygen and nitrogen leads to a slow settling towards the core. This effect is the most obvious in the old and metal-rich systems, such as NGC 6791 (`Bedin et al. 2008 <https://ui.adsabs.harvard.edu/abs/2008ApJ...678.1279B/abstract>`_, `Garvia-Berro et al. 2010 <https://ui.adsabs.harvard.edu/abs/2010Natur.465..194G/abstract>`_). (4) In the late time of the WD evolution, convection plays a significant role in slowing down the cooling. As temperature decreases, the convective zone grows deeper into the interior and eventually reaches the degenerate core (see Figure 11 from `Althaus, Corsico, Isern, and García-Berro, 2010 <https://ui.adsabs.harvard.edu/abs/2010A%26ARv..18..471A/abstract>`_). This efficiently replenish the energy radiated away from the photosphere, thus this process known as the convective coupling, modifies the relations between the WD luminosity and core temperature (`D'Antona and Mazzitelli 1989 <https://ui.adsabs.harvard.edu/abs/1989ApJ...347..934D/abstract>`_, `Fontaine, Brassard and Bergeron 2001 <https://ui.adsabs.harvard.edu/abs/2001PASP..113..409F/abstract>`_). (5) Crystallisation occurs as the non-degenerate ions evolve from gas to fluid and eventually solid. The liquid-solid transition releases latent heat that slows down the cooling process. This also couples with the release of gravitational energy associated with changes in the carbon-oxygen profile (`Salaris et al. 1997  <https://ui.adsabs.harvard.edu/abs/1997ApJ...486..413S/abstract>`_) when the heavier oxygen-rich crystals displace carbon as a result of gravitational settling. Depending on the changes in the carbon-oxygen abundance profile, and the choice of phase diagram of a carbon-oxygen mixture, it modifies the rate of cooling and this specific effect is colloquially known as the (6) Phase Separation effect. (7) Coulomb Interactions modify the thermodynamical properties of the ionic gas, in particular the specific heat. Its strength is determined by the Coulomb coupling parameters. At first, the parameter is small, it slowly increases as an WD cools and the ions begin to change from gas to liquid and eventually form lattice. This releases latent heat that contribute to ~5% of the total luminosity (`Shaviv and Kovetz 1976 <https://ui.adsabs.harvard.edu/abs/1976A%26A....51..383S/abstract>`_). At late time, few modes of the lattice are excited, the heat capacity drops according to the Debye law, this results in enhanced cooling. This process kicks in after :math:`10^9` yr for a :math:`1.0\,\odot` WD and over a Hubble time for a :math:`0.5\,\odot` WD. See below the plot of the luminosity as a function of cooling age.
 
-.. figure:: ../_static/DA_cooling_model_from_plotter.png
+.. figure:: ../_static/DA_cooling_model_from_plotter.png