WRF-urban-NbS development

[chenghaow]

Development of the WRF-urban-NbS module within the single-layer urban canopy model

TYPE: new feature

KEYWORDS: urban canopy models, urban trees, nature-based solutions, urban grass, urban hydrology, radiative view factors

SOURCE: Yuqi Huang (University of Oklahoma), Chenghao Wang (University of Oklahoma), Cenlin He (NCAR)

DESCRIPTION OF CHANGES:
Problem: The current WRF-urban modeling system employs a single-layer urban canopy model (SLUCM) that assumes a dry street canyon. While a green roof module exists, ground vegetation and street trees are not represented. As a result, key nature-based solution (NbS) processes such as evapotranspiration, radiative shading, and soil–vegetation–atmosphere interactions are not captured. In addition, radiative exchanges involving trees are not explicitly resolved. A version of the urban tree module within SLUCM was developed and tested for the contiguous U.S. but only accounted for shading in a simplified way:

• Wang, C., Wang, Z. H., & Yang, J. (2018). Cooling effect of urban trees on the built environment of contiguous United States. Earth's Future, 6(8), 1066–1081. https://doi.org/10.1029/2018EF000891

Solution:
This PR introduces urban ground vegetation and street trees into the single-layer urban canopy model. Round-shaped urban trees are explicitly represented, resolving evapotranspiration, shading, and root water uptake. Radiative exchanges between trees and surrounding urban elements are solved using newly implemented analytical view factors.
The development is largely based on the Arizona State University Single-Layer Urban Canopy Model (ASLUM v3.1) and its hydrologically enhanced version, ASLUM-Hydro, and extends their capabilities within the WRF-Urban framework. See the following two papers for ASLUM v3.1 and ASLUM-Hydro:

• Wang, C., Wang, Z. H., & Ryu, Y. H. (2021). A single-layer urban canopy model with transmissive radiation exchange between trees and street canyons. Building and Environment, 191, 107593. https://doi.org/10.1016/j.buildenv.2021.107593
• Huang, Y., Wang, C., & Wang, Z. H. (2025). Multi-parameterization of hydrological processes in an urban canopy model. Building and Environment, 113567. https://doi.org/10.1016/j.buildenv.2025.113567

ISSUE: NA

LIST OF MODIFIED FILES:
The following files were modified (generated using git diff --name-only master urban_nbs):

• Registry/Registry.EM_COMMON
• dyn_em/module_first_rk_step_part1.F
• dyn_em/start_em.F
• phys/module_physics_init.F
• phys/module_sf_clm.F
• phys/module_sf_noahdrv.F
• phys/module_sf_urban.F
• phys/module_surface_driver.F
• run/URBPARM.TBL
• run/URBPARM_LCZ.TBL
• run/URBPARM_UZE.TBL
• wrftladj/module_physics_init_ad.F
• wrftladj/module_physics_init_tl.F
• wrftladj/start_em_ad.F
• wrftladj/start_em_tl.F

TESTS CONDUCTED:

• Successfully tested in offline mode coupled with the HRLDAS system
• Demonstrated systematic performance improvements across 20 global urban sites when evaluated against flux-tower observations from the Urban-PLUMBER project
• Successfully compiled on the NCAR Derecho system
• Short-term online WRF simulations are currently ongoing

Note:
Successful compilation requires Noah-MP-related source files that are not included in WRF v3.7.1, including a modified version of module_sf_noahmpdrv.F. These changes will be addressed in a separate PR dedicated to Noah-MP.

RELEASE NOTE:
Manuscripts in development:

• Huang, Y., Wang, C., & He, C. Integrating nature-based solutions into the WRF-urban modeling system. Manuscript in prepration.
• Wang, C., Huang, Y., Miller, D. L., Katz, D., & Ghosh, A. K. Analytical view factors for urban canopy models with trees: model development and case study in New York City. Manuscript in preparation.

[cenlinhe]

This PR will fail the regression test because the NoahMP link has not been updated yet. The developers are working to update the noahmp github for this changes and will update the commit soon once the noahmp link is updated.

