SUEWS

From UMEP
Jump to: navigation, search
This page contains changes which are not marked for translation.

Contents

SUEWS v2017b

The current version of SUEWS is v2017b. The software can be downloaded by completing the form here.

Ward HC, L Järvi, T Sun, S Onomura, F Lindberg, F Olofson, A Gabey, CSB Grimmond (2017) SUEWS Manual V2017b, http://urban-climate.net/umep/SUEWS Department of Meteorology, University of Reading, Reading, UK

This wiki page (http://urban-climate.net/umep/SUEWS) is regularly updated with new developments. For what's new in this version, see Version History.

The latest formal release of SUEWS is v2017b (released 1 August 2017).

The manual for SUEWS v2017b can be accessed here and should be referenced as follows:

Ward HC, L Järvi, T Sun, S Onomura, F Lindberg, F Olofson, A Gabey, CSB Grimmond (2017) SUEWS Manual V2017b, http://urban-climate.net/umep/SUEWS Department of Meteorology, University of Reading, Reading, UK

To download the latest version of SUEWS please complete the online form.

Please refer to Ward et al. (2017) for further details v2017a:

Ward HC, Yin San Tan, AM Gabey, S Kotthaus, WTJ Morrison, CSB Grimmond Impact of temporal resolution of precipitation forcing data on modelled urban-atmosphere exchanges and surface conditions International Journal of Climatology doi: 10.1002/joc.5200 

See other publications in the next section (if you have papers that could be added, please send them through)

Recent publications

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

Järvi et al. (2017) Application and evalution in cold climates. Implications of warming

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  https://www.nature.com/articles/s41598-017-05733-y

Kokkonen et al. 2017 Downscaling climate (rainfall) data to 1 h

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) to downscaling of reanalysis forcing data Urban Climate  https://doi.org/10.1016/j.uclim.2017.05.001

Ward and Grimmond (2017) for example applications:

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, http://dx.doi.org/10.1016/j.landurbplan.2017.04.001  

Demuzere et al. 2017 evaluation in Singapore and comparison with other urban land surface models

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 doi:10.1002/qj.3028 

Ward et al. (2016) Evaluation of SUEWS model

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 http://dx.doi.org/10.1016/j.uclim.2016.05.001.Ward et al. (2016)

Ao et al. (2016) Evaluation of radiation in Shanghai

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 http://dx.doi.org/10.1175/JAMC-D-16-0082.1

Onomura et al. (2015) Boundary layer modelling

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

Järvi et al. (2014) Snow melt model development

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


Other papers

Introduction

Overview of SUEWS

Surface Urban Energy and Water Balance Scheme (SUEWS) (Järvi et al. 2011[1], Ward et al. 2016[2]) 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[3]), similar to that used in forests, to model evaporation from urban surfaces.

The seven surface types considered in 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.

SUEWS and UMEP

SUEWS can be run as a standalone model but also can be used within UMEP. There are numerous tools included within UMEP to help a user get started. The SUEWS simple within UMEP is a fast way to start using SUEWS.

The version of SUEWS within UMEP is the complete model. Thus all options that are listed in this manual are available to the user. In the UMEP SUEWS simple runs all options are set to values to allow intial exploration of the model behaviour.

The version of SUEWS within UMEP is a more recent release of the model than the independent SUEWS release.

UMEP Description
Pre-Processor Meteorological Data Prepare Existing Data Transforms meteorological data into UMEP format
Download data (WATCH) Prepare meteorological dataset from WATCH
Spatial Data Spatial Data Downloader Plugin for retrieving geodata from online services suitable for various UMEP related tools
LCZ Converter Conversion from Local Climate Zones (LCZs) in the WUDAPT database into SUEWS input data
Urban land cover Land Cover Reclassifier Reclassifies a grid into UMEP format land cover grid. Land surface models
Land Cover Fraction (Point) Land cover fractions estimates from a land cover grid based on a specific point in space
Land Cover Fraction (Grid) Land cover fractions estimates from a land cover grid based on a polygon grid
Urban Morphology Morphometric Calculator (Point) Morphometric parameters from a DSM based on a specific point in space
Morphometric Calculator (Grid) Morphometric parameters estimated from a DSM based on a polygon grid
Source Area Model (Point) Source area calculated from a DSM based on a specific point in space.
SUEWS Prepare Preprocessing and preparing input data for the SUEWS model
Processor


Urban Energy Balance Anthropogenic Heat (QF) (LQF) Spatial variations anthropogenic heat release for urban areas
GQF Anthropogenic Heat (QF).
SUEWS (Simple) Urban Energy and Water Balance.
SUEWS (Advanced) Urban Energy and Water Balance.
Post-Processor Urban Energy Balance SUEWS analyser Plugin for plotting and statistical analysis of model results from SUEWS simple and SUEWS advanced
Benchmark Benchmark System For statistical analysis of model results, such as SUEWS

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).
  4. NARP (Net All-wave Radiation Parameterization, Offerle et al. 2003[4] , Loridan et al. 2011[5] ) 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)[1] approach, based on heating and cooling degree days and population density (allows distinction between weekdays and weekends).
    • Loridan et al. (2011)[5] 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[6], Lindberg et al. 2013[7]). A new version has been now included in UMEP. To distinguish it is referred to as LQF
    • GreaterQF (Iamarino et al. 2011[8]). 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[9], Grimmond & Oke 1999a[10], 2002[11]). 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[12]). OHM approach using analytically-derived coefficients. (Not recommended in v2017b)
    • ESTM (Element Surface Temperature Method, Offerle et al. 2005[13]). Heat transfer through urban facets (roof, wall, road, interior) is calculated from surface temperature measurements and knowledge of material properties. (Not recommended in v2017b)
  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[11]) 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 model output. 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[1][2]. 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)[14] and urban evaporation-interception scheme of Grimmond and Oke (1991)[3].

  • Precipitation is a required variable in the meteorological forcing file.
  • Irrigation can be modelled[1] 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 (Use of observed soil moisture is not possible in v2017b).
  • Runoff is permitted:
    • between surface types within each model grid
    • between model grids (Not implemented in v2017b)
    • to deep soil
    • to pipes.

Snowmelt

The snowmelt model within SUEWS is described in Järvi et al. (2014)[15]. Due to changes in the new model version (since v2016a) when compared to the older versions, the snow calculation has slightly changed. The main difference is that previously all surface state could freeze in 1-h time step but now the amount of freezing surface state is calculated similar way as melt water can freeze within the snow pack. Also the snowmelt-related coefficients have slightly changed (see SUEWS_Snow.txt).

Convective boundary layer

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

Thermal comfort

SOLWEIG (Solar and longwave environmental irradiance geometry model, Lindberg et al. 2008[18], Lindberg and Grimmond 2011[19]) is a 2D radiation model to estimate mean radiant temperature.

Overview of scales. Source: Onomura et al. (2015) [17]

Preparing to run the model

The following is to help with the model setup. Note that there is a version of SUEWS in UMEP and there are some starting tutorials for that. 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 file (60-min) Input
SSss_YYYY_data_5.txt Meteorological input file (5-min) Input
InitialConditionsSSss_YYYY.nml(+) Initial conditions file Input
SUEWS_SiteInfo_SSss.xlsm Spreadsheet containing all other input information Input
RunControl.nml Sets model run options Input (located in main directory)
SS_Filechoices.txt Summary of model run options Output
SSss_YYYY_5.txt (Optional) 5-min resolution output file Output
SSss_YYYY_60.txt 60-min resolution output file Output
SSss_DailyState.txt Daily state variables (all years in one file) Output

(+) 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 for your own data it is good to make certain that you can run the test data and get the same results as in the example files provided. It is recommended that you make a copy of the example output files and put them somewhere else 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

This section describes the information required to run SUEWS for your site. The input data can be summarised as follows:

  1. Continuous meteorological forcing data for the entire period to be modelled. Note you can not have gaps in the meteorological data. If you need help with preparing the data you may want to use some of the tools in UMEP.
  2. Knowledge of the surface and soil conditions immediately before the start of the run (if these initial conditions are not known, it is usually possible to determine suitable values by running the model and using the output at the end of the run to infer the conditions at the start of the 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[2]
  • Accurate meteorological forcing data, particularly precipitation and incoming shortwave radiation[20]
  • Initial soil moisture conditions[21]
  • Anthropogenic heat flux parameters, particularly if there are considerable energy emissions from transport, buildings, metabolism, etc[2]
  • External water use (if irrigation or street cleaning occurs)
  • Snow clearing (if running the snow option)
  • Surface conductance parameterisation[1][2]

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 surfaces SUEWS_NonVeg.txt
Bare soil surfaces SUEWS_NonVeg.txt
Vegetation Evergreen trees and shrubs SUEWS_Veg.txt
Deciduous trees and shrubs 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[6] [7] to estimate the anthropogenic heat flux which can then be provided as input SUEWS along with the meteorological forcing data. The LUCY model can be downloaded from here.

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 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 (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 (see error messages) and write the error to the 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 meteorological forcing data 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 InitialConditions.

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 (i.e. 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 the diurnal cycle 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
Filename Description Location Option
Program
SUEWS_V2017b.exe SUEWS executable Directory where the program will run
Input files
RunControl.nml Specifies options for the model run Same directory as executable 1/run
SUEWS_SiteSelect.txt Main input file for this site Input directory 1/run
SUEWS_NonVeg.txt Inputs for non-vegetated surfaces Input directory 1/run
SUEWS_Veg.txt Inputs for vegetated surfaces Input directory 1/run
SUEWS_Water.txt Inputs for water surfaces Input directory 1/run
SUEWS_Snow.txt Inputs for snow Input directory 1/run
SUEWS_Soil.txt Inputs for sub-surface soil Input directory 1/run
SUEWS_AnthropogenicHeat.txt Inputs for anthropogenic heat flux Input directory 1/run
SUEWS_Irrigation.txt Inputs for irrigation Input directory 1/run
SUEWS_Profiles.txt Inputs for hourly profiles (energy use, water use, snow-clearing) Input directory 1/run
SUEWS_WithinGridWaterDist.txt Inputs describing within-grid water distribution Input directory 1/run
SUEWS_OHMCoefficients.txt Inputs for OHM coefficients Input directory 1/run
SUEWS_Conductance.txt Inputs for surface conductance Input directory 1/run
SUEWS_SiteInfo.xlsm (Optional) spreadsheet for creating input files Anywhere, but the input files created must be in the input directory -
SSss_YYYY_data_tt.txt / SSss_YYYY_data_TT.txt Meteorological input file at model time-step (tt) / lower resolution (TT) Input directory 1/grid/year or 1/year
InitialConditionsSSss_YYYY.nml Initial conditions file Input directory 1/grid/run or 1/run
ESTMinput.nml Specifies options and inputs for ESTM model Input directory 1/run [E]
SUEWS_ESTMCoefficients.txt Inputs for ESTM coefficients Input directory 1/run [E]
SSss_YYYY_ESTM_Ts_data_tt.txt Surface temperature data input file at model time-step (tt) / lower resolution (TT) Input directory 1/grid/year or 1/year [E]
CBLinput.nml Specifies options and inputs for CBL model Input directory 1/run [B]
CBL_initial_data.txt Initial data for CBL model Input directory 1/day [B]
Output files
SSss_YYYY_tt.txt Model output at model time-step (optional) Output directory 1/grid/year
SSss_YYYY_TT.txt Model output at resolution specified by ResolutionFilesOut Output directory 1/grid/year
SSss_DailyState.txt Status at a daily time step Output directory 1/grid
InitialConditionsSSss_YYYY+1.nml New InitialConditions file written for each grid at the end of each year for multi-year runs. If the run finishes before the end of the year the InitialConditions file is still written and the file name is appended with '_EndofRun' Input directory 1/grid/year
SS_FileChoices.txt Summary of model run options Output directory 1/run
SS_YYYY_TT_OutputFormat.txt Describes header, units and formatting of the main output file Output directory 1/run
SSss_YYYY_ESTM_tt.txt Model output at model time-step (optional) Output directory 1/grid/year [E]
SSss_YYYY_ESTM_TT.txt Model output at resolution specified by ResoltuionFilesOut Output directory 1/grid/year [E]
problems.txt Contains details of serious errors encountered in the model run Same directory as executable 1/run
warnings.txt List of potential issues encountered in the model run Same directory as executable 1/run
CBL_id.txt CBL model output file for day of year id Output directory 1/day [B]

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.

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.

The format should be:

&RunControl
Parameters and variables (see table below)
/

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.
Name Required/Optional Description
Model run options
CBLuse R Determines whether a CBL slab model is used to calculate temperature and humidity.
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 R Determines whether the snow part of the model runs.
Value Comments
0

Snow calculations are not performed.

1

Snow calculations are performed.

SOLWEIGUse R Determines whether a high resolution radiation model to calculate mean radiant temperate should be used (SOLWEIG). NOTE: this option will considerably slow down the model since SOLWEIG is a 2D model.
Value Comments
0

SOLWEIG calculations are not performed.

1

SOLWEIG calculations are performed. A grid of mean radiant temperature (Tmrt) is calculated based on high resolution digital surface models.

NetRadiationMethod (previously NetRadiationChoice) R Determines method for calculation of radiation fluxes.
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[5]).
  • 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[5]).
  • 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 release
200
  • Q* modelled with L↓ modelled using cloud cover fraction supplied in meteorological forcing file (Loridan et al. 2011[5]).
  • Zenith angle accounted for in albedo calculation.
  • SSss_YYYY_NARPOut.txt file produced.
  • Not recommended in this release
300
  • Q* modelled with L↓ modelled using air temperature and relative humidity supplied in meteorological forcing file (Loridan et al. 2011[5]).
  • Zenith angle accounted for in albedo calculation.
  • SSss_YYYY_NARPOut.txt file produced.
  • Not recommended in this release
AnthropHeatMethod (previously AnthropHeatChoice) R Determines method for QF calculation.
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
  1. LQF which is simpler
  2. GQF which is more complete but requires more data inputs
1
  • Currently not recommended!
  • Calculated according to Loridan et al. (2011)[5] using coefficients specified in SUEWS_AnthropogenicHeat.txt.
  • Modelled values will be used even if QF is provided in the meteorological forcing file.
2
  • Recommended
  • Calculated according to Järvi et al. (2011)[1] using coefficients specified in SUEWS_AnthropogenicHeat.txt and diurnal patterns specified in SUEWS_Profiles.txt.
  • Modelled values will be used even if QF is provided in the meteorological forcing file.
AnthropCO2Method R Determines method for CO2 calculation.
Value Comments
1

Not used.

2
  • Under development - not recommended in v2017b
  • Calculate CO2 emissions from traffic based on QF calculation.
3
  • Under development - not recommended in v2017b
  • Calculate CO2 emissions from traffic from input data provided.
StorageHeatMethod (previously QSChoice) Determines method for calculating storage heat flux ΔQS.
Value Comments
1
  • ΔQS modelled using the objective hysteresis model (OHM)[9][10][11] using parameters specified for each surface type.
2
  • Uses observed values of ΔQS supplied in meteorological forcing file.
3
  • ΔQS modelled using AnOHM.
  • Not available in v2017b
4
  • ΔQS modelled using the Element Surface Temperature Method (ESTM) (Offerle et al. 2005[13]).
  • Not recommended in v2017b
OHMIncQF R Determines whether the storage heat flux calculation uses Q* or (Q*+QF).
Value Comments
0

ΔQS modelled Q* only.

1

ΔQS modelled using Q*+QF.

StabilityMethod R Defines which atmospheric stability functions are used.
Value Comments
0

Not used.

1

Not used.

2
  • Recommended
  • Momentum - unstable: Dyer (1974)[22] modified by Högstrom (1988)[23]; stable: Van Ulden and Holtslag (1985)[24]
  • Heat - Dyer (1974)[22] modified by Högstrom (1988)[23]
3
  • Momentum: Campbell and Norman (Eq 7.27, Pg97) [25]
  • Heat - unstable: Campbell and Norman[25]; stable: Dyer (1974)[22] modified by Högstrom (1988)[23]
4
  • Momentum: Businger et al. (1971)[26] modified by Högstrom (1988)[23]
  • Heat: Businger et al. (1971)[26] modified by Högstrom (1988)[23]
RoughLenHeatMethod (previously RoughLen_heat) R Determines method for calculating roughness length for heat.
Value Comments
1
  • Uses value of 0.1z0m.
2
  • Recommended
  • Calculated according to Kawai et al. (2009)[27].
3
  • Calculated according to Voogt and Grimmond (2000)[28].
4
  • Calculated according to Kanda et al. (2007)[29].
RoughLenMomMethod (previously z0_method) R Determines how aerodynamic roughness length (z0m) and zero displacement height (zdm) are calculated.
Value Comments
1
  • Values specified in SUEWS_SiteSelect.txt are used. Note that UMEP provides tools to calculate these]. See Kent et al. (2017a) for recommendations on methods. Kent et al. (2017b) have developed a method to include vegetation which is also avaialble within UMEP.
  • 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
  • Kent CW, S Grimmond, D Gatey 2017b: Aerodynamic roughness parameters in cities: inclusion of vegetation Journal of Wind Engineering & Industrial Aerodynamics http://dx.doi.org/10.1016/j.jweia.2017.07.016
