SWRC/HCC Fitter — User Manual

1Overview

The SWRC/HCC Fitter estimates the two functions that govern unsaturated water flow in soil:

• Water-retention curve (SWRC), θ(h) — how volumetric water content θ changes with suction (matric head h, shown on the log scale as pF = log₁₀(h in cm)).
• Hydraulic-conductivity curve (HCC), K(h) — how unsaturated conductivity K drops as the soil dries.

You upload measured points, pick a model, and the app fits the model parameters by global optimisation (differential evolution), then shows the fitted curves, parameters with confidence intervals, goodness-of-fit metrics, and uncertainty bands. You can overlay and compare many models at once.

2Get the app — web or desktop

The app is the same in both places, so every step in this manual applies to both.

A · Use it online (nothing to install)

Open PTF.bluerror.com in any modern browser. Your data is processed in a private session and is not stored.

B · Desktop app (Windows)

1. Download SWRC-HCC-Fitter-setup.exe from the latest release.
2. Run it and follow the wizard. Approve the one-time Microsoft Visual C++ runtime if prompted (needed by the desktop window).
3. The first launch downloads a private Python runtime (a couple of minutes, internet required once). After that it starts instantly and works offline.
4. Launch SWRC-HCC Fitter from the Start Menu or desktop shortcut.

3Data format

The app reads CSV, text, and Excel (.xlsx / .xls) files. You can provide the two branches separately or in one combined file. Columns are auto-detected, and you confirm the mapping in the toolbar.

Option A — two files (retention + conductivity)

A retention file with a suction column and a water-content column, and a conductivity file with a suction column and a conductivity column. Suction can be given as pF (= log₁₀ of cm of head).

pF,theta
0.00,0.4294
1.00,0.4054
1.80,0.2669
2.30,0.1738
3.00,0.1001
4.20,0.0690

pF,K
0.50,38.73
1.10,12.44
1.70,0.7181
2.30,0.00922
2.90,8.32e-05
3.20,8.89e-06

• pF — suction as log₁₀(h/cm). E.g. pF 2 = 100 cm ≈ 10 kPa; pF 4.2 ≈ permanent wilting point.
• theta — volumetric water content (cm³/cm³), e.g. 0.0–0.5.
• K — unsaturated conductivity in your own units (e.g. cm/day). Must be positive (it is fitted in log space).

Option B — one combined file, multiple samples

Use a sample_id column plus separate suction columns for each branch. Leave cells blank where a branch has no measurement on that row.

sample_id,pF_theta,theta,pF_K,K
Loam_A,0.00,0.4294,0.50,38.73
Loam_A,1.50,0.3310,1.40,4.467
Loam_A,2.30,0.1738,2.30,0.00922
Sand_B,0.00,0.3790,0.50,290.4
Sand_B,1.50,0.2104,1.40,55.13

No data of your own? Use a built-in database

The app ships with three public soil hydraulic databases. In the toolbar, open “No data? Try a database”, pick a source and a soil sample, and click Load — the measured retention and conductivity are loaded ready to fit (your own uploads are never touched). You can also download the whole collection as an Excel workbook (one *_SWRC and one *_HCC sheet per source, each with Sample_ID and pF).

• Hohenbrink et al. (2023) — German database, 569 soils (evaporation method + dewpoint + saturated K).
• UNSODA 2.0 (Nemes et al., 2001; Leij et al., 1996) — global, 329 soils; independent cross-database test set.
• EU-HYDI (Weynants et al., 2013) — European Hydropedological Data Inventory, 2243 soils; independent test set.

4The 5-step workflow

1. Upload one or more CSV files in the top toolbar (Browse CSV or drag & drop).
2. Map columns: set the Retention pF/θ and Conductivity pF/K dropdowns (auto-guessed). Pick a sample_id column and a single sample if you have several.
3. Pick a model in the matrix: a retention shape (row) × variant (original/Brunswick/PDI), and a conductivity model below.
4. Choose the fit metric (nRMSE, NSE, or NLL) and the number of bootstrap refits.
5. Press Fit. Read the curves, parameter table, statistics, and (optionally) Ctrl+click more models to compare. Export when happy.