[weiwangncar]

@chenghaow This PR fails for multiple tests when real*8 is used. To try real*8 compilation, do configure -r8. A sample compilation output is attached here.
output_10.txt

[chenghaow]

@weiwangncar Thanks for sharing the compilation log. We found that the issue is caused by an inconsistency in module_sf_urban.F between WRF v4.7.1 and HRLDAS (specifically the DLOG function). To address this, we (1) commented out the double-precision-related code inherited from the HRLDAS urban module, and (2) restored the distributed aerodynamic roughness length code that had been removed from the HRLDAS urban module. We are now testing the compilation on our end on Derecho.

@cenlinhe I'll open a separate issue in the HRLDAS repo on this.

[cenlinhe]

yes, Noah-MP uses a different double precision flag (DOUBLE_PREC) than WRF (DOUBLE_PRECISION). My NoahMPv5 coupling will resolve this issue, but it's good that you reverted back to the original WRF-Urban treatment. Please make sure that you did not remove any other default urban code in the WRF version (do not use HRLDAS version).

[chenghaow]

yes, Noah-MP uses a different double precision flag (DOUBLE_PREC) than WRF (DOUBLE_PRECISION). My NoahMPv5 coupling will resolve this issue, but it's good that you reverted back to the original WRF-Urban treatment. Please make sure that you did not remove any other default urban code in the WRF version (do not use HRLDAS version).

Sure. We will keep the double precision flag in the offline version though.

[cenlinhe]

HRLDAS version of the urban code may lag a few recent WRF-Urban updates.

[chenghaow]

The current version successfully compiled on Derecho with ./configure -r8

[weiwangncar]

@chenghaow The last regression tests failed on three cases. Attached is the output file from this group of tests (search for kiaps2):
output_19.txt

[cenlinhe]

This PR needs to be merged first before the refactored NoahMP coupling PR (#2268) because this PR modifies the non-refactored NoahMP urban driver. Once this urban PR is merged, I will need to update the Noah-MP urban driver in the refactored code and hence the refactored NoahMP coupling PR above to avoid any merge conflicts.

[chenghaow]

@weiwangncar Looks like our recent fix failed the regression tests. Would you please share the output file? Thanks!

[weiwangncar]

@chenghaow See attached file here (tests for kiaps2 namelists):
output_19.txt

[weiwangncar]

@chenghaow The last commit caused failed compilation with errors like these:

module_sf_urban.f90:2066:45:

 2066 |          DTB = SIGN(MIN(ABS(DTB), max_step), DTB) 
      |                                             1
Error: 'b' argument of 'sign' intrinsic at (1) must be the same type and kind as 'a'
module_sf_urban.f90:2067:45:

 2067 |          DTG = SIGN(MIN(ABS(DTG), max_step), DTG) 
      |                                             1
Error: 'b' argument of 'sign' intrinsic at (1) must be the same type and kind as 'a'
module_sf_urban.f90:2068:47:    

 2068 |          DTVG = SIGN(MIN(ABS(DTVG), max_step), DTVG)
      |                                               1 
Error: 'b' argument of 'sign' intrinsic at (1) must be the same type and kind as 'a'

[chenghaow]

Hi @weiwangncar We just fixed some unit-related bugs, but this updated version failed the regression tests. Our compilation succeeded on Derecho, though. Would you please share the output file when you have a moment? Thanks.

[weiwangncar]

@chenghaow The latest commit failed the same tests. Here is the output:
output_19.txt
Here is the namelist.input file for this test. You can run it locally to see if it could. Use gfortran if you can when compile.
namelist.input.kiaps2.txt

[weiwangncar]

@chenghaow To compile KIAPS radiation option, edit configure.wrf, and search for -DBUILD_RRTMK=0, and changes the value to 1.

[weiwangncar]

@chenghaow On Derecho, you can find the data used by regression test in /glade/derecho/scratch/weiwang/Data/em_real/.

[weiwangncar]

@chenghaow The last commit resulted in only one run failure: the MPI run using namelist.input.kiaps2. The serial and OpenMP runs have completed.