Troubleshooting manual irrigation setup in Urban Energy Balance

General
1

Hello !

I’m currently trying to build a prototype project for a new urban district, focusing on vegetation and irrigation strategies. My final goal is to run SUEWS to obtain T2m and RH2 that I can, later, use in SOLWEIG entry datas to obtain comfort temperature and cool area.

I successfully created my .yaml file and managed to run the Urban Energy Balance: SUEWS model with it. However, I am struggling to correctly use the Database Manager to implement irrigation.

In my prototype, I want to irrigate a predefined area of green space using a fixed irrigation volume (based on the amount of reclaimed water available on site). The irrigated green space is composed of approximately one-third grass, one-third medium vegetation, and one-third trees. Since the study area covers several hectares but only a few thousand square meters of green spaces are actually irrigated, I would like to apply irrigation only to these specific areas rather than to the entire district. So my first problem is : can we do that with SUEWS, is it linked to the IrrFrac or to the grids themselves ?

In general, I believe I understood the difference between automatic irrigation and manual irrigation, and in my case manual irrigation seems more appropriate.

However, using the Database Manager, I think we are only using the automatic method ?
I tried to use it, I filled the Irrigation tab with the daily water volume and all the other parameters . After I saved my irrigation profile, I am confused about how it should be linked to the different typologies and land covers tabs (Claude AI told me it was automatically save in Typologies), and how to ensure that it is actually applied to my study site. My project is located in Paris, France.

I also tried implementing manual irrigation by:

  • setting WaterUseMethod = 1 in the YAML file,
  • modifying the meteorological input file to include a custom Wuh column,
  • modifying the irrigation fractions (IrrFrac).

Unfortunately, this did not work either.

Could someone explain the correct workflow for implementing irrigation in SUEWS, particularly when irrigation is limited to a specific portion of the study area and the total irrigation volume is prescribed ?

1 Like
2

Hi @Dreywen, thanks for such a carefully written question, and for listing what you already tried. That makes it possible to point at the exact step that is failing.

Short answer: two things are being conflated, and each on its own is enough to give you no irrigation.

The YAML key is the immediate bug. WaterUseMethod is not a current field. The current key is model.physics.water_use, and it takes observed (or 1). Unknown keys are ignored rather than rejected, so your line never took effect and the run stayed on the modelled pathway. Checked against 2026.6.5: writing it your way fails suews validate with model.physics.water_use: required physics parameter is missing, while water_use: observed validates cleanly. Worth running the validator before every run; it would have caught this in seconds.

“Manual” is not the setting you want. The automatic/manual split (ie_a, ie_m, the wuprof*_24hr profiles) lives entirely inside the modelled pathway, where SUEWS derives the daily volume itself from soil moisture deficit; “manual” there just means the portion switched off when daily rainfall exceeds 2 mm. With a fixed volume of reclaimed water you want the observed pathway, and none of those parameters are read.

Targeting part of the site: yes, via irrigation_fraction, not the grids. Within a grid SUEWS has no geometry, so irrigation cannot be aimed at a polygon. irrigation_fraction states what proportion of each land cover is irrigated, and with water_use: observed the kernel does

WUArea_i    = irrigation_fraction_i * sfr_i * SurfaceArea   [m2]
WUAreaTotal = sum over surfaces                             [m2]
depth       = wuh / WUAreaTotal * 1000                      [mm]
wu_surf_i   = depth * irrigation_fraction_i                 [mm over tile i]

The volume is spread as a uniform depth over the total irrigated area, so your one-third split needs no hand-apportioning: make the three irrigated areas equal and each class takes a third. To set each fraction, divide the irrigated area of that class by its total area in the grid. If the district is 5 ha with grass at 10% (5000 m2) of which 1000 m2 is irrigated, irrigation_fraction for grass is 0.2. Same for deciduous and evergreen (“medium vegetation” normally maps to deciduous), everything else 0. As a check, the WUArea terms should sum to your few thousand square metres.

