Soakline user guide

Getting started

A study has up to five sections, one per tab: Crop water, Reference ET, Sprinkler, Drip and Drainage, plus a Report tab. A new study opens with every section filled with example values; most are illustrative learning values, and the field names say where a value is quoted from a publication.

1. On Crop water, change the planting day or a stage length and watch the season totals, the crop-coefficient chart and the monthly balance update.
2. Open Examples for a single-section study, for example the two published FAO-56 reference-ET days or the ILRI drain-spacing examples.
3. Remove a section you do not need with Remove; add it back from its tab.
4. Save writes a JSON project file and Open reads it back. CSV downloads the results of the current study.

Calculations run in a Web Worker on your device and need a current site token. Editing, opening and saving never need one. The study is also kept in this browser between visits.

Reference evapotranspiration (ETo)

Soakline computes grass reference evapotranspiration with the FAO Penman-Monteith equation of FAO Irrigation and Drainage Paper 56 (Allen and others, 1998), for one day or for a mean month. Inputs are the day of the year, latitude, elevation, maximum and minimum temperature, a humidity measure (maximum and minimum relative humidity, mean relative humidity, dewpoint, or actual vapour pressure), wind speed and its measurement height, and a radiation measure (sunshine hours, measured solar radiation, or the temperature-range estimate with a coefficient kRs).

Every intermediate is shown: atmospheric pressure, psychrometric constant, slope of the vapour-pressure curve, saturation and actual vapour pressure, extraterrestrial radiation, daylight hours, solar and clear-sky radiation, net shortwave and longwave radiation, soil heat flux and the radiation and aerodynamic terms. All of them, and any warning, are also in the Report and the results CSV. Wind measured at another height is converted to 2 m with the logarithmic profile; at exactly 2 m the measured value is used.

The tool warns, rather than refuses, when sunshine exceeds the possible daylight (it is capped), when solar radiation exceeds the clear-sky value (the ratio is capped at 1 in the longwave term), when the solar-to-clear-sky ratio falls below 0.26 (the cloudiness factor of the longwave equation turns negative, outside the range it was fitted for), and when the equation gives a negative value (ETo is then reported as 0). Latitudes beyond 66° are refused because the sunrise-angle formula has no solution at the poles.

Crop water requirement

