Precision Irrigation Optimization

Purpose

Precision Irrigation Optimization generates zone-specific irrigation plans that maximize agronomic return per unit water while controlling pumping cost, runoff risk, and avoidable leaching.

It integrates soil properties, terrain, crop water demand, and weather to produce actionable recommendations for:

• Timing (when to irrigate)
• Application depth (how much)
• Delivery strategy (method and route)
• Cost-yield tradeoffs (whether additional water is economical)

Typical Questions This Tool Helps Answer

• Which field zones have the highest irrigation deficit score and what is the recommended prescription depth for each variable-rate zone?
• Where is moisture stress risk highest across the field, and how does the high-stress zone fraction change between conservative and fast irrigation profiles?
• If soil moisture data is unavailable, how does the slope-only heuristic prescription compare to a sensor-informed run, and where are the largest differences?

Background

Precision irrigation optimization couples crop water demand, soil storage dynamics, and operational constraints to produce schedule recommendations. A standard root-zone balance is:

$$S_{t+1}=S_t+P_t+I_t-ET_t-D_t-R_t$$

With irrigation decision variable $I_t$ selected to keep storage within agronomically acceptable depletion bounds.

Demand and Response Framing

Crop demand is often modeled with stage-sensitive coefficients:

$$ET_c=K_c\cdot ET_0$$

Where $ET_0$ is reference evapotranspiration and $K_c$ varies by crop stage. The optimization challenge is to satisfy demand while respecting delivery capacity and operational windows.

Objective Trade-Offs

Typical objective formulations balance yield protection against water and operating cost:

$$\max\big(Revenue(Y(I))-WaterCost(I)-OperatingCost(I)\big)$$

This is a multi-objective trade space in practice, even when represented as one scalar objective.

Methodological Considerations

• Align weather and soil-moisture timing with irrigation decision windows.
• Validate coefficient assumptions ($K_c$, depletion limits) against local agronomy guidance.
• Compare schedule alternatives under dry and wet scenarios before deployment.

Practical Interpretation Pitfalls

Common mistakes include over-trusting a single optimized schedule, ignoring delivery-system constraints, and treating modeled savings as guaranteed without field feedback loops.

Inputs

Parameters

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Important summary keys

Returned payload keys

The workflow returns these output keys:

• irrigation_prescription
• moisture_stress_risk
• vri_zones
• run_matrix_summary (with sweep_spec)
• sensitivity_report (with sweep_spec)
• sensitivity_report_html (with sweep_spec)
• stability_map (with sweep_spec)
• summary
• html_report

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.precision_irrigation_optimization(
    dem="field_dem_5m.tif",
    soil_moisture="soil_moisture_normalized.tif",
    profile="balanced",
    target_moisture=0.62,
    max_irrigation_mm=20.0,
    output_prefix="pivot_block_a",
)

References

• Allen, R. G., Pereira, L. S., Raes, D., & Smith, M. (1998). Crop evapotranspiration. FAO Irrigation and Drainage Paper 56.
• Irmak, S., et al. (2012). Irrigation scheduling using soil moisture and ET-based approaches. Applied Engineering in Agriculture.

Parameter Interaction Notes

• target_moisture directly changes the moisture deficit and usually has the largest effect on prescription depth.
• profile changes both terrain penalty and stress boost, so it affects irrigation depth and stress risk at the same time.
• max_irrigation_mm acts as both an output cap and the threshold basis for VRI zones 1, 2, and 3.
• If soil_moisture is omitted, the outputs become heuristic and should be treated differently from sensor-informed runs.

QA and Acceptance Criteria

1. Verify the example uses the runtime argument names exactly.
2. Verify target_moisture is within [0, 1] and max_irrigation_mm > 0.
3. Verify the summary JSON contains the documented keys.
4. Verify the returned payload includes irrigation_prescription, moisture_stress_risk, vri_zones, summary, and html_report.
5. Verify the VRI zone raster contains only 1, 2, 3, plus nodata.
6. If soil_moisture is provided from another grid, verify harmonization was acceptable before operational deployment.

The workflow fails if dem cannot be read, if optional soil_moisture cannot be read, if harmonized soil_moisture still does not match DEM dimensions, if target_moisture falls outside [0, 1], if max_irrigation_mm <= 0, or if profile is unsupported.

Advanced Operational Guidance

• Prefer supplying soil_moisture for execution-grade recommendations.
• Compare summary.high_stress_fraction across scenarios before adopting a more aggressive target moisture.
• Inspect field margins because edge cells are set to nodata where neighborhood slope cannot be computed.
• Keep scenario prefixes unique since the workflow writes a family of files from one prefix.

Implementation Patterns

• DEM-only baseline: generate a heuristic first-pass prescription.
• Sensor-informed run: add soil_moisture and compare prescription totals and stress fraction.
• Profile sensitivity run: compare fast, balanced, and conservative.
• Delivery run: package the three rasters with the JSON summary and HTML report, and record final parameters.

Related Tools

• precision_ag_yield_zone_intelligence
• yield_data_conditioning_and_qa
• in_season_crop_stress_intervention_planning

When To Use This Workflow

Use this workflow when you need a compact variable-rate irrigation package from terrain and optional moisture data, and when the goal is reproducible scenario comparison rather than a full agronomic or economic optimizer.

What this workflow helps you do:

• Produce irrigation depth and stress-risk surfaces quickly.
• Compare moisture targets and profile settings consistently.
• Hand off a complete raster-plus-summary package for operations review.

Results Delivery Checklist

1. Deliver the three rasters, the JSON summary, and the HTML report together.
2. Record whether soil_moisture was supplied or omitted.
3. Record the final profile, target_moisture, and max_irrigation_mm values.
4. Review edge-cell nodata behavior before downstream execution use.
5. Compare summary.high_stress_fraction across scenarios before finalizing the recommendation.

Common Questions

Q: Why can high_stress_fraction remain high even after increasing max_irrigation_mm?
A: Because stress is driven by moisture deficit and terrain penalty. Raising the cap does not automatically remove steep-slope stress patterns.

Q: What is the most common misread of the VRI zone raster?
A: Treating zones 1, 2, and 3 as fixed agronomic classes. They are relative prescription tiers tied to the configured max_irrigation_mm.

Q: Which settings matter most for scenario sensitivity?
A: target_moisture and profile. One changes the deficit target and the other changes terrain moderation and stress amplification.

Q: When should teams trust a DEM-only run?
A: DEM-only runs are useful for exploratory planning or gap filling. Operations should prefer a run with current soil moisture when prescriptions will drive execution.