2
  • z0m and zd are calculated using 'rule of thumb' (Grimmond and Oke 1999[30]) 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)[31] 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 (previously SMD_Choice) R Determines method for calculating soil moisture deficit (SMD).
Value Comments
0
  • Recommended
  • SMD modelled using parameters specified in SUEWS_Soil.txt.
1
  • Not currently implemented - do not use!
  • 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
  • Not currently implemented - do not use!
  • 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 (previously WUChoice) R Defines how external water use is calculated.
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.

File-related options
FileChoice R Two-letter site identification code (e.g. He, Sc, Kc).
FileInputPath R Input directory.
FileOutputPath R Output directory.
MultipleMetFiles R Specifies whether one single meteorological forcing file is used for all grids or a separate met file is provided for each grid.
Value Comments
0
  • Single meteorological forcing file used for all grids.
  • No grid number should appear in the file name.
1
  • Separate meteorological forcing files used for each grid.
  • The grid number should appear in the file name.
MultipleInitFiles R Specifies whether one single initial conditions file is used for all grids at the start of the run or a separate initial conditions file is provided for each grid.
Value Comments
0
  • Single initial conditions file used for all grids.
  • No grid number should appear in the file name.
1
  • Separate initial conditions files used for each grid.
  • The grid number should appear in the file name.
MultipleESTMFiles O Specifies whether one single ESTM forcing file is used for all grids or a separate file is provided for each grid.
Value Comments
0
  • Single ESTM forcing file used for all grids.
  • No grid number should appear in the file name.
1
  • Separate ESTM forcing files used for each grid.
  • The grid number should appear in the file name.
KeepTstepFilesIn O Specifies whether input meteorological forcing files at the resolution of the model time step should be saved.
Value Comments
0
  • Meteorological forcing files at model time step are not written out. This is the default option
  • Recommended to reduce processing time and save disk space as (e.g. 5-min) files can be large.
1
  • Meteorological forcing files at model time step are written out.
KeepTstepFilesOut O Specifies whether output meteorological forcing files at the resolution of the model time step should be saved.
Value Comments
0
  • Output files at model time are not saved. This is the default option.
  • Recommended to save disk space as (e.g. 5-min) files can be large.
1
  • Output files at model time step are written out.
WriteOutOption O Specifies which variables are written in the output files.
Value Comments
0
  • All (except snow-related) output variables written. This is the default option.
1
  • All (including snow-related) output variables written.
2
  • Writes out a minimal set of output variables (use this to save space or if information about the different surfaces is not required).
SuppressWarnings O Controls whether the warnings.txt file is written or not.
Value Comments
0
  • The warnings.txt file is written. This is the default option.
1
  • No warnings.txt file is written. May be useful for large model runs as this file can grow large.
Time-related options
Tstep R Specifies the model time step [s]. A value of 300 s (5 min) is strongly recommended. The time step cannot be less than 1 min or greater than 10 min, and must be a whole number of minutes that divide into an hour (i.e. options are 1, 2, 3, 4, 5, 6, 10 min or 60, 120, 180, 240, 300, 360, 600 s).
ResolutionFilesIn R Specifies the resolution of the input files [s] which SUEWS will disaggregate to the model time step. 1800 s for 30 min or 3600 s for 60 min are recommended. (N.B. if ResolutionFilesIn is not provided, SUEWS assumes ResolutionFilesIn = Tstep.)
ResolutionFilesInESTM O Specifies the resolution of the ESTM input files [s] which SUEWS will disaggregate to the model time step.
ResolutionFilesOut R Specifies the resolution of the output files [s]. 1800 s for 30 min or 3600 s for 60 min are recommended.
Options related to disaggregation of input data
DisaggMethod O Specifies how meteorological variables in the input file (except rain and snow) are disaggregated to the model time step. Wind direction is not currently downscaled so non -999 values will cause an error.
Value Comments
1

Linear downscaling of averages for all variables, additional zenith check is used for Kdown. This is the default option.

2

Linear downscaling of instantaneous values for all variables, additional zenith check is used for Kdown.

3

WFDEI setting: average Kdown (with additional zenith check); instantaneous for Tair, RH, pres and U. (N.B. WFDEI actually provides Q not RH)

KdownZen O Can be used to switch off zenith checking in Kdown disaggregation. Note that the zenith calculation requires location information obtained from SUEWS_SiteSelect.txt. If a single met file is used for all grids, the zenith is calculated for the first grid and the disaggregated data is then applied for all grids.
Value Comments
0

No zenith angle check is applied.

1

Disaggregated Kdown is set to zero when zenith angle exceeds 90 degrees (i.e. sun below horizon) and redistributed over the day. This is the default option.

RainDisaggMethod O Specifies how rain in the meteorological forcing file are disaggregated to the model time step. If present in the original met forcing file, snow is currently disaggregated in the same way as rainfall.
Value Comments
100

Rainfall is evenly distributed among all subintervals in a rainy interval. This is the default option.

101

Rainfall is evenly distributed among among RainAmongN subintervals in a rainy interval – also requires RainAmongN to be set.

102

Rainfall is evenly distributed among among RainAmongN subintervals in a rainy interval for different intensity bins – also requires MultRainAmongN and MultRainAmongNUpperI to be set.

RainAmongN O Specifies the number of subintervals (of length tt) over which to distribute rainfall in each interval (of length TT). Must be an integer value. Use with RainDisaggMethod = 101.
MultRainAmongN O Specifies the number of subintervals (of length tt) over which to distribute rainfall in each interval (of length TT) for up to 5 intensity bins. Must take integer values. Use with RainDisaggMethod = 102.

e.g. MultRainAmongN(1) = 5, MultRainAmongN(2) = 8, MultRainAmongN(3) = 12

MultRainAmongNUpperI O Specifies upper limit for each intensity bin to apply MultRainAmongN. Any intensities above the highest specified intensity will use the last MultRainAmongN value and write a warning to warnings.txt. Use with RainDisaggMethod = 102.

e.g. MultRainAmongNUpperI(1) = 0.5, MultRainAmongNUpperI(2) = 2.0, MultRainAmongNUpperI(3) = 50.0

DisaggMethodESTM O Specifies how ESTM-related temperatures in the input file are disaggregated to the model time step.
Value Comments
1

Linear downscaling of averages.

2

Linear downscaling of instantaneous values.

netCDF-related options

N.B.: This feature is NOT enabled in the public release due to the dependency of netCDF library.

Please contact the development team for assistance in enabling this feature if this feature is needed: SUEWS mail list

ncMode O Determine if the output files should be written in netCDF format.
Value Comments
0
  • Output files are kept as plain text files (i.e., .txt).
1
  • Output files will be written in netCDF format (i.e., .nc).
nRow O Number of rows (e.g., 36) in the output layout (only applicable when ncMode=1).
nCol O Number of columns (e.g., 47) in the output layout (only applicable when ncMode=1).

SUEWS_SiteInfo.xlsm

The following text files provide SUEWS with information about the study area. These text files are stored as worksheets in SUEWS_SiteInfo.xlsm and can be either edited using Excel and then generated using the macro, or 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.

Use Column
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. 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.

SUEWS_SiteSelect.txt

For each year and each grid, site specific surface cover information and other input parameters is 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 (before the two rows of '-9') will be read by the model and run. In this file the column order is important. '!' 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.

No. Use Column name Example Description
1 MU Grid 1 Grid number (any integer 0-2,147,483,647 (largest 4-byte integer)) identifying the current grid.
  • 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. GridConnections not currently implemented!)

The two last lines in this column must read '-9' to indicate that the last lines have been reached (using two lines allows differences in computer file savings to be dealt with).

2 MU Year 2011 Year [YYYY]

Years must be continuous. If running multiple years, ensure the rows in 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).

3 MU StartDLS 86 Start of the day light savings [DOY]

See section on Day Light Savings.

4 MU EndDLS 303 End of the day light savings [DOY]

See section on Day Light Savings.

5 MU lat 60.00 Latitude for the centre of the grid [decimal degrees]
  • 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.
6 MU lng -18.20 Longitude for the centre of the grid [decimal degrees]
  • 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.
7 MU Timezone 0 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 MU SurfaceArea 75.3 Area of the grid [ha].
9 MU Alt 25.0 Altitude [m]

Mean topographic height above sea-level.

  • Used for both the radiation and water flow between grids. (N.B. water flow between grids not currently implemented.)
