Note

Please report issues with the manual on the GitHub page.

SUEWS: Surface Urban Energy and Water Balance Scheme

Documentation Status
  • How to get SUEWS?

  • How to use SUEWS?

    • For existing users:

    Overview of changes in this version, see Version 2019a (released on 15 November 2019). If these changes impact your existing simulations, please see appropriate parts of the manual. It may be necessary to adapt some of your input files for for the current version.

    Tip

    A helper python script, SUEWS table converter, is provided to help facilitate the conversion of input files between different SUEWS versions.

    Additionally, the manuals for previous versions can be accessed in respective sections under Version History.

    • For new users:

    Before performing SUEWS simulations, new users should read the overview Introduction, then follow the steps in Preparing to run the model to prepare input files for SUEWS.

    Note there are tutorials learning about running SUEWS available the tutorial.

  • How has SUEWS been used?

The scientific details and application examples of SUEWS can be found in Recent publications.
  • How to cite SUEWS?

    Tip

    Visit the repositories below for different citation styles.

    • Software:

      Sun Ting, Järvi Leena, Grimmond Sue, Lindberg Fredrik, Li Zhenkun, Tang Yihao, Ward Helen: (2019, February 21). SUEWS: Surface Urban Energy and Water Balance Scheme (Version 2018c). Zenodo. doi_software

    • Manual:

      Sun Ting, Järvi Leena, Grimmond Sue, Lindberg Fredrik, Li Zhenkun, Tang Yihao, Ward Helen: (2019, February 21). SUEWS Documentation (Version 2018c). Zenodo. doi_docs

  • How to support SUEWS?

    1. Cite SUEWS appropriately in your work.
    2. Contribute to the development.
    3. Report issues via the GitHub page.
    4. Provide suggestions and feedback.

Note

Please report issues with the manual on the GitHub page.

Introduction

Surface Urban Energy and Water Balance Scheme (SUEWS) (Järvi et al. 2011 [J11], Ward et al. 2016 [W16]) is able to simulate the urban radiation, energy and water balances using only commonly measured meteorological variables and information about the surface cover. SUEWS utilizes an evaporation-interception approach (Grimmond et al. 1991 [G91]), similar to that used in forests, to model evaporation from urban surfaces.

Overview of SUEWS

Overview of SUEWS

The model uses seven surface types: paved, buildings, evergreen trees/shrubs, deciduous trees/shrubs, grass, bare soil and water. The surface state for each surface type at each time step is calculated from the running water balance of the canopy where the evaporation is calculated from the Penman-Monteith equation. The soil moisture below each surface type (excluding water) is taken into account.

Horizontal movement of water above and below ground level is allowed. The user can specify the model time-step, but 5 min is strongly recommended. The main output file is provided at a resolution of 60 min by default. The model provides the radiation and energy balance components, surface and soil wetness, surface and soil runoff and the drainage for each surface. Timestamps refer to the end of the averaging period.

Model applicability: SUEWS is a neighbourhood-scale or local-scale model.

The seven surface types considered in SUEWS

The seven surface types considered in SUEWS

Note

Please report issues with the manual on the GitHub page.

Parameterisations and sub-models within SUEWS

Net all-wave radiation, Q*

There are several options for modelling or using observed radiation components depending on the data available. As a minimum, SUEWS requires incoming shortwave radiation to be provided.

  1. Observed net all-wave radiation can be provided as input instead of being calculated by the model.
  2. Observed incoming shortwave and incoming longwave components can be provided as input, instead of incoming longwave being calculated by the model.
  3. Other data can be provided as input, such as cloud fraction (see options in RunControl.nml).
  4. NARP (Net All-wave Radiation Parameterization, Offerle et al. 2003 [O2003] , Loridan et al. 2011 [L2011] ) scheme calculates outgoing shortwave and incoming and outgoing longwave radiation components based on incoming shortwave radiation, temperature, relative humidity and surface characteristics (albedo, emissivity).

Anthropogenic heat flux, QF

  1. Two simple anthropogenic heat flux sub-models exist within SUEWS:
    • Järvi et al. (2011) [J11] approach, based on heating and cooling degree days and population density (allows distinction between weekdays and weekends).
    • Loridan et al. (2011) [L2011] approach, based on a linear piece-wise relation with air temperature.
  2. Pre-calculated values can be supplied with the meteorological forcing data, either derived from knowledge of the study site, or obtained from other models, for example:
    • LUCY (Allen et al. 2011 [lucy], Lindberg et al. 2013 [lucy2]). A new version has been now included in UMEP. To distinguish it is referred to as LQF
    • GreaterQF (Iamarino et al. 2011 [I11]). A new version has been now included in UMEP. To distinguish it is referred to as GQF

Storage heat flux, ΔQS

  1. Three sub-models are available to estimate the storage heat flux:
    • OHM (Objective Hysteresis Model, Grimmond et al. 1991 [G91OHM], Grimmond & Oke 1999a [GO99QS], 2002 [GO2002]). Storage heat heat flux is calculated using empirically-fitted relations with net all-wave radiation and the rate of change in net all-wave radiation.
    • AnOHM (Analytical Objective Hysteresis Model, Sun et al. 2017 [AnOHM17]). OHM approach using analytically-derived coefficients. Not recommended in this version.
    • ESTM (Element Surface Temperature Method, Offerle et al. 2005 [OGF2005]). Heat transfer through urban facets (roof, wall, road, interior) is calculated from surface temperature measurements and knowledge of material properties. Not recommended in this version.
  2. Alternatively, ‘observed’ storage heat flux can be supplied with the meteorological forcing data.

Turbulent heat fluxes, QH and QE

  1. LUMPS (Local-scale Urban Meteorological Parameterization Scheme, Grimmond & Oke 2002 [GO2002]) provides a simple means of estimating sensible and latent heat fluxes based on the proportion of vegetation in the study area.
  2. SUEWS adopts a more biophysical approach to calculate the latent heat flux; the sensible heat flux is then calculated as the residual of the energy balance. The initial estimate of stability is based on the LUMPS calculations of sensible and latent heat flux. Future versions will have alternative sensible heat and storage heat flux options.

Sensible and latent heat fluxes from both LUMPS and SUEWS are provided in the Output files. Whether the turbulent heat fluxes are calculated using LUMPS or SUEWS can have a major impact on the results. For SUEWS, an appropriate surface conductance parameterisation is also critical [J11] [W16]. For more details see Differences between SUEWS, LUMPS and FRAISE .

Water balance

The running water balance at each time step is based on the urban water balance model of Grimmond et al. (1986) [G86] and urban evaporation-interception scheme of Grimmond and Oke (1991) [G91].

  • Precipitation is a required variable in the meteorological forcing file.
  • Irrigation can be modelled [J11] or observed values can be provided if data are available.
  • Drainage equations and coefficients to use must be specified in the input files.
  • Soil moisture can be calculated by the model.
  • Runoff is permitted:
    • between surface types within each model grid
    • between model grids (Not available in this version.)
    • to deep soil
    • to pipes.

Snowmelt

The snowmelt model is described in Järvi et al. (2014) [Leena2014]. Changes since v2016a: 1) previously all surface states could freeze in 1-h time step, now the freezing surface state is calculated similarly as melt water and can freeze within the snow pack. 2) Snowmelt-related coefficients have also slightly changed (see SUEWS_Snow.txt).

Convective boundary layer

A convective boundary layer (CBL) slab model (Cleugh and Grimmond 2001 [CG2001]) calculates the CBL height, temperature and humidity during daytime (Onomura et al. 2015 [Shiho2015]).

Surface Diagnostics

A MOST-based surface diagnostics module is implemented in 2017b for calculating the surface level diagnostics, including:

  • T2: air temperature at 2 m agl
  • Q2: air specific humidity at 2 m agl
  • U10: wind speed at 10 m agl

The details for formulation of these diagnostics can be found in equations 2.54, 2.55 and 2.56 in Brutsaert (2005) [B05]

Wind, Temperature and Humidity Profiles in the Roughness Sublayer

Wind, temperature and humidity profiles are derived at 30 levels in the surface layer. In order to account for the roughness sublayer and canopy layer, we follow Harman and Finnigan (2007) [HF07], Harman and Finnigan (2008) [HF08], and Theeuwes et al. (2019) [T19].

The 30 levels have a step of 0.1 times the canopy height zh (should still output zh somewhere) dz = 0.1 * zh. However. if 3 x canopy height is less the 10 m steps of 0.3333 m are used:

IF ((3.*Zh) < 10.) THEN
dz = 1./3.
zarray = (/(I, I=1, nz)/)*dz...

Here nz = 30.

Note

The temperature and humidity profiles are calculated from the forcing data down into the canopy. Therefore it is assumed that the forcing temperature and humidity are above the blending height. The wind speed is calculated from the surface (assumed to be zero) upward and does not use the wind speed from the forcing data.

Note

Please report issues with the manual on the GitHub page.

Preparing to run the model

The following is to help with the model setup. Note that there are also starting tutorials for the version of SUEWS in UMEP. The version there is the same (i.e. the executable) as the standalone version so you can swap to that later once you have some familiarity.

Preparatory reading

Read the manual and relevant papers (and references therein):

  • Järvi L, Grimmond CSB & Christen A (2011) The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver. J. Hydrol. 411, 219-237. doi:10.1016/j.jhydrol.2011.10.00
  • Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H & Strachan IB (2014) Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities. Geosci. Model Dev. 7, 1691-1711. doi:10.5194/gmd-7-1691-2014
  • Ward HC, Kotthaus S, Järvi L and Grimmond CSB (2016) Surface Urban Energy and Water Balance Scheme (SUEWS): development and evaluation at two UK sites. Urban Climate 18, 1-32. doi:10.1016/j.uclim.2016.05.001

See other publications with example applications

Decide what type of model run you are interested in

  Available in this release
LUMPS Yes – not standalone
SUEWS at a point or for an individual area Yes
SUEWS for multiple grids or areas Yes
SUEWS with Boundary Layer (BL) Yes
SUEWS with snow Yes
SUEWS with SOLWEIG No
SUEWS with SOLWEIG and BL No

Download the program and example data files

Visit the website to receive a link to download the program and example data files. Select the appropriate compiled version of the model to download. For windows there is an installation version which will put the programs and all the files into the appropriate place. There is also a version linked to QGIS: UMEP.

Note, as the definition of long double precision varies between computers (e.g. Mac vs Windows) slightly different results may occur in the output files.

Test/example files are given for the London KCL site, 2011 data (denoted Kc11)

In the following, SS is the site code (e.g. Kc), ss the grid ID, YYYY the year and tt the time interval.

Filename Description Input/output
SSss_data.txt Meteorological input Input file (60-min)
SSss_YYYY_data_5.txt Meteorological input Input file (5-min)
InitialConditionsSSss Initial conditions Input - _YYYY.nml(+) file
SUEWS_SiteInfo_SSss.x Spreadsheet Input lsm containing all other input information
RunControl.nml Sets model run Input (located in options main directory)
SS_Filechoices.txt Summary of model run Output options
SSss_YYYY_5.txt (Optional) 5-min Output resolution output file
SSss_YYYY_60.txt 60-min resolution Output output file
SSss_DailyState.txt Daily state variables Output (all years in one file)

(+) There is a second file InitialConditionsSSss_YYYY_EndOfRun.nml or InitialConditionsSSss_YYYY+1.nml in the input directory. At the end of the run, and at the end of each year of the run, these files are written out so that this information could be used to initialize further model runs.

Run the model for example data

Before running the model with your own data, check that you get the same results as the test run example files provided. Copy the example output files elsewhere so you can compare the results. When you run the program it will write over the supplied files.

To run the model you can use Command Prompt (in the directory where the programme is located type the model name) or just double click the executable file.

Please see Troubleshooting if you have problems running the model.

Preparation of data

The information required to run SUEWS for your site consists of:

  1. Continuous meteorological forcing data for the entire period to be modelled without gaps. If you need help preparing the data you can use some of the UMEP tools.
  2. Knowledge of the surface and soil conditions immediately prior to the first model timestep. If these initial conditions are unknown, model spinup can help; i.e. run the model and use the output at the end of the run to infer the conditions at the start of the main run).
  3. The location of the site (latitude, longitude, altitude).
  4. Information about the characteristics of the surface, including land cover, heights of buildings and trees, radiative characteristics (e.g. albedo, emissivity), drainage characteristics, soil characteristics, snow characteristics, phenological characteristics (e.g. seasonal cycle of LAI).
  5. Information about human behaviour, including energy use and water use (e.g. for irrigation or street cleaning) and snow clearing (if applicable). The anthropogenic energy use and water use may be provided as a time series in the meteorological forcing file if these data are available or modelled based on parameters provided to the model, including population density, hourly and weekly profiles of energy and water use, information about the proportion of properties using irrigation and the type of irrigation (automatic or manual).

It is particularly important to ensure the following input information is appropriate and representative of the site:

  • Fractions of different land cover types and (less so) heights of buildings [W16]
  • Accurate meteorological forcing data, particularly precipitation and incoming shortwave radiation [Ko17]
  • Initial soil moisture conditions [Best2014]
  • Anthropogenic heat flux parameters, particularly if there are considerable energy emissions from transport, buildings, metabolism, etc [W16]
  • External water use (if irrigation or street cleaning occurs)
  • Snow clearing (if running the snow option)
  • Surface conductance parameterisation [J11] [W16]

SUEWS can be run either for an individual area or for multiple areas. There is no requirement for the areas to be of any particular shape but here we refer to them as model ‘grids’.

Preparation of site characteristics and model parameters

The area to be modelled is described by a set of characteristics that are specified in the SUEWS_SiteSelect.txt file. Each row corresponds to one model grid for one year (i.e. running a single grid over three years would require three rows; running two grids over two years would require four rows). Characteristics are often selected by a code for a particular set of conditions. For example, a specific soil type (links to SUEWS_Soil.txt) or characteristics of deciduous trees in a particular region (links to SUEWS_Veg.txt). The intent is to build a library of characteristics for different types of urban areas. The codes are specified by the user, must be integer values and must be unique within the first column of each input file, otherwise the model will return an error. (Note in SUEWS_SiteSelect.txt the first column is labelled ‘Grid’ and can contain repeat values for different years.) See Input files for details. Note UMEP maybe helpful for components of this.

Land cover

For each grid, the land cover must be classified using the following surface types:

Classification Surface type File where characteristics are specified
Non-vegetated Paved surfaces SUEWS_NonVeg.txt
  Building SUEWS_NonVeg.txt
  Bare soil SUEWS_NonVeg.txt
Vegetation Evergreen trees SUEWS_Veg.txt
  Deciduous trees SUEWS_Veg.txt
  Grass SUEWS_Veg.txt
Water Water SUEWS_Water.txt
Snow Snow SUEWS_Snow.txt

The surface cover fractions (i.e. proportion of the grid taken up by each surface) must be specified in SUEWS_SiteSelect.txt. The surface cover fractions are critical, so make certain that the different surface cover fractions are appropriate for your site.

For some locations, land cover information may be already available (e.g. from various remote sensing resources). If not, websites like Bing Maps and Google Maps allow you to see aerial images of your site and can be used to estimate the relative proportion of each land cover type. If detailed spatial datasets are available, UMEP allows for a direct link to a GIS environment using QGIS.

Anthropogenic heat flux (QF)

You can either model QF within SUEWS or provide it as an input.

  • To model it population density is needed as an input for LUMPS and SUEWS to calculate QF.
  • If you have no information about the population of the site we recommend that you use the LUCY model [lucy] [lucy2] to estimate the anthropogenic heat flux which can then be provided as input SUEWS along with the meteorological forcing data.

Alternatively, you can use the updated version of LUCY called LQF, which is included in UMEP.

Other information

The surface cover fractions and population density can have a major impact on the model output. However, it is important to consider the suitability of all parameters for your site. Using inappropriate parameters may result in the model returning an error or, worse, generating output that is simply not representative of your site. Please read the section on Input files. Recommended or reasonable ranges of values are suggested for some parameters, along with important considerations for how to select appropriate values for your site.

Data Entry

To create the series of input text files describing the characteristics of your site, there are three options:

  1. Data can be entered directly into the input text files. The example (.txt) files provide a template to create your own files which can be edited with A text editor directly.
  2. Data can be entered into the spreadsheet SUEWS_SiteInfo.xlsm and the input text files generated by running the macro.
  3. Use UMEP.

To run the xlsm macro: Enter the data for your site into the xlsm spreadsheet SUEWS_SiteInfo.xlsm and then use the macro to create the text files which will appear the same directory.

If there is a problem

  • Make sure none of the text files to be generated are open.
  • It is recommended to close the spreadsheet before running the actual model code.

Note that in all txt files:

  • The first two rows are headers. The first row is the column number; the second row is the column name.
  • The names and order of the columns should not be altered from the templates, as these are checked by the model and errors will be returned if particular columns cannot be found.
  • Since v2017a it is no longer necessary for the meteorological forcing data to have two rows with -9 in column 1 as their last two rows.
  • “!” indicates a comment, so any text following “!” on the same line will not be read by the model.
  • If data are unavailable or not required, enter the value -999 in the correct place in the input file.
  • Ensure the units are correct for all input information. See Input files for a description of parameters.

In addition to these text files, the following files are also needed to run the model.

Preparation of the RunControl file

In the RunControl.nml file the site name (SS) and directories for the model input and output are given. This means before running the model (even the with the example datasets) you must either

  1. open the RunControl.nml file and edit the input and output file paths and the site name (with a A text editor) so that they are correct for your setup, or
  2. create the directories specified in the RunControl.nml file

From the given site identification the model identifies the input files and generates the output files. For example if you specify:

FileOutputPath = “C:\FolderName\SUEWSOutput\”

and use site code SS the model creates an output file:

C:\FolderName\SUEWSOutput\SSss_YYYY_TT.txt

Note

remember to add the last backslash in windows and slash in Linux/Mac

If the file paths are not correct the program will return an error when run and write the error to the Error messages: problems.txt file.

Preparation of the Meteorological forcing data

The model time-step is specified in RunControl.nml (5 min is highly recommended). If meteorological forcing data are not available at this resolution, SUEWS has the option to downscale (e.g. hourly) data to the time-step required. See details about the SSss_YYYY_data_tt.txt to learn more about choices of data input. Each grid can have its own meteorological forcing file, or a single file can be used for all grids. The forcing data should be representative of the local-scale, i.e. collected (or derived) above the height of the roughness elements (buildings and trees).

Preparation of the InitialConditions file

Information about the surface state and meteorological conditions just before the start of the run are provided in the Initial Conditions file. At the very start of the run, each grid can have its own Initial Conditions file, or a single file can be used for all grids. For details see Initial Conditions file.

Run the model for your site

To run the model you can use Command Prompt (in the directory where the programme is located type the model name) or just double click the executable file.

Please see Troubleshooting if you have problems running the model.

Analyse the output

It is a good idea to perform initial checks that the model output looks reasonable.

Characteristic Things to check
Leaf area index
Does the phenology look appropriate?
  • what does the seasonal cycle of leaf area index (LAI) look like?
  • Are the leaves on the trees at approximately the right time of the year?
Kdown
Is the timing of diurnal cycles correct for the incoming solar radiation?
  • Although Kdown is a required input, it is also included in the output file. It is a good idea to check that the timing of Kdown in the output file is appropriate, as problems can indicate errors with the timestamp, incorrect time settings or problems with the disaggregation. In particular, make sure the sign of the longitude is specified correctly in SUEWS_SiteSelect.txt.
  • Checking solar angles (zenith and azimuth) can also be a useful check that the timing is correct.
Albedo
Is the bulk albedo correct?
  • This is critical because a small error has an impact on all the fluxes (energy and hydrology).
  • If you have measurements of outgoing shortwave radiation compare these with the modelled values.
  • How do the values compare to literature values for your area?

Summary of files

The table below lists the files required to run SUEWS and the output files produced. SS is the two-letter code (specified in RunControl) representing the site name, ss is the grid identification (integer values between 0 and 2,147,483,647 (largest 4-byte integer)) and YYYY is the year. TT is the resolution of the input/output file and tt is the model time-step.

The last column indicates whether the files are needed/produced once per run (1/run), or once per day (1/day), for each year (1/year) or for each grid (1/grid):

[B] indicates files used with the CBL part of SUEWS (BLUEWS) and therefore are only needed/produced if this option is selected
[E] indicates files associated with ESTM storage heat flux models and therefore are only needed/produced if this option is selected

Get in contact

For issues met in using SUEWS, we recommend the following ways to get in contact with the developers and the SUEWS community:

  1. Report issues on our GitHub page.
  2. Ask for help by joining the Email-list for SUEWS.

Note

Please report issues with the manual on the GitHub page.

Input files

SUEWS allows you to input a large number of parameters to describe the characteristics of your site. You should not assume that the example values provided in files or in the tables below are appropriate. Values marked with ‘MD’ are examples of recommended values (see the suggested references to help decide how appropriate these are for your site/model domain); values marked with ‘MU’ need to be set (i.e. changed from the example) for your site/model domain.

Note

Please report issues with the manual on the GitHub page.

RunControl.nml

The file RunControl.nml is a namelist that specifies the options for the model run. It must be located in the same directory as the executable file.

A sample file of RunControl.nml looks like

&RunControl
CBLUse=0
SnowUse=0
SOLWEIGUse=0
NetRadiationMethod=3 
EmissionsMethod=2
StorageHeatMethod=3
OHMIncQF=0
StabilityMethod=2
RoughLenHeatMethod=2
RoughLenMomMethod=2
SMDMethod=0
WaterUseMethod=0
FileCode='Saeve'
FileInputPath="./Input/"
FileOutputPath="./Output/"
MultipleMetFiles=0
MultipleInitFiles=0
MultipleESTMFiles=1
KeepTstepFilesIn=1
KeepTstepFilesOut=1
WriteOutOption=2
ResolutionFilesOut=3600
Tstep=300
ResolutionFilesIn=3600
ResolutionFilesInESTM=3600 
DisaggMethod=1         
RainDisaggMethod=100  
DisaggMethodESTM=1      
SuppressWarnings=1     
KdownZen=0
diagnose=0
/

Note

  • In Linux and Mac, please add an empty line after the end slash.
  • The file is not case-sensitive.
  • The parameters and variables can appear in any order.

The parameters and their setting instructions are provided through the links below:

Note

Please report issues with the manual on the GitHub page.

Scheme options

CBLuse

Warning

Not available in this version.

Requirement:

Required

Description:

Determines whether a CBL slab model is used to calculate temperature and humidity.

Configuration:
Value Comments
0
CBL model not used. SUEWS and LUMPS use temperature and humidity provided in the meteorological forcing file.
1
CBL model is used to calculate temperature and humidity used in SUEWS and LUMPS.
SnowUse
Requirement:

Required

Description:

Determines whether the snow part of the model runs.

Configuration:
Value Comments
0
Snow calculations are not performed.
1
Snow calculations are performed.
NetRadiationMethod
Requirement:

Required

Description:

Determines method for calculation of radiation fluxes.

Configuration:
Value Comments
0 Uses observed values of Q* supplied in meteorological forcing file.
1 Q* modelled with L↓ observations supplied in meteorological forcing file. Zenith angle not accounted for in albedo calculation.
2 Q* modelled with L↓ modelled using cloud cover fraction supplied in meteorological forcing file (Loridan et al. 2011 [L2011]). Zenith angle not accounted for in albedo calculation.
3 Q* modelled with L↓ modelled using air temperature and relative humidity supplied in meteorological forcing file (Loridan et al. 2011 [L2011]). Zenith angle not accounted for in albedo calculation.
100 Q* modelled with L↓ observations supplied in meteorological forcing file. Zenith angle accounted for in albedo calculation. SSss_YYYY_NARPOut.txt file produced. Not recommended in this version.
200 Q* modelled with L↓ modelled using cloud cover fraction supplied in meteorological forcing file (Loridan et al. 2011 [L2011]). Zenith angle accounted for in albedo calculation. SSss_YYYY_NARPOut.txt file produced. Not recommended in this version.
300 Q* modelled with L↓ modelled using air temperature and relative humidity supplied in meteorological forcing file (Loridan et al. 2011 [L2011]). Zenith angle accounted for in albedo calculation. SSss_YYYY_NARPOut.txt file produced. Not recommended in this version.
EmissionsMethod
Requirement:

Required

Description:

Determines method for QF calculation.

Configuration:
Value Comments
0 Uses values provided in the meteorological forcing file (SSss_YYYY_data_tt.txt). If you do not want to include QF to the calculation of surface energy balance, you should set values in the meteorological forcing file to zero to prevent calculation of QF. UMEP provides two methods to calculate QF LQF which is simpler GQF which is more complete but requires more data inputs
1 Not recommended in this version. Calculated according to Loridan et al. (2011) [L2011] using coefficients specified in SUEWS_AnthropogenicEmission.txt. Modelled values will be used even if QF is provided in the meteorological forcing file.
2 Recommended in this version. Calculated according to Järvi et al. (2011) [J11] using coefficients specified in SUEWS_AnthropogenicEmission.txt and diurnal patterns specified in SUEWS_Profiles.txt. Modelled values will be used even if QF is provided in the meteorological forcing file.
3 Updated Loridan et al. (2011) [L2011] method using daily (not instantaneous) air temperature (HDD(id-1,3)) using coefficients specified in SUEWS_AnthropogenicEmission.txt. Modelled values will be used even if QF is provided in the meteorological forcing file.
StorageHeatMethod
Requirement:

Required

Description:

Determines method for calculating storage heat flux ΔQS.

Configuration:
Value Comments
1 ΔQS modelled using the objective hysteresis model (OHM) [G91OHM] using parameters specified for each surface type.
2 Uses observed values of ΔQS supplied in meteorological forcing file.
3 ΔQS modelled using AnOHM. Not recommended in this version.
4 ΔQS modelled using the Element Surface Temperature Method (ESTM) (Offerle et al. 2005 [OGF2005] ). Not recommended in this version.
OHMIncQF
Requirement:

Required

Description:

Determines whether the storage heat flux calculation uses Q* or ( Q* +QF).

Configuration:
Value Comments
0
ΔQS modelled Q* only.
1
ΔQS modelled using Q*+QF.
StabilityMethod
Requirement:

Required

Description:

Defines which atmospheric stability functions are used.

Configuration:
Value Comments
0 Not used.
1 Not used.
2
  • Momentum:
    • unstable: Dyer (1974) [D74] modified by Högstrom (1988) [H1988]
    • stable: Van Ulden and Holtslag (1985) [VUH85]
  • Heat: Dyer (1974) [D74] modified by Högstrom (1988) [H1988]

Not recommended in this version.

3
  • Momentum: Campbell and Norman (Eq 7.27, Pg97) [CN1988]
  • Heat

Recommended in this version.

4
  • Momentum: Businger et al. (1971) [B71] modified by Högstrom (1988) [H1988]
  • Heat: Businger et al. (1971) [B71] modified by Högstrom (1988) [H1988]

Not recommended in this version.

RoughLenHeatMethod
Requirement:

Required

Description:

Determines method for calculating roughness length for heat.

Configuration:
Value Comments
1 Uses value of 0.1z0m.
2

Calculated according to Kawai et al. (2009) [Ka09].

Recommended in this version.

3 Calculated according to Voogt and Grimmond (2000) [VG00].
4 Calculated according to Kanda et al. (2007) [Ka07].
RoughLenMomMethod
Requirement:

Required

Description:

Determines how aerodynamic roughness length (z0m) and zero displacement height (zdm) are calculated.

Configuration:
Value Comments
1

Values specified in SUEWS_SiteSelect.txt are used.

Tip

Note that UMEP provides tools to calculate these. See Kent et al. (2017a) [Kent2017a] for recommendations on methods. Kent et al. (2017b) [Kent2017b] have developed a method to include vegetation which is also avaialble within UMEP.

2 z0m and zd are calculated using ‘rule of thumb’ (Grimmond and Oke 1999 [GO99]) using mean building and tree height specified in SUEWS_SiteSelect.txt. z0m and zd are adjusted with time to account for seasonal variation in porosity of deciduous trees.
3 z0m and zd are calculated based on the MacDonald et al. (1998) [Mc98] method using mean building and tree heights, plan area fraction and frontal areal index specified in SUEWS_SiteSelect.txt. z0m and zd are adjusted with time to account for seasonal variation in porosity of deciduous trees.
SMDMethod
Requirement:

Required

Description:

Determines method for calculating soil moisture deficit (SMD).

Configuration:
Value Comments
0 SMD modelled using parameters specified in SUEWS_Soil.txt. Recommended in this version.
1 Observed SM provided in the meteorological forcing file is used. Data are provided as volumetric soil moisture content. Metadata must be provided in SUEWS_Soil.txt.
2 Observed SM provided in the meteorological forcing file is used. Data are provided as gravimetric soil moisture content. Metadata must be provided in SUEWS_Soil.txt.
WaterUseMethod
Requirement:

Required

Description:

Defines how external water use is calculated.

Configuration:
Value Comments
0 External water use modelled using parameters specified in SUEWS_Irrigation.txt.
1 Observations of external water use provided in the meteorological forcing file are used.

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

SUEWS Site Information

The following text files provide SUEWS with information about the study area.

Note

Please report issues with the manual on the GitHub page.

SUEWS_AnthropogenicEmission.txt

Note

this file used to be named as SUEWS_AnthropogenicHeat.txt and is changed to this name in v2019a.

SUEWS_AnthropogenicEmission.txt provides the parameters needed to model the anthropogenic heat flux using either the method of Järvi et al. (2011) based on heating and cooling degree days (EmissionsMethod = 2 in RunControl.nml) or the method of Loridan et al. (2011) based on air temperature (EmissionsMethod = 1 in RunControl.nml).

The sub-daily variation in anthropogenic heat flux is modelled according to the daily cycles specified in SUEWS_Profiles.txt.

Alternatively, if available, the anthropogenic heat flux can be provided in the met forcing file (and set EmissionsMethod = 0 in RunControl.nml) by filling the qf column with valid values.

No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 BaseTHDD MU Base temperature for heating degree days [°C]
3 QF_A_WD MU O Base value for QF on weekdays [W m-2 (Cap ha-1 )-1 ]
4 QF_B_WD MU O Parameter related to cooling degree days on weekdays [W m-2 K-1 (Cap ha-1 )-1]
5 QF_C_WD MU O Parameter related to heating degree days on weekdays [W m-2 K-1 (Cap ha-1 )-1]
6 QF_A_WE MU O Base value for QF on weekends [W m-2 (Cap ha-1 )-1]
7 QF_B_WE MU O Parameter related to cooling degree days on weekends [W m-2 K-1 (Cap ha-1 )-1]
8 QF_C_WE MU O Parameter related to heating degree days on weekends [W m-2 K-1 (Cap ha-1 )-1]
9 AHMin_WD MU O Minimum QF on weekdays [W m-2]
10 AHMin_WE MU O Minimum QF on weekends [W m-2]
11 AHSlope_Heating_WD MU O Heating slope of QF on weekdays [W m-2 K-1]
12 AHSlope_Heating_WE MU O Heating slope of QF on weekends [W m-2 K-1]
13 AHSlope_Cooling_WD MU O Cooling slope of QF on weekdays [W m-2 K-1]
14 AHSlope_Cooling_WE MU O Cooling slope of QF on weekends [W m-2 K-1]
15 TCritic_Heating_WD MU O Critical heating temperature on weekdays [°C]
16 TCritic_Heating_WE MU O Critical heating temperature on weekends [°C]
17 TCritic_Cooling_WD MU O Critical cooling temperature on weekdays [°C]
18 TCritic_Cooling_WE MU O Critical cooling temperature on weekends [°C]
19 EnergyUseProfWD MU O Code linking to EnergyUseProfWD in SUEWS_Profiles.txt.
20 EnergyUseProfWE MU O Code linking to EnergyUseProfWE in SUEWS_Profiles.txt.
21 ActivityProfWD MU O Code linking to ActivityProfWD in SUEWS_Profiles.txt.
22 ActivityProfWE MU O Code linking to ActivityProfWE in SUEWS_Profiles.txt.
23 TraffProfWD MU O Code for traffic activity profile (weekdays) linking to Code of SUEWS_Profiles.txt. Not used in v2018a.
24 TraffProfWE MU O Code for traffic activity profile (weekends) linking to Code of SUEWS_Profiles.txt. Not used in v2018a.
25 PopProfWD MU O Code for population density profile (weekdays) linking to Code of SUEWS_Profiles.txt.
26 PopProfWE MU O Code for population density profile (weekends) linking to Code of SUEWS_Profiles.txt.
27 MinQFMetab MU O Minimum value for human heat emission. [W m-2]
28 MaxQFMetab MU O Maximum value for human heat emission. [W m-2]
29 MinFCMetab MU O Minimum (night) CO2 from human metabolism. [W m-2]
30 MaxFCMetab MU O Maximum (day) CO2 from human metabolism. [W m-2]
31 FrPDDwe MU O Fraction of weekend population to weekday population. [-]
32 FrFossilFuel_Heat MU O Fraction of fossil fuels used for building heating [-]
33 FrFossilFuel_NonHeat MU O Fraction of fossil fuels used for building energy use [-]
34 EF_umolCO2perJ MU O Emission factor for fuels used for building heating.
35 EnEF_v_Jkm MU O Emission factor for heat [J k|m^-1|].
36 FcEF_v_kgkmWD MU O CO2 emission factor for weekdays [kg km-1]
37 FcEF_v_kgkmWE MU O CO2 emission factor for weekends [kg km-1]
38 CO2PointSource MU O CO2 emission factor [kg km-1]
39 TrafficUnits MU O Units for the traffic rate for the study area. Not used in v2018a.

An example SUEWS_AnthropogenicEmission.txt can be found below:

1           2                 3                4                5                6                7                8              9               10                11                 12                 13                 14                 15                 16                 17                 18                 19              20              21             22              23             24             25             26               27            28             29             30                 31               32                33                   34             35                    36               37            38             39
Code        BaseTHDD          QF_A_WD          QF_B_WD          QF_C_WD          QF_A_WE          QF_B_WE          QF_C_WE        AHMin_WD        AHMin_WE          AHSlope_Heating_WD AHSlope_Heating_WE AHSlope_Cooling_WD AHSlope_Cooling_WE TCritic_Heating_WD TCritic_Heating_WE TCritic_Cooling_WD TCritic_Cooling_WE EnergyUseProfWD EnergyUseProfWE ActivityProfWD ActivityProfWE  TraffProfWD    TraffProfWE    PopProfWD      PopProfWE        MinQFMetab    MaxQFMetab     MinFCMetab     MaxFCMetab         FrPDDwe          FrFossilFuel_Heat FrFossilFuel_NonHeat EF_umolCO2perJ EnEF_v_Jkm            FcEF_v_kgkmWD    FcEF_v_kgkmWE CO2PointSource TrafficUnits
10          18.2000           0.1000           0.0099           0.0102           0.1000           0.0099           0.0102         15.0000         15.0000           2.7000             2.7000             2.7000             2.7000             7.0000             7.0000             7.0000             7.0000             44.0000         45.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.0500            0.0000               1.1590         3970000.0000          0.2850           0.2850        0              1.0000
11          18.2000           0.3081           0.0099           0.0102           0.3081           0.0099           0.0102         -999.0000       -999.0000         -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          44.0000         45.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.0500            0.0000               1.1590         4110000.0000          0.2850           0.2850        0              1.0000
551         18.2000           0.1446           0.0000           0.0037           0.1329           0.0000           0.0038         -999.0000       -999.0000         -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          42.0000         43.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.7000            0.7000               1.1590         3970000.0000          0.2850           0.2850        0              1.0000
5512        18.2000           0.3081           0.0099           0.0102           0.3081           0.0099           0.0102         -999.0000       -999.0000         -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          -999.0000          42.0000         43.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.7000            0.7000               1.1590         3970000.0000          0.2850           0.2850        0              1.0000
661         18.2000           0.3081           0.0099           0.0102           0.3081           0.0099           0.0102         15.0000         15.0000           2.7000             2.7000             2.7000             2.7000             7.0000             7.0000             7.0000             7.0000             42.0000         43.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.7000            0.7000               1.1590         3970000.0000          0.2850           0.2850        0              1.0000
2           18.2000           0.1000           0.0099           0.0200           0.1000           0.0099           0.0200         15.0000         15.0000           2.7000             2.7000             2.7000             2.7000             7.0000             7.0000             7.0000             7.0000             44.0000         45.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.0500            0.0000               1.1590         4110000.0000          0.2850           0.2850        0              1.0000
3           18.2000           0.1000           0.0099           0.0300           0.1000           0.0099           0.0300         15.0000         15.0000           2.7000             2.7000             2.7000             2.7000             7.0000             7.0000             7.0000             7.0000             44.0000         45.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.0500            0.0000               1.1590         4110000.0000          0.2850           0.2850        0              1.0000
4           18.2000           0.1000           0.0099           0.0400           0.1000           0.0099           0.0400         15.0000         15.0000           2.7000             2.7000             2.7000             2.7000             7.0000             7.0000             7.0000             7.0000             44.0000         45.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.0500            0.0000               1.1590         4110000.0000          0.2850           0.2850        0              1.0000
51          18.2000           0.1217           0.0099           0.0400           0.1156           0.0099           0.0400         15.0000         15.0000           2.7000             2.7000             2.7000             2.7000             7.0000             7.0000             7.0000             7.0000             44.0000         45.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.0500            0.0000               1.1590         4110000.0000          0.2850           0.2850        0              1.0000
52          18.2000           0.1702           0.0099           0.0400           0.1446           0.0099           0.0400         15.0000         15.0000           2.7000             2.7000             2.7000             2.7000             7.0000             7.0000             7.0000             7.0000             44.0000         45.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.0500            0.0000               1.1590         4110000.0000          0.2850           0.2850        0              1.0000
53          18.2000           0.0772           0.0099           0.0400           0.0754           0.0099           0.0400         15.0000         15.0000           2.7000             2.7000             2.7000             2.7000             7.0000             7.0000             7.0000             7.0000             44.0000         45.0000         55663.0000     55664.0000      701.0000       702.0000       801.0000       802.0000         75.0000       175.0000       120.0000       280.0000           1.0000           0.0500            0.0000               1.1590         4110000.0000          0.2850           0.2850        0              1.0000
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_BiogenCO2.txt

Caution

The BiogenCO2 part is under development and not ready for use.

SUEWS_BiogenCO2.txt provides the parameters needed to model the Biogenic CO2 characteristics of vegetation surfaces.

No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 alpha MU O The mean apparent ecosystem quantum. Represents the initial slope of the light-response curve.
3 beta MU O The light-saturated gross photosynthesis of the canopy. [umol m-2 s-1 ]
4 theta MU O The convexity of the curve at light saturation.
5 alpha_enh MU O Part of the alpha coefficient related to the fraction of vegetation.
6 beta_enh MU O Part of the beta coefficient related to the fraction of vegetation.
7 resp_a MU O Respiration coefficient a.
8 resp_b MU O Respiration coefficient b - related to air temperature dependency.
9 min_respi MU O Minimum soil respiration rate (for cold-temperature limit) [umol m-2 s-1].

An example SUEWS_BiogenCO2.txt can be found below:

1     2       3       4       5           6          7        8        9
Code  alpha   beta    theta   alpha_enh   beta_enh   resp_a   resp_b   min_respi
11    0.044   43.35   -999     -999        -999       1.08     0.064   0.6 ! London/Swindon , plant canopies, Ruimy et al. (1995)
12    0.0593  35      -999     -999        -999       1.08     0.064   0.6 ! Hardwood forest, Schmid et al. (2000)
13    0.0205  16.3    -999     -999        -999       1.08     0.064   0.6 ! Temperate grassland, Flanagan et al. (2002)
21    0.031   17.793  0.723    -999        -999       3.229    0.0329  0.6 ! Helsinki
31    0.005   8.747   0.96     0.016       33.454     2.43     0       0.6 ! Helsinki
32    0.004   8.747   0.96     0.016       33.353     2.43     0       0.6 ! Helsinki test
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_Conductance.txt

SUEWS_Conductance.txt contains the parameters needed for the Jarvis (1976) [Ja76] surface conductance model used in the modelling of evaporation in SUEWS. These values should not be changed independently of each other. The suggested values below have been derived using datasets for Los Angeles and Vancouver (see Järvi et al. (2011) [J11]) and should be used with gsModel = 1. An alternative formulation ( gsModel =2) uses slightly different functional forms and different coefficients (with different units).

No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 G1 MD Related to maximum surface conductance [mm s-1]
3 G2 MD Related to Kdown dependence [W m-2]
4 G3 MD Related to VPD dependence [units depend on gsModel]
5 G4 MD Related to VPD dependence [units depend on gsModel]
6 G5 MD Related to temperature dependence [°C]
7 G6 MD Related to soil moisture dependence [mm-1]
8 TH MD Upper air temperature limit [°C]
9 TL MD Lower air temperature limit [°C]
10 S1 MD A parameter related to soil moisture dependence [-]
11 S2 MD A parameter related to soil moisture dependence [mm]
12 Kmax MD Maximum incoming shortwave radiation [W m-2]
13 gsModel MD Formulation choice for conductance calculation.

An example SUEWS_Conductance.txt can be found below:

1    2       3        4      5      6       7      8  9   10   11 12   13
Code G1      G2       G3     G4     G5      G6     TH TL  S1   S2 Kmax gsModel
100  16.4764 566.0923 0.2163 3.3649 11.0764 0.0176 40 0   0.45 15 1200 1       ! Default Jarvi et al. (2011) gsModel=1
200  3.5     200      0.13   0.7    30      0.05   55 -10 5.56 0  1200 2       ! Updated Ward  et al. (2016) gsModel=2
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_Irrigation.txt

SUEWS includes a simple model for external water use if observed data are not available. The model calculates daily water use from the mean daily air temperature, number of days since rain and fraction of irrigated area using automatic/manual irrigation. The sub-daily pattern of water use is modelled according to the daily cycles specified in SUEWS_Profiles.txt.

Alternatively, if available, the external water use can be provided in the met forcing file (and set WaterUseMethod = 1 in RunControl.nml) by filling the Wuh columns with valid values.

No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 Ie_start MU Day when irrigation starts [DOY]
3 Ie_end MU Day when irrigation ends [DOY]
4 InternalWaterUse MU Internal water use [mm h-1]
5 Faut MU Fraction of irrigated area that is irrigated using automated systems
6 Ie_a1 MD Coefficient for automatic irrigation model [mm d-1 ]
7 Ie_a2 MD Coefficient for automatic irrigation model [mm d-1 K-1]
8 Ie_a3 MD Coefficient for automatic irrigation model [mm d-2 ]
9 Ie_m1 MD Coefficient for manual irrigation model [mm d-1 ]
10 Ie_m2 MD Coefficient for manual irrigation model [mm d-1 K-1]
11 Ie_m3 MD Coefficient for manual irrigation model [mm d-2 ]
12 DayWat(1) MU Irrigation allowed on Sundays [1], if not [0]
13 DayWat(2) MU Irrigation allowed on Mondays [1], if not [0]
14 DayWat(3) MU Irrigation allowed on Tuesdays [1], if not [0]
15 DayWat(4) MU Irrigation allowed on Wednesdays [1], if not [0]
16 DayWat(5) MU Irrigation allowed on Thursdays [1], if not [0]
17 DayWat(6) MU Irrigation allowed on Fridays [1], if not [0]
18 DayWat(7) MU Irrigation allowed on Saturdays [1], if not [0]
19 DayWatPer(1) MU Fraction of properties using irrigation on Sundays [0-1]
20 DayWatPer(2) MU Fraction of properties using irrigation on Mondays [0-1]
21 DayWatPer(3) MU Fraction of properties using irrigation on Tuesdays [0-1]
22 DayWatPer(4) MU Fraction of properties using irrigation on Wednesdays [0-1]
23 DayWatPer(5) MU Fraction of properties using irrigation on Thursdays [0-1]
24 DayWatPer(6) MU Fraction of properties using irrigation on Fridays [0-1]
25 DayWatPer(7) MU Fraction of properties using irrigation on Saturdays [0-1]

An example SUEWS_Irrigation.txt can be found below:

1     	 2        	 3      	 4                	 5    	 6       	 7     	 8     	 9      	 10    	 11    	 12        	 13        	 14        	 15        	 16        	 17        	 18        	 19           	 20           	 21           	 22           	 23           	 24           	 25
Code  	 Ie_start 	 Ie_end 	 InternalWaterUse 	 Faut 	 Ie_a1   	 Ie_a2 	 Ie_a3 	 Ie_m1  	 Ie_m2 	 Ie_m3 	 DayWat(1) 	 DayWat(2) 	 DayWat(3) 	 DayWat(4) 	 DayWat(5) 	 DayWat(6) 	 DayWat(7) 	 DayWatPer(1) 	 DayWatPer(2) 	 DayWatPer(3) 	 DayWatPer(4) 	 DayWatPer(5) 	 DayWatPer(6) 	 DayWatPer(7)
99999 	 1        	 366    	 0                	 0    	 0       	 0     	 0     	 0      	 0     	 0     	 0         	 0         	 0         	 0         	 0         	 0         	 0         	 0            	 0            	 0            	 0            	 0            	 0            	 0 ! No        irrigation
1     	 152      	 243    	 0                	 0.2  	 -84.535 	 9.959 	 3.674 	 -25.36 	 2.988 	 1.102 	 1         	 1         	 1         	 1         	 1         	 1         	 1         	 1            	 1            	 1            	 1            	 1            	 1            	 1
550   	 1        	 366    	 0                	 0    	 0       	 0     	 0     	 0      	 0     	 0     	 0         	 0         	 0         	 0         	 0         	 0         	 0         	 0            	 0            	 0            	 0            	 0            	 0            	 0 ! Swindon 	 "(not        used,   no           irrigation)"
660   	 1        	 366    	 0                	 0    	 0       	 0     	 0     	 0      	 0     	 0     	 0         	 0         	 0         	 0         	 0         	 0         	 0         	 0            	 0            	 0            	 0            	 0            	 0            	 0 ! London  	 (assume      no      irrigation   at             the   moment)
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_NonVeg.txt

SUEWS_NonVeg.txt specifies the characteristics for the non-vegetated surface cover types (Paved, Bldgs, BSoil) by linking codes in column 1 of SUEWS_NonVeg.txt to the codes specified in SUEWS_SiteSelect.txt (Code_Paved, Code_Bldgs, Code_BSoil). Each row should correspond to a particular surface type. For suggestions on how to complete this table, see: Typical Values.

No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 AlbedoMin MU Effective surface albedo (middle of the day value) for wintertime (not including snow).
3 AlbedoMax MU Effective surface albedo (middle of the day value) for summertime.
4 Emissivity MU Effective surface emissivity.
5 StorageMin MD Minimum water storage capacity for upper surfaces (i.e. canopy).
6 StorageMax MD Maximum water storage capacity for upper surfaces (i.e. canopy)
7 WetThreshold MD Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface [mm].
8 StateLimit MD Upper limit to the surface state. [mm]
9 DrainageEq MD Calculation choice for Drainage equation
10 DrainageCoef1 MD Coefficient D0 [mm h-1] used in DrainageEq
11 DrainageCoef2 MD Coefficient b [-] used in DrainageEq
12 SoilTypeCode L Code for soil characteristics below this surface linking to Code of SUEWS_Soil.txt
13 SnowLimPatch O Limit for the snow water equivalent when snow cover starts to be patchy [mm]
14 SnowLimRemove O Limit of the snow water equivalent for snow removal from roads and roofs [mm]
15 OHMCode_SummerWet L Code for OHM coefficients to use for this surface during wet conditions in summer, linking to SUEWS_OHMCoefficients.txt.
16 OHMCode_SummerDry L Code for OHM coefficients to use for this surface during dry conditions in summer, linking to SUEWS_OHMCoefficients.txt.
17 OHMCode_WinterWet L Code for OHM coefficients to use for this surface during wet conditions in winter, linking to SUEWS_OHMCoefficients.txt.
18 OHMCode_WinterDry L Code for OHM coefficients to use for this surface during dry conditions in winter, linking to SUEWS_OHMCoefficients.txt.
19 OHMThresh_SW MD Temperature threshold determining whether summer/winter OHM coefficients are applied [°C]
20 OHMThresh_WD MD Soil moisture threshold determining whether wet/dry OHM coefficients are applied [-]
21 ESTMCode L Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt
22 AnOHM_Cp MU Volumetric heat capacity for this surface to use in AnOHM [J m-3]
23 AnOHM_Kk MU Thermal conductivity for this surface to use in AnOHM [W m K-1]
24 AnOHM_Ch MU Bulk transfer coefficient for this surface to use in AnOHM [-]

An example SUEWS_NonVeg.txt can be found below:

1    	 2         	 3         	 4          	 5          	 6          	 7            	 8          	 9          	 10            	 11            	 12           	 13           	 14            	 15                	 16                	 17                	 18                	 19           	 20           	 21       	 22       	 23       	 24
Code 	 AlbedoMin 	 AlbedoMax 	 Emissivity 	 StorageMin 	 StorageMax 	 WetThreshold 	 StateLimit 	 DrainageEq 	 DrainageCoef1 	 DrainageCoef2 	 SoilTypeCode 	 SnowLimPatch 	 SnowLimRemove 	 OHMCode_SummerWet 	 OHMCode_SummerDry 	 OHMCode_WinterWet 	 OHMCode_WinterDry 	 OHMThresh_SW 	 OHMThresh_WD 	 ESTMCode 	 AnOHM_Cp 	 AnOHM_Kk 	 AnOHM_Ch
100  	 0.09      	 0.09      	 0.95       	 0.48       	 0.48       	 0.48         	 0.48       	 3          	 10            	 3             	 50           	 190          	 40            	 800               	 800               	 800               	 800               	 10           	 0.9          	 0        	 2000000  	 1.2      	 4        	 ! 	 PAV   	 Helsinki
150  	 0.15      	 0.15      	 0.91       	 0.25       	 0.25       	 0.25         	 0.25       	 3          	 10            	 3             	 60           	 190          	 100           	 750               	 750               	 750               	 750               	 10           	 0.9          	 0        	 2000000  	 1.2      	 4        	 ! 	 BLDG  	 Helsinki
551  	 0.1       	 0.1       	 0.95       	 0.48       	 0.48       	 0.6          	 0.48       	 3          	 10            	 3             	 551          	 -999         	 -999          	 800               	 800               	 800               	 800               	 10           	 0.9          	 0        	 2000000  	 1.2      	 4        	 ! 	 Paved 	 Swindon  	 Ward    	 et          	 al.    	 (2013)
552  	 0.12      	 0.12      	 0.91       	 0.25       	 0.25       	 0.6          	 0.25       	 3          	 10            	 3             	 552          	 -999         	 -999          	 799               	 799               	 799               	 799               	 10           	 0.9          	 0        	 2000000  	 1.2      	 4        	 ! 	 Bldgs 	 Swindon  	 Ward    	 et          	 al.    	 (2013)
553  	 0.18      	 0.18      	 0.94       	 0.8        	 0.8        	 1            	 0.8        	 3          	 10            	 3             	 553          	 -999         	 -999          	 55                	 55                	 55                	 55                	 10           	 0.9          	 809      	 2000000  	 1.2      	 4        	 ! 	 BSoil 	 Swindon  	 Ward    	 et          	 al.    	 (2013)
661  	 0.12      	 0.12      	 0.95       	 0.48       	 0.48       	 0.48         	 0.48       	 3          	 10            	 3             	 661          	 120          	 10            	 800               	 800               	 800               	 800               	 10           	 0.9          	 0        	 1.5e6    	 0.1      	 2        	 ! 	 Paved 	 London
662  	 0.15      	 0.15      	 0.91       	 0.25       	 0.25       	 0.25         	 0.25       	 3          	 10            	 3             	 661          	 120          	 8.5           	 799               	 799               	 799               	 799               	 10           	 0.9          	 0        	 6000000  	 1.3      	 6        	 ! 	 Bldgs 	 London
663  	 0.21      	 0.21      	 0.93       	 1          	 1          	 1            	 1          	 2          	 0.013         	 1.71          	 661          	 -999         	 -999          	 55                	 55                	 55                	 55                	 10           	 0.9          	 809      	 4000000  	 1.5      	 5        	 ! 	 Bsoil 	 (not     	 used)   	 London
703  	 0.18      	 0.18      	 0.94       	 0.8        	 0.8        	 1            	 0.8        	 3          	 10            	 3             	 553          	 -999         	 -999          	 55                	 55                	 55                	 55                	 10           	 0.9          	 809      	 3500000  	 1.1      	 3        	 ! 	 BSoil 	 UF       	 Fredrik 	 LondonSmall 	 London 	 not    	 used 	 6
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_OHMCoefficients.txt

OHM, the Objective Hysteresis Model (Grimmond et al. 1991) [G91OHM] calculates the storage heat flux as a function of net all-wave radiation and surface characteristics.

  • For each surface, OHM requires three model coefficients (a1, a2, a3). The three should be selected as a set.
  • The SUEWS_OHMCoefficients.txt file provides these coefficients for each surface type.
  • A variety of values has been derived for different materials and can be found in the literature (see: Typical Values).
  • Coefficients can be changed depending on:
    1. surface wetness state (wet/dry) based on the calculated surface wetness state and soil moisture.
    2. season (summer/winter) based on a 5-day running mean air temperature.
  • To use the same coefficients irrespective of wet/dry and summer/winter conditions, use the same code for all four OHM columns (OHMCode_SummerWet, OHMCode_SummerDry, OHMCode_WinterWet and OHMCode_WinterDry).

Note

  1. AnOHM (set in RunControl.nml by StorageHeatMethod = 3) does not use the coefficients specified in SUEWS_OHMCoefficients.txt but instead requires three parameters to be specified for each surface type (including snow): heat capacity (AnOHM_Cp), thermal conductivity (AnOHM_Kk) and bulk transfer coefficient (AnOHM_Ch). These are specified in SUEWS_NonVeg.txt, SUEWS_Veg.txt, SUEWS_Water.txt and SUEWS_Snow.txt. No additional files are required for AnOHM.
  2. AnOHM is under development in v2018b and should NOT be used!
No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 a1 MU Coefficient for Q* term [-]
3 a2 MU Coefficient for dQ*/dt term [h]
4 a3 MU Constant term [W m-2]

An example SUEWS_OHMCoefficients.txt can be found below:

1    	 2      	 3       	 4
Code 	 a1     	 a2      	 a3          	 !   	 Surface       type          	 Reference    	 Not           recommended   (NR)
10   	 0.71   	 0.04    	 -39.7       	 !   	 "Canyon       (E-W),          Japan"       	 Yosheida      (1990/91)
11   	 0.32   	 0.01    	 -27.7       	 !   	 "Canyon,      Vancouver"    	 Nunez          (1974)
100  	 0.515  	 0.025   	 -33.7       	 !   	 Canyon        (average)
200  	 0.336  	 0.313   	 -31.4       	 !   	 "Vegetation   (average).      This           is            the           average       of            Codes       20,          30,           50,           51,             52,          53,            60              (i.e.    includes      soil     and    water)."
201  	 0.215  	 0.325   	 -19.85      	 !   	 NEW           Vegetation      only           (average      of            codes         20            and         30).
2011 	 0.230  	 0.276   	 -16.91      	 !   	 Code          201             x              Mulitplier    for           summer
2012 	 0.270  	 -0.435  	 6.62        	 !   	 Code          201             x              Multiplier    for           winter
20   	 0.11   	 0.11    	 -12.3       	 !   	 Mixed         Forest        	 McCaughey      (1985)
30   	 0.32   	 0.54    	 -27.4       	 !   	 Short         grass         	 Doll           et            al.           (1985)
50   	 0.38   	 0.56    	 -27.3       	 !   	 Bare          soil          	 Novak          (1982)
51   	 0.33   	 0.07    	 -34.9       	 !   	 Bare          soil            (wet)        	 Fuchs         &             Hadas         (1972)
52   	 0.35   	 0.43    	 -36.5       	 !   	 Bare          soil            (dry)        	 Fuchs         &             Hadas         (1972)
53   	 0.36   	 0.27    	 -42.4       	 !   	 Bare          soil          	 Asaeda         &             Ca            (1983)
55   	 0.355  	 0.335   	 -35.275     	 !   	 "Bare         soil            (average).     This          is            the           average       of          Codes        50,           51,           52,             53."
551  	 0.379  	 0.284   	 -30.05      	 !   	 Code          55              x              Mulitplier    for           summer
552  	 0.445  	 -0.448  	 11.77       	 !   	 Code          55              x              Mulitplier    for           winter
60   	 0.5    	 0.21    	 -39.1       	 !   	 Water         (shallow        -              turbid)     	 Souch         et            al.           (1998)
601  	 0.534  	 0.178   	 -33.31      	 !   	 Code          60              x              Multiplier    for           summer
602  	 0.627  	 -0.281  	 13.05       	 !   	 Code          60              x              Multiplier    for           winter
61   	 0.25   	 0.6     	 -30         	 !   	 Snow        	 Jarvi           et             al.           (2014)
713  	 0.17   	 0.1     	 -17         	 !   	 "Roof         (tar            and            gravel,       summer)"    	 summer
701  	 0.3    	 0.96    	 -24         	 !   	 "Roof         (commerical     or             industrial,   gravel,       dry,          WS            <           1            m/s,          Vancouver)" 	 "Meyn           &            Oke            (2009)          Table    4,            Pg       750"
702  	 0.26   	 0.89    	 -21         	 !   	 "Roof         (commerical     or             industrial,   gravel,       dry,          WS            1-1.4       m/s,         Vancouver)" 	 "Meyn         &               Oke          (2009)         Table           4,       Pg            750"
703  	 0.23   	 0.87    	 -24         	 !   	 "Roof         (commerical     or             industrial,   gravel,       dry,          WS            1.5-2       m/s,         Vancouver)" 	 "Meyn         &               Oke          (2009)         Table           4,       Pg            750"
704  	 0.23   	 0.69    	 -21         	 !   	 "Roof         (commerical     or             industrial,   gravel,       wet,          WS            0.9-1.9     m/s,         Vancouver)" 	 "Meyn         &               Oke          (2009)         Table           4,       Pg            750"
705  	 0.06   	 0.28    	 -3          	 !   	 "Roof         (commerical     or             industrial,   bitumen       spread        over          flat        industrial   membrane,     wet           &               dry,         WS             1.1-2           m/s,     Vancouver)" 	 "Meyn    &      Oke        (2009)   Table   4,   Pg   750"
706  	 0.15   	 0.28    	 -6          	 !   	 "Roof         (residential,   asphalt        shingle       on            plywood,      dry,          WS          <            1             m/s,          Vancouver)"   	 "Meyn        &              Oke             (2009)   Table         4,       Pg     750"
707  	 0.12   	 0.25    	 -5          	 !   	 "Roof         (residential,   asphalt        shingle       on            plywood,      dry,          WS          <            1.0-1.4       m/s,          Vancouver)"   	 "Meyn        &              Oke             (2009)   Table         4,       Pg     750"
708  	 0.1    	 0.23    	 -6          	 !   	 "Roof         (residential,   asphalt        shingle       on            plywood,      dry,          WS          <            2             m/s,          Vancouver)"   	 "Meyn        &              Oke             (2009)   Table         4,       Pg     750"
709  	 0.09   	 0.18    	 -1          	 !   	 "Roof         (STAR,          residential,   high          albedo        asphalt       shingle,      dry,        WS           1.0-1.4       m/s)"       	 "Meyn           &            Oke            (2009)          Table    4,            Pg       750"
710  	 0.07   	 0.26    	 -6          	 !   	 "Roof         (STAR,          Japanese       ceramic       tile)"      	 "Meyn         &             Oke         (2009)       Table         4,            Pg              750"
711  	 0.06   	 0.43    	 -4          	 !   	 "Roof         (STAR,          slate          tile,         dry,          WS            1.0-1.4       m/s)"     	 "Meyn        &             Oke           (2009)          Table        4,             Pg              750"
712  	 0.07   	 0.06    	 -5          	 !   	 "Roof         (STAR,          clay           tile,         dry,          WS            1.0-1.4       m/s)"     	 "Meyn        &             Oke           (2009)          Table        4,             Pg              750"
750  	 0.19   	 0.54    	 -15.125     	 !   	 "Roof         (own            for            SMEAR         III,          Helsinki)"  	 Jarvi         et          al.          (2014)
751  	 0.12   	 0.24    	 -4.5        	 !   	 Own           for             Montreal       suburban      (calculated   as            a             average     from         shingle       types)       	 Jarvi           et           al.            (2014)
752  	 0.26   	 0.85    	 -21.4       	 !   	 Own           for             Montreal       urban         (calculated   as            a             average     from         gravel)     	 Jarvi         et              al.          (2014)
790  	 0.44   	 0.57    	 -28.9       	 !   	 Roof          (Uppsala)     	 Taseler        (1980)      	 NR
791  	 0.82   	 0.34    	 -55.7       	 !   	 Roof          (membrane       &              concrete)   	 Yoshida       et            al.           (1990/91)  	 NR
798  	 0.477  	 0.337   	 -33.87      	 !   	 "Rooftop      average         (of            Taesler,      Yap           and           Yoshida,      as          in           Grimmond      et            al.             1992)"     	 Keogh          et              al.      (2012)
7981 	 0.510  	 0.286   	 -28.85      	 !   	 Code          798             x              Multiplier    for           summer
7982 	 0.598  	 -0.451  	 11.30       	 !   	 Code          798             x              Multiplier    for           winter
799  	 0.238  	 0.427   	 -16.7       	 !   	 Original      roof            average        (inlcudes     two           not           recommended   -           Meyn         2001          and           old             Meyn         2001           coefficients)
800  	 0.719  	 0.194   	 -36.6       	 !   	 "Impervious   (average).      This           is            the           average       of            Codes       801,         802,          901,          902,            903,         905,           906."
801  	 0.81   	 0.1     	 -79.9       	 !   	 Concrete    	 Doll            et             al.           (1985)
802  	 0.85   	 0.32    	 -28.5       	 !   	 Concrete    	 Asaeda          &              Ca            (1993)
901  	 0.36   	 0.23    	 -19.3       	 !   	 Asphalt     	 Narita          et             al.           (1984)
902  	 0.64   	 0.32    	 -43.6       	 !   	 Asphalt     	 Asaeda          &              Ca            (1993)
903  	 0.82   	 0.68    	 -20.1       	 !   	 Asphalt       -               check          these         values?     	 Anandakumar   (1998)
905  	 0.72   	 0.54    	 -40.2       	 !   	 Asphalt       (winter)        -              check         these         values?     	 Anandakumar   (1998)
906  	 0.83   	 -0.83   	 -24.6       	 !   	 Asphalt       (summer)        -              check         these         values?     	 Anandakumar   (1998)
904  	 0.805  	 -0.193  	 -9.39       	 !   	 An99          weighted        average        (all          year)         -             calculated    by          HCW
907  	 0.767  	 0.452   	 -34.76      	 !   	 An99          Apr-Sep         weighted       average       (summer)      -             calculated    by          HCW
908  	 0.843  	 -0.838  	 15.98       	 !   	 An99          Oct-Mar         weighted       average       (winter)      -              calculated    by          HCW
909  	 0.67   	 0.493   	 -47.97      	 !   	 An99          August          average        -             calculated    by            HCW
910  	 0.718  	 0.532   	 -40.81      	 !   	 An99          JJA             average        -             calculated    by            HCW
850  	 0.665  	 0.243   	 -42.825     	 !   	 "Impervious   (average)       excluding      all           An99          values,       i.e.          average     of           Codes         801,          802,            901,         902."
851  	 0.676  	 0.300   	 -42.42      	 !   	 "NEW          Impervious      (average).     This          is            the           average       of          Codes        801,          802,          901,            902,         910."        	 Ward            et       al.           (2015)
8511 	 0.722  	 0.255   	 -36.14      	 !   	 Code          851             x              Multiplier    for           summer
8512 	 0.848  	 -0.402  	 14.16       	 !   	 Code          851             x              Multiplier    for           winter
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_Profiles.txt

SUEWS_Profiles.txt specifies the daily cycle of variables related to human behaviour (energy use, water use and snow clearing). Different profiles can be specified for weekdays and weekends. The profiles are provided at hourly resolution here; the model will then interpolate the hourly energy and water use profiles to the resolution of the model time step and normalize the values provided. Thus it does not matter whether columns 2-25 add up to, say 1, 24, or another number, because the model will handle this. Currently, the snow clearing profiles are not interpolated as these are effectively a switch (0 or 1).

If the anthropogenic heat flux and water use are specified in the met forcing file, the energy and water use profiles are not used.

Profiles are specified for the following

  • Anthropogenic heat flux (weekday and weekend)
  • Water use (weekday and weekend; manual and automatic irrigation)
  • Snow removal (weekday and weekend)
  • Human activity (weekday and weekend).
No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 2-25 MU Multiplier for each hour of the day [-] for energy and water use. For SnowClearing, set those hours to 1 when snow removal from paved and roof surface is allowed (0 otherwise) if the snow removal limits set in the SUEWS_NonVeg.txt (SnowLimR emove column) are exceeded.

An example SUEWS_Profiles.txt can be found below:

1     2           3           4           5           6           7           8           9          10          11          12         13          14          15          16          17          18          19          20          21          22          23          24          25
Code  0           1           2           3           4           5           6           7          8           9           10         11          12          13          14          15          16          17          18          19          20          21          22          23
10    0.01        0.01        0.01        0.01        0.01        0.01        0.01        0.04       0.04        0.04        0.04       0.04        0.04        0.04        0.04        0.04        0.13        0.13        0.13        0.13        0.01        0.01        0.01        0.01        ! Vs        1987          Water     Use    Profile values
11    0.03        0.03        0.03        0.03        0.03        0.03        0.03        0.02       0.02        0.02        0.02       0.02        0.02        0.02        0.02        0.02        0.12        0.12        0.12        0.12        0.03        0.03        0.03        0.03        ! Manual    LA            Water     Use    Profile values
12    0.04        0.04        0.04        0.04        0.04        0.04        0.04        0.04       0.04        0.04        0.04       0.04        0.04        0.04        0.04        0.04        0.05        0.05        0.05        0.05        0.04        0.04        0.04        0.04        ! Automatic LA            Water     Use    Profile values

40    0.3         0.23        0.15        0.13        0.15        0.45        1.2         1.7        1.55        1.4         1.3        1.3         1.35        1.37        1.45        1.6         1.75        1.7         1.2         1.1         0.95        0.65        0.38        0.33        ! AHDIUPRF  Anthropogenic Heat      Flux   Profile values
41    1           1           1           1           1           1           1           1          1           1           1          1           1           1           1           1           1           1           1           1           1           1           1           1           ! AHDIUPRF  Anthropogenic Heat      Flux   Profile values
42    0.57        0.45        0.43        0.4         0.4         0.45        0.71        1.2        1.44        1.29        1.28       1.31        1.3         1.32        1.35        1.44        1.51        1.41        1.14        0.99        0.86        0.85        0.8         0.7         ! AHDIUPRF1 Anthropogenic Heat      Flux   Profile values   Vs87
43    0.65        0.49        0.46        0.47        0.47        0.53        0.7         1.13       1.37        1.37        1.3        1.37        1.33        1.3         1.27        1.36        1.44        1.3         1.1         0.98        0.84        0.9         0.87        0.74        ! AHDIUPRF2 Anthropogenic Heat      Flux   Profile values   Vs87

1     0           0           0           0           0           0           1           1          1           1           1          1           1           1           1           1           1           1           0           0           0           0           0           0           ! Helsinki  Snow          removal

99999 -999        -999        -999        -999        -999        -999        -999        -999       -999        -999        -999       -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        ! Swindon   "Snow         clearing, water  use     (not     used)"
90000 1           1           1           1           1           1           1           1          1           1           1          1           1           1           1           1           1           1           1           1           1           1           1           1           ! Arbitrary (constant     all       day)

550   -999        -999        -999        -999        -999        -999        -999        -999       -999        -999        -999       -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        ! Swindon   "Snow         clearing, water  use     (not     used)"
551   0.57        0.45        0.43        0.4         0.4         0.45        0.71        1.2        1.44        1.29        1.28       1.31        1.3         1.32        1.35        1.44        1.51        1.41        1.14        0.99        0.86        0.85        0.8         0.7         ! Swindon   Weekday       QF
552   0.65        0.49        0.46        0.47        0.47        0.53        0.7         1.13       1.37        1.37        1.3        1.37        1.33        1.3         1.27        1.36        1.44        1.3         1.1         0.98        0.84        0.9         0.87        0.74        ! Swindon   Weekend       QF
5512  0.421569876 0.332818323 0.318026398 0.295838509 0.295838509 0.332818323 0.525113354 0.45004736 0.374981366 0.335920807 0.33331677 0.341128882 0.338524845 0.343732919 0.351545031 0.374981366 0.393209627 0.618174689 0.843139752 0.732200311 0.636052795 0.628656832 0.591677019 0.517717391 ! Swindon   Weekday       QF        scaled for     variable pop


660   -999        -999        -999        -999        -999        -999        -999        -999       -999        -999        -999       -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        -999        ! London    "Snow         clearing, water  use     (not     used)"
661   0.57        0.45        0.43        0.4         0.4         0.45        0.71        1.2        1.44        1.29        1.28       1.31        1.3         1.32        1.35        1.44        1.51        1.41        1.14        0.99        0.86        0.85        0.8         0.7         ! London    Weekday       QF
662   0.65        0.49        0.46        0.47        0.47        0.53        0.7         1.13       1.37        1.37        1.3        1.37        1.33        1.3         1.27        1.36        1.44        1.3         1.1         0.98        0.84        0.9         0.87        0.74        ! London    Weekend       QF
55663 1           1           1           1           1           1           1           1.5        2           2           2          2           2           2           2           2           2           2           2           2           2           2           1.5         1           ! UK        Human         activity  1
55664 1           1           1           1           1           1           1           1          1.5         2           2          2           2           2           2           2           2           2           2           2           2           2           1.5         1           ! UK        Human         activity  1

701   0.19        0.14        0.12        0.13        0.20        0.59        1.21        1.67       1.57        1.32        1.27       1.31        1.37        1.44        1.74        2.01        1.90        1.53        1.20        1.00        0.83        0.59        0.40        0.30        ! Helsinki  Traffic       Weekday
702   0.55        0.54        0.51        0.46        0.36        0.31        0.38        0.49       0.73        1.04        1.30       1.51        1.69        1.79        1.79        1.76        1.71        1.61        1.43        1.23        1.00        0.75        0.58        0.50        ! Helsinki  Traffic       Weekend
801   1           1           1           1           1           1.5         2           2          2           2           2          2           2           2           2           2           2           2           2           2           2           1.5         1           1           ! Helsinki  Population    Weekday
802   1           1           1           1           1           1           1           1          1.5         2           2          2           2           2           2           2           2           2           2           2           2           2           1.5         1           ! Helsinki  Population    Weekend

-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_SiteSelect.txt

For each year and each grid, site specific surface cover information and other input parameters are provided to SUEWS by SUEWS_SiteSelect.txt. The model currently requires a new row for each year of the model run. All rows in this file will be read by the model and run.

No. Column Name Use Description
1 Grid MU a unique number to represent grid
2 Year MU Year [YYYY]
3 StartDLS MU Start of the day light savings [DOY]
4 EndDLS MU End of the day light savings [DOY]
5 lat MU Latitude [deg].
6 lng MU longitude [deg]
7 Timezone MU Time zone [h] for site relative to UTC (east is positive). This should be set according to the times given in the meteorological forcing file(s).
8 SurfaceArea MU Area of the grid [ha].
9 Alt MU Altitude of grids [m].
10 z MU Measurement height [m].
11 id MD Day of year [DOY]
12 ih MD Hour [H]
13 imin MD Minute [M]
14 Fr_Paved MU Surface cover fraction of Paved surfaces [-]
15 Fr_Bldgs MU Surface cover fraction of buildings [-]
16 Fr_EveTr MU Surface cover fraction of EveTr: evergreen trees and shrubs [-]
17 Fr_DecTr MU Surface cover fraction of deciduous trees and shrubs [-]
18 Fr_Grass MU Surface cover fraction of Grass [-]
19 Fr_Bsoil MU Surface cover fraction of bare soil or unmanaged land [-]
20 Fr_Water MU Surface cover fraction of open water [-]
21 IrrFr_EveTr MU Fraction of evergreen trees that are irrigated [-]
22 IrrFr_DecTr MU Fraction of deciduous trees that are irrigated [-]
23 IrrFr_Grass MU Fraction of Grass that is irrigated [-]
24 H_Bldgs MU Mean building height [m]
25 H_EveTr MU Mean height of evergreen trees [m]
26 H_DecTr MU Mean height of deciduous trees [m]
27 z0 O Roughness length for momentum [m]
28 zd O Zero-plane displacement [m]
29 FAI_Bldgs O Frontal area index for buildings [-]
30 FAI_EveTr O Frontal area index for evergreen trees [-]
31 FAI_DecTr O Frontal area index for deciduous trees [-]
32 PopDensDay O Daytime population density (i.e. workers, tourists) [people ha-1]
33 PopDensNight O Night-time population density (i.e. residents) [people ha-1]
34 TrafficRate_WD O Weekday traffic rate [veh km m-2 s-1] Can be used for CO2 flux calculation - not used in v2018a.
35 TrafficRate_WE O Weekend traffic rate [veh km m-2 s-1] Can be used for CO2 flux calculation - not used in v2018a.
36 QF0_BEU_WD O Building energy use [W m-2]
37 QF0_BEU_WE O Building energy use [W m-2]
38 Code_Paved L Code for Paved surface characteristics linking to Code of SUEWS_NonVeg.txt
39 Code_Bldgs L Code for Bldgs surface characteristics linking to Code of SUEWS_NonVeg.txt
40 Code_EveTr L Code for EveTr surface characteristics linking to Code of SUEWS_Veg.txt
41 Code_DecTr L Code for DecTr surface characteristics linking to Code of SUEWS_Veg.txt
42 Code_Grass L Code for Grass surface characteristics linking to Code of SUEWS_Veg.txt
43 Code_BSoil L Code for BSoil surface characteristics linking to Code of SUEWS_NonVeg.txt
44 Code_Water L Code for Water surface characteristics linking to Code of SUEWS_Water.txt
45 LUMPS_DrRate MD Drainage rate of bucket for LUMPS [mm h-1]
46 LUMPS_Cover MD Limit when surface totally covered with water for LUMPS [mm]
47 LUMPS_MaxRes MD Maximum water bucket reservoir [mm] Used for LUMPS surface wetness control.
48 NARP_Trans MD Atmospheric transmissivity for NARP [-]
49 CondCode L Code for surface conductance parameters linking to Code of SUEWS_Conductance.txt
50 SnowCode L Code for snow surface characteristics linking to Code of SUEWS_Snow.txt
51 SnowClearingProfWD L Code for snow clearing profile (weekdays) linking to Code of SUEWS_Profiles.txt.
52 SnowClearingProfWE L Code for snow clearing profile (weekends) linking to Code of SUEWS_Profiles.txt.
53 AnthropogenicCode L Code for modelling anthropogenic heat flux linking to Code of SUEWS_AnthropogenicEmission.txt, which contains the model coefficients for estimation of the anthropogenic heat flux (used if EmissionsMethod = 1, 2 in RunControl.nml).
54 IrrigationCode L Code for modelling irrigation linking to Code of SUEWS_Irrigation.txt
55 WaterUseProfManuWD L Code for water use profile (manual irrigation, weekdays) linking to Code of SUEWS_Profiles.txt.
56 WaterUseProfManuWE L Code for water use profile (manual irrigation, weekends) linking to Code of SUEWS_Profiles.txt.
57 WaterUseProfAutoWD L Code for water use profile (automatic irrigation, weekdays) linking to Code of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in Code of SUEWS_Profiles.txt.
58 WaterUseProfAutoWE L Code for water use profile (automatic irrigation, weekends) linking to Code of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in Code of SUEWS_Profiles.txt.
59 FlowChange MD Difference in input and output flows for water surface [mm h-1]
60 RunoffToWater MD MU Fraction of above-ground runoff flowing to water surface during flooding [-]
61 PipeCapacity MD MU Storage capacity of pipes [mm]
62 GridConnection1of8 MD MU Number of the 1st grid where water can flow to
63 Fraction1of8 MD MU Fraction of water that can flow to GridConnection1of8 [-]
64 GridConnection2of8 MD MU Number of the 2nd grid where water can flow to
65 Fraction2of8 MD MU Fraction of water that can flow to GridConnection2of8 [-]
66 GridConnection3of8 MD MU Number of the 3rd grid where water can flow to
67 Fraction3of8 MD MU Fraction of water that can flow to GridConnection3of8 [-]
68 GridConnection4of8 MD MU Number of the 4th grid where water can flow to
69 Fraction4of8 MD MU Fraction of water that can flow to GridConnection4of8 [-]
70 GridConnection5of8 MD MU Number of the 5th grid where water can flow to
71 Fraction5of8 MD MU Fraction of water that can flow to GridConnection5of8 [-]
72 GridConnection6of8 MD MU Number of the 6th grid where water can flow to
73 Fraction6of8 MD MU Fraction of water that can flow to GridConnection6of8 [-]
74 GridConnection7of8 MD MU Number of the 7th grid where water can flow to
75 Fraction7of8 MD MU Fraction of water that can flow to GridConnection7of8 [-]
76 GridConnection8of8 MD MU Number of the 8th grid where water can flow to
77 Fraction8of8 MD MU Fraction of water that can flow to GridConnection8of8 [-]
78 WithinGridPavedCode L Code that links to the fraction of water that flows from Paved surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.
79 WithinGridBldgsCode L Code that links to the fraction of water that flows from Bldgs surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt
80 WithinGridEveTrCode L Code that links to the fraction of water that flows from EveTr surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.
81 WithinGridDecTrCode L Code that links to the fraction of water that flows from DecTr surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.
82 WithinGridGrassCode L Code that links to the fraction of water that flows from Grass surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.
83 WithinGridBSoilCode L Code that links to the fraction of water that flows from BSoil surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.
84 WithinGridWaterCode L Code that links to the fraction of water that flows from Water surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.
85 AreaWall MU Area of wall within grid (needed for ESTM calculation).
86 Fr_ESTMClass_Paved1 MU Surface cover fraction of Paved surface class 1 used in ESTM calculations
87 Fr_ESTMClass_Paved2 MU Surface cover fraction of Paved surface class 2 used in ESTM calculations
88 Fr_ESTMClass_Paved3 MU Surface cover fraction of Paved surface class 3 used in ESTM calculations
89 Code_ESTMClass_Paved1 L Code linking to SUEWS_ESTMCoefficients.txt
90 Code_ESTMClass_Paved2 L Code linking to SUEWS_ESTMCoefficients.txt
91 Code_ESTMClass_Paved3 L Code linking to SUEWS_ESTMCoefficients.txt
92 Fr_ESTMClass_Bldgs1 MU Surface cover fraction of building class 1 used in ESTM calculations
93 Fr_ESTMClass_Bldgs2 MU Surface cover fraction of building class 2 used in ESTM calculations
94 Fr_ESTMClass_Bldgs3 MU Surface cover fraction of building class 3 used in ESTM calculations
95 Fr_ESTMClass_Bldgs4 MU Surface cover fraction of building class 4 used in ESTM calculations
96 Fr_ESTMClass_Bldgs5 MU Surface cover fraction of building class 5 used in ESTM calculations
97 Code_ESTMClass_Bldgs1 L Code linking to SUEWS_ESTMCoefficients.txt
98 Code_ESTMClass_Bldgs2 L Code linking to SUEWS_ESTMCoefficients.txt
99 Code_ESTMClass_Bldgs3 L Code linking to SUEWS_ESTMCoefficients.txt
100 Code_ESTMClass_Bldgs4 L Code linking to SUEWS_ESTMCoefficients.txt
101 Code_ESTMClass_Bldgs5 L Code linking to SUEWS_ESTMCoefficients.txt

Attention

  • Two rows of -9 should be placed at end of this file.

  • In this file the column order is important.

  • Surface cover fractions specified from Fr_Paved to Fr_Water should sum up to 1.

  • Surface cover fractions specified from Fr_ESTMClass_Paved1 to Fr_ESTMClass_Paved3 should sum up to 1.

  • Surface cover fractions specified from Fr_ESTMClass_Bldgs1 to Fr_ESTMClass_Bldgs5 should sum up to 1.

  • In this file the row order is important for simulations of multiple grids and multiple years. Ensure the rows in are arranged so that all grids for a particular year appear on consecutive lines (rather than grouping all years together for a particular grid). See below for a valid example:

    Grid  Year ...
    1     2001 ...
    2     2001 ...
    1     2002 ...
    2     2002 ...
    

Tip

! can be used to indicate comments in the file. Comments are not read by the programme so they can be used by the user to provide notes for their interpretation of the contents. This is strongly recommended.

Day Light Savings (DLS)

The dates for DLS normally vary for each year and country as they are often associated with a specific set of Sunday mornings at the beginning of summer and autumn. Note it is important to remember leap years. You can check http://www.timeanddate.com/time/dst/ for your city.

Tip

If DLS does not occur give a start and end day immediately after it. Make certain the dummy dates are correct for the hemisphere

  • For northern hemisphere, use: 180 181
  • For southern hemisphere, use:  365 1
Example when running multiple years (in this case 2008 and 2009 in Canada):
Year start of daylight savings end of daylight savings
2008 170 240
2009 172 242
Grid Connections (water flow between grids)

Caution

This section gives an example of water flow between grids, calculated based on the relative elevation of the grids and length of the connecting surface between adjacent grids. For the square grids in the figure, water flow is assumed to be zero between diagonally adjacent grids, as the length of connecting surface linking the grids is very small. Model grids need not be square or the same size.

The table gives example values for the grid connections part of SUEWS_SiteSelect.txt for the grids shown in the figure. For each row, only water flowing out of the current grid is entered (e.g. water flows from 234 to 236 and 237, with a larger proportion of water flowing to 237 because of the greater length of connecting surface between 234 and 237 than between 234 and 236. No water is assumed to flow between 234 and 233 or 235 because there is no elevation difference between these grids. Grids 234 and 238 are at the same elevation and only connect at a point, so no water flows between them. Water enters grid 234 from grids 230, 231 and 232 as these are more elevated.

Example grid connections showing water flow between grids. Arrows indicate the water flow in to and out of grid 234, but note that only only water flowing out of each grid is entered in `SUEWS_SiteSelect.txt`

Example grid connections showing water flow between grids.

Note

Arrows indicate the water flow in to and out of grid 234, but note that only only water flowing out of each grid is entered in SUEWS_SiteSelect.txt

Example values for the grid connections part of `SUEWS_SiteSelect.txt` for the grids.

Example values for the grid connections part of SUEWS_SiteSelect.txt for the grids.

An example SUEWS_SiteSelect.txt can be found below:

1    2    3        4      5       6       7        8           9       10      11     12     13     14       15       16       17       18       19       20       21          22          23          24      25      26      27     28     29        30        31        32         33           34             35             36         37         38         39         40         41         42         43         44         45           46          47           48         49       50       51                 52                 53                54             55                 56                 57                 58                 59         60            61           62                 63           64                 65           66                 67           68                 69           70                 71           72                 73           74                 75           76                 77           78                  79                  80                  81                  82                  83                       84                  85        86                  87                  88                  89                    90                    91                    92                  93                  94                  95                  96                  97                    98                    99                    100                   101
Grid Year StartDLS EndDLS lat     lng     Timezone SurfaceArea Alt     z       id     ih     imin   Fr_Paved Fr_Bldgs Fr_EveTr Fr_DecTr Fr_Grass Fr_Bsoil Fr_Water IrrFr_EveTr IrrFr_DecTr IrrFr_Grass H_Bldgs H_EveTr H_DecTr z0     zd     FAI_Bldgs FAI_EveTr FAI_DecTr PopDensDay PopDensNight TrafficRate_WD TrafficRate_WE QF0_BEU_WD QF0_BEU_WE Code_Paved Code_Bldgs Code_EveTr Code_DecTr Code_Grass Code_Bsoil Code_Water LUMPS_DrRate LUMPS_Cover LUMPS_MaxRes NARP_Trans CondCode SnowCode SnowClearingProfWD SnowClearingProfWE AnthropogenicCode IrrigationCode WaterUseProfManuWD WaterUseProfManuWE WaterUseProfAutoWD WaterUseProfAutoWE FlowChange RunoffToWater PipeCapacity GridConnection1of8 Fraction1of8 GridConnection2of8 Fraction2of8 GridConnection3of8 Fraction3of8 GridConnection4of8 Fraction4of8 GridConnection5of8 Fraction5of8 GridConnection6of8 Fraction6of8 GridConnection7of8 Fraction7of8 GridConnection8of8 Fraction8of8 WithinGridPavedCode WithinGridBldgsCode WithinGridEveTrCode WithinGridDecTrCode WithinGridGrassCode WithinGridUnmanBSoilCode WithinGridWaterCode AreaWall  Fr_ESTMClass_Paved1 Fr_ESTMClass_Paved2 Fr_ESTMClass_Paved3 Code_ESTMClass_Paved1 Code_ESTMClass_Paved2 Code_ESTMClass_Paved3 Fr_ESTMClass_Bldgs1 Fr_ESTMClass_Bldgs2 Fr_ESTMClass_Bldgs3 Fr_ESTMClass_Bldgs4 Fr_ESTMClass_Bldgs5 Code_ESTMClass_Bldgs1 Code_ESTMClass_Bldgs2 Code_ESTMClass_Bldgs3 Code_ESTMClass_Bldgs4 Code_ESTMClass_Bldgs5
1    2004 85       302    57.7700 11.8700 2.0000   1.0000      15.0000 10.0000 1.0000 0.0000 0.0000 1.0000   0.0000   0.0000   0.0000   0.0000   0.0000   0.0000   0.0000      0.0000      0.0000      0.0010  0.0000  0.0000  0.0100 0.2000 0.0000    0.0000    0.0000    0.0000     0.0000       0.0134         0.0095         0.7442     0.7955     661.0000   662.0000   661.0000   662.0000   663.0000   663.0000   661.0000   0.2500       1.0000      10.0000      1.0000     200.0000 660.0000 660.0000           660.0000           661.0000          660.0000       660.0000           660.0000           660.0000           660.0000           0.0000     0.1000        100.0000     0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       661.0000            662.0000            663.0000            664.0000            665.0000            666.0000                 667.0000            -999.0000 0.0000              1.0000              0.0000              99999.0000            807.0000              99999.0000            1.0000              0.0000              0.0000              0.0000              0.0000              801.0000              99999.0000            99999.0000            99999.0000            99999.0000
1    2005 85       302    57.7700 11.8700 2.0000   1.0000      15.0000 10.0000 1.0000 0.0000 0.0000 1.0000   0.0000   0.0000   0.0000   0.0000   0.0000   0.0000   0.0000      0.0000      0.0000      0.0010  0.0000  0.0000  0.0100 0.2000 0.0000    0.0000    0.0000    0.0000     0.0000       0.0134         0.0095         0.7442     0.7955     661.0000   662.0000   661.0000   662.0000   663.0000   663.0000   661.0000   0.2500       1.0000      10.0000      1.0000     200.0000 660.0000 660.0000           660.0000           661.0000          660.0000       660.0000           660.0000           660.0000           660.0000           0.0000     0.1000        100.0000     0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       0.0000             0.0000       661.0000            662.0000            663.0000            664.0000            665.0000            666.0000                 667.0000            -999.0000 0.0000              1.0000              0.0000              99999.0000            807.0000              99999.0000            1.0000              0.0000              0.0000              0.0000              0.0000              801.0000              99999.0000            99999.0000            99999.0000            99999.0000
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_Snow.txt

SUEWS_Snow.txt specifies the characteristics for snow surfaces when SnowUse=1 in RunControl.nml. If the snow part of the model is not run, fill this table with ‘-999’ except for the first (Code) column and set SnowUse=0 in RunControl.nml. For a detailed description of the variables, see Järvi et al. (2014) [Leena2014].

No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 RadMeltFactor MU Hourly radiation melt factor of snow [mm W-1 h-1]
3 TempMeltFactor MU Hourly temperature melt factor of snow [mm K-1 h-1]
4 AlbedoMin MU Effective surface albedo (middle of the day value) for wintertime (not including snow).
5 AlbedoMax MU Effective surface albedo (middle of the day value) for summertime.
6 Emissivity MU Effective surface emissivity.
7 tau_a MD Time constant for snow albedo aging in cold snow [-]
8 tau_f MD Time constant for snow albedo aging in melting snow [-]
9 PrecipLimAlb MD Limit for hourly precipitation when the ground is fully covered with snow [mm]
10 SnowDensMin MD Fresh snow density [kg m-3]
11 SnowDensMax MD Maximum snow density [kg m-3]
12 tau_r MD Time constant for snow density ageing [-]
13 CRWMin MD Minimum water holding capacity of snow [mm]
14 CRWMax MD Maximum water holding capacity of snow [mm]
15 PrecipLimSnow MD Temperature limit when precipitation falls as snow [°C]
16 OHMCode_SummerWet L Code for OHM coefficients to use for this surface during wet conditions in summer, linking to SUEWS_OHMCoefficients.txt.
17 OHMCode_SummerDry L Code for OHM coefficients to use for this surface during dry conditions in summer, linking to SUEWS_OHMCoefficients.txt.
18 OHMCode_WinterWet L Code for OHM coefficients to use for this surface during wet conditions in winter, linking to SUEWS_OHMCoefficients.txt.
19 OHMCode_WinterDry L Code for OHM coefficients to use for this surface during dry conditions in winter, linking to SUEWS_OHMCoefficients.txt.
20 OHMThresh_SW MD Temperature threshold determining whether summer/winter OHM coefficients are applied [°C]
21 OHMThresh_WD MD Soil moisture threshold determining whether wet/dry OHM coefficients are applied [-]
22 ESTMCode L Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt
23 AnOHM_Cp MU Volumetric heat capacity for this surface to use in AnOHM [J m-3]
24 AnOHM_Kk MU Thermal conductivity for this surface to use in AnOHM [W m K-1]
25 AnOHM_Ch MU Bulk transfer coefficient for this surface to use in AnOHM [-]

An example SUEWS_Snow.txt can be found below:

1     	 2             	 3              	 4         	 5         	 6          	 7     	 8     	 9            	 10          	 11          	 12    	 13     	 14     	 15            	 16                	 17                	 18                	 19                	 20           	 21           	 22       	 23       	 24       	 25
Code  	 RadMeltFactor 	 TempMeltFactor 	 AlbedoMin 	 AlbedoMax 	 Emissivity 	 tau_a 	 tau_f 	 PrecipLimAlb 	 SnowDensMin 	 SnowDensMax 	 tau_r 	 CRWMin 	 CRWMax 	 PrecipLimSnow 	 OHMCode_SummerWet 	 OHMCode_SummerDry 	 OHMCode_WinterWet 	 OHMCode_WinterDry 	 OHMThresh_SW 	 OHMThresh_WD 	 ESTMCode 	 AnOHM_Cp 	 AnOHM_Kk 	 AnOHM_Ch
99999 	 -999          	 -999           	 -999      	 -999      	 -999       	 -999  	 -999  	 -999         	 -999        	 -999        	 -999  	 -999   	 -999   	 -999          	 61                	 61                	 61                	 61                	 10           	 0.9          	 99999    	 100000   	 1.2      	 4        	 !
1     	 0.0016        	 0.12           	 0.18      	 0.85      	 0.99       	 0.018 	 0.11  	 2            	 100         	 400         	 0.043 	 0.05   	 0.2    	 2.2           	 61                	 61                	 61                	 61                	 10           	 0.9          	 61       	 100000   	 1.2      	 4        	 ! 	 Helsinki   (HCW   added   0.99   for      emissivity) 	 Jarvi   et   al.   (2014)
550   	 0.001         	 0.14           	 0.18      	 0.8       	 0.99       	 0.01  	 0.1   	 2            	 100         	 450         	 0.02  	 0.03   	 0.1    	 2.2           	 61                	 61                	 61                	 61                	 10           	 0.9          	 61       	 100000   	 1.2      	 4        	 ! 	 Swindon  	 Ward   et      al.    (2013)
660   	 0.001         	 0.14           	 0.18      	 0.8       	 0.99       	 0.01  	 0.1   	 2            	 100         	 450         	 0.02  	 0.03   	 0.1    	 2.2           	 61                	 61                	 61                	 61                	 10           	 0.9          	 61       	 100000   	 1.2      	 4        	 ! 	 London
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_Soil.txt

SUEWS_Soil.txt specifies the characteristics of the sub-surface soil below each of the non-water surface types (Paved, Bldgs, EveTr, DecTr, Grass, BSoil). The model does not have a soil store below the water surfaces. Note that these sub-surface soil stores are different to the bare soil/unmamnaged surface cover type. Each of the non-water surface types need to link to soil characteristics specified here. If the soil characteristics are assumed to be the same for all surface types, use a single code value to link the characteristics here with the SoilTypeCode columns in SUEWS_NonVeg.txt and SUEWS_Veg.txt.

Soil moisture can either be provided using observational data in the met forcing file (SMDMethod = 1 or 2 in RunControl.nml) and providing some metadata information here (OBS columns), or modelled by SUEWS (SMDMethod = 0 in RunControl.nml).

Caution

The option to use observational data is not operational in the current release!

No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 SoilDepth MD Depth of soil beneath the surface [mm]
3 SoilStoreCap MD Limit value for SoilDepth [mm]
4 SatHydraulicCond MD Hydraulic conductivity for saturated soil [mm s-1]
5 SoilDensity MD Soil density [kg m-3]
6 InfiltrationRate O Infiltration rate.
7 OBS_SMDepth O The depth of soil moisture measurements. [mm]
8 OBS_SMCap O The maximum observed soil moisture. [m3 m-3 or kg kg-1]
9 OBS_SoilNotRocks O Fraction of soil without rocks. [-]

An example SUEWS_Soil.txt can be found below:

1    	 2         	 3            	 4                	 5           	 6                	 7           	 8         	 9
Code 	 SoilDepth 	 SoilStoreCap 	 SatHydraulicCond 	 SoilDensity 	 InfiltrationRate 	 OBS_SMDepth 	 OBS_SMCap 	 OBS_SoilNotRocks
551  	 350       	 150          	 5.00E-04         	 -999        	 -999             	 -999        	 -999      	 -999             	 ! 	 Swindon   (below   Paved)  	 Ward   et   al.   (2013)
552  	 350       	 150          	 5.00E-04         	 -999        	 -999             	 -999        	 -999      	 -999             	 ! 	 Swindon   (below   Built)  	 Ward   et   al.   (2013)
553  	 350       	 150          	 5.00E-04         	 -999        	 -999             	 -999        	 -999      	 -999             	 ! 	 Swindon   (below   others) 	 Ward   et   al.   (2013)
661  	 350       	 150          	 5.00E-04         	 -999        	 -999             	 -999        	 -999      	 -999             	 ! 	 London
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_Veg.txt

SUEWS_Veg.txt specifies the characteristics for the vegetated surface cover types (EveTr, DecTr, Grass) by linking codes in column 1 of SUEWS_Veg.txt to the codes specified in SUEWS_SiteSelect.txt (Code_EveTr, Code_DecTr, Code_Grass). Each row should correspond to a particular surface type. For suggestions on how to complete this table, see: Typical Values.

No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 AlbedoMin MU Effective surface albedo (middle of the day value) for wintertime (not including snow).
3 AlbedoMax MU Effective surface albedo (middle of the day value) for summertime.
4 Emissivity MU Effective surface emissivity.
5 StorageMin MD Minimum water storage capacity for upper surfaces (i.e. canopy).
6 StorageMax MD Maximum water storage capacity for upper surfaces (i.e. canopy)
7 WetThreshold MD Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface [mm].
8 StateLimit MD Upper limit to the surface state. [mm]
9 DrainageEq MD Calculation choice for Drainage equation
10 DrainageCoef1 MD Coefficient D0 [mm h-1] used in DrainageEq
11 DrainageCoef2 MD Coefficient b [-] used in DrainageEq
12 SoilTypeCode L Code for soil characteristics below this surface linking to Code of SUEWS_Soil.txt
13 SnowLimPatch O Limit for the snow water equivalent when snow cover starts to be patchy [mm]
14 BaseT MU Base Temperature for initiating growing degree days (GDD) for leaf growth. [°C]
15 BaseTe MU Base temperature for initiating sensesance degree days (SDD) for leaf off. [°C]
16 GDDFull MU The growing degree days (GDD) needed for full capacity of the leaf area index (LAI) [°C].
17 SDDFull MU The sensesence degree days (SDD) needed to initiate leaf off. [°C]
18 LAIMin MD leaf-off wintertime value
19 LAIMax MD full leaf-on summertime value
20 PorosityMin MD leaf-off wintertime value Used only for DecTr (can affect roughness calculation)
21 PorosityMax MD full leaf-on summertime value Used only for DecTr (can affect roughness calculation)
22 MaxConductance MD The maximum conductance of each vegetation or surface type. [mm s-1]
23 LAIEq MD LAI calculation choice.
24 LeafGrowthPower1 MD a parameter required by LAI calculation in LAIEq
25 LeafGrowthPower2 MD a parameter required by LAI calculation [K-1] in LAIEq
26 LeafOffPower1 MD a parameter required by LAI calculation [K-1] in LAIEq
27 LeafOffPower2 MD a parameter required by LAI calculation [K-1] in LAIEq
28 OHMCode_SummerWet L Code for OHM coefficients to use for this surface during wet conditions in summer, linking to SUEWS_OHMCoefficients.txt.
29 OHMCode_SummerDry L Code for OHM coefficients to use for this surface during dry conditions in summer, linking to SUEWS_OHMCoefficients.txt.
30 OHMCode_WinterWet L Code for OHM coefficients to use for this surface during wet conditions in winter, linking to SUEWS_OHMCoefficients.txt.
31 OHMCode_WinterDry L Code for OHM coefficients to use for this surface during dry conditions in winter, linking to SUEWS_OHMCoefficients.txt.
32 OHMThresh_SW MD Temperature threshold determining whether summer/winter OHM coefficients are applied [°C]
33 OHMThresh_WD MD Soil moisture threshold determining whether wet/dry OHM coefficients are applied [-]
34 ESTMCode L Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt
35 AnOHM_Cp MU Volumetric heat capacity for this surface to use in AnOHM [J m-3]
36 AnOHM_Kk MU Thermal conductivity for this surface to use in AnOHM [W m K-1]
37 AnOHM_Ch MU Bulk transfer coefficient for this surface to use in AnOHM [-]
38 BiogenCO2Code MU Code linking to the Code column in SUEWS_BiogenCO2.txt.

An example SUEWS_Veg.txt can be found below:

1        2           3           4               5               6               7               8               9               10              11              12              13              14      15          16          17          18          19          20              21              22                  23      24                  25                  26              27              28                  29                  30                  31                  32              33              34          35          36          37       38
Code     AlbedoMin   AlbedoMax   Emissivity      StorageMin      StorageMax      WetThreshold    StateLimit      DrainageEq      DrainageCoef1   DrainageCoef2   SoilTypeCode    SnowLimPatch    BaseT   BaseTe      GDDFull     SDDFull     LAIMin      LAIMax      PorosityMin     PorosityMax     MaxConductance   LAIEq      LeafGrowthPower1    LeafGrowthPower2    LeafOffPower1   LeafOffPower2   OHMCode_SummerWet   OHMCode_SummerDry   OHMCode_WinterWet   OHMCode_WinterDry   OHMThresh_SW    OHMThresh_WD    ESTMCode    AnOHM_Cp    AnOHM_Kk    AnOHM_Ch BiogenCO2Code
300      0.1         0.1         0.98            1.3             1.3             1.3             1.3             2               0.013           1.71            70              190             5       10          300         -450        4           5.1         -999            -999            7.4                 1       0.04                0.001               -1.5            0.0015          200                 200                 200                 200                 10              0.9             200         1000000     1.2         4        21                 !   ET      Helsinki    Jarvi et al  (2014)
330      0.16        0.16        0.98            0.3             0.8             0.8             0.8             2               0.013           1.71            70              190             5       10          300         -450        1           5.5         0.2             0.6             11.7                1       0.04                0.001               -1.5            0.0015          200                 200                 200                 200                 10              0.9             200         1000000     1.2         4        21                 !   DT      Helsinki    Jarvi et al  (2014)
360      0.19        0.19        0.93            1.9             1.9             1.9             1.9             3               10              3               70              190             5       10          300         -450        1.6         5.9         -999            -999            40                  1       0.04                0.001               -1.5            0.0015          200                 200                 200                 200                 10              0.9             200         1000000     1.2         4        21                 !   IG      Helsinki    Jarvi et al  (2014)
361      0.19        0.19        0.93            1.9             1.9             1.9             1.9             2               0.13            1.71            70              190             5       10          300         -450        1.6         5.9         -999            -999            33.1                1       0.04                0.001               -1.5            0.0015          200                 200                 200                 200                 10              0.9             200         1000000     1.2         4        21                 !   UG      Helsinki    Jarvi et al  (2014)
551      0.1         0.1         0.98            1.3             1.3             1.8             1.3             2               0.013           1.71            553             -999            6       11          300         -450        4           5.1         -999            -999            7.4                 1       0.04                0.001               -1.5            0.0015          200                 200                 200                 200                 10              0.9             810         1000000     1.2         4        11                 !   EveTr   Swindon     Ward  et al. (2013)
552      0.12        0.18        0.98            0.3             0.8             1               0.8             2               0.013           1.71            553             -999            6       11          300         -450        1           5.5         0.2             0.6             11.7                1       0.04                0.001               -1.5            0.0015          200                 200                 200                 200                 10              0.9             811         1000000     1.2         4        11                 !   DecTr   Swindon     Ward  et al. (2013)
553      0.18        0.21        0.93            1.9             1.9             2               1.9             2               0.013           1.71            553             -999            6       11          300         -450        1.6         5.9         -999            -999            33.1                1       0.04                0.001               -1.5            0.0015          200                 200                 200                 200                 10              0.9             812         1000000     1.2         4        11                 !   Grass   Swindon     Ward  et al. (2013)
661      0.11        0.12        0.98            1.3             1.3             1.3             1.3             2               0.013           1.71            661             120             5       11          300         -450        4           5.1         -999            -999            7.4                 0       0.03                0.0005              0.03            0.0005          200                 200                 200                 200                 10              0.9             810         1000000     1.2         4        11                 !   EveTr   London
662      0.12        0.18        0.98            0.3             0.8             0.8             0.8             2               0.013           1.71            661             120             5       11          300         -450        1           5.5         0.2             0.6             11.7                0       0.03                0.0005              0.03            0.0005          200                 200                 200                 200                 10              0.9             811         1000000     1.2         4        11                 !   DecTr   London
663      0.18        0.21        0.93            1.9             1.9             1.9             1.9             2               0.013           1.71            661             120             5       11          300         -450        1.6         5.9         -999            -999            33.1                0       0.03                0.0005              0.03            0.0005          200                 200                 200                 200                 10              0.9             812         1000000     1.2         4        11                 !   Grass   London
700      0.11        0.12        0.98            1.3             1.3             1.3             1.3             2               0.013           1.71            661             120             5       11          300         -450        4           5.1         -999            -999            7.4                 0       0.03                0.0005              0.03            0.0005          201                 201                 201                 201                 10              0.9             810         1000000     1.2         4        11                 !   EveTr   London
701      0.12        0.18        0.98            0.3             0.8             0.8             0.8             2               0.013           1.71            661             120             5       11          300         -450        1           5.5         0.2             0.6             11.7                0       0.03                0.0005              0.03            0.0005          201                 201                 201                 201                 10              0.9             811         1000000     1.2         4        11                 !   DecTr   London
702      0.18        0.21        0.93            1.9             1.9             1.9             1.9             2               0.013           1.71            661             120             5       11          300         -450        1.6         5.9         -999            -999            33.1                0       0.03                0.0005              0.03            0.0005          201                 201                 201                 201                 10              0.9             812         500000      0.2         1        11                 !   Grass   London
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_Water.txt

SUEWS_Water.txt specifies the characteristics for the water surface cover type by linking codes in column 1 of SUEWS_Water.txt to the codes specified in SUEWS_SiteSelect.txt (Code_Water).

No. Column Name Use Description
1 Code L Code linking to a corresponding look-up table.
2 AlbedoMin MU Effective surface albedo (middle of the day value) for wintertime (not including snow).
3 AlbedoMax MU Effective surface albedo (middle of the day value) for summertime.
4 Emissivity MU Effective surface emissivity.
5 StorageMin MD Minimum water storage capacity for upper surfaces (i.e. canopy).
6 StorageMax MD Maximum water storage capacity for upper surfaces (i.e. canopy)
7 WetThreshold MD Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface [mm].
8 StateLimit MU Upper limit to the surface state. [mm]
9 WaterDepth MU Water depth [mm].
10 DrainageEq MD Calculation choice for Drainage equation
11 DrainageCoef1 MD Coefficient D0 [mm h-1] used in DrainageEq
12 DrainageCoef2 MD Coefficient b [-] used in DrainageEq
13 OHMCode_SummerWet L Code for OHM coefficients to use for this surface during wet conditions in summer, linking to SUEWS_OHMCoefficients.txt.
14 OHMCode_SummerDry L Code for OHM coefficients to use for this surface during dry conditions in summer, linking to SUEWS_OHMCoefficients.txt.
15 OHMCode_WinterWet L Code for OHM coefficients to use for this surface during wet conditions in winter, linking to SUEWS_OHMCoefficients.txt.
16 OHMCode_WinterDry L Code for OHM coefficients to use for this surface during dry conditions in winter, linking to SUEWS_OHMCoefficients.txt.
17 OHMThresh_SW MD Temperature threshold determining whether summer/winter OHM coefficients are applied [°C]
18 OHMThresh_WD MD Soil moisture threshold determining whether wet/dry OHM coefficients are applied [-]
19 ESTMCode L Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt
20 AnOHM_Cp MU Volumetric heat capacity for this surface to use in AnOHM [J m-3]
21 AnOHM_Kk MU Thermal conductivity for this surface to use in AnOHM [W m K-1]
22 AnOHM_Ch MU Bulk transfer coefficient for this surface to use in AnOHM [-]

An example SUEWS_Water.txt can be found below:

1    	 2         	 3         	 4          	 5          	 6          	 7            	 8          	 9          	 10         	 11            	 12            	 13                	 14                	 15                	 16                	 17           	 18           	 19       	 20       	 21       	 22
Code 	 AlbedoMin 	 AlbedoMax 	 Emissivity 	 StorageMin 	 StorageMax 	 WetThreshold 	 StateLimit 	 WaterDepth 	 DrainageEq 	 DrainageCoef1 	 DrainageCoef2 	 OHMCode_SummerWet 	 OHMCode_SummerDry 	 OHMCode_WinterWet 	 OHMCode_WinterDry 	 OHMThresh_SW 	 OHMThresh_WD 	 ESTMCode 	 AnOHM_Cp 	 AnOHM_Kk 	 AnOHM_Ch
1000 	 0.08      	 0.08      	 0.95       	 0.5        	 0.5        	 0.5          	 2000       	 2000       	 0          	 0             	 0             	 60                	 60                	 60                	 60                	 10           	 0.9          	 60       	 4100000   	 1.2      	 4        	 ! 	 Helsinki 	 Jarvi   et       al.    (2014)
551  	 0.1       	 0.1       	 0.95       	 0.5        	 0.5        	 0.5          	 1000       	 1000       	 -999       	 -999          	 -999          	 60                	 60                	 60                	 60                	 10           	 0.9          	 60       	 4100000   	 1.2      	 4        	 ! 	 Swindon    (no     water) 	 Ward   et       al.   (2013)
661  	 0.1       	 0.1       	 0.95       	 0.5        	 0.5        	 0.5          	 30000      	 20000      	 0          	 0             	 0             	 60                	 60                	 60                	 60                	 10           	 0.9          	 813      	 4100000   	 1.2      	 4        	 ! 	 London
-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_WithinGridWaterDist.txt

SUEWS_WithinGridWaterDist.txt specifies the movement of water between surfaces within a grid/area. It allows impervious connectivity to be taken into account.

Each row corresponds to a surface type (linked by the Code in column 1 to the SUEWS_SiteSelect.txt columns: WithinGridPavedCode, WithinGridBldgsCode, …, WithinGridWaterCode). Each column contains the fraction of water flowing from the surface type to each of the other surface types or to runoff or the sub-surface soil store.

Note

  • The sum of each row (excluding the Code) must equal 1.
  • Water CANNOT flow from one surface to that same surface, so the diagonal elements should be zero.
  • The row corresponding to the water surface should be zero, as there is currently no flow permitted from the water surface to other surfaces by the model.
  • Currently water CANNOT go to both runoff and soil store (i.e. it must go to one or the other – runoff for impervious surfaces; soilstore for pervious surfaces).

In the table below, for example,

  • All flow from paved surfaces goes to runoff;
  • 90% of flow from buildings goes to runoff, with small amounts going to other surfaces (mostly paved surfaces as buildings are often surrounded by paved areas);
  • All flow from vegetated and bare soil areas goes into the sub-surface soil store;
  • The row corresponding to water contains zeros (as it is currently not used).
No. Column Name Use Description
1 ToPaved MU Fraction of water going to Paved
2 ToBldgs MU Fraction of water going to Bldgs
3 ToEveTr MU Fraction of water going to EveTr
4 ToDecTr MU Fraction of water going to DecTr
5 ToGrass MU Fraction of water going to Grass
6 ToBSoil MU Fraction of water going to BSoil
7 ToWater MU Fraction of water going to Water
8 ToRunoff MU Fraction of water going to Runoff
9 ToSoilStore MU Fraction of water going to SoilStore

An example SUEWS_WithinGridWaterDist.txt can be found below:

1    	 2       	 3       	 4       	 5       	 6       	 7       	 8       	 9        	 10
Code 	 ToPaved 	 ToBldgs 	 ToEveTr 	 ToDecTr 	 ToGrass 	 ToBSoil 	 ToWater 	 ToRunoff 	 ToSoilStore !
10   	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 1        	 0           ! Paved     	 Example
20   	 0.06    	 0       	 0.01    	 0.01    	 0.01    	 0.01    	 0       	 0.9      	 0           ! Buildings 	 Example
30   	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 1           ! Evergreen 	 Example
40   	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 1           ! Decid     	 Example
50   	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 1           ! Grass     	 Example
60   	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 1           ! UnmanBare 	 Example
70   	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 0           ! Water     	 Example
21   	 0.03    	 0       	 0.01    	 0.01    	 0.01    	 0.01    	 0       	 0.93     	 0           ! Buildings 	 Example

551  	 0       	 0       	 0       	 0       	 0.02    	 0       	 0       	 0.98     	 0           ! Paved     	 Swindon
552  	 0.08    	 0       	 0       	 0       	 0.02    	 0       	 0       	 0.9      	 0           ! Bldgs     	 Swindon
553  	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 1           ! EveTr     	 Swindon
554  	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 1           ! DecTr     	 Swindon
555  	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 1           ! Grass     	 Swindon
556  	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 1           ! Bsoil     	 Swindon
557  	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 0           ! Water     	 Swindon 	 (not   present)

661  	 0       	 0       	 0       	 0       	 0.02    	 0       	 0       	 0.98     	 0           ! Paved     	 London
662  	 0.1     	 0       	 0       	 0       	 0       	 0       	 0       	 0.9      	 0           ! Bldgs     	 London
663  	 0.1     	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 0.9         ! EveTr     	 London  	 (not   present)
664  	 0.1     	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 0.9         ! DecTr     	 London
665  	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 1           ! Grass     	 London
666  	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 1           ! Bsoil     	 London  	 (not   present)
667  	 0       	 0       	 0       	 0       	 0       	 0       	 0       	 0        	 0           ! Water     	 London
-9
-9

Note

Please report issues with the manual on the GitHub page.

Input Options

a1
Description:

Coefficient for Q* term [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_OHMCoefficients.txt MU Coefficient for Q* term [-]
a2
Description:

Coefficient for dQ*/dt term [h]

Configuration:
Referencing Table Requirement Comment
SUEWS_OHMCoefficients.txt MU Coefficient for dQ*/dt term [h]
a3
Description:

Constant term [W m-2]

Configuration:
Referencing Table Requirement Comment
SUEWS_OHMCoefficients.txt MU Constant term [W m-2]
ActivityProfWD
Description:

Code linking to ActivityProfWD in SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt L

Code for human activity profile (weekdays) Provides the link to column 1 of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt. Used for CO2 flux calculation.

Not used in this version.

ActivityProfWE
Description:

Code linking to ActivityProfWE in SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt L

Code for human activity profile (weekends) Provides the link to column 1 of SUEWS_Profiles.txt. Look the codes Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt. Used for CO2 flux calculation.

Not used in this version.

AHMin_WD
Description:

Minimum QF on weekdays [W m-2]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O Use with EmissionsMethod = 1
AHMin_WE
Description:

Minimum QF on weekends [W m-2]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O Use with EmissionsMethod = 1
AHSlope_Heating_WD
Description:

Heating slope of QF on weekdays [W m-2 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O Use with EmissionsMethod = 1
AHSlope_Heating_WE
Description:

Heating slope of QF on weekends [W m-2 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O Use with EmissionsMethod = 1
AHSlope_Cooling_WD
Description:

Cooling slope of QF on weekdays [W m-2 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O Use with EmissionsMethod = 1
AHSlope_Cooling_WE
Description:

Cooling slope of QF on weekends [W m-2 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O Use with EmissionsMethod = 1
AlbedoMax
Description:

Effective surface albedo (middle of the day value) for summertime.

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MU Effective surface albedo (middle of the day value) for summertime. View factors should be taken into account.
SUEWS_Veg.txt MU

Example values [-]

SUEWS_Water.txt MU

Example values [-]

SUEWS_Snow.txt MU

Example values [-]

AlbedoMin
Description:

Effective surface albedo (middle of the day value) for wintertime (not including snow).

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MU Not currently used for non-vegetated surfaces – set the same as AlbedoMax.
SUEWS_Veg.txt MU

Example values [-]

SUEWS_Water.txt MU Not currently used for water surface - set same as AlbedoMax.
SUEWS_Snow.txt MU

Example values [-]

alpha
Description:

The mean apparent ecosystem quantum. Represents the initial slope of the light-response curve. [umol CO2 umol photons^-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_BiogenCO2.txt MU O Example values: EmissionsMethod = 11, 12, 13, 14, 15 or 16: 0.044 Ruimy et al (1995) [R95], 0.0593 Schmid et al. (2000) [S2000], 0.0205 Flanagan et al. (2002) [FWC2002]. EmissionsMethod = 21, 22, 23, 24, 25, or 26: 0.031 Bellucco et al. (2017) [B2017] EmissionsMethod = 31, 32, 33, 34, 35, 36: 0.005 Bellucco et al. (2017) [B2017]
Alt
Description:

Altitude of grids [m].

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Used for both the radiation and water flow between grids. Not available in this version.
AnOHM_Ch
Description:

Bulk transfer coefficient for this surface to use in AnOHM [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MU Bulk transfer coefficient for this surface to use in AnOHM [-]
SUEWS_Veg.txt MU Bulk transfer coefficient for this surface to use in AnOHM [-]
SUEWS_Water.txt MU Bulk transfer coefficient for this surface to use in AnOHM [-]
SUEWS_Snow.txt MU Bulk transfer coefficient for this surface to use in AnOHM [-]
AnOHM_Cp
Description:

Volumetric heat capacity for this surface to use in AnOHM [J m-3]

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MU Volumetric heat capacity for this surface to use in AnOHM [J m-3]
SUEWS_Veg.txt MU Volumetric heat capacity for this surface to use in AnOHM [J m-3]
SUEWS_Water.txt MU Volumetric heat capacity for this surface to use in AnOHM [J m-3]
SUEWS_Snow.txt MU Volumetric heat capacity for this surface to use in AnOHM [J m-3]
AnOHM_Kk
Description:

Thermal conductivity for this surface to use in AnOHM [W m K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MU Thermal conductivity for this surface to use in AnOHM [W m K-1]
SUEWS_Veg.txt MU Thermal conductivity for this surface to use in AnOHM [W m K-1]
SUEWS_Water.txt MU Thermal conductivity for this surface to use in AnOHM [W m K-1]
SUEWS_Snow.txt MU Thermal conductivity for this surface to use in AnOHM [W m K-1]
AnthropogenicCode
Description:

Code for modelling anthropogenic heat flux linking to Code of SUEWS_AnthropogenicEmission.txt, which contains the model coefficients for estimation of the anthropogenic heat flux (used if EmissionsMethod = 1, 2 in RunControl.nml).

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Value of integer is arbitrary but must match code specified in column 1 of SUEWS_AnthropogenicEmission.txt.
AreaWall
Description:

Area of wall within grid (needed for ESTM calculation).

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Area of wall within grid (needed for ESTM calculation).
BaseT
Description:

Base Temperature for initiating growing degree days (GDD) for leaf growth. [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MU See section 2.2 Järvi et al. (2011); Appendix A Järvi et al. (2014). Example values: 5 for EveTr Järvi et al. (2011) [J11]
BaseTe
Description:

Base temperature for initiating sensesance degree days (SDD) for leaf off. [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MU See section 2.2 Järvi et al. (2011) [J11] ; Appendix A Järvi et al. (2014) [Leena2014] . Example values: 10 EveTr Järvi et al. (2011) [J11]
BaseTHDD
Description:

Base temperature for heating degree days [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU Base temperature for heating degree days [°C] e.g. Sailor and Vasireddy (2006) [SV06]
beta
Description:

The light-saturated gross photosynthesis of the canopy. [umol m-2 s-1 ]

Configuration:
Referencing Table Requirement Comment
SUEWS_BiogenCO2.txt MU O

Example values:

EmissionsMethod = 11, 12, 13, 14, 15, 16: 43.35 Ruimy et al. (1995) [R95], 35 Schmid et al. (2000) [S2000], 16.3 Flanagan et al. (2002) [FWC2002] EmissionsMethod = 21, 22, 23, 24, 25, 26: 17.793 Bellucco et al. (2017) [B2017] EmissionsMethod = 31, 32, 33, 34, 35, 36: 8.474 Bellucco et al. (2017) [B2017]

theta
Description:

The convexity of the curve at light saturation.

Configuration:
Referencing Table Requirement Comment
SUEWS_BiogenCO2.txt MU O Example value: EmissionsMethod = 21, 22, 23, 24, 25, 26: 0.723 Bellucco et al. (2017) [B2017] EmissionsMethod = 31, 32, 33, 34, 35, 36: 0.96 Bellucco et al. (2017) [B2017]
alpha_enh
Description:

Part of the alpha coefficient related to the fraction of vegetation.

Configuration:
Referencing Table Requirement Comment
SUEWS_BiogenCO2.txt MU O Example value: 0.016 Bellucco et al. (2017) [B2017]
beta_enh
Description:

Part of the beta coefficient related to the fraction of vegetation.

Configuration:
Referencing Table Requirement Comment
SUEWS_BiogenCO2.txt MU O Example values: 33.454 Bellucco et al. (2017) [B2017]
resp_a
Description:

Respiration coefficient a.

Configuration:
Referencing Table Requirement Comment
SUEWS_BiogenCO2.txt MU O Example values: 1.08 Schmid et al. (2000) [S2000], 3.229 Järvi et al. (2012) [J12]
resp_b
Description:

Respiration coefficient b - related to air temperature dependency.

Configuration:
Referencing Table Requirement Comment
SUEWS_BiogenCO2.txt MU O Example values: 0.0064 Schmid et al. (2000) [S2000], 0.0329 Järvi et al. (2012) [J12].
min_respi
Description:

Minimum soil respiration rate (for cold-temperature limit) [umol m-2 s-1].

Configuration:
Referencing Table Requirement Comment
SUEWS_BiogenCO2.txt MU O Example values: 0.6 estimate from Hyytiälä forest site.
BiogenCO2Code
Description:

Code linking to the Code column in SUEWS_BiogenCO2.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt L Code linking to the Code column in SUEWS_BiogenCO2.txt.
QF0_BEU_WD
Description:

Building energy use [W m-2]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Weekday building energy use [W m-2] Can be used for CO2 flux calculation.
QF0_BEU_WE
Description:

Building energy use [W m-2]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Can be used for CO2 flux calculation. set to -999 Not used in this version.
CO2PointSource
Description:

CO2 emission factor [kg km-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O CO2 emission factor [kg km-1]
Code
Description:

Code linking to a corresponding look-up table.

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt L Code linking to SUEWS_SiteSelect.txt for paved surfaces (Code_Paved), buildings (Code_Bldgs) and bare soil surfaces (Code_BSoil). Value of integer is arbitrary but must match codes specified in SUEWS_SiteSelect.txt.
SUEWS_Veg.txt L Code linking to SUEWS_SiteSelect.txt for evergreen trees and shrubs (Code_EveTr), deciduous trees and shrubs (Code_DecTr) and grass surfaces (Code_Grass). Value of integer is arbitrary but must match codes specified in SUEWS_SiteSelect.txt.
SUEWS_Water.txt L Code linking to SUEWS_SiteSelect.txt for water surfaces (Code_Water). Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.
SUEWS_Snow.txt L Code linking to SUEWS_SiteSelect.txt for snow surfaces (SnowCode). Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.
SUEWS_Soil.txt L Code linking to the SoilTypeCode column in SUEWS_NonVeg.txt (for Paved, Bldgs and BSoil surfaces) and SUEWS_Veg.txt (for EveTr, DecTr and Grass surfaces). Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.
SUEWS_Conductance.txt L Code linking to the CondCode column in SUEWS_SiteSelect.txt . Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.
SUEWS_AnthropogenicEmission.txt L Code linking to the AnthropogenicCode column in SUEWS_SiteSelect.txt . Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.
SUEWS_Irrigation.txt L Code linking to SUEWS_SiteSelect.txt for irrigation modelling (IrrigationCode). Value of integer is arbitrary but must match codes specified in SUEWS_SiteSelect.txt.
SUEWS_OHMCoefficients.txt L Code linking to the OHMCode_SummerWet, OHMCode_SummerDry, OHMCode_WinterWet and OHMCode_WinterDry columns in SUEWS_NonVeg.txt, SUEWS_Veg.txt, SUEWS_Water.txt and SUEWS_Snow.txt files. Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.
SUEWS_ESTMCoefficients.txt L For buildings and paved surfaces, set to zero if there is more than one ESTM class per grid and the codes and surface fractions specified in SUEWS_SiteSelect.txt will be used instead.
SUEWS_BiogenCO2.txt L Code linking to the BiogenCO2Code column in SUEWS_Veg.txt.
Code_Bldgs
Description:

Code for Bldgs surface characteristics linking to Code of SUEWS_NonVeg.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for Bldgs surface characteristics Provides the link to column 1 of SUEWS_NonVeg.txt, which contains the attributes describing buildings in this grid for this year. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_NonVeg.txt.
Code_BSoil
Description:

Code for BSoil surface characteristics linking to Code of SUEWS_NonVeg.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Value of integer is arbitrary but must match code specified in column 1 of SUEWS_NonVeg.txt.
Code_DecTr
Description:

Code for DecTr surface characteristics linking to Code of SUEWS_Veg.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for DecTr surface characteristics Provides the link to column 1 of SUEWS_Veg.txt, which contains the attributes describing deciduous trees and shrubs in this grid for this year. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Veg.txt.
Code_ESTMClass_Bldgs1
Description:

Code linking to SUEWS_ESTMCoefficients.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code linking to SUEWS_ESTMCoefficients.txt
Code_ESTMClass_Bldgs2
Description:

Code linking to SUEWS_ESTMCoefficients.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code linking to SUEWS_ESTMCoefficients.txt
Code_ESTMClass_Bldgs3
Description:

Code linking to SUEWS_ESTMCoefficients.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code linking to SUEWS_ESTMCoefficients.txt
Code_ESTMClass_Bldgs4
Description:

Code linking to SUEWS_ESTMCoefficients.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code linking to SUEWS_ESTMCoefficients.txt
Code_ESTMClass_Bldgs5
Description:

Code linking to SUEWS_ESTMCoefficients.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code linking to SUEWS_ESTMCoefficients.txt
Code_ESTMClass_Paved1
Description:

Code linking to SUEWS_ESTMCoefficients.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code linking to SUEWS_ESTMCoefficients.txt
Code_ESTMClass_Paved2
Description:

Code linking to SUEWS_ESTMCoefficients.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code linking to SUEWS_ESTMCoefficients.txt
Code_ESTMClass_Paved3
Description:

Code linking to SUEWS_ESTMCoefficients.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code linking to SUEWS_ESTMCoefficients.txt
Code_EveTr
Description:

Code for EveTr surface characteristics linking to Code of SUEWS_Veg.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for EveTr surface characteristics Provides the link to column 1 of SUEWS_Veg.txt, which contains the attributes describing evergreen trees and shrubs in this grid for this year. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Veg.txt.
Code_Grass
Description:

Code for Grass surface characteristics linking to Code of SUEWS_Veg.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for Grass surface characteristics Provides the link to column 1 of SUEWS_Veg.txt, which contains the attributes describing grass surfaces in this grid for this year. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Veg.txt.
Code_Paved
Description:

Code for Paved surface characteristics linking to Code of SUEWS_NonVeg.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for Paved surface characteristics Provides the link to column 1 of SUEWS_NonVeg.txt, which contains the attributes describing paved areas in this grid for this year. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_NonVeg.txt. e.g. 331 means use the characteristics specified in the row of input file SUEWS_NonVeg.txt which has 331 in column 1 (Code).
Code_Water
Description:

Code for Water surface characteristics linking to Code of SUEWS_Water.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for Water surface characteristics Provides the link to column 1 of SUEWS_Water.txt, which contains the attributes describing open water in this grid for this year. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Water.txt.
CondCode
Description:

Code for surface conductance parameters linking to Code of SUEWS_Conductance.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for surface conductance parameters Provides the link to column 1 of SUEWS_Conductance.txt, which contains the parameters for the Jarvis (1976) [Ja76] parameterisation of surface conductance. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Conductance.txt. e.g. 33 means use the characteristics specified in the row of input file SUEWS_Conductance.txt which has 33 in column 1 (Code).
CRWMax
Description:

Maximum water holding capacity of snow [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_Snow.txt MD Maximum water holding capacity of snow [mm]
CRWMin
Description:

Minimum water holding capacity of snow [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_Snow.txt MD Minimum water holding capacity of snow [mm]
DayWat(1)
Description:

Irrigation allowed on Sundays [1], if not [0]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Irrigation allowed on Sundays [1], if not [0]
DayWat(2)
Description:

Irrigation allowed on Mondays [1], if not [0]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Irrigation allowed on Mondays [1], if not [0]
DayWat(3)
Description:

Irrigation allowed on Tuesdays [1], if not [0]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Irrigation allowed on Tuesdays [1], if not [0]
DayWat(4)
Description:

Irrigation allowed on Wednesdays [1], if not [0]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Irrigation allowed on Wednesdays [1], if not [0]
DayWat(5)
Description:

Irrigation allowed on Thursdays [1], if not [0]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Irrigation allowed on Thursdays [1], if not [0]
DayWat(6)
Description:

Irrigation allowed on Fridays [1], if not [0]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Irrigation allowed on Fridays [1], if not [0]
DayWat(7)
Description:

Irrigation allowed on Saturdays [1], if not [0]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Irrigation allowed on Saturdays [1], if not [0]
DayWatPer(1)
Description:

Fraction of properties using irrigation on Sundays [0-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Fraction of properties using irrigation on Sundays [0-1]
DayWatPer(2)
Description:

Fraction of properties using irrigation on Mondays [0-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Fraction of properties using irrigation on Mondays [0-1]
DayWatPer(3)
Description:

Fraction of properties using irrigation on Tuesdays [0-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Fraction of properties using irrigation on Tuesdays [0-1]
DayWatPer(4)
Description:

Fraction of properties using irrigation on Wednesdays [0-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Fraction of properties using irrigation on Wednesdays [0-1]
DayWatPer(5)
Description:

Fraction of properties using irrigation on Thursdays [0-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Fraction of properties using irrigation on Thursdays [0-1]
DayWatPer(6)
Description:

Fraction of properties using irrigation on Fridays [0-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Fraction of properties using irrigation on Fridays [0-1]
DayWatPer(7)
Description:

Fraction of properties using irrigation on Saturdays [0-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Fraction of properties using irrigation on Saturdays [0-1]
DrainageCoef1
Description:

Coefficient D0 [mm h-1] used in DrainageEq

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MD
SUEWS_Veg.txt MD
SUEWS_Water.txt MD Not currently used for water surface
DrainageCoef2
Description:

Coefficient b [-] used in DrainageEq

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MD
SUEWS_Veg.txt MD
SUEWS_Water.txt MD Not currently used for water surface
DrainageEq
Description:

Calculation choice for Drainage equation

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MD
  • Options:
    • 1: Falk and Niemczynowicz (1978) [FN78]
    • 2: Halldin et al. (1979) [Ha79] (Rutter eqn corrected for c=0, see Calder & Wright (1986) [CW86])
    • 3: for BSoil Falk and Niemczynowicz (1978) [FN78]; for Paved and Bldgs Coefficients are specified in the following two columns. Recommended in this version.
SUEWS_Veg.txt MD
  • Options:
    • 1: Falk and Niemczynowicz (1978) [FN78]
    • 2: Halldin et al. (1979) [Ha79] (Rutter eqn corrected for c=0, see Calder & Wright (1986) [CW86] )
    • 3: for EveTr, DecTr, Grass (unirrigated) Falk and Niemczynowicz (1978) [FN78] Coefficients are specified in the following two columns. Recommended in this version.
SUEWS_Water.txt MD Not currently used for water surface.
EF_umolCO2perJ
Description:

Emission factor for fuels used for building heating.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Weekday building energy use [W m-2] Can be used for CO2 flux calculation.
Emissivity
Description:

Effective surface emissivity.

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MU Effective surface emissivity. View factors should be taken into account.
SUEWS_Veg.txt MU

Example values [-]

SUEWS_Water.txt MU

Example values [-]

  • 0.95 Water Oke (1987) [Ok87]
SUEWS_Snow.txt MU

Example values [-]

EndDLS
Description:

End of the day light savings [DOY]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU End of the day light savings [DOY] See Day Light Savings (DLS).
EnEF_v_Jkm
Description:

Emission factor for heat [J k|m^-1|].

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O Emission factor for heat [J k|m^-1|]. Example values: 3.97e6 Sailor and Lu (2004) [SL04]
EnergyUseProfWD
Description:

Code linking to EnergyUseProfWD in SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt L Code for energy use profile (weekdays) Provides the link to column 1 of SUEWS_Profiles.txt. Look the codes Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt.
EnergyUseProfWE
Description:

Code linking to EnergyUseProfWE in SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt L Code for energy use profile (weekends) Provides the link to column 1 of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt.
ESTMCode
Description:

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt L For paved and building surfaces, it is possible to specify multiple codes per grid (3 for paved, 5 for buildings) using SUEWS_SiteSelect.txt . In this case, set ESTMCode here to zero.
SUEWS_Veg.txt L Code for ESTM coefficients to use for this surface. Links to SUEWS_ESTMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_ESTMCoefficients.txt.
SUEWS_Water.txt L Code for ESTM coefficients to use for this surface. Links to SUEWS_ESTMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_ESTMCoefficients.txt.
SUEWS_Snow.txt L For paved and building surfaces, it is possible to specify multiple codes per grid (3 for paved, 5 for buildings) using SUEWS_SiteSelect.txt . In this case, set ESTM code here to zero.
FAI_Bldgs
Description:

Frontal area index for buildings [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Frontal area index for buildings [-] Required if RoughLenMomMethod = 3 in RunControl.nml .
FAI_DecTr
Description:

Frontal area index for deciduous trees [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Frontal area index for deciduous trees [-] Required if RoughLenMomMethod = 3 in RunControl.nml .
FAI_EveTr
Description:

Frontal area index for evergreen trees [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Frontal area index for evergreen trees [-] Required if RoughLenMomMethod = 3 in RunControl.nml .
Faut
Description:

Fraction of irrigated area that is irrigated using automated systems

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Fraction of irrigated area that is irrigated using automated systems (e.g. sprinklers).
FcEF_v_kgkmWD
Description:

CO2 emission factor for weekdays [kg km-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O CO2 emission factor for weekdays [kg km-1] Can be used for CO2 flux calculation.
FcEF_v_kgkmWE
Description:

CO2 emission factor for weekends [kg km-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O CO2 emission factor for weekdays [kg km-1] Can be used for CO2 flux calculation.
FcEF_v_Jkm
Description:

Traffic emission factor for CO2.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Weekday building energy use [W m-2] Can be used for CO2 flux calculation.
fcld
Description:

Cloud fraction [tenths]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Cloud fraction [tenths]
FlowChange
Description:

Difference in input and output flows for water surface [mm h-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD Difference in input and output flows for water surface [mm h-1] Used to indicate river or stream flow through the grid. Currently not fully tested!
Fraction1of8
Description:

Fraction of water that can flow to GridConnection1of8 [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Fraction of water that can flow to the grid specified in previous column [-]
Fraction2of8
Description:

Fraction of water that can flow to GridConnection2of8 [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Fraction of water that can flow to the grid specified in previous column [-]
Fraction3of8
Description:

Fraction of water that can flow to GridConnection3of8 [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Fraction of water that can flow to the grid specified in previous column [-]
Fraction4of8
Description:

Fraction of water that can flow to GridConnection4of8 [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Fraction of water that can flow to the grid specified in previous column [-]
Fraction5of8
Description:

Fraction of water that can flow to GridConnection5of8 [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Fraction of water that can flow to the grid specified in previous column [-]
Fraction6of8
Description:

Fraction of water that can flow to GridConnection6of8 [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Fraction of water that can flow to the grid specified in previous column [-]
Fraction7of8
Description:

Fraction of water that can flow to GridConnection7of8 [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Fraction of water that can flow to the grid specified in previous column [-]
Fraction8of8
Description:

Fraction of water that can flow to GridConnection8of8 [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Fraction of water that can flow to the grid specified in previous column [-]
Fr_Bldgs
Description:

Surface cover fraction of buildings [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Surface cover fraction of buildings [-]
Fr_Bsoil
Description:

Surface cover fraction of bare soil or unmanaged land [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Surface cover fraction of bare soil or unmanaged land [-]
Fr_DecTr
Description:

Surface cover fraction of deciduous trees and shrubs [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Surface cover fraction of deciduous trees and shrubs [-]
Fr_ESTMClass_Bldgs1
Description:

Surface cover fraction of building class 1 used in ESTM calculations

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Columns 94-98 must add up to 1
Fr_ESTMClass_Bldgs2
Description:

Surface cover fraction of building class 2 used in ESTM calculations

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Columns 94-98 must add up to 1
Fr_ESTMClass_Bldgs3
Description:

Surface cover fraction of building class 3 used in ESTM calculations

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Columns 94-98 must add up to 1
Fr_ESTMClass_Bldgs4
Description:

Surface cover fraction of building class 4 used in ESTM calculations

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Columns 94-98 must add up to 1
Fr_ESTMClass_Bldgs5
Description:

Surface cover fraction of building class 5 used in ESTM calculations

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Columns 94-98 must add up to 1
Fr_ESTMClass_Paved1
Description:

Surface cover fraction of Paved surface class 1 used in ESTM calculations

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Columns 88-90 must add up to 1
Fr_ESTMClass_Paved2
Description:

Surface cover fraction of Paved surface class 2 used in ESTM calculations

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Columns 88-90 must add up to 1
Fr_ESTMClass_Paved3
Description:

Surface cover fraction of Paved surface class 3 used in ESTM calculations

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Columns 88-90 must add up to 1
Fr_EveTr
Description:

Surface cover fraction of EveTr: evergreen trees and shrubs [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Surface cover fraction of evergreen trees and shrubs [-]
Fr_Grass
Description:

Surface cover fraction of Grass [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Surface cover fraction of grass [-]
Fr_Paved
Description:

Surface cover fraction of Paved surfaces [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Columns 14 to 20 must sum to 1 .
Fr_Water
Description:

Surface cover fraction of open water [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Surface cover fraction of open water [-] (e.g. river, lakes, ponds, swimming pools)
FrFossilFuel_Heat
Description:

Fraction of fossil fuels used for building heating [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Weekday building energy use [W m-2] Can be used for CO2 flux calculation.
FrFossilFuel_NonHeat
Description:

Fraction of fossil fuels used for building energy use [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Weekday building energy use [W m-2] Can be used for CO2 flux calculation.
FrPDDwe
Description:Fraction of weekend population to weekday population. [-]
Configuration:
G1
Description:

Related to maximum surface conductance [mm s-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Related to maximum surface conductance [mm s-1]
G2
Description:

Related to Kdown dependence [W m-2]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Related to Kdown dependence [W m-2]
G3
Description:

Related to VPD dependence [units depend on gsModel]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Related to VPD dependence [units depend on gsChoice in RunControl.nml ]
G4
Description:

Related to VPD dependence [units depend on gsModel]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Related to VPD dependence [units depend on gsChoice in RunControl.nml ]
G5
Description:

Related to temperature dependence [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Related to temperature dependence [°C]
G6
Description:

Related to soil moisture dependence [mm-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Related to soil moisture dependence [mm-1]
gamq_gkgm
Description:

vertical gradient of specific humidity [g kg-1 m-1]

Configuration:
Referencing Table Requirement Comment
CBL_initial_data.txt MU vertical gradient of specific humidity (g kg-1 m-1 )
gamt_Km
Description:

vertical gradient of potential temperature [K m-1]

Configuration:
Referencing Table Requirement Comment
CBL_initial_data.txt MU vertical gradient of potential temperature (K m-1 ) strength of the inversion
GDDFull
Description:

The growing degree days (GDD) needed for full capacity of the leaf area index (LAI) [°C].

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MU This should be checked carefully for your study area using modelled LAI from the DailyState output file compared to known behaviour in the study area. See section 2.2 Järvi et al. (2011) [J11] ; Appendix A Järvi et al. (2014) [Leena2014] for more details. Example values: 300 for EveTr Järvi et al. (2011) [J11]
Grid
Description:

a unique number to represent grid

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Grid numbers do not need to be consecutive and do not need to start at a particular value. Each grid must have a unique grid number. All grids must be present for all years. These grid numbers are referred to in GridConnections (columns 64-79) ( N.B. Not available in this version. )
GridConnection1of8
Description:

Number of the 1st grid where water can flow to The next 8 pairs of columns specify the water flow between grids. The first column of each pair specifies the grid that the water flows to (from the current grid, column 1); the second column of each pair specifies the fraction of water that flow to that grid. The fraction (i.e. amount) of water transferred may be estimated based on elevation, the length of connecting surface between grids, presence of walls, etc. Water cannot flow from the current grid to the same grid, so the grid number here must be different to the grid number in column 1. Water can flow to a maximum of 8 other grids. If there is no water flow between grids, or a single grid is run, set to 0. See section on Grid Connections

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU The next 8 pairs of columns specify the water flow between grids. The first column of each pair specifies the grid that the water flows to (from the current grid, column 1); the second column of each pair specifies the fraction of water that flow to that grid. The fraction (i.e. amount) of water transferred may be estimated based on elevation, the length of connecting surface between grids, presence of walls, etc. Water cannot flow from the current grid to the same grid, so the grid number here must be different to the grid number in column 1. Water can flow to a maximum of 8 other grids. If there is no water flow between grids, or a single grid is run, set to 0. See section on Grid Connections
GridConnection2of8
Description:

Number of the 2nd grid where water can flow to

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Number of the grid where water can flow to
GridConnection3of8
Description:

Number of the 3rd grid where water can flow to

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Number of the grid where water can flow to
GridConnection4of8
Description:

Number of the 4th grid where water can flow to

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Number of the grid where water can flow to
GridConnection5of8
Description:

Number of the 5th grid where water can flow to

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Number of the grid where water can flow to
GridConnection6of8
Description:

Number of the 6th grid where water can flow to

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Number of the grid where water can flow to
GridConnection7of8
Description:

Number of the 7th grid where water can flow to

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Number of the grid where water can flow to
GridConnection8of8
Description:

Number of the 8th grid where water can flow to

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Number of the grid where water can flow to
gsModel
Description:

Formulation choice for conductance calculation.

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD
  • 1 Järvi et al. (2011) [J11]
  • 2 (Recommended) Ward et al. (2016) [W16]
H_Bldgs
Description:

Mean building height [m]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Mean building height [m]
H_DecTr
Description:

Mean height of deciduous trees [m]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Mean height of deciduous trees [m]
H_EveTr
Description:

Mean height of evergreen trees [m]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Mean height of evergreen trees [m]
id
Description:

Day of year [DOY]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD Not used: set to 1 in this version.
SSss_YYYY_ESTM_Ts_data_tt.txt MU Day of year [DOY]
SSss_YYYY_data_tt.txt MU Day of year [DOY]
CBL_initial_data.txt MU Day of year [DOY]
Ie_a1
Description:

Coefficient for automatic irrigation model [mm d-1 ]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MD Coefficient for automatic irrigation model [mm d -1 ]
Ie_a2
Description:

Coefficient for automatic irrigation model [mm d-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MD Coefficient for automatic irrigation model [mm d -1 K-1]
Ie_a3
Description:

Coefficient for automatic irrigation model [mm d-2 ]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MD Coefficient for automatic irrigation model [mm d -2 ]
Ie_end
Description:

Day when irrigation ends [DOY]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Day when irrigation ends [DOY]
Ie_m1
Description:

Coefficient for manual irrigation model [mm d-1 ]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MD Coefficient for manual irrigation model [mm d -1 ]
Ie_m2
Description:

Coefficient for manual irrigation model [mm d-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MD Coefficient for manual irrigation model [mm d -1 K-1]
Ie_m3
Description:

Coefficient for manual irrigation model [mm d-2 ]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MD Coefficient for manual irrigation model [mm d -2 ]
Ie_start
Description:

Day when irrigation starts [DOY]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Day when irrigation starts [DOY]
ih
Description:

Hour [H]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD Hour [H] Not used: set to 0 in this version.
imin
Description:

Minute [M]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD Minute [M] Not used: set to 0 in this version.
SSss_YYYY_ESTM_Ts_data_tt.txt MU Minute [M]
SSss_YYYY_data_tt.txt MU Minute [M]
InfiltrationRate
Description:

Infiltration rate.

Configuration:
Referencing Table Requirement Comment
SUEWS_Soil.txt O Not currently used
Internal_albedo
Description:

Albedo of all internal elements for building surfaces only

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Albedo of all internal elements for building surfaces only
Internal_CHbld
Description:

Bulk transfer coefficient of internal building elements [W m-2 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Bulk transfer coefficient of internal building elements [W m-2 K-1] (for building surfaces only and if IbldCHmod == 0 in ESTMinput.nml
Internal_CHroof
Description:

Bulk transfer coefficient of internal roof [W m-2 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Bulk transfer coefficient of internal roof [W m-2 K-1] (for building surfaces only and if IbldCHmod == 0 in ESTMinput.nml
Internal_CHwall
Description:

Bulk transfer coefficient of internal wall [W m-2 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Bulk transfer coefficient of internal wall [W m-2 K-1] (for building surfaces only and if IbldCHmod == 0 in ESTMinput.nml
Internal_emissivity
Description:

Emissivity of all internal elements for building surfaces only

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Emissivity of all internal elements for building surfaces only
Internal_k1
Description:

Thermal conductivity of the first layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Thermal conductivity of the first layer [W m-1 K-1]
Internal_k2
Description:

Thermal conductivity of the second layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the second layer [W m-1 K-1]
Internal_k3
Description:

Thermal conductivity of the third layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the third layer [W m-1 K-1]
Internal_k4
Description:

Thermal conductivity of the fourth layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the fourth layer [W m-1 K-1]
Internal_k5
Description:

Thermal conductivity of the fifth layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the fifth layer [W m-1 K-1]
Internal_rhoCp1
Description:

Volumetric heat capacity of the first layer[J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Volumetric heat capacity of the first layer[J m-3 K-1]
Internal_rhoCp2
Description:

Volumetric heat capacity of the second layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the second layer [J m-3 K-1]
Internal_rhoCp3
Description:

Volumetric heat capacity of the third layer[J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the third layer[J m-3 K-1]
Internal_rhoCp4
Description:

Volumetric heat capacity of the fourth layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the fourth layer [J m-3 K-1]
Internal_rhoCp5
Description:

Volumetric heat capacity of the fifth layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the fifth layer [J m-3 K-1]
Internal_thick1
Description:

Thickness of the first layer [m] for building surfaces only

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Thickness of the first layer [m] for building surfaces only; set to -999 for all other surfaces
Internal_thick2
Description:

Thickness of the second layer [m]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the second layer [m] (if no second layer, set to -999.)
Internal_thick3
Description:

Thickness of the third layer [m]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the third layer [m] (if no third layer, set to -999.)
Internal_thick4
Description:

Thickness of the fourth layer [m]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the fourth layer [m] (if no fourth layer, set to -999.)
Internal_thick5
Description:

Thickness of the fifth layer [m]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the fifth layer [m] (if no fifth layer, set to -999.)
InternalWaterUse
Description:

Internal water use [mm h-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Irrigation.txt MU Internal water use [mm h-1]
IrrFr_DecTr
Description:

Fraction of deciduous trees that are irrigated [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Fraction of deciduous trees that are irrigated [-]
IrrFr_EveTr
Description:

Fraction of evergreen trees that are irrigated [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Fraction of evergreen trees that are irrigated [-] e.g. 50% of the evergreen trees/shrubs are irrigated
IrrFr_Grass
Description:

Fraction of Grass that is irrigated [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Fraction of grass that is irrigated [-]
IrrigationCode
Description:

Code for modelling irrigation linking to Code of SUEWS_Irrigation.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for modelling irrigation Provides the link to column 1 of SUEWS_Irrigation.txt, which contains the model coefficients for estimation of the water use (used if WU_Choice = 0 in RunControl.nml ). Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Irrigation.txt.
it
Description:

Hour [H]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU Hour [H]
SSss_YYYY_data_tt.txt MU Hour [H]
iy
Description:

Year [YYYY]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU Year [YYYY]
SSss_YYYY_data_tt.txt MU Year [YYYY]
kdiff
Description:

Diffuse radiation [W m-2].

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Recommended if SOLWEIGUse = 1
kdir
Description:

Direct radiation [W m-2].

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Recommended if SOLWEIGUse = 1
kdown
Description:

Incoming shortwave radiation [W m-2].

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt MU Must be > 0 W m-2 .
Kmax
Description:

Maximum incoming shortwave radiation [W m-2]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Maximum incoming shortwave radiation [W m-2]
lai
Description:

Observed leaf area index [m-2 m-2]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Observed leaf area index [m-2 m-2]
LAIEq
Description:

LAI calculation choice.

Note

North and South hemispheres are treated slightly differently.

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MD

Coefficients are specified in the following parameters: LeafGrowthPower1, LeafGrowthPower2, LeafOffPower1 and LeafOffPower2.

Options

LAIMax
Description:

full leaf-on summertime value

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MD full leaf-on summertime value Example values: - 5.1 EveTr Breuer et al. (2003) [Br03] - 5.5 DecTr Breuer et al. (2003) [Br03] - 5.9 Grass Breuer et al. (2003) [Br03]
LAIMin
Description:

leaf-off wintertime value

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MD leaf-off wintertime value Example values: - 4. EveTr Järvi et al. (2011) [J11] - 1. DecTr Järvi et al. (2011) [J11] - 1.6 Grass Grimmond and Oke (1991) [G91]
lat
Description:

Latitude [deg].

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Use coordinate system WGS84. Positive values are northern hemisphere (negative southern hemisphere). Used in radiation calculations. Note, if the total modelled area is small the latitude and longitude could be the same for each grid but small differences in radiation will not be determined. If you are defining the latitude and longitude differently between grids make certain that you provide enough decimal places.
ldown
Description:

Incoming longwave radiation [W m-2]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Incoming longwave radiation [W m-2]
LeafGrowthPower1
Description:

a parameter required by LAI calculation in LAIEq

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MD

Example values

LeafGrowthPower2
Description:

a parameter required by LAI calculation [K-1] in LAIEq

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MD

Example values

LeafOffPower1
Description:

a parameter required by LAI calculation [K-1] in LAIEq

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MD

Example values

LeafOffPower2
Description:

a parameter required by LAI calculation [K-1] in LAIEq

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MD

Example values

lng
Description:

longitude [deg]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Use coordinate system WGS84. For compatibility with GIS, negative values are to the west, positive values are to the east (e.g. Vancouver = -123.12; Shanghai = 121.47) Note this is a change of sign convention between v2016a and v2017a See latitude for more details.
LUMPS_Cover
Description:

Limit when surface totally covered with water for LUMPS [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD Limit when surface totally covered with water [mm] Used for LUMPS surface wetness control. Default recommended value of 1 mm from Loridan et al. (2011) [L2011] .
LUMPS_DrRate
Description:

Drainage rate of bucket for LUMPS [mm h-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD Drainage rate of bucket for LUMPS [mm h-1] Used for LUMPS surface wetness control. Default recommended value of 0.25 mm h-1 from Loridan et al. (2011) [L2011] .
LUMPS_MaxRes
Description:

Maximum water bucket reservoir [mm] Used for LUMPS surface wetness control.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD Maximum water bucket reservoir [mm] Used for LUMPS surface wetness control. Default recommended value of 10 mm from Loridan et al. (2011) [L2011] .
MaxQFMetab
Description:

Maximum value for human heat emission. [W m-2]

Example values: 175 Sailor and Lu (2004) [SL04]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O Maximum value for human heat emission. [W m-2]
MaxFCMetab
Description:

Maximum (day) CO2 from human metabolism. [W m-2]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O Maximum (day) CO2 from human metabolism. [W m-2]
MaxConductance
Description:

The maximum conductance of each vegetation or surface type. [mm s-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MD

Example values [mm s-1]

  • 7.4: EveTr Järvi et al. (2011) [J11]
  • 11.7: DecTr Järvi et al. (2011) [J11]
  • 33.1: Grass (unirrigated) Järvi et al. (2011) [J11]
  • 40.: Grass (irrigated) Järvi et al. (2011) [J11]
MinQFMetab
Description:

Minimum value for human heat emission. [W m-2]

Example values: 75 Sailor and Lu (2004) [SL04]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O Minimum value for human heat emission. [W m-2].
MinFCMetab
Description:

Minimum (night) CO2 from human metabolism. [W m-2]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O Minimum (night) CO2 from human metabolism. [W m-2]
NARP_Trans
Description:

Atmospheric transmissivity for NARP [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD Atmospheric transmissivity for NARP [-] Value must in the range 0-1. Default recommended value of 1.
nroom
Description:

Number of rooms per floor for building surfaces only [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Number of rooms per floor for building surfaces only
OBS_SMCap
Description:

The maximum observed soil moisture. [m3 m-3 or kg kg-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Soil.txt O Use only if soil moisture is observed and provided in the met forcing file and SMDMethod = 1 or 2. Use of observed soil moisture not currently tested
OBS_SMDepth
Description:

The depth of soil moisture measurements. [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_Soil.txt O Use only if soil moisture is observed and provided in the met forcing file and SMDMethod = 1 or 2. Use of observed soil moisture not currently tested
OBS_SoilNotRocks
Description:

Fraction of soil without rocks. [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_Soil.txt O Use only if soil moisture is observed and provided in the met forcing file and SMDMethod = 1 or 2. Use of observed soil moisture not currently tested
OHMCode_SummerDry
Description:

Code for OHM coefficients to use for this surface during dry conditions in summer, linking to SUEWS_OHMCoefficients.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt L Code for OHM coefficients to use for this surface during dry conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Veg.txt L Code for OHM coefficients to use for this surface during dry conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Water.txt L Code for OHM coefficients to use for this surface during dry conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Snow.txt L Code for OHM coefficients to use for this surface during dry conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
OHMCode_SummerWet
Description:

Code for OHM coefficients to use for this surface during wet conditions in summer, linking to SUEWS_OHMCoefficients.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt L Code for OHM coefficients to use for this surface during wet conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Veg.txt L Code for OHM coefficients to use for this surface during wet conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Water.txt L Code for OHM coefficients to use for this surface during wet conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Snow.txt L Code for OHM coefficients to use for this surface during wet conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
OHMCode_WinterDry
Description:

Code for OHM coefficients to use for this surface during dry conditions in winter, linking to SUEWS_OHMCoefficients.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt L Code for OHM coefficients to use for this surface during dry conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Veg.txt L Code for OHM coefficients to use for this surface during dry conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Water.txt L Code for OHM coefficients to use for this surface during dry conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Snow.txt L Code for OHM coefficients to use for this surface during dry conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
OHMCode_WinterWet
Description:

Code for OHM coefficients to use for this surface during wet conditions in winter, linking to SUEWS_OHMCoefficients.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt L Code for OHM coefficients to use for this surface during wet conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Veg.txt L Code for OHM coefficients to use for this surface during wet conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Water.txt L Code for OHM coefficients to use for this surface during wet conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
SUEWS_Snow.txt L Code for OHM coefficients to use for this surface during wet conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.
OHMThresh_SW
Description:

Temperature threshold determining whether summer/winter OHM coefficients are applied [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MD Temperature threshold determining whether summer/winter OHM coefficients are applied [°C] If 5-day running mean air temperature is greater than or equal to this threshold, OHM coefficients for summertime are applied; otherwise coefficients for wintertime are applied.
SUEWS_Veg.txt MD Temperature threshold determining whether summer/winter OHM coefficients are applied [°C] If 5-day running mean air temperature is greater than or equal to this threshold, OHM coefficients for summertime are applied; otherwise coefficients for wintertime are applied.
SUEWS_Water.txt MD Temperature threshold determining whether summer/winter OHM coefficients are applied [°C] If 5-day running mean air temperature is greater than or equal to this threshold, OHM coefficients for summertime are applied; otherwise coefficients for wintertime are applied.
SUEWS_Snow.txt MD Not actually used for Snow surface as winter wet conditions always assumed.
OHMThresh_WD
Description:

Soil moisture threshold determining whether wet/dry OHM coefficients are applied [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MD Not actually used for building and paved surfaces (as impervious).
SUEWS_Veg.txt MD Note that OHM coefficients for wet conditions are applied if the surface is wet.
SUEWS_Water.txt MD Not actually used for water surface (as no soil surface beneath).
SUEWS_Snow.txt MD Not actually used for Snow surface as winter wet conditions always assumed.
PipeCapacity
Description:

Storage capacity of pipes [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Storage capacity of pipes [mm] Runoff amounting to less than the value specified here is assumed to be removed by pipes.
PopDensDay
Description:

Daytime population density (i.e. workers, tourists) [people ha-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Daytime population density (i.e. workers, tourists) [people ha -1 ] Population density is required if EmissionsMethod = 2 in RunControl.nml . The model will use the average of daytime and night-time population densities, unless only one is provided. If daytime population density is unknown, set to -999.
PopDensNight
Description:

Night-time population density (i.e. residents) [people ha-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Night-time population density (i.e. residents) [people ha -1 ] Population density is required if EmissionsMethod = 2 in RunControl.nml . The model will use the average of daytime and night-time population densities, unless only one is provided. If night-time population density is unknown, set to -999.
PopProfWD
Description:

Code for population density profile (weekdays) linking to Code of SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O Weekday building energy use [W m-2] Can be used for CO2 flux calculation.
PopProfWE
Description:

Code for population density profile (weekends) linking to Code of SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O Weekday building energy use [W m-2] Can be used for CO2 flux calculation.
PorosityMax
Description:

full leaf-on summertime value Used only for DecTr (can affect roughness calculation)

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MD full leaf-on summertime value Used only for DecTr (can affect roughness calculation)
PorosityMin
Description:

leaf-off wintertime value Used only for DecTr (can affect roughness calculation)

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MD leaf-off wintertime value Used only for DecTr (can affect roughness calculation)
PrecipLimAlb
Description:

Limit for hourly precipitation when the ground is fully covered with snow [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_Snow.txt MD Limit for hourly precipitation when the ground is fully covered with snow. Then snow albedo is reset to AlbedoMax [mm]
PrecipLimSnow
Description:

Temperature limit when precipitation falls as snow [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_Snow.txt MD Auer (1974) [Au74]
pres
Description:

Barometric pressure [kPa]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt MU Barometric pressure [kPa]
qe
Description:

Latent heat flux [W m-2]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Latent heat flux [W m-2]
qf
Description:

Anthropogenic heat flux [W m-2]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Anthropogenic heat flux [W m-2]
QF_A_WD
Description:

Base value for QF on weekdays [W m-2 (Cap ha-1 )-1 ]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O

Use with EmissionsMethod = 2

Example values:

QF_A_WE
Description:

Base value for QF on weekends [W m-2 (Cap ha-1 )-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O

Use with EmissionsMethod = 2

Example values:

QF_B_WD
Description:

Parameter related to cooling degree days on weekdays [W m-2 K-1 (Cap ha-1 )-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O

Use with EmissionsMethod = 2

Example values:

QF_B_WE
Description:

Parameter related to cooling degree days on weekends [W m-2 K-1 (Cap ha-1 )-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O

Use with EmissionsMethod = 2

Example values:

QF_C_WD
Description:

Parameter related to heating degree days on weekdays [W m-2 K-1 (Cap ha-1 )-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O

Use with EmissionsMethod = 2

Example values:

QF_C_WE
Description:

Parameter related to heating degree days on weekends [W m-2 K-1 (Cap ha-1 )-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O

Example values:

q+_gkg
Description:

specific humidity at the top of CBL [g kg-1]

Configuration:
Referencing Table Requirement Comment
CBL_initial_data.txt MU specific humidity at the top of CBL (g kg-1 )
q_gkg
Description:

specific humidiy in CBL [g kg-1]

Configuration:
Referencing Table Requirement Comment
CBL_initial_data.txt MU specific humidiy in CBL (g kg-1 )
qh
Description:

Sensible heat flux [W m-2]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Sensible heat flux [W m-2]
qn
Description:

Net all-wave radiation [W m-2]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Required if NetRadiationMethod = 1.
qs
Description:

Storage heat flux [W m-2]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Storage heat flux [W m-2]
RadMeltFactor
Description:

Hourly radiation melt factor of snow [mm W-1 h-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Snow.txt MU Hourly radiation melt factor of snow [mm W-1 h-1]
rain
Description:

Rainfall [mm]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt MU Rainfall [mm]
RH
Description:

Relative Humidity [%]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt MU Relative Humidity [%]
RunoffToWater
Description:

Fraction of above-ground runoff flowing to water surface during flooding [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MD MU Fraction of above-ground runoff flowing to water surface during flooding [-] Value must be in the range 0-1. Fraction of above-ground runoff that can flow to the water surface in the case of flooding.
S1
Description:

A parameter related to soil moisture dependence [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Related to soil moisture dependence [-] These will change in the future to ensure consistency with soil behaviour
S2
Description:

A parameter related to soil moisture dependence [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Related to soil moisture dependence [mm] These will change in the future to ensure consistency with soil behaviour
SatHydraulicCond
Description:

Hydraulic conductivity for saturated soil [mm s-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Soil.txt MD Hydraulic conductivity for saturated soil [mm s-1]
SDDFull
Description:

The sensesence degree days (SDD) needed to initiate leaf off. [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_Veg.txt MU

This should be checked carefully for your study area using modelled LAI from the DailyState output file compared to known behaviour in the study area. See section 2.2 Järvi et al. (2011) [J11] ; Appendix A Järvi et al. (2014) [Leena2014] for more details.

Example values:

snow
Description:

Snowfall [mm]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Required if SnowUse = 1
SnowClearingProfWD
Description:

Code for snow clearing profile (weekdays) linking to Code of SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for snow clearing profile (weekdays) Provides the link to column 1 of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt. e.g. 1 means use the characteristics specified in the row of input file SUEWS_Profiles.txt which has 1 in column 1 (Code).
SnowClearingProfWE
Description:

Code for snow clearing profile (weekends) linking to Code of SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for snow clearing profile (weekends) Provides the link to column 1 of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt. e.g. 1 means use the characteristics specified in the row of input file SUEWS_Profiles.txt which has 1 in column 1 (Code). Providing the same code for SnowClearingProfWD and SnowClearingProfWE would link to the same row in SUEWS_Profiles.txt, i.e. the same profile would be used for weekdays and weekends.
SnowCode
Description:

Code for snow surface characteristics linking to Code of SUEWS_Snow.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for snow surface characteristics Provides the link to column 1 of SUEWS_Snow.txt, which contains the attributes describing snow surfaces in this grid for this year. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Snow.txt.
SnowDensMax
Description:Maximum snow density [kg m-3]
Configuration:
SnowDensMin
Description:Fresh snow density [kg m-3]
Configuration:
SnowLimPatch
Description:

Limit for the snow water equivalent when snow cover starts to be patchy [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt O

Limit of snow water equivalent when the surface is fully covered with snow. Not needed if SnowUse = 0 in RunControl.nml .

Example values:

SUEWS_Veg.txt O

Limit of snow water equivalent when the surface is fully covered with snow. Not needed if SnowUse = 0 in RunControl.nml .

Example values:

SnowLimRemove
Description:

Limit of the snow water equivalent for snow removal from roads and roofs [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt O

Not needed if SnowUse = 0 in RunControl.nml . Not available in this version.

Example values [mm]

SoilDensity
Description:

Soil density [kg m-3]

Configuration:
Referencing Table Requirement Comment
SUEWS_Soil.txt MD Soil density [kg m-3]
SoilDepth
Description:

Depth of soil beneath the surface [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_Soil.txt MD Depth of sub-surface soil store [mm] i.e. the depth of soil beneath the surface
SoilStoreCap
Description:

Limit value for SoilDepth [mm]

Configuration:
Referencing Table Requirement Comment
SUEWS_Soil.txt MD SoilStoreCap must not be greater than SoilDepth.
SoilTypeCode
Description:

Code for soil characteristics below this surface linking to Code of SUEWS_Soil.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt L Code for soil characteristics below this surface Provides the link to column 1 of SUEWS_Soil.txt, which contains the attributes describing sub-surface soil for this surface type. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Soil.txt.
SUEWS_Veg.txt L Code for soil characteristics below this surface Provides the link to column 1 of SUEWS_Soil.txt, which contains the attributes describing sub-surface soil for this surface type. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Soil.txt.
StartDLS
Description:

Start of the day light savings [DOY]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Start of the day light savings [DOY] See Day Light Savings (DLS).
StateLimit
Description:

Upper limit to the surface state. [mm]

Currently only used for the water surface. Set to a large value (e.g. 20000 mm = 20 m) if the water body is substantial (lake, river, etc) or a small value (e.g. 10 mm) if water bodies are very shallow (e.g. fountains). WaterDepth (column 9) must not exceed this value.

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MD Currently only used for the water surface
SUEWS_Veg.txt MD Currently only used for the water surface
SUEWS_Water.txt MU Surface state cannot exceed this value. Set to a large value (e.g. 20000 mm = 20 m) if the water body is substantial (lake, river, etc) or a small value (e.g. 10 mm) if water bodies are very shallow (e.g. fountains). WaterDepth (column 9) must not exceed this value.
StorageMax
Description:

Maximum water storage capacity for upper surfaces (i.e. canopy)

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MD

Maximum water storage capacity for upper surfaces (i.e. canopy) Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces). Not currently used for non-vegetated surfaces - set the same as StorageMin.

Example values:

SUEWS_Veg.txt MD

Maximum water storage capacity for upper surfaces (i.e. canopy) Min/max values are to account for seasonal variation (e.g. leaf-off/leaf-on differences for vegetated surfaces) Only used for DecTr surfaces - set EveTr and Grass values the same as StorageMin.

Example values:

SUEWS_Water.txt MD Maximum water storage capacity for upper surfaces (i.e. canopy) Min and max values are to account for seasonal variation - not used for water surfaces so set same as StorageMin.
StorageMin
Description:

Minimum water storage capacity for upper surfaces (i.e. canopy).

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MD

Minimum water storage capacity for upper surfaces (i.e. canopy). Min/max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces). Not currently used for non-vegetated surfaces - set the same as StorageMax.

Example values:

SUEWS_Veg.txt MD

Minimum water storage capacity for upper surfaces (i.e. canopy). Min/max values are to account for seasonal variation (e.g. leaf-off/leaf-on differences for vegetated surfaces).

Example values:

SUEWS_Water.txt MD

Minimum water storage capacity for upper surfaces (i.e. canopy). Min/max values are to account for seasonal variation - not used for water surfaces.

Example values:

-0.5 Water

SurfaceArea
Description:

Area of the grid [ha].

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Area of the grid [ha].
Surf_k1
Description:

Thermal conductivity of the first layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Thermal conductivity of the first layer [W m-1 K-1]
Surf_k2
Description:

Thermal conductivity of the second layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the second layer [W m-1 K-1]
Surf_k3
Description:

Thermal conductivity of the third layer[W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the third layer[W m-1 K-1]
Surf_k4
Description:

Thermal conductivity of the fourth layer[W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the fourth layer[W m-1 K-1]
Surf_k5
Description:

Thermal conductivity of the fifth layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the fifth layer [W m-1 K-1]
Surf_rhoCp1
Description:

Volumetric heat capacity of the first layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Volumetric heat capacity of the first layer [J m-3 K-1]
Surf_rhoCp2
Description:

Volumetric heat capacity of the second layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the second layer [J m-3 K-1]
Surf_rhoCp3
Description:

Volumetric heat capacity of the third layer[J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the third layer[J m-3 K-1]
Surf_rhoCp4
Description:

Volumetric heat capacity of the fourth layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the fourth layer [J m-3 K-1]
Surf_rhoCp5
Description:

Volumetric heat capacity of the fifth layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the fifth layer [J m-3 K-1]
Surf_thick1
Description:

Thickness of the first layer [m] for roofs (building surfaces) and ground (all other surfaces)

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Thickness of the first layer [m] for roofs (building surfaces) and ground (all other surfaces)
Surf_thick2
Description:

Thickness of the second layer [m] (if no second layer, set to -999.)

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the second layer [m] (if no second layer, set to -999.)
Surf_thick3
Description:

Thickness of the third layer [m] (if no third layer, set to -999.)

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the third layer [m] (if no third layer, set to -999.)
Surf_thick4
Description:

Thickness of the fourth layer [m] (if no fourth layer, set to -999.)

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the fourth layer [m] (if no fourth layer, set to -999.)
Surf_thick5
Description:

Thickness of the fifth layer [m] (if no fifth layer, set to -999.)

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the fifth layer [m] (if no fifth layer, set to -999.)
Tair
Description:

Air temperature [°C]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt MU Air temperature [°C]
tau_a
Description:

Time constant for snow albedo aging in cold snow [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_Snow.txt MD Time constant for snow albedo aging in cold snow [-]
tau_f
Description:

Time constant for snow albedo aging in melting snow [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_Snow.txt MD Time constant for snow albedo aging in melting snow [-]
tau_r
Description:

Time constant for snow density ageing [-]

Configuration:
Referencing Table Requirement Comment
SUEWS_Snow.txt MD Time constant for snow density ageing [-]
TCritic_Heating_WD
Description:

Critical heating temperature on weekdays [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O Use with EmissionsMethod = 1
TCritic_Heating_WE
Description:

Critical heating temperature on weekends [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O Use with EmissionsMethod = 1
TCritic_Cooling_WD
Description:

Critical cooling temperature on weekdays [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O Use with EmissionsMethod = 1
TCritic_Cooling_WE
Description:

Critical cooling temperature on weekends [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt MU O Use with EmissionsMethod = 1
TempMeltFactor
Description:

Hourly temperature melt factor of snow [mm K-1 h-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_Snow.txt MU Hourly temperature melt factor of snow [mm K-1 h-1] (In previous model version, this parameter was 0.12)
TH
Description:

Upper air temperature limit [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Upper air temperature limit [°C]
Theta+_K
Description:

potential temperature at the top of CBL [K]

Configuration:
Referencing Table Requirement Comment
CBL_initial_data.txt MU potential temperature at the top of CBL (K)
Theta_K
Description:

potential temperature in CBL [K]

Configuration:
Referencing Table Requirement Comment
CBL_initial_data.txt MU potential temperature in CBL (K)
Tiair
Description:

Indoor air temperature [˚C]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU Indoor air temperature [˚C]
Timezone
Description:

Time zone [h] for site relative to UTC (east is positive). This should be set according to the times given in the meteorological forcing file(s).

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Time zone [h] for site relative to UTC (east is positive). This should be set according to the times given in the meteorological forcing file(s).
TL
Description:

Lower air temperature limit [°C]

Configuration:
Referencing Table Requirement Comment
SUEWS_Conductance.txt MD Lower air temperature limit [°C]
ToBldgs
Description:

Fraction of water going to Bldgs

Configuration:
Referencing Table Requirement Comment
SUEWS_WithinGridWaterDist.txt MU Fraction of water going to Bldgs
ToBSoil
Description:

Fraction of water going to BSoil

Configuration:
Referencing Table Requirement Comment
SUEWS_WithinGridWaterDist.txt MU Fraction of water going to BSoil
ToDecTr
Description:

Fraction of water going to DecTr

Configuration:
Referencing Table Requirement Comment
SUEWS_WithinGridWaterDist.txt MU Fraction of water going to DecTr
ToEveTr
Description:

Fraction of water going to EveTr

Configuration:
Referencing Table Requirement Comment
SUEWS_WithinGridWaterDist.txt MU Fraction of water going to EveTr
ToGrass
Description:

Fraction of water going to Grass

Configuration:
Referencing Table Requirement Comment
SUEWS_WithinGridWaterDist.txt MU Fraction of water going to Grass
ToPaved
Description:

Fraction of water going to Paved

Configuration:
Referencing Table Requirement Comment
SUEWS_WithinGridWaterDist.txt MU Fraction of water going to Paved
ToRunoff
Description:

Fraction of water going to Runoff

Configuration:
Referencing Table Requirement Comment
SUEWS_WithinGridWaterDist.txt MU Fraction of water going to Runoff
ToSoilStore
Description:

Fraction of water going to SoilStore

Configuration:
Referencing Table Requirement Comment
SUEWS_WithinGridWaterDist.txt MU Fraction of water going to SoilStore
ToWater
Description:

Fraction of water going to Water

Configuration:
Referencing Table Requirement Comment
SUEWS_WithinGridWaterDist.txt MU Fraction of water going to Water
TraffProfWD
Description:

Code for traffic activity profile (weekdays) linking to Code of SUEWS_Profiles.txt. Not used in v2018a.

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O Weekday building energy use [W m-2] Can be used for CO2 flux calculation.
TraffProfWE
Description:

Code for traffic activity profile (weekends) linking to Code of SUEWS_Profiles.txt. Not used in v2018a.

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O Weekday building energy use [W m-2] Can be used for CO2 flux calculation.
TrafficUnits
Description:

Units for the traffic rate for the study area. Not used in v2018a.

Configuration:
Referencing Table Requirement Comment
SUEWS_AnthropogenicEmission.txt O Weekday building energy use [W m-2] Can be used for CO2 flux calculation.
TrafficRate_WD
Description:

Weekday traffic rate [veh km m-2 s-1] Can be used for CO2 flux calculation - not used in v2018a.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Weekday traffic rate [veh km m-2 s-1] Can be used for CO2 flux calculation.
TrafficRate_WE
Description:

Weekend traffic rate [veh km m-2 s-1] Can be used for CO2 flux calculation - not used in v2018a.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Weekend traffic rate [veh km m-2 s-1] Can be used for CO2 flux calculation.
Troad
Description:

Ground surface temperature [˚C] (used when TsurfChoice = 1 or 2)

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU Ground surface temperature [˚C] (used when TsurfChoice = 1 or 2)
Troof
Description:

Roof surface temperature [˚C] (used when TsurfChoice = 1 or 2)

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU Roof surface temperature [˚C] (used when TsurfChoice = 1 or 2)
Tsurf
Description:

Bulk surface temperature [˚C] (used when TsurfChoice = 0)

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU Bulk surface temperature [˚C] (used when TsurfCoice = 0)
Twall
Description:

Wall surface temperature [˚C] (used when TsurfChoice = 1)

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU Wall surface temperature [˚C] (used when TsurfChoice = 1)
Twall_e
Description:

East-facing wall surface temperature [˚C] (used when TsurfChoice = 2)

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU East-facing wall surface temperature [˚C] (used when TsurfChoice = 2)
Twall_n
Description:

North-facing wall surface temperature [˚C] (used when TsurfChoice = 2)

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU North-facing wall surface temperature [˚C] (used when TsurfChoice = 2)
Twall_s
Description:

South-facing wall surface temperature [˚C] (used when TsurfChoice = 2)

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU South-facing wall surface temperature [˚C] (used when TsurfChoice = 2)
Twall_w
Description:

West-facing wall surface temperature [˚C] (used when TsurfChoice = 2)

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_ESTM_Ts_data_tt.txt MU West-facing wall surface temperature [˚C] (used when TsurfChoice = 2)
U
Description:

Wind speed. [m s-1. ]Height of the wind speed measurement (z) is needed in SUEWS_SiteSelect.txt .

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt MU Height of the wind speed measurement (z) is needed in SUEWS_SiteSelect.txt.
Wall_k1
Description:

Thermal conductivity of the first layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Thermal conductivity of the first layer [W m-1 K-1]
Wall_k2
Description:

Thermal conductivity of the second layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the second layer [W m-1 K-1]
Wall_k3
Description:

Thermal conductivity of the third layer [W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the third layer [W m-1 K-1]
Wall_k4
Description:

Thermal conductivity of the fourth layer[W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the fourth layer[W m-1 K-1]
Wall_k5
Description:

Thermal conductivity of the fifth layer[W m-1 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thermal conductivity of the fifth layer[W m-1 K-1]
Wall_rhoCp1
Description:

Volumetric heat capacity of the first layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Volumetric heat capacity of the first layer [J m-3 K-1]
Wall_rhoCp2
Description:

Volumetric heat capacity of the second layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the second layer [J m-3 K-1]
Wall_rhoCp3
Description:

Volumetric heat capacity of the third layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the third layer [J m-3 K-1]
Wall_rhoCp4
Description:

Volumetric heat capacity of the fourth layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the fourth layer [J m-3 K-1]
Wall_rhoCp5
Description:

Volumetric heat capacity of the fifth layer [J m-3 K-1]

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Volumetric heat capacity of the fifth layer [J m-3 K-1]
Wall_thick1
Description:

Thickness of the first layer [m] for building surfaces only; set to -999 for all other surfaces

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt MU Thickness of the first layer [m] for building surfaces only; set to -999 for all other surfaces
Wall_thick2
Description:

Thickness of the second layer [m] (if no second layer, set to -999.)

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the second layer [m] (if no second layer, set to -999.)
Wall_thick3
Description:

Thickness of the third layer [m] (if no third layer, set to -999.)

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the third layer [m] (if no third layer, set to -999.)
Wall_thick4
Description:

Thickness of the fourth layer [m] (if no fourth layer, set to -999.)

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the fourth layer [m] (if no fourth layer, set to -999.)
Wall_thick5
Description:

Thickness of the fifth layer [m] (if no fifth layer, set to -999.)

Configuration:
Referencing Table Requirement Comment
SUEWS_ESTMCoefficients.txt O Thickness of the fifth layer [m] (if no fifth layer, set to -999.)
WaterDepth
Description:

Water depth [mm].

Configuration:
Referencing Table Requirement Comment
SUEWS_Water.txt MU Set to a large value (e.g. 20000 mm = 20 m) if the water body is substantial (lake, river, etc) or a small value (e.g. 10 mm) if water bodies are very shallow (e.g. fountains). This value must not exceed StateLimit (column 8).
WaterUseProfAutoWD
Description:

Code for water use profile (automatic irrigation, weekdays) linking to Code of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in Code of SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for water use profile (automatic irrigation, weekdays) Provides the link to column 1 of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt.
WaterUseProfAutoWE
Description:

Code for water use profile (automatic irrigation, weekends) linking to Code of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in Code of SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for water use profile (automatic irrigation, weekends) Provides the link to column 1 of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt.
WaterUseProfManuWD
Description:

Code for water use profile (manual irrigation, weekdays) linking to Code of SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for water use profile (manual irrigation, weekdays) Provides the link to column 1 of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt.
WaterUseProfManuWE
Description:

Code for water use profile (manual irrigation, weekends) linking to Code of SUEWS_Profiles.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code for water use profile (manual irrigation, weekends) Provides the link to column 1 of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt.
wdir
Description:

Wind direction [deg].

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Not available in this version.
WetThreshold
Description:

Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface [mm].

Configuration:
Referencing Table Requirement Comment
SUEWS_NonVeg.txt MD

Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface.

Example values:

  • 0.6 Paved
  • 0.6 Bldgs
    1. BSoil
SUEWS_Veg.txt MD

Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface.

Example values:

  • 1.8 EveTr
    1. DecTr
    1. Grass
SUEWS_Water.txt MD

Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface.

Example values:

  • 0.5 Water
WithinGridBldgsCode
Description:

Code that links to the fraction of water that flows from Bldgs surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code that links to the fraction of water that flows from Bldgs surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_WithinGridWaterDist.txt.
WithinGridBSoilCode
Description:

Code that links to the fraction of water that flows from BSoil surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code that links to the fraction of water that flows from BSoil surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_WithinGridWaterDist.txt.
WithinGridDecTrCode
Description:

Code that links to the fraction of water that flows from DecTr surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code that links to the fraction of water that flows from DecTr surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_WithinGridWaterDist.txt.
WithinGridEveTrCode
Description:

Code that links to the fraction of water that flows from EveTr surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code that links to the fraction of water that flows from EveTr surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_WithinGridWaterDist.txt.
WithinGridGrassCode
Description:

Code that links to the fraction of water that flows from Grass surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code that links to the fraction of water that flows from Grass surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_WithinGridWaterDist.txt.
WithinGridPavedCode
Description:

Code that links to the fraction of water that flows from Paved surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code that links to the fraction of water that flows from Paved surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_WithinGridWaterDist.txt.
WithinGridWaterCode
Description:

Code that links to the fraction of water that flows from Water surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt.

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt L Code that links to the fraction of water that flows from Water surfaces to surfaces in columns 2-10 of SUEWS_WithinGridWaterDist.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_WithinGridWaterDist.txt.
Wuh
Description:

External water use [m3]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O External water use [ m3]
xsmd
Description:

Observed soil moisture [m3 m-3 or kg kg-1]

Configuration:
Referencing Table Requirement Comment
SSss_YYYY_data_tt.txt O Observed soil moisture [ m3 m-3 or kg kg-1]
Year
Description:

Year [YYYY]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU Year [YYYY] Years must be continuous. If running multiple years, ensure the rows in SUEWS_SiteSelect.txt are arranged so that all grids for a particular year appear on consecutive lines (rather than grouping all years together for a particular grid).
z
Description:

Measurement height [m].

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt MU z must be greater than the displacement height. Forcing data should be representative of the local-scale, i.e. above the height of the roughness elements.
z0
Description:

Roughness length for momentum [m]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Value supplied here is used if RoughLenMomMethod = 1 in RunControl.nml ; otherwise set to ‘-999’ and a value will be calculated by the model (RoughLenMomMethod = 2, 3).
zd
Description:

Zero-plane displacement [m]

Configuration:
Referencing Table Requirement Comment
SUEWS_SiteSelect.txt O Value supplied here is used if RoughLenMomMethod = 1 in RunControl.nml ; otherwise set to ‘-999’ and a value will be calculated by the model (RoughLenMomMethod = 2, 3).
zi0
Description:

initial convective boundary layer height (m)

Configuration:
Referencing Table Requirement Comment
CBL_initial_data.txt MU initial convective boundary layer height [m]

Note

Please report issues with the manual on the GitHub page.

Typical Values

Other values to add - please let us know

Generic Properties
Property General Type Value Description Reference
Albedo Non Vegetated 0.09 Paved Helsinki Järvi et al. (2014)
Albedo Non Vegetated 0.15 Buildings Helsinki Järvi et al. (2014)
Albedo Non Vegetated 0.19 Bare Soil, Helsinki Järvi et al. (2014)
Albedo Non Vegetated 0.12 Paved Oke (1987)
Albedo Non Vegetated 0.15 Buildings Oke (1987)
Albedo Non Vegetated 0.21 Bare Soil Oke (1987)
Emissivity Non Vegetated 0.95 Paved Oke (1987)
Emissivity Non Vegetated 0.91 Buildings Oke (1987)
Emissivity Non Vegetated 0.93 Bare Soil Oke (1987)
Surface Water storage capacity Non Vegetated 0.48 Paved Davies and Hollis (1981)
Surface Water storage capacity Non Vegetated 0.25 Buildings Falk and Niemczynowicz (1978)
Albedo Vegetation 0.10 EveTr  
Albedo Vegetation 0.12 DecTr  
Albedo Vegetation 0.18 Grass  
Albedo Vegetated 0.10 EveTr Helsinki Järvi et al. (2014)
Albedo Vegetated 0.16 DecTr Helsinki Järvi et al. (2014)
Albedo Vegetated 0.19 Grass Helsinki Järvi et al. (2014)
Albedo Vegetated 0.10 EveTr Oke (1987)
Albedo Vegetated 0.18 DecTr Oke (1987)
Albedo Vegetated 0.21 Grass Oke (1987)
Emissivity Vegetated 0.98 EveTr Oke (1987)
Emissivity Vegetated 0.98 DecTr Oke (1987)
Emissivity Vegetated 0.93 Grass Oke (1987)
water Storage Minimum capacity (mm) Vegetated 1.3 EveTr Breuer et al. (2003)
water Storage Minimum capacity (mm) Vegetated 0.3 DecTr Breuer et al. (2003)
water Storage Minimum capacity (mm) Vegetated 1.9 Grass Breuer et al. (2003)
Maximum water storage capacity of this surface [mm] Vegetated 1.3 EveTr Breuer et al. (2003)
Maximum water storage capacity of this surface [mm] Vegetated 0.8 DecTr Grimmond and Oke (1991)
Maximum water storage capacity of this surface [mm] Vegetated 1.9 Grass Breuer et al. (2003)
Albedo Max(leaf on) Vegetated 0.12 DecTr  
Albedo Max(leaf on) Vegetated 0.18 Grass  
Albedo Max(leaf on) Vegetated 0.10 EveTr Helsinki Järvi et al. (2014)
Albedo Max(leaf on) Vegetated 0.16 DecTr Helsinki Järvi et al. (2014)
Albedo Max(leaf on) Vegetated 0.19 Grass Helsinki Järvi et al. (2014)
Albedo Max(leaf on) Vegetated 0.10 EveTr Oke (1987)
Albedo Max(leaf on) Vegetated 0.18 DecTr Oke (1987)
Albedo Max(leaf on) Vegetated 0.21 Grass Oke (1987)
Emissivity *View factors should be taken into account Vegetated 0.98 EveTr Oke (1987)
Emissivity *View factors should be taken into account Vegetated 0.98 DecTr Oke (1987)
Emissivity *View factors should be taken into account Vegetated 0.93 Grass Oke (1987)
Minimum water storage capacity of this surface [mm] *Min & max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces). Vegetated 1.3 EveTr Breuer et al. (2003)
Minimum water storage capacity of this surface [mm]*Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces). Vegetated 0.3 DecTr Breuer et al. (2003)
Minimum water storage capacity of this surface [mm] *Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces). Vegetated 1.9 Grass Breuer et al. (2003)
Maximum water storage capacity of this surface [mm] *Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces) Vegetated 1.3 EveTr Breuer et al. (2003)
Maximum water storage capacity of this surface [mm] *Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces) Vegetated 0.8 DecTr Grimmond and Oke (1991)
Maximum water storage capacity of this surface [mm] *Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces) Vegetated 1.9 Grass Breuer et al. (2003)
AlbedoMin Water 0.1 Water Oke (1987)
AlbedoMax Water 0.1 Water Oke (1987)
Emissivity Water 0.95 Water Oke (1987)
Minimum water storage capacity of this surface [mm] Water 0.5 Water  
Maximum water storage capacity for upper surfaces (i.e. canopy) Water 0.5 Water  
WetThreshold water 0.5 Water  
StateLimit *Upper limit to the surface state [mm] *State cannot exceed this value. *Set to a large value (e.g. 20000 mm = 20 m) if the water body is substantial (lake| river| etc) or a small value (e.g. 10 mm) if water bodies are very shallow (e.g. fountains). Water 20000 Water  
RadMeltFactor Snow 0.0016 Hourly radiation melt factor of snow [mm W-1 h-1]  
TempMeltFactor Snow 0.12 Hourly temperature melt factor of snow [mm °C -1 h-1]  
AlbedoMin Snow 0-1 Minimum snow albedo [-] - 0.18 Järvi et al. (2014)
AlbedoMax *Maximum snow albedo (fresh snow) [-] Snow 0.85   Järvi et al. (2014)
Emissivity *Effective surface emissivity. *View factors should be taken into account Snow 0.99 Snow Järvi et al. (2014)
tau_a *Time constant for snow albedo aging in cold snow [-] Snow 0.018   Järvi et al. (2014)
tau_f *Time constant for snow albedo aging in melting snow [-] Snow 0.11   Järvi et al. (2014)
PrecipiLimAlb Snow 2 Limit for hourly precipitation when the ground is fully covered with snow. Then snow albedo is reset to AlbedoMax [mm]  
snowDensMin Snow 100 Fresh snow density [kg m-3]  
snowDensMax Snow 400 Maximum snow density [kg m-3]  
tau_r *Time constant for snow density ageing [-] Snow 0.043   Järvi et al. (2014)
CRWMin *Minimum water holding capacity of snow [mm] Snow 0.05   Järvi et al. (2014)
CRWMax *Maximum water holding capacity of snow [mm] Snow 0.20   Järvi et al. (2014)
PrecipLimSnow Snow 2.2 Temperature limit when precipitation falls as snow [°C] Auer (1974) [Au74]
SoilDepth Snow 350 Depth of sub-surface soil store [mm] *depth of soil beneath the surface  
SoilStoreCap Soil 150
  • Capacity of sub-surface soil store [mm]
  • how much water can be stored in the sub-surface soil when at maximum capacity.
  • (SoilStoreCap must not be greater than SoilDepth.)
 
SatHydraulicCond Soil 0.0005 Hydraulic conductivity for saturated soil [mm s-1]  
SoilDensity Soil 1.16 Soil density [kg m-3]  
InfiltrationRate Soil   Infiltration rate [mm h-1]  
OBS_SMDepth Soil   Depth of soil moisture measurements [mm]  
OBS_SMCap Soil   Maxiumum observed soil moisture [m3 m-3 or kg kg-1]  
OBS_SoilNotRocks Soil   Fraction of soil without rocks [-]  

The above text files (used to be stored as worksheets in SUEWS_SiteInfo.xlsm for versions prior to v2018a) can be edited directly (see Data Entry). Please note this file is subject to possible changes from version to version due to new features, modifications, etc. Please be aware of using the correct copy of this worksheet that are always shipped with the SUEWS public release.

Tip

See SUEWS input converter for conversion of input file between different versions.

Note

Please report issues with the manual on the GitHub page.

Initial Conditions file

To start the model, information about the conditions at the start of the run is required. This information is provided in initial conditions file. One file can be specified for each grid (MultipleInitFiles=1 in RunControl.nml, filename includes grid number) or, alternatively, a single file can be specified for all grids (MultipleInitFiles=0 in RunControl.nml, no grid number in the filename). After that, a new InitialConditionsSSss_YYYY.nml file will be written for each grid for the following years. It is recommended that you look at these files (written to the input directory) to check the status of various surfaces at the end or the run. This may help you get more realistic starting values if you are uncertain what they should be. Note this file will be created for each year for multiyear runs for each grid. If the run finishes before the end of the year the InitialConditions file is still written and the file name is appended with ‘_EndofRun’.

A sample file of InitialConditionsSSss_YYYY.nml looks like

&InitialConditions
LeavesOutInitially=0
SoilstorePavedState=150
SoilstoreBldgsState=150
SoilstoreEveTrstate=150
SoilstoreDecTrState=150
SoilstoreGrassState=150
SoilstoreBSoilState=150
BoInit=10
/

The two most important pieces of information in the initial conditions file is the soil moisture and state of vegetation at the start of the run. This is the minimal information required; other information can be provided if known, otherwise SUEWS will make an estimate of initial conditions.

The parameters and their setting instructions are provided through the links below:

Note

Variables can be in any order

Note

Please report issues with the manual on the GitHub page.

Soil moisture states

SoilstorePavedState
Requirement:Required
Description:Initial water stored in soil beneath Paved surface [mm]
Configuration:For maximum values, see the used soil code in SUEWS_Soil.txt
SoilstoreBldgsState
Requirement:Required
Description:Initial water stored in soil beneath Bldgs surface [mm]
Configuration:For maximum values, see the used soil code in SUEWS_Soil.txt
SoilstoreEveTrState
Requirement:Required
Description:Initial water stored in soil beneath EveTr surface [mm]
Configuration:For maximum values, see the used soil code in SUEWS_Soil.txt
SoilstoreDecTrState
Requirement:Required
Description:Initial water stored in soil beneath DecTr surface [mm]
Configuration:For maximum values, see the used soil code in SUEWS_Soil.txt
SoilstoreGrassState
Requirement:Required
Description:Initial water stored in soil beneath Grass surface [mm]
Configuration:For maximum values, see the used soil code in SUEWS_Soil.txt
SoilstoreBSoilState
Requirement:Required
Description:Initial water stored in soil beneath BSoil surface [mm]
Configuration:For maximum values, see the used soil code in SUEWS_Soil.txt

Note

Please report issues with the manual on the GitHub page.

Vegetation parameters

LeavesOutInitially
Requirement:Optional
Description:Flag for initial leave status [1 or 0]
Configuration:If the model run starts in winter when trees are bare, set LeavesOutInitially = 0 and the vegetation parameters will be set accordingly based on the values set in SUEWS_SiteInfo.xlsm. If the model run starts in summer when leaves are fully out, set LeavesOutInitially = 1 and the vegetation parameters will be set accordingly based on the values set in SUEWS_SiteInfo.xlsm. Not LeavesOutInitially can only be set to 0, 1 or -999 (fractional values cannot be used to indicate partial leaf-out). The value of LeavesOutInitially overrides any values provided for the individual vegetation parameters. To prevent LeavesOutInitially from setting the initial conditions, either omit it from the namelist or set to -999. If values are provided individually, they should be consistent the information provided in SUEWS_Veg.txt and the time of year. If values are provided individually, values for all required surfaces must be provided (i.e. specifying only albGrass0 but not albDecTr0 nor albEveTr0 is not permitted).
GDD_1_0
Requirement:Optional
Description:GDD related initial value
Configuration:Cannot be negative. If leaves are already full, then this should be the same as GDDFull in SUEWS_Veg.txt. If winter, set to 0. It is important that the vegetation characteristics are set correctly (i.e. for the start of the run in summer/winter).
GDD_2_0
Requirement:Optional
Description:GDD related initial value
Configuration:Cannot be positive If the leaves are full but in early/mid summer then set to 0. If late summer or autumn , this should be a negative value. If leaves are off , then use the values of SDDFull in SUEWS_Veg.txt to guide your minimum value. It is important that the vegetation characteristics are set correctly (i.e. for the start of the run in summer/winter).
LAIinitialEveTr
Requirement:Optional
Description:Initial LAI for evergreen trees EveTr.
Configuration:The recommended values can be found from SUEWS_Veg.txt
LAIinitialDecTr
Requirement:Optional
Description:Initial LAI for deciduous trees DecTr.
Configuration:The recommended values can be found from SUEWS_Veg.txt
LAIinitialGrass
Requirement:Optional
Description:Initial LAI for irrigated grass Grass.
Configuration:The recommended values can be found from SUEWS_Veg.txt
albEveTr0
Requirement:Optional
Description:Albedo of evergreen surface EveTr on day 0 of run
Configuration:The recommended values can be found from SUEWS_Veg.txt
albDecTr0
Requirement:Optional
Description:Albedo of deciduous surface DecTr on day 0 of run
Configuration:The recommended values can be found from SUEWS_Veg.txt
albGrass0
Requirement:Optional
Description:Albedo of grass surface Grass on day 0 of run
Configuration:The recommended values can be found from SUEWS_Veg.txt
decidCap0
Requirement:Optional
Description:Storage capacity of deciduous surface DecTr on day 0 of run.
Configuration:The recommended values can be found from SUEWS_Veg.txt
porosity0
Requirement:Optional
Description:Porosity of deciduous vegetation on day 0 of run.
Configuration:This varies between 0.2 (leaf-on) and 0.6 (leaf-off). The recommended values can be found from SUEWS_Veg.txt

Note

Please report issues with the manual on the GitHub page.

Recent meteorology

DaysSinceRain
Requirement:Optional
Description:Days since rain [d]
Configuration:Important to use correct value if starting in summer season If starting when external water use is not occurring it will be reset with the first rain so can just be set to 0. If unknown, SUEWS sets to zero by default. Used to model irrigation.
Temp_C0
Requirement:Optional
Description:Initial air temperature [degC]
Configuration:If unknown, SUEWS uses the mean temperature for the first day of the run.

Note

Please report issues with the manual on the GitHub page.

Above ground state

PavedState
Requirement:Optional
Description:Initial wetness condition on Paved
Configuration:If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
BldgsState
Requirement:Optional
Description:Initial wetness condition on Bldgs
Configuration:If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
EveTrState
Requirement:Optional
Description:Initial wetness condition on EveTr
Configuration:If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
DecTrState
Requirement:Optional
Description:Initial wetness condition on DecTr
Configuration:If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
GrassState
Requirement:Optional
Description:Initial wetness condition on Grass
Configuration:If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
BSoilState
Requirement:Optional
Description:Initial wetness condition on BSoil
Configuration:If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
WaterState
Requirement:Optional
Description:Initial wetness condition on Water
Configuration:For a large water body (e.g. river, sea, lake) set WaterState to a large value, e.g. 20000 mm; for small water bodies (e.g. ponds, fountains) set WaterState to smaller value, e.g. 1000 mm. This value must not exceed StateLimit specified in SUEWS_Water.txt . If unknown, model uses value of WaterDepth specified in SUEWS_Water.txt .

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

Meteorological Input File

SUEWS is designed to run using commonly measured meteorological variables.

  • Required inputs must be continuous – i.e. gap fill any missing data.

  • Temporal information (i.e., iyidit and imin should be in local time.

  • The table below gives the must-use (MU) and optional (O) additional input variables.

  • If an optional input variable is not available or will not be used by the model, enter ‘-999.0’ for this column.

  • Since v2017a forcing files no longer need to end with two rows containing ‘-9’ in the first column.

  • One single meteorological file can be used for all grids (MultipleMetFiles=0 in RunControl.nml, no grid number in file name) if appropriate for the study area, or

  • separate met files can be used for each grid if data are available (MultipleMetFiles=1 in RunControl.nml, filename includes grid number).

  • The meteorological forcing file names should be appended with the temporal resolution in minutes (SS_YYYY_data_tt.txt, or SSss_YYYY_data_tt.txt for multiple grids).

  • Separate met forcing files should be provided for each year.

  • Files do not need to start/end at the start/end of the year, but they must contain a whole number of days.

  • The meteorological input file should match the information given in SUEWS_SiteSelect.txt.

  • If a partial year is used that specific year must be given in SUEWS_SiteSelect.txt.

  • If multiple years are used, all years should be included in SUEWS_SiteSelect.txt.

  • If a whole year (e.g. 2011) is intended to be modelled using and hourly resolution dataset, the number of lines in the met data file should be 8760 and begin and end with:

    iy     id  it  imin
    2011   1   1   0 …
    …
    2012   1   0   0 …
    

SSss_YYYY_data_tt.txt

Main meteorological data file.

No. Use Column Name Description
1 MU iy Year [YYYY]
2 MU id Day of year [DOY]
3 MU it Hour [H]
4 MU imin Minute [M]
5 O qn Net all-wave radiation [W m-2] Required if NetRadiationMethod = 0.
6 O qh Sensible heat flux [W m-2]
7 O qe Latent heat flux [W m-2]
8 O qs Storage heat flux [W m-2]
9 O qf Anthropogenic heat flux [W m-2]
10 MU U Wind speed [m s-1] Height of the wind speed measurement (z) is needed in SUEWS_SiteSelect.txt.
11 MU RH Relative Humidity [%]
12 MU Tair Air temperature [°C]
13 MU pres Barometric pressure [kPa]
14 MU rain Rainfall [mm]
15 MU kdown Incoming shortwave radiation [W m-2] Must be > 0 W m-2.
16 O snow Snow cover fraction (0 – 1) [-] Required if SnowUse = 1
17 O ldown Incoming longwave radiation [W m-2]
18 O fcld Cloud fraction [tenths]
19 O Wuh External water use [m3]
20 O xsmd Observed soil moisture [m3 m-3] or [kg kg-1]
21 O lai Observed leaf area index [m-2 m-2]
22 O kdiff Diffuse radiation [W m-2] Recommended in this version. if SOLWEIGUse = 1
23 O kdir Direct radiation [W m-2] Recommended in this version. if SOLWEIGUse = 1
24 O wdir Wind direction [°] Not available in this version.

Note

Please report issues with the manual on the GitHub page.

CBL input files

Main references for this part of the model: Onomura et al. (2015) [Shiho2015] and Cleugh and Grimmond (2001) [CG2001].

If CBL slab model is used (CBLuse = 1 in RunControl.nml) the following files are needed.

Filename Purpose
CBL_initial_data.txt Gives initial data every morning * when CBL slab model starts running. * filename must match the InitialData_FileName in CBLInput.nml * fixed formats.
CBLInput.nml Specifies run options, parameters and input file names. * Can be in any order

CBL_initial_data.txt

This file should give initial data every morning when CBL slab model starts running. The file name should match the InitialData_FileName in CBLInput.nml.

Definitions and example file of initial values prepared for Sacramento.

No. Column name Description
1 id Day of year [DOY]
2 zi0 Initial convective boundary layer height (m)
3 gamt_Km Vertical gradient of potential temperature (K m-1) strength of the inversion
4 gamq_gkgm Vertical gradient of specific humidity (g kg-1 m-1)
5 Theta+_K Potential temperature at the top of CBL (K)
6 q+_gkg Specific humidity at the top of CBL (g kg-1)
7 Theta_K Potential temperature in CBL (K)
8 q_gkg Specific humidiy in CBL (g kg-1)
  • gamt_Km and gamq_gkgm written to two significant figures are required for the model performance in appropriate ranges [Shiho2015].
id zi0 gamt_Km gamq_gkgm Theta+_K q+_gkg theta_K q_gkg
234 188 0.0032 0.00082 290.4 9.6 288.7 8.3
235 197 0.0089 0.089 290.2 8.4 288.3 8.7
               

CBLInput.nml

sample file of CBLInput.nml looks like
&CBLInput
EntrainmentType=1       ! 1.Tennekes and Driedonks(1981), 2.McNaughton and Springgs(1986), 3.Rayner and Watson(1991),4.Tennekes(1973),
QH_choice=1             ! 1.suews  2.lumps 3.obs
CO2_included=0
cblday(236)=1
cblday(258)=1
cblday(259)=1
cblday(260)=1
cblday(285)=1
cblday(297)=1
wsb=-0.01  
InitialData_use=1
InitialDataFileName='CBLinputfiles/CBL_initial_data.txt'
sondeflag=0
FileSonde(234)='CBLinputfiles\Sonde_Sc_1991_0822_0650.txt'
FileSonde(235)='CBLinputfiles\Sonde_Sc_1991_0823_0715.txt'
FileSonde(236)='CBLinputfiles\Sonde_Sc_1991_0824_0647.txt'
FileSonde(238)='CBLinputfiles\Sonde_Sc_1991_0826_0642.txt'
FileSonde(239)='CBLinputfiles\Sonde_Sc_1991_0827_0640.txt'
FileSonde(240)='CBLinputfiles\Sonde_Sc_1991_0828_0640.txt'
/

Note

The file contents can be in any order.

The parameters and their setting instructions are provided through the links below:

Note

Please report issues with the manual on the GitHub page.

CBLinput
EntrainmentType
Requirement:

Required

Description:

Determines entrainment scheme. See Cleugh and Grimmond 2000 [16] for details.

Configuration:
Value Comments
1 Tennekes and Driedonks (1981) - Recommended in this version.
2 McNaughton and Springs (1986)
3 Rayner and Watson (1991)
4 Tennekes (1973)
QH_Choice
Requirement:

Required

Description:

Determines QH used for CBL model.

Configuration:
Value Comments
1 QH modelled by SUEWS
2 QH modelled by LUMPS
3 Observed QH values are used from the meteorological input file
InitialData_use
Requirement:

Required

Description:

Determines initial values (see CBL_initial_data.txt)

Configuration:
Value Comments
0 All initial values are calculated. Not available in this version.
1 Take zi0, gamt_Km and gamq_gkgm from input data file. Theta+_K, q+_gkg, Theta_K and q_gkg are calculated using Temp_C, avrh and Pres_kPa in meteorological input file.
2 Take all initial values from input data file (see CBL_Initial_data.txt).
Sondeflag
Requirement:

Required

Description:

to fill

Configuration:
Value Comments
0 Does not read radiosonde vertical profile data - Recommended in this version.
1 Reads radiosonde vertical profile data
CBLday(id)
Requirement:Required
Description:Set CBLday(id) = 1 If CBL model is set to run for DOY 175–177, CBLday(175) = 1, CBLday(176) = 1, CBLday(177) = 1
Configuration:to fill
CO2_included
Requirement:Required
Description:Set to zero in current version
Configuration:to fill
FileSonde(id)
Requirement:Required
Description:If Sondeflag=1, write the file name including the path from site directory e.g. FileSonde(id)= ‘CBLinputfilesXXX.txt’, XXX is an arbitrary name.
Configuration:to fill
InitialDataFileName
Requirement:Required
Description:If InitialData_use ≥ 1, write the file name including the path from site directory e.g. InitialDataFileName=’CBLinputfilesCBL_initial_data.txt’
Configuration:to fill
Wsb
Requirement:Required
Description:Subsidence velocity (m s-1 ) in eq. 1 and 2 of Onomura et al. (2015) [17] . (-0.01 m s-1 Recommended in this version.)
Configuration:to fill

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

SUEWS input converter

SUEWS input converter is a Python 3 script to convert input files between different versions based on pre-defined rules.

How to use

Download the converter script and rule.csv below, and specify these arguments in the script:

  1. fromVer: which version to convert from.
  2. toVer: which version to convert to.
  3. fromDir: where the input files are located.
  4. toDir: where the converted files are produced.

Downloads

Description of rules

The converter currently picks up the following types of actions:

  1. Add: New entries or files to be added with default values.
  2. Rename: Entries to be renamed from one version to another.
  3. Delete: Entries to be deleted from one version to another.

Note

For entries introduced in a version via a new file, the new file will be created to hold the new entries without extra delaration for new files.

The current available rules are listed below:

From To Action File Variable Column Value
2017a 2018a Delete RunControl.nml anthropco2method -999 -999
2017a 2018a Rename RunControl.nml AnthropHeatMethod -999 EmissionsMethod
2017a 2018a Add SUEWS_AnthropogenicHeat.txt AHMin_WD 9 15
2017a 2018a Add SUEWS_AnthropogenicHeat.txt AHMin_WE 10 15
2017a 2018a Add SUEWS_AnthropogenicHeat.txt AHSlope_Heating_WD 11 2.7
2017a 2018a Add SUEWS_AnthropogenicHeat.txt AHSlope_Heating_WE 12 2.7
2017a 2018a Add SUEWS_AnthropogenicHeat.txt AHSlope_Cooling_WD 13 2.7
2017a 2018a Add SUEWS_AnthropogenicHeat.txt AHSlope_Cooling_WE 14 2.7
2017a 2018a Add SUEWS_AnthropogenicHeat.txt TCritic_Heating_WD 15 7
2017a 2018a Add SUEWS_AnthropogenicHeat.txt TCritic_Heating_WE 16 7
2017a 2018a Add SUEWS_AnthropogenicHeat.txt TCritic_Cooling_WD 17 7
2017a 2018a Add SUEWS_AnthropogenicHeat.txt TCritic_Cooling_WE 18 7
2017a 2018a Add SUEWS_AnthropogenicHeat.txt EnergyUseProfWD 19 44
2017a 2018a Add SUEWS_AnthropogenicHeat.txt EnergyUseProfWE 20 45
2017a 2018a Add SUEWS_AnthropogenicHeat.txt ActivityProfWD 21 55663
2017a 2018a Add SUEWS_AnthropogenicHeat.txt ActivityProfWE 22 55664
2017a 2018a Add SUEWS_AnthropogenicHeat.txt TraffProfWD 23 701
2017a 2018a Add SUEWS_AnthropogenicHeat.txt TraffProfWE 24 702
2017a 2018a Add SUEWS_AnthropogenicHeat.txt PopProfWD 25 801
2017a 2018a Add SUEWS_AnthropogenicHeat.txt PopProfWE 26 802
2017a 2018a Add SUEWS_AnthropogenicHeat.txt MinQFMetab 27 75
2017a 2018a Add SUEWS_AnthropogenicHeat.txt MaxQFMetab 28 175
2017a 2018a Add SUEWS_AnthropogenicHeat.txt FrFossilFuel_Heat 29 0.05
2017a 2018a Add SUEWS_AnthropogenicHeat.txt FrFossilFuel_NonHeat 30 0
2017a 2018a Add SUEWS_AnthropogenicHeat.txt EF_umolCO2perJ 31 1.159
2017a 2018a Add SUEWS_AnthropogenicHeat.txt EnEF_v_Jkm 32 3.97E+06
2017a 2018a Add SUEWS_AnthropogenicHeat.txt FcEF_v_kgkm 33 0.285
2017a 2018a Add SUEWS_AnthropogenicHeat.txt TrafficUnits 34 1
2017a 2018a Add SUEWS_AnthropogenicHeat.txt EnergyUseProfWD 19 -999
2017a 2018a Add SUEWS_AnthropogenicHeat.txt EnergyUseProfWE 20 -999
2017a 2018a Add SUEWS_AnthropogenicHeat.txt ActivityProfWD 21 -999
2017a 2018a Add SUEWS_AnthropogenicHeat.txt ActivityProfWE 22 -999
2017a 2018a Delete SUEWS_AnthropogenicHeat.txt AHMin -999 -999
2017a 2018a Delete SUEWS_AnthropogenicHeat.txt AHSlope -999 -999
2017a 2018a Delete SUEWS_AnthropogenicHeat.txt TCritic -999 -999
2017a 2018a Rename SUEWS_AnthropogenicHeat.txt QF_A_Weekday -999 QF_A_WD
2017a 2018a Rename SUEWS_AnthropogenicHeat.txt QF_B_Weekday -999 QF_B_WD
2017a 2018a Rename SUEWS_AnthropogenicHeat.txt QF_C_Weekday -999 QF_C_WD
2017a 2018a Rename SUEWS_AnthropogenicHeat.txt QF_A_Weekend -999 QF_A_WE
2017a 2018a Rename SUEWS_AnthropogenicHeat.txt QF_B_Weekend -999 QF_B_WE
2017a 2018a Rename SUEWS_AnthropogenicHeat.txt QF_C_Weekend -999 QF_C_WE
2017a 2018a Add SUEWS_BiogenCO2.txt Code 1 31
2017a 2018a Add SUEWS_BiogenCO2.txt alpha 2 0.004
2017a 2018a Add SUEWS_BiogenCO2.txt beta 3 8.747
2017a 2018a Add SUEWS_BiogenCO2.txt theta 4 0.96
2017a 2018a Add SUEWS_BiogenCO2.txt alpha_enh 5 0.016
2017a 2018a Add SUEWS_BiogenCO2.txt beta_enh 6 33.353
2017a 2018a Add SUEWS_BiogenCO2.txt resp_a 7 2.43
2017a 2018a Add SUEWS_BiogenCO2.txt resp_b 8 0
2017a 2018a Add SUEWS_BiogenCO2.txt min_respi 9 0.6
2017a 2018a Delete SUEWS_SiteSelect.txt TrafficRate -999 -999
2017a 2018a Delete SUEWS_SiteSelect.txt BuildEnergyUse -999 -999
2017a 2018a Delete SUEWS_SiteSelect.txt EnergyUseProfWD -999 -999
2017a 2018a Delete SUEWS_SiteSelect.txt EnergyUseProfWE -999 -999
2017a 2018a Delete SUEWS_SiteSelect.txt ActivityProfWD -999 -999
2017a 2018a Delete SUEWS_SiteSelect.txt ActivityProfWE -999 -999
2017a 2018a Add SUEWS_SiteSelect.txt TrafficRate_WD 34 0.01
2017a 2018a Add SUEWS_SiteSelect.txt TrafficRate_WE 35 0.01
2017a 2018a Add SUEWS_SiteSelect.txt QF0_BEU_WD 36 0.88
2017a 2018a Add SUEWS_SiteSelect.txt QF0_BEU_WE 37 0.88
2017a 2018a Add SUEWS_Veg.txt BiogenCO2Code 38 31
2016a 2017a Add SUEWS_Conductance.txt gsModel 13 1
2016a 2017a Add SUEWS_NonVeg.txt OHMThresh_SW 19 10
2016a 2017a Add SUEWS_NonVeg.txt OHMThresh_WD 20 0.9
2016a 2017a Add SUEWS_NonVeg.txt ESTMCode 21 806
2016a 2017a Add SUEWS_NonVeg.txt AnOHM_Cp 22 20000000
2016a 2017a Add SUEWS_NonVeg.txt AnOHM_Kk 23 1.2
2016a 2017a Add SUEWS_NonVeg.txt AnOHM_Ch 24 4
2016a 2017a Add SUEWS_Snow.txt OHMThresh_SW 20 10
2016a 2017a Add SUEWS_Snow.txt OHMThresh_WD 21 0.9
2016a 2017a Add SUEWS_Snow.txt ESTMCode 22 61
2016a 2017a Add SUEWS_Snow.txt AnOHM_Cp 23 100000
2016a 2017a Add SUEWS_Snow.txt AnOHM_Kk 24 1.2
2016a 2017a Add SUEWS_Snow.txt AnOHM_Ch 25 4
2016a 2017a Add SUEWS_Water.txt WaterDepth 9 0
2016a 2017a Add SUEWS_Water.txt OHMThresh_SW 17 10
2016a 2017a Add SUEWS_Water.txt OHMThresh_WD 18 0.9
2016a 2017a Add SUEWS_Water.txt ESTMCode 19 60
2016a 2017a Add SUEWS_Water.txt AnOHM_Cp 20 100000
2016a 2017a Add SUEWS_Water.txt AnOHM_Kk 21 1.2
2016a 2017a Add SUEWS_Water.txt AnOHM_Ch 22 4
2016a 2017a Add SUEWS_Veg.txt PorosityMin 20 -999
2016a 2017a Add SUEWS_Veg.txt PorosityMax 21 -999
2016a 2017a Add SUEWS_Veg.txt OHMThresh_SW 32 10
2016a 2017a Add SUEWS_Veg.txt OHMThresh_WD 33 0.9
2016a 2017a Add SUEWS_Veg.txt ESTMCode 34 200
2016a 2017a Add SUEWS_Veg.txt AnOHM_Cp 35 100000
2016a 2017a Add SUEWS_Veg.txt AnOHM_Kk 36 1.2
2016a 2017a Add SUEWS_Veg.txt AnOHM_Ch 37 4
2016a 2017a Add SUEWS_ESTMCoefficients.txt Code 1 800
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_thick1 2 0.1
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_k1 3 0.74
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_rhoCp1 4 1500000
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_thick2 5 0.1
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_k2 6 0.93
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_rhoCp2 7 1500000
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_thick3 8 0.05
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_k3 9 0.06
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_rhoCp3 10 70000
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_thick4 11 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_k4 12 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_rhoCp4 13 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_thick5 14 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_k5 15 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Surf_rhoCp5 16 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_thick1 17 0.1
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_k1 18 1
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_rhoCp1 19 1600000
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_thick2 20 0.1
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_k2 21 1
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_rhoCp2 22 1600000
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_thick3 23 0.1
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_k3 24 1
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_rhoCp3 25 1600000
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_thick4 26 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_k4 27 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_rhoCp4 28 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_thick5 29 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_k5 30 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Wall_rhoCp5 31 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_thick1 32 0.05
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_k1 33 0.5
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_rhoCp1 34 1500000
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_thick2 35 0.05
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_k2 36 0.5
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_rhoCp2 37 1500000
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_thick3 38 0.05
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_k3 39 0.5
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_rhoCp3 40 1500000
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_thick4 41 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_k4 42 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_rhoCp4 43 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_thick5 44 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_k5 45 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_rhoCp5 46 -999
2016a 2017a Add SUEWS_ESTMCoefficients.txt nroom 47 10
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_albedo 48 0.5
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_emissivity 49 1
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_CHwall 50 0.001
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_CHroof 51 0.001
2016a 2017a Add SUEWS_ESTMCoefficients.txt Internal_CHbld 52 0.001
2016a 2017a Add SUEWS_SiteSelect.txt Timezone 7 0
2016a 2017a Add SUEWS_SiteSelect.txt z 10 999
2016a 2017a Add SUEWS_SiteSelect.txt TrafficRate 34 99999
2016a 2017a Add SUEWS_SiteSelect.txt BuildEnergyUse 35 99999
2016a 2017a Add SUEWS_SiteSelect.txt ActivityProfWD 54 5663
2016a 2017a Add SUEWS_SiteSelect.txt ActivityProfWE 55 5664
2016a 2017a Add SUEWS_SiteSelect.txt AreaWall 87 7000
2016a 2017a Add SUEWS_SiteSelect.txt Fr_ESTMClass_Paved1 88 0
2016a 2017a Add SUEWS_SiteSelect.txt Fr_ESTMClass_Paved2 89 1
2016a 2017a Add SUEWS_SiteSelect.txt Fr_ESTMClass_Paved3 90 0
2016a 2017a Add SUEWS_SiteSelect.txt Code_ESTMClass_Paved1 91 806
2016a 2017a Add SUEWS_SiteSelect.txt Code_ESTMClass_Paved2 92 807
2016a 2017a Add SUEWS_SiteSelect.txt Code_ESTM_Paved3 93 808
2016a 2017a Add SUEWS_SiteSelect.txt Fr_ESTMClass_Bldgs1 94 1
2016a 2017a Add SUEWS_SiteSelect.txt Fr_ESTMClass_Bldgs2 95 0
2016a 2017a Add SUEWS_SiteSelect.txt Fr_ESTMClass_Bldgs3 96 0
2016a 2017a Add SUEWS_SiteSelect.txt Fr_ESTMClass_Bldgs4 97 0
2016a 2017a Add SUEWS_SiteSelect.txt Fr_ESTMClass_Blgds5 98 0
2016a 2017a Add SUEWS_SiteSelect.txt Code_ESTMClass_Bldgs1 99 801
2016a 2017a Add SUEWS_SiteSelect.txt Code_ESTMClass_Bldgs2 100 802
2016a 2017a Add SUEWS_SiteSelect.txt Code_ESTMClass_Bldgs3 101 803
2016a 2017a Add SUEWS_SiteSelect.txt Code_ESTMClass_Bldgs4 102 804
2016a 2017a Add SUEWS_SiteSelect.txt Code_ESTMClass_Bldgs5 103 805
2016a 2017a Rename RunControl.nml AnthropHeatChoice -999 AnthropHeatMethod
2016a 2017a Rename RunControl.nml CBLuse -999 CBLUse
2016a 2017a Rename RunControl.nml NetRadiationChoice -999 NetRadiationMethod
2016a 2017a Rename RunControl.nml RoughLen_heat -999 RoughLenHeatMethod
2016a 2017a Rename RunControl.nml smd_choice -999 SMDMethod
2016a 2017a Rename RunControl.nml WU_choice -999 WaterUseMethod
2016a 2017a Rename RunControl.nml z0_method -999 RoughLenMomMethod
2016a 2017a Delete RunControl.nml gsChoice -999 -999
2016a 2017a Delete RunControl.nml SkipHeaderSiteInfo -999 -999
2016a 2017a Delete RunControl.nml SkipHeaderMet -999 -999
2016a 2017a Delete RunControl.nml SnowFractionChoice -999 -999
2016a 2017a Delete RunControl.nml TIMEZONE -999 -999
2016a 2017a Delete RunControl.nml z -999 -999
2016a 2017a Rename RunControl.nml SOLWEIGuse -999 SOLWEIGUse
2016a 2017a Rename RunControl.nml QSChoice -999 StorageHeatMethod
2016a 2017a Add RunControl.nml AnthropCO2Method -999 1
2016a 2017a Add RunControl.nml MultipleMetFiles -999 0
2016a 2017a Add RunControl.nml MultipleInitFiles -999 0
2016a 2017a Add RunControl.nml MultipleESTMFiles -999 0
2016a 2017a Add RunControl.nml ResolutionFilesIn -999 3600
2016a 2017a Add RunControl.nml ResolutionFilesInESTM -999 3600
2016a 2017a Add RunControl.nml ResolutionFilesOut -999 3600
2016a 2017a Add RunControl.nml DissagMethod -999 1
2016a 2017a Add RunControl.nml RainDissagMethod -999 100
2016a 2017a Add RunControl.nml SuppressWarnings -999 1
2016a 2017a Add RunControl.nml ncMode -999 0
2016a 2017a Add RunControl.nml nRow -999 0
2016a 2017a Add RunControl.nml nCol -999 0
2016a 2017a Add RunControl.nml Diagnose -999 0
2016a 2017a Rename RunControl.nml WriteSurfsFile -999 WriteOutOption

Note

Please report issues with the manual on the GitHub page.

Output files

Runtime diagnostic information

Error messages: problems.txt

If there are problems running the program serious error messages will be written to problems.txt.

  • Serious problems will usually cause the program to stop after writing the error message. If this is the case, the last line of problems.txt will contain a non-zero number (the error code).

  • If the program runs successfully, problems.txt file ends with:

    Run completed.
    0
    

SUEWS has a large number of error messages included to try to capture common errors to help the user determine what the problem is. If you encounter an error that does not provide an error message please capture the details so we can hopefully provide better error messages in future.

See Troubleshooting section for help solving problems. If the file paths are not correct the program will return an error when run (see Preparing to run the model).

Warning messages: warnings.txt

  • If the program encounters a more minor issue it will not stop but a warning may be written to warnings.txt. It is advisable to check the warnings to ensure there is not a more serious problem.
  • The warnings.txt file can be large (over several GBs) given warning messages are written out during a large scale simulation, you can use tail/head to view the ending/starting part without opening the whole file on Unix-like systems (Linux/mac OS), which may slow down your system.
  • To prevent warnings.txt from being written, set SuppressWarnings to 1 in RunControl.nml.
  • Warning messages are usually written with a grid number, timestamp and error count. If the problem occurs in the initial stages (i.e. before grid numbers and timestamps are assigned, these are printed as 00000).

Summary of model parameters: SS_FileChoices.txt

For each run, the model parameters specified in the input files are written out to the file SS_FileChoices.txt.

Model output files

SSss_YYYY_SUEWS_TT.txt

SUEWS produces the main output file (SSss_YYYY_SUEWS_tt.txt) with time resolution (TT min) set by ResolutionFilesOut in RunControl.nml.

Before these main data files are written out, SUEWS provides a summary of the column names, units and variables included in the file Ss_YYYY_TT_OutputFormat.txt (one file per run).

The variables included in the main output file are determined according to WriteOutOption set in RunControl.nml.

Column Name WriteOutOption Description
1 Year 0,1,2 Year [YYYY]
2 DOY 0,1,2 Day of year [DOY]
3 Hour 0,1,2 Hour [H]
4 Min 0,1,2 Minute [M]
5 Dectime 0,1,2 Decimal time [-]
6 Kdown 0,1,2 Incoming shortwave radiation [W m-2]
7 Kup 0,1,2 Outgoing shortwave radiation [W m-2]
8 Ldown 0,1,2 Incoming longwave radiation [W m-2]
9 Lup 0,1,2 Outgoing longwave radiation [W m-2]
10 Tsurf 0,1,2 Bulk surface temperature [°C]
11 QN 0,1,2 Net all-wave radiation [W m-2]
12 QF 0,1,2 Anthropogenic heat flux [W m-2]
13 QS 0,1,2 Storage heat flux [W m-2]
14 QH 0,1,2 Sensible heat flux (calculated using SUEWS) [W m-2]
15 QE 0,1,2 Latent heat flux (calculated using SUEWS) [W m-2]
16 QHlumps 0,1 Sensible heat flux (calculated using LUMPS) [W m-2]
17 QElumps 0,1 Latent heat flux (calculated using LUMPS) [W m-2]
18 QHresis 0,1 Sensible heat flux (calculated using resistance method) [W m-2]
19 Rain 0,1,2 Rain [mm]
20 Irr 0,1,2 Irrigation [mm]
21 Evap 0,1,2 Evaporation [mm]
22 RO 0,1,2 Runoff [mm]
23 TotCh 0,1,2 Change in surface and soil moisture stores [mm]
24 SurfCh 0,1,2 Change in surface moisture store [mm]
25 State 0,1,2 Surface wetness state [mm]
26 NWtrState 0,1,2 Surface wetness state (for non-water surfaces) [mm]
27 Drainage 0,1,2 Drainage [mm]
28 SMD 0,1,2 Soil moisture deficit [mm]
29 FlowCh 0,1 Additional flow into water body [mm]
30 AddWater 0,1 Additional water flow received from other grids [mm]
31 ROSoil 0,1 Runoff to soil (sub-surface) [mm]
32 ROPipe 0,1 Runoff to pipes [mm]
33 ROImp 0,1 Above ground runoff over impervious surfaces [mm]
34 ROVeg 0,1 Above ground runoff over vegetated surfaces [mm]
35 ROWater 0,1 Runoff for water body [mm]
36 WUInt 0,1 Internal water use [mm]
37 WUEveTr 0,1 Water use for irrigation of evergreen trees [mm]
38 WUDecTr 0,1 Water use for irrigation of deciduous trees [mm]
39 WUGrass 0,1 Water use for irrigation of grass [mm]
40 SMDPaved 0,1 Soil moisture deficit for paved surface [mm]
41 SMDBldgs 0,1 Soil moisture deficit for building surface [mm]
42 SMDEveTr 0,1 Soil moisture deficit for evergreen surface [mm]
43 SMDDecTr 0,1 Soil moisture deficit for deciduous surface [mm]
44 SMDGrass 0,1 Soil moisture deficit for grass surface [mm]
45 SMDBSoil 0,1 Soil moisture deficit for bare soil surface [mm]
46 StPaved 0,1 Surface wetness state for paved surface [mm]
47 StBldgs 0,1 Surface wetness state for building surface [mm]
48 StEveTr 0,1 Surface wetness state for evergreen tree surface [mm]
49 StDecTr 0,1 Surface wetness state for deciduous tree surface [mm]
50 StGrass 0,1 Surface wetness state for grass surface [mm]
51 StBSoil 0,1 Surface wetness state for bare soil surface [mm]
52 StWater 0,1 Surface wetness state for water surface [mm]
53 Zenith 0,1,2 Solar zenith angle [°]
54 Azimuth 0,1,2 Solar azimuth angle [°]
55 AlbBulk 0,1,2 Bulk albedo [-]
56 Fcld 0,1,2 Cloud fraction [-]
57 LAI 0,1,2 Leaf area index [m 2 m-2]
58 z0m 0,1 Roughness length for momentum [m]
59 zdm 0,1 Zero-plane displacement height [m]
60 ustar 0,1,2 Friction velocity [m s-1]
61 Lob 0,1,2 Obukhov length [m]
62 RA 0,1 Aerodynamic resistance [s m-1]
63 RS 0,1 Surface resistance [s m-1]
64 Fc 0,1,2 CO2 flux [umol m-2 s-1]
65 FcPhoto 0,1 CO2 flux from photosynthesis [umol m-2 s-1]
66 FcRespi 0,1 CO2 flux from respiration [umol m-2 s-1]
67 FcMetab 0,1 CO2 flux from metabolism [umol m-2 s-1]
68 FcTraff 0,1 CO2 flux from traffic [umol m-2 s-1]
69 FcBuild 0,1 CO2 flux from buildings [umol m-2 s-1]
70 FcPoint 0,1 CO2 flux from point source [umol m-2 s-1]
71 QNSnowFr 1 Net all-wave radiation for snow-free area [W m-2]
72 QNSnow 1 Net all-wave radiation for snow area [W m-2]
73 AlbSnow 1 Snow albedo [-]
74 QM 1 Snow-related heat exchange [W m-2]
75 QMFreeze 1 Internal energy change [W m-2]
76 QMRain 1 Heat released by rain on snow [W m-2]
77 SWE 1 Snow water equivalent [mm]
78 MeltWater 1 Meltwater [mm]
79 MeltWStore 1 Meltwater store [mm]
80 SnowCh 1 Change in snow pack [mm]
81 SnowRPaved 1 Snow removed from paved surface [mm]
82 SnowRBldgs 1 Snow removed from building surface [mm]
83 Ts 0,1,2 Skin temperature [°C]
84 T2 0,1,2 Air temperature at 2 m agl [°C]
85 Q2 0,1,2 Air specific humidity at 2 m agl [g kg-1]
86 U10 0,1,2 Wind speed at 10 m agl [m s-1]
87 RH2 0,1,2 Relative humidity at 2 m agl [%]

SSss_DailyState.txt

Contains information about the state of the surface and soil and vegetation parameters at a time resolution of one day. One file is written for each grid so it may contain multiple years.

Column Name Description
1 Year Year [YYYY]
2 DOY Day of year [DOY]
3 Hour Hour of the last timestep of a day [HH]
4 Min Minute of the last timestep of a day [MM]
5 HDD1_h Heating degree days [°C d]
6 HDD2_c Cooling degree days [°C d]
7 HDD3_Tmean Average daily air temperature [°C]
8 HDD4_T5d 5-day running-mean air temperature [°C]
9 P_day Daily total precipitation [mm]
10 DaysSR Days since rain [days]
11 GDD_EveTr Growing degree days for evergreen eree [°C d]
12 GDD_DecTr Growing degree days for deciduous tree [°C d]
13 GDD_Grass Growing degree days for grass [°C d]
14 SDD_EveTr Senescence degree days for evergreen eree [°C d]
15 SDD_DecTr Senescence degree days for deciduous tree [°C d]
16 SDD_Grass Senescence degree days for grass [°C d]
17 Tmin Daily minimum temperature [°C]
18 Tmax Daily maximum temperature [°C]
19 DLHrs Day length [h]
20 LAI_EveTr Leaf area index of evergreen trees [m-2 m-2]
21 LAI_DecTr Leaf area index of deciduous trees [m-2 m-2]
22 LAI_Grass Leaf area index of grass [m-2 m-2]
23 DecidCap Moisture storage capacity of deciduous trees [mm]
24 Porosity Porosity of deciduous trees [-]
25 AlbEveTr Albedo of evergreen trees [-]
26 AlbDecTr Albedo of deciduous trees [-]
27 AlbGrass Albedo of grass [-]
28 WU_EveTr1 Total water use for evergreen trees [mm]
29 WU_EveTr2 Automatic water use for evergreen trees [mm]
30 WU_EveTr3 Manual water use for evergreen trees [mm]
31 WU_DecTr1 Total water use for deciduous trees [mm]
32 WU_DecTr2 Automatic water use for deciduous trees [mm]
33 WU_DecTr3 Manual water use for deciduous trees [mm]
34 WU_Grass1 Total water use for grass [mm]
35 WU_Grass2 Automatic water use for grass [mm]
36 WU_Grass3 Manual water use for grass [mm]
37 deltaLAI Change in leaf area index (normalised 0-1) [-]
38 LAIlumps Leaf area index used in LUMPS (normalised 0-1) [-]
39 AlbSnow Snow albedo [-]
40 DensSnow_Paved Snow density - paved surface [kg m-3]
41 DensSnow_Bldgs Snow density - building surface [kg m-3]
42 DensSnow_EveTr Snow density - evergreen surface [kg m-3]
43 DensSnow_DecTr Snow density - deciduous surface [kg m-3]
44 DensSnow_Grass Snow density - grass surface [kg m-3]
45 DensSnow_BSoil Snow density - bare soil surface [kg m-3]
46 DensSnow_Water Snow density - water surface [kg m-3]
47 a1 OHM cofficient a1 - [-]
48 a2 OHM cofficient a2 [W m-2 h-1]
49 a3 OHM cofficient a3 - [W m-2]

InitialConditionsSSss_YYYY.nml

At the end of the model run (or the end of each year in the model run) a new InitialConditions file is written out (to the input folder) for each grid, see Initial Conditions file

SSss_YYYY_snow_TT.txt

SUEWS produces a separate output file for snow (when snowUse = 1 in RunControl.nml) with details for each surface type.

File format of SSss_YYYY_snow_TT.txt

Column Name Description
1 iy Year [YYYY]
2 id Day of year [DOY]
3 it Hour [H]
4 imin Minute [M]
5 dectime Decimal time [-]
6 SWE_Paved Snow water equivalent – paved surface [mm]
7 SWE_Bldgs Snow water equivalent – building surface [mm]
8 SWE_EveTr Snow water equivalent – evergreen surface [mm]
9 SWE_DecTr Snow water equivalent – deciduous surface [mm]
10 SWE_Grass Snow water equivalent – grass surface [mm]
11 SWE_BSoil Snow water equivalent – bare soil surface [mm]
12 SWE_Water Snow water equivalent – water surface [mm]
13 Mw_Paved Meltwater – paved surface [mm h-1]
14 Mw_Bldgs Meltwater – building surface [mm h-1]
15 Mw_EveTr Meltwater – evergreen surface [mm h-1]
16 Mw_DecTr Meltwater – deciduous surface [mm h-1]
17 Mw_Grass Meltwater – grass surface [mm h-1 1]
18 Mw_BSoil Meltwater – bare soil surface [mm h-1]
19 Mw_Water Meltwater – water surface [mm h-1]
20 Qm_Paved Snowmelt-related heat – paved surface [W m-2]
21 Qm_Bldgs Snowmelt-related heat – building surface [W m-2]
22 Qm_EveTr Snowmelt-related heat – evergreen surface [W m-2]
23 Qm_DecTr Snowmelt-related heat – deciduous surface [W m-2]
24 Qm_Grass Snowmelt-related heat – grass surface [W m-2]
25 Qm_BSoil Snowmelt-related heat – bare soil surface [W m-2]
26 Qm_Water Snowmelt-related heat – water surface [W m-2]
27 Qa_Paved Advective heat – paved surface [W m-2]
28 Qa_Bldgs Advective heat – building surface [W m-2]
29 Qa_EveTr Advective heat – evergreen surface [W m-2]
30 Qa_DecTr Advective heat – deciduous surface [W m-2]
31 Qa_Grass Advective heat – grass surface [W m-2]
32 Qa_BSoil Advective heat – bare soil surface [W m-2]
33 Qa_Water Advective heat – water surface [W m-2]
34 QmFr_Paved Heat related to freezing of surface store – paved surface [W m-2]
35 QmFr_Bldgs Heat related to freezing of surface store – building surface [W m-2]
36 QmFr_EveTr Heat related to freezing of surface store – evergreen surface [W m-2]
37 QmFr_DecTr Heat related to freezing of surface store – deciduous surface [W m-2]
38 QmFr_Grass Heat related to freezing of surface store – grass surface [W m-2]
39 QmFr_BSoil Heat related to freezing of surface store – bare soil surface [W m-2]
40 QmFr_Water Heat related to freezing of surface store – water [W m-2]
41 fr_Paved Fraction of snow – paved surface [-]
42 fr_Bldgs Fraction of snow – building surface [-]
43 fr_EveTr Fraction of snow – evergreen surface [-]
44 fr_DecTr Fraction of snow – deciduous surface [-]
45 fr_Grass Fraction of snow – grass surface [-]
46 Fr_BSoil Fraction of snow – bare soil surface [-]
47 RainSn_Paved Rain on snow – paved surface [mm]
48 RainSn_Bldgs Rain on snow – building surface [mm]
49 RainSn_EveTr Rain on snow – evergreen surface [mm]
50 RainSn_DecTr Rain on snow – deciduous surface [mm]
51 RainSn_Grass Rain on snow – grass surface [mm]
52 RainSn_BSoil Rain on snow – bare soil surface [mm]
53 RainSn_Water Rain on snow – water surface [mm]
54 qn_PavedSnow Net all-wave radiation – paved surface [W m-2]
55 qn_BldgsSnow Net all-wave radiation – building surface [W m-2]
56 qn_EveTrSnow Net all-wave radiation – evergreen surface [W m-2]
57 qn_DecTrSnow Net all-wave radiation – deciduous surface [W m-2]
58 qn_GrassSnow Net all-wave radiation – grass surface [W m-2]
59 qn_BSoilSnow Net all-wave radiation – bare soil surface [W m-2]
60 qn_WaterSnow Net all-wave radiation – water surface [W m-2]
61 kup_PavedSnow Reflected shortwave radiation – paved surface [W m-2]
62 kup_BldgsSnow Reflected shortwave radiation – building surface [W m-2]
63 kup_EveTrSnow Reflected shortwave radiation – evergreen surface [W m-2]
64 kup_DecTrSnow Reflected shortwave radiation – deciduous surface [W m-2]
65 kup_GrassSnow Reflected shortwave radiation – grass surface [W m-2]
66 kup_BSoilSnow Reflected shortwave radiation – bare soil surface [W m-2]
67 kup_WaterSnow Reflected shortwave radiation – water surface [W m-2]
68 frMelt_Paved Amount of freezing melt water – paved surface [mm]
69 frMelt_Bldgs Amount of freezing melt water – building surface [mm]
70 frMelt_EveTr Amount of freezing melt water – evergreen surface [mm]
71 frMelt_DecTr Amount of freezing melt water – deciduous surface [mm]
72 frMelt_Grass Amount of freezing melt water – grass surface [mm]
73 frMelt_BSoil Amount of freezing melt water – bare soil surface [mm]
74 frMelt_Water Amount of freezing melt water – water surface [mm]
75 MwStore_Paved Melt water store – paved surface [mm]
76 MwStore_Bldgs Melt water store – building surface [mm]
77 MwStore_EveTr Melt water store – evergreen surface [mm]
78 MwStore_DecTr Melt water store – deciduous surface [mm]
79 MwStore_Grass Melt water store – grass surface [mm]
80 MwStore_BSoil Melt water store – bare soil surface [mm]
81 MwStore_Water Melt water store – water surface [mm]
82 DensSnow_Paved Snow density – paved surface [kg m-3]
83 DensSnow_Bldgs Snow density – building surface [kg m-3]
84 DensSnow_EveTr Snow density – evergreen surface [kg m-3]
85 DensSnow_DecTr Snow density – deciduous surface [kg m-3]
86 DensSnow_Grass Snow density – grass surface [kg m-3]
87 DensSnow_BSoil Snow density – bare soil surface [kg m-3]
88 DensSnow_Water Snow density – water surface [kg m-3]
89 Sd_Paved Snow depth – paved surface [mm]
90 Sd_Bldgs Snow depth – building surface [mm]
91 Sd_EveTr Snow depth – evergreen surface [mm]
92 Sd_DecTr Snow depth – deciduous surface [mm]
93 Sd_Grass Snow depth – grass surface [mm]
94 Sd_BSoil Snow depth – bare soil surface [mm]
95 Sd_Water Snow depth – water surface [mm]
96 Tsnow_Paved Snow surface temperature – paved surface [°C]
97 Tsnow_Bldgs Snow surface temperature – building surface [°C]
98 Tsnow_EveTr Snow surface temperature – evergreen surface [°C]
99 Tsnow_DecTr Snow surface temperature – deciduous surface [°C]
100 Tsnow_Grass Snow surface temperature – grass surface [°C]
101 Tsnow_BSoil Snow surface temperature – bare soil surface [°C]
102 Tsnow_Water Snow surface temperature – water surface [°C]

SSss_YYYY_RSL_TT.txt

SUEWS produces a separate output file for wind, temperature and humidity profiles in the roughness sublayer at 30 levels: levels 1 and 30 are positioned at 0.1 and 3.0 Zh (i.e., canopy height) with other levels evenly distributed in between.

File format of SSss_YYYY_RSL_TT.txt:

Column Name Description
1 Year Year [YYYY]
2 DOY Day of year [DOY]
3 Hour Hour [H]
4 Min Minute [M]
5 Dectime Decimal time [-]
6 z_1 Height at level 1 [m]
7 z_2 Height at level 2 [m]
8 z_3 Height at level 3 [m]
9 z_4 Height at level 4 [m]
10 z_5 Height at level 5 [m]
11 z_6 Height at level 6 [m]
12 z_7 Height at level 7 [m]
13 z_8 Height at level 8 [m]
14 z_9 Height at level 9 [m]
15 z_10 Height at level 10 [m]
16 z_11 Height at level 11 [m]
17 z_12 Height at level 12 [m]
18 z_13 Height at level 13 [m]
19 z_14 Height at level 14 [m]
20 z_15 Height at level 15 [m]
21 z_16 Height at level 16 [m]
22 z_17 Height at level 17 [m]
23 z_18 Height at level 18 [m]
24 z_19 Height at level 19 [m]
25 z_20 Height at level 20 [m]
26 z_21 Height at level 21 [m]
27 z_22 Height at level 22 [m]
28 z_23 Height at level 23 [m]
29 z_24 Height at level 24 [m]
30 z_25 Height at level 25 [m]
31 z_26 Height at level 26 [m]
32 z_27 Height at level 27 [m]
33 z_28 Height at level 28 [m]
34 z_29 Height at level 29 [m]
35 z_30 Height at level 30 [m]
36 U_1 Wind speed at level 1 [m s-1]
37 U_2 Wind speed at level 2 [m s-1]
38 U_3 Wind speed at level 3 [m s-1]
39 U_4 Wind speed at level 4 [m s-1]
40 U_5 Wind speed at level 5 [m s-1]
41 U_6 Wind speed at level 6 [m s-1]
42 U_7 Wind speed at level 7 [m s-1]
43 U_8 Wind speed at level 8 [m s-1]
44 U_9 Wind speed at level 9 [m s-1]
45 U_10 Wind speed at level 10 [m s-1]
46 U_11 Wind speed at level 11 [m s-1]
47 U_12 Wind speed at level 12 [m s-1]
48 U_13 Wind speed at level 13 [m s-1]
49 U_14 Wind speed at level 14 [m s-1]
50 U_15 Wind speed at level 15 [m s-1]
51 U_16 Wind speed at level 16 [m s-1]
52 U_17 Wind speed at level 17 [m s-1]
53 U_18 Wind speed at level 18 [m s-1]
54 U_19 Wind speed at level 19 [m s-1]
55 U_20 Wind speed at level 20 [m s-1]
56 U_21 Wind speed at level 21 [m s-1]
57 U_22 Wind speed at level 22 [m s-1]
58 U_23 Wind speed at level 23 [m s-1]
59 U_24 Wind speed at level 24 [m s-1]
60 U_25 Wind speed at level 25 [m s-1]
61 U_26 Wind speed at level 26 [m s-1]
62 U_27 Wind speed at level 27 [m s-1]
63 U_28 Wind speed at level 28 [m s-1]
64 U_29 Wind speed at level 29 [m s-1]
65 U_30 Wind speed at level 30 [m s-1]
66 T_1 Air temperature at level 1 [°C]
67 T_2 Air temperature at level 2 [°C]
68 T_3 Air temperature at level 3 [°C]
69 T_4 Air temperature at level 4 [°C]
70 T_5 Air temperature at level 5 [°C]
71 T_6 Air temperature at level 6 [°C]
72 T_7 Air temperature at level 7 [°C]
73 T_8 Air temperature at level 8 [°C]
74 T_9 Air temperature at level 9 [°C]
75 T_10 Air temperature at level 10 [°C]
76 T_11 Air temperature at level 11 [°C]
77 T_12 Air temperature at level 12 [°C]
78 T_13 Air temperature at level 13 [°C]
79 T_14 Air temperature at level 14 [°C]
80 T_15 Air temperature at level 15 [°C]
81 T_16 Air temperature at level 16 [°C]
82 T_17 Air temperature at level 17 [°C]
83 T_18 Air temperature at level 18 [°C]
84 T_19 Air temperature at level 19 [°C]
85 T_20 Air temperature at level 20 [°C]
86 T_21 Air temperature at level 21 [°C]
87 T_22 Air temperature at level 22 [°C]
88 T_23 Air temperature at level 23 [°C]
89 T_24 Air temperature at level 24 [°C]
90 T_25 Air temperature at level 25 [°C]
91 T_26 Air temperature at level 26 [°C]
92 T_27 Air temperature at level 27 [°C]
93 T_28 Air temperature at level 28 [°C]
94 T_29 Air temperature at level 29 [°C]
95 T_30 Air temperature at level 30 [°C]
96 q_1 Specific humidity at level 1 [g kg-1]
97 q_2 Specific humidity at level 2 [g kg-1]
98 q_3 Specific humidity at level 3 [g kg-1]
99 q_4 Specific humidity at level 4 [g kg-1]
100 q_5 Specific humidity at level 5 [g kg-1]
101 q_6 Specific humidity at level 6 [g kg-1]
102 q_7 Specific humidity at level 7 [g kg-1]
103 q_8 Specific humidity at level 8 [g kg-1]
104 q_9 Specific humidity at level 9 [g kg-1]
105 q_10 Specific humidity at level 10 [g kg-1]
106 q_11 Specific humidity at level 11 [g kg-1]
107 q_12 Specific humidity at level 12 [g kg-1]
108 q_13 Specific humidity at level 13 [g kg-1]
109 q_14 Specific humidity at level 14 [g kg-1]
110 q_15 Specific humidity at level 15 [g kg-1]
111 q_16 Specific humidity at level 16 [g kg-1]
112 q_17 Specific humidity at level 17 [g kg-1]
113 q_18 Specific humidity at level 18 [g kg-1]
114 q_19 Specific humidity at level 19 [g kg-1]
115 q_20 Specific humidity at level 20 [g kg-1]
116 q_21 Specific humidity at level 21 [g kg-1]
117 q_22 Specific humidity at level 22 [g kg-1]
118 q_23 Specific humidity at level 23 [g kg-1]
119 q_24 Specific humidity at level 24 [g kg-1]
120 q_25 Specific humidity at level 25 [g kg-1]
121 q_26 Specific humidity at level 26 [g kg-1]
122 q_27 Specific humidity at level 27 [g kg-1]
123 q_28 Specific humidity at level 28 [g kg-1]
124 q_29 Specific humidity at level 29 [g kg-1]
125 q_30 Specific humidity at level 30 [g kg-1]

SSss_YYYY_BL.txt

Meteorological variables modelled by CBL portion of the model are output in to this file created for each day with time step (see section CBL Input).

Column Name Description Units
1 iy Year [YYYY]  
2 id Day of year [DoY]  
3 it Hour [H]  
4 imin Minute [M]  
5 dectime Decimal time [-]  
6 zi Convectibe boundary layer height m
7 Theta Potential temperature in the inertial sublayer K
8 Q Specific humidity in the inertial sublayer g kg-1
9 theta+ Potential temperature just above the CBL K
10 q+ Specific humidity just above the CBL g kg-1
11 Temp_C Air temperature °C
12 RH Relative humidity %
13 QH_use Sensible heat flux used for calculation W m-2
14 QE_use Latent heat flux used for calculation W m-2
15 Press_hPa Pressure used for calculation hPa
16 avu1 Wind speed used for calculation m s-1
17 ustar Friction velocity used for calculation m s-1
18 avdens Air density used for calculation kg m-3
19 lv_J_kg Latent heat of vaporization used for calculation J kg-1
20 avcp Specific heat capacity used for calculation J kg-1 K-1
21 gamt Vertical gradient of potential temperature K m-1
22 gamq Vertical gradient of specific humidity kg kg-1 m-1

SSss_YYYY_ESTM_TT.txt

If the ESTM model option is run, the following output file is created. Note: First time steps of storage output could give NaN values during the initial converging phase.

ESTM output file format

Column Name Description Units
1 iy Year  
2 id Day of year  
3 it Hour  
4 imin Minute  
5 dectime Decimal time  
6 QSnet Net storage heat flux (QSwall+QSground+QS) W m-2
7 QSair Storage heat flux into air W m-2
8 QSwall Storage heat flux into wall W m-2
9 QSroof Storage heat flux into roof W m-2
10 QSground Storage heat flux into ground W m-2
11 QSibld Storage heat flux into internal elements in buildling W m-2
12 Twall1 Temperature in the first layer of wall (outer-most) K
13 Twall2 Temperature in the first layer of wall K
14 Twall3 Temperature in the first layer of wall K
15 Twall4 Temperature in the first layer of wall K
16 Twall5 Temperature in the first layer of wall (inner-most) K
17 Troof1 Temperature in the first layer of roof (outer-most) K
18 Troof2 Temperature in the first layer of roof K
19 Troof3 Temperature in the first layer of roof K
20 Troof4 Temperature in the first layer of roof K
21 Troof5 Temperature in the first layer of ground (inner-most) K
22 Tground1 Temperature in the first layer of ground (outer-most) K
23 Tground2 Temperature in the first layer of ground K
24 Tground3 Temperature in the first layer of ground K
25 Tground4 Temperature in the first layer of ground K
26 Tground5 Temperature in the first layer of ground (inner-most) K
27 Tibld1 Temperature in the first layer of internal elements K
28 Tibld2 Temperature in the first layer of internal elements K
29 Tibld3 Temperature in the first layer of internal elements K
30 Tibld4 Temperature in the first layer of internal elements K
31 Tibld5 Temperature in the first layer of internal elements K
32 Tabld Air temperature in buildings K

Note

Please report issues with the manual on the GitHub page.

Troubleshooting

How to report an issue of this manual?

Please submit your issue via our GitHub page.

How to join your email-list?

Please join our email-list here.

How to create a directory?

Please search the web using this phrase if you do not know how to create a folder or directory

How to unzip a file

Please search the web using this phrase if you do not know how to unzip a file

A text editor

A program to edit plain text files. If you search on the web using the phrase ‘text editor’ you will find numerous programs. These include for example, NotePad, EditPad, Text Pad etc

Command prompt

From Start select run –type cmd – this will open a window. Change directory to the location of where you stored your files. The following website may be helpful if you do not know what a command prompt is: http://dosprompt.info/

Day of year [DOY]

January 1st is day 1, February 1st is day 32. If you search on the web using the phrase ‘day of year calendar’ you will find tables that allow rapid conversions. Remember that after February 28th DOY will be different between leap years and non-leap years.

ESTM output

First time steps of storage output could give NaN values during the initial converging phase.

First things to Check if the program seems to have problems

  • Check the problems.txt file.
  • Check file options – in RunControl.nml.
  • Look in the output directory for the SS_FileChoices.txt. This allows you to check all options that were used in the run. You may want to compare it with the original version supplied with the model.
  • Note there can not be missing time steps in the data. If you need help with this you may want to checkout UMEP

A pop-up saying “file path not found”

This means the program cannot find the file paths defined in RunControl.nml file. Possible solutions:

  • Check that you have created the folder that you specified in RunControl.nml.
  • Check does the output directory exist?
  • Check that you have a single or double quotes around the FileInputPath, FileOutputPath and FileCode

====“%sat_vap_press.f temp=0.0000 pressure dectime”==== Temperature is zero in the calculation of water vapour pressure parameterization.

  • You don’t need to worry if the temperature should be (is) 0°C.
  • If it should not be 0°C this suggests that there is a problem with the data.

%T changed to fit limits

  • [TL =0.1]/ [TL =39.9] You may want to change the coefficients for surface resistance. If you have data from these temperatures, we would happily determine them.

%Iteration loop stopped for too stable conditions.

  • [zL]/[USTAR] This warning indicates that the atmospheric stability gets above 2. In these conditions MO theory is not necessarily valid. The iteration loop to calculate the Obukhov length and friction velocity is stopped so that stability does not get too high values. This is something you do not need to worry as it does not mean wrong input data.

“Reference to undefined variable, array element or function result”

  • Parameter(s) missing from input files.

See also the error messages provided in problems.txt and warnings.txt

Note

Please report issues with the manual on the GitHub page.

Recent publications

Note

If you have papers to add to this list please let us and others know via the email list.

topic:Application and evalution in cold climates. Implications of warming
citation:Järvi L, S Grimmond, JP McFadden, A Christen, I Strachan, M Taka, L Warsta, M Heimann 2017: Warming effects on the urban hydrology in cold climate regions Scientific Reports 7: 5833
topic:Downscaling climate (rainfall) data to 1 h
citation:Kokkonen T, CSB Grimmond, O Räty, HC Ward, A Christen, T Oke, S Kotthaus, L Järvi 2017: Sensitivity of Surface Urban Energy and Water Balance Scheme (SUEWS)
topic:for example applications:
citation:Ward HC, S Grimmond 2017: Using biophysical modelling to assess the impact of various scenarios on summertime urban climate across Greater London Landscape and Urban Planning 165, 142–161
topic:evaluation in Singapore and comparison with other urban land surface models
citation:Demuzere M, S Harshan, L Järvi, M Roth, CSB Grimmond, V Masson, KW Oleson, E Velasco H Wouters 2017: Impact of urban canopy models and external parameters on the modelled urban energy balance QJRMS, 143, Issue 704, Part A, 1581–1596
topic:Evaluation of SUEWS model
citation:Ward HC, Kotthaus S, Järvi L and Grimmond CSB (2016) Surface Urban Energy and Water Balance Scheme (SUEWS): Development and evaluation at two UK sites. Urban Climate
topic:Evaluation of radiation in Shanghai
citation:Ao XY, CSB Grimmond, DW Liu, ZH Han, P Hu, YD Wang, XR Zhen, JG Tan 2016: Radiation fluxes in a business district of Shanghai JAMC, 55, 2451-2468
topic:Boundary layer modelling
citation:Onomura S, Grimmond CSB, Lindberg F, Holmer B & Thorsson S (2015) Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme Urban Climate, 11, 1-23
topic:Snow melt model development
citation:Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H & Strachan IB 2014: Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities Geosci. Model Dev. 7, 1691-1711

Other papers

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

Tutorials

To help users getting started with SUEWS, the community is working on setting up tutorials and instructions for different parts of SUEWS and related tool. The tutorials are available are found in the table below.

Topic Application
Urban Energy Balance - SUEWS Introduction Energy, water and radiation fluxes for one location
Urban Energy Balance - SUEWS Advanced Energy, water and radiation fluxes for one location
Urban Energy Balance - SUEWS Spatial Energy, water and radiation fluxes for a spatial grid
Urban Energy Balance - SUEWS and WUDAPT Making use of WUDAPT local climate zones in SUEWS

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS Introduction

Introduction

In this tutorial you will use a land-surface model, SUEWS to simulate energy exchanges in a city (London is the test case).

SUEWS (Surface Urban Energy and Water Balance Scheme) allows the energy and water balance exchanges for urban areas to be modelled (Järvi et al. 2011, 2014, Ward et al. 2016a). The model is applicable at the neighbourhood scale (e.g. 102 to 104 m). The fluxes calculated are applicable to height of about 2-3 times the mean height of the roughness elements; i.e. above the roughness sublayer (RSL). The use of SUEWS within Urban Multi-scale Environmental Predictor (UMEP) provides an introduction to the model and the processes simulated, the parameters used and the impact on the resulting fluxes.

Tools such as this, once appropriately assessed for an area, can be used for a broad range of applications. For example, for climate services (e.g. http://www.wmo.int/gfcs/). Running a model can allow analyses, assessments, and long-term projections and scenarios. Most applications require not only meteorological data but also information about the activities that occur in the area of interest (e.g. agriculture, population, road and infrastructure, and socio-economic variables).

Model output may be needed in many formats depending on a users’ needs. Thus, the format must be useful, while ensuring the science included within the model is appropriate. The figure below provides an overview of UMEP, a city based climate service tool (CBCST). Within UMEP there are a number of models which can predict and diagnose a range of meteorological processes. In this activity we are concerned with SUEWS, initially the central components of the model. See manual or published papers for more detailed information of the model.

none

Overview of the climate service tool UMEP (from Lindberg et al. 2018)

SUEWS can be run in a number of different ways:

  1. Within UMEP via the Simple selection. This is useful for becoming familiar with the model (Part 1)
  2. Within UMEP via the Advanced selection. This can be used to exploit the full capabilities of the model (Part 2)
  3. SUEWS standalone (see manual)
  4. Within other larger scale models (e.g. WRF).

SUEWS Simple Objectives

This tutorial introduces SUEWS and demonstartes how to run the model within UMEP (Urban Multi-scale Environmental Predictor). Help with Abbreviations.

Steps
  1. An introduction to the model and how it is designed.
  2. Different kinds of input data that are needed to run the model
  3. How to run the model
  4. How to examine the model output

Initial Steps

UMEP is a python plugin used in conjunction with QGIS. To install the software and the UMEP plugin see the getting started section in the UMEP manual.

As UMEP is under development, some documentation may be missing and/or there may be instability. Please report any issues or suggestions to our repository.

SUEWS Model Inputs

Details of the model inputs and outputs are provided in the SUEWS manual. As this tutorial is concerned with a simple application only the most critical parameters are shown. Other versions allow many other parameters to be modified to more appropriate values if applicable. The table below provides an overview of the parameters that can be modified in the Simple application of SUEWS.

Type Definition Reference/Comments
  Building/ Tree Morphology  
Mean height of Building/Trees (m)   Grimmond and Oke (1999)
Frontal area index Area of the front face of a roughness element exposed to the wind relative to the plan area. Grimmond and Oke (1999), Fig 2
Plan area index Area of the roughness elements relative to the total plan area. Grimmond and Oke (1999), Fig 2
  Land cover fraction Should sum to 1
Paved Roads, sidewalks, parking lots, impervious surfaces that are not buildings  
Buildings Buildings Same as the plan area index of buildings in the morphology section.
Evergreen trees Trees/shrubs that retain their leaves/needles all year round Tree plan area index will be the sum of evergreen and deciduous area. Note: this is the same as the plan area index of vegetation in the morphology section.
Deciduous trees Trees/shrubs that lose their leaves Same as above
Grass Grass  
Bare soil Bare soil – non vegetated but water can infilitrate  
Water River, ponds, swimming pools, fountains  
  Initial conditions What is the state of the conditions when the model run begins?
Days since rain (days) This will influence irrigation behaviour in the model. If there has been rain recently then it will be longer before irrigiation occurs. If this is a period or location when no irrigation is permitted/occurring then this is not critical as the model will calculate from this point going forward.
Daily mean temperature (°C) Influences irrigation and anthropogenic heat flux  
Soil mositure status (%) This will influence both evaporation and runoff processes If close to 100% then there is plenty of water for evaporation but also a higher probability of flooding if intense precipitation occurs.
  Other  
Year What days are weekdays/weekends  
Latitude (°) Solar related calculations  
Longitude (°) Solar related calculations  
UTC (h) Time zone Influences solar related calculations

How to Run SuewsSimple from the UMEP-plugin

  1. Open SuewsSimple from UMEP -> Processor -> Urban Energy Balance -> Urban Energy Balance, SUEWS (Simple). The GUI that opens looks quite extensive but it is actually not that complicated to start a basic model run (figure below). Some additional information about the plugin is found in the left window. As you can read, a test dataset from observations for London, UK (Kotthaus and Grimmond 2014, Ward et al. 2016a) is included in within the plugin.
none

The interface for SUEWS, simple version (click on image to make it larger).

  1. To make use of this dataset click on Add settings from test dataset (see near bottom of the box). The land cover fractions and all other settings originate from Kotthaus and Grimmond (2014). They used a source area model to obtain the different input parameters (their Fig. 7 in Kotthaus and Grimmond, 2014).
  2. Before you start the model, change the location of the output data to any location of your choice. Also, make notes on the settings such as Year etc.
  3. Do a model run and explore the results by clicking Run. A command window appears, when SUEWS performs the calculations using the settings from the interface. Once the calculations are done, some of the results are shown in two summary plots.
none

Model output from SUEWS (simple) using the default settings and data (click on image to make it larger).

none

Model output from SUEWS (simple) using the default settings and data (click on image to make it larger).

Model results

The graphs in the upper figure are the monthly mean energy (left) and water balance (right). The lower graphs show the radiation fluxes, energy fluxes, and water related outputs throughout the year. This plot includes a lot of data and it might be difficult to examine it in detail.

To zoom into the plot: use the tools in the top left corner, to zoom to a period of interest. For example, the Zoom in to about the last ten days in March (figure below). This was a period with clear relatively weather.

none

Zoom in on end of March from the daily plot (click on image to make it larger).

Saving a Figure

Use the disk tool in the upper left corner.

  1. .jpg
  2. .pdf
  3. .tif (Recommended)
  4. .png

Output data Files

In the output folder (you selected earlier) you will find (at least) three files:

  1. Kc98_2012_60.txt – provides the 60 min model results for site “KC1” for the year 2012
  2. Kc_FilesChoices.txt – this indicates all options used in the model run see the SUEWS Manual for interpretation of content (this is for when you are doing large number of runs so you know exactly what options were used in each run)
  3. Kc98_DailyState.txt – this provides the daily mean state (see SUEWS manual for detailed explanation). This allows you to see, for example, the daily state of the LAI (leaf area index).
  4. Kc_OutputFormat.txt – provides detailed information about the output files such as extended descriptions for each column including units.

If you open these files in a text editor. To understand the header variables read the SUEWS manual.

Sensitivity to land surface fractions

none

Land cover fractions (click on image to make it larger).

The previous results are for a densely build-up area in London, UK. In order to test the sensitivity of SUEWS to some surface properties you can think about changing some of the surface properties in the SUEWS Simple. For example, change the land cover fraction by:

  1. Change the land cover fractions as seen in the figure. Feel free to select other values as long as all the fractions add up to 1.0.
  2. Save the output to a different folder by selecting output folder.
  3. Click Run.

References

  • Grimmond CSB and Oke 1999: Aerodynamic properties of urban areas derived, from analysis of surface form. Journal of Applied Climatology 38:9, 1262-1292
  • Grimmond et al. 2015: Climate Science for Service Partnership: China, Shanghai Meteorological Servce, Shanghai, China, August 2015.
  • Järvi L, Grimmond CSB & Christen A 2011: The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver J. Hydrol. 411, 219-237
  • Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H &Strachan IB 2014: Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities, , Geosci. Model Dev. 7, 1691-1711
  • Kormann R, Meixner FX 2001: An analytical footprint model for non-neutral stratification. Bound.-Layer Meteorol., 99, 207–224
  • Kotthaus S and Grimmond CSB 2014: Energy exchange in a dense urban environment – Part II: Impact of spatial heterogeneity of the surface. Urban Climate 10, 281–307
  • Onomura S, Grimmond CSB, Lindberg F, Holmer B, Thorsson S 2015: Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme. Urban Climate. 11:1-23 (link to paper)
  • Ward HC, L Järvi, S Onomura, F Lindberg, A Gabey, CSB Grimmond 2016 SUEWS Manual V2016a, http://urban-climate.net/umep/SUEWS Department of Meteorology, University of Reading, Reading, UK
  • Ward HC, Kotthaus S, Järvi L and Grimmond CSB 2016b: Surface Urban Energy and Water Balance Scheme (SUEWS): Development and evaluation at two UK sites. Urban Climate http://dx.doi.org/10.1016/j.uclim.2016.05.001
  • Ward HC, S Kotthaus, CSB Grimmond, A Bjorkegren, M Wilkinson, WTJ Morrison, JG Evans, JIL Morison, M Iamarino 2015b: Effects of urban density on carbon dioxide exchanges: observations of dense urban, suburban and woodland areas of southern England. Env Pollution 198, 186-200

Authors this document: Lindberg and Grimmond (2016)

Definitions and Notation

To help you find further information about the acronyms they are classified by T: Type of term: C: computer term, S: science term, G: GIS term.

  Definition T Ref./Comment
DEM Digital elevation model G  
DSM Digital surface model G  
FAI (λF) Frontal area index S Grimmond and Oke (1999)
GUI Graphical User Interface C  
LAI Leaf Area Index S  
PAI (λP) Plan area index S  
png Portable Network Graphics C format for saving plots/figures
QGIS   G www.qgis.org
SUEWS Surface Urban Energy and Water Balance Scheme S  
Tif Tagged Image File Format C format for saving plots/figures
UI user interface C  
UMEP Urban Multi-scale Environmental predictor C  
z0 Roughness length for momentum S Grimmond and Oke (1999)
zd Zero plane displacement length for momentum S Grimmond and Oke (1999)

Further explanation

Morphometric Methods to determine Roughness parameters:

For more and overview and details see Grimmond and Oke (1999) and Kent et al. (2017a). This uses the height and spacing of roughness elements (e.g. buildings, trees) to model the roughness parameters. For more details see Kent et al. (2017a), Kent et al. (2017b) and [Kent et al. (2017c)]. UMEP has tools for doing this: Pre-processor -> Urban Morphology

Source Area Model

For more details see Kotthaus and Grimmond (2014b) and Kent et al. (2017a). The Kormann and Meixner (2001) model is used to determine the probable area that a turbulent flux measurement was impacted by. This is a function of wind direction, stability, turbulence characteristics (friction velocity, variance of the lateral wind velocity) and roughness parameters.

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS Advanced

Introduction

The tutorial Urban Energy Balance - SUEWS Introduction should be completed first. This tutorial is designed to work with QGIS 2.18.

Objectives
  1. To explore the link between QGIS and SUEWS to include new site-specific information
  2. To examine how it affects the energy fluxes
Overview of steps
  1. Initially become familiar with SUEWS advanced which is a plugin that makes it possible for you to set all parameters that can be manipulated in SUEWS as well as execute the model on mutiple grids (Urban Energy Balance - SUEWS Spatial).
  2. Derive new surface information
  3. Run the model

How to Run from the UMEP-plugin

How to run SUEWS Advanced:

  1. Open the plugin which is located at UMEP -> Processor -> Urban Energy Balance -> Urban Energy Balance, SUEWS/BLUEWS (Advanced). This has most of the general settings (e.g. activate the snow module etc.) which are related to RunControl.nml.
  2. Use the Input folder:
    • C:/Users/your_user_name/.qgis2/python/plugins/UMEP/suewsmodel/Input
  3. Create or enter an Output directory of your choice.
  4. From the Input folder - confirm the data are in there.
  5. Tick in Obtain temporal… and set Temporal resolution of output (minutes) to 60.
  6. Click Run
  7. Make sure that output files are created.
  8. You can now close the SUEWS/BLUEWS (Advanced)-plugin again.
Interface for SUEWS Advanced version.

Interface for SUEWS Advanced version.

Sensitivity Test

The default dataset included in Suews Simple has parameters calculated from a source area model to obtain the appropriate values for the input parameters. Roughness parameters such as roughness length (z0) and zero plane displacement length (zd) are calculated using morphometric models. Now you will explore the differences in fluxes using the default settings or using input parameters from the geodata included in the test datasets available for this tutorial. Download the zip-file (see below) and extract the files to a suitable location where you both have reading and writing capabilities.

Data for the tutorial can be downloaded here

Geodata Name
Ground and building DSM DSM_LondonCity_1m.tif (m asl)
Vegetation DSM CDSM_LondonCity_1m.tif (m agl)
DEM (digital elevation model) DEM_LondonCity_1m.tif (masl)
Land cover LC_londoncity_UMEP_32631

They are all projected in UTM 31N (EPSG:32631). The three surface models originate from a LiDAR dataset. The land cover data is a mixture of Ordnance Survey and the LiDAR data.

  1. Open the geodatasets. Go to Layer > Add layer > Add Raster Layer. Locate the files you downloaded before (see above).
  2. A QGIS style file (.qml) is available for the land cover grid. It can found in C:Usersyour_user_name.qgis2pythonpluginsUMEP\ LandCoverReclassifier\. Load it in the Layer > Properties > Style > Style (lower left) Load file.
  3. Click Apply before you close so that the names of the classes also load. You can also get the properties of a layer by right-click on a layer in the Layers-window.
  4. If you have another land cover dataset you can use the LandCoverReclassifier in the UMEP pre-processor to populate with the correct values suitable for the UMEP plugin environment.
  5. Now take a moment and investigate the different geodatasets. What is the sparial (pixel) resolution? How is ground represented in the CDSM?

Generating data from the geodatasets

  1. Make certain that you have the geodatafiles open. The file at the top (left hand side (LHS)) of the list is the one that is shown in the centre (figure below). You can swap their order using the LHS box.

  2. Open SUEWS Simple.

  3. Begin by adding the test dataset again.

  4. Update the building morphology parameters (top left panel in Suews Simple).

  5. To generate new values, click on Open tool.

  6. This is another plugin within UMEP that can be used to generate morphometric parameters

    None

    QGIS where Suews Simple and Image Morphometric Parameters (Point) is opened.

  7. First, clear the map canvas from your two other plugin windows, e.g. as figure above.

  8. If you use the default test data in SUEWS Simple - you can overwrite is as you go.

  9. Locate the eddy covariance tower position on the Strand building, King’s College London. To find the position, consult Figure 1 (KSS) in Kotthaus and Grimmond (2014).

  10. Use Select point on canvas and put a point at that location (left).

  11. Generate a study area. Use 500 m search distance, 5 degree interval and click Generate study area.

  12. A circular area will be considered. Enter the DSM and DEM files (i.e. the files you currently have in the viewer)

  13. Click Run.

    None

    Figure 3. Settings for Image Morphometric Parameters for buildings.

  14. In the folder you specified two additional files will be present (i) isotropic - averages of the morphometric parameters (ii) anisotropic - values for each wind sector you specified (5 degrees).

  15. Close this plugin

  16. Click on Fetch file from… in the building morphology panel

  17. Choose the isotropic file (just generated).

  18. Do the same for vegetation (upper left panel, right). See figure below.

  19. Instead of locating the point again you can use the existing point.

  20. You still need to generate a separate study area for the vegetation calculation.

  21. Examine the CDSM (vegetation file) in your map canvas. As you can see, this data has no ground heights (ground = 0). Therefore, this time Tick in the box Raster DSM (only buildings) exist.

  22. Enter the CDSM as your Raster DSM (only buildings).

    None

    Settings for Image Morphometric Parameters for vegetation

  23. A warning appears that your vegetation fractions between the morphology dataset and land cover dataset are large. You can ignore this for now since the land cover dataset also will change.

  24. Repeat the same procedure for land cover as you did for buildings and vegetation but instead using the Land Cover Fraction (Point) plugin.

  25. Enter the meteorological file, Year etc. This should be the same as for the first run you made.

  26. Now you are ready to run the model. Click Run.

If you get an error window (figure below). This error is generate by SUEWS as the sum of the land cover fractions is not 1. If you calculate carefully, one part of a thousand is missing (this is probably a rounding error during data extraction). To fix this issue: add 0.001 to e.g. bare soil. Now run again.

None

Possible error window from running SUEWS with new settings.

None

The settings for running with geodata derived parameters (old version of GUI).

You are now familiar with the Suews Simple plugin. Your next task is to choose another location within the geodataset domain, generate data and run the model. If you choose an area where the fraction of buildings and paved surfaces are low, consider lowering the population density to get more realistic model outputs. Compare the results for the different area.

References

  • Grimmond CSB and Oke 1999: Aerodynamic properties of urban areas derived, from analysis of surface form. Journal of Applied Climatology 38:9, 1262-1292
  • Grimmond et al. 2015: Climate Science for Service Partnership: China, Shanghai Meteorological Servce, Shanghai, China, August 2015.
  • Järvi L, Grimmond CSB & Christen A 2011: The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver J. Hydrol. 411, 219-237
  • Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H &Strachan IB 2014: Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities, , Geosci. Model Dev. 7, 1691-1711
  • Kormann R, Meixner FX 2001: An analytical footprint model for non-neutral stratification. Bound.-Layer Meteorol., 99, 207-224
  • Kotthaus S and Grimmond CSB 2014: Energy exchange in a dense urban environment - Part II: Impact of spatial heterogeneity of the surface. Urban Climate 10, 281–307
  • Onomura S, Grimmond CSB, Lindberg F, Holmer B, Thorsson S 2015: Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme. Urban Climate. 11:1-23 (link to paper)
  • Ward HC, L Järvi, S Onomura, F Lindberg, A Gabey, CSB Grimmond 2016 SUEWS Manual V2016a, http://urban-climate.net/umep/SUEWS Department of Meteorology, University of Reading, Reading, UK
  • Ward HC, Kotthaus S, Järvi L and Grimmond CSB 2016b: Surface Urban Energy and Water Balance Scheme (SUEWS): Development and evaluation at two UK sites. Urban Climate http://dx.doi.org/10.1016/j.uclim.2016.05.001
  • Ward HC, S Kotthaus, CSB Grimmond, A Bjorkegren, M Wilkinson, WTJ Morrison, JG Evans, JIL Morison, M Iamarino 2015b: Effects of urban density on carbon dioxide exchanges: observations of dense urban, suburban and woodland areas of southern England. Env Pollution 198, 186-200

Authors of this document: Lindberg and Grimmond (2016)

Definitions and Notation

To help you find further information about the acronyms they are classified by T: Type of term: C: computer term, S: science term, G: GIS term.

  Definition T Reference/Comme nt
DEM Digital elevation model G  
DSM Digital surface model G  
FAI (λF) Frontal area index S Grimmond and Oke (1999), their figure 2
GUI Graphical User Interface C  
LAI Leaf Area Index S  
PAI (λP) Plan area index S  
png Portable Network Graphics C format for saving plots/figures
QGIS   G www.qgis.org
SUEWS Surface Urban Energy and Water Balance Scheme S  
Tif Tagged Image File Format C format for saving plots/figures
UI user interface C  
UMEP Urban Multi-scale Environmental predictor C  
z0 Roughness length for momentum S Grimmond and Oke (1999)
zd Zero plane displacement length for momentum S Grimmond and Oke (1999)

Further explanation

Morphometric Methods to determine Roughness parameters:

For more and overview and details see Grimmond and Oke (1999). This uses the height and spacing of roughness elements (e.g. buildings, trees) to model the roughness parameters. UMEP has tools for doing this: Pre-processor -> Urban Morphology

Source Area Model

For more details see Kotthaus and Grimmond (2014b). The Kormann and Meixner (2001) model is used to determine the probable area that a turbulent flux measurement was impacted by. This is a function of wind direction, stability, turbulence characteristics (friction velocity, variance of the lateral wind velocity) and roughness parameters.

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS Spatial

Introduction

In this tutorial you will generate input data for the SUEWS model and simulate spatial (and temporal) variations of energy exchanges within a small area on Manhattan (New York City) with regards to a heat wave event.

Tools such as this, once appropriately assessed for an area, can be used for a broad range of applications. For example, for climate services (e.g. http://www.wmo.int/gfcs/ , Baklanov et al. 2018). Running a model can allow analyses, assessments, and long-term projections and scenarios. Most applications require not only meteorological data but also information about the activities that occur in the area of interest (e.g. agriculture, population, road and infrastructure, and socio-economic variables).

This tutorial makes use of local high resolution detailed spatial data. If this kind of data are unavailable, other datasets such as local climate zones (LCZ) from the WUDAPT database could be used. The tutorial Urban Energy Balance - SUEWS and WUDAPT is available if you want to know more about using LCZs in SUEWS. However, it is strongly recommended to go through this tutorial before moving on to the WUDAPT/SUEWS tutorial.

Model output may be needed in many formats depending on a users’ needs. Thus, the format must be useful, while ensuring the science included within the model is appropriate. Fig. 9.13 shows the overall structure of UMEP, a city based climate service tool (CBCST) used in this tutorial. Within UMEP there are a number of models which can predict and diagnose a range of meteorological processes.

_images/SUEWSIntro_UMEP_overview.png

Overview of the climate service tool UMEP (from Lindberg et al. 2018)

Note

This tutorial is currently designed to work with QGIS 2.18. It is recommended that you have a look at the tutorials Urban Energy Balance - SUEWS Introduction and Urban Energy Balance - SUEWS Advanced before you go through this tutorial.

Objectives

To perform and analyse energy exchanges within a small area on Manhattan, NYC.

Steps to be preformed
  1. Pre-process the data and create input datasets for the SUEWS model
  2. Run the model
  3. Analyse the results
  4. Perform simple mitigation measures to see how it affects the model results (optional)

Initial Steps

UMEP is a Python plugin used in conjunction with QGIS. To install the software and the UMEP plugin see the getting started section in the UMEP manual.

As UMEP is under development, some documentation may be missing and/or there may be instability. Please report any issues or suggestions to our repository.

Loading and analyzing the spatial data

All the geodata used in this tutorial are from open access sources, primarily from the New York City. Information about the data are found in the table below.

Note

You can download the all the data from here. Unzip and place in a folder that you have read and write access to.

Spatial data used in this tutorial
Geodata Year Source Description
Digital surface model (DSM) 2013 (Lidar), 2016 (building polygons) United States Geological Survey (USGS). New York CMGP Sandy 0.7m NPS Lidar and NYC Open Data Portal. link A raster grid including both buildings and ground given in meter above sea level.
Digital elevation model (DEM) 2013 United States Geological Survey (USGS). New York CMGP Sandy 0.7m NPS Lidar. link A raster grid including only ground heights given in meter above sea level.
Digital canopy model (CDSM) 2013 (August) United States Geological Survey (USGS). New York CMGP Sandy 0.7m NPS Lidar. link A vegetation raster grid where vegetation heights is given in meter above ground level. Vegetation lower than 2.5 meter pixels with no vegetation should be zero.
Land cover (UMEP formatted) 2010 New York City Landcover 2010 (3ft version). University of Vermont Spatial Analysis Laboratory and New York City Urban Field Station. link A raster grid including: 1. Paved surfaces, 2. Building surfaces, 3. Evergreen trees and shrubs, 4. Deciduous trees and shrubs, 5. Grass surfaces, 6. Bare soil, 7. Open water
Population density (residential) 2010 2010 NYC Population by Census Tracts, Department of City Planning (DCP). link) People per census tract converted to pp/ha. Converted from vector to raster.
Land use 2018 NYC Department of City Planning, Technical Review Division. link Used to redistribute population during daytime (see text). Converted from vector to raster
  • Start by loading all the raster datasets into an empty QGIS project.

The order in the Layers Panel determines what layer is visible. You can choose to show a layer (or not) with the tick box. You can modify layers by right-clicking on a layer in the Layers Panel and choose Properties. Note for example that that CDSM (vegetation) is given as height above ground (meter) and that all non-vegetated pixels are set to zero. This makes it hard to get an overview of all 3D objects (buildings and trees). QGIS default styling for a raster is using the 98 percentile of the values. Therefore, not all the range of the data is shown in the layer window to the left.

  • Right-click on your CDSM layer and go to Properties > Style and choose Singleband pseudocolor with a min value of 0 and max of 35. Choose a colour scheme of your liking.
  • Go to Transparency and add an additional no data value of 0. Click ok.
  • Now put your CDSM layer at the top and your DSM layer second in your Layers Panel. Now you can see both buildings and vegetation 3D object in your map canvas.
none

DSM and CDSM visible at the same time (click for larger image)

The land cover grid comes with a specific QGIS style file.

  • Right-click on the land cover layer (landcover_2010_nyc) and choose Properties. Down to the left you see a Style-button. Choose Load Style and open landcoverstyle.qml and click OK.
  • Make only your land cover class layer visible to examine the spatial variability of the different land cover classes.

The land cover grid has already been classified into the seven different classes used in most UMEP applications (see Land Cover Reclassifier). If you have a land cover dataset that is not UMEP formatted you can use the Land Cover Reclassifier found at UMEP > Pre-processor > Urban Land Cover > Land Cover Reclassifier in the menubar to reclassify your data.

Furthermore, a polygon grid (500 m x 500 m) to define the study area and individual grids is included (Grid_500m.shp). Such a grid can be produced directly in QGIS (e.g. Vector > Research Tools > Vector Grid) or an external grid can be used.

  • Load the vector layer Grid_500m.shp into your QGIS project.
  • In the Style tab in layer Properties, choose a Simple fill with a No Brush fill style to be able to see the spatial data within each grid.
  • Also, add the label IDs for the grid to the map canvas in Properties > Labels to make it easier to identify the different grid squares later on in this tutorial.

As you can see the grid does not cover the whole extent of the raster grids. This is to reduce computation time during the tutorial. One grid cell takes ~20 s to model with SUEWS with meteorological forcing data for a full year.

Meteorological forcing data

Meteorological forcing data are mandatory for most of the models within UMEP. The UMEP specific format is given in Table 9.2. Some of the variables are optional and if not available or needed should be set to -999. The columns can not be empty. The needed data for this tutorial are discussed below.

Variables included in UMEP meteorological input file.
No. Header Description Accepted range Comments
1 iy Year [YYYY] Not applicable  
2 id Day of year [DOY] 1 to 365 (366 if leap year)  
3 it Hour [H] 0 to 23  
4 imin Minute [M] 0 to 59  
5 qn Net all-wave radiation [W m-2] -200 to 800  
6 qh Sensible heat flux [W m-2] -200 to 750  
7 qe Latent heat flux [W m-2] -100 to 650  
8 qs Storage heat flux [W m-2] -200 to 650  
9 qf Anthropogenic heat flux [W m-2] 0 to 1500  
10 U Wind speed [m s-1] 0.001 to 60  
11 RH Relative Humidity [%] 5 to 100  
12 Tair Air temperature [°C] -30 to 55  
13 pres Surface barometric pressure [kPa] 90 to 107  
14 rain Rainfall [mm] 0 to 30 (per 5 min) this should be scaled based on time step used
15 kdown Incoming shortwave radiation [W m-2] 0 to 1200  
16 snow Snow [mm] 0 to 300 (per 5 min) this should be scaled based on time step used
17 ldown Incoming longwave radiation [W m-2] 100 to 600  
18 fcld Cloud fraction [tenths] 0 to 1  
19 wuh External water use [m3] 0 to 10 (per 5 min) scale based on time step being used
20 xsmd (Observed) soil moisture 0.01 to 0.5 [m3 m-3 or kg kg-1]
21 lai (Observed) leaf area index [m2 m-2] 0 to 15  
22 kdiff Diffuse shortwave radiation [W m-2] 0 to 600  
23 kdir Direct shortwave radiation [W m-2] 0 to 1200 Should be perpendicular to the Sun beam. One way to check this is to compare direct and global radiation and see if kdir is higher than global radiation during clear weather. Then kdir is measured perpendicular to the solar beam.
24 wdir Wind direction [°] 0 to 360  

The meteorological dataset used in this tutorial (MeteorologicalData_NYC_2010.txt) is from NOAA (most of the meteorological variables) and NREL (solar radiation data). It consists of tab-separated hourly air temperature, relative humidity, incoming shortwave radiation, pressure, precipitation and wind speed for 2010. There are other possibilities within UMEP to acquire meteorological forcing data. The pre-processor plugin WATCH can be used to download the variables needed from the global WATCH forcing datasets (Weedon et al. 2011, 2014).

  • Open the meteorological dataset (MeteorologicalData_NYC_2010.txt) in a text editor of your choice. As you can see it does not include all the variables shown in Table 9.2. However, these variables are the mandatory ones that are required to run SUEWS. In order to format (and make a quality check) the data provided into UMEP standard, you will use the MetPreProcessor.
  • Open MetDataPreprocessor (UMEP> Pre-Processor -> Meteorological Data > Prepare existing data).
  • Load MeteorologicalData_NYC_2010.txt and make the settings as shown below. Name your new dataset NYC_metdata_UMEPformatted.txt.
none

The settings for formatting met data into UMEP format (click for a larger image)

  • Close the Metdata preprocessor and open your newly fomatted datset in a text editor of your choice. Now you see that the forcing data is structured into the UMEP pre-defined format.
  • Close your text file and move on to the next section of this tutorial.

Preparing input data for the SUEWS model

A key capability of UMEP is to facilitate preparation of input data for the various models. SUEWS requires input information to model the urban energy balance. The plugin SUEWS Prepare is for this purpose. This tutorial makes use of high resolution data but WUDAPT datasets in-conjuction with the LCZ Converter can be used (UMEP > Pre-Processor > Spatial data > LCZ Converter).

  • Open SUEWS Prepare (UMEP > Pre-Processor > SUEWS prepare).
none

The dialog for the SUEWS Prepare plugin (click for a larger image).

Here you can see the various settings that can be modified. You will focus on the Main Settings tab where the mandatory settings are chosen. The other tabs include the settings for e.g. different land cover classes, human activities etc.

There are 10 frames included in the Main Settings tab where 8 need to be filled in for this tutorial:

  1. Polygon grid
  2. Building morphology
  3. Tree morphology
  4. Land cover fractions
  5. Meteorological data
  6. Population density
  7. Daylight savings and UTC
  8. Initial conditions

The two optional frames (Land use fractions and Wall area) should be used if the ESTM model is used to estimate the storage energy term (Delta QS). In this tutorial we use the OHM modelling scheme so these two tabs can be ignored for now.

  • Close SUEWS Prepare
Building morphology

First you will calculate roughness parameters based on the building geometry within your grids.

  • Open UMEP > Pre-Processor > Urban Morphology > Morphometric Calculator (Grid).
  • Use the settings as in the figure below and press Run.
  • When calculation ids done, close the plugin.

Note

For mac users, use this workaround: manually create a directory, go into the folder above and type the folder name. It will give a warning “—folder name–” already exists. Do you want to replace it? Click replace.

none

The settings for calculating building morphology.

This operation should have produced 17 different text files; 16 (anisotrophic) that include morphometric parameters from each 5 degree section for each grid and one file (isotropic) that includes averaged values for each of the 16 grids. You can open build_IMPGrid_isotropic.txt and compare the different values for a park grid (3054) and an urban grid (3242). Header abbreviations are explained here.

Tree morphology

Now you will calculate roughness parameters based on the vegetation (trees and bushes) within your grids. As you noticed there is only one surface dataset for vegetation present (CDSM_nyc) and if you examine your land cover grid (landcover_2010_nyc) you can see that there is only one class of high vegetation (Deciduous trees) present with our model domain. Therefore, you will not separate between evergreen and deciduous vegetation in this tutorial. As shown in Table 9.1, the tree surface model represents height above ground.

  • Again, Open UMEP > Pre-Processor > Urban Morphology > Morphometric Calculator (Grid).
  • Use the settings as in the figure below and press Run.
  • When calculation is done, close the plugin.
_images/SUEWSSpatial_IMCGVeg.png

The settings for calculating vegetation morphology.

Land cover fractions

Moving on to land cover fraction calculations for each grid.

  • Open UMEP > Pre-Processor > Urban Land Cover > Land Cover Fraction (Grid).
  • Use the settings as in the figure below and press Run.
  • When calculation is done, close the plugin.
_images/SUEWSSpatial_LCF.png

The settings for calculating land cover fractions

Population density

Population density will be used to estimate the anthropogenic heat release (QF) in SUEWS. There is a possibility to use both night-time and daytime population densities to make the model more dynamic. You have two different raster grids for night-time (pop_nighttime_perha) and daytime (pop_daytime_perha), respectively. This time you will make use of QGIS built-in function to to acquire the population density for each grid.

  • Go to Plugins > Manage and Install Plugins and make sure that the Zonal statistics plugin is ticked. This is a build-in plugin which comes with the QGIS installation.
  • Close the Plugin manager and open Raster > Zonal Statistics > Zonal Statistics.
  • Choose your pop_daytime_perha layer as Raster layer and your Grid_500m and polygon layer. Use a Output column prefix of PPday and chose only to calculate Mean. Click OK.
  • Run the tool again but this time use the night-time dataset.
SUEWS Prepare

Now you are ready to organise all the input data into the SUEWS input format.

  • Open SUEWS Prepare
  • In the Polygon grid frame, choose your polygon grid (Grid_500m) and choose id as your ID field
  • In the Building morphology frame, fetch the file called build_IMPGrid_isotropic.txt.
  • In the Land cover fractions frame, fetch the file called lc_LCFG_isotropic.txt.
  • In the Tree morphology frame, fetch the file called veg_IMPGrid_isotropic.txt.
  • In the Meteorological data frame, fetch your UMEP formatted met forcing data text file.
  • In the Population density frame, choose the appropriate attributes created in the previous section for daytime and night-time population density.
  • In the Daylight savings and UTC frame, set start and end of the daylight saving to 87 and 304, respectively and choose -5 (i.e. the time zone).
  • In the Initial conditions frame, choose Winter (0%) in the Leaf Cycle, 100% Soil moisture state and nyc as a File code.
  • In the Anthropogenic tab, change the code to 771. This will make use of settings adjusted for NYC according to Sailor et al. 2015.
  • Choose an empty directory as your Output folder in the main tab.
  • Press Generate
  • When processing is finished, close SUEWS Prepare.

Running the SUEWS model in UMEP

To perform modelling energy fluxes for multiple grids, Urban Energy Balance - SUEWS Advanced can be used.

  • Open UMEP > Processor > Urban Energy Balance > SUEWS/BLUEWS, Advanced. Here you can change some of the run control settings in SUEWS. SUEWS can also be executed outside of UMEP and QGIS (see SUEWS Manual. This is recommended when modelling long time series (multiple years) of large model domains (many grid points).
  • Change the OHM option to [1]. This allows the anthropogenic energy to be partitioned also into the storage energy term.
  • Leave the rest of the combobox settings at the top as default and tick both the Use snow module and the Obtain temporal resolution… box.
  • Set the Temporal resolution of output (minutes) to 60.
  • Locate the directory where you saved your output from SUEWSPrepare earlier and choose an output folder of your choice.
  • Also, Tick the box Apply spin-up using…. This will force the model to run twice using the conditions from the first run as initial conditions for the second run.
  • Click Run. This computation will take a while so be patient.

Analysing model reults

UMEP has a tool for basic analysis of any modelling performed with the SUEWS model. The SUEWSAnalyser tool is available from the post-processing section in UMEP.

  • Open UMEP > Post-Processor > Urban Energy Balance > SUEWS Analyzer. There are two main sections in this tool. The Plot data-section can be used to make temporal analysis as well as making simple comparisins between two grids or variables. This Spatial data-section can be used to make aggregated maps of the output variables from the SUEWS model. This requires that you have loaded the same polygon grid into your QGIS project that was used when you prepared the input data for SUEWS using SUEWS Prepare earlier in this tutorial.
none

The dialog for the SUEWS Analyzer tool.

To access the output data from the a model run, the RunControl.nml file for that particular run must be located. If your run has been made through UMEP, this file can be found in your output folder. Otherwise, this file can be located in the same folder from where the model was executed.

  • In the top panel of SUEWS Analyzer, load the RunControl.nml located in the output folder.

You will start by plotting basic data for grid 3242 which is one of the most dense urban area in the World.

  • In the left panel, choose grid 3242 and year 2010. Tick plot basic data and click Plot. This will display some of the most essential variables such as radiation balance and budget etc. You can use the tools such as the zoom to examine a shorter time period more in detail.
none

Basic plot for grid 3242. Click on image for enlargement.

Notice e.g. the high QF values during winter as well as the low QE values throughout the year.

  • Close the plot and make the same kind of plot for grid 3054 which is a grid mainly within Central Park. Consider the differences between the plot generated for grid 3242. Close the plot when you are done.

In the left panel, there is also possibilities to examine two different variables in time, either from the same grid or between two different grid points. There is also possible to examine different parameters through scatterplots.

The right panel in SUEWS Analyzer can be used to perform basic spatial analysis on your model results by producing aggragated maps etc. using different variables and time spans. Sensible heat (QH) is one variable to visualise warm areas as it is a variable that show the amount of the available energy that will be partitioned into heat.

  • Make the settings as shown in the figure below but change the location where you will save your data on your own system.
none

The dialog for the SUEWS Analyzer tool to produce a mean QH for each grid. Click on image for enlargement.

Note that the warmest areas are located in the most dense urban environments and the coolest are found where either vegetation and/or water bodies are present. During 2010 there was a 3-day heat-wave event in the region around NYC that lasted from 5 to 8 July 2010 (Day of Year: 186-189).

  • Make a similar average map but this time of 2m air temperature and choose only the heat wave period. Save it as a separate geoTiff.

The influence of mitigation measures on the urban energy balance (optional)

There are different ways of manipulating the data using UMEP as well directly changing the input data in SUEWS to examine the influence of mitigation measures on the UEB. The most detailed way would be to directly changing the surface data by e.g. increasing the number of street trees. This can be done by e.g. using the TreeGenerator-plugin in UMEP. This method would require that you go through the workflow of this tutorial again before you do your new model run. Another way is to directly manipulate input data to SUEWS at grid point level. This can done by e.g. changing the land cover fractions in SUEWS_SiteSelect.txt, the file that includes all grid-specific information used in SUEWS.

  • Make a copy of your whole input folder created from SUEWSPRepare earlier and rename it to e.g. Input_mitigation.
  • In that folder remove all the files beginning with InitialConditions except the one called InitialConditionsnyc_2010.nml.
  • Open SUEWS_SiteSelect.txt in Excel (or similar software).
  • Now increace the fraction of decidious trees (Fr_DecTr) for grid 3242 and 3243 by 0.2. As the total land cover fraction has to be 1 you also need to reduce the paved fraction (Fr_Paved) by the same amount.
  • Save and close. Remember to keep the format (tab-separated text).
  • Create an empty folder called Output_mitigation
  • Open SuewsAdvanced and make the same settings as before but change the input and output folders.
  • Run the model.
  • When finished, create a similar average air temperature map for the heat event and compare the two maps. You can do a difference map by using the Raster Calculator in QGIS (Raster>Raster Calculator…).

Tutorial finished.

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS and WUDAPT

Introduction

Note

This tutorial is not ready for use. Work in progress.

In this tutorial you will generate input data for the SUEWS model and simulate spatial (and temporal) variations of energy exchanges within an area in New York City using local climate zones derived within the WUDAPT project. The World Urban Database and Access Portal Tools project is a community-based project to gather a census of cities around the world.

Note

This tutorial is currently designed to work with QGIS 2.18. It is strongly recommended that you goo through the Urban Energy Balance - SUEWS Spatial tutorial before you go through this tutrial.

Objectives

To prepare input data for the SUEWS model using a WUDAPT dataset and analyse energy exchanges within an area in New York City, US.

Initial Steps

UMEP is a python plugin used in conjunction with QGIS. To install the software and the UMEP plugin see the getting started section in the UMEP manual.

As UMEP is under development, some documentation may be missing and/or there may be instability. Please report any issues or suggestions to our repository.

Loading and analyzing the spatial data

Note

You can download the all the data from here. Unzip and place in a folder where you have read and write access to. The LCZ data for various cities are also available from the WUDAPT portal.

  • Start by loading the raster dataset (NYC_LCZ.tif) into an empty QGIS project. This dataset is referenced to the WGS84 CRS (ESPG:4326).
  • You can set the correct colors for your LCZ raster by opening the LCZ converter at UMEP > Pre-Processer > Spatial data > LCZ converter. In the upper right corner, choose the LCZ raster and press Color Raster and then close the LCZ Converter.

Vector grid generation

A vector polygon grid is required for specifying the extent and resolution of the modelling.You will make use of a built-in tool in QGIS to generate such a grid.

  1. First zoom in to Manhattan as shown in the figure below
none

Zoom in the Manhattan island.

  1. As WGS84 (EPSG:4326) is in degree coordinates and maybe you want to specify your grid in meters, you need to change the CRS of your current QGIS-project. Click on the globe at the bottom right of your QGIS window and select ESPG:26918 as your ‘on the fly’ CRS.
  2. Open vector grid at Vector > Research Tools > Vector grid.
  3. Select the extend of your canvas by clicking the … next to Grid extent (xmin, xmax, ymin, ymax) and select Use layer/canvas extent.
  4. Select Use Canvas Extent.
  5. As you can see the units in now in meters and not in degrees. Specify the desired grid spacing to 5000 meters. This will save time later on. Of course you can set it a much smaller number if you have the time to wait when the model performs the calculations later on.
  6. Make sure the output is in polygons, not lines.
  7. Create as temporary layer.
  8. Save your grid by right-click on the new layer in the Layers Panel and choose Save as…. Here it is very imporant that you save in the same CRS as you other layers (ESPG:4326). Save as a shape file.

Population density

Population density is required to estimate the anthropogenic heat release (QF) in SUEWS. There is a possibility to make use of both night-time and daytime population densities to make the model more dynamic. In this tutorial you will only use a night-time dataset. This dataset can be aqcuired from the Spatial Data Downloader in UMEP.

  1. Open de spatial downloader at UMEP > Pre-Processer > Spatial data > Spatial Data Downloader.

  2. Select population density and select the GPWv4: UN-Adjusted Population Density closest to the year you intend to model (2010). The values will be in (pp / square kilometer).

  3. Make sure your canvas is zoomed out to the entire LCZ map and click Use canvas extent

  4. Now click Get data.

  5. Save as a geoTiff (.tif) with the name GPWv4_2010.

  6. Now you need to calculate population density per grid in units pp/hectare. First open the QGIS built-in tool Zonal statistics (Raster > Zonal Statistics). If the tool is absent you need to activate it by going to Plugins > Manage and Install Plugins and add Zonal statistics plugin. Open the tool and make the settings as shown below. This will calulate mean population density per grid.

    none

    Settings for the Zonal statistics plugin.

  7. Open the attribute table for your Grid_5000m-layer (right-click on layer and choose (Open attribute Table).

  8. Click the abacus shaped symbol this is the Field calculator.

  9. Under Output field name write “pp_ha, the Output field type should be “Decimal number (real)”, and the Output Precision can be set to 2.

  10. In the expression dialog box write gpw_mean/100, here gpw_mean is the name of your population density field and the 100 is to convert the data from km2 to ha.

  11. Click OK and you should have a new field called “pp_ha”.

  12. Click the yellow pencil in the top left corner of the attribute table to stop editing and save your changes and close the attribute table.

LCZ converter

Now you will make use of the LCZ Converter-plugin to generate input data for the SUEWS model.

  1. Open the LCZ converter at UMEP > Pre-Processer > Spatial data > LCZ converter.
  2. Select the LCZ raster layer at ‘’ LCZ raster’‘.
  3. Select the vector grid you have just created in step 3 at Vector grid and select the ID field of the polygon grid at ID field.
  4. By clicking Adjust default parameters you can edit the table. This table specifies the pervious, trees, grass, etc. fractions for each of the LCZ classes. For more information about each of the classes see LCZConverter. If you choose to edit the table, make sure all fractions add up to 1.0.
  5. If you are unsure about the exact fractions for each of the LCZ click the tab Pervious distribution. Select Same for all LCZ’s
none

Settings for the LCZ converter plugin.

  1. Now you can select your best estimate about the distribution of the pervious surface fractions for urban and the tree distribution for rural. In addition, also specify the expected height of the trees.
  2. Once you are satisfied click Update Table.
  3. Select add results to polygon.
  4. Add a file prefix if desired.
  5. Finally select an output folder where you would like to receive the text files and click Run.

Note

For mac users use this workaround: manually create a directory, go into the folder above and type the folder name. It will give a warning “—folder name–” already exists. Do you want to replace it? Click replace.

This should generate 3 text files, one with the land cover fractions, one with morphometric parameters for buildings and one for trees for each grid cell of the polygon grid.

SUEWS

Before running SUEWS, you will need to prepare some of the data required to run it.

  1. SUEWS prepare requires the grid CRS to be in metres not degrees, therefore we need to reproject the grid. Right-click the vector grid and click save as... Assign a different file name, use CRS ESPG:26918 and click OK.
  2. Open SUEWS prepare at: UMEP > Pre-Processer > SUEWS prepare.
  3. Under vector polygon grid specify your reprojected vector grid and the ID field.
  4. Select the location of the Meteorological file that was included in the input data, the building morphology (_build_), tree morphology (_veg_) and land cover fractions (_LCFGrid_) from the step above and the population density (pp_ha) in the dropdown list.
  5. Enter the start and end of day light savings time for 2010 and the UTC offset of New York.
  6. Specify the Leaf cycle = winter when initialising in January. Unless the user has better information initialise the Soil moisture state at 100 %.
  7. Select an output folder where the initial data to run SUEWS should be saved and press Generate.
  8. Open SUEWS at UMEP > Processer > Urban Energy Balance > Urban Energy Balance (SUEWS/BLUEWS, advanced). Using this for the first time, the system will ask you to download the latest version of SUEWS, click OK.
  9. Change the OHM option to [1]. This allows the anthropogenic energy to be partitioned also into the storage energy term.
  10. Leave the rest of the combobox settings at the top as default and tick both the Use snow module and the Obtain temporal resolution… box.
  11. Set the Temporal resolution of output (minutes) to 60.
  12. Locate the directory where you saved your output from SUEWSPrepare earlier and choose an output folder of your choice.
  13. Also, Tick the box Apply spin-up using…. This will force the model to run twice using the conditions from the first run as initial conditions for the second run.
  14. Click Run. This computation will take a while so be patient. If it only takes a very short time (a few seconds) the model has probably crashed. Please consult the problems.txt file for more information.

Analysing model reults

When the model has successfully run, it is time to look at some of the output of the model. The SUEWSAnalyser tool is available from the post-processing section in UMEP.

  1. To better visualise what would be interesting to plot, label the grid ID’s of your vector grid. Do this by right-clicking the vector grid, going to properties, under the Labels tab click Show labels for this layer, label with id and select a text format of your choosing.
  2. Open UMEP > Post-Processor > Urban Energy Balance > SUEWS Analyzer. There are two main sections in this tool. The Plot data-section can be used to make temporal analysis as well as making simple comparisins between two grids or variables. This Spatial data-section can be used to make aggregated maps of the output variables from the SUEWS model. This requires that you have loaded the same polygon grid into your QGIS project that was used when you prepared the input data for SUEWS using SUEWS Prepare earlier in this tutorial.
  3. To access the output data from the a model run, the RunControl.nml file for that particular run must be located. If your run has been made through UMEP, this file can be found in your output folder. Otherwise, this file can be located in the same folder from where the model was executed. In the top panel of SUEWS Analyzer, load the RunControl.nml located in the output folder.

Feel free to try plotting different variables, first let’s try and look at a variable for two different grid cells.

  1. Load the RunControl.nml located in the output folder.
  2. On the left hand specify a Grid cell that is largely urban, select Year to investigate. Select the desired time period and a variable, for example Sensible heat flux.
  3. Comparing with another less urbanised gridcell turn on include another variable and specify the desired Grid, selecting the same Variable (Sensible heat flux).
  4. Click plot.
none

Example of the comparison of the heat flux for two grid cell in the vector grid.

Now we will look at the horizontal distribution of the storage flux. #. On the right-hand side of SUEWS analyser specify the Net Storage flux as a variable to analyse. #. Select the Year to investigate and a time period during the summer season. #. Select the Median and Only daytime. #. Select the Vector polygon grid you have been using and save as a GeoTiff. #. Specify an output filename, and tick Add Geotiff to map canvas and Generate.

none

Example of the median, night-time net storage flux.

This should generate a geotiff file with a median, night-time net storage flux in the selected timeperiod.

Tutorial finished.

Note

Please report issues with the manual on the GitHub page.

Development, Suggestions and Support

If you are interested in contributing to the code please contact Sue Grimmond. Please follow Coding Guidelines for coding SUEWS.

Please provide your feedbacks via channels listed here.

Note

Please report issues with the manual on the GitHub page.

Coding Guidelines

If you are interested in contributing to the code please contact Sue Grimmond.

Coding

  1. Core physics and calculatoin schemes of SUEWS are written in Fortran 90

  2. Code is hosted in GitHub as private repository

  3. Variables

    • Names should be defined at least in one place in the code – ideally when defined

    • Implicit None should be used in all subroutines

    • Variable name should include units. e.g. Temp_C, Temp_K

    • Output variable attributes should be provided in the TYPE structure defined in the ctrl_output module as follows:

      : TYPE varAttr
      : CHARACTER(len = 15) :: header ! short name in headers
      : CHARACTER(len = 12) :: unit   ! unit
      : CHARACTER(len = 14) :: fmt    ! output format
      : CHARACTER(len = 50) :: longNm ! long name for detailed description
      : CHARACTER(len = 1)  :: aggreg ! aggregation method
      : CHARACTER(len = 10) :: group  ! group: datetime, default, ESTM, Snow, etc.
      : INTEGER             :: level  ! output priority level: 0 for highest (defualt output)
      : END TYPE varAttr
      
  4. Code should be written generally

  5. Data set for testing should be provided

  6. Demonstration that the model performance has improved when new code has been added or that any deterioration is warranted.

  7. Additional requirements for modelling need to be indicated in the manual

  8. All code should be commented in the program (with initials of who made the changes – name specified somewhere and institution)

  9. The references used in the code and in the equations will be collected to a webpage

  10. Current developments that are being actively worked on

Testing

  1. The testing of SUEWS is done using Python 3
  2. The following tests are done for each release of SUEWS:
  1. Working status of all physics schemes
  2. Year-grid looping logic
  3. Identity of output results with internal test dataset

Please use pre-defined make test option to check if your code can pass all tests or not. If not, the correctness of added code should be justified with caution.

Preparation of SUEWS Manual

  1. The SUEWS manual is written in reStructuredText (aka rst) with a Sphinx flavour
  2. The SUEWS manual is hosted by readthedocs.org
  3. CSV tables used in following pages are automatically generated from the Description field in Input Options by each build, so DON’T manually edit them as your edits will be swiped automatically:

F2PY tips

This includes several DON’T’s that have never been mentioned by F2PY docs:

  1. DON’T mix comments as lines into argument list of Fortran subroutines/functions:

DONT:

subroutine(&
! DONT DO this
args&
)

OK:

subroutine(&
args& ! OK this way
)

2. DON’T end a subroutine as ENDSUBROUTINE. Instead, leave a space in between to form END SUBROUTINE. Otherwise, the subroutines won’t be correctly parsed and picked up by F2PY.

Note

Please report issues with the manual on the GitHub page.

Suggestions and Support

Please provide your feedbacks via these channels:

Note

Please report issues with the manual on the GitHub page.

Benchmark Report

Since v2018a, SUEWS is benchmarked against observations for assessment of model performance. A site based benchmark report generation system is introduced in v2018c to produce detailed reports for testing sites; the number of sites is expanding and more cases will be added as they are benchmarked.

Each report includes the following parts:

  1. Overall performance:
  1. Performance Score: Large scores indicate better performance. The scores are calculated according to weighted averages of statistics for selected benchmark variables.
  2. Detailed Statistics: Grids are coloured based relative performance between different versions: a greener grid indicates better performance in the chosen variable using the specific release whereas a redder one shows poorer performance; and those with gray backgrounds indicate the same performance across different releases.
  1. Cross-comparison in model variables between releases:
  1. Detailed statistics tables: statistics for each variable.
  2. Pair plots: comparison in simulation results between different version-pairs.
  3. Time series plots: comparison in simulated monthly climatologies of diurnal cycles of each variable between different version-pairs.

The latest benchmark reports are available at the SUEWS Benchmark site.

Note

Please report issues with the manual on the GitHub page.

API

This link redirects to the SUEWS API site, which provides documentation of SUEWS source code automatically generated by Doxygen.

SUEWS developers are strongly suggested to use the API site as the main reference for understanding SUEWS source code.

Note

Please report issues with the manual on the GitHub page.

Version History

Note

Please report issues with the manual on the GitHub page.

Version 2019a (released on 15 November 2019)

  • Improvement

    1. An anthropogenic emission module is added. Module details refer to Järvi et al. (2019) [J19].
    2. A canyon profile module is added. Module details refer to Theeuwes et al. (2019) [T19].
  • Changes

    1. Input file SUEWS_AnthropogenicHeat.txt is renamed to SUEWS_AnthropogenicEmission.txt with new parameters added: MinFCMetab, MaxFCMetab, FrPDDwe, FcEF_v_kgkmWD and FcEF_v_kgkmWE.
    2. BLUEWS has been recovered; set CBLUse to use it.
    3. Removed features:
    • SOLWEIG: fully removed from code.
    • netCDF: fully removed as this is very infrequently used; users who need this are suggested to use SuPy with help from pandas and xarray to save results in netCDF more elegantly.
  • Fix

    1. Fixed a bug in LAI calculation for longterm runs.
    2. Fixed a bug in net all-wave radiation differential calculation for OHM.
    3. Fixed a bug in GDD/SDD calculation that different vegetative land covers could unexpectedly affect each other.
    4. Fixed water redistribution bug in snow module.
  • Known issues

    1. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2018c (released on 21 February 2019)

  • Improvement

    1. SuPy (SUEWS in Python): a Python-enhanced wrapper of SUEWS, which can facilitate a more fluent workflow of SUEWS-centred urban climate research. More details refer to SuPy documentation site.
    2. Improved benchmark report: More testing sites are added thanks to an automated benchmark report system.
  • Changes

    None.

  • Fix

    1. Fixed a bug in LAI calculation for longterm runs.
    2. Fixed a bug in net all-wave radiation differential calculation for OHM.
    3. Fixed water redistribution bug in snow module.
  • Known issues

    1. BLUEWS is disabled
    2. Observed soil moisture can not be used as an input
    3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2018b (released 17 December 2018)

  • Improvement

    1. Improved calculation of OHM-related radiation terms:

      The temporal difference term dQ*/dt is now calculated using the time-step-weighted dQ* of previous time step instead of a series of Q* values from previous time steps, which improves the usage of memory and allows time-step-varying simulations (needed by WRF-SUEWS coupling).

  • Changes

    None.

  • Fix

    1. Fixed a bug in picking up external water use from meteorological forcing file.
  • Known issues

    1. BLUEWS is disabled
    2. Observed soil moisture can not be used as an input
    3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2018a (released 2 August 2018)

  • New
    1. Many under-the-hood improvements:
      • Added explicit interface intent for confusion-less coupling between SUEWS modules
      • Restructured layout of physics schemes for better modularity
      • Improved the alignment in output txt files
    2. New readthedocs.org-based documentation system
    3. Added SUEWS input converter for conversion of input files between versions
    4. Added Benchmark Report for recent releases.
  • Improvement
    1. Improved the near surface diagnostics scheme (T2, Q2, U10)
    2. Improved skin temperature calculation (Ts)
  • Changes
    1. StabilityMethod: recommended option is change from 2 to 3 as options other than 3 have been noticed with numerical issues under several scenarios, which will be fixed in the next release.
    2. Model run - changes in selections moved from SUEWS_SiteSelect.txt to SUEWS_AnthropogenicHeat.txt: EnergyUseProfWD, EnergyUseProfWE, ActivityProfWD, ActivityProfWE.
    3. BiogenCO2Code is added to SUEWS_Veg.txt for looking up biogenic characteristics in the new SUEWS_BiogenCO2.txt file.
    4. TraifficRate and BuildEnergyUse in SUEWS_SiteSelect.txt are expanded to allow weekday and weekend values: TrafficRate_WD, TrafficRate_WE, QF0_BEU_WD, QF0_BEU_WE.
    5. AnthropCO2Method is removed from RunControl.nml.
    6. AnthropHeatMethod is renamed to EmissionsMethod.
    7. AHMin, AHSlope and TCritic are expanded to allow weekday and weekend values by adding _WD and _WE as suffix, of which AHSlope and TCritic are also expanded to allow cooling and heating settings.
  • Known issues
    1. BLUEWS is disabled
    2. Observed soil moisture can not be used as an input
    3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2017b (released 2 August 2017)

PDF Manual for v2017b

  1. Surface-level diagnostics: T2 (air temperature at 2 m agl), Q2 (air specific humidity at 2 m agl) and U10 (wind speed at 10 m agl) added as default output.
  2. Output in netCDF format. Please note this feature is NOT enabled in the public release due to the dependency of netCDF library. Assistance in enabling this feature may be requested to the development team via SUEWS mail list.
  3. Edits to the manual.
  4. New capabilities being developed, including two new options for calculating storage heat flux (AnOHM, ESTM) and modelling of carbon dioxide fluxes. These are currently under development and should not be used in Version 2017b.
  5. Known issues
    1. BLUEWS parameters need to be checked
    2. Observed soil moisture can not be used as an input
    3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2017a (Feb 2017)

  1. Changes to input file formats (including RunControl.nml and InitialConditions files) to facilitate setting up and running the model. Met forcing files no longer need two rows of -9 at the end to indicate the end of the file.
  2. Changes to output file formats (now option to write out only a subset of variables, rather than all variables).
  3. SUEWS can now disaggregate forcing files to the model time-step and aggregate output at the model time-step to lower resolution. This removes the need for the python wrapper used with previous versions.
  4. InitialConditions format and requirements changed. A single file can now be provided for multiple grids. SUEWS will approximate most (but not all) of the required initial conditions if values are unknown. (However, if detailed information about the initial conditions is known, this can still be provided to and used by SUEWS.)
  5. Leaf area index calculations now use parameters provided for each vegetated surface (previously only the deciduous tree LAI development parameters were applied to all vegetated surfaces).
  6. For compatibility with GIS, the sign convention for longitude has been changed. Now negative values are to the west, positive values are to the east. Note this appears to have been incorrectly coded in previous versions (but may not necessarily have been problematic).
  7. Storage heat flux calculation adapted for shorter (sub-hourly) model time-step: hysteresis calculation now based on running means over the previous hour.
  8. Improved error handling, including separate files for serious errors (problems.txt) and less critical issues (warnings.txt).
  9. Edits to the manual.
  10. New capabilities being developed, including two new options for calculating storage heat flux (AnOHM, ESTM) and modelling of carbon dioxide fluxes. These are currently under development and should not be used in Version 2017a.

Note

Please report issues with the manual on the GitHub page.

Version 2016a (released 21 June 2016)

PDF Manual for v2016a

  1. Major changes to the input file formats to facilitate the running of multiple grids and multiple years. Surface characteristics are provided in SUEWS_SiteSelect.txt and other input files are cross-referenced via codes or profile types.
  2. The surface types have been altered:
    • Previously, grass surfaces were entered separately as irrigated grass and unirrigated grass surfaces, whilst the ‘unmanaged’ land cover fraction was assumed by the model to behave as unirrigated grass. There is now a single surface type for grass (total for irrigated plus unirrigated) and a new bare soil surface type.
    • The proportion of irrigated vegetation must now be specified for grass, evergreen trees and deciduous trees individually.
  3. The entire model now runs at a time step specified by the user. Note that 5 min is strongly recommended. (Previously only the water balance calculations were done at 5 min with the energy balance calculations at 60 min).
  4. Surface conductance now depends on the soil moisture under the vegetated surfaces only (rather than the total soil moisture for the whole study area as previously).
  5. Albedo of evergreen trees and grass surfaces can now change with leaf area index as was previously possible for deciduous trees only.
  6. New suggestions in Troubleshooting section.
  7. Edits to the manual.
  8. CBL model included.
  9. SUEWS has been incorporated into UMEP

Note

Please report issues with the manual on the GitHub page.

Version 2014b (released 8 October 2014)

PDF Manual for v2014b

These affect the run configuration if previously run with older versions of the model:

  1. New input of three additional columns in the Meteorological input file (diffusive and direct solar radiation, and wind direction)
  2. Change of input variables in InitialConditions.nml file. Note we now refer to CT as ET (ie. Evergreen trees rather than coniferous trees)
  3. In GridConnectionsYYYY.txt, the site names should now be without the underscore (e.g Sm and not Sm_)

Other issues:

  1. Number of grid areas that can be modelled (for one grid, one year 120; for one grid two years 80)
  2. Comment about Time interval of input data
  3. Bug fix: Column headers corrected in 5 min file
  4. Bug fix: Surface state 60 min file - corrected to give the last 5 min of the hour (rather than cumulating through the hour)
  5. Bug fix: units in the Horizontal soil water transfer
  6. ErrorHints: More have been added to the problems.txt file.
  7. Manual: new section on running the model appropriately
  8. Manual: notation table updated
  9. Possibility to add snow accumulation and melt: new paper

Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H, and Strachan IB Version 2014: Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities, Geosci. Model Dev. 7, 1691-1711, doi:10.5194/gmd-7-1691-Version 2014.

Note

Please report issues with the manual on the GitHub page.

Version 2014a.1 (released 26 February 2014)

  1. Please see the large number of changes made in the Version 2014a release.
  2. This is a minor change to address installing the software.
  3. Minor updates to the manual

Note

Please report issues with the manual on the GitHub page.

Version 2014a (released 21 February 2014)

  1. Bug fix: External irrigation is calculated as combined from automatic and manual irrigation and during precipitation events the manual irrigation is reduced to 60% of the calculated values. In previous version of the model, the irrigation was in all cases taken 60% of the calculated value, but now this has been fixed.
  2. In previous versions of the model, irrigation was only allowed on the irrigated grass surface type. Now, irrigation is also allowed on evergreen and deciduous trees/shrubs surfaces. These are not however treated as separate surfaces, but the amount of irrigation is evenly distributed to the whole surface type in the modelled area. The amount of water is calculated using same equation as for grass surface (equation 5 in Järvi et al. Version 2011), and the fraction of irrigated trees/shrubs (relative to the area of tree/shrubs surface) is set in the gis file (See Table 4.11: SSss_YYYY.gis)
  3. In the current version of the model, the user is able to adjust the leaf-on and leaf-off lengths in the FunctionalTypes. nml file. In addition, user can choose whether to use temperature dependent functions or combination of temperature and day length (advised to be used at high-latitudes)
  4. In the gis-file, there is a new variable Alt that is the area altitude above sea level. If not known exactly use an approximate value.
  5. Snow removal profile has been added to the HourlyProfileSSss_YYYY.txt. Not yet used!
  6. Model time interval has been changed from minutes to seconds. Preferred interval is 3600 seconds (1 hour)
  7. Manual correction: input variable Soil moisture said soil moisture deficit in the manual – word removed
  8. Multiple compiled versions of SUEWS released. There are now users in Apple, Linux and Windows environments. So we will now release compiled versions for more operating systems (section 3).
  9. There are some changes in the output file columns so please, check the respective table of each used output file.
  10. Bug fix: with very small amount of vegetation in an area – impacted Phenology for LUMPS

Note

Please report issues with the manual on the GitHub page.

Version 2013a

  1. Radiation selection bug fixed
  2. Aerodynamic resistance – when very low - no longer reverts to neutral (which caused a large jump) – but stays low
  3. Irrigation day of week fixed
  4. New error messages
  5. min file – now includes a decimal time column – see Section 5.4 – Table 5.3

Note

Please report issues with the manual on the GitHub page.

Version 2012b

  1. Error message generated if all the data are not available for the surface resistance calculations
  2. Error message generated if wind data are below zero plane displacement height.
  3. All error messages now written to ‘Problem.txt’ rather than embedded in an ErrorFile. Note some errors will be written and the program will continue others will stop the program.
  4. Default variables removed (see below). Model will stop if any data are problematic. File should be checked to ensure that reasonable data are being used. If an error occurs when there should not be one let us know as it may mean we have made the limits too restrictive.

Contents no longer used File defaultFcld=0.1 defaultPres=1013 defaultRH=50 defaultT=10 defaultU=3 RunControl.nml

  • Just delete lines from file
  • Values you had were likely different from these example value shown here

Note

Please report issues with the manual on the GitHub page.

Version 2012a

  1. Improved error messages when an error is encountered. Error message will generally be written to the screen and to the file ‘problems.txt’
  2. Format of all input files have changed.
  3. New excel spreadsheet and R programme to help prepare required data files. (Not required)
  4. Format of coef flux (OHM) input files have changed.
    • This allows for clearer identification for users of the coefficients that are actually to be used
    • This requires an additional file with coefficients. These do not need to be adjusted but new coefficients can be added. We would appreciate receiving additional coefficients so they can be included in future releases – Please email Sue.
  5. Storage heat flux (OHM) coefficients can be changed by
    • time of year (summer, winter)
    • surface wetness state
  6. New files are written: DailyState.txt
    • Provides the status of variables that are updated on a daily or basis or a snapshot at the end of each day.
  7. Surface Types
    • Clarification of surface types has been made. See GIS and OHM related files

Note

Please report issues with the manual on the GitHub page.

Version 2011b

  1. Storage heat flux (ΔQs) and anthropogenic heat flux (QF) can be set to be 0 W m-2
  2. Calculation of hydraulic conductivity in soil has been improved and HydraulicConduct in SUEWSInput.nml is replaced with name SatHydraulicConduct
  3. Following removed from HeaderInput.nml
    • HydraulicConduct
    • GrassFractionIrrigated
    • PavedFractionIrrigated
    • TreeFractionIrrigated

The lower three are now determined from the water use behaviour used in SUEWS

  1. Following added to HeaderInput.nml
    • SatHydraulicConduct
    • defaultQf
    • defaultQs
  2. If ΔQs and QF are not calculated in the model but are given as an input, the missing data is replaced with the default values.
  3. Added to SAHP input file
    • AHDIUPRF – diurnal profile used if EmissionsMethod = 1

Version 2012a this became obsolete OHM file (SSss_YYYY.ohm)

Note

Please report issues with the manual on the GitHub page.

Acknowledgements

Contributors

Name Affiliation Contributions Versions Remarks
Prof Sue Grimmond University of Reading, UK; prior: Indiana University, USA, King’s College London, UK, University of British Columbia, Canada OHM, Evaporation-Interception, Resistances, NARP, irrigation, anthropogenic heat, etc v2011b – v2019a Team Leader
Dr Ting Sun University of Reading, UK AnOHM; Documentation system; WRF-SUEWS coupling; SuPy (python wrapper of SUEWS) v2017b – v2019a Current Lead Developer
Dr Leena Järvi University of Helsinki, Finland Snow-related physics; Anthropogenic emission calculation, CO2 v2011b – v2019a Lead Developer of v2011b – v2014b
Dr Helen Ward University of Reading, UK OHM improvement; Resistance calculation; Anthropogenic heat calculation v2016a - v2017b Lead Developer of v2016a - v2017
Dr Fredrik Lindberg Göteborg University, Sweden UMEP-related work, NARP, ESTM v2011b – v2019a Lead Developer of UMEP
Dr Hamidreza Omidvar University of Reading, UK WRF-SUEWS coupling; Documentation system v2018c – v2019a Major contributor to WRF(v4.0)-SUEWS(v2018c) coupling
Minttu P. Havu University of Helsinki, Finland CO2 v2018c – v2019a  
Dr Zhenkun Li Shanghai Climate Centre, China WRF-SUEWS coupling v2018b – v2018c Major contributor to WRF(v3.9)-SUEWS(v2018b) coupling
Yihao Tang University of Reading, UK Stability, air temperature v2018b - v2018c  
Dr Shiho Onomura Göteborg University, Sweden BLUEWS, ESTM v2016a  
Dr Thomas Loridan King’s College London, UK NARP v2011a  
Dr Brian Offerle Indiana University, USA ESTM, NARP v2011a  

Dependency Libraries

Note

We gratefully acknowledge the libraries/code that SUEWS uses as dependency and greatly appreciate their developers for the excellent work. Please let us know if any inapproriate use of these code and we will remove/modify the related parts accordingly.

Library Remarks
datetime-fortran date and time related processsing
minpack AnOHM-related sinusoidal curve fitting
Recursive Fortran 95 quicksort routine netCDF output for QGIS-compliant grid layout
Fortran Strings Module by Dr George Benthien string processing

Funding

Note

The following grants are acknowledged for their contribution to model development (D) and/or supportive observations (O).

Funder Project D , O
NERC APEx D
NERC COSMA NE/S005889/ D
UKRI GCRF Urban Disaster Risk Hub D
Newton/Met Office CSSP-China (AJYG-DX4P1V HRC,AJYF-2GLAMK EUN, others) D, O
NERC ClearfLo Clean Air for London NE/H003231/1 O
NERC/Belmont TRUC NE/L008971/1, G8MUREFU3FP-2201-075 D, O
EPSRC LoHCool Low carbon climate-responsive Heating and Cooling of Cities EP/N009797/1 D
NERC Independent Research Fellowship D
NSF BCS-0095284, ATM-0710631, BCS-0221105 D, O
EPSRC Data Assimilation for the REsilient City (DARE) EP/P002331/1 O
Royal Society/Newton Mobility funding O
H2020 UrbanFluxes (637519) D, O
EUf7 BRIDGE (211345) D, O
EUf7 emBRACE (283201) D, O
University of Reading Sue Grimmond O, D
KCL Sue Grimmond O
EPSRC EP/I00159X/1 EP/I00159X/2 Materials Innovation Hub: Connecting Materials Culture to Materials Science O
NERC Field Spectroscopy Facility (FSF) 616.1110 Investigating the Urban Energy Balance of London O
EUf7 MEGAPOLI 212520 D
NERC Airborne Remote Sensing Facility & Field Spectroscopy Facility (GB08/19) O
CFCAS Environmental Prediction for Canadian Cities D, O

Note

Please report issues with the manual on the GitHub page.

Notation

λF
Frontal area index
ΔQS
Storage heat flux
BLUEWS

Boundary Layer part of SUEWS

Relation between BLUEWS and SUEWS

Relation between BLUEWS and SUEWS

CDD
Cooling degree days
GDD
Growing degree days
HDD
Heating degree days
Bldgs
Building surface
CBL
Convective boundary layer
DEM
Digital Elevation Model
DSM
Digital surface model
DTM
Digital Terrain Model
DecTr
Deciduous trees and shrubs
EveTr
Evergreen trees and shrubs
ESTM
Element Surface Temperature Method (Offerle et al.,2005 [OGF2005])
Grass
Grass surface
BSoil
Unmanaged land and/or bare soil
Runoff
The water that drains freely off the impervious surface
SoilStore
The water stored in the underlying soil that infiltrates from the pervious surface
L↓
Incoming longwave radiation
LAI
Leaf area index
LUMPS
Local-scale Urban Meteorological Parameterization Scheme (Loridan et al. 2011 [L2011])
MU
Parameters which must be supplied and must be specific for the site/grid being run.
MD
Parameters which must be supplied and must be specific for the site/grid being run (but default values may be ok if these values are not known specifically for the site).
O
Parameters that are optional, depending on the model settings in RunControl.nml. Set any parameters that are not used/not known to ‘-999’.
L
Codes that are used to link between the input files. These codes are required but their values are completely arbitrary, providing that they link the input files in the correct way. The user should choose these codes, bearing in mind that the codes they match up with in column 1 of the corresponding input file must be unique within that file. Codes must be integers. Note that the codes must match up with column 1 of the corresponding input file, even if those parameters are not used (in which case set all columns except column 1 to ‘-999’ in the corresponding input file), otherwise the model run will fail.
NARP
Net All-wave Radiation Parameterization (Offerle et al. 2003 [O2003], Loridan et al. 2011 [L2011])
OHM
Objective Hysteresis Model (Grimmond et al. 1991 [G91OHM], Grimmond & Oke 1999a [GO99QS], 2002 [GO2002])
Paved
Paved surface
Q*
Net all-wave radiation
QE
Latent heat flux
QF
Anthropogenic heat flux
QH
Sensible heat flux
SOLWEIG
The solar and longwave environmental irradiance geometry model (Lindberg et al. 2008 [FL2008], Lindberg and Grimmond 2011 [FL2011])
SVF
Sky view factor
θ
Potential temperature
tt
Time step of data
UMEP
Urban Multi-scale Environmental Predictor
Water
Water surface
WATCH
The WATCH project has produced a large number of data sets which should be of considerable use in regional and global studies of climate and water. see WATCH webpage
zi
Convective boundary layer height

Note

Please report issues with the manual on the GitHub page.

References

[J11]Järvi L, Grimmond CSB & Christen A (2011) The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver. J. Hydrol. 411, 219-237.
[W16]Ward HC, Kotthaus S, Järvi L and Grimmond CSB 2016: Surface Urban Energy and Water Balance Scheme (SUEWS): development and evaluation at two UK sites. Urban Climate. 18, 1-32 doi: 10.1016/j.uclim.2016.05.001
[G91]Grimmond CSB & Oke TR (1991) An Evaporation-Interception Model for Urban Areas. Water Resour. Res. 27, 1739-1755.
[O2003]Offerle B, Grimmond CSB & Oke TR (2003) Parameterization of Net All-Wave Radiation for Urban Areas. J. Appl. Meteorol. 42, 1157-1173.
[L2011]Loridan T, CSB Grimmond, BD Offerle, DT Young, T Smith, L Järvi, F Lindberg (2011) Local-Scale Urban Meteorological Parameterization Scheme (LUMPS): longwave radiation parameterization & seasonality related developments. Journal of Applied Meteorology & Climatology 50, 185-202, doi: 10.1175/2010JAMC2474.1
[lucy]Allen L, F Lindberg, CSB Grimmond (2011) Global to city scale model for anthropogenic heat flux, International Journal of Climatology, 31, 1990-2005.
[lucy2]Lindberg F, Grimmond CSB, Nithiandamdan Y, Kotthaus S, Allen L (2013) Impact of city changes and weather on anthropogenic heat flux in Europe 1995–2015, Urban Climate,4,1-13 paper
[I11]Iamarino M, Beevers S & Grimmond CSB (2011) High-resolution (space, time) anthropogenic heat emissions: London 1970-2025. International J. of Climatology. 32, 1754-1767.
[G91OHM]Grimmond CSB, Cleugh HA & Oke TR (1991) An objective urban heat storage model and its comparison with other schemes. Atmos. Env. 25B, 311-174.
[GO99QS]Grimmond CSB & Oke TR (1999a) Heat storage in urban areas: Local-scale observations and evaluation of a simple model. J. Appl. Meteorol. 38, 922-940.
[GO2002]Grimmond CSB & Oke TR (2002) Turbulent Heat Fluxes in Urban Areas: Observations and a Local-Scale Urban Meteorological Parameterization Scheme (LUMPS) J. Appl. Meteorol. 41, 792-810.
[AnOHM17]Sun T, Wang ZH, Oechel W & Grimmond CSB (2017) The Analytical Objective Hysteresis Model (AnOHM v1.0): Methodology to Determine Bulk Storage Heat Flux Coefficients. Geosci. Model Dev. Discuss. doi: 10.5194/gmd-2016-300.
[OGF2005]Offerle B, CSB Grimmond, K Fortuniak (2005) Heat storage & anthropogenic heat flux in relation to the energy balance of a central European city center. International J. of Climatology. 25: 1405–1419 doi: 10.1002/joc.1198
[G86]Grimmond CSB, Oke TR and Steyn DG (1986) Urban water-balance 1. A model for daily totals. Water Resour Res 22: 1397-1403.
[Leena2014]Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H & Strachan IB (2014) Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities, Geosci. Model Dev. 7, 1691-1711, doi:10.5194/gmd-7-1691-2014.
[CG2001]Cleugh HA & Grimmond CSB (2001) Modelling regional scale surface energy exchanges and CBL growth in a heterogeneous, urban-rural landscape. Bound.-Layer Meteor. 98, 1-31.
[Shiho2015]Onomura S, Grimmond CSB, Lindberg F, Holmer B & Thorsson S (2015) Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme Urban Climate,11, 1-23 doi:10.1016/j.uclim.2014.11.001
[FL2008]Lindberg F, Holmer B & Thorsson S (2008) SOLWEIG 1.0 – Modelling spatial variations of 3D radiant fluxes and mean radiant temperature in complex urban settings. International Journal of Biometeorology 52, 697–713.
[FL2011]Lindberg F & Grimmond C (2011) The influence of vegetation and building morphology on shadow patterns and mean radiant temperature in urban areas: model development and evaluation. Theoretical and Applied Climatology 105:3, 311-323.
[Ko17]Kokkonen TV, Grimmond CSB, Räty O, Ward HC, Christen A, Oke TR, Kotthaus S & Järvi L (in review) Sensitivity of Surface Urban Energy and Water Balance Scheme (SUEWS) to downscaling of reanalysis forcing data.
[Best2014]Best MJ & Grimmond CSB (2014) Importance of initial state and atmospheric conditions for urban land surface models’ performance. Urban Climate 10: 387-406. doi: 10.1016/j.uclim.2013.10.006.
[D74]Dyer AJ (1974) A review of flux-profile relationships. Boundary-Layer Meteorol. 7, 363-372.
[VUH85]Van Ulden AP & Holtslag AAM (1985) Estimation of atmospheric boundary layer parameters for boundary layer applications. J. Clim. Appl. Meteorol. 24, 1196-1207.
[CN1988]Campbell GS & Norman JM (1998) Introduction to Environmental Biophysics. Springer Science, US.
[B71]Businger JA, Wyngaard JC, Izumi Y & Bradley EF (1971) Flux-Profile Relationships in the Atmospheric Surface Layer. J. Atmos. Sci., 28, 181–189.
[Ka09]Kawai T, Ridwan MK & Kanda M (2009) Evaluation of the simple urban energy balance model using selected data from 1-yr flux observations at two cities. J. Appl. Meteorol. Clim. 48, 693-715.
[VG00]Voogt JA & Grimmond CSB (2000) Modeling surface sensible heat flux using surface radiative temperatures in a simple urban terrain. J. Appl. Meteorol. 39, 1679-1699.
[Ka07]Kanda M, Kanega M, Kawai T, Moriwaki R & Sugawara H (2007). Roughness lengths for momentum and heat derived from outdoor urban scale models. J. Appl. Meteorol. Clim. 46, 1067-1079.
[GO99]Grimmond CSB & Oke TR (1999) Aerodynamic properties of urban areas derived from analysis of surface form. J. Appl. Meteorol. 38, 1262-1292.
[Mc98]MacDonald RW, Griffiths RF & Hall DJ (1998) An improved method for estimation of surface roughness of obstacle arrays. Atmos. Env. 32, 1857-1864.
[FN78]Falk J & Niemczynowicz J, (1978) Characteristics of the above ground runoff in sewered catchments, in Urban Storm Drainage, edited by Helliwell PR, Pentech, London
[Ha79]Halldin S, Grip H & Perttu K. (1979) Model for energy exchange of a pine forest canopy. In: Halldin S (Ed.), Comparison of Forest Water and Energy Exchange Models. International Society of Ecological Modeling
[CW86]Calder IR and Wright IR (1986) Gamma Ray Attenuation Studies of Interception From Sitka Spruce: Some Evidence for an Additional Transport Mechanism. Water Resour. Res., 22(3), 409–417.
[Ok87]Oke TR (1987) Boundary Layer Climates. Routledge, London, UK
[Br03]Breuer L, Eckhardt K and Frede H-G (2003) Plant parameter values for models in temperate climates. Ecol. Model. 169, 237-293.
[Ja76]Jarvis PG (1976) The interpretation of the variations in leaf water potential and stomatal conductance found in canopies in the field. Philos. Trans. R. Soc. London, Ser. B., 273, 593-610.
[Au74]Auer AH (1974) The rain versus snow threshold temperatures. Weatherwise, 27, 67.
[SV06]Sailor DJ and Vasireddy C (2006) Correcting aggregate energy consumption data account for variability in local weather. Environ. Modell. Softw. 21, 733-738.
[Ko14]Konarska J, Lindberg F, Larsson A, Thorsson S and Holmer B (2014) Transmissivity of solar radiation through crowns of single urban trees—application for outdoor thermal comfort modelling. Theor Appl Climatol 117:363–376.
[Re90]Reindl DT, Beckman WA and Duffie JA (1990) Diffuse fraction correlation. Sol Energy 45:1–7.
[LG2012]Loridan T and Grimmond CSB (2012) Characterization of energy flux partitioning in urban environments: links with surface seasonal properties. J. of Applied Meteorology and Climatology 51,219-241 doi: 10.1175/JAMC-D-11-038.1
[H1988]Högström U (1988) Non-dimensional wind and temperature profiles in the atmospheric surface layer: A re-evaluation. Boundary-Layer Meteorol. 42, 55–78.
[Kent2017a]Kent CW, CSB Grimmond, J Barlow, D Gatey, S Kotthaus, F Lindberg, CH Halios 2017a: Evaluation of urban local-scale aerodynamic parameters: implications for the vertical profile of wind and source areas Boundary Layer Meteorology 164,183–213 doi: 10.1007/s10546-017-0248-z
[Kent2017b]Kent CW, S Grimmond, D Gatey 2017b: Aerodynamic roughness parameters in cities: inclusion of vegetation Journal of Wind Engineering & Industrial Aerodynamics doi: 10.1016/j.jweia.2017.07.016
[S2000]Schmid HP, Grimmond CSB, Cropley F, Offerle B, Su H (2000) Measurements of CO2 and energy fluxes over a mixed hardwood forest in the mid-westerm United States. Agricultural and Forest Meteorology. 103, 357-374.
[R95]Ruimy A, Jarvis PG, Baldocchi DD, Saugier B (1995) CO2 Fluxes over Plant Canopies and Solar Radiation: A Review. Advances in Ecological Research, 26.
[SL04]Sailor DJ, Lu L (2004) A top-down methodology for developing diurnal and seasonal anthropogenic heating profiles for urban areas. Atmospheric Environment. 38, 2737-2648.
[B2017]Bellucco V, Marras S, Grimmond CSB, Jarvi L, Sirca C, Spano D (2017) Modelling the biogenic CO2 exchange in urban and non-urban ecosystems through the assessment of light-response curve parameters. Agricultural and Forest Meteorology. 236, 113-122.
[FWC2002]Flanagan LB, Wever LA, Carlson PJ (2002) Seasonal and interannual variation in carbon dioxide exchange and carbon balance in a northern temperate grassland. Global Change Biology. 8, 599-615.
[J12]Järvi L, Nordbo A, Junninen H, Riikonen A, Moilanen J, Nikinmaa E, Vesala T (2012) Seasonal and annual variation of carbon dioxide surface fluxes in Helsinki, Finland, in 2006-2010. Atmos. Chem. Phys. 12, 8475-8489.
[B05]Brutsaert, W. (2005), Hydrology: an introduction, Cambridge Univ Pr, Cambridge.
[HF07]Harman IN, Finnigan JJ (2007) A simple uni ed theory for flow in the canopy and roughness sublayer. Boundary-Layer Meteorol 123(2):339–363
[HF08]Harman, IN, Finnigan, JJ (2008) Scalar concentration profiles in the canopy and roughness sublayer. Boundary-layer meteorol, 129(3), 323–351.
[T19]Theeuwes NE, Ronda RJ, Harman IN, Christen A, Grimmond CSB (2019) Parametrizing Horizontally Averaged Wind and Temperature Profiles in the Urban Roughness Sublayer. Boundary-Layer Meteorol, 173: 321. https://doi.org/10.1007/s10546-019-00472-1
[J19]Järvi, L., Havu, M., Ward, H. C., Bellucco, V., McFadden, J. P., Toivonen, T., et al. (2019). Spatial modeling of local‐scale biogenic and anthropogenic carbon dioxide emissions in Helsinki. Journal of Geophysical Research: Atmospheres, 124. https://doi.org/10.1029/2018JD029576