The trap to check first. irrigation_fraction defaults to 0.0 on every surface. If they are all zero, WUAreaTotal is zero, the conversion is skipped, and the whole wuh volume is discarded with no error and no warning. I confirmed such a config validates clean today.

Smaller points on the forcing side:

  • wuh is m3 per forcing timestep for the whole grid, not mm and not per surface. Both -999 and 0 mean “no water”.
  • internalwateruse_h is subtracted before any water reaches the surfaces, on both pathways. Keep it at 0 here.
  • The checker still rejects wuh above 10 m3 (#1440). Probably fine at your scale, but you may trip it if a day’s volume is delivered in an hour or two.
  • wuh_paved and the other per-surface columns are recognised but not yet consumed by the kernel.

On the Database Manager: that is a UMEP component rather than SUEWS itself, so I would rather not guess at how its Irrigation tab maps onto typologies. @biglimp is the right person. From the SUEWS side, the parameters an irrigation profile supplies are largely the modelled-pathway inputs, which fits your impression that only the automatic method is offered there. Prescribing a volume, you can set water_use, the irrigation fractions and the wuh column directly and bypass that tab.

One question back, because it may be the root of both problems: when you say Claude told you the profile was saved automatically in Typologies, was that ordinary Claude chat, or Claude running the suews-agent? Plain chat answers about SUEWS from recall, and will produce confident, plausible detail that does not match the current schema. WaterUseMethod is a good example of the failure mode: it is the legacy name, still scattered through older material, and exactly what recall reproduces. The suews-agent instead reads the schema and source of the version you actually have installed, so it can validate your config and tell you which fields are genuinely active rather than which ones merely sound right. In Claude Code it is two commands:

/plugin marketplace add UMEP-dev/suews-agent
/plugin install suews@suews

There is an equivalent plugin for Codex. Everything I have quoted above came out of that route, which is why it quotes exact validator messages and actual model behaviour rather than general advice. If you are keeping an AI in the loop for this project, it is worth the few minutes.

One caveat for the SOLWEIG plan: T2 and RH2 come out as one value per grid per timestep, and the irrigation enters the water balance weighted by its area fraction. A few thousand square metres inside a several-hectare grid will therefore move those grid means only slightly, and SUEWS will not give you the local cooling at the patch. If that contrast is what you are after, consider giving the irrigated block its own grid.

Both the m3 units and that fixed cap are being reworked at the moment, so this part should get simpler before long.

Which version are you on? The above is checked against 2026.6.5.

Hope this helps.

1 Like
3

Hi !

Thank you @sunt05 for taking the time to write such a detailed explanation. This really helps me understand what was going wrong. I had some severe misconceptions about how irrigation work in SUEWS.

I’m indeed using ordinary free Claude Chat, to help me navigate in SUEWS. That explains why it suggested parameters that are no longer part of the current schema, (I previously had some other incorrect informations on .yaml file and the “UMEP” vs “UMEP for processing” plugins distinctions).

I’m currently using SUEWS v2026.1.28rc.

I’ll go back through my workflow and try to rebuild the irrigation setup properly using your recommendations. Not sure I will use the SUEWS-Agent (because Claude Code cost :sweat_smile: ) but I’ll consider using it if I’m too stuck somewhere in the future)

Thanks for all your help and for taking the time to explain everything about SUEWS irrigation. I’ll be happy to share the results of my next attempts on the forum, and hopefully they’ll be useful for others as well. (I’m also using Claude chat to write a detailed tutorial (for my coworkers initially) with all the steps to use SUEWS->SOLWEIG combination for irrigation, and try to include all problems encountered. If I achieve to produce a satisfaying version with all these new parameters and informations, I’ll make sure to share it here this fall so it can be fixed, improved and evolved with future updates).

Thanks again!

4

Thanks for coming back with the version, and I am glad the explanation helped.

That version is the important part, so let me correct myself before you start rebuilding: my previous post used the field names from 2026.6.5, and you are on 2026.1.28rc. The names changed in between. If you apply what I wrote verbatim it will not work, and worse, it will fail quietly rather than telling you why. Apologies for that; I should have asked which version you were on before answering rather than after.

