v1.4.0: Python package and reference dataset

Release date: 22 October 2026. The README and API page were accepted before publication. The release uses the annotated tag v1.4.0.

Changes

BoreTHM installs as the borethm Python package. The public interface documents the evaluation functions and the constructors needed to reuse the component calculations. Its listed names follow semantic versioning from 1.4.0. Internal modules may change in any release.

The commands borethm-evaluate, borethm-sites and borethm-water-table replace direct execution of source files. Study modules run with python -m borethm.studies.<module> in a source checkout when they need retained evidence. Standalone figure scripts are in scripts/. Data ship in src/borethm/data/; the water-property cache is stored outside the installation, with BORETHM_CACHE_DIR available to choose its directory.

The benchmark dataset has its own version, 1.0. It includes six cases, with retained expected outputs and existing tolerances. Its assembly runs no models. Some geometry recipes and geotherm definitions remain code references; the dataset guide describes those limits. The dataset will have a separate Zenodo deposit and citation.

The contribution guide and support guide describe development and issue reporting. CI checks package installation and the fast suite on Python 3.11 to 3.14. A trusted-publishing workflow sends manual builds to TestPyPI and published releases to PyPI.

No physics, input or calculation default changes. The existing result files, goldens and historical release records are unchanged. Earlier commands remain in their release records and run from the corresponding tag.

Reproduction

Follow the README setup with Python 3.14.4, then run from the checkout:

python -m pip install -r requirements-lock.txt
python -m pip install --no-deps -e .
borethm-water-table
python -m pytest
python -m pytest -m "slow or not slow"

Set OPENBLAS_NUM_THREADS, OMP_NUM_THREADS and MKL_NUM_THREADS to one before starting Python. Tests run in one process. The locked numerical libraries are NumPy 2.5.3, SciPy 1.18.1 and iapws 1.5.5; the plotting library is Matplotlib 3.11.2 and the test runner is pytest 9.1.1.

Validation

The local fast suite passes 401 tests, with 106 physical regressions excluded, in 24.72 seconds. The documentation link checker covers current reader pages; archived reviews and the v1.3.6 release record retain their historical paths. Checksums confirm that all 275 original result, golden, archive and release files are unchanged.

The full-suite CI run on candidate abdb56c passed all 507 tests, including 106 slow regressions, in 7,428.35 seconds (2 hours 3 minutes 48 seconds). Source files, input data and regressions match that candidate. Pytest reported 14 numerical runtime warnings from the circulation model and SciPy boundary-value solver. The run retains a JUnit report as full-physical-regressions. Every existing numerical regression reproduces within its unchanged tolerance. The package fingerprints required fresh physical calculations.

The TestPyPI publishing run succeeded. A fresh environment installed its 1.4.0 wheel from TestPyPI and passed the installation checks without Matplotlib. That upload preceded the documentation updates; the final release distributions are built and checked again before publication. The production publishing run published v1.4.0 to PyPI. A fresh environment installed it from production PyPI and passed the API, packaged-data, command-help and dependency checks without Matplotlib. The downloaded wheel and source distribution match the publishing artifacts by SHA-256. The release checklist records the remaining publication steps.

Citation and archive

The Zenodo software archive preserves v1.4.0. All 540 files in its ZIP match the Git tag exactly. Use the all-versions software DOI for the project citation; the DOI above identifies this release specifically. The citation metadata on main includes the software DOI and author ORCID iD.

Benchmark dataset 1.0 has a separate upload ZIP and will receive its own DOI after deposit. The software DOI does not identify that dataset separately.

Publication follow-up, 22 October 2026: production PyPI publication and a fresh installation were verified, and the Zenodo software archive was checked against the tag. The all-versions software DOI is recorded in the project citation metadata.