From e7d5d512e3aa6377396eee50cb550febcbfb808e Mon Sep 17 00:00:00 2001 From: olyson Date: Tue, 7 Apr 2026 15:51:42 -0600 Subject: [PATCH 1/5] First revision of Chapter 2.16 --- .../References/CLM50_Tech_Note_References.rst | 18 ++++++++++--- .../tech_note/Urban/CLM50_Tech_Note_Urban.rst | 26 ++++++++++++------- 2 files changed, 32 insertions(+), 12 deletions(-) diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 3aa6be1b71..90e4d68fe0 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -339,6 +339,10 @@ Entekhabi, D., and Eagleson, P.S. 1989. Land surface hydrology parameterization Fang, X. and Stefan, H.G., 1996. Long-term lake water temperature and ice cover simulations/measurements. Cold Regions Science and Technology 24:289-304. +.. _Fangetal2026: + +Fang, B., Zhao, L., Oleson, K., Zhang, K., Lawrence, P., Sacks, B., Cao, C., He, C., Huang, Q., Liu, Z., and Lee, X. 2026. Representing dynamic urban land change in the Community Earth System Model (CESM). JAMES, in revision. + .. _Farouki1981: Farouki, O.T. 1981. The thermal properties of soils in cold regions. Cold Regions Sci. and Tech. 5:67-75. @@ -419,6 +423,10 @@ Gallais, A., Coque, M., Gouis, J. L., Prioul, J. L., Hirel, B., and Quillere, I. Galloway, J.N., et al. 2004. Nitrogen cycles: past, present, and future. Biogeochem. 70:153-226. +.. _GaoOneill2020: + +Gao, J., and O’Neill, B.C. 2020. Mapping global urban land for the 21st century with data-driven simulations and Shared Socioeconomic Pathways. Nature Communications, 11(1), 2302. https://doi.org/10.1038/s41467-020-15788-7. + .. _Garciaetal1988: Garcia, R.L., Kanemasu, E.T., Blad, B.L., Bauer, A., Hatfield, J.L., Major, D.A., Reginato, R.J., and Hubbard, K.G. 1988. Interception and use efficiency of light in winter wheat under different nitrogen regimes. Agric. For. Meteor. 44:175-186. @@ -807,6 +815,10 @@ Li, H., L. Leung, A. Getirana, M. Huang, H. Wu, Y. Xu, J. Guo and N. Voisin. 201 Li, H., L. Leung, T. Tesfa, N. Voisin, M. Hejazi, L. Liu, Y. Liu, J. Rice, H. Wu, and X. Yang. 2015. Modeling stream temperature in the Anthropocene: An earth system modeling approach, J. Adv. Model. Earth Syst., 7, doi:10.1002/2015MS000471. +.. _Lietal2024: + +Li, X. "C", Zhao, L., Oleson, K., Zhou, Y., Qin, Y., Zhang, K., and Fang, B. 2024. Enhancing urban climate‐energy modeling in the Community Earth System Model (CESM) through explicit representation of urban air‐conditioning adoption. JAMES, 16, e2023MS004107. https://doi.org/10.1029/2023MS004107. + .. _Liangetal1994: Liang, X., Lettenmaier, D.P., Wood, E.F., and Burges, S.J. 1994. A simple hydrologically based model of land surface water and energy fluxes for GSMs. J. Geophys. Res. 99(D7):14,415–14,428. @@ -978,7 +990,7 @@ Oikawa, S., Hikosaka, K. and Hirose, T., 2005. Dynamics of leaf area and nitroge .. _Oke1987: -Oke, T. 1987. Boundary Layer Climates (2:math:`{}^{nd}` edition). Routledge, London and New York. +Oke, T. 1987. Boundary Layer Climates (2nd edition). Routledge, London and New York. .. _OlesonBonan2000: @@ -1012,9 +1024,9 @@ Oleson, K.W., Bonan, G.B., Feddema, J., Vertenstein, M., and Kluzek, E. 2010b. T Oleson, K.W., et al. 2013. Technical description of version 4.5 of the Community Land Model (CLM). NCAR Technical Note NCAR/TN-503+STR, National Center for Atmospheric Research, Boulder, CO, 420 pp. -.. _OlesonFeddema2018: +.. _OlesonFeddema2020: -Oleson, K.W., and Feddema, J. 2018. Parameterization and surface data improvements and new capabilities for the Community Land Model Urban (CLMU). JAMES, submitted. +Oleson, K.W., and Feddema, J. 2020. Parameterization and surface data improvements and new capabilities for the Community Land Model Urban (CLMU). JAMES, 12, e2018MS0001586, https://doi.org/10.1029/2018MS001596. .. _Olson1963: diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index 8777c7be74..d7db582252 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -3,23 +3,33 @@ Urban Model (CLMU) ====================== -At the global scale, and at the coarse spatial resolution of current climate models, urbanization has negligible impact on climate. However, the urban parameterization (CLMU; :ref:`Oleson et al. (2008b) `; :ref:`Oleson et al. (2008c) `) allows simulation of the urban environment within a climate model, and particularly the temperature where people live. As such, the urban model allows scientific study of how climate change affects the urban heat island and possible urban planning and design strategies to mitigate warming (e.g., white roofs). +The urban parameterization (CLMU; :ref:`Oleson et al. (2008b) `; :ref:`Oleson et al. (2008c) `; :ref:`Oleson and Feddema (2020) `) allows simulation of the urban environment within a climate model, and particularly the temperature/humidity where people live. As such, the urban model allows scientific study of how climate change affects the urban heat island and possible urban planning and design strategies to mitigate warming (e.g., white roofs). Urban areas in CLM are represented by up to three urban landunits per gridcell according to density class. The urban landunit is based on the "urban canyon" concept of :ref:`Oke (1987) ` in which the canyon geometry is described by building height (:math:`H`) and street width (:math:`W`) (:numref:`Figure schematic representation of the urban landunit`). The canyon system consists of roofs, walls, and canyon floor. Walls are further divided into shaded and sunlit components. The canyon floor is divided into pervious (e.g., to represent residential lawns, parks) and impervious (e.g., to represent roads, parking lots, sidewalks) fractions. Vegetation is not explicitly modeled for the pervious fraction; instead evaporation is parameterized by a simplified bulk scheme. -Each of the five urban surfaces is treated as a column within the landunit (:numref:`Figure schematic representation of the urban landunit`). Radiation parameterizations account for trapping of solar and longwave radiation inside the canyon. Momentum fluxes are determined for the urban landunit using a roughness length and displacement height appropriate for the urban canyon and stability formulations from CLM. A one-dimensional heat conduction equation is solved numerically for a multiple-layer (:math:`N_{levurb} =10`) column to determine conduction fluxes into and out of canyon surfaces. - -A new building energy model has been developed for CLM5.0. It accounts for the conduction of heat through interior surfaces (roof, sunlit and shaded walls, and floors), convection (sensible heat exchange) between interior surfaces and building air, longwave radiation exchange between interior surfaces, and ventilation (natural infiltration and exfiltration). Idealized HAC systems are assumed where the system capacity is infinite and the system supplies the amount of energy needed to keep the indoor air temperature (:math:`T_{iB}`) within maximum and minimum emperatures (:math:`T_{iB,\, \max },\, T_{iB,\, \min }` ), thus explicitly resolving space heating and air conditioning fluxes. Anthropogenic sources of waste heat (:math:`Q_{H,\, waste}` ) from HAC that account for inefficiencies in the heating and air conditioning equipment and from energy lost in the conversion of primary energy sources to end use energy are derived from :ref:`Sivak (2013) `. These sources of waste heat are incorporated as modifications to the canyon energy budget. +Each of the five urban surfaces is treated as a column within the landunit (:numref:`Figure schematic representation of the urban landunit`). Radiation parameterizations account for trapping of solar and longwave radiation inside the canyon. Momentum fluxes are determined for the urban landunit using a roughness length and displacement height appropriate for the urban canyon and stability formulations adopted from CLM. A one-dimensional heat conduction equation is solved numerically for a multiple-layer (:math:`N_{levurb} =10`) column to determine conduction fluxes into and out of canyon surfaces. Turbulent [sensible heat (:math:`Q_{H,\, u}` ) and latent heat (:math:`Q_{E,\, u}` )] and storage (:math:`Q_{S,\, u}` ) heat fluxes and surface (:math:`T_{u,\, s}` ) and internal (:math:`T_{u,\, i=1,\, N_{levgrnd} }` ) temperatures are determined for each urban surface :math:`u`. Hydrology on the roof and canyon floor is simulated and walls are hydrologically inactive. A snowpack can form on the active surfaces. A certain amount of liquid water is allowed to pond on these surfaces which supports evaporation. Water in excess of the maximum ponding depth runs off (:math:`R_{roof},\, R_{imprvrd},\, R_{prvrd}` ). The heat and moisture fluxes from each surface interact with each other through a bulk air mass that represents air in the urban canopy layer for which specific humidity (:math:`q_{ac}` ) and temperature (:math:`T_{ac}` ) are prognosed (:numref:`Figure schematic of urban and atmospheric model coupling`). The air temperature can be compared with that from surrounding vegetated/soil (rural) surfaces in the model to ascertain heat island characteristics. As with other landunits, the CLMU is forced either with output from a host atmospheric model (e.g., the Community Atmosphere Model (CAM)) or observed forcing (e.g., reanalysis or field observations). The urban model produces sensible, latent heat, and momentum fluxes, emitted longwave, and reflected solar radiation, which are area-averaged with fluxes from non-urban "landunits" (e.g., vegetation, lakes) to supply grid cell averaged fluxes to the atmospheric model. -Present day global urban extent and urban properties were developed by :ref:`Jackson et al. (2010) `. Urban extent, defined for four classes [tall building district (TBD), and high, medium, and low density (HD, MD, LD)], was derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity, and slope (:ref:`Dobson et al. 2000 `). The urban extent data for TBD, HD, and MD classes are aggregated from the original 1 km resolution to both a 0.05° by 0.05° global grid for high-resolution studies or a 0.5° by 0.5° grid. For the current implementation, the LD class is not used because it is highly rural and better modeled as a vegetated/soil surface. Although the TBD, HD, and MD classes are represented as individual urban landunits, urban model history output is currently a weighted average of the output for individual classes. +The version of the urban model that was first released as a component of CLM4.0 is separately described in the urban technical note (:ref:`Oleson et al. (2010b) `). The main changes in the urban model from CLM4.0 to CLM4.5 were 1) an expansion of the single urban landunit to up to three landunits per grid cell stratified by urban density types, 2) the number of urban layers for roofs and walls was no longer constrained to be equal to the number of ground layers, 3) space heating and air conditioning wasteheat factors were set to zero by default so that the user could customize these factors for their own application, 4) the elevation threshold used to eliminate urban areas in the surface dataset creation routines was increased from 2200 meters to 2600 meters, 5) hydrologic and thermal calculations for the pervious road followed CLM4.5 parameterizations. + +The main changes in the urban model from CLM4.5 to CLM5.0 were 1) a more sophisticated and realistic building space heating and air conditioning submodel (described below) that prognoses interior building air temperature and includes more realistic space heating and air conditioning wasteheat factors (see above), 2) the maximum building temperature (which determines air conditioning demand) was now read in from a file specified from the ``urbantv_streams`` namelist group instead of the surface dataset which allowed for dynamic control of this input variable. The maximum building temperatures that were defined in :ref:`Jackson et al. (2010) ` are only implemented beginning in year 1950 (thus air conditioning is off in prior years) and air conditioning is turned off in year 2100 (because the buildings are not suitable for air conditioning in some extreme global warming scenarios), 3) the inclusion of an optional updated urban properties dataset and new scenario tool. These features are described in more detail in :ref:`Oleson and Feddema (2020) `. In addition, a module of heat stress indices calculated online in the model that can be used to assess human thermal comfort for rural and urban areas was added. This last development is described and evaluated by :ref:`Buzan et al. (2015) `. + +The building energy model introduced in :ref:`Oleson and Feddema (2020) ` accounts for the conduction of heat through interior surfaces (roof, sunlit and shaded walls, and floors), convection (sensible heat exchange) between interior surfaces and building air, longwave radiation exchange between interior surfaces, and ventilation (natural infiltration and exfiltration). Idealized HAC systems are assumed where the system capacity is infinite and the system supplies the amount of energy needed to keep the indoor air temperature (:math:`T_{iB}`) within maximum and minimum emperatures (:math:`T_{iB,\, \max },\, T_{iB,\, \min }` ), thus explicitly resolving space heating and air conditioning fluxes. Anthropogenic sources of waste heat (:math:`Q_{H,\, waste}` ) from HAC that account for inefficiencies in the heating and air conditioning equipment and from energy lost in the conversion of primary energy sources to end use energy are derived from :ref:`Sivak (2013) `. These sources of waste heat are incorporated as modifications to the canyon energy budget. + +An explicit air conditioning (AC) adoption parameterization for the BEM was developed for CLM6 (:ref:`Li et al. (2024) `). An AC adoption parameter is introduced (:math:`p_{AC}` ). The AC flux is first calculated under saturated AC adoption (i.e., :math:`p_{AC}=100%` ). The actual AC flux removed from the indoor air is then scaled based on :math:`p_{AC}` and the waste heat added to the urban canyon due to AC energy use is also scaled by :math:`p_{AC}`. A global, spatially explicit data set for the AC adoption rate was developed at country- and sub-country-level from sources such as the International Energy Agency (IEA), national surveys, scientific literature, and others. For use with CLM, the AC adoption parameter was regridded to 0.9° latitude by 1.25° longitude and is read in for each of the three urban density classes using the file specified by the ``urbantv_streams`` namelist group (variables ``p_ac_MD``, ``p_ac_HD``, ``p_ac_TBD``). The maximum building interior temperature is also specified by the file in the ``urbantv_streams`` namelist group and is now considered to be the AC proxy setpoint in the parameterization and is set to 300K for all urban density classes (variables ``tbuildmax_MD``', ``tbuildmax_HD``, ``tbuildmax_TBD``). The explicit AC adoption parameterization in combination with the AC adoption rate data set significantly improve CLM's performance in model building AC energy flux, both in magnitude and spatial variability (:ref:`Li et al. (2024) `). + +Global urban properties were originally developed by :ref:`Jackson et al. (2010) `. For each of 33 distinct regions across the globe and four urban density classes [tall building district (TBD), and high, medium, and low density (HD, MD, LD)], thermal (e.g., heat capacity and thermal conductivity), radiative (e.g., albedo and emissivity) and morphological (e.g., height to width ratio, roof fraction, average building height, and pervious fraction of the canyon floor) properties, are provided for each of the density classes. Building interior minimum and maximum temperatures are prescribed based on climate and socioeconomic considerations. As described in :ref:`Oleson and Feddema (2020) ` the urban properties dataset in :ref:`Jackson et al. (2010) ` was modified with respect to wall and roof thermal properties to correct for biases in heat transfer due to layer and building type averaging. Further changes to the dataset reflect the need for scenario development, thus allowing for the creation of hypothetical wall types, and the easier interchange of wall facets. This slightly modified data set was an option in CLM5. + +The "raw" urban properties data set used by the model is created from the urban properties tool which is available as part of the Toolbox for Human-Earth System Integration & Scaling (THESIS) tool set (https://github.com/NCAR/THESISUrbanPropertiesTool; :ref:`Oleson and Feddema (2020) `). The driver script (``urban_prop.csh``) specifies three input csv files (by default, ``mat_prop.csv``, ``lam_spec.csv``, and ``city_spec.csv``; (:numref:`Figure schematic of THESIS urban properties tool`)) that describe the morphological, radiative, and thermal properties of urban areas, plus the minimum building interior temperature, and generates a global dataset at 0.05° latitude by longitude in NetCDF format. This dataset, when combined with the urban extent data described below, is then ingested into the ``mksurfdata_esmf`` tool to create surface datasets at the desired spatial and temporal resolutions. + +Urban extent (circa-year 2000), defined for the four density classes, was originally provided by :ref:`Jackson et al. (2010) ` and derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity, and slope (:ref:`Dobson et al. 2000 `). Note that the LD class is not used in CLM because it is highly rural (dominated by vegetation) and better modeled as a vegetated/soil surface. This data set was used for model versions CLM5 and earlier. A more up to date urban extent data set was derived for use with CLM6 from a 0.05° urban landcover projection data set (:ref:`Gao and O'Neill (2020) `) as described in :ref:`Fang et al. (2026) `. The :ref:`Gao and O'Neill (2020) ` data set provides global urban land cover for 2000-2100 in decadal intervals for a historical baseline (year 2000) and five CMIP6 ScenarioMIP Shared Socioeconomic Pathways (SSPs) at 0.05° resolution (2010-2100). Briefly, because the :ref:`Gao and O'Neill (2020) ` data set only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in the :ref:`Jackson et al. (2010) ` data set. The decadal urban data are then linearly interpolated to generate annual urban data from 2015-2100. To provide data prior to 2015, the average urban fraction of the five SSP scenarios was calculated in 2010 and 2015. Then annual urban fraction from 2000 to 2014 were obtained by interpolating betwen urban fraction in the historical baseline year 2000, and average SSP years 2010 and 2015. Finally, due to a lack of historical data, data for 1850-1999 were simply copied from year 2000 data. The yearly :ref:`Gao and O'Neill (2020) ` historical and SSP data sets are available for an intermediate model version (CTSM5.3) at 0.05° resolution. -For each of 33 distinct regions across the globe, thermal (e.g., heat capacity and thermal conductivity), radiative (e.g., albedo and emissivity) and morphological (e.g., height to width ratio, roof fraction, average building height, and pervious fraction of the canyon floor) properties are provided for each of the density classes. Building interior minimum and maximum temperatures are prescribed based on climate and socioeconomic considerations. The surface dataset creation routines (see CLM5.0 User's Guide) aggregate the data to the desired resolution. +However, it was deemed desirable to create a data set consistent with CMIP7 landcover change protocols. CMIP7 provides urban fraction at 0.25° resolution for 1700-2023. Again, since the data set only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in a year 2023 0.25° resolution version of the :ref:`Gao and O'Neill (2020) ` dataset created as described above. An exception is that the TBD class is not allowed before year 1900 as skyscrapers, etc. had not yet begun to be built. In that case, the urban fraction was split proportionally between the HD and MD classes. -An optional urban properties dataset, including a tool that allows for generating future urban development scenarios is also available (:ref:`Oleson and Feddema (2018) `). This will become the default dataset in future model versions. As described in :ref:`Oleson and Feddema (2018) ` the urban properties dataset in :ref:`Jackson et al. (2010) ` was modified with respect to wall and roof thermal properties to correct for biases in heat transfer due to layer and building type averaging. Further changes to the dataset reflect the need for scenario development, thus allowing for the creation of hypothetical wall types, and the easier interchange of wall facets. The new urban properties tool is available as part of the Toolbox for Human-Earth System Integration & Scaling (THESIS) tool set (http://www.cgd.ucar.edu/iam/projects/thesis/thesis-urbanproperties-tool.html; :ref:`Feddema and Kauffman (2016) `). The driver script (urban_prop.csh) specifies three input csv files (by default, mat_prop.csv, lam_spec.csv, and city_spec.csv; (:numref:`Figure schematic of THESIS urban properties tool`)) that describe the morphological, radiative, and thermal properties of urban areas, and generates a global dataset at 0.05° latitude by longitude in NetCDF format (urban_properties_data.05deg.nc). A standalone NCL routine (gen_data_clm.ncl) can be run separately after the mksurfdata_esmf tool creates the CLM surface dataset. This creates a supplementary streams file of setpoints for the maximum interior building temperature at yearly time resolution. +To accomodate the transient urban datasets developed above, dynamic urban capability was implemented into the model as described in :ref:`Fang et al. (2026) ` in a manner similar to the implementation of other land cover transient datasets including ensuring conservation for total gridcell water and energy content. See Chapter :numref:`rst_Transient Landcover Change` for further details. .. Figure 12.1. Schematic representation of the urban land unit @@ -45,6 +55,4 @@ An optional urban properties dataset, including a tool that allows for generatin Schematic of THESIS urban properties tool. Executable scripts are in orange, input files are blue, and output files are green. Items within the black box outline are either read in as input, executed, or output by the driver script (urban_prop.csh). -The urban model that was first released as a component of CLM4.0 is separately described in the urban technical note (:ref:`Oleson et al. (2010b) `). The main changes in the urban model from CLM4.0 to CLM4.5 were 1) an expansion of the single urban landunit to up to three landunits per grid cell stratified by urban density types, 2) the number of urban layers for roofs and walls was no longer constrained to be equal to the number of ground layers, 3) space heating and air conditioning wasteheat factors were set to zero by default so that the user could customize these factors for their own application, 4) the elevation threshold used to eliminate urban areas in the surface dataset creation routines was increased from 2200 meters to 2600 meters, 5) hydrologic and thermal calculations for the pervious road followed CLM4.5 parameterizations. -The main changes in the urban model from CLM4.5 to CLM5.0 are 1) a more sophisticated and realistic building space heating and air conditioning submodel that prognoses interior building air temperature and includes more realistic space heating and air conditioning wasteheat factors (see above), 2) the maximum building temperature (which determines air conditioning demand) is now read in from a namelist-defined file which allows for dynamic control of this input variable. The maximum building temperatures that are defined in :ref:`Jackson et al. (2010) ` are implemented in year 1950 (thus air conditioning is off in prior years) and air conditioning is turned off in year 2100 (because the buildings are not suitable for air conditioning in some extreme global warming scenarios), 3) an optional updated urban properties dataset and new scenario tool. These features are described in more detail in :ref:`Oleson and Feddema (2018) `. In addition, a module of heat stress indices calculated online in the model that can be used to assess human thermal comfort for rural and urban areas has been added. This last development is described and evaluated by :ref:`Buzan et al. (2015) `. From a53eca377c1f05cf9346e2551379ede61c8992ac Mon Sep 17 00:00:00 2001 From: olyson Date: Tue, 7 Apr 2026 16:03:15 -0600 Subject: [PATCH 2/5] Add note regarding CMIP7 future scenarios --- doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index d7db582252..1189757321 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -27,7 +27,7 @@ The "raw" urban properties data set used by the model is created from the urban Urban extent (circa-year 2000), defined for the four density classes, was originally provided by :ref:`Jackson et al. (2010) ` and derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity, and slope (:ref:`Dobson et al. 2000 `). Note that the LD class is not used in CLM because it is highly rural (dominated by vegetation) and better modeled as a vegetated/soil surface. This data set was used for model versions CLM5 and earlier. A more up to date urban extent data set was derived for use with CLM6 from a 0.05° urban landcover projection data set (:ref:`Gao and O'Neill (2020) `) as described in :ref:`Fang et al. (2026) `. The :ref:`Gao and O'Neill (2020) ` data set provides global urban land cover for 2000-2100 in decadal intervals for a historical baseline (year 2000) and five CMIP6 ScenarioMIP Shared Socioeconomic Pathways (SSPs) at 0.05° resolution (2010-2100). Briefly, because the :ref:`Gao and O'Neill (2020) ` data set only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in the :ref:`Jackson et al. (2010) ` data set. The decadal urban data are then linearly interpolated to generate annual urban data from 2015-2100. To provide data prior to 2015, the average urban fraction of the five SSP scenarios was calculated in 2010 and 2015. Then annual urban fraction from 2000 to 2014 were obtained by interpolating betwen urban fraction in the historical baseline year 2000, and average SSP years 2010 and 2015. Finally, due to a lack of historical data, data for 1850-1999 were simply copied from year 2000 data. The yearly :ref:`Gao and O'Neill (2020) ` historical and SSP data sets are available for an intermediate model version (CTSM5.3) at 0.05° resolution. -However, it was deemed desirable to create a data set consistent with CMIP7 landcover change protocols. CMIP7 provides urban fraction at 0.25° resolution for 1700-2023. Again, since the data set only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in a year 2023 0.25° resolution version of the :ref:`Gao and O'Neill (2020) ` dataset created as described above. An exception is that the TBD class is not allowed before year 1900 as skyscrapers, etc. had not yet begun to be built. In that case, the urban fraction was split proportionally between the HD and MD classes. +However, it was deemed desirable to create a data set consistent with CMIP7 landcover change protocols. CMIP7 provides urban fraction at 0.25° resolution for 1700-2023. Again, since the data set only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in a year 2023 0.25° resolution version of the :ref:`Gao and O'Neill (2020) ` dataset created as described above. An exception is that the TBD class is not allowed before year 1900 as skyscrapers, etc. had not yet begun to be built. In that case, the urban fraction was split proportionally between the HD and MD classes. Datasets for future scenarios, i.e., 2024-, will be created similarly when CMIP7 data is available. To accomodate the transient urban datasets developed above, dynamic urban capability was implemented into the model as described in :ref:`Fang et al. (2026) ` in a manner similar to the implementation of other land cover transient datasets including ensuring conservation for total gridcell water and energy content. See Chapter :numref:`rst_Transient Landcover Change` for further details. From 712bd5ba5052e97dad8ef7a9945594d1a4da57bb Mon Sep 17 00:00:00 2001 From: olyson Date: Tue, 7 Apr 2026 16:21:33 -0600 Subject: [PATCH 3/5] Add note about location of code for GaoOneill processing. --- doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index 1189757321..956cff5db5 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -25,7 +25,7 @@ Global urban properties were originally developed by :ref:`Jackson et al. (2010) The "raw" urban properties data set used by the model is created from the urban properties tool which is available as part of the Toolbox for Human-Earth System Integration & Scaling (THESIS) tool set (https://github.com/NCAR/THESISUrbanPropertiesTool; :ref:`Oleson and Feddema (2020) `). The driver script (``urban_prop.csh``) specifies three input csv files (by default, ``mat_prop.csv``, ``lam_spec.csv``, and ``city_spec.csv``; (:numref:`Figure schematic of THESIS urban properties tool`)) that describe the morphological, radiative, and thermal properties of urban areas, plus the minimum building interior temperature, and generates a global dataset at 0.05° latitude by longitude in NetCDF format. This dataset, when combined with the urban extent data described below, is then ingested into the ``mksurfdata_esmf`` tool to create surface datasets at the desired spatial and temporal resolutions. -Urban extent (circa-year 2000), defined for the four density classes, was originally provided by :ref:`Jackson et al. (2010) ` and derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity, and slope (:ref:`Dobson et al. 2000 `). Note that the LD class is not used in CLM because it is highly rural (dominated by vegetation) and better modeled as a vegetated/soil surface. This data set was used for model versions CLM5 and earlier. A more up to date urban extent data set was derived for use with CLM6 from a 0.05° urban landcover projection data set (:ref:`Gao and O'Neill (2020) `) as described in :ref:`Fang et al. (2026) `. The :ref:`Gao and O'Neill (2020) ` data set provides global urban land cover for 2000-2100 in decadal intervals for a historical baseline (year 2000) and five CMIP6 ScenarioMIP Shared Socioeconomic Pathways (SSPs) at 0.05° resolution (2010-2100). Briefly, because the :ref:`Gao and O'Neill (2020) ` data set only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in the :ref:`Jackson et al. (2010) ` data set. The decadal urban data are then linearly interpolated to generate annual urban data from 2015-2100. To provide data prior to 2015, the average urban fraction of the five SSP scenarios was calculated in 2010 and 2015. Then annual urban fraction from 2000 to 2014 were obtained by interpolating betwen urban fraction in the historical baseline year 2000, and average SSP years 2010 and 2015. Finally, due to a lack of historical data, data for 1850-1999 were simply copied from year 2000 data. The yearly :ref:`Gao and O'Neill (2020) ` historical and SSP data sets are available for an intermediate model version (CTSM5.3) at 0.05° resolution. +Urban extent (circa-year 2000), defined for the four density classes, was originally provided by :ref:`Jackson et al. (2010) ` and derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity, and slope (:ref:`Dobson et al. 2000 `). Note that the LD class is not used in CLM because it is highly rural (dominated by vegetation) and better modeled as a vegetated/soil surface. This data set was used for model versions CLM5 and earlier. A more up to date urban extent data set was derived for use with CLM6 from a 0.05° urban landcover projection data set (:ref:`Gao and O'Neill (2020) `) as described in :ref:`Fang et al. (2026) ` (code and auxiliary datasets available at https://figshare.com/s/4a890655b34498c1d082). The :ref:`Gao and O'Neill (2020) ` data set provides global urban land cover for 2000-2100 in decadal intervals for a historical baseline (year 2000) and five CMIP6 ScenarioMIP Shared Socioeconomic Pathways (SSPs) at 0.05° resolution (2010-2100). Briefly, because the :ref:`Gao and O'Neill (2020) ` data set only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in the :ref:`Jackson et al. (2010) ` data set. The decadal urban data are then linearly interpolated to generate annual urban data from 2015-2100. To provide data prior to 2015, the average urban fraction of the five SSP scenarios was calculated in 2010 and 2015. Then annual urban fraction from 2000 to 2014 were obtained by interpolating betwen urban fraction in the historical baseline year 2000, and average SSP years 2010 and 2015. Finally, due to a lack of historical data, data for 1850-1999 were simply copied from year 2000 data. The yearly :ref:`Gao and O'Neill (2020) ` historical and SSP data sets are available for an intermediate model version (CTSM5.3) at 0.05° resolution. However, it was deemed desirable to create a data set consistent with CMIP7 landcover change protocols. CMIP7 provides urban fraction at 0.25° resolution for 1700-2023. Again, since the data set only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in a year 2023 0.25° resolution version of the :ref:`Gao and O'Neill (2020) ` dataset created as described above. An exception is that the TBD class is not allowed before year 1900 as skyscrapers, etc. had not yet begun to be built. In that case, the urban fraction was split proportionally between the HD and MD classes. Datasets for future scenarios, i.e., 2024-, will be created similarly when CMIP7 data is available. From 0864f974c1e480fe540ccf0e7589da3f6c7b2114 Mon Sep 17 00:00:00 2001 From: olyson Date: Tue, 7 Apr 2026 16:24:33 -0600 Subject: [PATCH 4/5] data set to dataset --- doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index 956cff5db5..0ff444baf9 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -19,15 +19,15 @@ The main changes in the urban model from CLM4.5 to CLM5.0 were 1) a more sophist The building energy model introduced in :ref:`Oleson and Feddema (2020) ` accounts for the conduction of heat through interior surfaces (roof, sunlit and shaded walls, and floors), convection (sensible heat exchange) between interior surfaces and building air, longwave radiation exchange between interior surfaces, and ventilation (natural infiltration and exfiltration). Idealized HAC systems are assumed where the system capacity is infinite and the system supplies the amount of energy needed to keep the indoor air temperature (:math:`T_{iB}`) within maximum and minimum emperatures (:math:`T_{iB,\, \max },\, T_{iB,\, \min }` ), thus explicitly resolving space heating and air conditioning fluxes. Anthropogenic sources of waste heat (:math:`Q_{H,\, waste}` ) from HAC that account for inefficiencies in the heating and air conditioning equipment and from energy lost in the conversion of primary energy sources to end use energy are derived from :ref:`Sivak (2013) `. These sources of waste heat are incorporated as modifications to the canyon energy budget. -An explicit air conditioning (AC) adoption parameterization for the BEM was developed for CLM6 (:ref:`Li et al. (2024) `). An AC adoption parameter is introduced (:math:`p_{AC}` ). The AC flux is first calculated under saturated AC adoption (i.e., :math:`p_{AC}=100%` ). The actual AC flux removed from the indoor air is then scaled based on :math:`p_{AC}` and the waste heat added to the urban canyon due to AC energy use is also scaled by :math:`p_{AC}`. A global, spatially explicit data set for the AC adoption rate was developed at country- and sub-country-level from sources such as the International Energy Agency (IEA), national surveys, scientific literature, and others. For use with CLM, the AC adoption parameter was regridded to 0.9° latitude by 1.25° longitude and is read in for each of the three urban density classes using the file specified by the ``urbantv_streams`` namelist group (variables ``p_ac_MD``, ``p_ac_HD``, ``p_ac_TBD``). The maximum building interior temperature is also specified by the file in the ``urbantv_streams`` namelist group and is now considered to be the AC proxy setpoint in the parameterization and is set to 300K for all urban density classes (variables ``tbuildmax_MD``', ``tbuildmax_HD``, ``tbuildmax_TBD``). The explicit AC adoption parameterization in combination with the AC adoption rate data set significantly improve CLM's performance in model building AC energy flux, both in magnitude and spatial variability (:ref:`Li et al. (2024) `). +An explicit air conditioning (AC) adoption parameterization for the BEM was developed for CLM6 (:ref:`Li et al. (2024) `). An AC adoption parameter is introduced (:math:`p_{AC}` ). The AC flux is first calculated under saturated AC adoption (i.e., :math:`p_{AC}=100%` ). The actual AC flux removed from the indoor air is then scaled based on :math:`p_{AC}` and the waste heat added to the urban canyon due to AC energy use is also scaled by :math:`p_{AC}`. A global, spatially explicit dataset for the AC adoption rate was developed at country- and sub-country-level from sources such as the International Energy Agency (IEA), national surveys, scientific literature, and others. For use with CLM, the AC adoption parameter was regridded to 0.9° latitude by 1.25° longitude and is read in for each of the three urban density classes using the file specified by the ``urbantv_streams`` namelist group (variables ``p_ac_MD``, ``p_ac_HD``, ``p_ac_TBD``). The maximum building interior temperature is also specified by the file in the ``urbantv_streams`` namelist group and is now considered to be the AC proxy setpoint in the parameterization and is set to 300K for all urban density classes (variables ``tbuildmax_MD``', ``tbuildmax_HD``, ``tbuildmax_TBD``). The explicit AC adoption parameterization in combination with the AC adoption rate dataset significantly improve CLM's performance in model building AC energy flux, both in magnitude and spatial variability (:ref:`Li et al. (2024) `). -Global urban properties were originally developed by :ref:`Jackson et al. (2010) `. For each of 33 distinct regions across the globe and four urban density classes [tall building district (TBD), and high, medium, and low density (HD, MD, LD)], thermal (e.g., heat capacity and thermal conductivity), radiative (e.g., albedo and emissivity) and morphological (e.g., height to width ratio, roof fraction, average building height, and pervious fraction of the canyon floor) properties, are provided for each of the density classes. Building interior minimum and maximum temperatures are prescribed based on climate and socioeconomic considerations. As described in :ref:`Oleson and Feddema (2020) ` the urban properties dataset in :ref:`Jackson et al. (2010) ` was modified with respect to wall and roof thermal properties to correct for biases in heat transfer due to layer and building type averaging. Further changes to the dataset reflect the need for scenario development, thus allowing for the creation of hypothetical wall types, and the easier interchange of wall facets. This slightly modified data set was an option in CLM5. +Global urban properties were originally developed by :ref:`Jackson et al. (2010) `. For each of 33 distinct regions across the globe and four urban density classes [tall building district (TBD), and high, medium, and low density (HD, MD, LD)], thermal (e.g., heat capacity and thermal conductivity), radiative (e.g., albedo and emissivity) and morphological (e.g., height to width ratio, roof fraction, average building height, and pervious fraction of the canyon floor) properties, are provided for each of the density classes. Building interior minimum and maximum temperatures are prescribed based on climate and socioeconomic considerations. As described in :ref:`Oleson and Feddema (2020) ` the urban properties dataset in :ref:`Jackson et al. (2010) ` was modified with respect to wall and roof thermal properties to correct for biases in heat transfer due to layer and building type averaging. Further changes to the dataset reflect the need for scenario development, thus allowing for the creation of hypothetical wall types, and the easier interchange of wall facets. This slightly modified dataset was an option in CLM5. -The "raw" urban properties data set used by the model is created from the urban properties tool which is available as part of the Toolbox for Human-Earth System Integration & Scaling (THESIS) tool set (https://github.com/NCAR/THESISUrbanPropertiesTool; :ref:`Oleson and Feddema (2020) `). The driver script (``urban_prop.csh``) specifies three input csv files (by default, ``mat_prop.csv``, ``lam_spec.csv``, and ``city_spec.csv``; (:numref:`Figure schematic of THESIS urban properties tool`)) that describe the morphological, radiative, and thermal properties of urban areas, plus the minimum building interior temperature, and generates a global dataset at 0.05° latitude by longitude in NetCDF format. This dataset, when combined with the urban extent data described below, is then ingested into the ``mksurfdata_esmf`` tool to create surface datasets at the desired spatial and temporal resolutions. +The "raw" urban properties dataset used by the model is created from the urban properties tool which is available as part of the Toolbox for Human-Earth System Integration & Scaling (THESIS) tool set (https://github.com/NCAR/THESISUrbanPropertiesTool; :ref:`Oleson and Feddema (2020) `). The driver script (``urban_prop.csh``) specifies three input csv files (by default, ``mat_prop.csv``, ``lam_spec.csv``, and ``city_spec.csv``; (:numref:`Figure schematic of THESIS urban properties tool`)) that describe the morphological, radiative, and thermal properties of urban areas, plus the minimum building interior temperature, and generates a global dataset at 0.05° latitude by longitude in NetCDF format. This dataset, when combined with the urban extent data described below, is then ingested into the ``mksurfdata_esmf`` tool to create surface datasets at the desired spatial and temporal resolutions. -Urban extent (circa-year 2000), defined for the four density classes, was originally provided by :ref:`Jackson et al. (2010) ` and derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity, and slope (:ref:`Dobson et al. 2000 `). Note that the LD class is not used in CLM because it is highly rural (dominated by vegetation) and better modeled as a vegetated/soil surface. This data set was used for model versions CLM5 and earlier. A more up to date urban extent data set was derived for use with CLM6 from a 0.05° urban landcover projection data set (:ref:`Gao and O'Neill (2020) `) as described in :ref:`Fang et al. (2026) ` (code and auxiliary datasets available at https://figshare.com/s/4a890655b34498c1d082). The :ref:`Gao and O'Neill (2020) ` data set provides global urban land cover for 2000-2100 in decadal intervals for a historical baseline (year 2000) and five CMIP6 ScenarioMIP Shared Socioeconomic Pathways (SSPs) at 0.05° resolution (2010-2100). Briefly, because the :ref:`Gao and O'Neill (2020) ` data set only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in the :ref:`Jackson et al. (2010) ` data set. The decadal urban data are then linearly interpolated to generate annual urban data from 2015-2100. To provide data prior to 2015, the average urban fraction of the five SSP scenarios was calculated in 2010 and 2015. Then annual urban fraction from 2000 to 2014 were obtained by interpolating betwen urban fraction in the historical baseline year 2000, and average SSP years 2010 and 2015. Finally, due to a lack of historical data, data for 1850-1999 were simply copied from year 2000 data. The yearly :ref:`Gao and O'Neill (2020) ` historical and SSP data sets are available for an intermediate model version (CTSM5.3) at 0.05° resolution. +Urban extent (circa-year 2000), defined for the four density classes, was originally provided by :ref:`Jackson et al. (2010) ` and derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity, and slope (:ref:`Dobson et al. 2000 `). Note that the LD class is not used in CLM because it is highly rural (dominated by vegetation) and better modeled as a vegetated/soil surface. This dataset was used for model versions CLM5 and earlier. A more up to date urban extent dataset was derived for use with CLM6 from a 0.05° urban landcover projection dataset (:ref:`Gao and O'Neill (2020) `) as described in :ref:`Fang et al. (2026) ` (code and auxiliary datasets available at https://figshare.com/s/4a890655b34498c1d082). The :ref:`Gao and O'Neill (2020) ` dataset provides global urban land cover for 2000-2100 in decadal intervals for a historical baseline (year 2000) and five CMIP6 ScenarioMIP Shared Socioeconomic Pathways (SSPs) at 0.05° resolution (2010-2100). Briefly, because the :ref:`Gao and O'Neill (2020) ` dataset only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in the :ref:`Jackson et al. (2010) ` dataset. The decadal urban data are then linearly interpolated to generate annual urban data from 2015-2100. To provide data prior to 2015, the average urban fraction of the five SSP scenarios was calculated in 2010 and 2015. Then annual urban fraction from 2000 to 2014 were obtained by interpolating betwen urban fraction in the historical baseline year 2000, and average SSP years 2010 and 2015. Finally, due to a lack of historical data, data for 1850-1999 were simply copied from year 2000 data. The yearly :ref:`Gao and O'Neill (2020) ` historical and SSP datasets are available for an intermediate model version (CTSM5.3) at 0.05° resolution. -However, it was deemed desirable to create a data set consistent with CMIP7 landcover change protocols. CMIP7 provides urban fraction at 0.25° resolution for 1700-2023. Again, since the data set only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in a year 2023 0.25° resolution version of the :ref:`Gao and O'Neill (2020) ` dataset created as described above. An exception is that the TBD class is not allowed before year 1900 as skyscrapers, etc. had not yet begun to be built. In that case, the urban fraction was split proportionally between the HD and MD classes. Datasets for future scenarios, i.e., 2024-, will be created similarly when CMIP7 data is available. +However, it was deemed desirable to create a dataset consistent with CMIP7 landcover change protocols. CMIP7 provides urban fraction at 0.25° resolution for 1700-2023. Again, since the dataset only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in a year 2023 0.25° resolution version of the :ref:`Gao and O'Neill (2020) ` dataset created as described above. An exception is that the TBD class is not allowed before year 1900 as skyscrapers, etc. had not yet begun to be built. In that case, the urban fraction was split proportionally between the HD and MD classes. Datasets for future scenarios, i.e., 2024-, will be created similarly when CMIP7 data is available. To accomodate the transient urban datasets developed above, dynamic urban capability was implemented into the model as described in :ref:`Fang et al. (2026) ` in a manner similar to the implementation of other land cover transient datasets including ensuring conservation for total gridcell water and energy content. See Chapter :numref:`rst_Transient Landcover Change` for further details. From 7765766be266f738bde2b4f1a9f0d86586e4e5bf Mon Sep 17 00:00:00 2001 From: olyson Date: Tue, 7 Apr 2026 16:41:43 -0600 Subject: [PATCH 5/5] Add summary of CLM5->CLM6 --- .../tech_note/Urban/CLM50_Tech_Note_Urban.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index 0ff444baf9..695281556f 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -13,19 +13,21 @@ Turbulent [sensible heat (:math:`Q_{H,\, u}` ) and latent heat (:math:`Q_{E,\, u The heat and moisture fluxes from each surface interact with each other through a bulk air mass that represents air in the urban canopy layer for which specific humidity (:math:`q_{ac}` ) and temperature (:math:`T_{ac}` ) are prognosed (:numref:`Figure schematic of urban and atmospheric model coupling`). The air temperature can be compared with that from surrounding vegetated/soil (rural) surfaces in the model to ascertain heat island characteristics. As with other landunits, the CLMU is forced either with output from a host atmospheric model (e.g., the Community Atmosphere Model (CAM)) or observed forcing (e.g., reanalysis or field observations). The urban model produces sensible, latent heat, and momentum fluxes, emitted longwave, and reflected solar radiation, which are area-averaged with fluxes from non-urban "landunits" (e.g., vegetation, lakes) to supply grid cell averaged fluxes to the atmospheric model. -The version of the urban model that was first released as a component of CLM4.0 is separately described in the urban technical note (:ref:`Oleson et al. (2010b) `). The main changes in the urban model from CLM4.0 to CLM4.5 were 1) an expansion of the single urban landunit to up to three landunits per grid cell stratified by urban density types, 2) the number of urban layers for roofs and walls was no longer constrained to be equal to the number of ground layers, 3) space heating and air conditioning wasteheat factors were set to zero by default so that the user could customize these factors for their own application, 4) the elevation threshold used to eliminate urban areas in the surface dataset creation routines was increased from 2200 meters to 2600 meters, 5) hydrologic and thermal calculations for the pervious road followed CLM4.5 parameterizations. +The version of the urban model that was first released as a component of CLM4.0 is separately described in the urban technical note (:ref:`Oleson et al. (2010b) `). The main changes in the urban model from CLM4.0 to CLM4.5 were 1) an expansion of the single urban landunit to up to three landunits per grid cell stratified by urban density types, 2) the number of urban layers for roofs and walls was no longer constrained to be equal to the number of ground layers, 3) space heating and air conditioning (AC) wasteheat factors were set to zero by default so that the user could customize these factors for their own application, 4) the elevation threshold used to eliminate urban areas in the surface dataset creation routines was increased from 2200 meters to 2600 meters, 5) hydrologic and thermal calculations for the pervious road followed CLM4.5 parameterizations. -The main changes in the urban model from CLM4.5 to CLM5.0 were 1) a more sophisticated and realistic building space heating and air conditioning submodel (described below) that prognoses interior building air temperature and includes more realistic space heating and air conditioning wasteheat factors (see above), 2) the maximum building temperature (which determines air conditioning demand) was now read in from a file specified from the ``urbantv_streams`` namelist group instead of the surface dataset which allowed for dynamic control of this input variable. The maximum building temperatures that were defined in :ref:`Jackson et al. (2010) ` are only implemented beginning in year 1950 (thus air conditioning is off in prior years) and air conditioning is turned off in year 2100 (because the buildings are not suitable for air conditioning in some extreme global warming scenarios), 3) the inclusion of an optional updated urban properties dataset and new scenario tool. These features are described in more detail in :ref:`Oleson and Feddema (2020) `. In addition, a module of heat stress indices calculated online in the model that can be used to assess human thermal comfort for rural and urban areas was added. This last development is described and evaluated by :ref:`Buzan et al. (2015) `. +The main changes in the urban model from CLM4.5 to CLM5.0 were 1) a more sophisticated and realistic building space heating and AC submodel (described below) that prognoses interior building air temperature and includes more realistic space heating and AC wasteheat factors (see above), 2) the maximum building temperature (which determines AC demand) was now read in from a file specified from the ``urbantv_streams`` namelist group instead of the surface dataset which allowed for dynamic control of this input variable. The maximum building temperatures that were defined in :ref:`Jackson et al. (2010) ` are only implemented beginning in year 1950 (thus AC is off in prior years) and AC is turned off in year 2100 (because the buildings are not suitable for AC in some extreme global warming scenarios), 3) the inclusion of an optional updated urban properties dataset and new scenario tool. These features are described in more detail in :ref:`Oleson and Feddema (2020) `. In addition, a module of heat stress indices calculated online in the model that can be used to assess human thermal comfort for rural and urban areas was added. This last development is described and evaluated by :ref:`Buzan et al. (2015) `. -The building energy model introduced in :ref:`Oleson and Feddema (2020) ` accounts for the conduction of heat through interior surfaces (roof, sunlit and shaded walls, and floors), convection (sensible heat exchange) between interior surfaces and building air, longwave radiation exchange between interior surfaces, and ventilation (natural infiltration and exfiltration). Idealized HAC systems are assumed where the system capacity is infinite and the system supplies the amount of energy needed to keep the indoor air temperature (:math:`T_{iB}`) within maximum and minimum emperatures (:math:`T_{iB,\, \max },\, T_{iB,\, \min }` ), thus explicitly resolving space heating and air conditioning fluxes. Anthropogenic sources of waste heat (:math:`Q_{H,\, waste}` ) from HAC that account for inefficiencies in the heating and air conditioning equipment and from energy lost in the conversion of primary energy sources to end use energy are derived from :ref:`Sivak (2013) `. These sources of waste heat are incorporated as modifications to the canyon energy budget. +The main changes in the urban model from CLM5.0 to CLM6.0 are (see below) 1) an explicit AC scheme for the building energy model (BEM) that better captures AC energy flux, 2) the addition of transient urban capability (annual changes in urban fraction over the course of a simulation), 3) a slightly modified set of urban properties that were an option in CLM5.0 and are now used by default, 4) new datasets of urban extent (urban fraction of the grid cell) for 1700-2023 (2024- data expected soon also) based on CMIP7 LUH3 data. -An explicit air conditioning (AC) adoption parameterization for the BEM was developed for CLM6 (:ref:`Li et al. (2024) `). An AC adoption parameter is introduced (:math:`p_{AC}` ). The AC flux is first calculated under saturated AC adoption (i.e., :math:`p_{AC}=100%` ). The actual AC flux removed from the indoor air is then scaled based on :math:`p_{AC}` and the waste heat added to the urban canyon due to AC energy use is also scaled by :math:`p_{AC}`. A global, spatially explicit dataset for the AC adoption rate was developed at country- and sub-country-level from sources such as the International Energy Agency (IEA), national surveys, scientific literature, and others. For use with CLM, the AC adoption parameter was regridded to 0.9° latitude by 1.25° longitude and is read in for each of the three urban density classes using the file specified by the ``urbantv_streams`` namelist group (variables ``p_ac_MD``, ``p_ac_HD``, ``p_ac_TBD``). The maximum building interior temperature is also specified by the file in the ``urbantv_streams`` namelist group and is now considered to be the AC proxy setpoint in the parameterization and is set to 300K for all urban density classes (variables ``tbuildmax_MD``', ``tbuildmax_HD``, ``tbuildmax_TBD``). The explicit AC adoption parameterization in combination with the AC adoption rate dataset significantly improve CLM's performance in model building AC energy flux, both in magnitude and spatial variability (:ref:`Li et al. (2024) `). +The building energy model introduced in :ref:`Oleson and Feddema (2020) ` accounts for the conduction of heat through interior surfaces (roof, sunlit and shaded walls, and floors), convection (sensible heat exchange) between interior surfaces and building air, longwave radiation exchange between interior surfaces, and ventilation (natural infiltration and exfiltration). Idealized HAC systems are assumed where the system capacity is infinite and the system supplies the amount of energy needed to keep the indoor air temperature (:math:`T_{iB}`) within maximum and minimum emperatures (:math:`T_{iB,\, \max },\, T_{iB,\, \min }` ), thus explicitly resolving space heating and AC fluxes. Anthropogenic sources of waste heat (:math:`Q_{H,\, waste}` ) from HAC that account for inefficiencies in the heating and AC equipment and from energy lost in the conversion of primary energy sources to end use energy are derived from :ref:`Sivak (2013) `. These sources of waste heat are incorporated as modifications to the canyon energy budget. -Global urban properties were originally developed by :ref:`Jackson et al. (2010) `. For each of 33 distinct regions across the globe and four urban density classes [tall building district (TBD), and high, medium, and low density (HD, MD, LD)], thermal (e.g., heat capacity and thermal conductivity), radiative (e.g., albedo and emissivity) and morphological (e.g., height to width ratio, roof fraction, average building height, and pervious fraction of the canyon floor) properties, are provided for each of the density classes. Building interior minimum and maximum temperatures are prescribed based on climate and socioeconomic considerations. As described in :ref:`Oleson and Feddema (2020) ` the urban properties dataset in :ref:`Jackson et al. (2010) ` was modified with respect to wall and roof thermal properties to correct for biases in heat transfer due to layer and building type averaging. Further changes to the dataset reflect the need for scenario development, thus allowing for the creation of hypothetical wall types, and the easier interchange of wall facets. This slightly modified dataset was an option in CLM5. +An explicit AC adoption parameterization for the BEM was developed for CLM6.0 (:ref:`Li et al. (2024) `). An AC adoption parameter is introduced (:math:`p_{AC}` ). The AC flux is first calculated under saturated AC adoption (i.e., :math:`p_{AC}=100%` ). The actual AC flux removed from the indoor air is then scaled based on :math:`p_{AC}` and the waste heat added to the urban canyon due to AC energy use is also scaled by :math:`p_{AC}`. A global, spatially explicit dataset for the AC adoption rate was developed at country- and sub-country-level from sources such as the International Energy Agency (IEA), national surveys, scientific literature, and others. For use with CLM, the AC adoption parameter was regridded to 0.9° latitude by 1.25° longitude and is read in for each of the three urban density classes using the file specified by the ``urbantv_streams`` namelist group (variables ``p_ac_MD``, ``p_ac_HD``, ``p_ac_TBD``). The maximum building interior temperature is also specified by the file in the ``urbantv_streams`` namelist group and is now considered to be the AC proxy setpoint in the parameterization and is set to 300K for all urban density classes (variables ``tbuildmax_MD``', ``tbuildmax_HD``, ``tbuildmax_TBD``). The explicit AC adoption parameterization in combination with the AC adoption rate dataset significantly improve CLM's performance in model building AC energy flux, both in magnitude and spatial variability (:ref:`Li et al. (2024) `). + +Global urban properties were originally developed by :ref:`Jackson et al. (2010) `. For each of 33 distinct regions across the globe and four urban density classes [tall building district (TBD), and high, medium, and low density (HD, MD, LD)], thermal (e.g., heat capacity and thermal conductivity), radiative (e.g., albedo and emissivity) and morphological (e.g., height to width ratio, roof fraction, average building height, and pervious fraction of the canyon floor) properties, are provided for each of the density classes. Building interior minimum and maximum temperatures are prescribed based on climate and socioeconomic considerations. As described in :ref:`Oleson and Feddema (2020) ` the urban properties dataset in :ref:`Jackson et al. (2010) ` was modified with respect to wall and roof thermal properties to correct for biases in heat transfer due to layer and building type averaging. Further changes to the dataset reflect the need for scenario development, thus allowing for the creation of hypothetical wall types, and the easier interchange of wall facets. This slightly modified dataset was an option in CLM5.0. The "raw" urban properties dataset used by the model is created from the urban properties tool which is available as part of the Toolbox for Human-Earth System Integration & Scaling (THESIS) tool set (https://github.com/NCAR/THESISUrbanPropertiesTool; :ref:`Oleson and Feddema (2020) `). The driver script (``urban_prop.csh``) specifies three input csv files (by default, ``mat_prop.csv``, ``lam_spec.csv``, and ``city_spec.csv``; (:numref:`Figure schematic of THESIS urban properties tool`)) that describe the morphological, radiative, and thermal properties of urban areas, plus the minimum building interior temperature, and generates a global dataset at 0.05° latitude by longitude in NetCDF format. This dataset, when combined with the urban extent data described below, is then ingested into the ``mksurfdata_esmf`` tool to create surface datasets at the desired spatial and temporal resolutions. -Urban extent (circa-year 2000), defined for the four density classes, was originally provided by :ref:`Jackson et al. (2010) ` and derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity, and slope (:ref:`Dobson et al. 2000 `). Note that the LD class is not used in CLM because it is highly rural (dominated by vegetation) and better modeled as a vegetated/soil surface. This dataset was used for model versions CLM5 and earlier. A more up to date urban extent dataset was derived for use with CLM6 from a 0.05° urban landcover projection dataset (:ref:`Gao and O'Neill (2020) `) as described in :ref:`Fang et al. (2026) ` (code and auxiliary datasets available at https://figshare.com/s/4a890655b34498c1d082). The :ref:`Gao and O'Neill (2020) ` dataset provides global urban land cover for 2000-2100 in decadal intervals for a historical baseline (year 2000) and five CMIP6 ScenarioMIP Shared Socioeconomic Pathways (SSPs) at 0.05° resolution (2010-2100). Briefly, because the :ref:`Gao and O'Neill (2020) ` dataset only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in the :ref:`Jackson et al. (2010) ` dataset. The decadal urban data are then linearly interpolated to generate annual urban data from 2015-2100. To provide data prior to 2015, the average urban fraction of the five SSP scenarios was calculated in 2010 and 2015. Then annual urban fraction from 2000 to 2014 were obtained by interpolating betwen urban fraction in the historical baseline year 2000, and average SSP years 2010 and 2015. Finally, due to a lack of historical data, data for 1850-1999 were simply copied from year 2000 data. The yearly :ref:`Gao and O'Neill (2020) ` historical and SSP datasets are available for an intermediate model version (CTSM5.3) at 0.05° resolution. +Urban extent (circa-year 2000), defined for the four density classes, was originally provided by :ref:`Jackson et al. (2010) ` and derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity, and slope (:ref:`Dobson et al. 2000 `). Note that the LD class is not used in CLM because it is highly rural (dominated by vegetation) and better modeled as a vegetated/soil surface. This dataset was used for model versions CLM5.0 and earlier. A more up to date urban extent dataset was derived for use with CLM6.0 from a 0.05° urban landcover projection dataset (:ref:`Gao and O'Neill (2020) `) as described in :ref:`Fang et al. (2026) ` (code and auxiliary datasets available at https://figshare.com/s/4a890655b34498c1d082). The :ref:`Gao and O'Neill (2020) ` dataset provides global urban land cover for 2000-2100 in decadal intervals for a historical baseline (year 2000) and five CMIP6 ScenarioMIP Shared Socioeconomic Pathways (SSPs) at 0.05° resolution (2010-2100). Briefly, because the :ref:`Gao and O'Neill (2020) ` dataset only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in the :ref:`Jackson et al. (2010) ` dataset. The decadal urban data are then linearly interpolated to generate annual urban data from 2015-2100. To provide data prior to 2015, the average urban fraction of the five SSP scenarios was calculated in 2010 and 2015. Then annual urban fraction from 2000 to 2014 were obtained by interpolating betwen urban fraction in the historical baseline year 2000, and average SSP years 2010 and 2015. Finally, due to a lack of historical data, data for 1850-1999 were simply copied from year 2000 data. The yearly :ref:`Gao and O'Neill (2020) ` historical and SSP datasets are available for an intermediate model version (CTSM5.3) at 0.05° resolution. However, it was deemed desirable to create a dataset consistent with CMIP7 landcover change protocols. CMIP7 provides urban fraction at 0.25° resolution for 1700-2023. Again, since the dataset only provides the data as a single urban class, the urban area in each grid cell is partitioned according to the ratio of the density types in that grid cell in a year 2023 0.25° resolution version of the :ref:`Gao and O'Neill (2020) ` dataset created as described above. An exception is that the TBD class is not allowed before year 1900 as skyscrapers, etc. had not yet begun to be built. In that case, the urban fraction was split proportionally between the HD and MD classes. Datasets for future scenarios, i.e., 2024-, will be created similarly when CMIP7 data is available.