Bug / Feature Request: Enforce 0mm cap in deficit model to prevent phantom water buffers

[Megalos]

Hi all, I had the following thoughts and idea. Let me know what you think. Thanks!

Issue: Inconsistent Soil Moisture Conventions (Deficit vs. Absolute)

In irrigation theory, soil water balance bucket models typically follow one of two conventions:

1. Deficit Convention: A value of 0 mm represents Field Capacity (FC) — the maximum moisture the soil can retain against gravity. Negative values represent a moisture deficit (down to the Wilting Point). Any precipitation exceeding FC cannot be stored and is lost to surface runoff or deep percolation.
2. Absolute Content Convention: A value of 0 mm represents the Wilting Point, while Field Capacity is represented by a positive maximum bucket capacity (e.g., +20 mm).

The integration currently mixes both conventions. It resets the bucket to 0 mm after a full irrigation (following the Deficit Convention), yet it treats maximum_bucket as a positive upper limit above 0 mm (e.g., allowing the bucket to accumulate up to +20 mm). Physically, soil in a deficit model cannot store water beyond Field Capacity (0 mm); excess rainfall simply drains away past the root zone.

---

Consequence: Phantom Water Reserves Leading to Under-Irrigation

Mixing these conventions creates an unrealistic "water buffer" after heavy rainfall.

Example:

• The root zone is at Field Capacity (bucket = 0 mm).
• A heavy storm adds 20 mm of rain, pushing the bucket to +20 mm.
• With a daily Evapotranspiration ($ET_a$) of 2 mm/day, the integration calculates that no irrigation is needed for the next 20 / 2 = 10 days.

In reality: That excess 20 mm of gravitational water percolates deep into the subsoil within 24-48 hours and is out of reach for the roots. By day 10, the soil has actually built up a deficit of -16 mm to -20 mm, severely exceeding the Management Allowed Depletion (MAD) threshold (typically 50% of FC, or -10 mm in this setup). This results in unexpected plant drought stress.

---

Proposal: Enforce Deficit Clamping and MAD-Based Triggers

1. Clamp bucket at 0 mm in Deficit Mode: Strictly cap the maximum bucket value at 0 mm. Any precipitation occurring when bucket = 0 mm should be discarded, accurately reflecting runoff and deep percolation.
2. Promote MAD-based Irrigation Triggers: Encourage triggering irrigation only when the deficit reaches the Management Allowed Depletion (MAD) threshold (e.g., at -10 mm), replenishing the bucket back to 0 mm.

Benefits:

• Eliminates phantom water buffers after heavy rain.
• Aligns the codebase with physical soil-water dynamics (FAO-56 standard).
• Encourages healthier, deep-and-infrequent watering practices that foster deep root growth.

[altmenorg]

@Megalos apologies for the six weeks of silence on this. It deserved an answer, and it turns out half of it is now shipped.

Your second proposal is in v2026.9.0

Triggering on the management allowed depletion rather than on the first millimetre missing is exactly what the new per-zone Irrigation threshold does. Below it a zone waters nothing; once the deficit reaches it, the run covers the whole deficit. Set it to 0 and you get the old behaviour, which is the default so nobody's setup changed under them.

It came in through #815, from a different direction (someone wanting deep, infrequent watering for trees), and I did not connect it to this discussion at the time. You proposed it first, in July.

Your first proposal: the physics is right, the arithmetic is milder than you think

Your worry is a real one, and it is the right way round: gravitational water above field capacity drains past the root zone within a day or two and should not be counted on. But the phantom reserve you describe does not survive our defaults, because drainage is not linear.

Drainage is applied only above 0, scaled by (bucket / maximum_bucket) raised to the fourth power, at a default rate of 50.8 mm/h. That curve is very steep at the top. With the default 24 mm maximum bucket:

Surplus	Drained in one day	Left the next morning
20 mm	more than the surplus	0 mm
10 mm	more than the surplus	0 mm
5 mm	2.3 mm	2.7 mm
3 mm	0.30 mm	2.7 mm
2 mm	0.06 mm	1.9 mm

