From 2c576c646af8b970531bd9a93efb1d7fd1c0be0a Mon Sep 17 00:00:00 2001 From: "K.Tolstygin" Date: Fri, 11 Sep 2026 10:19:58 +0300 Subject: [PATCH] feat: add Myeni et al., (2021) --- docs/src/ptf-catalog/sources/index.md | 1 + docs/src/ptf-catalog/sources/myeni2021.md | 98 ++++++++++ docs/src/reference/c/functions.md | 2 + docs/src/reference/c/headers/myeni2021.md | 101 ++++++++++ docs/src/reference/c/headers/ptfkit.md | 1 + docs/src/reference/c/index.md | 1 + docs/src/reference/cpp/functions.md | 2 + docs/src/reference/cpp/index.md | 1 + docs/src/reference/cpp/modules/myeni2021.md | 106 +++++++++++ docs/src/reference/cpp/modules/ptfkit.md | 1 + docs/src/reference/python/index.md | 1 + docs/src/reference/python/myeni2021.md | 8 + specs/functions/myeni2021.yaml | 180 ++++++++++++++++++ specs/units.yaml | 2 +- targets/ptfkit-native/cpp/myeni2021.cppm | 69 +++++++ targets/ptfkit-native/cpp/ptfkit.cppm | 1 + .../ptfkit-native/include/ptfkit/myeni2021.h | 66 +++++++ targets/ptfkit-native/include/ptfkit/ptfkit.h | 1 + targets/ptfkit-native/tests/c/myeni2021.c | 18 ++ targets/ptfkit-native/tests/cpp/myeni2021.cpp | 19 ++ targets/ptfkit-py/src/ptfkit/_ptfkit.pyi | 2 + targets/ptfkit-py/src/ptfkit/myeni2021.c | 111 +++++++++++ targets/ptfkit-py/src/ptfkit/myeni2021.py | 144 ++++++++++++++ targets/ptfkit-py/src/ptfkit/ptfkit.c | 5 + targets/ptfkit-py/tests/test_myeni2021.py | 115 +++++++++++ targets/ptfkit-rs/src/lib.rs | 1 + targets/ptfkit-rs/src/myeni2021.rs | 113 +++++++++++ 27 files changed, 1169 insertions(+), 1 deletion(-) create mode 100644 docs/src/ptf-catalog/sources/myeni2021.md create mode 100644 docs/src/reference/c/headers/myeni2021.md create mode 100644 docs/src/reference/cpp/modules/myeni2021.md create mode 100644 docs/src/reference/python/myeni2021.md create mode 100644 specs/functions/myeni2021.yaml create mode 100644 targets/ptfkit-native/cpp/myeni2021.cppm create mode 100644 targets/ptfkit-native/include/ptfkit/myeni2021.h create mode 100644 targets/ptfkit-native/tests/c/myeni2021.c create mode 100644 targets/ptfkit-native/tests/cpp/myeni2021.cpp create mode 100644 targets/ptfkit-py/src/ptfkit/myeni2021.c create mode 100644 targets/ptfkit-py/src/ptfkit/myeni2021.py create mode 100644 targets/ptfkit-py/tests/test_myeni2021.py create mode 100644 targets/ptfkit-rs/src/myeni2021.rs diff --git a/docs/src/ptf-catalog/sources/index.md b/docs/src/ptf-catalog/sources/index.md index 75ac4b6..7ceb5ec 100644 --- a/docs/src/ptf-catalog/sources/index.md +++ b/docs/src/ptf-catalog/sources/index.md @@ -25,6 +25,7 @@ Each page describes the source, scope, inputs, outputs, status, and limitations | [Moisture retention and plasticity regressions for two groups of Nigerian soils.](./lal1979.md) | Nigeria | 49 | | [Li et al. (2007), Fengqiu County, North China Plain, China.](./li2007.md) | Fengqiu County soils in the North China Plain, China | 1 | | [Mayr and Jarvis (1999) modified Brooks-Corey water-retention parameter PTFs.](./mayr1999.md) | England and Wales | 1 | +| [Gravimetric field capacity and permanent wilting point for South African soils.](./myeni2021.md) | South Africa. | 2 | | [Oosterveld and Chang (1980), soil-moisture retention from texture and depth.](./oosterveld1980.md) | Southern Alberta, Canada | 5 | | [Pidgeon (1972), available-water regressions for ferrallitic soils in Uganda.](./pidgeon1972.md) | Non-alluvial ferrallitic soils in Uganda, predominantly kaolinitic and possibly illitic | 17 | | [Puckett et al. (1985), Alabama Lower Coastal Plain Ultisols.](./puckett1985.md) | Lower Coastal Plain of Alabama, USA | 1 | diff --git a/docs/src/ptf-catalog/sources/myeni2021.md b/docs/src/ptf-catalog/sources/myeni2021.md new file mode 100644 index 0000000..689b49c --- /dev/null +++ b/docs/src/ptf-catalog/sources/myeni2021.md @@ -0,0 +1,98 @@ +--- +# @generated by ptfkit-codegen; DO NOT EDIT. + +title: PTF source myeni2021 +nav-title: myeni2021 +--- + +# Gravimetric field capacity and permanent wilting point for South African soils. + +## Source + +Myeni, L., Mdlambuzi, T., Paterson, D. G., De Nysschen, G., & Moeletsi, M. E. (2021). Development and evaluation of pedotransfer functions to estimate soil moisture content at field capacity and permanent wilting point for South African soils. Water, 13(19), 2639. https://doi.org/10.3390/w13192639 + +[DOI: 10.3390/w13192639](https://doi.org/10.3390/w13192639) + +## Scope + +**Territory:** South Africa. + +**Dataset:** ARC national soil database: 6307 soil horizons retained after quality control, with 3171 development horizons and 3136 validation horizons. Horizons were grouped regardless of depth, soil type, textural class, geographic location and climate, then randomly split per granulometric range (Sections 2.1-2.2; Tables 2-3). + +## Functions + +### `calc_ptf_myeni2021_fc` + +Estimate gravimetric field capacity from clay, silt and soil organic carbon. + +**Status:** `implemented` + +**Prediction target:** Gravimetric soil moisture content at field capacity (-33 kPa). + +#### Inputs + +| Name | Type | Unit | Domain | Description | +| --- | --- | --- | --- | --- | +| `clay` | `number` | % | Development dataset range: 1.00-83.00% (Table 3). | Clay content by weight, particle diameter below 0.002 mm. | +| `silt` | `number` | % | Development dataset range: 1.00-64.00% (Table 3). | Silt content by weight, particle diameter 0.002-0.05 mm. | +| `soc` | `number` | % | Development dataset range: 0.01-9.36% (Table 3). | Soil organic carbon content by weight, measured by the Walkley-Black method. | + +#### Outputs + +| Name | Unit | Domain | Description | +| --- | --- | --- | --- | +| `fc` | kg kg⁻¹ | Observed development dataset range: 0.01-0.50 kg/kg (Table 3). | Gravimetric soil moisture content at field capacity (-33 kPa). | + +!!! note + + Table 5 gives the stepwise multiple linear regression for FC. + +!!! note + + Inputs are weight percentages; output is gravimetric water content. + +!!! warning + + Apply with caution outside South Africa, even under similar soil and climatic conditions. + +!!! warning + + Disturbed samples were used; soil structure is not explicitly represented. + +### `calc_ptf_myeni2021_pwp` + +Estimate gravimetric permanent wilting point from clay, silt and soil organic carbon. + +**Status:** `implemented` + +**Prediction target:** Gravimetric soil moisture content at permanent wilting point (-1500 kPa). + +#### Inputs + +| Name | Type | Unit | Domain | Description | +| --- | --- | --- | --- | --- | +| `clay` | `number` | % | Development dataset range: 1.00-83.00% (Table 3). | Clay content by weight, particle diameter below 0.002 mm. | +| `silt` | `number` | % | Development dataset range: 1.00-64.00% (Table 3). | Silt content by weight, particle diameter 0.002-0.05 mm. | +| `soc` | `number` | % | Development dataset range: 0.01-9.36% (Table 3). | Soil organic carbon content by weight, measured by the Walkley-Black method. | + +#### Outputs + +| Name | Unit | Domain | Description | +| --- | --- | --- | --- | +| `pwp` | kg kg⁻¹ | Observed development dataset range: 0.00-0.31 kg/kg (Table 3). | Gravimetric soil moisture content at permanent wilting point (-1500 kPa). | + +!!! note + + Table 5 gives the stepwise multiple linear regression for PWP without an additive constant. + +!!! note + + Inputs are weight percentages; output is gravimetric water content. + +!!! warning + + Apply with caution outside South Africa, even under similar soil and climatic conditions. + +!!! warning + + Disturbed samples were used; soil structure is not explicitly represented. diff --git a/docs/src/reference/c/functions.md b/docs/src/reference/c/functions.md index a41875f..b5d9c9e 100644 --- a/docs/src/reference/c/functions.md +++ b/docs/src/reference/c/functions.md @@ -133,6 +133,8 @@ title: C function index | [`calc_ptf_lal1979_group_ii_water_15bar_from_water_01bar`](headers/lal1979.md#function-calc_ptf_lal1979_group_ii_water_15bar_from_water_01bar) | Estimate gravimetric moisture retention at 15 bar suction for Group II. | [``](headers/lal1979.md) | | [`calc_ptf_li2007`](headers/li2007.md#function-calc_ptf_li2007) | Estimate van Genuchten parameters and saturated hydraulic conductivity for Fengqiu County soils. | [``](headers/li2007.md) | | [`calc_ptf_mayr1999`](headers/mayr1999.md#function-calc_ptf_mayr1999) | Estimate modified Brooks-Corey a, b, and saturated water content from texture, bulk density, and organic carbon. | [``](headers/mayr1999.md) | +| [`calc_ptf_myeni2021_fc`](headers/myeni2021.md#function-calc_ptf_myeni2021_fc) | Estimate gravimetric field capacity from clay, silt and soil organic carbon. | [``](headers/myeni2021.md) | +| [`calc_ptf_myeni2021_pwp`](headers/myeni2021.md#function-calc_ptf_myeni2021_pwp) | Estimate gravimetric permanent wilting point from clay, silt and soil organic carbon. | [``](headers/myeni2021.md) | | [`calc_ptf_oosterveld1980_available_water`](headers/oosterveld1980.md#function-calc_ptf_oosterveld1980_available_water) | Estimate available gravimetric soil moisture between field capacity and wilting point. | [``](headers/oosterveld1980.md) | | [`calc_ptf_oosterveld1980_field_capacity`](headers/oosterveld1980.md#function-calc_ptf_oosterveld1980_field_capacity) | Estimate gravimetric soil-moisture content at field capacity. | [``](headers/oosterveld1980.md) | | [`calc_ptf_oosterveld1980_field_capacity_tension`](headers/oosterveld1980.md#function-calc_ptf_oosterveld1980_field_capacity_tension) | Estimate field-capacity tension from clay content. | [``](headers/oosterveld1980.md) | diff --git a/docs/src/reference/c/headers/myeni2021.md b/docs/src/reference/c/headers/myeni2021.md new file mode 100644 index 0000000..a7ba8a5 --- /dev/null +++ b/docs/src/reference/c/headers/myeni2021.md @@ -0,0 +1,101 @@ +--- +title: "myeni2021.h" +--- + + + +# `` + +```c +#include +``` + +Gravimetric field capacity and permanent wilting point for South African soils. + +## Source + +Myeni, L., Mdlambuzi, T., Paterson, D. G., De Nysschen, G., & Moeletsi, M. E. (2021). Development and evaluation of pedotransfer functions to estimate soil moisture content at field capacity and permanent wilting point for South African soils. Water, 13(19), 2639. https://doi.org/10.3390/w13192639 + +[DOI: 10.3390/w13192639](https://doi.org/10.3390/w13192639) + +## Scope + +**Territory:** South Africa. + +**Dataset:** ARC national soil database: 6307 soil horizons retained after quality control, with 3171 development horizons and 3136 validation horizons. Horizons were grouped regardless of depth, soil type, textural class, geographic location and climate, then randomly split per granulometric range (Sections 2.1-2.2; Tables 2-3). + +[PTF catalog page](../../../ptf-catalog/sources/myeni2021.md) + +## Functions + +### `calc_ptf_myeni2021_fc` {#function-calc_ptf_myeni2021_fc} + +Estimate gravimetric field capacity from clay, silt and soil organic carbon. + +```c +static inline double calc_ptf_myeni2021_fc(double clay, double silt, double soc); +``` + +#### Parameters + +| Name | Direction | Description | +| --- | --- | --- | +| `clay` | in | Clay content by weight, particle diameter below 0.002 mm. (%) | +| `silt` | in | Silt content by weight, particle diameter 0.002-0.05 mm. (%) | +| `soc` | in | Soil organic carbon content by weight, measured by the Walkley-Black method. (%) | + +#### Returns + +Gravimetric soil moisture content at field capacity (-33 kPa). (kg kg⁻¹) + +!!! note + + Table 5 gives the stepwise multiple linear regression for FC. + +!!! note + + Inputs are weight percentages; output is gravimetric water content. + +!!! warning + + Apply with caution outside South Africa, even under similar soil and climatic conditions. + +!!! warning + + Disturbed samples were used; soil structure is not explicitly represented. + +### `calc_ptf_myeni2021_pwp` {#function-calc_ptf_myeni2021_pwp} + +Estimate gravimetric permanent wilting point from clay, silt and soil organic carbon. + +```c +static inline double calc_ptf_myeni2021_pwp(double clay, double silt, double soc); +``` + +#### Parameters + +| Name | Direction | Description | +| --- | --- | --- | +| `clay` | in | Clay content by weight, particle diameter below 0.002 mm. (%) | +| `silt` | in | Silt content by weight, particle diameter 0.002-0.05 mm. (%) | +| `soc` | in | Soil organic carbon content by weight, measured by the Walkley-Black method. (%) | + +#### Returns + +Gravimetric soil moisture content at permanent wilting point (-1500 kPa). (kg kg⁻¹) + +!!! note + + Table 5 gives the stepwise multiple linear regression for PWP without an additive constant. + +!!! note + + Inputs are weight percentages; output is gravimetric water content. + +!!! warning + + Apply with caution outside South Africa, even under similar soil and climatic conditions. + +!!! warning + + Disturbed samples were used; soil structure is not explicitly represented. diff --git a/docs/src/reference/c/headers/ptfkit.md b/docs/src/reference/c/headers/ptfkit.md index a537858..8855dbc 100644 --- a/docs/src/reference/c/headers/ptfkit.md +++ b/docs/src/reference/c/headers/ptfkit.md @@ -29,6 +29,7 @@ This umbrella header aggregates every public ptfkit source header. Include an in - [``](lal1979.md) — Moisture retention and plasticity regressions for two groups of Nigerian soils. - [``](li2007.md) — Li et al. (2007), Fengqiu County, North China Plain, China. - [``](mayr1999.md) — Mayr and Jarvis (1999) modified Brooks-Corey water-retention parameter PTFs. +- [``](myeni2021.md) — Gravimetric field capacity and permanent wilting point for South African soils. - [``](oosterveld1980.md) — Oosterveld and Chang (1980), soil-moisture retention from texture and depth. - [``](pidgeon1972.md) — Pidgeon (1972), available-water regressions for ferrallitic soils in Uganda. - [``](puckett1985.md) — Puckett et al. (1985), Alabama Lower Coastal Plain Ultisols. diff --git a/docs/src/reference/c/index.md b/docs/src/reference/c/index.md index 6eabe45..489f15b 100644 --- a/docs/src/reference/c/index.md +++ b/docs/src/reference/c/index.md @@ -26,6 +26,7 @@ ptfkit's C API is organized around installed headers. - [``](headers/lal1979.md) — Moisture retention and plasticity regressions for two groups of Nigerian soils. - [``](headers/li2007.md) — Li et al. (2007), Fengqiu County, North China Plain, China. - [``](headers/mayr1999.md) — Mayr and Jarvis (1999) modified Brooks-Corey water-retention parameter PTFs. +- [``](headers/myeni2021.md) — Gravimetric field capacity and permanent wilting point for South African soils. - [``](headers/oosterveld1980.md) — Oosterveld and Chang (1980), soil-moisture retention from texture and depth. - [``](headers/pidgeon1972.md) — Pidgeon (1972), available-water regressions for ferrallitic soils in Uganda. - [``](headers/puckett1985.md) — Puckett et al. (1985), Alabama Lower Coastal Plain Ultisols. diff --git a/docs/src/reference/cpp/functions.md b/docs/src/reference/cpp/functions.md index 8d075fa..d3cbb6e 100644 --- a/docs/src/reference/cpp/functions.md +++ b/docs/src/reference/cpp/functions.md @@ -133,6 +133,8 @@ title: C++ function index | [`ptfkit::lal1979::calc_ptf_lal1979_group_ii_water_15bar_from_water_01bar`](modules/lal1979.md#function-calc_ptf_lal1979_group_ii_water_15bar_from_water_01bar) | Estimate gravimetric moisture retention at 15 bar suction for Group II. | [`ptfkit.lal1979`](modules/lal1979.md) | | [`ptfkit::li2007::calc_ptf_li2007`](modules/li2007.md#function-calc_ptf_li2007) | Estimate van Genuchten parameters and saturated hydraulic conductivity for Fengqiu County soils. | [`ptfkit.li2007`](modules/li2007.md) | | [`ptfkit::mayr1999::calc_ptf_mayr1999`](modules/mayr1999.md#function-calc_ptf_mayr1999) | Estimate modified Brooks-Corey a, b, and saturated water content from texture, bulk density, and organic carbon. | [`ptfkit.mayr1999`](modules/mayr1999.md) | +| [`ptfkit::myeni2021::calc_ptf_myeni2021_fc`](modules/myeni2021.md#function-calc_ptf_myeni2021_fc) | Estimate gravimetric field capacity from clay, silt and soil organic carbon. | [`ptfkit.myeni2021`](modules/myeni2021.md) | +| [`ptfkit::myeni2021::calc_ptf_myeni2021_pwp`](modules/myeni2021.md#function-calc_ptf_myeni2021_pwp) | Estimate gravimetric permanent wilting point from clay, silt and soil organic carbon. | [`ptfkit.myeni2021`](modules/myeni2021.md) | | [`ptfkit::oosterveld1980::calc_ptf_oosterveld1980_available_water`](modules/oosterveld1980.md#function-calc_ptf_oosterveld1980_available_water) | Estimate available gravimetric soil moisture between field capacity and wilting point. | [`ptfkit.oosterveld1980`](modules/oosterveld1980.md) | | [`ptfkit::oosterveld1980::calc_ptf_oosterveld1980_field_capacity`](modules/oosterveld1980.md#function-calc_ptf_oosterveld1980_field_capacity) | Estimate gravimetric soil-moisture content at field capacity. | [`ptfkit.oosterveld1980`](modules/oosterveld1980.md) | | [`ptfkit::oosterveld1980::calc_ptf_oosterveld1980_field_capacity_tension`](modules/oosterveld1980.md#function-calc_ptf_oosterveld1980_field_capacity_tension) | Estimate field-capacity tension from clay content. | [`ptfkit.oosterveld1980`](modules/oosterveld1980.md) | diff --git a/docs/src/reference/cpp/index.md b/docs/src/reference/cpp/index.md index 1b87130..4e67d92 100644 --- a/docs/src/reference/cpp/index.md +++ b/docs/src/reference/cpp/index.md @@ -26,6 +26,7 @@ ptfkit's C++ API is organized around C++23 modules. - [`ptfkit.lal1979`](modules/lal1979.md) — Moisture retention and plasticity regressions for two groups of Nigerian soils. - [`ptfkit.li2007`](modules/li2007.md) — Li et al. (2007), Fengqiu County, North China Plain, China. - [`ptfkit.mayr1999`](modules/mayr1999.md) — Mayr and Jarvis (1999) modified Brooks-Corey water-retention parameter PTFs. +- [`ptfkit.myeni2021`](modules/myeni2021.md) — Gravimetric field capacity and permanent wilting point for South African soils. - [`ptfkit.oosterveld1980`](modules/oosterveld1980.md) — Oosterveld and Chang (1980), soil-moisture retention from texture and depth. - [`ptfkit.pidgeon1972`](modules/pidgeon1972.md) — Pidgeon (1972), available-water regressions for ferrallitic soils in Uganda. - [`ptfkit.puckett1985`](modules/puckett1985.md) — Puckett et al. (1985), Alabama Lower Coastal Plain Ultisols. diff --git a/docs/src/reference/cpp/modules/myeni2021.md b/docs/src/reference/cpp/modules/myeni2021.md new file mode 100644 index 0000000..3041771 --- /dev/null +++ b/docs/src/reference/cpp/modules/myeni2021.md @@ -0,0 +1,106 @@ +--- +# @generated by ptfkit-codegen; DO NOT EDIT. + +title: C++ module ptfkit.myeni2021 +nav-title: ptfkit.myeni2021 +--- + +# `ptfkit.myeni2021` + +```cpp +import ptfkit.myeni2021; +``` + +**Exported namespace:** `ptfkit::myeni2021` + +Gravimetric field capacity and permanent wilting point for South African soils. + +## Source + +Myeni, L., Mdlambuzi, T., Paterson, D. G., De Nysschen, G., & Moeletsi, M. E. (2021). Development and evaluation of pedotransfer functions to estimate soil moisture content at field capacity and permanent wilting point for South African soils. Water, 13(19), 2639. https://doi.org/10.3390/w13192639 + +[DOI: 10.3390/w13192639](https://doi.org/10.3390/w13192639) + +## Scope + +**Territory:** South Africa. + +**Dataset:** ARC national soil database: 6307 soil horizons retained after quality control, with 3171 development horizons and 3136 validation horizons. Horizons were grouped regardless of depth, soil type, textural class, geographic location and climate, then randomly split per granulometric range (Sections 2.1-2.2; Tables 2-3). + +[PTF catalog page](../../../ptf-catalog/sources/myeni2021.md) + +## Functions + +### `calc_ptf_myeni2021_fc` {#function-calc_ptf_myeni2021_fc} + +Estimate gravimetric field capacity from clay, silt and soil organic carbon. + +```cpp +[[nodiscard]] +inline double calc_ptf_myeni2021_fc(double clay, double silt, double soc) +``` + +#### Parameters + +| Name | Description | +| --- | --- | +| `clay` | Clay content by weight, particle diameter below 0.002 mm. (%) | +| `silt` | Silt content by weight, particle diameter 0.002-0.05 mm. (%) | +| `soc` | Soil organic carbon content by weight, measured by the Walkley-Black method. (%) | + +#### Returns + +Gravimetric soil moisture content at field capacity (-33 kPa). (kg kg⁻¹) + +!!! note + + Table 5 gives the stepwise multiple linear regression for FC. + +!!! note + + Inputs are weight percentages; output is gravimetric water content. + +!!! warning + + Apply with caution outside South Africa, even under similar soil and climatic conditions. + +!!! warning + + Disturbed samples were used; soil structure is not explicitly represented. + +### `calc_ptf_myeni2021_pwp` {#function-calc_ptf_myeni2021_pwp} + +Estimate gravimetric permanent wilting point from clay, silt and soil organic carbon. + +```cpp +[[nodiscard]] +inline double calc_ptf_myeni2021_pwp(double clay, double silt, double soc) +``` + +#### Parameters + +| Name | Description | +| --- | --- | +| `clay` | Clay content by weight, particle diameter below 0.002 mm. (%) | +| `silt` | Silt content by weight, particle diameter 0.002-0.05 mm. (%) | +| `soc` | Soil organic carbon content by weight, measured by the Walkley-Black method. (%) | + +#### Returns + +Gravimetric soil moisture content at permanent wilting point (-1500 kPa). (kg kg⁻¹) + +!!! note + + Table 5 gives the stepwise multiple linear regression for PWP without an additive constant. + +!!! note + + Inputs are weight percentages; output is gravimetric water content. + +!!! warning + + Apply with caution outside South Africa, even under similar soil and climatic conditions. + +!!! warning + + Disturbed samples were used; soil structure is not explicitly represented. diff --git a/docs/src/reference/cpp/modules/ptfkit.md b/docs/src/reference/cpp/modules/ptfkit.md index ba4a58c..f808cf8 100644 --- a/docs/src/reference/cpp/modules/ptfkit.md +++ b/docs/src/reference/cpp/modules/ptfkit.md @@ -30,6 +30,7 @@ This umbrella module re-exports every public ptfkit source module. Import an ind - [`ptfkit.lal1979`](lal1979.md) — Moisture retention and plasticity regressions for two groups of Nigerian soils. - [`ptfkit.li2007`](li2007.md) — Li et al. (2007), Fengqiu County, North China Plain, China. - [`ptfkit.mayr1999`](mayr1999.md) — Mayr and Jarvis (1999) modified Brooks-Corey water-retention parameter PTFs. +- [`ptfkit.myeni2021`](myeni2021.md) — Gravimetric field capacity and permanent wilting point for South African soils. - [`ptfkit.oosterveld1980`](oosterveld1980.md) — Oosterveld and Chang (1980), soil-moisture retention from texture and depth. - [`ptfkit.pidgeon1972`](pidgeon1972.md) — Pidgeon (1972), available-water regressions for ferrallitic soils in Uganda. - [`ptfkit.puckett1985`](puckett1985.md) — Puckett et al. (1985), Alabama Lower Coastal Plain Ultisols. diff --git a/docs/src/reference/python/index.md b/docs/src/reference/python/index.md index 0869ee4..3a3b896 100644 --- a/docs/src/reference/python/index.md +++ b/docs/src/reference/python/index.md @@ -25,6 +25,7 @@ ptfkit's Python API is organized around public source modules. - [`ptfkit.lal1979`](lal1979.md) — Moisture retention and plasticity regressions for two groups of Nigerian soils. - [`ptfkit.li2007`](li2007.md) — Li et al. (2007), Fengqiu County, North China Plain, China. - [`ptfkit.mayr1999`](mayr1999.md) — Mayr and Jarvis (1999) modified Brooks-Corey water-retention parameter PTFs. +- [`ptfkit.myeni2021`](myeni2021.md) — Gravimetric field capacity and permanent wilting point for South African soils. - [`ptfkit.oosterveld1980`](oosterveld1980.md) — Oosterveld and Chang (1980), soil-moisture retention from texture and depth. - [`ptfkit.pidgeon1972`](pidgeon1972.md) — Pidgeon (1972), available-water regressions for ferrallitic soils in Uganda. - [`ptfkit.puckett1985`](puckett1985.md) — Puckett et al. (1985), Alabama Lower Coastal Plain Ultisols. diff --git a/docs/src/reference/python/myeni2021.md b/docs/src/reference/python/myeni2021.md new file mode 100644 index 0000000..5b59586 --- /dev/null +++ b/docs/src/reference/python/myeni2021.md @@ -0,0 +1,8 @@ +--- +# @generated by ptfkit-codegen; DO NOT EDIT. + +title: Python module ptfkit.myeni2021 +nav-title: ptfkit.myeni2021 +--- + +::: ptfkit.myeni2021 diff --git a/specs/functions/myeni2021.yaml b/specs/functions/myeni2021.yaml new file mode 100644 index 0000000..dc3d19b --- /dev/null +++ b/specs/functions/myeni2021.yaml @@ -0,0 +1,180 @@ +source: + summary: Gravimetric field capacity and permanent wilting point for South African soils. + citation_apa: >- + Myeni, L., Mdlambuzi, T., Paterson, D. G., De Nysschen, G., & Moeletsi, + M. E. (2021). Development and evaluation of pedotransfer functions to + estimate soil moisture content at field capacity and permanent wilting + point for South African soils. Water, 13(19), 2639. + https://doi.org/10.3390/w13192639 + doi: + identifier: 10.3390/w13192639 + url: https://doi.org/10.3390/w13192639 +scope: + territory: South Africa. + dataset: >- + ARC national soil database: 6307 soil horizons retained after quality + control, with 3171 development horizons and 3136 validation horizons. + Horizons were grouped regardless of depth, soil type, textural class, + geographic location and climate, then randomly split per granulometric + range (Sections 2.1-2.2; Tables 2-3). +$defs: + Clay: + name: clay + symbol: Cl + unit: "%" + domain: "Development dataset range: 1.00-83.00% (Table 3)." + description: Clay content by weight, particle diameter below 0.002 mm. + Silt: + name: silt + symbol: Si + unit: "%" + domain: "Development dataset range: 1.00-64.00% (Table 3)." + description: Silt content by weight, particle diameter 0.002-0.05 mm. + Soc: + name: soc + symbol: SOC + unit: "%" + domain: "Development dataset range: 0.01-9.36% (Table 3)." + description: Soil organic carbon content by weight, measured by the Walkley-Black method. +functions: + - name: calc_ptf_myeni2021_fc + status: implemented + public_api: + name: calc_ptf_myeni2021_fc + summary: Estimate gravimetric field capacity from clay, silt and soil organic carbon. + scope: + prediction_target: Gravimetric soil moisture content at field capacity (-33 kPa). + models: + h_theta: null + k_h: null + inputs: + - $ref: '#/$defs/Clay' + - $ref: '#/$defs/Silt' + - $ref: '#/$defs/Soc' + outputs: + type: scalar + name: fc + quantity: gravimetric_water_content + symbol: FC + unit: mass_fraction + reported_unit: kg kg⁻¹ + domain: "Observed development dataset range: 0.01-0.50 kg/kg (Table 3)." + description: Gravimetric soil moisture content at field capacity (-33 kPa). + implementation: + variables: + - name: fc + expr: 0.014 + (0.005 * clay) + (0.009 * soc) + (0.002 * silt) + verification_cases: + - id: development_predictor_means + kind: calculated + inputs: {clay: 27.65, silt: 16.34, soc: 0.75} + expected: {fc: 0.19168} + source_location: Table 3 development predictor means; Table 5 FC equation. + rationale: >- + Use the published development predictor means, which lie inside + their marginal ranges. Together with the published sand mean of + 54.72%, texture sums to 98.71%, within the source's 95-105% quality + criterion. Direct decimal arithmetic from Table 5 gives 0.19168 + kg/kg, above the calculated PWP of 0.10454 kg/kg. This is a + calculated formula check, not a published input-output pair or + evidence of model accuracy. + documentation: + notes: + - Table 5 gives the stepwise multiple linear regression for FC. + - Inputs are weight percentages; output is gravimetric water content. + warnings: + - Apply with caution outside South Africa, even under similar soil and climatic conditions. + - Disturbed samples were used; soil structure is not explicitly represented. + - name: calc_ptf_myeni2021_pwp + status: implemented + public_api: + name: calc_ptf_myeni2021_pwp + summary: Estimate gravimetric permanent wilting point from clay, silt and soil organic carbon. + scope: + prediction_target: Gravimetric soil moisture content at permanent wilting point (-1500 kPa). + models: + h_theta: null + k_h: null + inputs: + - $ref: '#/$defs/Clay' + - $ref: '#/$defs/Silt' + - $ref: '#/$defs/Soc' + outputs: + type: scalar + name: pwp + quantity: gravimetric_water_content + symbol: PWP + unit: mass_fraction + reported_unit: kg kg⁻¹ + domain: "Observed development dataset range: 0.00-0.31 kg/kg (Table 3)." + description: Gravimetric soil moisture content at permanent wilting point (-1500 kPa). + implementation: + variables: + - name: pwp + expr: (0.003 * clay) + (0.001 * silt) + (0.007 * soc) + verification_cases: + - id: development_predictor_means + kind: calculated + inputs: {clay: 27.65, silt: 16.34, soc: 0.75} + expected: {pwp: 0.10454} + source_location: Table 3 development predictor means; Table 5 PWP equation. + rationale: >- + Use the published development predictor means, which lie inside + their marginal ranges. Together with the published sand mean of + 54.72%, texture sums to 98.71%, within the source's 95-105% quality + criterion. Direct decimal arithmetic from Table 5 gives 0.10454 + kg/kg, below the calculated FC of 0.19168 kg/kg. This is a + calculated formula check, not a published input-output pair or + evidence of model accuracy. + documentation: + notes: + - Table 5 gives the stepwise multiple linear regression for PWP without an additive constant. + - Inputs are weight percentages; output is gravimetric water content. + warnings: + - Apply with caution outside South Africa, even under similar soil and climatic conditions. + - Disturbed samples were used; soil structure is not explicitly represented. +scientific_notes: | + ## Supported models + + Table 5 publishes two new multiple linear regressions for gravimetric FC + and PWP. Table 1 lists comparison models from other authors; these are not + attributed to Myeni et al. or extracted as new models here. Textural classes + in Table 2 describe the dataset and are not categorical predictors. + + ## Review decisions + + Section 2.2 specifies weight percentages for predictors; Table 5 identifies + outputs as gravimetric kg kg⁻¹. Section 2.1 includes both percent and kg kg⁻¹ + in its initial description, but Table 5 equations and Table 3 fractional + output ranges establish the output scale used here. No percent conversion + or bulk-density conversion is applied. The abstract specifies -33 and + -1500 kPa; Section 2.1 describes the corresponding pressure-plate magnitudes. + + Although Table 5 lists a PWP constant significance statistic, its printed + output equation has no additive constant. The implementation follows that + equation. Reported coefficient standard errors and Table 6 performance + statistics are not implementation tolerances. The approved mass_fraction + notation alias preserves numerical values and the existing absolute + tolerance of 0.001, with no relative tolerance. + + ## Documented limitations + + The source supplies no complete published predictor-output example. Table 3 + contains marginal summaries, not individual horizons. Figure descriptions + in the supplied Markdown give approximate measured-versus-estimated points + without predictors; these are not verification pairs. Section 3.4.2 offers + the SMR spreadsheet on request, and the Data Availability Statement offers + data on request. Calculated cases follow the current extraction policy; + the supplied bundle's earlier missing-golden-case audit is historical. + + Table 3 ranges describe observed samples, not clipping bounds or a promise + of applicability for arbitrary combinations of marginal extrema. Section + 2.1 retained texture totals between 95% and 105%. The published development + texture means are preserved without renormalization. The study used + disturbed samples and omitted bulk density, limiting representation of + soil structure (Section 3.4.1). Transfer outside the study region requires + caution (Section 3.4.2 and Conclusions). + + ## Blockers + + None. The draft awaits human review before target generation. diff --git a/specs/units.yaml b/specs/units.yaml index d33b09f..b59d719 100644 --- a/specs/units.yaml +++ b/specs/units.yaml @@ -8,7 +8,7 @@ volume_percent: mass_fraction: preferred_notation: "kg/kg" - aliases: ["g/g", "g g⁻¹"] + aliases: ["g/g", "g g⁻¹", "kg kg⁻¹"] mass_percent: preferred_notation: "% w/w" diff --git a/targets/ptfkit-native/cpp/myeni2021.cppm b/targets/ptfkit-native/cpp/myeni2021.cppm new file mode 100644 index 0000000..db7c902 --- /dev/null +++ b/targets/ptfkit-native/cpp/myeni2021.cppm @@ -0,0 +1,69 @@ +/* @generated by ptfkit-codegen; DO NOT EDIT. */ + +export module ptfkit.myeni2021; + +/** + * @brief Gravimetric field capacity and permanent wilting point for South African soils. + * + * @details Source publication: + * Myeni, L., Mdlambuzi, T., Paterson, D. G., De Nysschen, G., & Moeletsi, M. E. (2021). + * Development and evaluation of pedotransfer functions to estimate soil moisture content at + * field capacity and permanent wilting point for South African soils. Water, 13(19), 2639. + * https://doi.org/10.3390/w13192639 + * @see https://doi.org/10.3390/w13192639 DOI: 10.3390/w13192639 + * + * @remark Geographic scope: + * South Africa. + * + * @remark Calibration dataset: + * ARC national soil database: 6307 soil horizons retained after quality control, with 3171 + * development horizons and 3136 validation horizons. Horizons were grouped regardless of + * depth, soil type, textural class, geographic location and climate, then randomly split per + * granulometric range (Sections 2.1-2.2; Tables 2-3). + */ + +export namespace ptfkit::myeni2021 { + +/** + * @brief Estimate gravimetric field capacity from clay, silt and soil organic carbon. + * @param clay Clay content by weight, particle diameter below 0.002 mm. (%) + * @param silt Silt content by weight, particle diameter 0.002-0.05 mm. (%) + * @param soc Soil organic carbon content by weight, measured by the Walkley-Black method. (%) + * @return Gravimetric soil moisture content at field capacity (-33 kPa). (kg kg⁻¹) + * + * @details Prediction target: + * Gravimetric soil moisture content at field capacity (-33 kPa). + * @note Table 5 gives the stepwise multiple linear regression for FC. + * @note Inputs are weight percentages; output is gravimetric water content. + * @warning Apply with caution outside South Africa, even under similar soil and climatic + * conditions. + * @warning Disturbed samples were used; soil structure is not explicitly represented. + */ +[[nodiscard]] +inline double calc_ptf_myeni2021_fc(double clay, double silt, double soc) { + return 0.014 + 0.005 * clay + 0.009 * soc + 0.002 * silt; +} + +/** + * @brief Estimate gravimetric permanent wilting point from clay, silt and soil organic carbon. + * @param clay Clay content by weight, particle diameter below 0.002 mm. (%) + * @param silt Silt content by weight, particle diameter 0.002-0.05 mm. (%) + * @param soc Soil organic carbon content by weight, measured by the Walkley-Black method. (%) + * @return Gravimetric soil moisture content at permanent wilting point (-1500 kPa). (kg + * kg⁻¹) + * + * @details Prediction target: + * Gravimetric soil moisture content at permanent wilting point (-1500 kPa). + * @note Table 5 gives the stepwise multiple linear regression for PWP without an additive + * constant. + * @note Inputs are weight percentages; output is gravimetric water content. + * @warning Apply with caution outside South Africa, even under similar soil and climatic + * conditions. + * @warning Disturbed samples were used; soil structure is not explicitly represented. + */ +[[nodiscard]] +inline double calc_ptf_myeni2021_pwp(double clay, double silt, double soc) { + return 0.003 * clay + 0.001 * silt + 0.007 * soc; +} + +} // namespace ptfkit::myeni2021 diff --git a/targets/ptfkit-native/cpp/ptfkit.cppm b/targets/ptfkit-native/cpp/ptfkit.cppm index 12a9d86..6915e6d 100644 --- a/targets/ptfkit-native/cpp/ptfkit.cppm +++ b/targets/ptfkit-native/cpp/ptfkit.cppm @@ -17,6 +17,7 @@ export import ptfkit.jabro1992; export import ptfkit.lal1979; export import ptfkit.li2007; export import ptfkit.mayr1999; +export import ptfkit.myeni2021; export import ptfkit.oosterveld1980; export import ptfkit.pidgeon1972; export import ptfkit.puckett1985; diff --git a/targets/ptfkit-native/include/ptfkit/myeni2021.h b/targets/ptfkit-native/include/ptfkit/myeni2021.h new file mode 100644 index 0000000..7e617ce --- /dev/null +++ b/targets/ptfkit-native/include/ptfkit/myeni2021.h @@ -0,0 +1,66 @@ +/* @generated by ptfkit-codegen; DO NOT EDIT. */ + +#ifndef PTFKIT_MYENI2021_H +#define PTFKIT_MYENI2021_H + +/** + * @brief Gravimetric field capacity and permanent wilting point for South African soils. + * + * @details Source publication: + * Myeni, L., Mdlambuzi, T., Paterson, D. G., De Nysschen, G., & Moeletsi, M. E. (2021). + * Development and evaluation of pedotransfer functions to estimate soil moisture content at + * field capacity and permanent wilting point for South African soils. Water, 13(19), 2639. + * https://doi.org/10.3390/w13192639 + * @see https://doi.org/10.3390/w13192639 DOI: 10.3390/w13192639 + * + * @remark Geographic scope: + * South Africa. + * + * @remark Calibration dataset: + * ARC national soil database: 6307 soil horizons retained after quality control, with 3171 + * development horizons and 3136 validation horizons. Horizons were grouped regardless of + * depth, soil type, textural class, geographic location and climate, then randomly split per + * granulometric range (Sections 2.1-2.2; Tables 2-3). + */ + +/** + * @brief Estimate gravimetric field capacity from clay, silt and soil organic carbon. + * @param clay Clay content by weight, particle diameter below 0.002 mm. (%) + * @param silt Silt content by weight, particle diameter 0.002-0.05 mm. (%) + * @param soc Soil organic carbon content by weight, measured by the Walkley-Black method. (%) + * @return Gravimetric soil moisture content at field capacity (-33 kPa). (kg kg⁻¹) + * + * @details Prediction target: + * Gravimetric soil moisture content at field capacity (-33 kPa). + * @note Table 5 gives the stepwise multiple linear regression for FC. + * @note Inputs are weight percentages; output is gravimetric water content. + * @warning Apply with caution outside South Africa, even under similar soil and climatic + * conditions. + * @warning Disturbed samples were used; soil structure is not explicitly represented. + */ +static inline double calc_ptf_myeni2021_fc(double clay, double silt, double soc) { + return 0.014 + 0.005 * clay + 0.009 * soc + 0.002 * silt; +} + +/** + * @brief Estimate gravimetric permanent wilting point from clay, silt and soil organic carbon. + * @param clay Clay content by weight, particle diameter below 0.002 mm. (%) + * @param silt Silt content by weight, particle diameter 0.002-0.05 mm. (%) + * @param soc Soil organic carbon content by weight, measured by the Walkley-Black method. (%) + * @return Gravimetric soil moisture content at permanent wilting point (-1500 kPa). (kg + * kg⁻¹) + * + * @details Prediction target: + * Gravimetric soil moisture content at permanent wilting point (-1500 kPa). + * @note Table 5 gives the stepwise multiple linear regression for PWP without an additive + * constant. + * @note Inputs are weight percentages; output is gravimetric water content. + * @warning Apply with caution outside South Africa, even under similar soil and climatic + * conditions. + * @warning Disturbed samples were used; soil structure is not explicitly represented. + */ +static inline double calc_ptf_myeni2021_pwp(double clay, double silt, double soc) { + return 0.003 * clay + 0.001 * silt + 0.007 * soc; +} + +#endif diff --git a/targets/ptfkit-native/include/ptfkit/ptfkit.h b/targets/ptfkit-native/include/ptfkit/ptfkit.h index fae7ac7..3e464dd 100644 --- a/targets/ptfkit-native/include/ptfkit/ptfkit.h +++ b/targets/ptfkit-native/include/ptfkit/ptfkit.h @@ -18,6 +18,7 @@ #include #include #include +#include #include #include #include diff --git a/targets/ptfkit-native/tests/c/myeni2021.c b/targets/ptfkit-native/tests/c/myeni2021.c new file mode 100644 index 0000000..d0cd05d --- /dev/null +++ b/targets/ptfkit-native/tests/c/myeni2021.c @@ -0,0 +1,18 @@ +/* @generated by ptfkit-codegen; DO NOT EDIT. */ + +#include +#include "support/close_enough.h" + +int main() { + { + const double result = calc_ptf_myeni2021_fc(27.65, 16.34, 0.75); + assert_close(result, 0.19168, 0.001, 0.0, "gravimetric_water_content", "mass_fraction", + "registry", "development_predictor_means"); + } + { + const double result = calc_ptf_myeni2021_pwp(27.65, 16.34, 0.75); + assert_close(result, 0.10454, 0.001, 0.0, "gravimetric_water_content", "mass_fraction", + "registry", "development_predictor_means"); + } + return 0; +} diff --git a/targets/ptfkit-native/tests/cpp/myeni2021.cpp b/targets/ptfkit-native/tests/cpp/myeni2021.cpp new file mode 100644 index 0000000..189d88e --- /dev/null +++ b/targets/ptfkit-native/tests/cpp/myeni2021.cpp @@ -0,0 +1,19 @@ +/* @generated by ptfkit-codegen; DO NOT EDIT. */ + +import ptfkit.myeni2021; + +#include "support/close_enough.h" + +int main() { + { + const auto result = ptfkit::myeni2021::calc_ptf_myeni2021_fc(27.65, 16.34, 0.75); + assert_close(result, 0.19168, 0.001, 0.0, "gravimetric_water_content", "mass_fraction", + "registry", "development_predictor_means"); + } + { + const auto result = ptfkit::myeni2021::calc_ptf_myeni2021_pwp(27.65, 16.34, 0.75); + assert_close(result, 0.10454, 0.001, 0.0, "gravimetric_water_content", "mass_fraction", + "registry", "development_predictor_means"); + } + return 0; +} diff --git a/targets/ptfkit-py/src/ptfkit/_ptfkit.pyi b/targets/ptfkit-py/src/ptfkit/_ptfkit.pyi index 12999b1..49437eb 100644 --- a/targets/ptfkit-py/src/ptfkit/_ptfkit.pyi +++ b/targets/ptfkit-py/src/ptfkit/_ptfkit.pyi @@ -127,6 +127,8 @@ calc_ptf_lal1979_group_ii_water_15bar_from_sand: ufunc calc_ptf_lal1979_group_ii_water_15bar_from_water_01bar: ufunc calc_ptf_li2007: ufunc calc_ptf_mayr1999: ufunc +calc_ptf_myeni2021_fc: ufunc +calc_ptf_myeni2021_pwp: ufunc calc_ptf_oosterveld1980_available_water: ufunc calc_ptf_oosterveld1980_field_capacity: ufunc calc_ptf_oosterveld1980_field_capacity_tension: ufunc diff --git a/targets/ptfkit-py/src/ptfkit/myeni2021.c b/targets/ptfkit-py/src/ptfkit/myeni2021.c new file mode 100644 index 0000000..694f5a2 --- /dev/null +++ b/targets/ptfkit-py/src/ptfkit/myeni2021.c @@ -0,0 +1,111 @@ +/* @generated by ptfkit-codegen; DO NOT EDIT. */ +#include +#include "ufunc.h" + +static const int calc_ptf_myeni2021_fc_types[] = {NPY_DOUBLE, NPY_DOUBLE, NPY_DOUBLE, NPY_DOUBLE}; +static int calc_ptf_myeni2021_fc_contiguous_loop(PyArrayMethod_Context *context, char *const *data, + const npy_intp *dimensions, + const npy_intp *strides, + NpyAuxData *transferdata) { + (void)context; + (void)strides; + (void)transferdata; + const double *in_clay = (const double *)data[0]; + const double *in_silt = (const double *)data[1]; + const double *in_soc = (const double *)data[2]; + double *out_fc = (double *)data[3]; + for (npy_intp index = 0; index < dimensions[0]; index++) { + const double clay = in_clay[index]; + const double silt = in_silt[index]; + const double soc = in_soc[index]; + const double ptfkit_result = calc_ptf_myeni2021_fc(clay, silt, soc); + out_fc[index] = ptfkit_result; + } + return 0; +} + +static int calc_ptf_myeni2021_fc_strided_loop(PyArrayMethod_Context *context, char *const *data, + const npy_intp *dimensions, const npy_intp *strides, + NpyAuxData *transferdata) { + (void)context; + (void)transferdata; + for (npy_intp index = 0; index < dimensions[0]; index++) { + const double clay = *(const double *)(data[0] + index * strides[0]); + const double silt = *(const double *)(data[1] + index * strides[1]); + const double soc = *(const double *)(data[2] + index * strides[2]); + const double ptfkit_result = calc_ptf_myeni2021_fc(clay, silt, soc); + *(double *)(data[3] + index * strides[3]) = ptfkit_result; + } + return 0; +} +static PyType_Slot calc_ptf_myeni2021_fc_slots[] = { + {NPY_METH_strided_loop, calc_ptf_myeni2021_fc_strided_loop}, + {NPY_METH_contiguous_loop, calc_ptf_myeni2021_fc_contiguous_loop}, + {0, NULL}, +}; +static PyArrayMethod_Spec calc_ptf_myeni2021_fc_spec = { + .name = "calc_ptf_myeni2021_fc", + .nin = 3, + .nout = 1, + .casting = NPY_SAME_KIND_CASTING, + .slots = calc_ptf_myeni2021_fc_slots, +}; + +static const int calc_ptf_myeni2021_pwp_types[] = {NPY_DOUBLE, NPY_DOUBLE, NPY_DOUBLE, NPY_DOUBLE}; +static int calc_ptf_myeni2021_pwp_contiguous_loop(PyArrayMethod_Context *context, char *const *data, + const npy_intp *dimensions, + const npy_intp *strides, + NpyAuxData *transferdata) { + (void)context; + (void)strides; + (void)transferdata; + const double *in_clay = (const double *)data[0]; + const double *in_silt = (const double *)data[1]; + const double *in_soc = (const double *)data[2]; + double *out_pwp = (double *)data[3]; + for (npy_intp index = 0; index < dimensions[0]; index++) { + const double clay = in_clay[index]; + const double silt = in_silt[index]; + const double soc = in_soc[index]; + const double ptfkit_result = calc_ptf_myeni2021_pwp(clay, silt, soc); + out_pwp[index] = ptfkit_result; + } + return 0; +} + +static int calc_ptf_myeni2021_pwp_strided_loop(PyArrayMethod_Context *context, char *const *data, + const npy_intp *dimensions, const npy_intp *strides, + NpyAuxData *transferdata) { + (void)context; + (void)transferdata; + for (npy_intp index = 0; index < dimensions[0]; index++) { + const double clay = *(const double *)(data[0] + index * strides[0]); + const double silt = *(const double *)(data[1] + index * strides[1]); + const double soc = *(const double *)(data[2] + index * strides[2]); + const double ptfkit_result = calc_ptf_myeni2021_pwp(clay, silt, soc); + *(double *)(data[3] + index * strides[3]) = ptfkit_result; + } + return 0; +} +static PyType_Slot calc_ptf_myeni2021_pwp_slots[] = { + {NPY_METH_strided_loop, calc_ptf_myeni2021_pwp_strided_loop}, + {NPY_METH_contiguous_loop, calc_ptf_myeni2021_pwp_contiguous_loop}, + {0, NULL}, +}; +static PyArrayMethod_Spec calc_ptf_myeni2021_pwp_spec = { + .name = "calc_ptf_myeni2021_pwp", + .nin = 3, + .nout = 1, + .casting = NPY_SAME_KIND_CASTING, + .slots = calc_ptf_myeni2021_pwp_slots, +}; + +int ptfkit_register_myeni2021(PyObject *module) { + if (ptfkit_add_ufunc(module, "calc_ptf_myeni2021_fc", calc_ptf_myeni2021_fc_types, 3, 1, + &calc_ptf_myeni2021_fc_spec) < 0) + return -1; + if (ptfkit_add_ufunc(module, "calc_ptf_myeni2021_pwp", calc_ptf_myeni2021_pwp_types, 3, 1, + &calc_ptf_myeni2021_pwp_spec) < 0) + return -1; + return 0; +} diff --git a/targets/ptfkit-py/src/ptfkit/myeni2021.py b/targets/ptfkit-py/src/ptfkit/myeni2021.py new file mode 100644 index 0000000..adb4fe7 --- /dev/null +++ b/targets/ptfkit-py/src/ptfkit/myeni2021.py @@ -0,0 +1,144 @@ +# @generated by ptfkit-codegen; DO NOT EDIT. + +# ruff: noqa: I001 + +r"""Gravimetric field capacity and permanent wilting point for South African soils. + +Reference: + Myeni, L., Mdlambuzi, T., Paterson, D. G., De Nysschen, G., & Moeletsi, M. E. (2021). + Development and evaluation of pedotransfer functions to estimate soil moisture content at field + capacity and permanent wilting point for South African soils. Water, 13(19), 2639. + https://doi.org/10.3390/w13192639 + [DOI: 10.3390/w13192639](https://doi.org/10.3390/w13192639) + +Territory + +: South Africa. + +Dataset + +: ARC national soil database: 6307 soil horizons retained after quality control, with 3171 + development horizons and 3136 validation horizons. Horizons were grouped regardless of depth, + soil type, textural class, geographic location and climate, then randomly split per + granulometric range (Sections 2.1-2.2; Tables 2-3). + +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, overload + +from ptfkit._dispatch import call as _call +from ptfkit._ptfkit import ( + calc_ptf_myeni2021_fc as _calc_ptf_myeni2021_fc, + calc_ptf_myeni2021_pwp as _calc_ptf_myeni2021_pwp, +) + + +if TYPE_CHECKING: + from numpy import floating + from numpy.typing import ArrayLike, NDArray + +__all__ = ['calc_ptf_myeni2021_fc', 'calc_ptf_myeni2021_pwp'] + + +@overload +def calc_ptf_myeni2021_fc(*, clay: float, silt: float, soc: float) -> floating: ... + + +@overload +def calc_ptf_myeni2021_fc( + *, + clay: ArrayLike, + silt: ArrayLike, + soc: ArrayLike, + out: NDArray[floating] | None = None, +) -> NDArray[floating]: ... + + +def calc_ptf_myeni2021_fc( + *, + clay: float | ArrayLike, + silt: float | ArrayLike, + soc: float | ArrayLike, + out: NDArray[floating] | None = None, +) -> floating | NDArray[floating]: + """Estimate gravimetric field capacity from clay, silt and soil organic carbon. + + Arguments: + clay: Clay content by weight, particle diameter below 0.002 mm. (%) + silt: Silt content by weight, particle diameter 0.002-0.05 mm. (%) + soc: Soil organic carbon content by weight, measured by the Walkley-Black method. (%) + out: Optional output arrays for in-place calculation. + + Returns: + fc: Gravimetric soil moisture content at field capacity (-33 kPa). (kg kg⁻¹) + + Notes: + Prediction target: Gravimetric soil moisture content at field capacity (-33 kPa). + Table 5 gives the stepwise multiple linear regression for FC. + Inputs are weight percentages; output is gravimetric water content. + + Warning: + Apply with caution outside South Africa, even under similar soil and climatic conditions. + Disturbed samples were used; soil structure is not explicitly represented. + + """ + return _call( + _calc_ptf_myeni2021_fc, + clay, + silt, + soc, + out=out, + ) + + +@overload +def calc_ptf_myeni2021_pwp(*, clay: float, silt: float, soc: float) -> floating: ... + + +@overload +def calc_ptf_myeni2021_pwp( + *, + clay: ArrayLike, + silt: ArrayLike, + soc: ArrayLike, + out: NDArray[floating] | None = None, +) -> NDArray[floating]: ... + + +def calc_ptf_myeni2021_pwp( + *, + clay: float | ArrayLike, + silt: float | ArrayLike, + soc: float | ArrayLike, + out: NDArray[floating] | None = None, +) -> floating | NDArray[floating]: + """Estimate gravimetric permanent wilting point from clay, silt and soil organic carbon. + + Arguments: + clay: Clay content by weight, particle diameter below 0.002 mm. (%) + silt: Silt content by weight, particle diameter 0.002-0.05 mm. (%) + soc: Soil organic carbon content by weight, measured by the Walkley-Black method. (%) + out: Optional output arrays for in-place calculation. + + Returns: + pwp: Gravimetric soil moisture content at permanent wilting point (-1500 kPa). (kg kg⁻¹) + + Notes: + Prediction target: Gravimetric soil moisture content at permanent wilting point (-1500 kPa). + Table 5 gives the stepwise multiple linear regression for PWP without an additive constant. + Inputs are weight percentages; output is gravimetric water content. + + Warning: + Apply with caution outside South Africa, even under similar soil and climatic conditions. + Disturbed samples were used; soil structure is not explicitly represented. + + """ + return _call( + _calc_ptf_myeni2021_pwp, + clay, + silt, + soc, + out=out, + ) diff --git a/targets/ptfkit-py/src/ptfkit/ptfkit.c b/targets/ptfkit-py/src/ptfkit/ptfkit.c index c5e7698..d97d983 100644 --- a/targets/ptfkit-py/src/ptfkit/ptfkit.c +++ b/targets/ptfkit-py/src/ptfkit/ptfkit.c @@ -21,6 +21,7 @@ #include "lal1979.c" #include "li2007.c" #include "mayr1999.c" +#include "myeni2021.c" #include "oosterveld1980.c" #include "pidgeon1972.c" #include "puckett1985.c" @@ -101,6 +102,10 @@ PyMODINIT_FUNC PyInit__ptfkit(void) { Py_DECREF(module); return NULL; } + if (ptfkit_register_myeni2021(module) < 0) { + Py_DECREF(module); + return NULL; + } if (ptfkit_register_oosterveld1980(module) < 0) { Py_DECREF(module); return NULL; diff --git a/targets/ptfkit-py/tests/test_myeni2021.py b/targets/ptfkit-py/tests/test_myeni2021.py new file mode 100644 index 0000000..00e739f --- /dev/null +++ b/targets/ptfkit-py/tests/test_myeni2021.py @@ -0,0 +1,115 @@ +# @generated by ptfkit-codegen; DO NOT EDIT. +from __future__ import annotations + +import pytest + +from _helpers import assert_close, prepare_vector_case +from ptfkit.myeni2021 import calc_ptf_myeni2021_fc, calc_ptf_myeni2021_pwp + + +CASES_CALC_PTF_MYENI2021_FC = [ + ({'clay': 27.65, 'silt': 16.34, 'soc': 0.75}, {'fc': 0.19168}), +] +CASES_CALC_PTF_MYENI2021_FC_IDS = [ + 'development_predictor_means', +] + + +@pytest.mark.parametrize( + ('inputs', 'expected'), CASES_CALC_PTF_MYENI2021_FC, ids=CASES_CALC_PTF_MYENI2021_FC_IDS +) +def test_calc_ptf_myeni2021_fc_verification(inputs: dict[str, float], expected: dict[str, float]): + result = calc_ptf_myeni2021_fc(**inputs) + + assert_close( + result, + expected['fc'], + absolute=0.001, + relative=0.0, + quantity='gravimetric_water_content', + unit='mass_fraction', + source='registry', + ) + + +def test_calc_ptf_myeni2021_fc_array(): + inputs, expected, _out = prepare_vector_case(CASES_CALC_PTF_MYENI2021_FC) + result = calc_ptf_myeni2021_fc(**inputs, out=None) + assert_close( + result[0], + expected['fc'], + absolute=0.001, + relative=0.0, + quantity='gravimetric_water_content', + unit='mass_fraction', + source='registry', + ) + + +def test_calc_ptf_myeni2021_fc_out(): + inputs, expected, out = prepare_vector_case(CASES_CALC_PTF_MYENI2021_FC) + result = calc_ptf_myeni2021_fc(**inputs, out=out) + assert result is out + assert_close( + result[0], + expected['fc'], + absolute=0.001, + relative=0.0, + quantity='gravimetric_water_content', + unit='mass_fraction', + source='registry', + ) + + +CASES_CALC_PTF_MYENI2021_PWP = [ + ({'clay': 27.65, 'silt': 16.34, 'soc': 0.75}, {'pwp': 0.10454}), +] +CASES_CALC_PTF_MYENI2021_PWP_IDS = [ + 'development_predictor_means', +] + + +@pytest.mark.parametrize( + ('inputs', 'expected'), CASES_CALC_PTF_MYENI2021_PWP, ids=CASES_CALC_PTF_MYENI2021_PWP_IDS +) +def test_calc_ptf_myeni2021_pwp_verification(inputs: dict[str, float], expected: dict[str, float]): + result = calc_ptf_myeni2021_pwp(**inputs) + + assert_close( + result, + expected['pwp'], + absolute=0.001, + relative=0.0, + quantity='gravimetric_water_content', + unit='mass_fraction', + source='registry', + ) + + +def test_calc_ptf_myeni2021_pwp_array(): + inputs, expected, _out = prepare_vector_case(CASES_CALC_PTF_MYENI2021_PWP) + result = calc_ptf_myeni2021_pwp(**inputs, out=None) + assert_close( + result[0], + expected['pwp'], + absolute=0.001, + relative=0.0, + quantity='gravimetric_water_content', + unit='mass_fraction', + source='registry', + ) + + +def test_calc_ptf_myeni2021_pwp_out(): + inputs, expected, out = prepare_vector_case(CASES_CALC_PTF_MYENI2021_PWP) + result = calc_ptf_myeni2021_pwp(**inputs, out=out) + assert result is out + assert_close( + result[0], + expected['pwp'], + absolute=0.001, + relative=0.0, + quantity='gravimetric_water_content', + unit='mass_fraction', + source='registry', + ) diff --git a/targets/ptfkit-rs/src/lib.rs b/targets/ptfkit-rs/src/lib.rs index 5e8164c..19dfa50 100644 --- a/targets/ptfkit-rs/src/lib.rs +++ b/targets/ptfkit-rs/src/lib.rs @@ -11,6 +11,7 @@ pub mod ferrerjulia2004; pub mod jabro1992; pub mod li2007; pub mod mayr1999; +pub mod myeni2021; pub mod pidgeon1972; pub mod puckett1985; pub mod rawls1982; diff --git a/targets/ptfkit-rs/src/myeni2021.rs b/targets/ptfkit-rs/src/myeni2021.rs new file mode 100644 index 0000000..651682b --- /dev/null +++ b/targets/ptfkit-rs/src/myeni2021.rs @@ -0,0 +1,113 @@ +// @generated by ptfkit-codegen; DO NOT EDIT. + +#![doc = r"Gravimetric field capacity and permanent wilting point for South African soils. + +# Reference + +Myeni, L., Mdlambuzi, T., Paterson, D. G., De Nysschen, G., & Moeletsi, M. E. (2021). +Development and evaluation of pedotransfer functions to estimate soil moisture content at field +capacity and permanent wilting point for South African soils. Water, 13(19), 2639. +https://doi.org/10.3390/w13192639 +DOI: 10.3390/w13192639 (https://doi.org/10.3390/w13192639) + +# Territory + +South Africa. + +# Dataset + +ARC national soil database: 6307 soil horizons retained after quality control, with 3171 +development horizons and 3136 validation horizons. Horizons were grouped regardless of depth, +soil type, textural class, geographic location and climate, then randomly split per +granulometric range (Sections 2.1-2.2; Tables 2-3)."] + +#[doc = r"Estimate gravimetric field capacity from clay, silt and soil organic carbon. + +# Arguments + + * clay: Clay content by weight, particle diameter below 0.002 mm. (%) + * silt: Silt content by weight, particle diameter 0.002-0.05 mm. (%) + * soc: Soil organic carbon content by weight, measured by the Walkley-Black method. (%) + +# Returns + + * fc: Gravimetric soil moisture content at field capacity (-33 kPa). (kg kg⁻¹) + +# Notes + +Prediction target: Gravimetric soil moisture content at field capacity (-33 kPa). +Table 5 gives the stepwise multiple linear regression for FC. +Inputs are weight percentages; output is gravimetric water content. + +# Warnings + +Apply with caution outside South Africa, even under similar soil and climatic conditions. +Disturbed samples were used; soil structure is not explicitly represented."] +#[cfg_attr(feature = "inline", inline)] +#[must_use] +pub fn calc_ptf_myeni2021_fc(clay: f64, silt: f64, soc: f64) -> f64 { + 0.014f64 + 0.005f64 * clay + 0.009f64 * soc + 0.002f64 * silt +} +#[cfg(test)] +mod calc_ptf_myeni2021_fc_tests { + use super::*; + use crate::test_support::assert_close; + #[test] + fn development_predictor_means() { + let result = calc_ptf_myeni2021_fc(27.65f64, 16.34f64, 0.75f64); + assert_close( + result, + 0.19168f64, + 0.001f64, + 0f64, + "gravimetric_water_content", + "mass_fraction", + "registry", + ); + } +} +#[doc = r"Estimate gravimetric permanent wilting point from clay, silt and soil organic carbon. + +# Arguments + + * clay: Clay content by weight, particle diameter below 0.002 mm. (%) + * silt: Silt content by weight, particle diameter 0.002-0.05 mm. (%) + * soc: Soil organic carbon content by weight, measured by the Walkley-Black method. (%) + +# Returns + + * pwp: Gravimetric soil moisture content at permanent wilting point (-1500 kPa). (kg kg⁻¹) + +# Notes + +Prediction target: Gravimetric soil moisture content at permanent wilting point (-1500 kPa). +Table 5 gives the stepwise multiple linear regression for PWP without an additive constant. +Inputs are weight percentages; output is gravimetric water content. + +# Warnings + +Apply with caution outside South Africa, even under similar soil and climatic conditions. +Disturbed samples were used; soil structure is not explicitly represented."] +#[cfg_attr(feature = "inline", inline)] +#[must_use] +pub fn calc_ptf_myeni2021_pwp(clay: f64, silt: f64, soc: f64) -> f64 { + 0.003f64 * clay + 0.001f64 * silt + 0.007f64 * soc +} +#[cfg(test)] +mod calc_ptf_myeni2021_pwp_tests { + use super::*; + use crate::test_support::assert_close; + #[test] + fn development_predictor_means() { + let result = calc_ptf_myeni2021_pwp(27.65f64, 16.34f64, 0.75f64); + assert_close( + result, + 0.10454f64, + 0.001f64, + 0f64, + "gravimetric_water_content", + "mass_fraction", + "registry", + ); + } +}