10 MU z 20.5 Height [m] of the meteorological forcing data. The most important height is that of the wind speed measurement.
  • 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.
11 MD id 1 Day [DOY]

Not used: set to 1 in this version.

12 MD ih 0 Hour [H]

Not used: set to 0 in this version.

13 MD imin 0 Minute [M]

Not used: set to 0 in this version.

14 MU Fr_Paved 0.20 Surface cover fraction of paved surfaces [-]

Areal cover fraction of paved surfaces (roads, pavements, car parks). e.g. 20% of the grid is covered with paved surfaces.

  • Columns 14 to 20 must sum to 1.
15 MU Fr_Bldgs 0.20 Surface cover fraction of buildings [-]
16 MU Fr_EveTr 0.10 Surface cover fraction of evergreen trees and shrubs [-]
17 MU Fr_DecTr 0.10 Surface cover fraction of deciduous trees and shrubs [-]
18 MU Fr_Grass 0.30 Surface cover fraction of grass [-]
19 MU Fr_Bsoil 0.05 Surface cover fraction of bare soil or unmanaged land [-]
20 MU Fr_Water 0.05 Surface cover fraction of open water [-]

(e.g. river, lakes, ponds, swimming pools)

21 MU IrrFr_EveTr 0.50 Fraction of evergreen trees that are irrigated [-]

e.g. 50% of the evergreen trees/shrubs are irrigated

22 MU IrrFr_DecTr 0.20 Fraction of deciduous trees that are irrigated [-]
23 MU IrrFr_Grass 0.70 Fraction of grass that is irrigated [-]
24 MU H_Bldgs 10 Mean building height [m]
25 MU H_EveTr 15 Mean height of evergreen trees [m]
26 MU H_DecTr 15 Mean height of deciduous trees [m]
27 O z0 0.6 Roughness length for momentum [m]

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).

28 O zd 1.5 Zero-plane displacement [m]

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).

29 O FAI_Bldgs 0.1 Frontal area index for buildings [-]

Required if RoughLenMomMethod = 3 in RunControl.nml.

30 O FAI_EveTr 0.2 Frontal area index for evergreen trees [-]

Required if RoughLenMomMethod = 3 in RunControl.nml.

31 O FAI_DecTr 0.2 Frontal area index for deciduous trees [-]

Required if RoughLenMomMethod = 3 in RunControl.nml.

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

Population density is required if AnthropHeatMethod = 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.

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

Population density is required if AnthropHeatMethod = 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.

34 O TrafficRate Traffic rate [veh km m-2 s-1]

Can be used for CO2 flux calculation. Do not use in v2017a - set to -999

35 O BuildEnergyUse Building energy use [W m-2]

Can be used for CO2 flux calculation. Do not use in v2017a - set to -999

36 L Code_Paved 331 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).

37 L Code_Bldgs 332 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.

38 L Code_EveTr 331 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.

39 L Code_DecTr 332 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.

40 L Code_Grass 333 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.

41 L Code_Bsoil 333 Code for BSoil surface characteristics

Provides the link to column 1 of SUEWS_NonVeg.txt, which contains the attributes describing bare soil in this grid for this year. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_NonVeg.txt.

42 L Code_Water 331 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.

43 MD LUMPS_DrRate 0.25 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)[5].

44 MD LUMPS_Cover 1 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)[5].

45 MD LUMPS_MaxRes 10 Maximum water bucket reservoir [mm]

Used for LUMPS surface wetness control. Default recommended value of 10 mm from Loridan et al. (2011)[5].

46 MD NARP_Trans 1 Atmospheric transmissivity for NARP [-]

Value must in the range 0-1. Default recommended value of 1.

47 L CondCode 33 Code for surface conductance parameters

Provides the link to column 1 of SUEWS_Conductance.txt, which contains the parameters for the Jarvis (1976) 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).

48 L SnowCode 33 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.

49 L SnowClearingProfWD 1 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).

50 L SnowClearingProfWE 1 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.

51 L AnthropogenicCode 33 Code for modelling anthropogenic heat flux

Provides the link to column 1 of SUEWS_AnthropogenicHeat.txt, which contains the model coefficients for estimation of the anthropogenic heat flux (used if AnthropHeatChoice = 1, 2 in RunControl.nml). Value of integer is arbitrary but must match code specified in column 1 of SUEWS_AnthropogenicHeat.txt.

52 L EnergyUseProfWD 333 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.

53 L EnergyUseProfWE 334 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.

54 L ActivityProfWD 333 Code for human activity 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. Used for CO2 flux calculation - not used in v2017a

55 L ActivityProfWE 333 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 v2017a

56 L IrrigationCode 33 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.

57 L WaterUseProfManuWD 335 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.

58 L WaterUseProfManuWE 336 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.

59 L WaterUseProfAutoWD 337 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.

60 L WaterUseProfAutoWE 338 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.

61 MD FlowChange 0 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!

62 MD,MU RunoffToWater 0.1 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.

63 MD,MU PipeCapacity 100 Storage capacity of pipes [mm]

Runoff amounting to less than the value specified here is assumed to be removed by pipes.

64 MD,MU GridConnection1of8 2 Number of the 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

Not currently implemented!

65 MD,MU Fraction1of8 0.2 Fraction of water that can flow to the grid specified in previous column [-]
66 MD,MU GridConnection2of8 0 Number of the grid where water can flow to
67 MD,MU Fraction2of8 0 Fraction of water that can flow to the grid specified in previous column [-]
68 MD,MU GridConnection3of8 0 Number of the grid where water can flow to
69 MD,MU Fraction3of8 0 Fraction of water that can flow to the grid specified in previous column [-]
70 MD,MU GridConnection4of8 0 Number of the grid where water can flow to
71 MD,MU Fraction4of8 0 Fraction of water that can flow to the grid specified in previous column [-]
72 MD,MU GridConnection5of8 0 Number of the grid where water can flow to
73 MD,MU Fraction5of8 0 Fraction of water that can flow to the grid specified in previous column [-]
74 MD,MU GridConnection6of8 0 Number of the grid where water can flow to
75 MD,MU Fraction6of8 0 Fraction of water that can flow to the grid specified in previous column [-]
76 MD,MU GridConnection7of8 0 Number of the grid where water can flow to
77 MD,MU Fraction7of8 0 Fraction of water that can flow to the grid specified in previous column [-]
78 MD,MU GridConnection8of8 0 Number of the grid where water can flow to
79 MD,MU Fraction8of8 0 Fraction of water that can flow to the grid specified in previous column [-]
80 L WithinGridPavedCode 331 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.

81 L WithinGridBldgsCode 332 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.

82 L WithinGridEveTrCode 333 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.

83 L WithinGridDecTrCode 334 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.

84 L WithinGridGrassCode 335 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.

85 L WithinGridBSoilCode 336 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.

86 L WithinGridWaterCode 337 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.

87 MU AreaWall 1.08 Area of wall within grid (needed for ESTM calculation).
88 MU Fr_ESTMClass_Paved1 Fraction of paved surface classified as ESTM class 1
  • Columns 88-90 must add up to 1
89 MU Fr_ESTMClass_Paved2 Fraction of paved surface classified as ESTM class 2
  • Columns 88-90 must add up to 1
90 MU Fr_ESTMClass_Paved3 Fraction of paved surface classified as ESTM class 3
  • Columns 88-90 must add up to 1
91 L Code_ESTMClass_Paved1 Code linking to SUEWS_ESTMCoefficients.txt
92 L Code_ESTMClass_Paved2 Code linking to SUEWS_ESTMCoefficients.txt
93 L Code_ESTMClass_Paved3 Code linking to SUEWS_ESTMCoefficients.txt
94 MU Fr_ESTMClass_Bldgs1 Fraction of building surface classified as ESTM class 1
  • Columns 94-98 must add up to 1
95 MU Fr_ESTMClass_Bldgs2 Fraction of building surface classified as ESTM class 2
  • Columns 94-98 must add up to 1
96 MU Fr_ESTMClass_Bldgs3 Fraction of building surface classified as ESTM class 3
  • Columns 94-98 must add up to 1
97 MU Fr_ESTMClass_Bldgs4 Fraction of building surface classified as ESTM class 4
  • Columns 94-98 must add up to 1
98 MU Fr_ESTMClass_Bldgs5 Fraction of building surface classified as ESTM class 5
  • Columns 94-98 must add up to 1
99 L Code_ESTMClass_Bldgs1 Code linking to SUEWS_ESTMCoefficients.txt
100 L Code_ESTMClass_Bldgs2 Code linking to SUEWS_ESTMCoefficients.txt
101 L Code_ESTMClass_Bldgs3 Code linking to SUEWS_ESTMCoefficients.txt
102 L Code_ESTMClass_Bldgs4 Code linking to SUEWS_ESTMCoefficients.txt
103 L Code_ESTMClass_Bldgs5 Code linking to SUEWS_ESTMCoefficients.txt
Day Light Savings (DLS)

The dates for DLS normally vary 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.

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: Year start of daylight savings end of daylight savings
when running multiple years (in this case 2008 and 2009 in Canada) 2008 170 240
2009 172 242
Grid Connections (water flow between grids)

N.B. not currently implemented - columns 64-79 of SUEWS_SiteSelect.txt can be set to zero.

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 values for the grid connections part of SUEWS_SiteSelect.txt for the grids.

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. Use Column name Example Description
1 L Code

331


332


333

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.

2 MU AlbedoMin 0-1 Minumum albedo of this surface [-]
  • Effective surface albedo (middle of the day value) for wintertime (not including snow).
  • View factors should be taken into account.
  • Not currently used for non-vegetated surfaces – set the same as AlbedoMax.
3 MU AlbedoMax 0-1 Maximum albedo of this surface [-]
  • Effective surface albedo (middle of the day value) for summertime.
  • View factors should be taken into account.
4 MU Emissivity 0-1 Emissivity of this surface [-]
  • Effective surface emissivity.
  • View factors should be taken into account.
5 MD StorageMin Minimum water storage capacity of this surface [mm]
  • 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 [mm]
0.48 Paved
0.25 Bldgs
0.80 BSoil
6 MD StorageMax Maximum water storage capacity of this surface [mm]
  • 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 [mm]
0.48 Paved
0.25 Bldgs
0.80 BSoil
7 MD WetThreshold Threshold for a completely wet surface [mm]
  • Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface.
Example values [mm]
0.6 Paved
0.6 Bldgs
1.0 BSoil
8 MD StateLimit Upper limit to the surface state [mm]
  • Currently only used for the water surface
9 MD DrainageEq 1, 2, 3 Drainage equation to use for this surface.
Options
1 Falk and Niemczynowicz (1978)[32]
2 Halldin et al. (1979)[33] (Rutter eqn corrected for c=0, see Calder & Wright (1986)[34]) Recommended[3] for BSoil
3 Falk and Niemczynowicz (1978)[32] Recommended[3] for Paved and Bldgs
  • Coefficients are specified in the following two columns.
10 MD DrainageCoef1 Coefficient for drainage equation [units vary according to DrainageEq specified in previous column]
Example values DrainageEq
10 Coefficient D0 [mm h-1] 3 Recommended[3] for Paved and Bldgs
0.013 Coefficient D0 [mm h-1] 2 Recommended[3] for BSoil
11 MD DrainageCoef2 Coefficient for drainage equation [units vary according to DrainageEq specified in previous column]
Example values DrainageEq
3 Coefficient b [-] 3 Recommended[3] for Paved and Bldgs
1.71 Coefficient b [mm-1] 2 Recommended[3] for BSoil
12 L SoilTypeCode 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.

13 O SnowLimPatch Maximum SWE [mm]

Limit of snow water equivalent when the surface is fully covered with snow.

Example values [mm]
190 Paved Järvi et al. (2014)[15]
190 Bldgs Järvi et al. (2014)[15]
190 BSoil Järvi et al. (2014)[15]
14 O SnowLimRemove SWE when snow is removed from this surface [mm]

Limit of snow water equivalent when snow is removed from paved surfaces and buildings

  • Not needed if SnowUse = 0 in RunControl.nml.
  • Currently not implemented for BSoil surface
Example values [mm]
40 Paved Järvi et al. (2014)[15]
100 Bldgs Järvi et al. (2014)[15]
15 L OHMCode_SummerWet 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.

16 L OHMCode_SummerDry 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.

17 L OHMCode_WinterWet 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.

18 L OHMCode_WinterDry 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.

