RSL diagnostics: docs and docstrings out of step with the code (level scheme, switch criteria, RSLLevel, MOST reference height)

[sunt05]

Summary

Four places where the documentation or docstrings for the near-surface diagnostics (roughness_sublayer, roughness_sublayer_level, the RSL profile) describe behaviour the code does not have, or omit behaviour it does have. Each was checked against src/suews/src/suews_phys_rslprof.f95 and src/suews/src/suews_ctrl_driver.f95 at tag 2026.6.5 (unchanged on master for these points). Two recent forum threads on the T2 response to tree cover and on MOST versus RSL comparability turned on exactly these gaps.

1. In-canopy level scheme

docs/source/parameterisations-and-sub-models.rst, section "Wind, Temperature and Humidity Profiles in the Roughness Sublayer" (around lines 243 to 261), says the number of in-canopy levels n_can is 3, 10 or 15 depending on z_H (thresholds 2 m and 10 m).

The code uses a fixed split: nz_can = 20, nz_above = nz - nz_can = 10 (suews_phys_rslprof.f95, RSLProfile, around lines 468 to 469 on master). The later section "RSL and SS Canopy Representation" (line 382) already states the 20/10 split correctly, so the file contradicts itself.

2. Automatic switch criteria

Three surfaces say the automatic MOST/RSL selection uses plan area index, frontal area index and roughness-element height:

• src/supy/data_model/core/model.py, RSLMethod docstring, option 2.
• docs/source/inputs/tables/RunControl/csv-table/DiagMethod.csv, code 2.
• docs/source/inputs/yaml/config-reference/modelphysics.rst, roughness_sublayer entry (generated from the docstring).

The code uses only 0.1 < PAI < 0.68 and zH > 2 (suews_phys_rslprof.f95 around lines 443 to 463 on master). The FAI bound is commented out with a note that the earlier constraint "seems wrong anyway". Either the docstring drops FAI, or the code gets its FAI criterion back; this issue asks for the docs to match the code as it stands.

3. roughness_sublayer_level docstring is incomplete

RSLLevel in src/supy/data_model/core/model.py describes only the DailyState branch (LAI and GDD adjustments for urban temperature). It omits that the driver also uses the level to choose which air temperature feeds the anthropogenic-heat and surface-conductance calculations: the forcing temperature for none, the diagnosed T2 for basic, a building half-height temperature for detailed (suews_ctrl_driver.f95 around lines 1408, 1583 and 3967 on master). This is the pathway through which a jump in the diagnosed T2 leaks into QF and QE, and users cannot find it from the docs.

4. Reference height of the MOST diagnostics is undocumented

Under RSL, T2, Q2 and U10 are interpolated at 2 m and 10 m above ground. Under MOST they are interpolated at 2 + zd + z0m and 10 + zd + z0m above ground (suews_phys_rslprof.f95 lines 618 to 628 at tag 2026.6.5). Nothing in the user docs says so. On a site with 22 m buildings the MOST "2 m" value sits about 18 m above ground, and the two schemes' "T2" differ by roughly 1 K in a summer daytime mean with nothing else changed. Users switching schemes, or running the automatic switch across a city, need this stated in the roughness_sublayer reference entry and in the RSL section, together with the point that the MOST convention is the standard one (the same as WRF's surface-layer diagnostics and CLM's 2 m temperature) and that the two schemes therefore report different quantities.

Exposing the actual sampling height as an output column would close this properly, but that is a code change and can be a separate issue once the convention is documented.

Proposed scope

Docs and docstrings only, one PR:

• Fix the level scheme text in parameterisations-and-sub-models.rst to the fixed 20/10 split.
• Remove FAI from the automatic-switch description in the RSLMethod docstring and DiagMethod.csv, then regenerate the config reference.
• Extend the RSLLevel docstring with the air-temperature selection for anthropogenic heat and surface conductance.
• Add a short subsection on the reference height of the MOST and RSL diagnostics, with the numbers above as an illustration, cross-linked from the roughness_sublayer entry.

Optional code hygiene in the same area, if a maintainer wants it in a separate PR: cd_tree and a_tree in suews_phys_rslprof.f95 are declared and never used.