Adding spatially explicit albedo for SLUCM

[Peter9192]

In this project we want to make it possible to pass spatially explicit fields for albedo and emissivity into the model.

This issue is an inventory of the steps needed to make that work.

• Add new variables to input data in WPS. See e.g. https://www.youtube.com/watch?v=xibGSLSaj6w. Basically we need to add a new entry in the geogrid table, and make sure corresponding the source data is available in the static data folder. As a shortcut for initial testing, we could manually add a new variable to the geo_em or wrfinput files after running geogrid/metgrid.
• Add variables to registry. WRF automatically generates code to initialize all model state variables, etc. The state variables for the SLUCM are registered here: https://github.com/Urban-M4/WRF/blob/0a11865f97680fdd6865b278ea29d910e5db3ed7/Registry/Registry.EM_COMMON#L819-L835 Evidently, albedo and emissivity are missing, so they need to be added. See https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/software.html#registry. If I understand correctly, if we set this to be an 'input' variable, it will automatically read it from the wrfinput.
• Use the new state variables in the code. The urban canopy model code lives here, and e.g. the albedo is used here: https://github.com/Urban-M4/WRF/blob/0a11865f97680fdd6865b278ea29d910e5db3ed7/phys/module_sf_urban.F#L914-L919 NB variables are defined here: https://github.com/Urban-M4/WRF/blob/0a11865f97680fdd6865b278ea29d910e5db3ed7/phys/module_sf_urban.F#L233-L238 and are currently initialized as fixed values: https://github.com/Urban-M4/WRF/blob/0a11865f97680fdd6865b278ea29d910e5db3ed7/phys/module_sf_urban.F#L486-L487 The URBPARAM table is read in subroutine urban_param_init: https://github.com/Urban-M4/WRF/blob/0a11865f97680fdd6865b278ea29d910e5db3ed7/phys/module_sf_urban.F#L2099-L2473 And the values for each grid point are then inferred in subroutine read_param: https://github.com/Urban-M4/WRF/blob/0a11865f97680fdd6865b278ea29d910e5db3ed7/phys/module_sf_urban.F#L1998-L2000 To change this, I think the easiest option is to change the relevant lines (e.g. 914-919) to use a different variable, which could be added as one of the input (and output!?) variables to the model, similar to e.g. nudapt params here: https://github.com/Urban-M4/WRF/blob/0a11865f97680fdd6865b278ea29d910e5db3ed7/phys/module_sf_urban.F#L392-L402 These variables then also need to be added as input to the subroutine, not sure whether they are passed directly to the urban subroutine, similar to here: https://github.com/Urban-M4/WRF/blob/0a11865f97680fdd6865b278ea29d910e5db3ed7/phys/module_sf_urban.F#L319 or to urban_var_init as in here https://github.com/Urban-M4/WRF/blob/0a11865f97680fdd6865b278ea29d910e5db3ed7/phys/module_sf_urban.F#L2592 They also need to be passed in where the corresponding subroutines are called, e.g. here https://github.com/Urban-M4/WRF/blob/0a11865f97680fdd6865b278ea29d910e5db3ed7/phys/module_physics_init.F#L3331

so far so good. I'm gonna see how far I get with this.

TODO: compare Jisk/wudapt/nudapt approaches

[Peter9192]

I made a call graph to see how data flows through wrf into the urban scheme.

flowchart TD
    subgraph init
    start_domain --> |grid| start_domain_em
    start_domain_em --> |urb2d| phy_init
    phy_init --> |urb2d| bl_init
    bl_init --> |urb2d| urban_var_init
    bl_init --> |urb2d| urban_var_init
    end 

    subgraph physics
    solve_em --> |grid| first_rk_step_part1
    first_rk_step_part1 --> |urb2d| surface_driver

    surface_driver ==> |urb2d| clmdrv
    clmdrv --> |urb0d init | urban

    surface_driver ==> |urb2d| lsm
    lsm --> |urb0d | urban

    surface_driver ==> |urb2d| lsm_mosaic
    lsm_mosaic --> |urb0d | urban
    lsm_mosaic --> |urb0d | urban

    surface_driver --> |urb2d| noahmp_urban 
    noahmp_urban -->  |urb0d| urban
    end

Notice that:

• subroutine urban_var_init gets 2d arrays
• subroutine urban gets scalar values only, i.e. one grid point at a time
• all subroutines that call urban have a block that maps from 2d to scalar just before the call (and for some vars also after it)
• high in the tree, WRF simply passes on the grid. The grid contains all state variables, so we don't have to worry about passing on parameters down the call tree until the individual variables are first dereferenced from the grid. Therefore I excluded the upper part of the call tree.
• subroutine clmdrv sets most nudapt params to 0 (initial values??). The other callers of urban set it to actual values from the input array. They seem to be copies of each other.
• some routines have multiple calls to urban or urban_var_init. Again, they seem to be copies of each other.

[Peter9192]

More notes:

subroutine urban_var_init:

• initialize all 2d arrays with zeros(?) or some other relevant value

subroutine urban_param_init:

• Called by bl_init
• Parse urban parameters from table into local arrays
• table is parsed once and local arrays are stored in module scope of urban scheme
• if use_wudapt_lcz: use URBPARM.TBL
• if use_wudapt_lcz: use URBPARM_LCZ.TBL
• local arrays look like: HGT_TBL(ICATE), i.e. they all have _TBL and hold 3 or 10 categories
• some parameters are calculated based on values from the table, e.g. SVF_TBL (sky view factor for each urban category)

subroutine read_param:

• sets value of urban parameters from table
• get param from local table arrays by urban type
• e.g. SVF = SVF_TBL(UTYPE)

subroutine urban:

• call read_param: initially get all params from table
• nudapt modification: if mh_urb > 0,
  • (re)calculate street and building width based on nudapt inputs
  • overwrite urbparam table values with those from nudapt
    • ZR = mh_urb (mean building height)
    • R = lp_urb (plan area fraction)
    • RW = 1.0-R (1 - plan area fraction)
    • HGT = mh_urb/(BW+SW) (normalized height)
    • SIGMA_ZED = stdh_urb (standard deviation of building height)
    • lambda_f = lf_urb (frontal area index; something to do with wind dir)
    • Lots of geometry calculations based on Macdonalds ZDC, Z0C, lambda_fr, Z0R, Z0HC
    • Calculate sky view factor VFWS, SVF