19 MD OHMThresh_SW 10 Temperature threshold determining whether summer/winter OHM coefficients are applied [deg 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.

20 MD OHMThresh_WD 0.9 Soil moisture threshold determining whether wet/dry OHM coefficients are applied [-]

If soil moisture (as a proportion of maximum soil moisture capacity) exceeds this threshold for bare soil and vegetated surfaces, OHM coefficients for wet conditions are applied; otherwise coefficients for dry coefficients are applied. Note that OHM coefficients for wet conditions are applied if the surface is wet. Not actually used for building and paved surfaces (as impervious).

21 L ESTMCode 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.

  • 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.
22 MU AnOHM_Cp Volumetric heat capacity for this surface to use in AnOHM [J m-3]
23 MU AnOHM_Kk Thermal conductivity for this surface to use in AnOHM [W m K-1]
24 MU AnOHM_Ch Bulk transfer coefficient for this surface to use in AnOHM [-]

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. Use Column name Example Description
1 L Code

331


332


333

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.

2 MU AlbedoMin 0-1 Minimum albedo of this surface [-]
  • Effective surface albedo (middle of the day value) for wintertime (not including snow), leaf-off.
  • View factors should be taken into account.
Example values [-]
0.10 EveTr Oke (1987)[35]
0.18 DecTr Oke (1987)[35]
0.21 Grass Oke (1987)[35]
3 MU AlbedoMax 0-1 Maxmium albedo of this surface [-]
  • Effective surface albedo (middle of the day value) for summertime, full leaf-on.
  • View factors should be taken into account.
Example values [-]
0.10 EveTr Oke (1987)[35]
0.18 DecTr Oke (1987)[35]
0.21 Grass Oke (1987)[35]
4 MU Emissivity 0-1 Emissivity of this surface [-]
  • Effective surface emissivity.
  • View factors should be taken into account.
Example values [-]
0.98 EveTr Oke (1987)[35]
0.98 DecTr Oke (1987)[35]
0.93 Grass Oke (1987)[35]
5 MD StorageMin Minimum water storage capacity of this surface [mm]
  • 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 [mm]
1.3 EveTr Breuer et al. (2003)[36]
0.3 DecTr Breuer et al. (2003)[36]
1.9 Grass Breuer et al. (2003)[36]
6 MD StorageMax Maximum water storage capacity of this surface [mm]
  • 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 [mm]
1.3 EveTr Breuer et al. (2003)[36]
0.8 DecTr Breuer et al. (2003)[36]
1.9 Grass Breuer et al. (2003)[36]
7 MD WetThreshold Threshold for a completely wet surface [mm]
  • Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface.
Example values [mm]
1.8 EveTr
1.0 DecTr
2.0 Grass
8 MD StateLimit Upper limit to the surface state [mm]
  • Currently only used for the water surface
9 MD DrainageEq 1, 2, 3 Drainage equation to use for this surface.
Options
1 Falk and Niemczynowicz (1978)[32]
2 Halldin et al. (1979)[33] (Rutter eqn corrected for c=0, see Calder & Wright (1986)[34]) Recommended[3] for EveTr, DecTr, Grass (unirrigated)
3 Falk and Niemczynowicz (1978)[32] Recommended[3] for Grass (irrigated)
  • Coefficients are specified in the following two columns.
10 MD DrainageCoef1 Coefficient for drainage equation [units vary according to DrainageEq specified in previous column]
Example values DrainageEq
10 Coefficient D0 [mm h-1] 3 Recommended[3] for Grass (irrigated)
0.013 Coefficient D0 [mm h-1] 2 Recommended[3] for EveTr, DecTr, Grass (unirrigated)
11 MD DrainageCoef2 Coefficient for drainage equation [units vary according to DrainageEq specified in previous column]
Example values DrainageEq
3 Coefficient b [-] 3 Recommended[3] for Grass (irrigated)
1.71 Coefficient b [mm-1] 2 Recommended[3] for EveTr, DecTr, Grass (unirrigated)
12 L SoilTypeCode 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.

13 O SnowLimPatch Maximum SWE [mm]
  • Limit of snow water equivalent when the surface surface is fully covered with snow.
  • Not needed if SnowUse = 0 in RunControl.nml.
Example values [mm]
190 EveTr Järvi et al. (2014)[15]
190 DecTr Järvi et al. (2014)[15]
190 Grass Järvi et al. (2014)[15]
14 MU BaseT Base temperature for initiating growing degree days for leaf growth [°C]
  • See section 2.2 Järvi et al. (2011); Appendix A Järvi et al. (2014).
Example values [°C]
5 EveTr Järvi et al. (2011)[1]
5 DecTr Järvi et al. (2011)[1]
5 Grass Järvi et al. (2011)[1]
15 MU BaseTe Base temperature for initiating senescence degree days for leaf off [°C]
  • See section 2.2 Järvi et al. (2011)[1]; Appendix A Järvi et al. (2014)[15].
Example values [°C]
10 EveTr Järvi et al. (2011)[1]
10 DecTr Järvi et al. (2011)[1]
10 Grass Järvi et al. (2011)[1]
16 MU GDDFull Growing degree days needed for full capacity of the leaf area index [°C]
  • 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)[1]; Appendix A Järvi et al. (2014)[15] for more details.
Example values [°C]
300 EveTr Järvi et al. (2011)[1]
300 DecTr Järvi et al. (2011)[1]
300 Grass Järvi et al. (2011)[1]
17 MU SDDFull Senescence degree days needed to initiate leaf off [°C]
  • 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)[1]; Appendix A Järvi et al. (2014)[15] for more details.
Example values [°C]
-450 EveTr Järvi et al. (2011)[1]
-450 DecTr Järvi et al. (2011)[1]
-450 Grass Järvi et al. (2011)[1]
18 MD LAIMin Minimum leaf area index [m-2 m-2]
  • leaf-off wintertime value
Example values [m-2 m-2]
4.0 EveTr Järvi et al. (2011)[1]
1.0 DecTr Järvi et al. (2011)[1]
1.6 Grass Grimmond and Oke (1991)[3] and references therein
19 MD LAIMax Maximum leaf area index [m-2 m-2]
  • full leaf-on summertime value
Example values [m-2 m-2]
5.1 EveTr Breuer et al. (2003)[36]
5.5 DecTr Breuer et al. (2003)[36]
5.9 Grass Breuer et al. (2003)[36]
20 MD PorosityMin 0.2 Minimum porosity [-]
  • leaf-off wintertime value
  • Used only for DecTr (can affect roughness calculation)
21 MD PorosityMax 0.6 Maximum porosity [-]
  • full leaf-on summertime value
  • Used only for DecTr (can affect roughness calculation)
22 MD MaxConductance Maximum conductance for each surface [mm s-1]

Used to calculate the surface conductance using the Jarvis (1976)[37] model. See Eq 15 Järvi et al. (2011)[1] or Eq 8 Ward et al. (2016)[2].

Example values [mm s-1]
7.4 EveTr Järvi et al. (2011)[1]
11.7 DecTr Järvi et al. (2011)[1]
33.1 Grass (unirrigated) Järvi et al. (2011)[1]
40.0 Grass (irrigated) Järvi et al. (2011)[1]
23 MD LAIEq 0, 1 LAI equation to use for this surface.
Options
0 Järvi et al. (2011)[1]
1 Järvi et al. (2014)[15]
  • Coefficients are specified in the following four columns.
  • N.B. North and South hemispheres are treated slightly differently.
24 MD LeafGrowthPower1 Coefficient (power) for leaf growth [-]

See Appendix A Järvi et al. (2014)[15] for more details.

Example values LAIEq
0.03 Järvi et al. (2011)[1] 0
0.04 Järvi et al. (2014)[15] 1
25 MD LeafGrowthPower2 Constant in the leaf growth equation [°C-1]

See Appendix A Järvi et al. (2014)[15] for more details.

Example values [°C-1] LAIEq
0.0005 Järvi et al. (2011)[1] 0
0.0010 Järvi et al. (2014)[15] 1
26 MD LeafOffPower1 Coefficient (power) for leaf off [-]

See Appendix A Järvi et al. (2014)[15] for more details.

Example values LAIEq
0.03 Järvi et al. (2011)[1] 0
-1.5 Järvi et al. (2014)[15] 1
27 MD LeafOffPower2 Constant in the leaf off equation [°C-1]

See Appendix A Järvi et al. (2014)[15] for more details.

Example values [°C-1] LAIEq
0.0005 Järvi et al. (2011)[1] 0
0.0015 Järvi et al. (2014)[15] 1
28 L OHMCode_SummerWet 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.

29 L OHMCode_SummerDry 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.

30 L OHMCode_WinterWet 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.

31 L OHMCode_WinterDry 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.

32 MD OHMThresh_SW 10 Temperature threshold determining whether summer/winter OHM coefficients are applied [deg 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.

33 MD OHMThresh_WD 0.9 Soil moisture threshold determining whether wet/dry OHM coefficients are applied [-]

If soil moisture (as a proportion of maximum soil moisture capacity) exceeds this threshold for bare soil and vegetated surfaces, OHM coefficients for wet conditions are applied; otherwise coefficients for dry coefficients are applied. Note that OHM coefficients for wet conditions are applied if the surface is wet.

34 L ESTMCode 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.

35 MU AnOHM_Cp Volumetric heat capacity for this surface to use in AnOHM [J m-3]
36 MU AnOHM_Kk Thermal conductivity for this surface to use in AnOHM [W m K-1]
37 MU AnOHM_Ch Bulk transfer coefficient for this surface to use in AnOHM [-]

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. Use Column name Example Description
1 L Code 331 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.

2 MU AlbedoMin 0-1 Minimum albedo of this surface [-]
  • View factors should be taken into account.
  • Not currently used for water surface - set same as AlbedoMax.
3 MU AlbedoMax 0-1 Albedo of this surface [-]
  • Effective albedo of the water surface.
  • View factors should be taken into account.
Example values [-]
0.1 Water Oke (1987)[35]
4 MU Emissivity 0-1 Emissivity of this surface [-]
  • Effective surface emissivity.
  • View factors should be taken into account
Example values [-]
0.95 Water Oke (1987)[35]
5 MD StorageMin Minimum water storage capacity of this surface [mm]
  • 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 [mm]
0.5 Water
6 MD StorageMax Maximum water storage capacity of this surface [mm]
  • 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.
7 MD WetThreshold Threshold for a completely wet surface [mm]
  • Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface.
Example values [mm]
0.5 Water
8 MU StateLimit Upper limit to the surface state [mm]
  • 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.
9 MU WaterDepth Typical depth for the water surface [mm]
  • 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).
10 MD DrainageEq -999 Drainage equation to use for this surface.
  • Not currently used for water surface.
11 MD DrainageCoef1 -999 Coefficient for drainage equation [units vary according to equation]
  • Not currently used for water surface
12 MD DrainageCoef2 -999 Coefficient for drainage equation [units vary according to equation]
  • Not currently used for water surface
13 L OHMCode_SummerWet 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.

14 L OHMCode_SummerDry 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.

15 L OHMCode_WinterWet 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.

16 L OHMCode_WinterDry 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.

17 MD OHMThresh_SW 10 Temperature threshold determining whether summer/winter OHM coefficients are applied [deg 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.

18 MD OHMThresh_WD 0.9 Soil moisture threshold determining whether wet/dry OHM coefficients are applied [-]

If soil moisture (as a proportion of maximum soil moisture capacity) exceeds this threshold for bare soil and vegetated surfaces, OHM coefficients for wet conditions are applied; otherwise coefficients for dry coefficients are applied. Note that OHM coefficients for wet conditions are applied if the surface is wet. Not actually used for water surface (as no soil surface beneath).

19 L ESTMCode 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.

20 MU AnOHM_Cp Volumetric heat capacity for this surface to use in AnOHM [J m-3]
21 MU AnOHM_Kk Thermal conductivity for this surface to use in AnOHM [W m K-1]
22 MU AnOHM_Ch Bulk transfer coefficient for this surface to use in AnOHM [-]

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)[15]. In the current release SnowUse should be set to 0.

No. Use Column name Example Description
1 L Code 331 Code linking to SUEWS_SiteSelect.txt for snow surfaces (SnowCode).

Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.

2 MU RadMeltFactor 0.0016 Hourly radiation melt factor of snow [mm W-1 h-1]
3 MU TempMeltFactor 0.07 Hourly temperature melt factor of snow [mm °C-1 h-1] (In previous model version, this parameter was 0.12)
4 MU AlbedoMin 0-1 Minimum snow albedo [-]
Example values [-]
0.18 Järvi et al. (2014)[15]
5 MU AlbedoMax 0-1 Maximum snow albedo (fresh snow) [-]
Example values [-]
0.85 Järvi et al. (2014)[15]
6 MU Emissivity 0-1 Emissivity of this surface [-]
  • Effective surface emissivity.
  • View factors should be taken into account
