lwbgt 0.3.0__tar.gz

lwbgt-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: ci
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            cc: gcc
+          - os: macos-15-intel
+            cc: clang
+          - os: windows-latest
+            cc: gcc
+    runs-on: ${{ matrix.os }}
+    env:
+      CC: ${{ matrix.cc }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.10'
+      - name: Check version coherence
+        run: python tests/check_versions.py
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: '4.3'
+          windows-path-include-mingw: true
+      - uses: julia-actions/setup-julia@v3
+        with:
+          version: '1.10'
+      - name: Configure
+        run: >-
+          cmake -S . -B build -G Ninja
+          -DCMAKE_BUILD_TYPE=Release
+          -DLWBGT_REQUIRE_ALL_BINDING_TESTS=ON
+      - name: Build
+        run: cmake --build build --parallel
+      - name: Test
+        run: ctest --test-dir build --output-on-failure

lwbgt-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,177 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  release-tag:
+    name: Verify annotated release tag
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Require an annotated tag object
+        run: test "$(git cat-file -t "$GITHUB_REF_NAME")" = tag
+
+  artifacts:
+    needs: release-tag
+    uses: ./.github/workflows/wheels.yml
+
+  testpypi-publish:
+    name: Publish verified artifacts to TestPyPI
+    needs: artifacts
+    runs-on: ubuntu-24.04
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/lwbgt/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: dist-*
+          path: dist
+          merge-multiple: true
+      - name: Require the complete release matrix
+        run: |
+          test "$(find dist -maxdepth 1 -type f -name '*.whl' | wc -l)" -eq 5
+          test "$(find dist -maxdepth 1 -type f -name '*.tar.gz' | wc -l)" -eq 1
+      - name: Publish through TestPyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  testpypi-smoke:
+    name: Verify TestPyPI artifact identity and installation
+    needs: testpypi-publish
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.10'
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: dist-*
+          path: dist
+          merge-multiple: true
+      - name: Download the release wheel from TestPyPI
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          mkdir testpypi
+          for attempt in $(seq 1 12); do
+            if python -m pip download \
+              --index-url https://test.pypi.org/simple/ \
+              --only-binary=:all: --no-cache-dir --no-deps \
+              --dest testpypi "lwbgt==$version"; then
+              break
+            fi
+            if test "$attempt" -eq 12; then
+              exit 1
+            fi
+            sleep 10
+          done
+      - name: Match the complete tested artifact set byte-for-byte
+        run: |
+          python - <<'PY'
+          import hashlib
+          import json
+          import os
+          import time
+          from pathlib import Path
+          from urllib.request import urlopen
+
+          version = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          expected = {
+              path.name: hashlib.sha256(path.read_bytes()).hexdigest()
+              for path in Path("dist").iterdir()
+              if path.is_file()
+          }
+          release_url = f"https://test.pypi.org/pypi/lwbgt/{version}/json"
+          published = {}
+          for attempt in range(12):
+              try:
+                  with urlopen(release_url) as response:
+                      release = json.load(response)
+                  published = {
+                      item["filename"]: item["digests"]["sha256"]
+                      for item in release["urls"]
+                  }
+              except OSError:
+                  published = {}
+              if published == expected:
+                  break
+              if attempt != 11:
+                  time.sleep(10)
+          else:
+              raise SystemExit(
+                  f"TestPyPI release differs: published={published}, expected={expected}"
+              )
+
+          downloaded = list(Path("testpypi").glob("*.whl"))
+          if len(downloaded) != 1:
+              raise SystemExit(f"expected one TestPyPI wheel, got {downloaded}")
+          expected_wheel = Path("dist", downloaded[0].name)
+          if not expected_wheel.is_file():
+              raise SystemExit(f"TestPyPI returned an unexpected artifact: {downloaded[0].name}")
+          actual_hash = hashlib.sha256(downloaded[0].read_bytes()).hexdigest()
+          expected_hash = hashlib.sha256(expected_wheel.read_bytes()).hexdigest()
+          if actual_hash != expected_hash:
+              raise SystemExit(
+                  f"TestPyPI artifact hash mismatch: {actual_hash} != {expected_hash}"
+              )
+          print(f"TestPyPI release identity: {len(expected)} artifacts: ok")
+          print(f"TestPyPI wheel download: {downloaded[0].name}: {actual_hash}")
+          PY
+      - name: Test the wheel retrieved from TestPyPI
+        run: |
+          python -m venv testpypi-test
+          testpypi-test/bin/python -m pip install --no-index testpypi/*.whl
+          testpypi-test/bin/python -m unittest discover -s tests/python -v
+
+  publish:
+    name: Publish verified artifacts to PyPI
+    needs: [artifacts, testpypi-smoke]
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lwbgt
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: dist-*
+          path: dist
+          merge-multiple: true
+      - name: Require the complete release matrix
+        run: |
+          test "$(find dist -maxdepth 1 -type f -name '*.whl' | wc -l)" -eq 5
+          test "$(find dist -maxdepth 1 -type f -name '*.tar.gz' | wc -l)" -eq 1
+      - name: Publish through PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub release
+    needs: publish
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: dist-*
+          path: dist
+          merge-multiple: true
+      - name: Create release for the existing annotated tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --verify-tag --generate-notes

lwbgt-0.3.0/.github/workflows/wheels.yml

@@ -0,0 +1,140 @@
+name: wheels
+
+on:
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  build-wheels:
+    name: ${{ matrix.artifact }} wheel
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-24.04
+            artifact: linux-x86_64
+            arch: x86_64
+            platform: linux
+          - runner: ubuntu-24.04-arm
+            artifact: linux-aarch64
+            arch: aarch64
+            platform: linux
+          - runner: macos-15-intel
+            artifact: macos-x86_64
+            arch: x86_64
+            platform: macos
+          - runner: macos-15
+            artifact: macos-arm64
+            arch: arm64
+            platform: macos
+          - runner: windows-2025
+            artifact: windows-amd64
+            arch: AMD64
+            platform: windows
+    runs-on: ${{ matrix.runner }}
+    env:
+      CIBW_BUILD: cp310-*
+      CIBW_SKIP: '*-musllinux_*'
+      CIBW_ARCHS: ${{ matrix.arch }}
+      CIBW_TEST_COMMAND: python -m unittest discover -s {project}/tests/python -v
+      CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: >-
+        delvewheel repair --analyze-existing --exclude ucrtbase.dll
+        -w {dest_dir} -v {wheel}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+      - name: Provision standalone MinGW GCC
+        if: matrix.platform == 'windows'
+        id: mingw
+        uses: egor-tensin/setup-mingw@v3
+        with:
+          platform: x64
+          version: 12.2.0
+      - name: Select MinGW compiler
+        if: matrix.platform == 'windows'
+        shell: pwsh
+        run: |
+          "CC=${{ steps.mingw.outputs.gcc }}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          "CMAKE_GENERATOR=Ninja" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+      - name: Check version coherence
+        run: python tests/check_versions.py
+      - name: Build, repair, and test wheel
+        uses: pypa/cibuildwheel@v4.1.1
+      - name: Inspect wheel contents
+        run: python tests/check_distribution.py "wheelhouse/*.whl"
+      - name: Inspect Linux dependencies
+        if: matrix.platform == 'linux'
+        run: |
+          python -m pip install auditwheel
+          for wheel in wheelhouse/*.whl; do
+            auditwheel show "$wheel"
+          done
+      - name: Inspect macOS dependencies
+        if: matrix.platform == 'macos'
+        run: python -m pip install delocate && delocate-listdeps wheelhouse/*.whl
+      - name: Inspect Windows dependencies
+        if: matrix.platform == 'windows'
+        run: python -m pip install delvewheel && delvewheel show --analyze-existing wheelhouse\*.whl
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist-${{ matrix.artifact }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  build-sdist:
+    name: source distribution
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+      - name: Check version coherence
+        run: python tests/check_versions.py
+      - name: Build source distribution
+        run: |
+          python -m pip install build twine
+          python -m build --sdist
+          python tests/check_distribution.py "dist/*.tar.gz"
+          python -m twine check dist/*
+      - name: Rebuild wheel from source distribution
+        run: |
+          python -m pip wheel --no-deps --wheel-dir sdist-wheel dist/*.tar.gz
+          python tests/check_distribution.py "sdist-wheel/*.whl"
+      - name: Test source-built wheel in a clean environment
+        run: |
+          python -m venv sdist-test
+          sdist-test/bin/python -m pip install --no-index sdist-wheel/*.whl
+          sdist-test/bin/python -m unittest discover -s tests/python -v
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  python-compatibility:
+    name: Linux wheel on Python ${{ matrix.python }}
+    needs: build-wheels
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.x']
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist-linux-x86_64
+          path: dist
+      - name: Install the same ABI-independent wheel
+        run: |
+          python -m pip install --no-index dist/*.whl
+          python -m unittest discover -s tests/python -v

lwbgt-0.3.0/.gitignore

@@ -0,0 +1,9 @@
+/build/
+/build-gcc16/
+/build-profile/
+__pycache__/
+*.py[cod]
+/dist/
+/wheelhouse/
+/sdist-wheel/
+/sdist-test/

lwbgt-0.3.0/ABI.md

@@ -0,0 +1,136 @@
+# ABI contract
+
+This document defines the supported binary interface for lwbgt. Public symbols
+and layouts described here are compatibility commitments; other link-visible
+symbols in the static archive are implementation details.
+
+## Versioning
+
+The project release version and FFI ABI version are independent:
+
+- `LWBGT_VERSION_MAJOR`, `LWBGT_VERSION_MINOR`, and `LWBGT_VERSION_PATCH`
+  identify the project release.
+- `LWBGT_FFI_ABI_VERSION` identifies the versioned structure and batch API.
+- The `calc_wbgt` and `esat` scalar symbols retain the original compatibility
+  ABI.
+- The `lwbgt_input_v1`, `lwbgt_output_v1`, and `lwbgt_calc_batch_v1` names are
+  permanent. Incompatible layouts or behavior require new `v2` names while the
+  v1 entry point remains available.
+
+New symbols and backward-compatible documentation clarifications may be added
+without changing the v1 ABI. Fields must not be reordered, resized, removed, or
+repurposed.
+
+## Data model and layout
+
+The v1 ABI requires 8-bit bytes, 32-bit `int32_t` and `float`, 64-bit `double`,
+and the field offsets below. Supported release builds enforce the total sizes
+and boundary offsets with compile-time assertions.
+
+### `lwbgt_input_v1`
+
+Total size: 104 bytes. Integer fields occupy the first 32 bytes; every floating
+point input is an ABI-boundary `double`.
+
+| Offset | Field | Type | Units and meaning |
+|---:|---|---|---|
+| 0 | `year` | `int32_t` | Four-digit Gregorian year |
+| 4 | `month` | `int32_t` | Month 1–12; 0 means `day` is day-of-year |
+| 8 | `day` | `int32_t` | Day of month, or day-of-year when `month == 0` |
+| 12 | `hour` | `int32_t` | Local standard-time hour, 0–23 |
+| 16 | `minute` | `int32_t` | Minutes past the hour |
+| 20 | `gmt_offset_hours` | `int32_t` | Local standard time minus GMT, in hours |
+| 24 | `averaging_minutes` | `int32_t` | Input averaging interval in minutes |
+| 28 | `urban` | `int32_t` | 0 selects rural; 1 selects urban wind scaling |
+| 32 | `latitude_deg_north` | `double` | Degrees north; south is negative |
+| 40 | `longitude_deg_east` | `double` | Degrees east; west is negative |
+| 48 | `solar_w_m2` | `double` | Solar irradiance, W/m² |
+| 56 | `pressure_hpa` | `double` | Barometric pressure, hPa (equivalent to mb) |
+| 64 | `air_temperature_c` | `double` | Dry-bulb air temperature, °C |
+| 72 | `relative_humidity_percent` | `double` | Relative humidity, percent |
+| 80 | `wind_speed_m_s` | `double` | Wind speed, m/s |
+| 88 | `wind_height_m` | `double` | Wind measurement height, m |
+| 96 | `vertical_temperature_difference_c` | `double` | Upper-minus-lower temperature difference, °C |
+
+### `lwbgt_output_v1`
+
+Total size: 24 bytes.
+
+| Offset | Field | Type | Meaning |
+|---:|---|---|---|
+| 0 | `status` | `int32_t` | Per-record scalar solver status |
+| 4 | `estimated_wind_speed_m_s` | `float` | Effective wind speed at 2 m, m/s |
+| 8 | `globe_temperature_c` | `float` | Globe temperature, °C |
+| 12 | `natural_wet_bulb_c` | `float` | Natural wet-bulb temperature, °C |
+| 16 | `psychrometric_wet_bulb_c` | `float` | Psychrometric wet-bulb temperature, °C |
+| 20 | `wbgt_c` | `float` | Outdoor wet-bulb globe temperature, °C |
+
+## Batch call contract
+
+```c
+int lwbgt_calc_batch_v1(
+    const lwbgt_input_v1 *inputs,
+    lwbgt_output_v1 *outputs,
+    size_t count
+);
+```
+
+- `count == 0` returns `LWBGT_BATCH_OK`; either pointer may be null.
+- For nonzero `count`, a null pointer returns
+  `LWBGT_BATCH_INVALID_ARGUMENT` without modifying outputs.
+- The caller owns both arrays and must provide at least `count` elements. The
+  input and output storage must not overlap.
+- Records execute serially, in ascending array order, by calling the scalar
+  implementation once per record.
+- The function return value reports call validity. Each output `status` reports
+  that record's scalar solver result: 0 for success and -1 for failure to
+  converge. A failed record uses the upstream `-9999` result convention.
+- Inputs are forwarded without domain validation, clamping, unit conversion, or
+  missing-value policy beyond behavior already present in the scalar model.
+- When wind is already measured at 2 m, the batch API returns the supplied wind
+  as `estimated_wind_speed_m_s`. This makes the batch result deterministic; the
+  legacy scalar function instead leaves that output pointer untouched when no
+  estimation is performed.
+
+## Scalar ABI
+
+The declarations in `lwbgt.h` are authoritative. Scalar floating-point inputs
+to `calc_wbgt` use `double` at the ABI boundary because the original K&R
+`float` parameters undergo default argument promotion. Output pointers remain
+`float *`.
+
+`esat` accepts temperature in kelvin. `phase == 0` computes saturation over
+liquid water; `phase == 1` computes saturation over ice. Other phase values are
+outside the supported contract.
+
+## Concurrency and ownership
+
+The implementation has no mutable shared calculation state. Independent scalar
+or batch calls are thread-safe when callers use separate output buffers. A
+single batch call is serial and does not create threads. The API retains no
+input or output pointers after return and performs no allocation.
+
+## Symbols and platforms
+
+The shared library exports only:
+
+```text
+calc_wbgt
+esat
+lwbgt_calc_batch_v1
+```
+
+The release CI validates Linux with GCC, macOS with AppleClang, and Windows with
+MinGW GCC. MSVC is unsupported because it cannot compile the preserved GNU89
+numerical source. The public header is valid C and C++ and is tested through
+installed C and C++ consumers.
+
+## Official Python binding
+
+The `lwbgt` Python distribution loads its bundled unversioned runtime through
+`importlib.resources` and `ctypes`. Its public `Input` and `Result` records map
+field-for-field to the v1 structures above. `calculate` and `calculate_batch`
+both use `lwbgt_calc_batch_v1`; the latter submits the entire iterable in one
+native call. `esat` directly exposes the scalar symbol. The binding performs no
+unit conversion, domain validation, clamping, missing-data handling, or solver
+failure substitution.

lwbgt-0.3.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## v0.3.0 — 2026-08-19
+
+- Added the official dependency-free Python API: immutable `Input` and `Result`
+  records plus `calculate`, `calculate_batch`, and `esat`.
+- Added an unversioned, wheel-only shared target built from the existing native
+  objects with the same restricted three-symbol export surface.
+- Added platform-specific, Python-ABI-independent wheel and rebuildable sdist
+  packaging through scikit-build-core.
+- Added installed-wheel ABI layout, resource loading, scalar, batch, failure,
+  `esat`, deterministic fixture, archive licensing, and version-coherence tests.
+- Added cibuildwheel coverage for manylinux x86_64/aarch64, macOS x86_64/arm64,
+  and Windows amd64, plus OIDC Trusted Publishing release automation.
+
+## v0.2.1 — 2026-08-18
+
+- Licensed project-authored files under Apache-2.0 while preserving the
+  Liljegren-derived numerical files under their UChicago Argonne terms.
+- Added the authoritative v1 ABI contract covering layouts, units, status and
+  ownership semantics, concurrency, symbols, and compatibility policy.
+- Added an installed C++ consumer that validates public-header compatibility,
+  structure sizes and offsets, and shared-library linkage.
+
+## v0.2.0 — 2026-08-18
+
+- Added the fixed-layout `lwbgt_input_v1` and `lwbgt_output_v1` structures and
+  serial `lwbgt_calc_batch_v1` FFI entry point without changing the scalar ABI.
+- Added versioned shared-library builds with a three-symbol dynamic export
+  surface while retaining the existing static archive.
+- Added dependency-light Python, R, and Julia examples and made them release
+  gates on Linux/GCC, macOS/Clang, and Windows/MinGW CI.
+- Added relocatable CMake and `pkg-config` installation metadata.
+- Verified the final static and shared artifacts on Linux/GCC,
+  macOS/AppleClang, and Windows/MinGW, including installed consumers and all
+  three language examples.
+- Revalidated the position-independent static build at 1.249× overall median
+  throughput with exact compatibility and all release gates passing.
+
+## v0.1.0 — 2026-08-18
+
+The release gate passes with 1.316× median single-thread throughput on GCC
+13.3.0 and 1.289× on GCC 16.2.0. All 454 compatibility cases remain
+bit-identical and every benchmark cohort exceeds 1.25×.
+
+- Pinned Liljegren WBGT v1.1 commit
+  `cd672a886880b67f3f27bdbf75038d8f7ff0bac2` and source blob
+  `7bc6e6ddd76a538d6454b27e9b252667846e6c9b`.
+- Added static `liblwbgt.a` and the permanent `calc_wbgt`/`esat` compatibility
+  declarations in `lwbgt.h`.
+- Skipped radiative work that was multiplied by zero in the psychrometric
+  wet-bulb solve.
+- Reused rounded air viscosity in cylinder and sphere convective coefficients.
+- Hoisted invariant atmospheric, surface, and solar radiation terms from the
+  iterative globe and natural wet-bulb solves after profiling identified both
+  solves as the remaining hot paths.
+- Proved exact output equality with GCC 13.3.0 and GCC 16.2.0.
+- Proved that all three existing HeatStressBench C adapters compile unchanged
+  and produce byte-identical generated, decomposition, NASA POWER sample, and
+  ERA5 sample results when only the link input changes.
+- Audited the static archive export surface and fixed the permanent supported
+  API at `calc_wbgt` and `esat`; inherited helper exports remain implementation
+  details.

lwbgt-0.3.0/CITATION.cff

@@ -0,0 +1,42 @@
+cff-version: 1.2.0
+message: "If you use lwbgt, please cite this software and the underlying Liljegren method."
+title: "lwbgt"
+type: software
+abstract: "A stable low-level C/FFI computational kernel for Liljegren outdoor WBGT, derived from the Liljegren WBGT v1.1 C implementation."
+authors:
+  - family-names: "Zheng"
+    given-names: "Yifei"
+    orcid: "https://orcid.org/0009-0001-4858-2025"
+version: 0.3.0
+date-released: 2026-08-19
+repository-code: "https://github.com/zyf0717/lwbgt"
+url: "https://github.com/zyf0717/lwbgt"
+license-url: "https://github.com/zyf0717/lwbgt/blob/main/LICENSING.md"
+keywords:
+  - WBGT
+  - Liljegren
+  - heat stress
+  - C
+  - FFI
+  - Python
+references:
+  - type: article
+    authors:
+      - family-names: "Liljegren"
+        given-names: "James C."
+      - family-names: "Carhart"
+        given-names: "Richard A."
+      - family-names: "Lawday"
+        given-names: "Philip"
+      - family-names: "Tschopp"
+        given-names: "Stephen"
+      - family-names: "Sharp"
+        given-names: "Robert"
+    title: "Modeling the Wet Bulb Globe Temperature Using Standard Meteorological Measurements"
+    journal: "Journal of Occupational and Environmental Hygiene"
+    year: 2008
+    volume: 5
+    issue: 10
+    start: 645
+    end: 655
+    doi: "10.1080/15459620802310770"