The good news is that only the names differ. I checked the water-use kernel in 2026.1.28 line by line against 2026.6.5 and it is identical, so everything in my last post about how irrigation works still holds: the area formula, the 2 mm rainfall rule for manual irrigation, internal water use being subtracted first, and the all-zero-fractions trap. Only the YAML spelling needs to change.

For 2026.1.28, the names are:

  • waterusemethod, not water_use — all lower case, no underscores
  • the value is the number 1, not the word observed — the readable words only arrived in 2026.6.5
  • irrfrac, not irrigation_fraction

So, taking a district of 5 ha where grass covers 10% (5000 m2) and 1000 m2 of that grass is irrigated:

model:
  physics:
    waterusemethod:
      value: 1          # 1 = observed (prescribed via the wuh column)

sites:
- name: your_site
  properties:
    land_cover:
      grass:
        irrfrac:
          value: 0.2    # 1000 m2 irrigated / 5000 m2 total grass
      dectr:
        irrfrac:
          value: 0.2    # your "medium vegetation"
      evetr:
        irrfrac:
          value: 0.2
      paved:
        irrfrac:
          value: 0.0    # and likewise for the rest

Those 0.2 values are placeholders following the worked example; substitute your own irrigated-over-total ratio for each class. The wuh forcing column is unchanged, still m3 per forcing timestep for the whole grid.

One more correction, and this one matters for how you debug. I said the validator would have caught your original mistake in seconds. That is true in 2026.6.5, where the physics options became required. It is not true in your version: waterusemethod carries a default of modelled, so leaving it out — or misspelling it, as WaterUseMethod did — silently falls back to modelled with no error at all. The validator is still worth running (suews-validate on your config; note the hyphen in this version, not a subcommand), but it will not flag this particular problem. So please do check the two things by hand after you rebuild: that waterusemethod reads 1, and that your irrfrac values are not all zero. Those two silent failures are exactly what cost you the last round.

Both of the silent failures you ran into are now filed, so thank you for surfacing them: #1647 for keys being ignored without warning, and #1646 for the zero-fraction case throwing your water away. Neither should have been silent.

On the agent and the cost: do not install anything on my account. The free suews-validate and suews-schema commands ship with SuPy and catch a good deal on their own, and the forum works fine as a fallback. The reason I raised the agent was narrower than “use this tool” — it was that a general chat assistant answers from memory, so it reproduces field names from whichever version dominated its training data. That is precisely how you ended up with WaterUseMethod, and it is why this thread has now had to correct the same class of error twice, once in your setup and once in mine.

Which brings me to your tutorial, and an offer.

A SUEWS to SOLWEIG irrigation walkthrough is genuinely missing, and you are in an unusually good position to write it because you have hit the real obstacles rather than the imagined ones. But a tutorial written against a chat assistant’s recall will bake in exactly the wrong field names we have just spent two posts undoing, and once that is published and copied it becomes much harder to fix.

So rather than you writing it alone and us correcting it afterwards, how about we write it together, in the open? My suggestion:

  • You own the direction. You set the scope, decide what a new user actually needs, supply the real details of your Paris case, and judge whether each draft is any good. You are the one who knows where the workflow hurts.
  • I take on drafting the technical content, checked against the source rather than recalled, and pinned to a stated version so it does not silently rot.
  • We do it in a public thread in Show and Tell, drafting in the open so anyone can correct us as we go, and so the corrections are part of the record rather than lost in private review.

If that appeals, start a thread in Show and Tell whenever you are ready, with a rough outline of what you want the tutorial to cover and which version you are targeting, and I will pick it up from there. If you would rather draft first and have us check it afterwards, that is fine too. Either way, please do share it. Your instinct to write down the problems encountered along the way is the right one, and it is the part most tutorials leave out.

1 Like
5

Hi @sunt05 !

Thanks for all your answers and your offer, I’ll be glad to accept it, I’m in holidays right now and will return to work in September (I’m a student) so I’ll be happy to work with you on this tutorial.

I’ll come back with a translated V.0, of the tutorial that I have today, in early september.

Bye.

1 Like