So your worked example, 20 mm of rain buying ten dry days, does not happen: that surplus is gone by the next calculation.

What does happen is the small version of it, and it is the opposite end of your example. A surplus of two or three millimetres barely drains at all, because the fourth power makes the curve nearly flat down there. It sits until evapotranspiration eats it, which at 2 mm/day is about a day. So the effect you describe is real, bounded to a couple of millimetres and roughly one day, rather than to 20 mm and ten days.

Whether that is worth clamping is a genuine question. Clamping at 0 would also discard water that really is available in the first hours after rain, which is not nothing. My inclination is to leave the model alone and be honest about the residue, but I would rather hear your view than decide it alone.

The case that does behave the way you describe is a zone with its drainage rate set to 0 and a large maximum bucket. Then nothing removes the surplus and your ten days are exact. That combination is reachable from the UI today and nothing warns about it. That is worth addressing, and it is a smaller change than reworking the convention.

On the convention itself, you were right and the documentation was wrong

You said the integration mixes the deficit and absolute conventions, and that the documentation confuses field capacity with the maximum bucket. That is correct, and the documentation said so literally: the Maximum bucket entry described itself as "the soil's water holding capacity", which it is not. It caps the surplus held above field capacity before the rest runs off, and it doubles as the saturation reference for the drainage curve above. It has no effect at all on the deficit side, so it never changes when a zone starts watering.

That is fixed, along with a second place where I had repeated it: the new irrigation threshold told people to derive their value from the maximum bucket. It now carries the actual method, total available water times a depletion fraction, as you set out here.

Thank you for writing this up properly. It has been the most useful thing in the tracker this week, and it should not have sat unanswered.

[Megalos]

Thanks @altmenorg for taking a critical look at this! :)

Regarding the MAD-based trigger for irrigation: indeed, this is now available in the latest version through the irrigation threshold. That's a very useful feature.

Regarding the maximum bucket value cap: you're right that in my example I implicitly assumed a drainage rate of 0 mm/h. The reason for this is that this is currently what the documentation recommends. The default drainage rate is indeed 50.8 mm/h, but the documentation advises starting with 0 mm/h: https://altmenorg.github.io/HAsmartirrigation/configuration-zones.html. This recommendation seems to originate from an older discussion where @jeroenterheerdt mentioned that there might be a bug and suggested setting the drainage rate to 0 mm/h for the time being: https://community.home-assistant.io/t/smart-irrigation-save-water-by-precisely-watering-your-lawn-garden/197377/694. I'm not sure whether that was actually a bug, or whether it was related to the confusion between the two different bucket conventions. In any case, I agree that simply capping the bucket at 0 mm is not a good substitute for having a proper drainage rate. In this case, I think the documentation should probably be updated so that it no longer recommends setting the drainage rate to 0 mm/h as the default approach.

Regarding the Maximum bucket value,I am still unsure about the ideal value for the Maximum Bucket field. Since the drainage rate relies on the (bucket/maximum_bucket)^4 formula, getting this value right is critical.

The current documentation links this to Available Water Capacity (AWC), but that logic only applies to the Absolute Content Convention, not the Deficit Convention as the integration seems to use. Until we have a better alternative, it might be best to stick with the values from the referenced discussion for now (which appear to use the Management Allowed Depletion (MAD), or 50% of the AWC).

I'm curious to learn in case you find a better suitable reference value for the Maximum bucket entry :).

[Megalos]

A possible next step could be to make the drainage calculation more continuous.

Currently, the drainage rate is effectively calculated from the resulting bucket value and then applied over the entire calculation interval (typically 24 hours). Because the drainage rate depends strongly on the bucket value through (bucket / maximum_bucket)^4, this can significantly overestimate drainage: as the surplus drains away, the drainage rate should decrease as well.

