Add WPS new data for global 1-km urban parameters (Liao et al 2025)

[cenlinhe]

This PR is to add new WPS dataset for global 1-km urban parameters (URB_PARAM) based on the new GloUCP data for year 2020 conditions (Liao et al 2025) and global 1-km urban/impervious surface fraction (FRC_URB2D and IMPERV) based on the Global Artificial Impervious Area (GAIA) dataset for year 2020 conditions (Gong et al. 2020).

The default URB_PARAM, FRC_URB2D and IMPERV variables are based on the outdated NLCD and NUDAPT urban data for year 2010 and only available over continental US. The new data covers global urban areas and is more updated. Thus, in this PR, I give higher data priority to these new datasets by default.

The WPS-compatible data with index files are available here on Derecho:
For URB_PARAM: /glade/work/wrfhelp/WPS_GEOG/gloucp2020_30s
For FRC_URB2D (0-1, fraction): /glade/work/wrfhelp/WPS_GEOG/urbfrac_gaia2020_30s
For IMPERV (0-100, percent): /glade/work/wrfhelp/WPS_GEOG/impfrac_gaia2020_30s

These datasets should be also be made available on the WRF data website (https://www2.mmm.ucar.edu/wrf/users/download/get_sources_wps_geog.html)

Tests have been done successfully by Cenlin He (NCAR) on Derecho.

Raw datasets are available for downloading: https://figshare.com/articles/dataset/_b_GloUCP_b_A_global_1_km_spatially_continuous_urban_canopy_parameters_for_the_WRF_model_/27011491

References:

• Liao, W., Li, Y., Liu, X., Wang, Y., Che, Y., Shao, L., Chen, G., Yuan, H., Zhang, N., and Chen, F.: GloUCP: a global 1 km spatially continuous urban canopy parameters for the WRF model, Earth Syst. Sci. Data, 17, 2535–2551, https://doi.org/10.5194/essd-17-2535-2025, 2025.
• Gong, P., Li, X.C., Wang, J., Bai, Y., Chen, B., Hu, T.Y., Liu, X.P., Xu, B., Yang, J., Zhang, W., & Zhou, Y.Y. 2020. Annual maps of global artificial impervious areas (GAIA) between 1985 and 2018. Remote Sensing of Environment, 236, 111510. doi: 10.1016/j.rse.2019.111510.

[cenlinhe]

@tslin2 @smileMchen Could you please do an independent test for these two datasets? Thanks!

[smileMchen]

Hi Cenlin,
I have run a few tests using the new global urban data. The test areas cover North America and East Asia, with the resolution of 15km and 3km respectively. WPS works fine and can well process the new data. The only issue I have seen is that, IMPERV and FRC_URB2D have same values, except that their units are different. Please confirm this is correct. Plots of FRC_URB2D and IMPERV are posted below.

[smileMchen]

FRC_URB2D.pdf
IMPERV.pdf

[cenlinhe]

Hi Ming, yes, the FRC_URB2D and IMPERV should be the same (units are different) since they are both derived from the 1-km Global Artificial Impervious Area (GAIA) dataset for year 2020 conditions (Gong et al. 2020).

[smileMchen]

Hi Ming, yes, the FRC_URB2D and IMPERV should be the same (units are different) since they are both derived from the 1-km Global Artificial Impervious Area (GAIA) dataset for year 2020 conditions (Gong et al. 2020).

Hi Cenlin,

Thank you for the confirmation. In this case, I wonder whether it is necessary to keep two variables. Probably one is enough because we can easily derive the other from the available one. But it is fine for me to keep both variables considering the consistency between different WPS versions.

[cenlinhe]

I think these two variables are required by different model schemes and they have different units, so it is better to keep both following the previous WPS.

[tslin2]

@cenlinhe @smileMchen Should this be added to other GEOGRID.TBL.ARW files, such as GEOGRID.TBL.ARW.noahmp, GEOGRID.TBL.ARW_LCZ?

Thanks

[cenlinhe]

@cenlinhe @smileMchen Should this be added to other GEOGRID.TBL.ARW files, such as GEOGRID.TBL.ARW.noahmp, GEOGRID.TBL.ARW_LCZ?

Thanks

Yes, you are right, this should be added to those other GEOGRID tables as well. Thank you for the note! I will update those files and this PR.

[tslin2]

@tslin2 @smileMchen Could you please do an independent test for these two datasets? Thanks!

My WPS test run is fine

[cenlinhe]

I just added these new entries to the other four GEOGRID.TBL files.

[cenlinhe]

OK, I did a WRF-SLUCM test run which failed using this new GloUCP data, which always showed "ZDC + Z0C + 2 is larger than 1st WRF atmospheric layer". I tried to increase the first layer to a large number (e.g., 500 m) which seems not working. I suspect there might be some data issue when the original data developer converted the data to WPS binary files. I am currently in contact with the original data developer to see if we could figure out what is wrong.
Also, BEP and BEP-BEM currently do not read in those 2-D urban parameters. They use LCZ or urban type map and parameter look up table (URBPARM*). So the new dataset should only be tested with SLUCM (urban_physics = 1).

[tslin2]

OK, I did a WRF-SLUCM test run which failed using this new GloUCP data, which always showed "ZDC + Z0C + 2 is larger than 1st WRF atmospheric layer". I tried to increase the first layer to a large number (e.g., 500 m) which seems not working. I suspect there might be some data issue when the original data developer converted the data to WPS binary files. I am currently in contact with the original data developer to see if we could figure out what is wrong. Also, BEP and BEP-BEM currently do not read in those 2-D urban parameters. They use LCZ or urban type map and parameter look up table (URBPARM*). So the new dataset should only be tested with SLUCM (urban_physics = 1).

I was looking at the previous email with @einaraz, looks like changing to average_gcell(2.0)+four_pt for URB_PARAM may work?

[cenlinhe]

OK, I did a WRF-SLUCM test run which failed using this new GloUCP data, which always showed "ZDC + Z0C + 2 is larger than 1st WRF atmospheric layer". I tried to increase the first layer to a large number (e.g., 500 m) which seems not working. I suspect there might be some data issue when the original data developer converted the data to WPS binary files. I am currently in contact with the original data developer to see if we could figure out what is wrong. Also, BEP and BEP-BEM currently do not read in those 2-D urban parameters. They use LCZ or urban type map and parameter look up table (URBPARM*). So the new dataset should only be tested with SLUCM (urban_physics = 1).

I was looking at the previous email with @einaraz, looks like changing to average_gcell(2.0)+four_pt for URB_PARAM may work?

The current method is: average_gcell(2.0)+nearest_neighbor, which should be similar to average_gcell(2.0)+four_pt. I checked that the max building height over New York City is about 137m which seems reasonable to me. But I am not sure why even I increase WRF 1st atmos layer to 300m, the error still shows up, which is weird.

[cenlinhe]

OK, it looks like when I used the second eta_levels = 1.000, 0.960, ...., the error is gone. It is still the new dataset providing a much higher building height (more realistic) than NUDAPT or table value. So the dataset looks fine.

[cenlinhe]

I was able to successfully run 500-m WRF-SLUCM with LCZ+GloUCP over New York City region with an eta_level = 1.000, 0.950, .... So I think the GloUCP dataset and implementation in WPS are fine.
Ming did a test for BEP/BEM, which also worked fine.

[cenlinhe]

Several tests have been done successfully. This dataset looks good to me. I approve it.

[weiwangncar]

@cenlinhe Do you recommend that we tar up the three datasets together or separately? Do you use these datasets together always, or can they be used separately when we place it on the server?

[cenlinhe]

@cenlinhe Do you recommend that we tar up the three datasets together or separately? Do you use these datasets together always, or can they be used separately when we place it on the server?

These three datasets can be used separately.

[islas]

@cenlinhe I've updated the PR description to reflect the state of the datasets now in /glade/work/wrfhelp/WPS_GEOG/ - I left the note about the download as that page has not been updated

[tslin2]

Hi all,
I am testing the WPSv4.7. The default description of FRC_URB2D in geo_em output file have some confusion.

The GEOGRID.TBL gives GAIA2020 data as priority=2 and nlcd2011 as priority=1,

WPS/geogrid/GEOGRID.TBL.ARW

Lines 460 to 478 in 5feccec

	===============================
	name=FRC_URB2D
	priority=1
	optional=yes
	dest_type=continuous
	fill_missing = 0.
	interp_option=default: average_gcell(2.0)+four_pt
	rel_path=default:urbfrac_nlcd2011/
	flag_in_output=FLAG_FRC_URB2D
	===============================
	name=FRC_URB2D
	priority=2
	optional=yes
	dest_type=continuous
	fill_missing = 0.
	interp_option=default: average_gcell(2.0)+four_pt
	rel_path=default:urbfrac_gaia2020_30s/
	flag_in_output=FLAG_FRC_URB2D
	===============================

The description in geo_em file
float FRC_URB2D(Time, south_north, west_east) ;
FRC_URB2D:FieldType = 104 ;
FRC_URB2D:MemoryOrder = "XY " ;
FRC_URB2D:units = "fraction" ;
FRC_URB2D:description = "Urban fraction derived from 30 m NLCD 2011 (22 = 50%, 23 = 90%, 24 = 95%)" ;
FRC_URB2D:stagger = "M" ;
FRC_URB2D:sr_x = 1 ;
FRC_URB2D:sr_y = 1 ;

and plot,

But the output is based on GAIA2020 data not nlcd2011, so the description should be the description of GAIA2020.

I have tested only one data use, only one priority, the description is correct:

NLCD2011:
float FRC_URB2D(Time, south_north, west_east) ;
FRC_URB2D:FieldType = 104 ;
FRC_URB2D:MemoryOrder = "XY " ;
FRC_URB2D:units = "fraction" ;
FRC_URB2D:description = "Urban fraction derived from 30 m NLCD 2011 (22 = 50%, 23 = 90%, 24 = 95%)" ;
FRC_URB2D:stagger = "M" ;
FRC_URB2D:sr_x = 1 ;
FRC_URB2D:sr_y = 1 ;

GAIA2020:
float FRC_URB2D(Time, south_north, west_east) ;
FRC_URB2D:FieldType = 104 ;
FRC_URB2D:MemoryOrder = "XY " ;
FRC_URB2D:units = "fraction" ;
FRC_URB2D:description = "global impervious surface fraction (0-1) from GAIA 2020 data" ;
FRC_URB2D:stagger = "M" ;
FRC_URB2D:sr_x = 1 ;
FRC_URB2D:sr_y = 1 ;

[weiwangncar]

@tslin2 Thanks for the report. After a chat with Michael, we realize that the new datasets were not added correctly to the GEOGRID.TBL. For a global dataset, the new ones should be added as part of the origin data type, not through priority option. There are many examples in the TBL file such as those for HGT_M and LANDUSEF. For example, for URB_PARAM, the section should look like this:

name=URB_PARAM
        priority=1 
        optional=yes
        dest_type=continuous
        fill_missing = 0.
        z_dim_name=num_urb_params
        interp_option=nudapt44:nearest_neighbor
        interp_option= default:average_gcell(2.0)+nearest_neighbor
        rel_path=nudapt44:NUDAPT44_1km/
        rel_path= default:gloucp2020_30s/
        flag_in_output=FLAG_URB_PARAM

We should make a PR to update this.

[tslin2]

@tslin2 Thanks for the report. After a chat with Michael, we realize that the new datasets were not added correctly to the GEOGRID.TBL. For a global dataset, the new ones should be added as part of the origin data type, not through priority option. There are many examples in the TBL file such as those for HGT_M and LANDUSEF. For example, for URB_PARAM, the section should look like this:

name=URB_PARAM
        priority=1 
        optional=yes
        dest_type=continuous
        fill_missing = 0.
        z_dim_name=num_urb_params
        interp_option=nudapt44:nearest_neighbor
        interp_option= default:average_gcell(2.0)+nearest_neighbor
        rel_path=nudapt44:NUDAPT44_1km/
        rel_path= default:gloucp2020_30s/
        flag_in_output=FLAG_URB_PARAM

We should make a PR to update this.

Thanks for looking into this and letting me know. Please let me know if I should submit a PR.

[weiwangncar]

@tslin2 If you could, it would be nice. Thank you!

[tslin2]

@tslin2 If you could, it would be nice. Thank you!

submit to #294, thanks