diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml new file mode 100644 index 0000000..5450572 --- /dev/null +++ b/.github/workflows/wheels.yml @@ -0,0 +1,54 @@ +name: Python wheels + +on: + push: + tags: ["v*"] + pull_request: + paths: ["lib/**", "swig/nfdrs4.i", "python/**", "pyproject.toml"] + workflow_dispatch: + +jobs: + wheels: + name: Wheels on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest] + steps: + - uses: actions/checkout@v4 + - uses: pypa/cibuildwheel@v2.23 + env: + CIBW_SKIP: "pp* *-musllinux_* *-win32 *_i686" + CIBW_TEST_EXTRAS: test + CIBW_TEST_COMMAND: pytest {project}/python/tests + - uses: actions/upload-artifact@v4 + with: + name: wheels-${{ matrix.os }} + path: wheelhouse/*.whl + + sdist: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: pipx run build --sdist + - uses: actions/upload-artifact@v4 + with: + name: sdist + path: dist/*.tar.gz + + # Publishes to PyPI on version tags. Requires a "pypi" environment and + # trusted publishing set up for this repo on pypi.org. + publish: + if: startsWith(github.ref, 'refs/tags/v') + needs: [wheels, sdist] + runs-on: ubuntu-latest + environment: pypi + permissions: + id-token: write + steps: + - uses: actions/download-artifact@v4 + with: + path: dist + merge-multiple: true + - uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..8815a97 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,47 @@ +[build-system] +requires = ["scikit-build-core>=0.10", "swig>=4.0"] +build-backend = "scikit_build_core.build" + +[project] +name = "nfdrs4" +dynamic = ["version"] +description = "Python bindings for the US National Fire Danger Rating System version 4 (NFDRS4)" +readme = "python/README.md" +requires-python = ">=3.9" +license = { text = "Public Domain" } +authors = [{ name = "USDA Forest Service, Missoula Fire Sciences Laboratory" }] +keywords = ["fire danger", "NFDRS", "fuel moisture", "wildland fire"] +classifiers = [ + "Programming Language :: Python :: 3", + "Programming Language :: C++", + "License :: Public Domain", + "Operating System :: OS Independent", + "Topic :: Scientific/Engineering :: Atmospheric Science", +] + +[project.urls] +Homepage = "https://github.com/firelab/NFDRS4" +Documentation = "https://doi.org/10.1016/j.envsoft.2024.106181" + +[project.optional-dependencies] +test = ["pytest"] + +[tool.scikit-build] +# Build only the Python extension (python/CMakeLists.txt). The top-level +# CMakeLists.txt also builds the CLI, which needs config4cpp and isn't +# required for the bindings. +cmake.source-dir = "python" +cmake.build-type = "Release" +wheel.packages = ["python/nfdrs4"] +install.components = ["python"] +sdist.include = ["/lib/", "/swig/nfdrs4.i", "/python/", "/CMakeLists.txt"] +sdist.exclude = ["__pycache__/", "*.pyc", ".git*", "docs/", ".readthedocs.yaml", "app/", "extern/", "data/", "doc/", "swig/nfdrs4_wrap.cxx", "swig/nfdrs4.py"] + +[tool.scikit-build.metadata.version] +# Single source of truth: the VERSION in the top-level CMakeLists.txt +provider = "scikit_build_core.metadata.regex" +input = "CMakeLists.txt" +regex = 'project\s*\([^)]*?VERSION\s+(?P[0-9][0-9.]*)' + +[tool.pytest.ini_options] +testpaths = ["python/tests"] diff --git a/python/CMakeLists.txt b/python/CMakeLists.txt new file mode 100644 index 0000000..5cecba9 --- /dev/null +++ b/python/CMakeLists.txt @@ -0,0 +1,56 @@ +# Builds the nfdrs4 Python extension. Driven by scikit-build-core via the +# top-level pyproject.toml: pip install . +cmake_minimum_required(VERSION 3.18) +project(nfdrs4_python LANGUAGES C CXX) + +set(CMAKE_CXX_STANDARD 14) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_POSITION_INDEPENDENT_CODE ON) # static libs end up in a shared module + +set(NFDRS4_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/..) + +# Reuse the upstream library targets (NFDRS4 -> utctime -> time64) +add_subdirectory(${NFDRS4_ROOT}/lib/time64 ${CMAKE_BINARY_DIR}/time64) +add_subdirectory(${NFDRS4_ROOT}/lib/utctime ${CMAKE_BINARY_DIR}/utctime) +add_subdirectory(${NFDRS4_ROOT}/lib/NFDRS4 ${CMAKE_BINARY_DIR}/NFDRS4) + +find_package(Python REQUIRED COMPONENTS Interpreter Development.Module) +find_package(SWIG 4.0 REQUIRED COMPONENTS python) +include(UseSWIG) + +# Use the upstream interface file unchanged. Its #include lines are written +# relative to swig/ ("../lib/..."), so swig/ goes on both include paths. +set(NFDRS4_I ${NFDRS4_ROOT}/swig/nfdrs4.i) +set_property(SOURCE ${NFDRS4_I} PROPERTY CPLUSPLUS ON) +set_property(SOURCE ${NFDRS4_I} PROPERTY INCLUDE_DIRECTORIES ${NFDRS4_ROOT}/swig) + +swig_add_library(nfdrs4_py + TYPE MODULE + LANGUAGE python + OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/py + OUTFILE_DIR ${CMAKE_CURRENT_BINARY_DIR}/cxx + SOURCES ${NFDRS4_I}) + +# Module file must be _nfdrs4. to match "%module nfdrs4" in the .i file +set_target_properties(nfdrs4_py PROPERTIES PREFIX "" OUTPUT_NAME _nfdrs4) +target_include_directories(nfdrs4_py PRIVATE ${NFDRS4_ROOT}/swig) +target_link_libraries(nfdrs4_py PRIVATE NFDRS4 Python::Module) +if(MSVC) + target_compile_options(nfdrs4_py PRIVATE /bigobj) +endif() + +# Optional: honour the "#pragma omp" sections in nfdrs4.cpp. +# Off by default so wheels don't need an OpenMP runtime. +option(NFDRS4_OPENMP "Build with OpenMP" OFF) +if(NFDRS4_OPENMP) + find_package(OpenMP REQUIRED COMPONENTS CXX) + target_link_libraries(NFDRS4 PUBLIC OpenMP::OpenMP_CXX) +endif() + +# Install the compiled module and the SWIG-generated proxy into the package. +# Uses its own component so the upstream header install() rules in lib/ are +# not dumped into site-packages (see install.components in pyproject.toml). +install(TARGETS nfdrs4_py + LIBRARY DESTINATION nfdrs4 COMPONENT python + RUNTIME DESTINATION nfdrs4 COMPONENT python) +install(FILES ${CMAKE_CURRENT_BINARY_DIR}/py/nfdrs4.py DESTINATION nfdrs4 COMPONENT python) diff --git a/python/README.md b/python/README.md new file mode 100644 index 0000000..5016d89 --- /dev/null +++ b/python/README.md @@ -0,0 +1,63 @@ +# nfdrs4 (Python) + +Python bindings for the US National Fire Danger Rating System version 4 (NFDRS4): +the Nelson dead fuel moisture model, the GSI-based live fuel moisture model, and +the NFDRS4 index calculator. The bindings are generated with SWIG from the C++ +sources in this repository. + +Model documentation: Jolly et al. (2024), *Modernizing the US National Fire Danger +Rating System (version 4)*, Environmental Modelling & Software, +https://doi.org/10.1016/j.envsoft.2024.106181 + +## Install + +From GitHub: + +```bash +pip install git+https://github.com/firelab/NFDRS4 +``` + +From a local clone: + +```bash +pip install . # or, for development: pip install -e . +``` + +The only thing you need on your machine is a C++ compiler (gcc/clang on +Linux/macOS, Visual Studio Build Tools on Windows). SWIG and CMake are +downloaded from PyPI automatically during the build. You don't need conda. + +To compile with the OpenMP sections in `nfdrs4.cpp` enabled: + +```bash +pip install . -C cmake.define.NFDRS4_OPENMP=ON +``` + +## Use + +```python +import nfdrs4 + +dfm = nfdrs4.DeadFuelMoisture.createDeadFuelMoisture1() +dfm.update(1, 1, 1, 1, 1) +dfm.medianRadialMoisture() # 0.5606... + +calc = nfdrs4.NFDRS4() +``` + +## Build wheels + +```bash +python -m build # sdist + wheel for the current Python +``` + +`.github/workflows/wheels.yml` uses [cibuildwheel](https://cibuildwheel.pypa.io) +to build wheels for Linux, macOS and Windows. Pushing a `v*` tag publishes them to +PyPI (this needs trusted publishing set up for the repo on pypi.org). + +## Test + +```bash +pip install .[test] +pytest +``` diff --git a/python/nfdrs4/__init__.py b/python/nfdrs4/__init__.py new file mode 100644 index 0000000..4b839c8 --- /dev/null +++ b/python/nfdrs4/__init__.py @@ -0,0 +1,16 @@ +"""Python bindings for the US National Fire Danger Rating System version 4. + +The classes are generated by SWIG from the C++ library, e.g.:: + + import nfdrs4 + dfm = nfdrs4.DeadFuelMoisture.createDeadFuelMoisture1() + calc = nfdrs4.NFDRS4() +""" +from importlib import metadata as _metadata + +from .nfdrs4 import * # noqa: F401,F403 (SWIG-generated proxy module) + +try: + __version__ = _metadata.version("nfdrs4") +except _metadata.PackageNotFoundError: # pragma: no cover + __version__ = "unknown" diff --git a/python/tests/test_nfdrs4.py b/python/tests/test_nfdrs4.py new file mode 100644 index 0000000..235d2c9 --- /dev/null +++ b/python/tests/test_nfdrs4.py @@ -0,0 +1,24 @@ +import math + +import nfdrs4 + + +def test_version(): + assert nfdrs4.__version__ not in ("", "unknown") + + +def test_dead_fuel_moisture_readme_example(): + # Values from swig/Readme.md + dfm = nfdrs4.DeadFuelMoisture.createDeadFuelMoisture1() + assert dfm.update(1, 1, 1, 1, 1) + assert math.isclose(dfm.medianRadialMoisture(), 0.5606049792805294, rel_tol=1e-9) + dfm.setAdsorptionRate(0.4) + assert dfm.diffusivitySteps() == 25 + assert dfm.deriveStickNodes(0.3) == 11 + + +def test_core_classes_exposed(): + for name in ("NFDRS4", "DeadFuelMoisture", "LiveFuelMoisture", + "NFDRS4State", "DFMCalcState", "LFMCalcState"): + assert hasattr(nfdrs4, name), name + nfdrs4.NFDRS4()