5Interface guide

5.1 Upload & column mapping

The toolbar groups the inputs: the upload zone, then Retention θ(h) (pF, θ), Conductivity K(h) (pF, K), and Sample (ID column + one sample). Hover the ⓘ badge on any panel for an in-app explanation.

5.2 Soil hydraulic model selection

The matrix has one row per retention function and one column per variant (original · Brunswick · PDI). Click a cell to set the base model (highlighted blue). Above the matrix, switch the modality (unimodal / bimodal / trimodal). Below it, choose the conductivity (K) model.

5.3 Optimisation parameters

5.4 Fit metric & σ

• nRMSE — range-normalised RMSE, so θ and K weigh equally. Uncertainty via bootstrap.
• NSE — variance-normalised (Nash–Sutcliffe). Uncertainty via bootstrap.
• NLL — Gaussian negative log-likelihood. It jointly calibrates the mean (model parameters) and the noise σ. Pick calibrate (σ̂ = RMSE, the maximum-likelihood value) or fixed (you type σθ and σK to control the θ-vs-K weighting). With NLL the uncertainty comes from the likelihood (Gauss–Newton + Monte-Carlo bands) instead of bootstrap.

5.5 Parameter tables

Two tables — retention and conductivity — list each parameter with its fitted Value and 2.5% / 97.5% interval. Symbols follow the selected variant's source paper (e.g. α, n, θ_r, θ_s; for Brunswick θ_cs, θ_ncs; for PDI K_snc, τ_s). Untick a row's checkbox to hold that parameter fixed during the fit. restore parameters resets to defaults.

5.6 Plots

Toggle the three square plots independently: Retention θ(h), Conductivity K(h), and Conductivity K(θ). Measured points are shown as dots; fitted models as lines; the shaded band is the 95% uncertainty (coloured to match each model). A standalone legend sits to the right so the plots stay square.

5.7 Statistical analysis

For the selected model: RMSE · NSE · KGE · NLL for each branch (θ and K), the corrected AICc (lower = better, penalises extra parameters), the calibrated/fixed σ, and water-content / plant-available-water summaries at standard suctions. When several models are fitted, a dropdown lets you inspect each one.

5.8 Model comparison

Hold Ctrl (or ⌘) and click extra cells in the matrix to overlay more models. Each curve gets its own distinct colour (the base model is blue); its uncertainty band matches. A plain click resets to a single base model.

5.9 Export

• ⬇ Figure — saves each shown plot as a high-resolution (3×) PNG, ready for slides or papers.
• ⬇ Parameters — fitted parameters + metrics + statistics as CSV.
• ⬇ Curves — the fitted θ(pF) and log₁₀K(pF) curves as CSV.
• ⬇ Fit all samples — fits every sample in the file with the selected model(s) and downloads a single combined parameters + metrics table (great for whole datasets). Pick a sample-ID column first.

In the desktop app a Save dialog appears; in the browser files download normally.

5.10 Learner mode (teaching aid)

Tick 🎓 Learner mode under the model matrix to reveal two teaching tools:

• Soil type presets — load typical van Genuchten parameters for a USDA texture class (sand → clay, after Carsel & Parrish 1988) and watch how the curve and numbers change.
• ▸ Preview curve from parameters — draws the curve straight from the current parameter values (no fitting), overlaying any uploaded data. Each parameter input shows its typical range on hover, so students can hand-tune and see each parameter's visual effect — then press Fit to compare their guess with the algorithm.

A short, student-ready walkthrough lives in the classroom guide.

6Worked examples

These use the downloadable sample files from §3. Grab RetMeas.csv, CondMeas.csv, and two_samples.csv first.

6.1 Your first fit — van Genuchten–Mualem

