ptfkit is a specification-driven collection of pedotransfer functions (PTFs) for estimating soil hydraulic properties.
A PTF is an empirical model that predicts a soil property from measurements that are generally easier, faster, or less expensive to obtain directly. Common inputs include particle-size fractions, bulk density, and organic matter content; predicted properties include soil water-retention characteristics and hydraulic conductivity.
ptfkit makes selected PTFs from soil-science publications available through consistent interfaces in several programming languages. It is intended for soil scientists, hydrologists, environmental modellers, agronomists, students, and software developers who need traceable implementations of published soil models.
The documentation provides a catalogue of source publications and API references for the supported targets.
Every PTF in ptfkit starts with its original scientific publication. The
equations and the information needed to interpret them are transcribed into a
reviewed YAML specification under specs/functions.
Each specification records the source citation, variable definitions, units,
calibration scope, equations, numerical examples, notes, and warnings.
The specifications are the target-independent source of truth. The generator
under codegen validates them, compiles their equations into a
shared semantic model, and generates the language implementations, tests, PTF
catalogue, and API reference pages. Generated artifacts are committed to the
repository, but changes to a PTF are made in its specification or in the
generator rather than in generated files.
This workflow keeps the scientific description, public interfaces, numerical tests, and documentation aligned across targets. A source specification may also document a PTF that is not implemented yet; its status in the PTF catalogue indicates whether it is available for generation and use.
See the PTF source specification guide for the scientific and structural contract represented by the YAML files.
| Target | Interface and distribution | Documentation |
|---|---|---|
| Python | Scalar and NumPy array inputs backed by native ufuncs; distributed on PyPI | Python API |
| Rust | Scalar functions grouped by source publication; distributed on crates.io | Rust API |
| C | Header-only C11 functions provided as a CMake package and versioned release archive | C API |
| C++ | Optional C++23 modules provided by the native CMake package and versioned release archive | C++ API |
Installation and usage instructions are maintained in each target's linked README.
Pedotransfer functions are empirical models fitted to particular datasets, territories, measurement methods, and variable ranges. Their accuracy and applicability outside those calibration conditions are not guaranteed. A PTF that is appropriate for one soil population or study design may be unsuitable for another.
ptfkit reproduces the reviewed equations, declared unit conversions, and documented numerical behavior. It does not select a PTF for a particular use case, assess the quality of input measurements, or replace expert scientific judgement. Declared input domains describe the source or mathematical contract and do not necessarily imply runtime range validation.
Before using a function, consult its catalogue page and original publication for the citation, calibration dataset, input definitions, units, domains, notes, and warnings. Also verify that the function is marked as implemented and is present in the API reference for the intended target.
Contributions may include reporting an implementation error, requesting a PTF, improving a specification, extending the generator, or working on a language target. Use GitHub Issues to report a problem or propose a change.
ptfkit has strict ownership and validation rules for specifications and generated files. Before making a contribution, read the development guide for repository setup, dependency management, the PTF extraction and generation workflow, validation commands, documentation builds, and commit conventions. The PTF source specification guide describes the scientific information and cross-target contracts that each specification must preserve.
If you use ptfkit in research, cite the software using the metadata in
CITATION.cff. On GitHub, select Cite this repository in
the repository sidebar to export the citation in APA or BibTeX format.