Example values [-]
0.99 Järvi et al. (2014)[15]
7 MD tau_a 0.018 Time constant for snow albedo aging in cold snow [-]
8 MD tau_f 0.11 Time constant for snow albedo aging in melting snow [-]
9 MD PrecipiLimAlb 2 Limit for hourly precipitation when the ground is fully covered with snow. Then snow albedo is reset to AlbedoMax [mm]
10 MD snowDensMin 100 Fresh snow density [kg m-3]
11 MD snowDensMax 400 Maximum snow density [kg m-3]
12 MD tau_r 0.043 Time constant for snow density ageing [-]
13 MD CRWMin 0.05 Minimum water holding capacity of snow [mm]
14 MD CRWMax 0.20 Maximum water holding capacity of snow [mm]
15 MD PrecipLimSnow 2.2 Temperature limit when precipitation falls as snow [°C]
16 L OHMCode_SummerWet 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.

17 L OHMCode_SummerDry 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.

18 L OHMCode_WinterWet 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.

19 L OHMCode_WinterDry 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.

20 MD OHMThresh_SW 10 Temperature threshold determining whether summer/winter OHM coefficients are applied [deg 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. Not actually used for Snow surface as winter wet conditions always assumed.

21 MD OHMThresh_WD 0.9 Soil moisture threshold determining whether wet/dry OHM coefficients are applied [-]

If soil moisture (as a proportion of maximum soil moisture capacity) exceeds this threshold for bare soil and vegetated surfaces, OHM coefficients for wet conditions are applied; otherwise coefficients for dry coefficients are applied. Note that OHM coefficients for wet conditions are applied if the surface is wet. Not actually used for Snow surface as winter wet conditions always assumed.

22 L ESTMCode 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.

  • 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.
23 MU AnOHM_Cp Volumetric heat capacity for this surface to use in AnOHM [J m-3]
24 MU AnOHM_Kk Thermal conductivity for this surface to use in AnOHM [W m K-1]
25 MU AnOHM_Ch Bulk transfer coefficient for this surface to use in AnOHM [-]

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 soi 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 (smd_choice = 1 or 2 in RunControl.nml) and providing some metadata information here (OBS_ columns), or modelled by SUEWS (smd_choice = 0 in RunControl.nml). - Note, the option to use observational data is not operational in the current release!

No. Use Column name Example Description
1 L Code 331 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.

2 MD SoilDepth 350 Depth of sub-surface soil store [mm]

i.e. the depth of soil beneath the surface

3 MD SoilStoreCap 150 Capacity of sub-surface soil store [mm]

i.e. how much water can be stored in the sub-surface soil when at maximum capacity.

  • SoilStoreCap must not be greater than SoilDepth.
4 MD SatHydraulicCond 0.0005 Hydraulic conductivity for saturated soil [mm s-1]
5 MD SoilDensity 1.16 Soil density [kg m-3]
6 O InfiltrationRate -999 Infiltration rate [mm h-1]
  • Not currently used
7 O OBS_SMDepth Depth of soil moisture measurements [mm]
  • Use only if soil moisture is observed and provided in the met forcing file and smd_choice = 1 or 2.
  • Use of observed soil moisture not currently tested
8 O OBS_SMCap Maxiumum observed soil moisture [m3 m-3 or kg kg-1]
  • Use only if soil moisture is observed and provided in the met forcing file and smd_choice = 1 or 2.
  • Use of observed soil moisture not currently tested
9 O OBS_SoilNotRocks Fraction of soil without rocks [-]
  • Use only if soil moisture is observed and provided in the met forcing file and smd_choice = 1 or 2.
  • Use of observed soil moisture not currently tested

SUEWS_Conductance.txt

SUEWS_Conductance.txt contains the parameters needed for the Jarvis (1976) 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)[1]) and should be used with gsModel=1. An alternative formulation (gsModel=2) uses slightly different functional forms and different coefficients (with different units).

No. Use Column name Example Description
1 L Code Code linking to the CondCode column in SUEWS_SiteSelect.txt.

Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.

2 MD G1 16.4764 Related to maximum surface conductance [mm s-1]
3 MD G2 566.0923 Related to Kdown dependence [W m-2]
4 MD G3 0.2163 Related to VPD dependence [units depend on gsChoice in RunControl.nml ]
5 MD G4 3.3649 Related to VPD dependence [units depend on gsChoice in RunControl.nml ]
6 MD G5 11.0764 Related to temperature dependence [°C]
7 MD G6 0.0176 Related to soil moisture dependence [mm-1]
8 MD TH 40 Upper air temperature limit [°C]
9 MD TL 0 Lower air temperature limit [°C]
10 MD S1 0.45 Related to soil moisture dependence [-]

These will change in the future to ensure consistency with soil behaviour

11 MD S2 15 Related to soil moisture dependence [mm]

These will change in the future to ensure consistency with soil behaviour

12 MD Kmax 1200 Maximum incoming shortwave radiation [W m-2]
13 MD gsModel 1 Determines which surface conductance parameterisation to use
  • 1 = Järvi et al. (2011)[1]
  • 2 = Ward et al. (2016)[2] Recommended.

The parameterisation specified here must match the coefficients specified in the other columns of SUEWS_Conductance.txt.

SUEWS_AnthropogenicHeat.txt

SUEWS_AnthropogenicHeatFlux.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 (AnthropHeatMethod = 2 in 4.1 RunControl.nml) or the method of Loridan et al. (2011) based on air temperature (AnthropHeatMethod = 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 AnthropHeatMethod = 0 in RunControl.nml), in which case all columns here except Code and BaseTHDD should be set to ’-999’.

No. Use Column name Example Description
1 L Code 331 Code linking to the AnthropogenicCode column in SUEWS_SiteSelect.txt.

Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.

2 MU BaseTHDD 18.2 Base temperature for heating degree days [°C]

e.g. Sailor and Vasireddy (2006)[39]

3 MU, O QF_A_Weekday Base value for QF on weekdays [W m-2 (Cap ha-1)-1]
  • Use with AnthropHeatChoice = 2
Example values [W m-2 (Cap ha-1)-1]
0.3081 Järvi et al. (2011)[1]
0.1000 Järvi et al. (2014)[15]
4 MU, O QF_B_Weekday Parameter related to cooling degree days on weekdays [W m-2 K-1 (Cap ha-1)-1]
  • Use with AnthropHeatMethod = 2
Example values [W m-2 K-1 (Cap ha-1)-1]
0.0099 Järvi et al. (2011)[1]
0.0099 Järvi et al. (2014)[15]
5 MU, O QF_C_Weekday Parameter related to heating degree days on weekdays [W m-2 K-1 (Cap ha-1)-1]
  • Use with AnthropHeatMethod = 2
Example values [W m-2 K-1 (Cap ha-1)-1]
0.0102 Järvi et al. (2011)[1]
0.0102 Järvi et al. (2014)[15]
6 MU, O QF_A_Weekend Base value for QF on weekends [W m-2 (Cap ha-1)-1]
  • Use with AnthropHeatMethod = 2
Example values [W m-2 (Cap ha-1)-1]
0.3081 Järvi et al. (2011)[1]
0.1000 Järvi et al. (2014)[15]
7 MU, O QF_B_Weekend 0-1 Parameter related to cooling degree days on weekends [W m-2 K-1 (Cap ha-1)-1]
  • Use with AnthropHeatMethod = 2
Example values [W m-2 K-1 (Cap ha-1)-1]
0.0099 Järvi et al. (2011)[1]
0.0099 Järvi et al. (2014)[15]
8 MU, O QF_C_Weekend Parameter related to heating degree days on weekends [W m-2 K-1 (Cap ha-1)-1]

Use with AnthropHeatMethod = 2

Example values [W m-2 K-1 (Cap ha-1)-1]
0.0102 Järvi et al. (2011)[1]
0.0102 Järvi et al. (2014)[15]
9 MU, O AHMin 15 Minimum QF [W m-2]
  • Use with AnthropHeatMethod = 1

e.g. Loridan et al. (2011)[5]

10 MU, O AHSlope 2.7 Slope of QF versus air temperature [W m-2 K-1]
  • Use with AnthropHeatMethod = 1

e.g. Loridan et al. (2011)[5]

11 MU, O TCritic 7 Critical temperature [°C]
  • Use with AnthropHeatMethod = 1

e.g. Loridan et al. (2011)[5]

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), in which case all columns here except Code should be set to '-999'.

No. Use Column name Example Description
1 L Code Code linking to [[#SUEWS_SiteSelect.txt|SUEWS_SiteSelect.txt] for irrigation modelling (IrrigationCode).

Value of integer is arbitrary but must match codes specified in SUEWS_SiteSelect.txt.

2 MU Ie_start 1-366 Day when irrigation starts [DOY]
3 MU Ie_end 1-366 Day when irrigation ends [DOY]
4 MU InternalWaterUse 0 Internal water use [mm h-1]
5 MU Faut 0-1 Fraction of irrigated area that is irrigated using automated systems (e.g. sprinklers).
6 MD Ie_a1 -84.54 Coefficient for automatic irrigation model [mm d-1]
7 MD Ie_a2 9.96 Coefficient for automatic irrigation model [mm d-1 °C-1]
8 MD Ie_a3 3.67 Coefficient for automatic irrigation model [mm d-2]
9 MD Ie_m1 -25.36 Coefficient for manual irrigation model [mm d-1]
10 MD Ie_m2 3.00 Coefficient for manual irrigation model [mm d-1 °C-1]
11 MD Ie_m3 1.10 Coefficient for manual irrigation model [mm d-2]
12 MU DayWat(1) 0 or 1 Irrigation allowed on Sundays [1], if not [0]
13 MU DayWat(2) 0 or 1 Irrigation allowed on Mondays [1], if not [0]
14 MU DayWat(3) 0 or 1 Irrigation allowed on Tuesdays [1], if not [0]
15 MU DayWat(4) 0 or 1 Irrigation allowed on Wednesdays [1], if not [0]
16 MU DayWat(5) 0 or 1 Irrigation allowed on Thursdays [1], if not [0]
17 MU DayWat(6) 0 or 1 Irrigation allowed on Fridays [1], if not [0]
18 MU DayWat(7) 0 or 1 Irrigation allowed on Saturdays [1], if not [0]
19 MU DayWatPer(1) 0-1 Fraction of properties using irrigation on Sundays [0-1]
20 MU DayWatPer(2) 0-1 Fraction of properties using irrigation on Mondays [0-1]
21 MU DayWatPer(3) 0-1 Fraction of properties using irrigation on Tuesdays [0-1]
22 MU DayWatPer(4) 0-1 Fraction of properties using irrigation on Wednesdays [0-1]
23 MU DayWatPer(5) 0-1 Fraction of properties using irrigation on Thursdays [0-1]
24 MU DayWatPer(6) 0-1 Fraction of properties using irrigation on Fridays [0-1]
25 MU DayWatPer(7) 0-1 Fraction of properties using irrigation on Saturdays [0-1]

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) - not used in v2017a.
No. Use Column name Example Description
1 L Code Code linking to the following columns in SUEWS_SiteSelect.txt:
  • EnergyUseProfWD : Anthropogenic heat flux, weekdays
  • EnergyUseProfWE : Anthropogenic heat flux, weekends
  • WaterUseProfManuWD : Manual irrigation, weekdays
  • WaterUseProfManuWE : Manual irrigation, weekends
  • WaterUseProfAutoWD : Automatic irrigation, weekdays
  • WaterUseProfAutoWE: Automatic irrigation, weekends
  • SnowClearingProfWD : Snow clearing, weekdays
  • SnowClearingProfWE: Snow clearing, weekends
  • ActivityProfWD: Human activity, weekdays
  • ActivityProfWE: Human activity, weekends
  • Value of integer is arbitrary but must match codes specified in SUEWS_SiteSelect.txt.
2-25 MU 0-23 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 (SnowLimRemove column) are exceeded.

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 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).
1 2 3 4 5 6 7 8 9 10
Code ToPaved ToBuilt ToEveTr ToDecTr ToGrass ToBSoil ToWater ToRunoff ToSoilStore
10 0 0 0 0 0 0 0 1 0 ! Paved
20 0.06 0 0.01 0.01 0.01 0.01 0 0.9 0 ! Bldgs
30 0 0 0 0 0 0 0 0 1 ! EveTr
40 0 0 0 0 0 0 0 0 1 ! DecTr
50 0 0 0 0 0 0 0 0 1 ! Grass
60 0 0 0 0 0 0 0 0 1 ! BSoil
70 0 0 0 0 0 0 0 0 0 ! Water

SUEWS_OHMCoefficients.txt

OHM, the Objective Hysteresis Model (Grimmond et al. 1991)[9] 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, AnOHM 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, thermal conductivity and bulk transfer coefficient. These are specified in SUEWS_NonVeg.txt, SUEWS_Veg.txt, SUEWS_Water.txt and SUEWS_Snow.txt. No additional files are required for AnOHM.

Note AnOHM is under development in v2017a and should not be used!

No. Use Column name Example Description
1 L Code 331 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.

2 MU a1 Coefficient for Q* term [-]
3 MU a2 Coefficient for dQ*/dt term [h]
4 MU a3 Constant term [W m-2]