1. Upload RetMeas.csv and CondMeas.csv together (select both, or drop both).
2. Mapping is auto-detected: Retention pF→pF, θ→theta; Conductivity pF→pF, K→K. Sample column = none (fit all rows).
3. In the matrix choose van Genuchten (m=1−1/n) row, original column, modality unimodal. Conductivity model: Mualem.
4. Fit metric nRMSE, bootstrap 0, max iter 150. Press Fit.
5. Enable all three plots. You should see a sigmoidal θ(h) through the points and a steeply falling K(h). Read the table: α ≈ 0.03–0.04 cm⁻¹, n ≈ 1.5–1.7, θ_s ≈ 0.43, K_s ≈ 45.
6. Set bootstrap to 30 and re-fit to add 95% bands and parameter intervals.

6.2 Compare original vs Brunswick vs PDI

1. Keep the van Genuchten unimodal base model from 6.1 (blue).
2. Ctrl+click the Brunswick and PDI cells in the same row to overlay them.
3. Press Fit. Three coloured curves appear on each plot. In the dry range the Brunswick and PDI curves bend toward θ→0, while the original flattens at θ_r.
4. Open Statistical analysis and switch models in the dropdown. Compare AICc: the lowest AICc is the best trade-off of fit vs. parameters. PDI usually wins when you have dry-range data.

6.3 NLL with calibrated σ → uncertainty bands

1. Single van Genuchten–Mualem model (as in 6.1).
2. Set Fit metric = NLL. The σ controls appear — leave it on calibrate. (Bootstrap is automatically off; NLL provides its own uncertainty.)
3. Press Fit. You get likelihood-based parameter intervals and a 95% band on every plot.
4. Check Statistical analysis: σθ and σK appear, and equal each branch's RMSE — that is the maximum-likelihood σ (NLL calibrates the mean and σ together).
5. To weight θ vs K yourself, switch σ to fixed and enter e.g. σθ = 0.02, σK = 0.3.

6.4 Several samples & a bimodal soil

1. Upload two_samples.csv. Set the Sample ID column to sample_id and pick Loam_A (the dropdown fits one sample at a time).
2. Map pF_theta/theta and pF_K/K.
3. For a structured soil, switch modality to bimodal — the parameter table now shows two pore systems (α₁,n₁,w₁,α₂,n₂). Fit and compare AICc against the unimodal fit.
4. Switch the sample to Sand_B and re-fit to see a much steeper, sandier curve.

7Model reference

Retention functions (8)

Each comes in unimodal / bimodal / trimodal (1–3 superimposed pore systems, mixed by weights w) and four variants (original / Brunswick / PDI / FXW): 8 × 3 × 4 = 96 retention models.

Conductivity (capillary-bundle) models (4)

The HCC adds saturated conductivity K_s and a tortuosity τ; Brunswick and PDI add film/non-capillary terms (K_snc, a). Any conductivity model combines with any retention curve.

8Metric reference

9Tips & troubleshooting

10FAQ

What is pF?

pF = log₁₀ of suction in cm of water. pF 2 = 100 cm (~10 kPa, field-capacity-ish); pF 4.2 ≈ 1500 kPa (permanent wilting point); pF 6.8 ≈ oven dryness.

Do I need both retention and conductivity?

No. Fit either branch alone, or both together. With both, the chosen metric balances them on a common scale.

Is my data uploaded anywhere?

The web app processes data in a transient session and does not store it; the desktop app runs entirely on your machine.

Why does calibrated σ equal RMSE?

That is the Gaussian maximum-likelihood estimate: σ̂ = √(SSE/N) = RMSE. NLL calibrates the mean and σ jointly.

Which conductivity model should I use?

Mualem (q=1, r=2) is the recommended default and works well with most retention curves.

11References & links

• Weber et al. (2019), Water Resources Research — modular (Brunswick) framework.
• Peters, Durner & Iden (2024), Vadose Zone Journal — the PDI model system.
• Peters, Iden & Durner (2023), HESS — comparison of capillary-bundle conductivity models. doi
• Mualem (1976); Burdine (1953); Alexander & Skaggs (1986); Childs & Collis-George (1950).
• Full-range variant: Rudiyanto et al. (2020) FXW, doi; Wang, Jin & Deng (2018), doi.

Built on the pyspsh forward model · numerical fitting in NumPy + SciPy. Released under the MIT License.