hallmodel 2026.6.19.6__tar.gz

hallmodel-2026.6.19.6/LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2018
+COPYRIGHT HOLDER: Instituto Nacional de Salud Pública

hallmodel-2026.6.19.6/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2018 Instituto Nacional de Salud Pública
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hallmodel-2026.6.19.6/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: hallmodel
+Version: 2026.6.19.6
+Summary: Python interface to the Hall body-weight dynamics models, backed by the hallmodel-core C++ kernel.
+Author: ChocoTonic
+License: # MIT License
+        
+        Copyright (c) 2018 Instituto Nacional de Salud Pública
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/ChocoTonic/hallmodel-py
+Project-URL: Core kernel, https://github.com/ChocoTonic/hallmodel-core
+Project-URL: Upstream R package, https://github.com/INSP-RH/bw
+Keywords: body-weight,metabolism,Hall,dynamic-weight-model
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE.md
+Requires-Dist: numpy>=1.24
+Dynamic: license-file
+
+# hallmodel-py
+
+Python interface to the [Hall](https://www.niddk.nih.gov/about-niddk/staff-directory/biography/hall-kevin)
+adult- and child- body-weight dynamics models, backed by the C++ kernel in
+[hallmodel-core](../hallmodel-core) (vendored here as a git submodule).
+
+The kernel is the same math the R package [`INSP-RH/bw`](https://github.com/INSP-RH/bw)
+compiles. Compiled in matched toolchains with `-ffp-contract=off`, the
+outputs are byte-for-byte reproducible against the upstream parity contract;
+under the contract's published tolerance (`rtol=1e-9`, `atol=1e-12`), all 18
+contract cases pass.
+
+This is the first reference consumer of `hallmodel-core` — it is also the
+worked example for "here is how you write a new language binding against the
+core."
+
+---
+
+## Install
+
+```bash
+git clone --recurse-submodules <repo-url> hallmodel-py
+cd hallmodel-py
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+Build needs a C++17 compiler and `pybind11` (declared in `pyproject.toml`).
+
+If you cloned without `--recurse-submodules`:
+
+```bash
+git submodule update --init --recursive
+```
+
+## Use
+
+```python
+import bw_cpp
+
+# Adult model — single individual, baseline EI from Mifflin-St Jeor
+res = bw_cpp.adult_weight(bw=76, ht=1.73, age=36, sex="male")
+print(res["Body_Weight"].shape)       # (1, 366)
+
+# Adult with a 500-kcal deficit over 365 days
+import numpy as np
+res = bw_cpp.adult_weight(
+    bw=90, ht=1.80, age=40, sex="male",
+    EIchange=np.full((1, 365), -500.0),
+)
+
+# Child model — auto FFM/FM/EI defaults from age + sex
+res = bw_cpp.child_weight(age=6, sex="male", days=365)
+
+# Energy interpolation
+out = bw_cpp.EnergyBuilder().build(
+    energy=np.array([[2000, 2200, 1800]]),
+    time=np.array([0, 5, 10]),
+    method="Linear",
+)
+```
+
+See the docstrings in [`bw_cpp/__init__.py`](bw_cpp/__init__.py) for the full
+API, and the upstream [R wrappers](https://github.com/INSP-RH/bw/tree/master/R)
+for the semantics of each parameter — they are the same.
+
+## Parity proof
+
+`./proof/verify.sh` builds the binding against the pinned `hallmodel-core`
+submodule, drives all 18 contract cases through `bw_cpp`, and asserts the
+contract's tolerance via `contract/compare.py`. Exit 0 = parity holds.
+
+```bash
+./proof/verify.sh
+```
+
+The committed [`proof/last_run.log`](proof/last_run.log) and
+[`proof/outputs/`](proof/outputs/) are the frozen evidence of the most
+recent green run. CI re-runs them on every PR. The pinned submodule sha is
+the version contract: bumping it triggers a re-verify.
+
+The one excluded field is `BMI_Category` — the contract's `generate.R`
+coerces character matrices through `as.numeric()`, producing a column of
+literal `"NA"` strings in every adult golden. See
+[`hallmodel-core/proof/verify.sh`](external/hallmodel-core/proof/verify.sh)
+for the full explanation.
+
+## How this maps to upstream
+
+| upstream R                            | here                          |
+| ------------------------------------- | ----------------------------- |
+| `INSP-RH/bw::adult_weight()`          | `bw_cpp.adult_weight()`       |
+| `INSP-RH/bw::child_weight()`          | `bw_cpp.child_weight()`       |
+| `INSP-RH/bw::child_reference_EI()`    | `bw_cpp.child_reference_EI()` |
+| `INSP-RH/bw::child_reference_FFMandFM()` | `bw_cpp.child_reference_FFMandFM()` |
+| `INSP-RH/bw::EnergyBuilder()`         | `bw_cpp.EnergyBuilder().build()` |
+
+Argument names, semantics, and defaults all match `INSP-RH/bw`'s R wrappers
+because this Python shim was deliberately written as a direct port of those
+wrappers. The contract gate enforces it.
+
+## License
+
+MIT, carried forward from [`INSP-RH/bw`](https://github.com/INSP-RH/bw).
+
+## Citing
+
+Cite the original `bw` package and Hall et al.'s underlying papers. See the
+README of [`INSP-RH/bw`](https://github.com/INSP-RH/bw) and
+[`hallmodel-core/docs/ATTRIBUTION.md`](external/hallmodel-core/docs/ATTRIBUTION.md).

hallmodel-2026.6.19.6/README.md

@@ -0,0 +1,110 @@
+# hallmodel-py
+
+Python interface to the [Hall](https://www.niddk.nih.gov/about-niddk/staff-directory/biography/hall-kevin)
+adult- and child- body-weight dynamics models, backed by the C++ kernel in
+[hallmodel-core](../hallmodel-core) (vendored here as a git submodule).
+
+The kernel is the same math the R package [`INSP-RH/bw`](https://github.com/INSP-RH/bw)
+compiles. Compiled in matched toolchains with `-ffp-contract=off`, the
+outputs are byte-for-byte reproducible against the upstream parity contract;
+under the contract's published tolerance (`rtol=1e-9`, `atol=1e-12`), all 18
+contract cases pass.
+
+This is the first reference consumer of `hallmodel-core` — it is also the
+worked example for "here is how you write a new language binding against the
+core."
+
+---
+
+## Install
+
+```bash
+git clone --recurse-submodules <repo-url> hallmodel-py
+cd hallmodel-py
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+Build needs a C++17 compiler and `pybind11` (declared in `pyproject.toml`).
+
+If you cloned without `--recurse-submodules`:
+
+```bash
+git submodule update --init --recursive
+```
+
+## Use
+
+```python
+import bw_cpp
+
+# Adult model — single individual, baseline EI from Mifflin-St Jeor
+res = bw_cpp.adult_weight(bw=76, ht=1.73, age=36, sex="male")
+print(res["Body_Weight"].shape)       # (1, 366)
+
+# Adult with a 500-kcal deficit over 365 days
+import numpy as np
+res = bw_cpp.adult_weight(
+    bw=90, ht=1.80, age=40, sex="male",
+    EIchange=np.full((1, 365), -500.0),
+)
+
+# Child model — auto FFM/FM/EI defaults from age + sex
+res = bw_cpp.child_weight(age=6, sex="male", days=365)
+
+# Energy interpolation
+out = bw_cpp.EnergyBuilder().build(
+    energy=np.array([[2000, 2200, 1800]]),
+    time=np.array([0, 5, 10]),
+    method="Linear",
+)
+```
+
+See the docstrings in [`bw_cpp/__init__.py`](bw_cpp/__init__.py) for the full
+API, and the upstream [R wrappers](https://github.com/INSP-RH/bw/tree/master/R)
+for the semantics of each parameter — they are the same.
+
+## Parity proof
+
+`./proof/verify.sh` builds the binding against the pinned `hallmodel-core`
+submodule, drives all 18 contract cases through `bw_cpp`, and asserts the
+contract's tolerance via `contract/compare.py`. Exit 0 = parity holds.
+
+```bash
+./proof/verify.sh
+```
+
+The committed [`proof/last_run.log`](proof/last_run.log) and
+[`proof/outputs/`](proof/outputs/) are the frozen evidence of the most
+recent green run. CI re-runs them on every PR. The pinned submodule sha is
+the version contract: bumping it triggers a re-verify.
+
+The one excluded field is `BMI_Category` — the contract's `generate.R`
+coerces character matrices through `as.numeric()`, producing a column of
+literal `"NA"` strings in every adult golden. See
+[`hallmodel-core/proof/verify.sh`](external/hallmodel-core/proof/verify.sh)
+for the full explanation.
+
+## How this maps to upstream
+
+| upstream R                            | here                          |
+| ------------------------------------- | ----------------------------- |
+| `INSP-RH/bw::adult_weight()`          | `bw_cpp.adult_weight()`       |
+| `INSP-RH/bw::child_weight()`          | `bw_cpp.child_weight()`       |
+| `INSP-RH/bw::child_reference_EI()`    | `bw_cpp.child_reference_EI()` |
+| `INSP-RH/bw::child_reference_FFMandFM()` | `bw_cpp.child_reference_FFMandFM()` |
+| `INSP-RH/bw::EnergyBuilder()`         | `bw_cpp.EnergyBuilder().build()` |
+
+Argument names, semantics, and defaults all match `INSP-RH/bw`'s R wrappers
+because this Python shim was deliberately written as a direct port of those
+wrappers. The contract gate enforces it.
+
+## License
+
+MIT, carried forward from [`INSP-RH/bw`](https://github.com/INSP-RH/bw).
+
+## Citing
+
+Cite the original `bw` package and Hall et al.'s underlying papers. See the
+README of [`INSP-RH/bw`](https://github.com/INSP-RH/bw) and
+[`hallmodel-core/docs/ATTRIBUTION.md`](external/hallmodel-core/docs/ATTRIBUTION.md).

hallmodel-2026.6.19.6/bindings/bw_cpp.cpp

@@ -0,0 +1,240 @@
+// pybind11 bindings exposing the pure-C++ bw kernel (src/kernel, src/include)
+// to Python — the same kernel the R package compiles, so results are identical.
+//
+// These mirror the [[Rcpp::export]] wrappers in src/*_rcpp.cpp one-to-one
+// (same arguments, same call patterns), but marshal NumPy arrays instead of
+// Rcpp types. The thin orchestration shim lives in Python (bw_cpp/__init__.py),
+// mirroring R/*.R.
+//
+// Build with -ffp-contract=off (see pyproject) so the arithmetic matches the
+// contract's golden bit-for-bit when compiled in the same toolchain.
+
+#include <pybind11/pybind11.h>
+#include <pybind11/numpy.h>
+#include <pybind11/stl.h>
+
+#include <cmath>
+#include <cstddef>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+#include "bw/adult.hpp"
+#include "bw/child.hpp"
+#include "bw/energy.hpp"
+
+namespace py = pybind11;
+
+// ---- input marshaling ------------------------------------------------------
+
+static std::vector<double> vec1d(const py::array_t<double>& a) {
+    auto b = a.template unchecked<1>();
+    std::vector<double> out(static_cast<std::size_t>(b.shape(0)));
+    for (py::ssize_t i = 0; i < b.shape(0); ++i) out[static_cast<std::size_t>(i)] = b(i);
+    return out;
+}
+
+// 2D NumPy (row-major) -> bw::Matrix preserving (i, j).
+static bw::Matrix mat2d(const py::array_t<double>& a) {
+    auto b = a.template unchecked<2>();
+    bw::Matrix m(static_cast<std::size_t>(b.shape(0)), static_cast<std::size_t>(b.shape(1)));
+    for (py::ssize_t i = 0; i < b.shape(0); ++i)
+        for (py::ssize_t j = 0; j < b.shape(1); ++j)
+            m(static_cast<std::size_t>(i), static_cast<std::size_t>(j)) = b(i, j);
+    return m;
+}
+
+// ---- output marshaling -----------------------------------------------------
+
+static py::array_t<double> from_mat(const bw::Matrix& m) {
+    py::array_t<double> out({m.nrow, m.ncol});
+    auto r = out.mutable_unchecked<2>();
+    for (std::size_t i = 0; i < m.nrow; ++i)
+        for (std::size_t j = 0; j < m.ncol; ++j)
+            r(i, j) = m(i, j);
+    return out;
+}
+
+static py::array_t<double> from_vec(const std::vector<double>& v) {
+    py::array_t<double> out(static_cast<py::ssize_t>(v.size()));
+    auto r = out.mutable_unchecked<1>();
+    for (std::size_t i = 0; i < v.size(); ++i) r(static_cast<py::ssize_t>(i)) = v[i];
+    return out;
+}
+
+// Child result matrices are laid out data[i + nind*j]; reshape to (nind, nsteps).
+static py::array_t<double> from_child(const std::vector<double>& data,
+                                      std::size_t nind, std::size_t nsteps) {
+    py::array_t<double> out({nind, nsteps});
+    auto r = out.mutable_unchecked<2>();
+    for (std::size_t i = 0; i < nind; ++i)
+        for (std::size_t j = 0; j < nsteps; ++j)
+            r(i, j) = data[i + nind * j];
+    return out;
+}
+
+static py::dict adult_result(const bw::AdultResult& res) {
+    // BMI_Category: list of per-individual lists of strings (rows = individuals).
+    py::list cat;
+    for (std::size_t i = 0; i < res.BMI_Category.nrow; ++i) {
+        py::list row;
+        for (std::size_t j = 0; j < res.BMI_Category.ncol; ++j)
+            row.append(res.BMI_Category(i, j));
+        cat.append(row);
+    }
+    py::dict d;
+    d["Time"]                   = from_vec(res.Time);
+    d["Age"]                    = from_mat(res.Age);
+    d["Adaptive_Thermogenesis"] = from_mat(res.Adaptive_Thermogenesis);
+    d["Extracellular_Fluid"]    = from_mat(res.Extracellular_Fluid);
+    d["Glycogen"]               = from_mat(res.Glycogen);
+    d["Fat_Mass"]               = from_mat(res.Fat_Mass);
+    d["Lean_Mass"]              = from_mat(res.Lean_Mass);
+    d["Body_Weight"]            = from_mat(res.Body_Weight);
+    d["Body_Mass_Index"]        = from_mat(res.Body_Mass_Index);
+    d["BMI_Category"]           = cat;
+    d["Energy_Intake"]          = from_mat(res.Energy_Intake);
+    d["Correct_Values"]         = res.Correct_Values;
+    d["Model_Type"]             = res.Model_Type;
+    return d;
+}
+
+static py::dict child_result(const bw::ChildRK4Result& R) {
+    py::dict d;
+    d["Time"]           = from_vec(R.Time);
+    d["Age"]            = from_child(R.Age,           R.nind, R.nsteps);
+    d["Fat_Free_Mass"]  = from_child(R.Fat_Free_Mass, R.nind, R.nsteps);
+    d["Fat_Mass"]       = from_child(R.Fat_Mass,      R.nind, R.nsteps);
+    d["Body_Weight"]    = from_child(R.Body_Weight,   R.nind, R.nsteps);
+    d["Correct_Values"] = R.Correct_Values;
+    d["Model_Type"]     = std::string("Children");
+    return d;
+}
+
+// ---- exported functions (mirror src/*_rcpp.cpp) ----------------------------
+
+static py::dict adult_baseline(py::array_t<double> bw, py::array_t<double> ht,
+        py::array_t<double> age, py::array_t<double> sex,
+        py::array_t<double> EIchange, py::array_t<double> NAchange,
+        py::array_t<double> PAL, py::array_t<double> pcarb_base,
+        py::array_t<double> pcarb, double dt, double days, bool checkValues) {
+    bw::Adult P(vec1d(bw), vec1d(ht), vec1d(age), vec1d(sex),
+                mat2d(EIchange), mat2d(NAchange),
+                vec1d(PAL), vec1d(pcarb), vec1d(pcarb_base), dt, checkValues);
+    return adult_result(P.rk4(days));
+}
+
+static py::dict adult_ei(py::array_t<double> bw, py::array_t<double> ht,
+        py::array_t<double> age, py::array_t<double> sex,
+        py::array_t<double> EIchange, py::array_t<double> NAchange,
+        py::array_t<double> PAL, py::array_t<double> pcarb_base,
+        py::array_t<double> pcarb, double dt, py::array_t<double> extradata,
+        double days, bool checkValues, bool isEnergy) {
+    bw::Adult P(vec1d(bw), vec1d(ht), vec1d(age), vec1d(sex),
+                mat2d(EIchange), mat2d(NAchange),
+                vec1d(PAL), vec1d(pcarb), vec1d(pcarb_base), dt,
+                vec1d(extradata), checkValues, isEnergy);
+    return adult_result(P.rk4(days));
+}
+
+static py::dict adult_ei_fat(py::array_t<double> bw, py::array_t<double> ht,
+        py::array_t<double> age, py::array_t<double> sex,
+        py::array_t<double> EIchange, py::array_t<double> NAchange,
+        py::array_t<double> PAL, py::array_t<double> pcarb_base,
+        py::array_t<double> pcarb, double dt, py::array_t<double> input_EI,
+        py::array_t<double> input_fat, double days, bool checkValues) {
+    bw::Adult P(vec1d(bw), vec1d(ht), vec1d(age), vec1d(sex),
+                mat2d(EIchange), mat2d(NAchange),
+                vec1d(PAL), vec1d(pcarb), vec1d(pcarb_base), dt,
+                vec1d(input_EI), vec1d(input_fat), checkValues);
+    return adult_result(P.rk4(days));
+}
+
+static py::dict child_classic(py::array_t<double> age, py::array_t<double> sex,
+        py::array_t<double> FFM, py::array_t<double> FM,
+        py::array_t<double> EIntake, double days, double dt, bool checkValues) {
+    auto b = EIntake.unchecked<2>();
+    std::size_t nr = static_cast<std::size_t>(b.shape(0));
+    std::size_t nc = static_cast<std::size_t>(b.shape(1));
+    std::vector<double> ei(nr * nc);
+    for (std::size_t r = 0; r < nr; ++r)
+        for (std::size_t c = 0; c < nc; ++c) ei[r * nc + c] = b(static_cast<py::ssize_t>(r), static_cast<py::ssize_t>(c));
+    bw::Child P(vec1d(age), vec1d(sex), vec1d(FFM), vec1d(FM), ei, nr, nc, dt, checkValues);
+    return child_result(P.rk4(days - 1));   // days-1: see child_rcpp.cpp
+}
+
+static py::dict child_richardson(py::array_t<double> age, py::array_t<double> sex,
+        py::array_t<double> FFM, py::array_t<double> FM,
+        double K, double Q, double A, double B, double nu, double C,
+        double days, double dt, bool checkValues) {
+    bw::Child P(vec1d(age), vec1d(sex), vec1d(FFM), vec1d(FM), K, Q, A, B, nu, C, dt, checkValues);
+    return child_result(P.rk4(days - 1));
+}
+
+// mass_reference_wrapper: returns {FM, FFM} (mirrors src/child_rcpp.cpp).
+static py::dict mass_reference(py::array_t<double> age, py::array_t<double> sex) {
+    std::vector<double> age_v = vec1d(age), sex_v = vec1d(sex);
+    std::vector<double> ffm(age_v.size(), 0.0), fm(age_v.size(), 0.0);
+    std::vector<double> ei(1, 0.0);
+    bw::Child P(age_v, sex_v, ffm, fm, ei, 1, 1, 1.0, false);
+    py::dict d;
+    d["FM"]  = from_vec(P.FMReference(age_v));
+    d["FFM"] = from_vec(P.FFMReference(age_v));
+    return d;
+}
+
+// intake_reference_wrapper(age, sex, FFM, FM, days, dt) -> (nind, ncols).
+static py::array_t<double> intake_reference(py::array_t<double> age, py::array_t<double> sex,
+        py::array_t<double> FFM, py::array_t<double> FM, double days, double dt) {
+    std::vector<double> age_v = vec1d(age), sex_v = vec1d(sex);
+    std::vector<double> ffm_v = vec1d(FFM), fm_v = vec1d(FM);
+    std::vector<double> ei(1, 0.0);
+    bw::Child P(age_v, sex_v, ffm_v, fm_v, ei, 1, 1, dt, false);
+    std::size_t nind = age_v.size();
+    std::size_t ncols = static_cast<std::size_t>(std::floor(days / dt) + 1);
+    bw::Matrix out(nind, ncols);
+    for (double i = 0; i < std::floor(days / dt) + 1; i += 1.0) {
+        std::vector<double> t(nind);
+        for (std::size_t k = 0; k < nind; ++k) t[k] = age_v[k] + dt * i / 365.0;
+        std::vector<double> col = P.IntakeReference(t);
+        std::size_t ci = static_cast<std::size_t>(i);
+        for (std::size_t k = 0; k < nind; ++k) out(k, ci) = col[k];
+    }
+    return from_mat(out);
+}
+
+// EnergyBuilder: deterministic methods only. Energy is (nrow, ntimes).
+static py::array_t<double> energy_builder(py::array_t<double> Energy,
+        py::array_t<double> Time, const std::string& interpol) {
+    auto e = Energy.unchecked<2>();
+    std::size_t nrow = static_cast<std::size_t>(e.shape(0));
+    std::size_t nt   = static_cast<std::size_t>(e.shape(1));
+    std::vector<double> tvec = vec1d(Time);
+    // build_deterministic expects column-major Energy[r + c*nrow]
+    std::vector<double> ecol(nrow * nt);
+    for (std::size_t r = 0; r < nrow; ++r)
+        for (std::size_t c = 0; c < nt; ++c) ecol[r + c * nrow] = e(static_cast<py::ssize_t>(r), static_cast<py::ssize_t>(c));
+    std::size_t ncols = bw::energy::output_ncols(tvec.data(), tvec.size());
+    std::vector<double> evals(nrow * ncols, 0.0);
+    bw::energy::Method m;
+    if (!bw::energy::parse_method(interpol.c_str(), &m))
+        throw std::invalid_argument("unknown/unsupported interpolation: " + interpol);
+    bw::energy::build_deterministic(ecol.data(), nrow, nt, tvec.data(), m, evals.data());
+    // evals column-major -> (nrow, ncols)
+    bw::Matrix out(nrow, ncols);
+    for (std::size_t r = 0; r < nrow; ++r)
+        for (std::size_t c = 0; c < ncols; ++c) out(r, c) = evals[r + c * nrow];
+    return from_mat(out);
+}
+
+PYBIND11_MODULE(_bw_cpp, m) {
+    m.doc() = "C++ kernel bindings for the bw dynamic body-weight models.";
+    m.def("adult_baseline", &adult_baseline);
+    m.def("adult_ei", &adult_ei);
+    m.def("adult_ei_fat", &adult_ei_fat);
+    m.def("child_classic", &child_classic);
+    m.def("child_richardson", &child_richardson);
+    m.def("mass_reference", &mass_reference);
+    m.def("intake_reference", &intake_reference);
+    m.def("energy_builder", &energy_builder);
+}

hallmodel-2026.6.19.6/bw_cpp/__init__.py

@@ -0,0 +1,137 @@
+"""bw_cpp — Python interface to the bw dynamic body-weight models, backed by the
+pure-C++ kernel (the same kernel the R package compiles).
+
+Python ergonomics, C++ performance, and — built in the pinned toolchain with
+-ffp-contract=off — output bit-identical to the upstream R/C++ results.
+
+This module is a thin orchestration shim mirroring R/adult_weight.R and
+R/child_weight.R: it validates inputs, converts sex to 0/1, fills defaults, and
+dispatches to the compiled kernel in _bw_cpp. All numeric work is in C++.
+"""
+import math
+
+import numpy as np
+
+import _bw_cpp
+
+__all__ = ["adult_weight", "child_weight", "EnergyBuilder",
+           "child_reference_FFMandFM", "child_reference_EI"]
+
+
+def _sex_to_num(sex):
+    """'male'->0, 'female'->1 (accepts scalar/list/array of strings or numbers)."""
+    arr = np.atleast_1d(np.asarray(sex, dtype=object))
+    out = np.zeros(len(arr), dtype=float)
+    for i, s in enumerate(arr):
+        if isinstance(s, str):
+            if s == "female":
+                out[i] = 1.0
+            elif s != "male":
+                raise ValueError(f"Invalid sex '{s}'. Use 'male' or 'female'.")
+        else:
+            out[i] = float(s)
+    return out
+
+
+def _vec(x, n):
+    a = np.atleast_1d(np.asarray(x, dtype=float))
+    if a.size == 1 and n > 1:
+        a = np.full(n, a.item())
+    return np.ascontiguousarray(a, dtype=float)
+
+
+def adult_weight(bw, ht, age, sex, *, EIchange=None, NAchange=None, EI=None,
+                 fat=None, PAL=1.5, pcarb_base=0.5, pcarb=None, days=365, dt=1.0,
+                 check_values=True):
+    """Adult body-weight trajectory. Mirrors R::adult_weight."""
+    bw = _vec(bw, 1); n = bw.size
+    ht = _vec(ht, n); age = _vec(age, n)
+    newsex = _sex_to_num(sex)
+    PAL = _vec(PAL, n); pcarb_base = _vec(pcarb_base, n)
+    pcarb = pcarb_base.copy() if pcarb is None else _vec(pcarb, n)
+
+    ncol = abs(math.ceil(days / dt))
+    EIchange = np.zeros((n, ncol)) if EIchange is None else np.atleast_2d(np.asarray(EIchange, float))
+    NAchange = np.zeros((n, ncol)) if NAchange is None else np.atleast_2d(np.asarray(NAchange, float))
+
+    fat_arr = np.full(n, np.nan) if fat is None else _vec(fat, n)
+    isfat = bool(np.any(np.isnan(fat_arr)))            # True == fat NOT supplied
+    if EI is None:
+        EI_arr = np.full(n, np.nan)
+    else:
+        EI_arr = _vec(EI, n)
+    isEI = bool(np.any(np.isnan(EI_arr)))              # True == EI NOT supplied
+
+    # kernel expects EIchange/NAchange transposed (rows = day, cols = individual)
+    EIc = np.ascontiguousarray(EIchange.T, dtype=float)
+    NAc = np.ascontiguousarray(NAchange.T, dtype=float)
+    cd = float(math.ceil(days))
+
+    if isfat and isEI:
+        res = _bw_cpp.adult_baseline(bw, ht, age, newsex, EIc, NAc, PAL, pcarb_base, pcarb, dt, cd, check_values)
+    elif (not isEI) and isfat:
+        res = _bw_cpp.adult_ei(bw, ht, age, newsex, EIc, NAc, PAL, pcarb_base, pcarb, dt, EI_arr, cd, check_values, True)
+    elif isEI and (not isfat):
+        res = _bw_cpp.adult_ei(bw, ht, age, newsex, EIc, NAc, PAL, pcarb_base, pcarb, dt, fat_arr, cd, check_values, False)
+    else:
+        res = _bw_cpp.adult_ei_fat(bw, ht, age, newsex, EIc, NAc, PAL, pcarb_base, pcarb, dt, EI_arr, fat_arr, cd, check_values)
+
+    if res["Correct_Values"] is False:
+        raise ValueError("One of the variables takes negative/NaN/NA/infinity values")
+    return res
+
+
+def child_reference_FFMandFM(age, sex):
+    """Reference FFM/FM. Mirrors R::child_reference_FFMandFM."""
+    age = _vec(age, 1)
+    return _bw_cpp.mass_reference(age, _sex_to_num(sex))
+
+
+def child_reference_EI(age, sex, FM, FFM, days, dt=1.0):
+    """Default child energy intake. Mirrors R::child_reference_EI.
+
+    NOTE the argument positions: R passes (age, sex, FM, FFM) into a wrapper whose
+    params are (age, sex, FFM, FM) — i.e. FM and FFM occupy swapped slots. We
+    reproduce that exactly, then transpose the result.
+    """
+    age = _vec(age, 1)
+    out = _bw_cpp.intake_reference(age, _sex_to_num(sex),
+                                   np.asarray(FM, float), np.asarray(FFM, float),
+                                   float(days), float(dt))
+    return np.ascontiguousarray(np.asarray(out).T, dtype=float)
+
+
+def child_weight(age, sex, *, FM=None, FFM=None, EI=None, richardson_params=None,
+                 days=365, dt=1.0, check_values=True):
+    """Child weight trajectory. Mirrors R::child_weight."""
+    age = _vec(age, 1); n = age.size
+    newsex = _sex_to_num(sex)
+    if FM is None or FFM is None:
+        ref = child_reference_FFMandFM(age, sex)
+        FM = ref["FM"] if FM is None else _vec(FM, n)
+        FFM = ref["FFM"] if FFM is None else _vec(FFM, n)
+    else:
+        FM = _vec(FM, n); FFM = _vec(FFM, n)
+
+    rp = richardson_params
+    have_rich = rp is not None and all(rp.get(k) is not None for k in ("K", "Q", "A", "B", "nu", "C"))
+
+    if EI is None and not have_rich:
+        EI = child_reference_EI(age, sex, FM, FFM, days, dt)
+
+    if EI is not None:
+        EImat = np.atleast_2d(np.asarray(EI, dtype=float))
+        return _bw_cpp.child_classic(age, newsex, np.asarray(FFM, float), np.asarray(FM, float),
+                                     np.ascontiguousarray(EImat), float(days), float(dt), check_values)
+    return _bw_cpp.child_richardson(age, newsex, np.asarray(FFM, float), np.asarray(FM, float),
+                                    float(rp["K"]), float(rp["Q"]), float(rp["A"]), float(rp["B"]),
+                                    float(rp["nu"]), float(rp["C"]), float(days), float(dt), check_values)
+
+
+class EnergyBuilder:
+    """Energy-intake interpolation (deterministic methods), backed by C++."""
+
+    def build(self, energy, time, method="Linear"):
+        energy = np.atleast_2d(np.asarray(energy, dtype=float))
+        time = np.ascontiguousarray(np.asarray(time, dtype=float))
+        return _bw_cpp.energy_builder(np.ascontiguousarray(energy), time, str(method))