SUEWS_ESTMCoefficients.txt

Note ESTM is under development in v2017a and should not be used!

The Element Surface Temperature Method (ESTM) (Offerle et al., 2005) calculates the net storage heat flux from surface temperatures. In the method the three-dimensional urban volume is reduced to four 1-d elements (i.e. building roofs, walls, and internal mass and ground (road, vegetation, etc)). The storage heat flux is calculated from the heat conduction through the different elements. For the inside surfaces of the roof and walls, and both surfaces for the internal mass (ceilings/floors, internal walls), the surface temperature of the element is determined by setting the conductive heat transfer out of (in to) the surface equal to the radiative and convective heat losses (gains). Each element (roof, wall, internal element and ground) can have maximum five layers and each layer has three parameters tied to it: thickness (x), thermal conductivity (k), volumetric heat capacity (rhoCp).

If ESTM is used (QSchoice=4), the files SUEWS_ESTMCoefficients.txt, ESTMinput.nml and SS_YYYY_ESTM_Ts_data_tt.txt should be prepared.

SUEWS_ESTMCoefficients.txt contains the parameters for the layers of each of the elements (roofs, wall, ground, internal mass).

  • If less than five layers are used, the parameters for unused layers should be set to -999.
  • The ESTM coefficients with the prefix Surf_ must be specified for each surface type (plus snow) but the Wall_ and Internal_ variables apply to the building surfaces only.
  • For each grid, one set of ESTM coefficients must be specified for each surface type; for paved and building surfaces it is possible to specify up to three and five sets of coefficients per grid (e.g. to represent different building materials) using the relevant columns in SUEWS_SiteSelect.txt. For the model to use these columns in site select, the ESTMCode column in SUEWS_NonVeg.txt should be set to zero.
No. Use Column name Example Description
1 L Code 331 Code linking to the ESTMCode column in SUEWS_NonVeg.txt, SUEWS_Veg,txt, SUEWS_Water.txt and SUEWS_Snow.txt files.
  • 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.
2 MU Surf_thick1 0.2 Thickness of the first layer [m] for roofs (building surfaces) and ground (all other surfaces)
3 MU Surf_k1 0.5 Thermal conductivity of the first layer [W m-1 K-1]
4 MU Surf_rhoCp1 840000 Volumetric heat capacity of the first layer [J m-3 K-1]
5 O Surf_thick2 - Thickness of the second layer [m] (if no second layer, set to -999.)
6 O Surf_k2 - Thermal conductivity of the second layer [W m-1 K-1]
7 O Surf_rhoCp2 - Volumetric heat capacity of the second layer [J m-3 K-1]
8 O Surf_thick3 - Thickness of the third layer [m] (if no third layer, set to -999.)
9 O Surf_k3 - Thermal conductivity of the third layer[W m-1 K-1]
10 O Surf_rhoCp3 - Volumetric heat capacity of the third layer[J m-3 K-1]
11 O Surf_thick4 - Thickness of the fourth layer [m] (if no fourth layer, set to -999.)
12 O Surf_k4 - Thermal conductivity of the fourth layer[W m-1 K-1]
13 O Surf_rhoCp4 - Volumetric heat capacity of the fourth layer [J m-3 K-1]
14 O Surf_thick5 - Thickness of the fifth layer [m] (if no fifth layer, set to -999.)
15 O Surf_k5 - Thermal conductivity of the fifth layer [W m-1 K-1]
16 O Surf_rhoCp5 - Volumetric heat capacity of the fifth layer [J m-3 K-1]
17 MU Wall_thick1 - Thickness of the first layer [m] for building surfaces only; set to -999 for all other surfaces
18 MU Wall_k1 - Thermal conductivity of the first layer [W m-1 K-1]
19 MU Wall_rhoCp1 - Volumetric heat capacity of the first layer [J m-3 K-1]
20 O Wall_thick2 - Thickness of the second layer [m] (if no second layer, set to -999.)
21 O Wall_k2 - Thermal conductivity of the second layer [W m-1 K-1]
22 O Wall_rhoCp2 - Volumetric heat capacity of the second layer [J m-3 K-1]
23 O Wall_thick3 - Thickness of the third layer [m] (if no third layer, set to -999.)
24 O Wall_k3 - Thermal conductivity of the third layer [W m-1 K-1]
25 O Wall_rhoCp3 - Volumetric heat capacity of the third layer [J m-3 K-1]
26 O Wall_thick4 - Thickness of the fourth layer [m] (if no fourth layer, set to -999.)
27 O Wall_k4 - Thermal conductivity of the fourth layer[W m-1 K-1]
28 O Wall_rhoCp4 - Volumetric heat capacity of the fourth layer [J m-3 K-1]
29 O Wall_thick5 - Thickness of the fifth layer [m] (if no fifth layer, set to -999.)
30 O Wall_k5 - Thermal conductivity of the fifth layer[W m-1 K-1]
31 O Wall_rhoCp5 - Volumetric heat capacity of the fifth layer [J m-3 K-1]
32 MU Internal_thick1 - Thickness of the first layer [m] for building surfaces only; set to -999 for all other surfaces
33 MU Internal_k1 - Thermal conductivity of the first layer [W m-1 K-1]
34 MU Internal_rhoCp1 - Volumetric heat capacity of the first layer[J m-3 K-1]
35 O Internal_thick2 - Thickness of the second layer [m] (if no second layer, set to -999.)
36 O Internal_k2 - Thermal conductivity of the second layer [W m-1 K-1]
37 O Internal_rhoCp2 - Volumetric heat capacity of the second layer [J m-3 K-1]
38 O Internal_thick3 - Thickness of the third layer [m] (if no third layer, set to -999.)
39 O Internal_k3 - Thermal conductivity of the third layer [W m-1 K-1]
40 O Internal_rhoCp3 - Volumetric heat capacity of the third layer[J m-3 K-1]
41 O Internal_thick4 - Thickness of the fourth layer [m] (if no fourth layer, set to -999.)
42 O Internal_k4 - Thermal conductivity of the fourth layer [W m-1 K-1]
43 O Internal_rhoCp4 - Volumetric heat capacity of the fourth layer [J m-3 K-1]
44 O Internal_thick5 - Thickness of the fifth layer [m] (if no fifth layer, set to -999.)
45 O Internal_k5 - Thermal conductivity of the fifth layer [W m-1 K-1]
46 O Internal_rhoCp5 - Volumetric heat capacity of the fifth layer [J m-3 K-1]
47 MU nroom - Number of rooms per floor for building surfaces only
48 MU Internal_albedo - Albedo of all internal elements for building surfaces only
49 MU Internal_emissivity - Emissivity of all internal elements for building surfaces only
50 O Internal_CHwall Bulk transfer coefficient of internal wall [W m-2 K-1] (for building surfaces only and if IbldCHmod == 0 in ESTMinput.nml
51 O Internal_CHroof Bulk transfer coefficient of internal roof [W m-2 K-1] (for building surfaces only and if IbldCHmod == 0 in ESTMinput.nml
52 O Internal_CHbld Bulk transfer coefficient of internal building elements [W m-2 K-1] (for building surfaces only and if IbldCHmod == 0 in ESTMinput.nml

Additional ESTM-related files

Depending on how the storage heat flux is calculated (specified by StorageHeatMethod in RunControl.nml), different input files are required:

Option StorageHeatMethod Files needed
OHM 1
Observations 2
  • Storage heat flux is provide in meteorological forcing file
AnOHM 3
ESTM 4

Note ESTM is under development in v2017a and should not be used!

The following input files are required if ESTM is used to calculate the storage heat flux.

ESTMinput.nml

ESTMinput.nml specifies the model settings and default values.

  • The file contents can be in any order.
Name Description
TsurfChoice Source of surface temperature data used.
0 *Tsurf in SSss_YYYY_ESTM_Ts_data_tt.txt used for all surface elements.
1 *Tground, Troof and Twall in SSss_YYYY_ESTM_Ts_data_tt.txt used.
  • Input surface temperature are different for ground, roof and wall.
2 *Tground, Troof, Twall_n, Twall_e, Twall_s and Twall_w in SSss_YYYY_ESTM_Ts_data_tt.txt used.
  • Wall surface temperature is different for four directions.
evolveTibld Source of internal building temperature (Tibld)
0 *Tiair in SSss_YYYY_ESTM_Ts_data_tt.txt used.
1 *Tibld calculated considering the effect of anthropogenic heat from HVAC
2 *Tibld calculated without considering the influence of HVAC.
IbldCHmod Method to calculate internal convective heat exchange coefficients (CH) for internal building, wall and roof if evolveTibld is 1 or 2.
0 CHs are read from SUEWS_ESTMcoefficients.txt.
1 CHs are calculated based on ASHRAE (2001)
2 CHs are calculated based on Awbi (1998).
LBC_soil Soil temperature at lowest boundary condition [˚C]
Theat_on Temperature at which heat control is turned on (used when evolveTibld =1) [˚C]
Theat_off Temperature at which heat control is turned off (used when evolveTibld=1) [˚C]
Theat_fix Ideal internal building temperature [˚C]

SSss_YYYY_ESTM_Ts_data_tt.txt

SSss_YYYY_ESTM_Ts_data_tt.txt contains a time-series of input surface temperature for roof, wall, ground and internal elements.

No. Column name Description
1 iy Year [YYYY]
2 id Day of year [DOY]
3 it Hour [H]
4 imin Minute [M]
5 Tiair Indoor air temperature [˚C]
6 Tsurf Bulk surface temperature [˚C] (used when TsurfCoice = 0)
7 Troof Roof surface temperature [˚C] (used when TsurfChoice = 1 or 2)
8 Troad Ground surface temperature [˚C] (used when TsurfChoice = 1 or 2)
9 Twall Wall surface temperature [˚C] (used when TsurfChoice = 1)
10 Twall_n North-facing wall surface temperature [˚C] (used when TsurfChoice = 2)
11 Twall_e East-facing wall surface temperature [˚C] (used when TsurfChoice = 2)
12 Twall_s South-facing wall surface temperature [˚C] (used when TsurfChoice = 2)
13 Twall_w West-facing wall surface temperature [˚C] (used when TsurfChoice = 2)

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'.

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.

InitialConditionsSSss_YYYY.nml

  • Variables can be in any order
Parameters Required/Optional Unit Comments
Soil moisture states
SoilstorePavedState R mm Initial state of the soil water storage under paved surfaces.
SoilstoreBldgsState R mm Initial state of the soil water storage under buildings
SoilstoreEveTrState R mm Initial state of the soil water storage under evergreen trees
SoilstoreDecTrState R mm Initial state of the soil water storage under deciduous trees
SoilstoreGrassState R mm Initial state of the soil water storage under grass
SoilstoreBSoilState R mm Initial state of the soil water storage under bare soil surfaces
(Note: no soil store below water surface)
Vegetation parameters Can be set individually or using a single vegetation parameter (LeavesOutInitially)
LeavesOutIntially (O) - Sets all required vegetation parameters accordingly using information for full leaf-out (1)/complete leaf-off (0)
  • If the model run starts in winter when trees are bare, set LeavesOutIntially = 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 LeavesOutIntially = 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 O °C Growing degree days for leaf growth.
  • 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 O °C Growing degree days for senescence growth.
  • 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 O m-2 m-2 Initial LAI for evergreen trees. The recommended values can be found from SUEWS_Veg.txt
LAIinitialDecTr O m-2 m-2 Initial LAI for deciduous trees. The recommended values can be found from SUEWS_Veg.txt
LAIinitialGrass O m-2 m-2 Initial LAI for irrigated grass. The recommended values can be found from SUEWS_Veg.txt
albEveTr0 O - Albedo of evergreen surface on day 0 of run
albDecTr0 O - Albedo of deciduous surface on day 0 of run
albGrass0 O - Albedo of grass surface on day 0 of run
decidCap0 O mm Deciduous storage capacity on day 0 of run.
porosity0 O - Porosity of deciduous vegetation on day 0 of run. This varies between 0.2 (leaf-on) and 0.6 (leaf-off).
Recent meteorology
DaysSinceRain O days Number of days since rainfall occurred.
  • 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 O °C Daily mean temperature [°C] for the day before the run starts
  • If unknown, SUEWS uses the mean temperature for the first day of the run.
  • Used to model irrigation and anthropogenic heat flux.
Above Ground State
PavedState O Initial wetness state of paved surface (0 indicates dry, wet otherwise).
  • If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
BldgsState O mm Initial wetness state for buildings (0 indicates dry, wet otherwise).
  • If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
EveTrState O mm Initial wetness state of evergreen trees (0 indicates dry, wet otherwise).
  • If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
DecTrState O mm Initial wetness state of deciduous trees (0 indicates dry, wet otherwise).
  • If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
GrassState O mm Initial wetness state of grass (0 indicates dry, wet otherwise).
  • If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
BSoilState O mm Initial wetness state of bare soil surface (0 indicates dry, wet otherwise).
  • If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).
WaterState O mm Initial state of water surface (must be set > 0, as 0 indicates dry surface).
  • 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.
Snow-related parameters Can be set individually or using a single snow parameter (SnowInitially)
SnowIntially (O) - Sets all required snow-related parameters accordingly if there is initially no snow
  • If the model run starts when there is no snow on the ground, set SnowIntially = 0 and the snow-related parameters will be set accordingly.
  • If the model run starts when there is snow on the ground, the following snow-related parameters must be set appropriately.
  • The value of SnowInitially overrides any values provided for the individual snow-related parameters.
  • To prevent SnowInitially 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_Snow.txt.
SnowWaterPavedState O mm Initial amount of liquid water in the snow on paved surfaces.
SnowWaterBldgsState O mm Initial amount of liquid water in the snow on buildings
SnowWaterEveTrState O mm Initial amount of liquid water in the snow on evergreen trees
SnowWaterDecTrState O mm Initial amount of liquid water in the snow on deciduous trees
SnowWaterGrassState O mm Initial amount of liquid water in the snow on grass surfaces
SnowWaterBSoilState O mm Initial amount of liquid water in the snow on bare soil surfaces
SnowWaterWaterState O mm Initial amount of liquid water in the snow in water
SnowPackPaved O mm Initial snow water equivalent if the snow on paved surfaces
SnowPackBldgs O mm Initial snow water equivalent if the snow on buildings
SnowPackEveTr O mm Initial snow water equivalent if the snow on evergreen trees
SnowPackDecTr O mm Initial snow water equivalent if the snow on deciduous trees
SnowPackGrass O mm Initial snow water equivalent if the snow on grass surfaces
SnowPackBSoil O mm Initial snow water equivalent if the snow on bare soil surfaces
SnowPackWater O mm Initial snow water equivalent if the snow on water
SnowFracPaved O - Initial plan area fraction of snow on paved surfaces
SnowFracBldgs O - Initial plan area fraction of snow on buildings
SnowFracEveTr O - Initial plan area fraction of snow on evergreen trees
SnowFracDecTr O - Initial plan area fraction of snow on deciduous trees
SnowFracGras O - Initial plan area fraction of snow on grass surfaces
SnowFracBSoil O - Initial plan area fraction of snow on bare soil surfaces
SnowFracWater O - Initial plan area fraction of snow on water
SnowDensPaved O kg m-3 Initial snow density on paved surfaces
SnowDensBldgs O kg m-3 Initial snow density on buildings
SnowDensEveTr O kg m-3 Initial snow density on evergreen trees
SnowDensDecTr O kg m-3 Initial snow density on deciduous trees
SnowDensGrass O kg m-3 Initial snow density on grass surfaces
SnowDensBSoil O kg m-3 Initial snow density on bare soil surfaces
SnowDensWater O kg m-3 Initial snow density on water

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.
  • The table below gives the required (R) 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 R iy Year [YYYY]
2 R id Day of year [DOY]
3 R it Hour [H]
4 R imin Minute [M]
5 O qn Net all-wave radiation [W m-2]
  • Required if NetRadiationMethod = 1.
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 R U Wind speed [m s-1]
11 R RH Relative Humidity [%]
12 R Tair Air temperature [°C]
13 R pres Barometric pressure [kPa]
14 R rain Rainfall [mm]
15 R kdown Incoming shortwave radiation [W m-2]
  • Must be > 0 W m-2.
16 O snow Snow [mm]
  • 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 [3]
20 O xsmd Observed soil moisture [3 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 if SOLWEIGUse = 1
23 O kdir Direct radiation [W m-2]
  • Recommended if SOLWEIGUse = 1
24 O wdir Wind direction [°]
  • Currently not implemented

CBL input files

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

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 format.
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[17].
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

CBL_Input.nml

Name Description
EntrainmentType Determines entrainment scheme. See Cleugh and Grimmond 2000[16] for details.
Value Comments
1 Tennekes and Driedonks (1981) - Recommended
2 McNaughton and Springs (1986)
3 Rayner and Watson (1991)
4 Tennekes (1973)
QH_Choice Determines QH used for CBL model.
Value Comments
1 QH modelled by SUEWS
2 QH modelled by LUMPS
3 Observed QH values are used from the meteorological input file
Wsb Subsidence velocity (m s-1) in eq. 1 and 2 of Onomura et al. (2015)[17].

(-0.01 m s-1 recommended)

CBLday(id) CBL model is used for the days you choose.
  • Set CBLday(id) = 1
  • If CBL model is set to run for DOY 175–177, CBLday(175) = 1, CBLday(176) = 1, CBLday(177) = 1
CO2_included Set to zero in current version
InitialData_use Determines initial values (see CBL_Initial_data.txt)
Value Comments
0 All initial values are calculated. (Not available in current release.)
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).
InitialDataFileName If InitialData_use ≥ 1, write the file name including the path from site directory e.g. InitialDataFileName='CBLinputfiles\CBL_initial_data.txt'
Sondeflag
Value Comments
0 Does not read radiosonde vertical profile data -recommended
1 Reads radiosonde vertical profile data
FileSonde(id) If Sondeflag=1, write the file name including the path from site directory

e.g. FileSonde(id)= 'CBLinputfiles\XXX.txt', XXX is an arbitrary name.

SOLWEIG input files

If the SOLWEIG model option is used (SOLWEIGout=1), spatial data and a SOLWEIGInput.nml file need to be prepared. The Digital Surface Models (DSMs) as well as derivatives originating from DSMs, e.g. Sky View Factors (SVF) must have the same spatial resolution and extent. Since SOLWEIG is a 2D model it will considerably increase computation time and should be used with care.

Description of choices in SOLWEIGinput_file.nml file. The file can be in any order.

Name Units Description
Posture - Determines the posture of a human for which the radiant fluxes should be considered
1 Standing (default)
2 Sitting
absL - Absorption coefficient of longwave radiation of a person.
  • Recommended value: 0.97
absK - Absorption coefficient of shortwave radiation of a person.
  • Recommended value: 0.70
heightgravity m Centre of gravity for a person.
  • Recommended value for a standing man: 1.1 m
usevegdem - Vegetation scheme
1 Vegetation scheme is active (Lindberg and Grimmond 2011[19])
2 No vegetation scheme used
DSMPath - Path to Digital Surface Models (DSM).
DSMname - Ground and Building DSM
CDSMname - Vegetation canopy DSM
TDSMname - Vegetation trunk zone DSM
TransMin - Tranmissivity of K through deciduous vegetation (leaf on)
  • Recommended value: 0.02 (Konarska et al. 2014[40])
TransMax - Tranmissivity of K through deciduous vegetation (leaf off)
  • Recommended value: 0.50 (Konarska et al. 2014[40])
SVFPath - Path to SVFs matrices (See Lindberg and Grimmond (2011)[19] for details)
SVFSuffix - Suffix used (if any)
BuildingName - Boolean matrix for locations of building pixels
row - X coordinate for point of interest. Here all variables from the model will written to SOLWEIGpoiOUT.txt
col - Y coordinate for point of interest. Here all variables from the model will written to SOLWEIGpoiOUT.txt
onlyglobal - Global radiation
0 Diffuse and direct shortwave radiation taken from met forcing file.
1 Diffuse and direct shortwave radiation calculated from Reindl et al. (1990)[41]
SOLWEIGpoi_out - Write output variables at point of interest (see below)
0 No POI output
Tmrt_out -
0 No grid output
1 Write grid to file (saves as ERSI Ascii grid)
Lup2d_out -
0 No grid output
1 Write grid to file (saves as ERSI Ascii grid)
Ldown2d_out -
0 No grid output
1 Write grid to file (saves as ERSI Ascii grid)
Kup2d_out -
0 No grid output
1 Write grid to file (saves as ERSI Ascii grid)
Kdown2d_out -
0 No grid output
1 Write grid to file (saves as ERSI Ascii grid)
GVF_out -
0 No grid output
1 Write grid to file (saves as ERSI Ascii grid)
SOLWEIG_ldown -
0 Not active (use SUEWS to estimate Ldown above canyon)
1 Use SOLWEIG to estimate Ldown above canyon
OutInterval min Output interval. Set to 60 in current version.
RunForGrid - Grid for which SOLWEIG should be run.
-999 All grids (use with care)

Output files

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).

Error 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_TT.txt

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

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] Do not use in v2017b!
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 [m2 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] Do not use in v2017b!
65 FcPhoto 0,1 CO2 flux from photosynthesis [umol m-2 s-1] Do not use in v2017b!
66 FcRespi 0,1 CO2 flux from respiration [umol m-2 s-1] Do not use in v2017b!
67 FcMetab 0,1 CO2 flux from metabolism [umol m-2 s-1] Do not use in v2017b!
68 FcTraff 0,1 CO2 flux from traffic [umol m-2 s-1] Do not use in v2017b!
69 FcBuild 0,1 CO2 flux from buildings [umol m-2 s-1] Do not use in v2017b!
70 QNSnowFr 1 Net all-wave radiation for snow-free area [W m-2]
71 QNSnow 1 Net all-wave radiation for snow area [W m-2]
72 AlbSnow 1 Snow albedo [-]
73 QM 1 Snow-related heat exchange [W m-2]
74 QMFreeze 1 Internal energy change [W m-2]
75 QMRain 1 Heat released by rain on snow [W m-2]
76 SWE 1 Snow water equivalent [mm]
77 MeltWater 1 Meltwater [mm]
78 MeltWStore 1 Meltwater store [mm]
79 SnowCh 1 Change in snow pack [mm]
80 SnowRPaved 1 Snow removed from paved surface [mm]
81 SnowRBldgs 1 Snow removed from building surface [mm]
82 T2 0,1,2 Air temperature at 2 m agl [°C]
83 Q2 0,1,2 Air specific humidity at 2 m agl [k kg-2]
84 U10 0,1,2 Wind speed at 10 m agl [m s-1]

