Cubic interpolation and MIST 2.5 isochrones

.github/workflows/test.yml

@@ -13,11 +13,11 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout 
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Python setup
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           architecture: 'x64'
@@ -26,16 +26,37 @@ jobs:
           python -m pip install --upgrade pip
           pip install pytest
           pip install pylint
-          pip install pytest-cov
-          pip install coveralls
           pip install .
       - name: Pylint
         if: ${{ ( matrix.os != 'windows-latest' ) }}
         run: pylint -E --disable=E1101 py/minimint/*py
       - name: Test
-        run:  pytest --cov=minimint -s
+        run: pytest -s
+
+  coverage:
+    name: 'Coverage (NUMBA_DISABLE_JIT=1)'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Python setup
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+          architecture: 'x64'
+      - name: Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest
+          pip install pytest-cov
+          pip install coveralls
+          pip install .
+      - name: Coverage test
+        run: NUMBA_DISABLE_JIT=1 pytest --cov=minimint -s
       - name: Coveralls
-        if: ${{ success() && (matrix.os != 'windows-latest') }}
+        if: ${{ success() }}
         run: coveralls --service=github
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.readthedocs.yml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

AGENTS.md

@@ -0,0 +1,50 @@
+# AGENTS.md
+
+## Working Rules
+- Never commit unless the user explicitly approves it.
+- If a change is large or touches many files, propose a short plan and wait for approval before editing.
+- Do not create or edit files outside this workspace without explicit permission.
+- Do not install dependencies unless explicitly requested.
+- Before making code changes, state what will be changed and why.
+- Be direct and factual; prioritize correctness over tone-polishing.
+
+## Repository Overview
+- Package code: `py/minimint/`
+  - `mist_interpolator.py`: MIST track download/preprocessing/interpolation APIs.
+  - `bolom.py`: bolometric correction loading/interpolation.
+  - `utils.py`: shared interpolation/path helpers.
+- Tests: `tests/` (main suite: `tests/test_minimint.py`).
+- Example notebook: `examples/Example.ipynb`.
+- Generated artifacts: `build/`, `dist/` (do not edit manually).
+
+## Development Commands
+- Install editable: `python -m pip install -e .`
+- Run tests: `pytest -s`
+- Run coverage: `pytest --cov=minimint -s`
+- CI lint gate: `pylint -E --disable=E1101 py/minimint/*py`
+- Build sdist/wheel: `python -m build --sdist --wheel`
+
+## Style Expectations
+- Python style consistent with existing files.
+- 4-space indentation.
+- `snake_case` for functions/variables; `CapWords` for classes.
+- Keep public API names stable (see `py/minimint/__init__.py`).
+- Add concise docstrings for non-trivial numerical logic and boundary handling.
+
+## Testing Expectations
+- Add/update tests in `tests/test_minimint.py` for behavioral changes.
+- Prefer focused regression tests for interpolation and edge cases.
+- Use `LOCAL_TESTING=1` for quick local iteration.
+- Run full test suite before finalizing significant interpolation/data-path changes.
+
+## Git Hygiene
+- Keep changes focused and minimal.
+- Never revert unrelated user changes.
+- Avoid committing generated or cache artifacts.
+- Use short imperative commit titles when commits are requested.
+
+## PR Checklist (when requested)
+- What changed and why.
+- API/numerical behavior impact.
+- Validation commands and results.
+- Linked issue(s), if any.

CHANGELOG.md

@@ -1,3 +1,10 @@
+# Version 1.0
+* Implement cubic interpolation
+* Add support of alpha-enhanced MIST 2.5 isochrones
+
+# Version 0.5.1.
+Fix the path to MIST bolometric corrections
+
 # Version 0.5.0
 * switch to pyproject.toml
 * allow to chose v/vcrit value when fetching MIST tracks

INTERP.md

@@ -0,0 +1,73 @@
+# How Minimint Interpolation Works (Current Implementation)
+
+This document describes the interpolation logic currently implemented in `minimint`.
+
+## Overview
+
+`minimint.Interpolator` combines two stages:
+
+1. `TheoryInterpolator`: maps `(mass, logage, [Fe/H]) -> (logg, logl, logteff, phase)`
+2. `BCInterpolator`: maps `(logteff, logg, [Fe/H], A_V) -> bolometric corrections`, then computes magnitudes
+
+The runtime is vectorized over stars.
+
+## Stage 1: TheoryInterpolator
+
+MIST tracks are tabulated on `(feh, mass, EEP)`, while user input includes `logage`, so the code first inverts age to fractional EEP.
+
+### 1) Spatial coefficients in `(feh, mass)`
+
+- Always compute bilinear weights (`C11..C22`) for the enclosing `(feh, mass)` cell.
+- If `spatial_order=3`, also compute cubic Hermite/Catmull-Rom-style weights in `feh` and `mass` (4-point stencil per axis).
+
+### 2) Age -> EEP inversion
+
+- A custom binary search (`_binary_search`) is used over EEP index.
+- The helper `getAge(EEP)` is evaluated at each iteration:
+  - `spatial_order=1`: bilinear in `(feh, mass)` + lookup at EEP
+  - `spatial_order=3`: bicubic in `(feh, mass)` + lookup at EEP, with linear fallback if any cubic stencil value is non-finite
+- Once bracketing EEP indices `(eep1, eep2)` are found, the fractional position `eep_frac` is solved with `utils.solve_steffen_t(...)` using age values at `EEP-1, EEP, EEP+1, EEP+2`.
+
+This keeps age/EEP interpolation monotonic while still enabling smooth cubic spatial behavior.
+
+### 3) Final theory quantities at target age
+
+For each good point:
+
+- Build EEP samples `eep-1, eep0, eep1, eep+2`
+- Evaluate spatial interpolation at those EEP samples:
+  - `logg`, `logl`, `logteff`: cubic spatial (`spatial_order=3`) with linear fallback on invalid cubic stencils
+  - `phase`: linear spatial interpolation
+- Interpolate in EEP:
+  - `logg`, `logl`, `logteff`: `utils.steffen_interp(...)`
+  - `phase`: linear in EEP between `eep1` and `eep2`
+
+### 4) Boundary helpers
+
+- `_isvalid` uses the same age interpolation mode as runtime (`spatial_order`-aware) to avoid boundary inconsistencies.
+- `getMaxMass`:
+  - Binary-searches mass grid for a valid/invalid bracket
+  - Refines with bisection using finite/non-finite behavior of `self(m, logage, feh)`
+
+## Stage 2: BCInterpolator
+
+Bolometric corrections are on a 4D regular grid `(logteff, logg, [Fe/H], A_V)`.
+
+Current runtime uses 4D cubic interpolation:
+
+- Per axis, compute cubic weights/indices (`_get_cubic_coeffs`)
+- Evaluate tensor-product cubic interpolant (`_interpolator_4cubic`)
+- Mark out-of-bounds points as `NaN`
+
+This is smoother than linear BC interpolation and avoids piecewise-linear color artifacts along isochrones.
+
+## Magnitude formula
+
+For each filter `lambda`:
+
+`M_lambda = 4.74 - 2.5 * logl - BC_lambda`
+
+## NaNs and validity
+
+- Points outside the physical track support are returned as `NaN`.
+- Cubic paths include linear fallback when a required cubic stencil contains non-finite values.

README.md

@@ -4,13 +4,14 @@
 
 # Minimint (MIni Mist INTerpolation)
 
-This is a python package to perform interpolation of MIST isochrones. It is simple, in the sense that it only does one thing - predict the stellar parameters ($\log g$, $T_{eff}$, $\log L$) and photometry in a given filter for a given mass, age and metallicity. It is also vectorized, so computing photometry for large number of stars, should not be slow.
+This is a python package to perform interpolation of MIST (v1.2 and alpha-enriched v2.5) isochrones. It is simple, in the sense that it only does one thing - predict the stellar parameters ($\log g$, $T_{eff}$, $\log L$) and photometry in a given filter for a given mass, age and metallicity. It is also vectorized, so computing photometry for a large number of stars should not be slow.
 
 Author: Sergey Koposov (2020-2026) skoposov __AT__ ed __DOT__ ac __DOT__ uk
 
 ## Instructions 
 
-* Install minimint. You can either pip install the released version or install from github
+* Install minimint. You can either pip install the released version or install from github. Currently the version supporting the MIST 2.5 isochrones is
+only available on github, but not yet through pypi. 
 
 ```
 pip install minimint
@@ -29,16 +30,98 @@ If you need additional filters, you can specify them using the filters parameter
 
 ``` minimint.download_and_prepare(filters=['JWST','WISE','DECam', 'GALEX', 'PanSTARRS', 'SDSSugriz', 'SkyMapper','UBVRIplus'])```
 Check which filters are available on the MIST website http://waps.cfa.harvard.edu/MIST/model_grids.html
-The downloading will take some time (20-30 min) and will use significant amount of disk space (10-30 Gb).
+
+You can select MIST version with `mist_version`:
+``` minimint.download_and_prepare(mist_version='1.2')```
+
+``` minimint.download_and_prepare(mist_version='2.5')```
+
+For MIST 1.2 the downloading will take some time (20-30 min) and will use significant amount of disk space (10-30 Gb).
+Keep in mind that the whole 2.5 set of tracks will use ~ 100 GB of *temporary* disk space. The space used after install should be < 2GB.
 
 If you want to put those processed isochrone files in a location different from the site-packages folder of minimint, you can use the outp_prefix parameter of `download_and_prepare`. You then will need to either specify the location each time when you construct the interpolators or with the MINIMINT_DATA_PATH environment variable.
 
+You can prepare multiple rotation grids and select by `vvcrit`:
+
+``` minimint.download_and_prepare(vvcrit=0.4)```
+
+``` minimint.download_and_prepare(vvcrit=0.0)```
+
+You can use these commands to just fetch a subset of the grid by specifying feh_values or afe_values arguments
+
+
+If you are using the latest 1.0 version of minimint existing local data from older releases should be regenerated by rerunning `download_and_prepare(...)`.
+
+### Manual Download + `prepare()`
+
+If you already downloaded MIST archives manually, you can unpack them yourself and run only the preparation step:
+
+You can also get the expected archive URLs directly from minimint:
+
+```python
+import minimint
+
+# Bolometric-correction archives
+bc_urls = minimint.get_bc_urls(['DECam', 'WISE'], mist_version='2.5')
+
+# EEP track archives
+eep_urls = minimint.get_eep_urls(
+    feh_values=[-1.0, -0.5, 0.0],
+    afe_values=[0.0, 0.2, 0.4],
+    mist_version='2.5',
+    vvcrit=0.4,
+)
+```
+
+Download/unpack those URLs however you prefer, then run:
+
+```python
+import minimint
+
+# folder with unpacked EEP directories/files
+eep_prefix = "/path/to/unpacked/eep_data"
+
+# folder with unpacked BC table files (can be same as eep_prefix)
+bolom_prefix = "/path/to/unpacked/bc_data"
+
+minimint.prepare(
+    eep_prefix,
+    bolom_prefix=bolom_prefix,
+    outp_prefix="/path/to/output",
+    mist_version="2.5",   # or "1.2"
+    vvcrit=0.4,
+)
+```
+
+For BC-only preparation (skip EEP processing), use:
+
+```python
+minimint.prepare(
+    eep_prefix="/path/to/unpacked/data",
+    bolom_prefix="/path/to/unpacked/data",
+    outp_prefix="/path/to/output",
+    bc_only=True,
+    mist_version="2.5",
+    vvcrit=0.4,
+)
+```
+
 ## Usage 
 
-In order to create an interpolator object for two filters (your can provide a list of any numbers of filters)
+In order to create an interpolator object for two filters (you can provide a list of any number of filters)
 
 ```ii = minimint.Interpolator(['DECam_g','DECam_r'])```
 
+To select a specific prepared v1.2 rotation grid:
+
+```ii = minimint.Interpolator(['DECam_g','DECam_r'], vvcrit=0.0)```
+
+To select MIST version explicitly:
+
+```ii = minimint.Interpolator(['DECam_g','DECam_r'], mist_version='1.2')```
+
+```ii = minimint.Interpolator(['DECam_g','DECam_r'], mist_version='2.5')```
+
 The interpolator is a callable, so you can call it on mass, log10(age), feh 
 
 ``` ii(mass, logage, feh)``` 
@@ -58,6 +141,20 @@ See the [notebook](examples/Example.ipynb) in the examples folder
 If you are interested in synthetic stellar populations you will need
 an implementation of the IMF. For this you may want to use https://github.com/keflavich/imf
 
+## Interpolation mode
+
+Minimint supports two interpolation modes via `interp_mode`:
+
+- `interp_mode='linear'`: more conservative and typically more robust on sparse/coarse grids.
+- `interp_mode='cubic'`: smoother cubic interpolation, but it can be a bit 'wiggly' in the parts of HRD with very rapid changes (like the horizontal branch region)
+
+Examples:
+
+```python
+ii_lin = minimint.Interpolator(['DECam_g', 'DECam_r'], interp_mode='linear')
+ii_cub = minimint.Interpolator(['DECam_g', 'DECam_r'], interp_mode='cubic')
+```
+
 ## Acknowledgement
 
 If you are using this package please cite it through zenodo link

docs/api.rst

@@ -0,0 +1,23 @@
+API Reference
+=============
+
+mist_interpolator
+-----------------
+
+.. automodule:: minimint.mist_interpolator
+   :members:
+   :show-inheritance:
+
+bolom
+-----
+
+.. automodule:: minimint.bolom
+   :members:
+   :show-inheritance:
+
+utils
+-----
+
+.. automodule:: minimint.utils
+   :members:
+   :show-inheritance: