Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions .github/workflows/wheels.yml
Original file line number Diff line number Diff line change
@@ -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
47 changes: 47 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -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<value>[0-9][0-9.]*)'

[tool.pytest.ini_options]
testpaths = ["python/tests"]
56 changes: 56 additions & 0 deletions python/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -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.<ext> 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)
63 changes: 63 additions & 0 deletions python/README.md
Original file line number Diff line number Diff line change
@@ -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
```
16 changes: 16 additions & 0 deletions python/nfdrs4/__init__.py
Original file line number Diff line number Diff line change
@@ -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"
24 changes: 24 additions & 0 deletions python/tests/test_nfdrs4.py
Original file line number Diff line number Diff line change
@@ -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()
Loading