SSss_YYYY_nn_TT.nc (when ncMode=1 in RunControl)

SUEWS can also produce the main output file in netCDF format by setting ncMode=1 (set in RunControl).

As the date and time information is incorporated in the netCDF output as separate dimension, the first five variables in the normal text output file (in .txt) are not included in the netCDF output but other variables are all kept.

N.B., considering the file size limit by the classic netCDF format, the output frequency is determined automatically by the internal SUEWS program setting to avoid the oversize problem in the netCDF files.

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 iy Year [YYYY]
2 id Day of year [DOY]
3 HDD1_h Heating degree days [°C]
4 HDD2_c Cooling degree days [°C]
5 HDD3_Tmean Average daily air temperature [°C]
6 HDT4_T5d 5-day running-mean air temperature [°C]
7 P/day Daily total precipitation [mm]
8 DaysSR Days since rain [days]
9 GDD1_g Growing degree days for leaf growth [°C]
10 GDD2_s Growing degree days for senescence [°C]
11 GDD3_Tmin Daily minimum temperature [°C]
12 GDD4_Tmax Daily maximum temperature [°C]
13 GDD5_DayLHrs Day length [h]
14 LAI_EveTr Leaf area index of evergreen trees [m-2 m-2]
15 LAI_DecTr Leaf area index of deciduous trees [m-2 m-2]
16 LAI_Grass Leaf area index of grass [m-2 m-2]
17 DecidCap Moisture storage capacity of deciduous trees [mm]
18 Porosity Porosity of deciduous trees [-]
19 AlbEveTr Albedo of evergreen trees [-]
20 AlbDecTr Albedo of deciduous trees [-]
21 AlbGrass Albedo of grass [-]
22 WU_EveTr(1) Total water use for evergreen trees [mm]
23 WU_EveTr(2) Automatic water use for evergreen trees [mm]
24 WU_EveTr(3) Manual water use for evergreen trees [mm]
25 WU_DecTr(1) Total water use for deciduous trees [mm]
26 WU_DecTr(2) Automatic water use for deciduous trees [mm]
27 WU_DecTr(3) Manual water use for deciduous trees [mm]
28 WU_Grass(1) Total water use for grass [mm]
29 WU_Grass(2) Automatic water use for grass [mm]
30 WU_Grass(3) Manual water use for grass [mm]
31 deltaLAI Change in leaf area index (normalised 0-1) [-]
32 LAIlumps Leaf area index used in LUMPS (normalised 0-1) [-]
33 AlbSnow Snow albedo [-]
34 DensSnow_Paved Snow density - paved surface [kg m-3]
35 DensSnow_Bldgs Snow density - building surface [kg m-3]
36 DensSnow_EveTr Snow density - evergreen surface [kg m-3]
37 DensSnow_DecTr Snow density - deciduous surface [kg m-3]
38 DensSnow_Grass Snow density - grass surface [kg m-3]
39 DensSnow_BSoil Snow density - bare soil surface [kg m-3]
40 DensSnow_Water Snow density - water surface [kg m-3]

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 InitialConditionsSSss_YYYY.nml

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_60.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-11]
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_Bdgs 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_EveTt 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_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).