For example, with the default maximum_bucket = 24 mm and drainage_rate = 50.8 mm/h, a surplus of 8 mm is currently calculated as being completely drained within the 24-hour interval. However, if the drainage rate is recalculated continuously as the bucket decreases, only about 3.7 mm would drain over 24 hours, leaving roughly 4.3 mm of surplus.

An hourly drainage update could already improve this substantially. Open-Meteo provides hourly precipitation data, so the integration could process the water balance chronologically, hour by hour, and recalculate the drainage rate after each step.

This would also address another source of inaccuracy: the timing of precipitation within the calculation interval.

For example, there is a large physical difference between:

• 8 mm of rain falling at 01:00, giving the surplus almost an entire day to drain before the next calculation; and
• the same 8 mm falling at 22:00, giving it only a short time to drain.

With the current daily calculation, this timing difference is not really taken into account, and the calculated drainage can end up being essentially the same in both cases. In the second example this can significantly overestimate drainage, because the positive surplus has only existed for a short period of time.

Using the hourly precipitation data already available from the weather provider could avoid this. The integration could update the bucket sequentially, for example:

previous bucket
+ hourly precipitation
- hourly ET (also available from Open-Meteo)
- drainage calculated from the current positive bucket
= new bucket

The drainage rate would then be recalculated for the next hour using the updated bucket value.

This would preserve the useful concept of a temporary positive bucket above field capacity, while making both the drainage rate itself and the timing of rainfall much more realistic. It should therefore result in considerably more accurate bucket estimates, especially after heavy rainfall or rainfall late in the calculation period.

Would this make sense? I'm not sure how easy or difficult this would be to implement.

[altmenorg]

@Megalos this has waited eleven days, and your 4 September reply seventeen. Both deserved better, and the second one turns out to prove me wrong, so let me start there.

You are right, and my table of 4 September was wrong

On 4 September I told you a 20 mm or 10 mm surplus was gone by the next calculation, and built a table on it. That table came from the formula in the code, which is exactly the formula you are now showing overestimates drainage. So I rebutted your concern with the very thing that was wrong.

What the code does today: it evaluates the drainage rate once, from the bucket after the interval's rain, multiplies it by the whole interval, and clamps at zero. For a law as steep as (bucket / maximum_bucket)^4 that is a single 24-hour step, and it drains far too much, because the rate should fall as the surplus drains.

The model means a rate law, dB/dt = -r (B/M)^4, and that has an exact solution for a constant rate, so no hourly stepping is needed for this part:

B(t) = [ B0^-3  +  3 r t / M^4 ]^(-1/3)

With the defaults, M = 24 mm, r = 50.8 mm/h, over 24 hours:

Surplus after rain	Left next morning, today	Left next morning, exact
20 mm	0.00 mm	4.48 mm
10 mm	0.00 mm	4.36 mm
8 mm	0.00 mm	4.26 mm
5 mm	2.70 mm	3.75 mm
3 mm	2.70 mm	2.75 mm
2 mm	1.94 mm	1.94 mm

The 8 mm row is your example to the hundredth: 3.74 mm drained, 4.26 mm left. The 2 and 3 mm rows of my table were right, because the curve is nearly flat down there and one step is close enough. From 5 mm up they were not.

There is a property in that column worth having. Whatever the storm, the exact solution cannot leave more than [3 r t / M^4]^(-1/3) above field capacity after t hours, which with the defaults is 4.49 mm after a day. So your original fear, a 20 mm storm buying ten dry days, does not happen either: the reserve it leaves is about two days of evapotranspiration. The truth was between us, and nearer your side than I said.

The fix is to use that solution in place of the single step. It is a contained change to one expression, it matches the rate law the model already claims to use, and it can be tested against the equation directly rather than against a remembered number. I want it in the next beta.

The drainage rate of 0 that our documentation recommends

You pointed out that you assumed a drainage rate of 0 because that is what the documentation tells people to start with, and it does, word for word. It also contradicts the code, whose default is 50.8 mm/h.

That matters more than it looked. With a rate of 0 nothing removes a surplus at all, so for anyone who followed the documentation, your original ten-day example was exact. I was answering with the defaults while our own documentation told people not to use them.

