diff --git a/codegen/src/corpus_report.rs b/codegen/src/corpus_report.rs index ccdac50..31b2124 100644 --- a/codegen/src/corpus_report.rs +++ b/codegen/src/corpus_report.rs @@ -852,8 +852,8 @@ functions: crate::compile::functions(entries.clone()).expect("repository specifications compile"); let report = Report::from_entries(&entries); - assert_eq!(report.verification.cases_total, 136); - assert_eq!(report.verification.by_kind["calculated"], 125); + assert_eq!(report.verification.cases_total, 138); + assert_eq!(report.verification.by_kind["calculated"], 127); assert_eq!(report.verification.by_kind["published"], 11); assert_eq!(report.sources.specification_files, entries.len()); assert_eq!( diff --git a/docs/src/ptf-catalog/sources/index.md b/docs/src/ptf-catalog/sources/index.md index a0400a6..e67f773 100644 --- a/docs/src/ptf-catalog/sources/index.md +++ b/docs/src/ptf-catalog/sources/index.md @@ -22,6 +22,7 @@ Each page describes the source, scope, inputs, outputs, status, and limitations | [Jabro (1992), United States.](./jabro1992.md) | USA | 1 | | [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 a8ff235..68fec59 100644 --- a/docs/src/reference/c/functions.md +++ b/docs/src/reference/c/functions.md @@ -79,6 +79,8 @@ title: C function index | [`calc_ptf_jabro1992`](headers/jabro1992.md#function-calc_ptf_jabro1992) | Estimate saturated hydraulic conductivity from silt, clay, and bulk density. | [``](headers/jabro1992.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 66a7827..0117a34 100644 --- a/docs/src/reference/c/headers/ptfkit.md +++ b/docs/src/reference/c/headers/ptfkit.md @@ -26,6 +26,7 @@ This umbrella header aggregates every public ptfkit source header. Include an in - [``](jabro1992.md) — Jabro (1992), United States. - [``](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 376c8f8..49c4107 100644 --- a/docs/src/reference/c/index.md +++ b/docs/src/reference/c/index.md @@ -23,6 +23,7 @@ ptfkit's C API is organized around installed headers. - [``](headers/jabro1992.md) — Jabro (1992), United States. - [``](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 371647f..a4bf54d 100644 --- a/docs/src/reference/cpp/functions.md +++ b/docs/src/reference/cpp/functions.md @@ -79,6 +79,8 @@ title: C++ function index | [`ptfkit::jabro1992::calc_ptf_jabro1992`](modules/jabro1992.md#function-calc_ptf_jabro1992) | Estimate saturated hydraulic conductivity from silt, clay, and bulk density. | [`ptfkit.jabro1992`](modules/jabro1992.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 0d24c39..99d1323 100644 --- a/docs/src/reference/cpp/index.md +++ b/docs/src/reference/cpp/index.md @@ -23,6 +23,7 @@ ptfkit's C++ API is organized around C++23 modules. - [`ptfkit.jabro1992`](modules/jabro1992.md) — Jabro (1992), United States. - [`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 19f9d28..5a85f22 100644 --- a/docs/src/reference/cpp/modules/ptfkit.md +++ b/docs/src/reference/cpp/modules/ptfkit.md @@ -27,6 +27,7 @@ This umbrella module re-exports every public ptfkit source module. Import an ind - [`ptfkit.jabro1992`](jabro1992.md) — Jabro (1992), United States. - [`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 a9ec82f..e0a51bc 100644 --- a/docs/src/reference/python/index.md +++ b/docs/src/reference/python/index.md @@ -22,6 +22,7 @@ ptfkit's Python API is organized around public source modules. - [`ptfkit.jabro1992`](jabro1992.md) — Jabro (1992), United States. - [`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 346ba0a..f51eeb0 100644 --- a/specs/units.yaml +++ b/specs/units.yaml @@ -8,7 +8,7 @@ volume_percent: mass_fraction: preferred_notation: "kg/kg" - aliases: ["g/g"] + aliases: ["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 b2f524c..6f659a8 100644 --- a/targets/ptfkit-native/cpp/ptfkit.cppm +++ b/targets/ptfkit-native/cpp/ptfkit.cppm @@ -14,6 +14,7 @@ export import ptfkit.hodnett2002; export import ptfkit.jabro1992; 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 2ed27a4..cdc86ac 100644 --- a/targets/ptfkit-native/include/ptfkit/ptfkit.h +++ b/targets/ptfkit-native/include/ptfkit/ptfkit.h @@ -15,6 +15,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..0df562f --- /dev/null +++ b/targets/ptfkit-native/tests/cpp/myeni2021.cpp @@ -0,0 +1,23 @@ +/* @generated by ptfkit-codegen; DO NOT EDIT. */ + +#ifdef IMPORT_UMBRELLA +import ptfkit; +#else +import ptfkit.myeni2021; +#endif + +#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 589523c..2041f28 100644 --- a/targets/ptfkit-py/src/ptfkit/_ptfkit.pyi +++ b/targets/ptfkit-py/src/ptfkit/_ptfkit.pyi @@ -73,6 +73,8 @@ calc_ptf_hodnett2002: ufunc calc_ptf_jabro1992: 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 5ba70bb..aef4871 100644 --- a/targets/ptfkit-py/src/ptfkit/ptfkit.c +++ b/targets/ptfkit-py/src/ptfkit/ptfkit.c @@ -18,6 +18,7 @@ #include "jabro1992.c" #include "li2007.c" #include "mayr1999.c" +#include "myeni2021.c" #include "oosterveld1980.c" #include "pidgeon1972.c" #include "puckett1985.c" @@ -85,6 +86,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 0b15118..1fa62a7 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..f6235f3 --- /dev/null +++ b/targets/ptfkit-rs/src/myeni2021.rs @@ -0,0 +1,146 @@ +// @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)."] + +#[cfg(test)] +fn resolved_tolerance(expected: f64, absolute: f64, relative: f64) -> f64 { + absolute + .max(relative * expected.abs()) + .max(0.00000000000001f64) +} +#[cfg(test)] +fn assert_close( + actual: f64, + expected: f64, + absolute: f64, + relative: f64, + quantity: &str, + unit: &str, + source: &str, +) { + let difference = (actual - expected).abs(); + let tolerance = resolved_tolerance(expected, absolute, relative); + assert!( + difference <= tolerance, + "actual={actual}, expected={expected}, difference={difference}, tolerance={tolerance}, quantity={quantity}, unit={unit}, source={source}" + ); +} +#[cfg(test)] +mod comparator_tests { + use super::*; + #[test] + fn accepts_below_and_rejects_above_tolerance() { + for expected in [0.0, 2.0, -2.0] { + let tolerance = resolved_tolerance(expected, 0.001, 0.01); + assert!((expected + tolerance * 0.5 - expected).abs() <= tolerance); + assert!((expected + tolerance * 2.0 - expected).abs() > tolerance); + } + } +} +#[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::*; + #[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::*; + #[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", + ); + } +}