Col Header Name 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

SOLWEIGpoiOut.txt

Calculated variables from POI, point of interest (row, col) stated in SOLWEIGinput.nml.

SOLWEIG model output file format: SOLWEIGpoiOUT.txt

Col Header Name Units
1 id Day of year
2 dectime Decimal time
3 azimuth Azimuth angle of the Sun °
4 altitude Altitude angle of the Sun °
5 GlobalRad Input Kdn W m-2
6 DiffuseRad Diffuse shortwave radiation W m-2
7 DirectRad Direct shortwave radiation W m-2
8 Kdown2d Incoming shortwave radiation at POI W m-2
9 Kup2d Outgoing shortwave radiation at POI W m-2
10 Ksouth Shortwave radiation from south at POI W m-2
11 Kwest Shortwave radiation from west at POI W m-2
12 Knorth Shortwave radiation from north at POI W m-2
13 Keast Shortwave radiation from east at POI W m-2
14 Ldown2d Incoming longwave radiation at POI W m-2
15 Lup2d Outgoing longwave radiation at POI W m-2
16 Lsouth Longwave radiation from south at POI W m-2
17 Lwest Longwave radiation from west at POI W m-2
18 Lnorth Longwave radiation from north at POI W m-2
19 Least Longwave radiation from east at POI W m-2
20 Tmrt Mean Radiant Temperature °C
21 I0 theoretical value of maximum incoming solar radiation W m-2
22 CI clearness index for Ldown (Lindberg et al. 2008)
23 gvf Ground view factor (Lindberg and Grimmond 2011)
24 shadow Shadow value (0= shadow, 1 = sun)
25 svf Sky View Factor from ground and buildings
26 svfbuveg Sky View Factor from ground, buildings and vegetation
27 Ta Air temperature °C
28 Tg Surface temperature °C

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

Col Header Name 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

Troubleshooting

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

is 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

Email list

  • SUEWS email list

https://www.lists.reading.ac.uk/mailman/listinfo/met-suews

  • UMEP email list

https://www.lists.reading.ac.uk/mailman/listinfo/met-umep

Acknowledgements

  • People who have contributed to the development of SUEWS (plus co-authors of papers):
  • Current contributors:
    • Prof C.S.B. Grimmond (University of Reading; previously Indiana University, King’s College London, UK); Dr Leena Järvi (University of Helsinki, Finland); Dr Helen Ward (University of Reading), Dr Fredrik Lindberg (Göteborg University, Sweden), Dr Andy Gabey (Reading), Dr Ting SUN (Reading), Dr Jie PENG (SIMS), Dr Natalie Theeuwes (Reading),
  • Past Contributors:
    • Dr Brian Offerle (Indiana University), Dr Thomas Loridan (King’s College London),Dr Shiho Onomura (Göteborg University, Sweden)
  • Users who have brought things to our attention to improve this manual and the model:
    • Dr Andy Coutts (Monash University, Australia), Kerry Nice (Monash University, Australia), Shiho Onomura (Göteborg University, Sweden), Dr Stefan Smith (University of Reading, UK), Dr Helen Ward (King’s College London, UK; University of Reading, UK); Duick Young (King’s College London), Dr Ning Zhang (Nanjing University, China)
  • Funding to support development:
    • National Science Foundation (USA, BCS-0095284, ATM-0710631), EU Framework 7 BRIDGE (211345), EUf7 emBRACE; UK Met Office; NERC ClearfLo, NERC/Belmont TRUC, Newton/Met Office CSSP-China, H2020 UrbanFluxes, EPSRC LoHCool

Notation

Definition
λF frontal area index
ΔQS storage heat flux
BLUEWS Boundary Layer part of SUEWS
Relation between BLUEWS and SUEWS Source: [17]
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[13])
Grass Grass surface
BSoil Unmanaged land and/or bare soil
L↓ incoming longwave radiation
LAI Leaf area index
LUMPS Local scale Urban Meteorological Parameterization Scheme (Loridan et al. 2011[5])
NARP Net All-wave Radiation Parameterization (Offerle et al. 2003[4], Loridan et al. 2011[5])
OHM Objective Hysteresis Model (Grimmond et al. 1991[9], Grimmond & Oke 1999a[10], 2002[11])
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[18], Lindberg and Grimmond 2011[19])
SVF Sky view factor
theta potential temperature
tt time step of data
UMEP Urban Multi-scale Environmental Predictor
Water Water surface
zi Convective boundary layer height

Development, Suggestions and Support

  1. Coding Guidelines
  2. Recommendations, Errors, Help/Updates - please join our email list
    1. www.lists.reading.ac.uk/mailman/listinfo/met-suews
    2. As UMEP has a number of tools to support SUEWS you may want to join that list also www.lists.reading.ac.uk/mailman/listinfo/met-umep

Version History

New in SUEWS Version 2017c

New in SUEWS 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 v2017b.
  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.

New in SUEWS 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 v2017a.

New in SUEWS 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 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

New in SUEWS Version 2014b (released 8 October 2014)

[V2014 manual] 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 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.

New in SUEWS Version 2014a.1 (released 26 February 2014)

  1. Please see the large number of changes made in the 2014a release.
  2. This is a minor change to address installing the software.
  3. Minor updates to the manual

New in SUEWS 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. 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

New in SUEWS 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

New in SUEWS 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

New in SUEWS 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

New in SUEWS Version2011b

  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 AnthropHeatChoice = 1

V2012a this became obsolete OHM file (SSss_YYYY.ohm)

Differences between SUEWS, LUMPS and FRAISE

The largest difference between LUMPS and SUEWS is that the latter simulates the urban water balance in detail while LUMPS takes a simpler approach for the sensible and latent heat fluxes and the water balance (“water bucket”). The calculation of evaporation/latent heat in SUEWS is more biophysically based. Due to its simplicity, LUMPS requires less parameters in order to run. SUEWS gives turbulent heat fluxes calculated with both models as an output. The model can run LUMPS alone without running SUEWS (Table 4.1 – SuewsStatus).

Similarities and differences between LUMPS and SUEWS.

LUMPS SUEWS
Net all-wave radiation (Q*) Input or NARP Input or NARP
Storage heat flux (ΔQS) Input or from OHM Input or from OHM
Anthropogenic heat flux (QF) Input or calculated Input or calculated
Latent heat (QE) DeBruin and Holtslag (1982) Penman-Monteith equation2
Sensible heat flux (QH) DeBruin and Holtslag (1982) Residual from available energy minus QE
Water balance No water balance included Running water balance of canopy and water balance of soil
Soil moisture Not considered Modelled
Surface wetness Simple water bucket model Running water balance
Irrigation Only fraction of surface area that is irrigated Input or calculated with a simple model
Surface cover buildings, paved, vegetation buildings, paved, coniferous and deciduous trees/shrubs, irrigated and unirrigated grass

FRAISE Flux Ratio – Active Index Surface Exchange

FRAISE provides an estimate of mean midday (±3 h around solar noon) energy partitioning from information on the surface characteristics and estimates of the mean midday incoming radiative energy and anthropogenic heat release. Please refer to Loridan and Grimmond (2012)[42] for further details.

Topic FRAISE LUMPS SUEWS
Complexity Simplest: FRAISE More complex: SUEWS
Software provided: R code Windows exe (written in Fortran) Windows exe (written in Fortran) - other versions available
Applicable period: Midday (within 3 h of solar noon) hourly 5 min-hourly-annual
Unique features: calculates active surface – and fluxes radiation and energy balances radiation, energy and water balance (includes LUMPS)

References

  1. 1.00 1.01 1.02 1.03 1.04 1.05 1.06 1.07 1.08 1.09 1.10 1.11 1.12 1.13 1.14 1.15 1.16 1.17 1.18 1.19 1.20 1.21 1.22 1.23 1.24 1.25 1.26 1.27 1.28 1.29 1.30 1.31 1.32 1.33 1.34 1.35 1.36 1.37 1.38 1.39 1.40 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.
  2. 2.0 2.1 2.2 2.3 2.4 2.5 2.6 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
  3. 3.00 3.01 3.02 3.03 3.04 3.05 3.06 3.07 3.08 3.09 3.10 3.11 3.12 3.13 3.14 Grimmond CSB & Oke TR (1991) An Evaporation-Interception Model for Urban Areas. Water Resour. Res. 27, 1739-1755.
  4. 4.0 4.1 Offerle B, Grimmond CSB & Oke TR (2003) Parameterization of Net All-Wave Radiation for Urban Areas. J. Appl. Meteorol. 42, 1157-1173.
  5. 5.00 5.01 5.02 5.03 5.04 5.05 5.06 5.07 5.08 5.09 5.10 5.11 5.12 5.13 5.14 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
  6. 6.0 6.1 Allen L, F Lindberg, CSB Grimmond (2011) Global to city scale model for anthropogenic heat flux, International Journal of Climatology, 31, 1990-2005.
  7. 7.0 7.1 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
  8. Iamarino M, Beevers S & Grimmond CSB (2011) High-resolution (space, time) anthropogenic heat emissions: London 1970-2025. International J. of Climatology. 32, 1754-1767.
  9. 9.0 9.1 9.2 9.3 Grimmond CSB, Cleugh HA & Oke TR (1991) An objective urban heat storage model and its comparison with other schemes. Atmos. Env. 25B, 311-174.
  10. 10.0 10.1 10.2 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.
  11. 11.0 11.1 11.2 11.3 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.
  12. 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.
  13. 13.0 13.1 13.2 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
  14. Grimmond CSB, Oke TR and Steyn DG (1986) Urban water-balance 1. A model for daily totals. Water Resour Res 22: 1397-1403.
  15. 15.00 15.01 15.02 15.03 15.04 15.05 15.06 15.07 15.08 15.09 15.10 15.11 15.12 15.13 15.14 15.15 15.16 15.17 15.18 15.19 15.20 15.21 15.22 15.23 15.24 15.25 15.26 15.27 15.28 15.29 15.30 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.
  16. 16.0 16.1 16.2 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.
  17. 17.0 17.1 17.2 17.3 17.4 17.5 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
  18. 18.0 18.1 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.
  19. 19.0 19.1 19.2 19.3 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.
  20. 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.
  21. 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.
  22. 22.0 22.1 22.2 Dyer AJ (1974) A review of flux-profile relationships. Boundary-Layer Meteorol. 7, 363-372.
  23. 23.0 23.1 23.2 23.3 23.4 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.
  24. Van Ulden AP & Holtslag AAM (1985) Estimation of atmospheric boundary layer parameters for boundary layer applications. J. Clim. Appl. Meteorol. 24, 1196-1207.
  25. 25.0 25.1 Campbell GS & Norman JM (1998) Introduction to Environmental Biophysics. Springer Science, US.
  26. 26.0 26.1 Businger JA, Wyngaard JC, Izumi Y & Bradley EF (1971) Flux-Profile Relationships in the Atmospheric Surface Layer. J. Atmos. Sci., 28, 181–189.
  27. 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.
  28. 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.
  29. 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.
  30. Grimmond CSB & Oke TR (1999) Aerodynamic properties of urban areas derived from analysis of surface form. J. Appl. Meteorol. 38, 1262-1292.
  31. MacDonald RW, Griffiths RF & Hall DJ (1998) An improved method for estimation of surface roughness of obstacle arrays. Atmos. Env. 32, 1857-1864.
  32. 32.0 32.1 32.2 32.3 Falk J & Niemczynowicz J, (1978) Characteristics of the above ground runoff in sewered catchments, in Urban Storm Drainage, edited by Helliwell PR, Pentech, London
  33. 33.0 33.1 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
  34. 34.0 34.1 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.
  35. 35.00 35.01 35.02 35.03 35.04 35.05 35.06 35.07 35.08 35.09 35.10 Oke TR (1987) Boundary Layer Climates. Routledge, London, UK
  36. 36.0 36.1 36.2 36.3 36.4 36.5 36.6 36.7 36.8 Breuer L, Eckhardt K and Frede H-G (2003) Plant parameter values for models in temperate climates. Ecol. Model. 169, 237-293.
  37. 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.
  38. Auer AH (1974) The rain versus snow threshold temperatures. Weatherwise, 27, 67.
  39. Sailor DJ and Vasireddy C (2006) Correcting aggregate energy consumption data account for variability in local weather. Environ. Modell. Softw. 21, 733-738.
  40. 40.0 40.1 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.
  41. Reindl DT, Beckman WA and Duffie JA (1990) Diffuse fraction correlation. Sol Energy 45:1–7.
  42. 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