The recommendation goes. It dates from an old workaround and, with the drainage computed as above, starting at 0 is simply the case where the model cannot drain.

Your question about the Maximum bucket

You asked for a better reference than available water capacity, and you were right that AWC belongs to the other convention. In the deficit convention, 0 is field capacity and everything above it is gravitational water on its way out. So the maximum bucket is how much water the root zone can hold above field capacity before it is saturated:

maximum bucket = (saturation - field capacity) x root depth

That difference is the soil's drainable porosity. The texture-class averages in Rawls, Brakensiek and Saxton (1982) put it near 0.35 for sand, 0.19 for loam and 0.08 for clay, which for a 20 cm root zone is about 70 mm, 40 mm and 15 mm. Take those as indicative: they move with how field capacity is defined, and a real soil is not a class average. The default 24 mm is a loam over a shallower root zone.

It is also the reference the drainage curve is built around: (B/M)^4 reaches the full rate at B = M, which is saturation. The drainage rate at saturation is then the saturated hydraulic conductivity, which the same averages give as roughly 210 mm/h for sand, 26 for sandy loam, 13 for loam and under 1 mm/h for clay. The default 50.8 sits between loamy sand and sandy loam, so it is fast for most garden soils.

So both parameters come from measurable soil properties rather than from experimenting, and the documentation should say that instead of what it says now.

Rain timing within the interval

This is the other half of your message and it is right as well: 8 mm at 01:00 and 8 mm at 22:00 should not drain the same, and a daily step cannot tell them apart. The exact solution above assumes the whole surplus is there from the start of the interval, so it still overestimates drainage for late rain, less than today but not by nothing.

Doing it properly means stepping the balance through the hours as you set out, and the hourly rain is now there for Open-Meteo, since @frankyhun's change in #836 reads its hourly history. But it is the same piece of work as the hourly evaporation in #818: an hourly water balance rather than a daily one. I would rather build that once, carefully, than bolt a sub-daily drainage onto a daily evaporation.

So: the exact drainage now, the documentation now, the hourly balance as the next real project with #818. Thank you, and I am sorry it took this long.

[altmenorg]

Both of the things I said would happen now are on dev:

• The exact drainage, in 0ea7f6b. Your 8 mm example now gives 3.74 mm drained and 4.26 mm left, and the calculation explanation shows the closed form instead of the old product. The tests check it against the rate law integrated numerically, so they do not just restate the formula; on the old code seven of them fail. Nothing tested drainage before, which is how it survived.
• The documentation, in 8b43d6b. The "start with 0 mm/h" recommendation is gone, and the drainage rate is described as the saturated hydraulic conductivity. The maximum bucket entry now gives the drainable porosity over the root depth.

One more thing came out of that last part, and it is yours as much as mine. The page recommended 30 mm for clay and 12 mm for sand. Above field capacity it is sand that has more room, not clay: those figures were closer to the available water capacity of the other convention, and inverted for this one. That is the confusion you described on 4 September, and it had made it into the recommended values themselves.

The tests also turned up a crash next to the drainage: a zone with no maximum bucket, which clearing the field in the panel produces, took its whole calculation down in the explanation. Fixed with it.

Both will be in the next beta. The hourly balance stays the next real piece, with #818.

[altmenorg]

@Megalos the exact drainage is released in v2026.9.1-beta2: your 8 mm example now drains 3.74 mm and leaves 4.26, and a test integrates the rate law step by step to check it. The documentation no longer recommends a drainage rate of 0, and derives the drainage rate and the maximum bucket from the soil.

The same beta has the hourly evapotranspiration from #818 behind a switch, which is the first half of the hourly water balance you described. Thank you again for the arithmetic.

[Megalos]

Thanks @altmenorg! Replaying of both the evapotranspiration, precipitation and drainage is indeed the right approach, together with the continuous version of the drainage calculation. Thank you for explaining. I'll test for a few days after I return from a small stay in Mallorca this week 😉