Enter the monthly climate (ETo computed from each month's mean climate at the 15th of the month, or entered directly) and the monthly rainfall. The crop has a planting day, four stage lengths and three crop coefficients (initial, mid-season and end). Kc is constant in the initial and mid-season stages and changes linearly in the development and late stages (FAO-56 Eq. 66). Optional climate adjustments raise or lower Kc mid and Kc end for wind speed, minimum humidity and crop height (Eqs. 62 and 65); they apply only inside the FAO-56 limits (wind 1 to 6 m/s, minimum humidity 20 to 80 %, height 0.1 to 10 m), and the Kc end adjustment only when Kc end is at least 0.45.

Crop evapotranspiration is computed for every day of the season (up to 365 days, crossing the year end if needed) as Kc times the ETo of that day's month. For each month, rainfall and effective rainfall are prorated to the days of the season in that month. Effective rainfall uses the FAO Training Manual 3 formula (0.8 P − 25 above 75 mm a month, 0.6 P − 10 otherwise, never negative), a fixed fraction you choose, or no rain.

The net irrigation requirement of a month is ETc minus effective rainfall, never negative. The gross requirement divides it by the application efficiency and by one minus the leaching requirement you enter. Because rainfall is only known per month, the balance gives a peak-month average daily requirement: the largest monthly net requirement divided by the season days in that month. That value and the design flow based on it are labelled as monthly averages. The largest single-day crop ET is reported separately, with the gross requirement and design flow it implies when rain is ignored; it is the larger and safer basis for sizing. Each design flow is the irrigated area times its daily depth, delivered in the operating hours per day you give.

The climate adjustment of Kc mid and Kc end must leave the coefficient at zero or above; a combination that would make it negative is refused with a message. Warnings from the monthly ETo calculations of the months the season uses (for example sunshine above the possible daylight) appear with the month name in the crop-water warnings. When soil heat flux uses neighbouring months (Eq. 43) and a neighbour has entered ETo instead of climate data, that month uses zero and says so. A climate-adjusted Kc above 2 is flagged, and an Eq. 65 adjustment of a Kc end below 0.45 is shown as not applied.

Limitation: this is a monthly balance without soil-water storage. Rain in excess of one month's ETc is not carried into the next month, and no irrigation calendar is produced.

Sprinkler application and uniformity

The application (precipitation) rate is the sprinkler flow divided by the area each sprinkler serves: a flow in litres per hour over the product of the two spacings in metres gives millimetres per hour. The set time is the gross depth divided by the rate. Soakline warns when the rate exceeds the maximum rate you enter for the soil.

Enter catch-can depths from a field test to obtain the Christiansen coefficient of uniformity, CU = 100 (1 − Σ|x − mean| / (n · mean)), and the low-quarter distribution uniformity, DU = 100 × (mean of the lowest quarter) / mean. When the number of cans is not a multiple of four, the lowest quarter is exactly n/4 cans, with a fractional weight on the boundary can. The map shades each can; fewer than 16 cans gives a warning.

Drip uniformity, laterals and manifolds

An emitter follows q = Kd · H^x, with Kd taken from the rated flow at the rated head and x the discharge exponent (0 for a fully pressure-compensating emitter). From the manufacturer's coefficient of variation Cv, the emitters per plant Np and a target emission uniformity, Soakline gives the head for the design average flow, the minimum allowed flow qm = EU · qa / (100 (1 − 1.27 Cv / √Np)), the head Hm that delivers it, and the allowable head variation in the sub-unit, 2.5 (Ha − Hm), following the FAO Irrigation Manual, Module 9.

The lateral is solved emitter by emitter from the far end: each emitter's flow depends on its own pressure, friction in each pipe segment uses the Hazen-Williams form of Module 9 or the Darcy-Weisbach equation with a constant friction factor, a loss factor adds fittings, and the ground slope adds or removes head (downhill positive). The far-end pressure is found by bisection so that the computed inlet head matches yours; the iterations, residual and a converged flag are shown. The lateral's design uniformity uses its own minimum and average flows. If the inlet head cannot pressurise the whole lateral (an uphill rise larger than the inlet head, or friction that uses it up before the far end) so that some emitter would run below 0.1 m of pressure, the lateral is reported as infeasible: no uniformity, heads or manifold numbers are shown or exported, only the reason and the inlet head that would give the far-end emitter its rated head.

For comparison Soakline shows Christiansen's F factor for equal outlets with the first outlet one spacing from the inlet, next to the factor the solution actually produced. A manifold feeds identical laterals, each taking the lateral inlet flow; its inlet head is set so the least-favoured lateral receives the lateral design inlet head. Velocity heads are neglected.

Subsurface drainage

Drain spacing follows Hooghoudt's steady-state equation, q = (8 Kb d h + 4 Kt h²) / L², as presented in ILRI Publication 16 (Drainage Principles and Applications, chapter 8). Enter the drainage coefficient q, the drain depth, the required depth of the water table midway between drains (h is their difference), the depth of the impervious layer below drain level D, and the hydraulic conductivity above and below drain level (equal values for a uniform soil). A pipe drain is described by its radius; an open drain or a trench by its wet perimeter u, which gives an equivalent radius u/π.

The equivalent depth d is computed exactly with the series of Van der Molen and Wesseling, so no table interpolation is needed; with the impervious layer at drain level (D = 0) the equation reduces to the flow above drain level only, and that spacing is shown too. Spacing is found by bisection.

The drain-pipe check uses Manning's equation for a full pipe. A perforated field drain receives water along its length, so for the same head loss it carries √3 times the full uniform-flow discharge; a reduction factor R (for example 0.58) restores a safety margin. Soakline reports the design capacity, the maximum drained area and drain length at the solved spacing, and the smallest inside diameter that carries the design flow.

Not modelled: unsteady drainage, entrance resistance, layered soils other than drains at a layer interface, and envelope design.

Files, exports and limitations

Projects are JSON files with a format name and a version number; a file from a newer version is refused with a message, and older versions are upgraded through a migration chain. Files up to 1 MB are accepted. The results CSV is built from the results of exactly the current study, so it can never be stale, and it carries every warning and solver convergence flag shown on screen; text that a spreadsheet could read as a formula is prefixed with an apostrophe.

Monthly climate can be imported from a CSV file with a header row and 12 month rows, either with the columns month, tmax, tmin, rh_mean, wind_2m, sunshine_h and rain_mm, or with month, eto_mm_day and rain_mm. The month column is required and decides where each row goes: use 1 to 12, Jan to Dec or the full month name, in any order, with every month exactly once (Sept is accepted for September); a missing, repeated or unknown month is refused. Every row must have exactly as many cells as the header, and numbers must use a point as the decimal mark: a row such as 3,5 written with a decimal comma is refused with its row number rather than read as two values. Hexadecimal, binary and octal notation is refused. Error messages give the physical line number in the file (blank lines count). Windows, Unix and old Mac line endings are all read; a quoted cell may contain the delimiter but must end on the same line.

Limits: 12 months; seasons up to 365 days; up to 2000 emitters per lateral, 500 laterals per manifold and 400 catch cans. Values outside physical ranges are refused with a message that names the field; non-zero values smaller than 1e-12 are refused rather than rounded to zero.

How we verify

The Verify page runs the same cases as the automated test suite. Validation cases reproduce published worked examples: FAO-56 Examples 2, 3, 5, 8, 9, 10, 13, 14, 15, 17, 18, 27 and 28; the effective-rainfall and irrigation-need examples of FAO Training Manual 3; the precipitation rate, set time and F-factor table of FAO Irrigation Manual Module 8; the Hazen-Williams example, F-factor table and emission-uniformity examples of Module 9; and ILRI Publication 16 Examples 8.1 to 8.3 and Table 21.9. Verification cases check closed forms (the sum-of-squares form of the F factor, the drain spacing with the impervious layer at drain level, the inversion of Manning's equation), conservation (mass and energy along a lateral, the season water ledger) and independent code (a different series for the equivalent depth, a different solver for a single outlet).

Each case declares the comparisons it must return; a case passes only when every declared comparison is present exactly once and within its tolerance, and every tolerance states why it has its size (usually the rounding of the printed example). Where a printed table disagrees with its own formula (rows N = 22 to 25 of the Module 8 F table and the N = 6 row of the Module 9 table), the row is not used and the case says so. One case, a published field catch-can test, is pending a source and is never counted as a pass.

Sources

• Allen R.G., Pereira L.S., Raes D., Smith M. (1998). Crop evapotranspiration: guidelines for computing crop water requirements. FAO Irrigation and Drainage Paper 56. FAO, Rome.
• Brouwer C., Heibloem M. (1986). Irrigation Water Management Training Manual No. 3: Irrigation Water Needs. FAO, Rome.
• Savva A.P., Frenken K. (2001, 2002). Irrigation Manual, Module 8 (Sprinkler irrigation systems) and Module 9 (Localized irrigation systems). FAO Sub-Regional Office for East and Southern Africa, Harare.
• Ritzema H.P. (ed.) (2006). Drainage Principles and Applications, ILRI Publication 16, 3rd edition. ILRI, Wageningen.

Soakline reproduces no text or table from these publications; it implements the published equations and compares its results with the published examples.

Professional use

Results are for education and preliminary design. They must be checked by a qualified professional, and they are not a substitute for code-compliant design or licensed engineering judgement. Crop coefficients, soil and emitter properties, efficiencies and drainage criteria are your inputs; Soakline does not supply design criteria or claim compliance with any standard.