Development and release¶
Layout¶
| path | role |
|---|---|
functions.toml |
the inventory: every public function, its parameters, defaults, flags, dispatch and C symbol |
tools/regen.py |
generates src/_ufuncs_generated.c, accudist/_api.py, accudist/rmath.py, docs/api-reference.md from the inventory and validates every C call against Rmath.h |
tools/check_inventory.py |
every symbol in Rmath.h is a function, bespoke wrapper, RNG primitive or documented exclusion |
vendor/nmath/ |
R 4.5.2 src/nmath + headers, pristine except for vendor/patches/ |
tools/sync_rmath.py |
downloads the pinned R tarball (vendor/VENDOR.toml), verifies its SHA-256, extracts, applies the patches |
src/accudist_shim.{h,c} |
thread-local error word and message buffer, calloc hook |
src/_ufuncsmodule.c |
module init, RNG state, bespoke entry points |
accudist/_core.py, _errstate.py, _bespoke.py |
hand-written Python helpers |
accudist/compat/ |
the scipy-shaped shim (imports only the public API) |
tools/grids.py, tools/gen_reference.{py,R} |
designed evaluation grids and the R reference generator |
tests/data/*.json |
R 4.5.2 reference values (decimal, 17 significant digits) |
tests/reference_tolerances.py |
the documented regions with relaxed tolerance |
Workflow¶
uv venv && source .venv/bin/activate
uv pip install setuptools numpy pytest hypothesis scipy mpmath
uv pip install --no-build-isolation -e .
python tools/regen.py --check # generated files are up to date
python tools/check_inventory.py # Rmath.h fully accounted for
pytest -q # offline; ~330 tests, a few seconds
pytest -q -m "not slow" # skip the thread stress test
Generated files are committed so that building from the sdist needs no tooling beyond a C compiler. CI fails if they are stale.
Adding or changing a function¶
- Edit
functions.toml(public parameter order inparams, C order inc_args). python tools/regen.py(fails if the C arity disagrees withRmath.h).- Add a grid in
tools/grids.pyif needed and runpython tools/gen_reference.py <name>(needs R 4.5.2 onPATH). pytest -q -k <name>.
Bumping R¶
- Update version, URL and SHA-256 in
vendor/VENDOR.toml. python tools/sync_rmath.py; fix any patch that no longer applies (never editvendor/nmath/in place).python tools/check_inventory.pyfor new or removed symbols.- Under the new R:
python tools/gen_reference.py. Any changed reference value is a finding; investigate before committing. - Record it in
CHANGELOG.md.
Build flags¶
| flag | why |
|---|---|
-DMATHLIB_STANDALONE -DHAVE_CONFIG_H |
nmath's standalone mode with our src/config.h |
-ffp-contract=off |
no fused multiply-add, so results do not depend on the CPU |
-fvisibility=hidden |
only PyInit__ufuncs is exported; nmath's plain C names cannot collide with another Rmath in the process |
-O2, never -ffast-math |
nmath relies on IEEE Inf/NaN semantics |
Documentation site¶
The site is published by hand from a checkout of main:
uv pip install mkdocs-material
mkdocs build --strict # catches broken links; CI runs this on every push
mkdocs gh-deploy # builds and pushes to the gh-pages branch
GitHub Pages must be configured to serve from the gh-pages branch.
Release¶
Wheels are built by .github/workflows/wheels.yml with cibuildwheel for CPython
3.10 to 3.14 on manylinux x86_64/aarch64, macOS x86_64/arm64 and Windows AMD64,
tested in a clean environment, and published to PyPI through trusted publishing
(no API token in the repository) when a v* tag is pushed. The sdist is built
and installed offline in the same workflow.
- Update
versioninpyproject.tomlandCHANGELOG.md. git tag v0.1.0 && git push --tags.- The
pypienvironment on GitHub must be configured as a trusted publisher on PyPI for the workflow to publish.
Versioning: MAJOR.MINOR.PATCH; accudist.__r_version__ reports the vendored R.
An R bump that changes any reference value is at least a minor release.