Note

Please report issues with the manual on the GitHub page.

SUEWS: Surface Urban Energy and Water Balance Scheme

• How to get SUEWS?

  • Latest release:

    The latest formal release of SUEWS is Version 2020a (Released on 14 May 2020) and can be downloaded via our Zenodo repository (a sample input dataset is included in the release archive).

  • Previous releases:

    Previous releases can be downloaded via our GitHub page.

• How to use SUEWS?

  • For existing users:

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

  Tip

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

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

  • For new users:

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

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

• How has SUEWS been used?

The scientific details and application examples of SUEWS can be found in Recent publications.

• How to cite SUEWS?

  Tip

  Visit the repositories below for different citation styles.

  • Software with manual:

    Ting Sun, Leena Järvi, Hamidreza Omidvar, Natalie Theeuwes, Fredrik Lindberg, Zhenkun Li, & Sue Grimmond. (2019, November 8). Urban-Meteorology-Reading/SUEWS: 2019a Release (Version 2019a). Zenodo.

• How to support SUEWS?

  1. Cite SUEWS appropriately in your work.

  2. Contribute to the development.

  3. Report issues via the GitHub page.

  4. Provide suggestions and feedback.

Note

Please report issues with the manual on the GitHub page.

Introduction

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

Overview of SUEWS

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

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

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

The seven surface types considered in SUEWS

Note

Please report issues with the manual on the GitHub page.

Parameterisations and sub-models within SUEWS

Net all-wave radiation, Q*

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

1. Observed net all-wave radiation can be provided as input instead of being calculated by the model.

2. Observed incoming shortwave and incoming longwave components can be provided as input, instead of incoming longwave being calculated by the model.

3. Other data can be provided as input, such as cloud fraction (see options in RunControl.nml).

4. NARP (Net All-wave Radiation Parameterization, Offerle et al. 2003 [O2003] , Loridan et al. 2011 [L2011] ) scheme calculates outgoing shortwave and incoming and outgoing longwave radiation components based on incoming shortwave radiation, temperature, relative humidity and surface characteristics (albedo, emissivity).

Anthropogenic heat flux, Q_F

1. Two simple anthropogenic heat flux sub-models exist within SUEWS:

   • Järvi et al. (2011) [J11] approach, based on heating and cooling degree days and population density (allows distinction between weekdays and weekends).

   • Loridan et al. (2011) [L2011] approach, based on a linear piece-wise relation with air temperature.

2. Pre-calculated values can be supplied with the meteorological forcing data, either derived from knowledge of the study site, or obtained from other models, for example:

   • LUCY (Allen et al. 2011 [lucy], Lindberg et al. 2013 [lucy2]). A new version has been now included in UMEP. To distinguish it is referred to as LQF

   • GreaterQF (Iamarino et al. 2011 [I11]). A new version has been now included in UMEP. To distinguish it is referred to as GQF

Storage heat flux, ΔQ_S

1. Three sub-models are available to estimate the storage heat flux:

   • OHM (Objective Hysteresis Model, Grimmond et al. 1991 [G91OHM], Grimmond & Oke 1999a [GO99QS], 2002 [GO2002]). Storage heat heat flux is calculated using empirically-fitted relations with net all-wave radiation and the rate of change in net all-wave radiation.

   • AnOHM (Analytical Objective Hysteresis Model, Sun et al. 2017 [AnOHM17]). OHM approach using analytically-derived coefficients. Not recommended in this version.

   • ESTM (Element Surface Temperature Method, Offerle et al. 2005 [OGF2005]). Heat transfer through urban facets (roof, wall, road, interior) is calculated from surface temperature measurements and knowledge of material properties. Not recommended in this version.

2. Alternatively, ‘observed’ storage heat flux can be supplied with the meteorological forcing data.

Turbulent heat fluxes, Q_H and Q_E

1. LUMPS (Local-scale Urban Meteorological Parameterization Scheme, Grimmond & Oke 2002 [GO2002]) provides a simple means of estimating sensible and latent heat fluxes based on the proportion of vegetation in the study area.

2. SUEWS adopts a more biophysical approach to calculate the latent heat flux; the sensible heat flux is then calculated as the residual of the energy balance. The initial estimate of stability is based on the LUMPS calculations of sensible and latent heat flux. Future versions will have alternative sensible heat and storage heat flux options.

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

Water balance

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

• Precipitation is a required variable in the meteorological forcing file.

• Irrigation can be modelled [J11] or observed values can be provided if data are available.

• Drainage equations and coefficients to use must be specified in the input files.

• Soil moisture can be calculated by the model.

• Runoff is permitted:

  • between surface types within each model grid

  • between model grids (Not available in this version.)

  • to deep soil

  • to pipes.

Snowmelt

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

Convective boundary layer

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

Surface Diagnostics

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

• T2: air temperature at 2 m agl

• Q2: air specific humidity at 2 m agl

• U10: wind speed at 10 m agl

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

Wind, Temperature and Humidity Profiles in the Roughness Sublayer

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

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

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

Here nz = 30.

Note

All the diagnostic profiles (wind speed, temperature and humidity) are calculated from the forcing data down into the canopy. Therefore it is assumed that the forcing temperature and humidity are above the blending height.

Note

Please report issues with the manual on the GitHub page.

Preparing to run the model

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

Preparatory reading

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

• Järvi L, Grimmond CSB & Christen A (2011) The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver. J. Hydrol. 411, 219-237. doi:10.1016/j.jhydrol.2011.10.00

• Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H & Strachan IB (2014) Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities. Geosci. Model Dev. 7, 1691-1711. doi:10.5194/gmd-7-1691-2014

• Ward HC, Kotthaus S, Järvi L and Grimmond CSB (2016) Surface Urban Energy and Water Balance Scheme (SUEWS): development and evaluation at two UK sites. Urban Climate 18, 1-32. doi:10.1016/j.uclim.2016.05.001

See other publications with example applications

Decide what type of model run you are interested in

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

Download the program and example data files

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

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

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

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

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

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

Run the model for example data

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

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

Please see Troubleshooting if you have problems running the model.

Preparation of data

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

1. Continuous meteorological forcing data for the entire period to be modelled without gaps. If you need help preparing the data you can use some of the UMEP tools.

2. Knowledge of the surface and soil conditions immediately prior to the first model timestep. If these initial conditions are unknown, model spinup can help; i.e. run the model and use the output at the end of the run to infer the conditions at the start of the main run).

3. The location of the site (latitude, longitude, altitude).

4. Information about the characteristics of the surface, including land cover, heights of buildings and trees, radiative characteristics (e.g. albedo, emissivity), drainage characteristics, soil characteristics, snow characteristics, phenological characteristics (e.g. seasonal cycle of LAI). For guidance on how to derive parameters related to LAI, albedo, surface conductance and surface roughness, the reader is referred to this link.

5. Information about human behaviour, including energy use and water use (e.g. for irrigation or street cleaning) and snow clearing (if applicable). The anthropogenic energy use and water use may be provided as a time series in the meteorological forcing file if these data are available or modelled based on parameters provided to the model, including population density, hourly and weekly profiles of energy and water use, information about the proportion of properties using irrigation and the type of irrigation (automatic or manual).

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

• Fractions of different land cover types and (less so) heights of buildings [W16]

• Accurate meteorological forcing data, particularly precipitation and incoming shortwave radiation [Ko17]

• Initial soil moisture conditions [Best2014]

• Anthropogenic heat flux parameters, particularly if there are considerable energy emissions from transport, buildings, metabolism, etc [W16]

• External water use (if irrigation or street cleaning occurs)

• Snow clearing (if running the snow option)

• Surface conductance parameterisation [J11] [W16]

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

Preparation of site characteristics and model parameters

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

Land cover

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

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

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

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

Anthropogenic heat flux (Q_F)

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

• To model it population density is needed as an input for LUMPS and SUEWS to calculate Q_F.

• If you have no information about the population of the site we recommend that you use the LUCY model [lucy] [lucy2] to estimate the anthropogenic heat flux which can then be provided as input SUEWS along with the meteorological forcing data.

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

Other information

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

Data Entry

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

1. Data can be entered directly into the input text files. The example (.txt) files provide a template to create your own files which can be edited with A text editor directly.

2. Data can be entered into the spreadsheet SUEWS_SiteInfo.xlsm and the input text files generated by running the macro.

3. Use UMEP.

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

If there is a problem

• Make sure none of the text files to be generated are open.

• It is recommended to close the spreadsheet before running the actual model code.

Note that in all txt files:

• The first two rows are headers. The first row is the column number; the second row is the column name.

• The names and order of the columns should not be altered from the templates, as these are checked by the model and errors will be returned if particular columns cannot be found.

• Since v2017a it is no longer necessary for the meteorological forcing data to have two rows with -9 in column 1 as their last two rows.

• “!” indicates a comment, so any text following “!” on the same line will not be read by the model.

• If data are unavailable or not required, enter the value -999 in the correct place in the input file.

• Ensure the units are correct for all input information. See Input files for a description of parameters.

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

Preparation of the RunControl file

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

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

2. create the directories specified in the RunControl.nml file

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

FileOutputPath = “C:\FolderName\SUEWSOutput\”

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

C:\FolderName\SUEWSOutput\SSss_YYYY_TT.txt

Note

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

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

Preparation of the Meteorological forcing data

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

Preparation of the InitialConditions file

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

Run the model for your site

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

Please see Troubleshooting if you have problems running the model.

Analyse the output

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

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

Summary of files

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

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

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

Get in contact

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

1. Report issues on our GitHub page.

2. Ask for help by joining the Email-list for SUEWS.

Note

Please report issues with the manual on the GitHub page.

Input files

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

Note

Please report issues with the manual on the GitHub page.

RunControl.nml

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

A sample file of RunControl.nml looks like

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

Note

• In Linux and Mac, please add an empty line after the end slash.

• The file is not case-sensitive.

• The parameters and variables can appear in any order.

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

• Scheme options

  CBLuse SnowUse NetRadiationMethod BaseTMethod EmissionsMethod StorageHeatMethod

  OHMIncQF StabilityMethod RoughLenHeatMethod RoughLenMomMethod SMDMethod WaterUseMethod

• File related options

  FileCode FileInputPath FileOutputPath MultipleMetFiles MultipleInitFiles

  MultipleESTMFiles KeepTstepFilesIn KeepTstepFilesOut WriteOutOption SuppressWarnings

• Time related options

  Tstep ResolutionFilesIn

  ResolutionFilesInESTM ResolutionFilesOut

• Options related to disaggregation of input data

  DisaggMethod KdownZen RainDisaggMethod RainAmongN

  MultRainAmongN MultRainAmongNUpperI DisaggMethodESTM

Note

Please report issues with the manual on the GitHub page.

Scheme options

CBLuse

Warning

Not available in this version.

Requirement

Required

Description

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

Configuration

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

SnowUse

Requirement

Required

Description

Determines whether the snow part of the model runs.

Configuration

Value	Comments
0	Snow calculations are not performed.
1	Snow calculations are performed.

NetRadiationMethod

Requirement

Required

Description

Determines method for calculation of radiation fluxes.

Configuration

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

BaseTMethod

Requirement

Required

Description

Determines method for base temperature used in HDD/CDD calculations.

Configuration

Value	Comments
1	V-shape approach: a single BaseT_HC is used
2	U-shape approach: TCritic_Heating_WD (TCritic_Heating_WE) and TCritic_Cooling_WD (TCritic_Cooling_WE) are used for HDD and CDD calculations in weekdays (weekends), respectively.

EmissionsMethod

Requirement

Required

Description

Determines method for QF calculation.

Configuration

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

StorageHeatMethod

Requirement

Required

Description

Determines method for calculating storage heat flux ΔQS.

Configuration

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

OHMIncQF

Requirement

Required

Description

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

Configuration

Value	Comments
0	ΔQS modelled Q* only.
1	ΔQS modelled using Q*+QF.

StabilityMethod

Requirement

Required

Description

Defines which atmospheric stability functions are used.

Configuration

Value	Comments
0	Not used.
1	Not used.
2	Momentum: unstable: Dyer (1974) [D74] modified by Högstrom (1988) [H1988] stable: Van Ulden and Holtslag (1985) [VUH85] Heat: Dyer (1974) [D74] modified by Högstrom (1988) [H1988] Not recommended in this version.
3	Momentum: Campbell and Norman (Eq 7.27, Pg97) [CN1988] Heat unstable: Campbell and Norman [CN1988] stable: Campbell and Norman [CN1988] Recommended in this version.
4	Momentum: Businger et al. (1971) [B71] modified by Högstrom (1988) [H1988] Heat: Businger et al. (1971) [B71] modified by Högstrom (1988) [H1988] Not recommended in this version.

RoughLenHeatMethod

Requirement

Required

Description

Determines method for calculating roughness length for heat.

Configuration

Value	Comments
1	Uses value of 0.1*z0m.
2	Calculated according to Kawai et al. (2009) [Ka09].
3	Calculated according to Voogt and Grimmond (2000) [VG00].
4	Calculated according to Kanda et al. (2007) [Ka07].
5	Adaptively using z0m based on pervious coverage: if fully pervious, use method 1; otherwise, use method 2. Recommended in this version.

RoughLenMomMethod

Requirement

Required

Description

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

Configuration

Value	Comments
1	Values specified in SUEWS_SiteSelect.txt are used. Tip Note that UMEP provides tools to calculate these. See Kent et al. (2017a) [Kent2017a] for recommendations on methods. Kent et al. (2017b) [Kent2017b] have developed a method to include vegetation which is also avaialble within UMEP.
2	z0m and zd are calculated using ‘rule of thumb’ (Grimmond and Oke 1999 [GO99]) using mean building and tree height specified in SUEWS_SiteSelect.txt. z0m and zd are adjusted with time to account for seasonal variation in porosity of deciduous trees.
3	z0m and zd are calculated based on the MacDonald et al. (1998) [Mc98] method using mean building and tree heights, plan area fraction and frontal areal index specified in SUEWS_SiteSelect.txt. z0m and zd are adjusted with time to account for seasonal variation in porosity of deciduous trees.

SMDMethod

Requirement

Required

Description

Determines method for calculating soil moisture deficit (SMD).

Configuration

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

WaterUseMethod

Requirement

Required

Description

Defines how external water use is calculated.

Configuration

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

Note

Please report issues with the manual on the GitHub page.

Time related options

Tstep

Requirement

Required

Description

Specifies the model time step [s].

Configuration

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

Requirement

Required

Description

Specifies the resolution of the input files [s] which SUEWS will disaggregate to the model time step.

Configuration

1800 s for 30 min or 3600 s for 60 min are recommended.

Note

If ResolutionFilesIn is not provided, SUEWS assumes ResolutionFilesIn = Tstep.

ResolutionFilesInESTM

Requirement

Optional

Description

Specifies the resolution of the ESTM input files [s] which SUEWS will disaggregate to the model time step.

Configuration

The same as for ResolutionFilesIn.

ResolutionFilesOut

Requirement

Required

Description

Specifies the resolution of the output files [s].

Configuration

1800 s for 30 min or 3600 s for 60 min are recommended.

Note

Please report issues with the manual on the GitHub page.

File related options

FileCode

Requirement

Required

Description

Alphabetical site identification code (e.g. He, Sc, Kc).

Configuration

This must be consistent with names of meterological input file and initial condition files

FileInputPath

Requirement

Required

Description

Input directory.

Configuration

This can be set either as an absolute path or a relative path where the program is initiated.

FileOutputPath

Requirement

Required

Description

Output directory.

Configuration

This can be set either as an absolute path or a relative path where the program is initiated.

MultipleMetFiles

Requirement

Required

Description

Specifies whether one single meteorological forcing file is used for all grids or a separate met file is provided for each grid.

Configuration

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

Requirement

Required

Description

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.

Configuration

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

Requirement

Optional

Description

Specifies whether one single ESTM forcing file is used for all grids or a separate file is provided for each grid.

Configuration

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

Requirement

Optional

Description

Specifies whether input meteorological forcing files at the resolution of the model time step should be saved.

Configuration

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

Requirement

Optional

Description

Specifies whether output meteorological forcing files at the resolution of the model time step should be saved.

Configuration

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

Requirement

Optional

Description

Specifies which variables are written in the output files.

Configuration

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

Requirement

Optional

Description

Controls whether the warnings.txt file is written or not.

Configuration

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.

Note

Please report issues with the manual on the GitHub page.

Options related to disaggregation of input data

DisaggMethod

Requirement

Optional

Description

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.

Configuration

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

Requirement

Optional

Description

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.

Configuration

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

Requirement

Optional

Description

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.

Configuration

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

Requirement

Optional

Description

Specifies the number of subintervals (of length tt) over which to distribute rainfall in each interval (of length TT).

Configuration

Must be an integer value. Use with RainDisaggMethod = 101.

MultRainAmongN

Requirement

Optional

Description

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.

Configuration

Use with RainDisaggMethod = 102. e.g. MultRainAmongN(1) = 5, MultRainAmongN(2) = 8, MultRainAmongN(3) = 12

MultRainAmongNUpperI

Requirement

Optional

Description

Specifies upper limit for each intensity bin to apply MultRainAmongN.

Configuration

Any intensities above the highest specified intensity will use the last MultRainAmongN value and write a warning to Warning messages: warnings.txt. Use with RainDisaggMethod = 102. e.g. MultRainAmongNUpperI(1) = 0.5, MultRainAmongNUpperI(2) = 2.0, MultRainAmongNUpperI(3) = 50.0

DisaggMethodESTM

Requirement

Optional

Description

Specifies how ESTM-related temperatures in the input file are disaggregated to the model time step.

Configuration

Value	Comments
1	Linear downscaling of averages.
2	Linear downscaling of instantaneous values.

Note

Please report issues with the manual on the GitHub page.

SUEWS Site Information

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_AnthropogenicEmission.txt

Note

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

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

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

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

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

An example SUEWS_AnthropogenicEmission.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_BiogenCO2.txt

Caution

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

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

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

An example SUEWS_BiogenCO2.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Conductance.txt

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

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

An example SUEWS_Conductance.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Irrigation.txt

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

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

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

An example SUEWS_Irrigation.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_NonVeg.txt

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

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

An example SUEWS_NonVeg.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_OHMCoefficients.txt

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

• For each surface, OHM requires three model coefficients (a1, a2, a3). The three should be selected as a set.

• The SUEWS_OHMCoefficients.txt file provides these coefficients for each surface type.

• A variety of values has been derived for different materials and can be found in the literature (see: Typical Values).

• Coefficients can be changed depending on:

  1. surface wetness state (wet/dry) based on the calculated surface wetness state and soil moisture.

  2. season (summer/winter) based on a 5-day running mean air temperature.

• To use the same coefficients irrespective of wet/dry and summer/winter conditions, use the same code for all four OHM columns (OHMCode_SummerWet, OHMCode_SummerDry, OHMCode_WinterWet and OHMCode_WinterDry).

Note

1. AnOHM (set in RunControl.nml by StorageHeatMethod = 3) does not use the coefficients specified in SUEWS_OHMCoefficients.txt but instead requires three parameters to be specified for each surface type (including snow): heat capacity (AnOHM_Cp), thermal conductivity (AnOHM_Kk) and bulk transfer coefficient (AnOHM_Ch). These are specified in SUEWS_NonVeg.txt, SUEWS_Veg.txt, SUEWS_Water.txt and SUEWS_Snow.txt. No additional files are required for AnOHM.

2. AnOHM is under development in v2018b and should NOT be used!

No.	Column Name	Use	Description
1	Code	L	Code linking to a corresponding look-up table.
2	a1	MU	Coefficient for Q* term [-]
3	a2	MU	Coefficient for dQ*/dt term [h]
4	a3	MU	Constant term [W m-2]

An example SUEWS_OHMCoefficients.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Profiles.txt

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

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

Profiles are specified for the following

• Anthropogenic heat flux (weekday and weekend)

• Water use (weekday and weekend; manual and automatic irrigation)

• Snow removal (weekday and weekend)

• Human activity (weekday and weekend).

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

An example SUEWS_Profiles.txt can be found below:

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

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

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

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

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


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

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

-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_SiteSelect.txt

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

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

Attention

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

• In this file the column order is important.

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

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

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

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

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

Tip

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

Day Light Savings (DLS)

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

Tip

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

• For northern hemisphere, use: 180 181

• For southern hemisphere, use:  365 1

Example when running multiple years (in this case 2008 and 2009 in Canada):

Year	start of daylight savings	end of daylight savings
2008	170	240
2009	172	242

Grid Connections (water flow between grids)

Caution

• Not available in this version.

• columns between GridConnection1of8 and GridConnection8of8 in 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.

Note

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

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

An example SUEWS_SiteSelect.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Snow.txt

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

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

An example SUEWS_Snow.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Soil.txt

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

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

Caution

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

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

An example SUEWS_Soil.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Veg.txt

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

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

An example SUEWS_Veg.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Water.txt

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

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

An example SUEWS_Water.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_WithinGridWaterDist.txt

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

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

Note

• The sum of each row (excluding the Code) must equal 1.

• Water CANNOT flow from one surface to that same surface, so the diagonal elements should be zero.

• The row corresponding to the water surface should be zero, as there is currently no flow permitted from the water surface to other surfaces by the model.

• Currently water CANNOT go to both runoff and soil store (i.e. it must go to one or the other – runoff for impervious surfaces; soilstore for pervious surfaces).

In the table below, for example,

• All flow from paved surfaces goes to runoff;

• 90% of flow from buildings goes to runoff, with small amounts going to other surfaces (mostly paved surfaces as buildings are often surrounded by paved areas);

• All flow from vegetated and bare soil areas goes into the sub-surface soil store;

• The row corresponding to water contains zeros (as it is currently not used).

No.	Column Name	Use	Description
1	ToPaved	MU	Fraction of water going to Paved
2	ToBldgs	MU	Fraction of water going to Bldgs
3	ToEveTr	MU	Fraction of water going to EveTr
4	ToDecTr	MU	Fraction of water going to DecTr
5	ToGrass	MU	Fraction of water going to Grass
6	ToBSoil	MU	Fraction of water going to BSoil
7	ToWater	MU	Fraction of water going to Water
8	ToRunoff	MU	Fraction of water going to Runoff
9	ToSoilStore	MU	Fraction of water going to SoilStore

An example SUEWS_WithinGridWaterDist.txt can be found below:

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

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

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

Note

Please report issues with the manual on the GitHub page.

Input Options

a1

Description

Coefficient for Q* term [-]

Configuration

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

a2

Description

Coefficient for dQ*/dt term [h]

Configuration

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

a3

Description

Constant term [W m^-2]

Configuration

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

ActivityProfWD

Description

Code linking to ActivityProfWD in SUEWS_Profiles.txt.

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	L	Code for human activity profile (weekdays) Provides the link to column 1 of SUEWS_Profiles.txt. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt. Used for CO2 flux calculation. Not used in this version.

ActivityProfWE

Description

Code linking to ActivityProfWE in SUEWS_Profiles.txt.

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	L	Code for human activity profile (weekends) Provides the link to column 1 of SUEWS_Profiles.txt. Look the codes Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Profiles.txt. Used for CO2 flux calculation. Not used in this version.

AHMin_WD

Description

Minimum QF on weekdays [W m^-2]

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 1

AHMin_WE

Description

Minimum QF on weekends [W m^-2]

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 1

AHSlope_Heating_WD

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 1

AHSlope_Heating_WE

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 1

AHSlope_Cooling_WD

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 1

AHSlope_Cooling_WE

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 1

AlbedoMax

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_NonVeg.txt	MU	Effective surface albedo (middle of the day value) for summertime. View factors should be taken into account.
SUEWS_Veg.txt	MU	Example values [-] 0.1 EveTr Oke (1987) [Ok87] 0.18 DecTr Oke (1987) [Ok87] 0.21 Grass Oke (1987) [Ok87]
SUEWS_Water.txt	MU	Example values [-] 0.1 Water Oke (1987) [Ok87]
SUEWS_Snow.txt	MU	Example values [-] 0.85 Järvi et al. (2014) [Leena2014]

AlbedoMin

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_NonVeg.txt	MU	Not currently used for non-vegetated surfaces – set the same as AlbedoMax.
SUEWS_Veg.txt	MU	Example values [-] 0.1 EveTr Oke (1987) [Ok87] 0.18 DecTr Oke (1987) [Ok87] 0.21 Grass Oke (1987) [Ok87]
SUEWS_Water.txt	MU	Not currently used for water surface - set same as AlbedoMax.
SUEWS_Snow.txt	MU	Example values [-] 0.18 Järvi et al. (2014) [Leena2014]

alpha

Description

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

Configuration

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

Alt

Description

Altitude of grids [m].

Configuration

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

AnOHM_Ch

Description

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

Configuration

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

AnOHM_Cp

Description

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

Configuration

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

AnOHM_Kk

Description

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

Configuration

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

AnthropogenicCode

Description

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

Configuration

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

AreaWall

Description

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

Configuration

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

BaseT

Description

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

Configuration

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

BaseTe

Description

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

Configuration

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

BaseT_HC

Description

Base temperature for heating degree days [°C]

Configuration

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

beta

Description

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

Configuration

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

theta

Description

The convexity of the curve at light saturation.

Configuration

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

alpha_enh

Description

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

Configuration

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

beta_enh

Description

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

Configuration

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

resp_a

Description

Respiration coefficient a.

Configuration

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

resp_b

Description

Respiration coefficient b - related to air temperature dependency.

Configuration

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

min_respi

Description

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

Configuration

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

BiogenCO2Code

Description

Code linking to the Code column in SUEWS_BiogenCO2.txt.

Configuration

Referencing Table	Requirement	Comment
SUEWS_Veg.txt	L	Code linking to the Code column in SUEWS_BiogenCO2.txt.

QF0_BEU_WD

Description

Building energy use [W m^-2]

Configuration

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

QF0_BEU_WE

Description

Building energy use [W m^-2]

Configuration

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

CO2PointSource

Description

CO2 emission factor [kg km^-1]

Configuration

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

Code

Description

Code linking to a corresponding look-up table.

Configuration

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

Code_Bldgs

Description

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

Configuration

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

Code_BSoil

Description

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

Configuration

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

Code_DecTr

Description

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

Configuration

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

Code_ESTMClass_Bldgs1

Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	L	Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Bldgs2

Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	L	Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Bldgs3

Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	L	Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Bldgs4

Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	L	Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Bldgs5

Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	L	Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Paved1

Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	L	Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Paved2

Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	L	Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Paved3

Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	L	Code linking to SUEWS_ESTMCoefficients.txt

Code_EveTr

Description

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

Configuration

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

Code_Grass

Description

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

Configuration

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

Code_Paved

Description

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

Configuration

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

Code_Water

Description

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

Configuration

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

CondCode

Description

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

Configuration

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

CRWMax

Description

Maximum water holding capacity of snow [mm]

Configuration

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

CRWMin

Description

Minimum water holding capacity of snow [mm]

Configuration

Referencing Table	Requirement	Comment
SUEWS_Snow.txt	MD	Minimum water holding capacity of snow [mm]

DayWat(1)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Irrigation allowed on Sundays [1], if not [0]

DayWat(2)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Irrigation allowed on Mondays [1], if not [0]

DayWat(3)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Irrigation allowed on Tuesdays [1], if not [0]

DayWat(4)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Irrigation allowed on Wednesdays [1], if not [0]

DayWat(5)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Irrigation allowed on Thursdays [1], if not [0]

DayWat(6)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Irrigation allowed on Fridays [1], if not [0]

DayWat(7)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Irrigation allowed on Saturdays [1], if not [0]

DayWatPer(1)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Fraction of properties using irrigation on Sundays [0-1]

DayWatPer(2)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Fraction of properties using irrigation on Mondays [0-1]

DayWatPer(3)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Fraction of properties using irrigation on Tuesdays [0-1]

DayWatPer(4)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Fraction of properties using irrigation on Wednesdays [0-1]

DayWatPer(5)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Fraction of properties using irrigation on Thursdays [0-1]

DayWatPer(6)

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Fraction of properties using irrigation on Fridays [0-1]

DayWatPer(7)

Description

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

Configuration

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

DrainageCoef1

Description

Coefficient D0 [mm h^-1] used in DrainageEq

Configuration

Referencing Table	Requirement	Comment
SUEWS_NonVeg.txt	MD	Example values: DrainageEq = 3, 10 for Paved and Bldgs; DrainageEq = 2, 0.013 for BSoil
SUEWS_Veg.txt	MD	Example values: DrainageEq = 3, 10 for Grass (irrigated); DrainageEq = 2, 0.013 for EveTr, DecTr, Grass (unirrigated)
SUEWS_Water.txt	MD	Not currently used for water surface

DrainageCoef2

Description

Coefficient b [-] used in DrainageEq

Configuration

Referencing Table	Requirement	Comment
SUEWS_NonVeg.txt	MD	Example values: DrainageEq = 3, 3 for Paved and Bldgs DrainageEq = 2, 1.71 for BSoil
SUEWS_Veg.txt	MD	Example values: DrainageEq = 3, 3 for Grass (irrigated) DrainageEq = 2, 1.71 for EveTr, DecTr, Grass (unirrigated)
SUEWS_Water.txt	MD	Not currently used for water surface

DrainageEq

Description

Calculation choice for Drainage equation

Configuration

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

EF_umolCO2perJ

Description

Emission factor for fuels used for building heating.

Configuration

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

Emissivity

Description

Effective surface emissivity.

Configuration

Referencing Table	Requirement	Comment
SUEWS_NonVeg.txt	MU	Effective surface emissivity. View factors should be taken into account.
SUEWS_Veg.txt	MU	Example values [-] 0.98 EveTr Oke (1987) [Ok87] 0.98 DecTr Oke (1987) [Ok87] 0.93 Grass Oke (1987) [Ok87]
SUEWS_Water.txt	MU	Example values [-] 0.95 Water Oke (1987) [Ok87]
SUEWS_Snow.txt	MU	Example values [-] 0.99 Järvi et al. (2014) [Leena2014]

EndDLS

Description

End of the day light savings [DOY]

Configuration

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

EnEF_v_Jkm

Description

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

Configuration

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

EnergyUseProfWD

Description

Code linking to EnergyUseProfWD in SUEWS_Profiles.txt.

Configuration

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

EnergyUseProfWE

Description

Code linking to EnergyUseProfWE in SUEWS_Profiles.txt.

Configuration

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

ESTMCode

Description

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

Configuration

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

FAI_Bldgs

Description

Frontal area index for buildings [-]

Configuration

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

FAI_DecTr

Description

Frontal area index for deciduous trees [-]

Configuration

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

FAI_EveTr

Description

Frontal area index for evergreen trees [-]

Configuration

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

Faut

Description

Fraction of irrigated area that is irrigated using automated systems

Configuration

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

FcEF_v_kgkmWD

Description

CO2 emission factor for weekdays [kg km^-1]

Configuration

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

FcEF_v_kgkmWE

Description

CO2 emission factor for weekends [kg km^-1]

Configuration

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

FcEF_v_Jkm

Description

Traffic emission factor for CO2.

Configuration

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

fcld

Description

Cloud fraction [tenths]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	O	Cloud fraction [tenths]

FlowChange

Description

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

Configuration

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

Fraction1of8

Description

Fraction of water that can flow to GridConnection1of8 [-]

Configuration

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

Fraction2of8

Description

Fraction of water that can flow to GridConnection2of8 [-]

Configuration

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

Fraction3of8

Description

Fraction of water that can flow to GridConnection3of8 [-]

Configuration

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

Fraction4of8

Description

Fraction of water that can flow to GridConnection4of8 [-]

Configuration

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

Fraction5of8

Description

Fraction of water that can flow to GridConnection5of8 [-]

Configuration

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

Fraction6of8

Description

Fraction of water that can flow to GridConnection6of8 [-]

Configuration

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

Fraction7of8

Description

Fraction of water that can flow to GridConnection7of8 [-]

Configuration

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

Fraction8of8

Description

Fraction of water that can flow to GridConnection8of8 [-]

Configuration

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

Fr_Bldgs

Description

Surface cover fraction of buildings [-]

Configuration

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

Fr_Bsoil

Description

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

Configuration

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

Fr_DecTr

Description

Surface cover fraction of deciduous trees and shrubs [-]

Configuration

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

Fr_ESTMClass_Bldgs1

Description

Surface cover fraction of building class 1 used in ESTM calculations

Configuration

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

Fr_ESTMClass_Bldgs2

Description

Surface cover fraction of building class 2 used in ESTM calculations

Configuration

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

Fr_ESTMClass_Bldgs3

Description

Surface cover fraction of building class 3 used in ESTM calculations

Configuration

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

Fr_ESTMClass_Bldgs4

Description

Surface cover fraction of building class 4 used in ESTM calculations

Configuration

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

Fr_ESTMClass_Bldgs5

Description

Surface cover fraction of building class 5 used in ESTM calculations

Configuration

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

Fr_ESTMClass_Paved1

Description

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

Configuration

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

Fr_ESTMClass_Paved2

Description

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

Configuration

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

Fr_ESTMClass_Paved3

Description

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

Configuration

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

Fr_EveTr

Description

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

Configuration

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

Fr_Grass

Description

Surface cover fraction of Grass [-]

Configuration

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

Fr_Paved

Description

Surface cover fraction of Paved surfaces [-]

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	MU	Columns 14 to 20 must sum to 1 .

Fr_Water

Description

Surface cover fraction of open water [-]

Configuration

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

FrFossilFuel_Heat

Description

Fraction of fossil fuels used for building heating [-]

Configuration

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

FrFossilFuel_NonHeat

Description

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

Configuration

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

FrPDDwe

Description

Fraction of weekend population to weekday population. [-]

Configuration

G1

Description

Related to maximum surface conductance [mm s^-1]

Configuration

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

G2

Description

Related to Kdown dependence [W m^-2]

Configuration

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

G3

Description

Related to VPD dependence [units depend on gsModel]

Configuration

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

G4

Description

Related to VPD dependence [units depend on gsModel]

Configuration

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

G5

Description

Related to temperature dependence [°C]

Configuration

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

G6

Description

Related to soil moisture dependence [mm^-1]

Configuration

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

gamq_gkgm

Description

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

Configuration

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

gamt_Km

Description

vertical gradient of potential temperature [K m^-1]

Configuration

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

GDDFull

Description

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

Configuration

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

Grid

Description

a unique number to represent grid

Configuration

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

GridConnection1of8

Description

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

Configuration

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

GridConnection2of8

Description

Number of the 2nd grid where water can flow to

Configuration

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

GridConnection3of8

Description

Number of the 3rd grid where water can flow to

Configuration

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

GridConnection4of8

Description

Number of the 4th grid where water can flow to

Configuration

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

GridConnection5of8

Description

Number of the 5th grid where water can flow to

Configuration

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

GridConnection6of8

Description

Number of the 6th grid where water can flow to

Configuration

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

GridConnection7of8

Description

Number of the 7th grid where water can flow to

Configuration

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

GridConnection8of8

Description

Number of the 8th grid where water can flow to

Configuration

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

gsModel

Description

Formulation choice for conductance calculation.

Configuration

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

H_Bldgs

Description

Mean building height [m]

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	MU	Mean building height [m]

H_DecTr

Description

Mean height of deciduous trees [m]

Configuration

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

H_EveTr

Description

Mean height of evergreen trees [m]

Configuration

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

H_maintain

Description

water depth to maintain used in automatic irrigation (e.g., ponding water due to flooding irrigation in rice crop-field) [mm].

Note

1. H_maintain can be positive (e.g., ponding water due to flooding irrigation in rice crop-field) or negative (e.g., soil water store level to maintain: SoilStoreCap + H_maintain ) or zero (e.g., to maintain a maximum soil store level, i.e., SoilStoreCap).

2. Disable this feature by setting this parameter to -999: then no restrictions will be applied to maintain available water level.

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	water depth to maintain used in automatic irrigation.

id

Description

Day of year [DOY]

Configuration

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

Ie_a1

Description

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

Configuration

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

Ie_a2

Description

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

Configuration

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

Ie_a3

Description

Coefficient for automatic irrigation model [mm d^-2 ]

Configuration

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

Ie_end

Description

Day when irrigation ends [DOY]

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Day when irrigation ends [DOY]

Ie_m1

Description

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

Configuration

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

Ie_m2

Description

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

Configuration

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

Ie_m3

Description

Coefficient for manual irrigation model [mm d^-2 ]

Configuration

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

Ie_start

Description

Day when irrigation starts [DOY]

Configuration

Referencing Table	Requirement	Comment
SUEWS_Irrigation.txt	MU	Day when irrigation starts [DOY]

ih

Description

Hour [H]

Configuration

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

imin

Description

Minute [M]

Configuration

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

InfiltrationRate

Description

Infiltration rate.

Configuration

Referencing Table	Requirement	Comment
SUEWS_Soil.txt	O	Not currently used

Internal_albedo

Description

Albedo of all internal elements for building surfaces only

Configuration

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

Internal_CHbld

Description

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

Configuration

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

Internal_CHroof

Description

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

Configuration

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

Internal_CHwall

Description

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

Configuration

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

Internal_emissivity

Description

Emissivity of all internal elements for building surfaces only

Configuration

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

Internal_k1

Description

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

Configuration

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

Internal_k2

Description

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

Configuration

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

Internal_k3

Description

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

Configuration

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

Internal_k4

Description

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

Configuration

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

Internal_k5

Description

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

Configuration

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

Internal_rhoCp1

Description

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

Configuration

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

Internal_rhoCp2

Description

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

Configuration

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

Internal_rhoCp3

Description

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

Configuration

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

Internal_rhoCp4

Description

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

Configuration

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

Internal_rhoCp5

Description

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

Configuration

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

Internal_thick1

Description

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

Configuration

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

Internal_thick2

Description

Thickness of the second layer [m]

Configuration

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

Internal_thick3

Description

Thickness of the third layer [m]

Configuration

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

Internal_thick4

Description

Thickness of the fourth layer [m]

Configuration

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

Internal_thick5

Description

Thickness of the fifth layer [m]

Configuration

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

InternalWaterUse

Description

Internal water use [mm h^-1]

Configuration

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

IrrFr_Paved

Description

Fraction of Paved that is irrigated [-]

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	MU	Fraction of paved surfaces that are irrigated [-]

IrrFr_Bldgs

Description

Fraction of Bldgs that is irrigated [-]

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	MU	Fraction of rooftop of buildings (e.g., green roofs) that are irrigated [-]

IrrFr_DecTr

Description

Fraction of DecTr that is irrigated [-]

Configuration

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

IrrFr_EveTr

Description

Fraction of EveTr that is irrigated [-]

Configuration

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

IrrFr_Grass

Description

Fraction of Grass that is irrigated [-]

Configuration

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

IrrFr_BSoil

Description

Fraction of BSoil that is irrigated [-]

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	MU	Fraction of bare soil that are irrigated [-]

IrrFr_Water

Description

Fraction of Water that is irrigated [-]

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	MU	Fraction of water that are irrigated [-]

IrrigationCode

Description

Code for modelling irrigation linking to Code of SUEWS_Irrigation.txt

Configuration

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

it

Description

Hour [H]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_ESTM_Ts_data_tt.txt	MU	Hour [H]
SSss_YYYY_data_tt.txt	MU	Hour [H]

iy

Description

Year [YYYY]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_ESTM_Ts_data_tt.txt	MU	Year [YYYY]
SSss_YYYY_data_tt.txt	MU	Year [YYYY]

kdiff

Description

Diffuse radiation [W m^-2].

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	O	Recommended if SOLWEIGUse = 1

kdir

Description

Direct radiation [W m^-2].

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	O	Recommended if SOLWEIGUse = 1

kdown

Description

Incoming shortwave radiation [W m^-2].

Configuration

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

Kmax

Description

Maximum incoming shortwave radiation [W m^-2]

Configuration

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

lai

Description

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

Configuration

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

LAIEq

Description

LAI calculation choice.

Note

North and South hemispheres are treated slightly differently.

Configuration

Referencing Table	Requirement	Comment
SUEWS_Veg.txt	MD	Coefficients are specified in the following parameters: LeafGrowthPower1, LeafGrowthPower2, LeafOffPower1 and LeafOffPower2. Options 0 Järvi et al. (2011) [J11] 1 Järvi et al. (2014) [Leena2014]

LAIMax

Description

full leaf-on summertime value

Configuration

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

LAIMin

Description

leaf-off wintertime value

Configuration

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

lat

Description

Latitude [deg].

Configuration

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

ldown

Description

Incoming longwave radiation [W m^-2]

Configuration

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

LeafGrowthPower1

Description

a parameter required by LAI calculation in LAIEq

Configuration

Referencing Table	Requirement	Comment
SUEWS_Veg.txt	MD	Example values LAIEq = 0: 0.03 Järvi et al. (2011) [J11] LAIEq = 1: 0.04 Järvi et al. (2014) [Leena2014]

LeafGrowthPower2

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Veg.txt	MD	Example values LAIEq = 0: 0.0005 Järvi et al. (2011) [J11] LAIEq = 1: 0.001 Järvi et al. (2014) [Leena2014]

LeafOffPower1

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Veg.txt	MD	Example values LAIEq = 0: 0.03 Järvi et al. (2011) [J11] LAIEq = 1: -1.5 Järvi et al. (2014) [Leena2014]

LeafOffPower2

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Veg.txt	MD	Example values LAIEq = 0: 0.0005 Järvi et al. (2011) [J11] LAIEq = 1: 0.0015 Järvi et al. (2014) [Leena2014]

lng

Description

longitude [deg]

Configuration

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

LUMPS_Cover

Description

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

Configuration

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

LUMPS_DrRate

Description

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

Configuration

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

LUMPS_MaxRes

Description

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

Configuration

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

MaxQFMetab

Description

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

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

Configuration

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

MaxFCMetab

Description

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

Configuration

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

MaxConductance

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_Veg.txt	MD	Example values [mm s-1] 7.4: EveTr Järvi et al. (2011) [J11] 11.7: DecTr Järvi et al. (2011) [J11] 33.1: Grass (unirrigated) Järvi et al. (2011) [J11] 40.: Grass (irrigated) Järvi et al. (2011) [J11]

MinQFMetab

Description

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

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

Configuration

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

MinFCMetab

Description

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

Configuration

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

NARP_Trans

Description

Atmospheric transmissivity for NARP [-]

Configuration

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

nroom

Description

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

Configuration

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

OBS_SMCap

Description

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

Configuration

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

OBS_SMDepth

Description

The depth of soil moisture measurements. [mm]

Configuration

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

OBS_SoilNotRocks

Description

Fraction of soil without rocks. [-]

Configuration

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

OHMCode_SummerDry

Description

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

Configuration

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

OHMCode_SummerWet

Description

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

Configuration

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

OHMCode_WinterDry

Description

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

Configuration

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

OHMCode_WinterWet

Description

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

Configuration

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

OHMThresh_SW

Description

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

Configuration

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

OHMThresh_WD

Description

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

Configuration

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

PipeCapacity

Description

Storage capacity of pipes [mm]

Configuration

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

PopDensDay

Description

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

Configuration

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

PopDensNight

Description

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

Configuration

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

PopProfWD

Description

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

Configuration

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

PopProfWE

Description

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

Configuration

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

PorosityMax

Description

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

Configuration

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

PorosityMin

Description

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

Configuration

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

PrecipLimAlb

Description

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

Configuration

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

PrecipLimSnow

Description

Temperature limit when precipitation falls as snow [°C]

Configuration

Referencing Table	Requirement	Comment
SUEWS_Snow.txt	MD	Auer (1974) [Au74]

pres

Description

Barometric pressure [kPa]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	MU	Barometric pressure [kPa]

qe

Description

Latent heat flux [W m^-2]

Configuration

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

qf

Description

Anthropogenic heat flux [W m^-2]

Configuration

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

QF_A_WD

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 2 Example values: 0.3081 Järvi et al. (2011) [J11] 0.1 Järvi et al. (2014) [Leena2014]

QF_A_WE

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 2 Example values: 0.3081 Järvi et al. (2011) [J11] 0.1 Järvi et al. (2014) [Leena2014]

QF_B_WD

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 2 Example values: 0.0099 Järvi et al. (2011) [J11] 0.0099 Järvi et al. (2014) [Leena2014]

QF_B_WE

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 2 Example values: 0.0099 Järvi et al. (2011) [J11] 0.0099 Järvi et al. (2014) [Leena2014]

QF_C_WD

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 2 Example values: 0.0102 Järvi et al. (2011) [J11] 0.0102 Järvi et al. (2014) [Leena2014]

QF_C_WE

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Example values: 0.0102 Järvi et al. (2011) [J11] 0.0102 Järvi et al. (2014) [Leena2014]

q+_gkg

Description

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

Configuration

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

q_gkg

Description

specific humidiy in CBL [g kg^-1]

Configuration

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

qh

Description

Sensible heat flux [W m^-2]

Configuration

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

qn

Description

Net all-wave radiation [W m^-2]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	O	Required if NetRadiationMethod = 1.

qs

Description

Storage heat flux [W m^-2]

Configuration

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

RadMeltFactor

Description

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

Configuration

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

rain

Description

Rainfall [mm]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	MU	Rainfall [mm]

RH

Description

Relative Humidity [%]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	MU	Relative Humidity [%]

RunoffToWater

Description

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

Configuration

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

S1

Description

A parameter related to soil moisture dependence [-]

Configuration

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

S2

Description

A parameter related to soil moisture dependence [mm]

Configuration

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

SatHydraulicCond

Description

Hydraulic conductivity for saturated soil [mm s^-1]

Configuration

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

SDDFull

Description

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

Configuration

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

snow

Description

Snowfall [mm]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	O	Required if SnowUse = 1

SnowClearingProfWD

Description

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

Configuration

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

SnowClearingProfWE

Description

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

Configuration

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

SnowCode

Description

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

Configuration

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

SnowDensMax

Description

Maximum snow density [kg m^-3]

Configuration

SnowDensMin

Description

Fresh snow density [kg m^-3]

Configuration

SnowLimPatch

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_NonVeg.txt	O	Limit of snow water equivalent when the surface is fully covered with snow. Not needed if SnowUse = 0 in RunControl.nml . Example values: 190: Paved Järvi et al. (2014) [Leena2014] 190: Bldgs Järvi et al. (2014) [Leena2014] 190: BSoil Järvi et al. (2014) [Leena2014]
SUEWS_Veg.txt	O	Limit of snow water equivalent when the surface is fully covered with snow. Not needed if SnowUse = 0 in RunControl.nml . Example values: 190: EveTr Järvi et al. (2014) [Leena2014] 190: DecTr Järvi et al. (2014) [Leena2014] 190: Grass Järvi et al. (2014) [Leena2014]

SnowLimRemove

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_NonVeg.txt	O	Not needed if SnowUse = 0 in RunControl.nml . Not available in this version. Example values [mm] 40: Paved Järvi et al. (2014) [Leena2014] 100: Bldgs Järvi et al. (2014) [Leena2014]

SoilDensity

Description

Soil density [kg m^-3]

Configuration

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

SoilDepth

Description

Depth of soil beneath the surface [mm]

Configuration

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

SoilStoreCap

Description

Limit value for SoilDepth [mm]

Configuration

Referencing Table	Requirement	Comment
SUEWS_Soil.txt	MD	SoilStoreCap must not be greater than SoilDepth.

SoilTypeCode

Description

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

Configuration

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

StartDLS

Description

Start of the day light savings [DOY]

Configuration

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

StateLimit

Description

Upper limit to the surface state. [mm]

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

Configuration

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

StorageMax

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_NonVeg.txt	MD	Maximum water storage capacity for upper surfaces (i.e. canopy) Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces). Not currently used for non-vegetated surfaces - set the same as StorageMin. Example values: 0.48 Paved 0.25 Bldgs 0.8 BSoil
SUEWS_Veg.txt	MD	Maximum water storage capacity for upper surfaces (i.e. canopy) Min/max values are to account for seasonal variation (e.g. leaf-off/leaf-on differences for vegetated surfaces) Only used for DecTr surfaces - set EveTr and Grass values the same as StorageMin. Example values: 1.3: EveTr Breuer et al. (2003) [Br03] 0.8: DecTr Breuer et al. (2003) [Br03] 1.9: Grass Breuer et al. (2003) [Br03]
SUEWS_Water.txt	MD	Maximum water storage capacity for upper surfaces (i.e. canopy) Min and max values are to account for seasonal variation - not used for water surfaces so set same as StorageMin.

StorageMin

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_NonVeg.txt	MD	Minimum water storage capacity for upper surfaces (i.e. canopy). Min/max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces). Not currently used for non-vegetated surfaces - set the same as StorageMax. Example values: 0.48 Paved 0.25 Bldgs 0.8 BSoil
SUEWS_Veg.txt	MD	Minimum water storage capacity for upper surfaces (i.e. canopy). Min/max values are to account for seasonal variation (e.g. leaf-off/leaf-on differences for vegetated surfaces). Example values: 1.3 EveTr Breuer et al. (2003) [Br03] 0.3 DecTr Breuer et al. (2003) [Br03] 1.9 Grass Breuer et al. (2003) [Br03]
SUEWS_Water.txt	MD	Minimum water storage capacity for upper surfaces (i.e. canopy). Min/max values are to account for seasonal variation - not used for water surfaces. Example values: -0.5 Water

SurfaceArea

Description

Area of the grid [ha].

Configuration

Referencing Table	Requirement	Comment
SUEWS_SiteSelect.txt	MU	Area of the grid [ha].

Surf_k1

Description

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

Configuration

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

Surf_k2

Description

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

Configuration

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

Surf_k3

Description

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

Configuration

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

Surf_k4

Description

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

Configuration

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

Surf_k5

Description

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

Configuration

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

Surf_rhoCp1

Description

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

Configuration

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

Surf_rhoCp2

Description

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

Configuration

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

Surf_rhoCp3

Description

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

Configuration

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

Surf_rhoCp4

Description

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

Configuration

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

Surf_rhoCp5

Description

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

Configuration

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

Surf_thick1

Description

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

Configuration

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

Surf_thick2

Description

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

Configuration

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

Surf_thick3

Description

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

Configuration

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

Surf_thick4

Description

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

Configuration

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

Surf_thick5

Description

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

Configuration

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

Tair

Description

Air temperature [°C]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	MU	Air temperature [°C]

tau_a

Description

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

Configuration

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

tau_f

Description

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

Configuration

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

tau_r

Description

Time constant for snow density ageing [-]

Configuration

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

TCritic_Heating_WD

Description

Critical heating temperature on weekdays [°C]

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 1

TCritic_Heating_WE

Description

Critical heating temperature on weekends [°C]

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 1

TCritic_Cooling_WD

Description

Critical cooling temperature on weekdays [°C]

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 1

TCritic_Cooling_WE

Description

Critical cooling temperature on weekends [°C]

Configuration

Referencing Table	Requirement	Comment
SUEWS_AnthropogenicEmission.txt	MU O	Use with EmissionsMethod = 1

TempMeltFactor

Description

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

Configuration

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

TH

Description

Upper air temperature limit [°C]

Configuration

Referencing Table	Requirement	Comment
SUEWS_Conductance.txt	MD	Upper air temperature limit [°C]

Theta+_K

Description

potential temperature at the top of CBL [K]

Configuration

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

Theta_K

Description

potential temperature in CBL [K]

Configuration

Referencing Table	Requirement	Comment
CBL_initial_data.txt	MU	potential temperature in CBL (K)

Tiair

Description

Indoor air temperature [˚C]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_ESTM_Ts_data_tt.txt	MU	Indoor air temperature [˚C]

Timezone

Description

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

Configuration

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

TL

Description

Lower air temperature limit [°C]

Configuration

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

ToBldgs

Description

Fraction of water going to Bldgs

Configuration

Referencing Table	Requirement	Comment
SUEWS_WithinGridWaterDist.txt	MU	Fraction of water going to Bldgs

ToBSoil

Description

Fraction of water going to BSoil

Configuration

Referencing Table	Requirement	Comment
SUEWS_WithinGridWaterDist.txt	MU	Fraction of water going to BSoil

ToDecTr

Description

Fraction of water going to DecTr

Configuration

Referencing Table	Requirement	Comment
SUEWS_WithinGridWaterDist.txt	MU	Fraction of water going to DecTr

ToEveTr

Description

Fraction of water going to EveTr

Configuration

Referencing Table	Requirement	Comment
SUEWS_WithinGridWaterDist.txt	MU	Fraction of water going to EveTr

ToGrass

Description

Fraction of water going to Grass

Configuration

Referencing Table	Requirement	Comment
SUEWS_WithinGridWaterDist.txt	MU	Fraction of water going to Grass

ToPaved

Description

Fraction of water going to Paved

Configuration

Referencing Table	Requirement	Comment
SUEWS_WithinGridWaterDist.txt	MU	Fraction of water going to Paved

ToRunoff

Description

Fraction of water going to Runoff

Configuration

Referencing Table	Requirement	Comment
SUEWS_WithinGridWaterDist.txt	MU	Fraction of water going to Runoff

ToSoilStore

Description

Fraction of water going to SoilStore

Configuration

Referencing Table	Requirement	Comment
SUEWS_WithinGridWaterDist.txt	MU	Fraction of water going to SoilStore

ToWater

Description

Fraction of water going to Water

Configuration

Referencing Table	Requirement	Comment
SUEWS_WithinGridWaterDist.txt	MU	Fraction of water going to Water

TraffProfWD

Description

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

Configuration

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

TraffProfWE

Description

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

Configuration

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

TrafficUnits

Description

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

Configuration

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

TrafficRate_WD

Description

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

Configuration

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

TrafficRate_WE

Description

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

Configuration

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

Troad

Description

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

Configuration

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

Troof

Description

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

Configuration

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

Tsurf

Description

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

Configuration

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

Twall

Description

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

Configuration

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

Twall_e

Description

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

Configuration

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

Twall_n

Description

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

Configuration

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

Twall_s

Description

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

Configuration

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

Twall_w

Description

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

Configuration

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

U

Description

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

Configuration

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

Wall_k1

Description

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

Configuration

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

Wall_k2

Description

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

Configuration

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

Wall_k3

Description

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

Configuration

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

Wall_k4

Description

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

Configuration

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

Wall_k5

Description

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

Configuration

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

Wall_rhoCp1

Description

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

Configuration

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

Wall_rhoCp2

Description

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

Configuration

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

Wall_rhoCp3

Description

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

Configuration

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

Wall_rhoCp4

Description

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

Configuration

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

Wall_rhoCp5

Description

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

Configuration

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

Wall_thick1

Description

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

Configuration

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

Wall_thick2

Description

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

Configuration

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

Wall_thick3

Description

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

Configuration

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

Wall_thick4

Description

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

Configuration

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

Wall_thick5

Description

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

Configuration

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

WaterDepth

Description

Water depth [mm].

Configuration

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

WaterUseProfAutoWD

Description

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

Configuration

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

WaterUseProfAutoWE

Description

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

Configuration

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

WaterUseProfManuWD

Description

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

Configuration

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

WaterUseProfManuWE

Description

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

Configuration

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

wdir

Description

Wind direction [deg].

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	O	Not available in this version.

WetThreshold

Description

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

Configuration

Referencing Table	Requirement	Comment
SUEWS_NonVeg.txt	MD	Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface. Example values: 0.6 Paved 0.6 Bldgs BSoil
SUEWS_Veg.txt	MD	Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface. Example values: 1.8 EveTr DecTr Grass
SUEWS_Water.txt	MD	Depth of water which determines whether evaporation occurs from a partially wet or completely wet surface. Example values: 0.5 Water

WithinGridBldgsCode

Description

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

Configuration

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

WithinGridBSoilCode

Description

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

Configuration

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

WithinGridDecTrCode

Description

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

Configuration

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

WithinGridEveTrCode

Description

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

Configuration

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

WithinGridGrassCode

Description

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

Configuration

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

WithinGridPavedCode

Description

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

Configuration

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

WithinGridWaterCode

Description

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

Configuration

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

Wuh

Description

External water use [m³]

Configuration

Referencing Table	Requirement	Comment
SSss_YYYY_data_tt.txt	O	External water use [ m3]

xsmd

Description

Observed soil moisture [m³ m^-3 or kg kg^-1]

Configuration

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

Year

Description

Year [YYYY]

Configuration

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

z

Description

Measurement height [m].

Configuration

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

z0

Description

Roughness length for momentum [m]

Configuration

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

zd

Description

Zero-plane displacement [m]

Configuration

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

zi0

Description

initial convective boundary layer height (m)

Configuration

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

Note

Please report issues with the manual on the GitHub page.

Typical Values

Other values to add - please let us know

Generic Properties

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

Storage Heat Flux Related

OHM Coefficients

• Values determined from the literature

• If you have recommendations for others to be included please let us know.

• In the model run, canyons are excluded

Surface type	Description	Author (data source)	a1	a2	a3
Canyon	E-W canyon	Yoshida et al. (1990, 1991)	0.71	0.04	-39.7
	N-S canyon	Nunez (1974)	0.32	0.01	-27.7
Vegetation	Mixed forest	McCaughey (1985)	0.11	0.11	-12.3
	Short grass	Doll et al. (1985)	0.32	0.54	-27.4
	Bare soil	Novak (1982)	0.38	0.56	-27.3
	Bare soil (wet)	Fuchs & Hadas (1972)	0.33	0.07	-34.9
	Bare soil (dry)	Fuchs & Hadas (1972)	0.65	0.43	-36.5
	Bare soil	Asaeda & Ca (1993)	0.36	0.27	-42.4
	Water Shallow – Turbid	Souch et al. (1998)	0.50	0.21	-39.1
	Unirrigated grass (Crops)	Grimmond et al. (1993)	0.21	0.11	-16.1
	Short irrigated grass	Grimmond et al. (1993)	0.35	-0.01	-26.3
Roof	Tar and gravel, Vancouver	Yap (1973)	0.17	0.10	-17.0
	Uppsala	Taesler (1980)	0.44	0.57	-28.9
	Membrane and concrete, Kyoto	Yoshida et al. (1990,1991)	0.82	0.34	-55.7
	Average gravel/tar/conc. flat industrial, Vancouver	Meyn (2000)	0.25	0.92	-22.0
	Dry –gravel/tar/conc. flat industrial, Vancouver	Meyn (2000)	0.25	0.70	-22.0
	Wet – gravel/tar/conc. flat industrial, Vancouver	Meyn (2000)	0.25	0.70	-22.0
	Bitumen spread over flat industrial membrane, Vancouver	Meyn (2000)	0.06	0.28	-3.0
	Asphalt shingle on plywood residential roof , Vancouver	Meyn (2000)	0.14	0.33	-6.0
	Star – high albedo asphalt shingle residential roof	Meyn (2000)	0.09	0.18	-1.0
	Star - Ceramic Tile	Meyn (2000)	0.07	0.26	-6.0
	Star - Slate Tile	Meyn (2000)	0.08	0.32	0.0
	Helsinki – Suburban	Järvi et al. (2014)	0.19	0.54	-15.1
	Montreal – Suburban	Järvi et al. (2014)	0.12	0.24	-4.5
	Montreal – Urban	Järvi et al. (2014)	0.26	0.85	-21.4
Impervious	Concrete	Doll et al. (1985)	0.81	0.10	-79.9
	Concrete	Asaeda & Ca (1993)	0.85	0.32	-28.5
	Asphalt	Narita et al. (1984)	0.36	0.23	-19.3
	Asphalt	Asaeda & Ca (1993)	0.64	0.32	-43.6
	Asphalt	Anandakumar (1999)	0.82	0.68	-20.1
	Asphalt (winter)	Anandakumar (1999)	0.72	0.54	-40.2
	Asphalt (summer)	Anandakumar (1999)	0.83	-0.83	-24.6

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

Tip

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

Note

Please report issues with the manual on the GitHub page.

Initial Conditions file

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

A sample file of InitialConditionsSSss_YYYY.nml looks like

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

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

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

Note

Variables can be in any order

• Soil moisture states

  SoilstorePavedState SoilstoreBldgsState SoilstoreEveTrState

  SoilstoreDecTrState SoilstoreGrassState SoilstoreBSoilState

• Vegetation parameters

  LeavesOutInitially GDD_1_0 GDD_2_0 LAIinitialEveTr LAIinitialDecTr LAIinitialGrass

  albEveTr0 albDecTr0 albGrass0 decidCap0 porosity0

• Recent meteorology

  DaysSinceRain

  Temp_C0

• Above ground state

  PavedState BldgsState EveTrState DecTrState

  GrassState BSoilState WaterState

• Snow related parameters

  SnowInitially SnowWaterPavedState SnowWaterBldgsState SnowWaterEveTrState SnowWaterDecTrState SnowWaterGrassState SnowWaterBSoilState SnowWaterWaterState SnowPackPaved SnowPackBldgs SnowPackEveTr SnowPackDecTr SnowPackGrass SnowPackBSoil SnowPackWater

  SnowFracPaved SnowFracBldgs SnowFracEveTr SnowFracDecTr SnowFracGrass SnowFracBSoil SnowFracWater SnowDensPaved SnowDensBldgs SnowDensEveTr SnowDensDecTr SnowDensGrass SnowDensBSoil SnowDensWater SnowAlb0

Note

Please report issues with the manual on the GitHub page.

Soil moisture states

SoilstorePavedState

Requirement

Required

Description

Initial water stored in soil beneath Paved surface [mm]

Configuration

For maximum values, see the used soil code in SUEWS_Soil.txt

SoilstoreBldgsState

Requirement

Required

Description

Initial water stored in soil beneath Bldgs surface [mm]

Configuration

For maximum values, see the used soil code in SUEWS_Soil.txt

SoilstoreEveTrState

Requirement

Required

Description

Initial water stored in soil beneath EveTr surface [mm]

Configuration

For maximum values, see the used soil code in SUEWS_Soil.txt

SoilstoreDecTrState

Requirement

Required

Description

Initial water stored in soil beneath DecTr surface [mm]

Configuration

For maximum values, see the used soil code in SUEWS_Soil.txt

SoilstoreGrassState

Requirement

Required

Description

Initial water stored in soil beneath Grass surface [mm]

Configuration

For maximum values, see the used soil code in SUEWS_Soil.txt

SoilstoreBSoilState

Requirement

Required

Description

Initial water stored in soil beneath BSoil surface [mm]

Configuration

For maximum values, see the used soil code in SUEWS_Soil.txt

Note

Please report issues with the manual on the GitHub page.

Vegetation parameters

LeavesOutInitially

Requirement

Optional

Description

Flag for initial leave status [1 or 0]

Configuration

If the model run starts in winter when trees are bare, set LeavesOutInitially = 0 and the vegetation parameters will be set accordingly based on the values set in SUEWS_SiteInfo.xlsm. If the model run starts in summer when leaves are fully out, set LeavesOutInitially = 1 and the vegetation parameters will be set accordingly based on the values set in SUEWS_SiteInfo.xlsm. Not LeavesOutInitially can only be set to 0, 1 or -999 (fractional values cannot be used to indicate partial leaf-out). The value of LeavesOutInitially overrides any values provided for the individual vegetation parameters. To prevent LeavesOutInitially from setting the initial conditions, either omit it from the namelist or set to -999. If values are provided individually, they should be consistent the information provided in SUEWS_Veg.txt and the time of year. If values are provided individually, values for all required surfaces must be provided (i.e. specifying only albGrass0 but not albDecTr0 nor albEveTr0 is not permitted).

GDD_1_0

Requirement

Optional

Description

GDD related initial value

Configuration

Cannot be negative. If leaves are already full, then this should be the same as GDDFull in SUEWS_Veg.txt. If winter, set to 0. It is important that the vegetation characteristics are set correctly (i.e. for the start of the run in summer/winter).

GDD_2_0

Requirement

Optional

Description

GDD related initial value

Configuration

Cannot be positive If the leaves are full but in early/mid summer then set to 0. If late summer or autumn , this should be a negative value. If leaves are off , then use the values of SDDFull in SUEWS_Veg.txt to guide your minimum value. It is important that the vegetation characteristics are set correctly (i.e. for the start of the run in summer/winter).

LAIinitialEveTr

Requirement

Optional

Description

Initial LAI for evergreen trees EveTr.

Configuration

The recommended values can be found from SUEWS_Veg.txt

LAIinitialDecTr

Requirement

Optional

Description

Initial LAI for deciduous trees DecTr.

Configuration

The recommended values can be found from SUEWS_Veg.txt

LAIinitialGrass

Requirement

Optional

Description

Initial LAI for irrigated grass Grass.

Configuration

The recommended values can be found from SUEWS_Veg.txt

albEveTr0

Requirement

Optional

Description

Albedo of evergreen surface EveTr on day 0 of run

Configuration

The recommended values can be found from SUEWS_Veg.txt

albDecTr0

Requirement

Optional

Description

Albedo of deciduous surface DecTr on day 0 of run

Configuration

The recommended values can be found from SUEWS_Veg.txt

albGrass0

Requirement

Optional

Description

Albedo of grass surface Grass on day 0 of run

Configuration

The recommended values can be found from SUEWS_Veg.txt

decidCap0

Requirement

Optional

Description

Storage capacity of deciduous surface DecTr on day 0 of run.

Configuration

The recommended values can be found from SUEWS_Veg.txt

porosity0

Requirement

Optional

Description

Porosity of deciduous vegetation on day 0 of run.

Configuration

This varies between 0.2 (leaf-on) and 0.6 (leaf-off). The recommended values can be found from SUEWS_Veg.txt

Note

Please report issues with the manual on the GitHub page.

Recent meteorology

DaysSinceRain

Requirement

Optional

Description

Days since rain [d]

Configuration

Important to use correct value if starting in summer season If starting when external water use is not occurring it will be reset with the first rain so can just be set to 0. If unknown, SUEWS sets to zero by default. Used to model irrigation.

Temp_C0

Requirement

Optional

Description

Initial air temperature [degC]

Configuration

If unknown, SUEWS uses the mean temperature for the first day of the run.

Note

Please report issues with the manual on the GitHub page.

Above ground state

PavedState

Requirement

Optional

Description

Initial wetness condition on Paved

Configuration

If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).

BldgsState

Requirement

Optional

Description

Initial wetness condition on Bldgs

Configuration

If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).

EveTrState

Requirement

Optional

Description

Initial wetness condition on EveTr

Configuration

If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).

DecTrState

Requirement

Optional

Description

Initial wetness condition on DecTr

Configuration

If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).

GrassState

Requirement

Optional

Description

Initial wetness condition on Grass

Configuration

If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).

BSoilState

Requirement

Optional

Description

Initial wetness condition on BSoil

Configuration

If unknown, model assumes dry surfaces (acceptable as rainfall or irrigation will update these states quickly).

WaterState

Requirement

Optional

Description

Initial wetness condition on Water

Configuration

For a large water body (e.g. river, sea, lake) set WaterState to a large value, e.g. 20000 mm; for small water bodies (e.g. ponds, fountains) set WaterState to smaller value, e.g. 1000 mm. This value must not exceed StateLimit specified in SUEWS_Water.txt . If unknown, model uses value of WaterDepth specified in SUEWS_Water.txt .

Note

Please report issues with the manual on the GitHub page.

Snow related parameters

SnowInitially

Requirement

Optional

Description

Flag for initial snow status [0 or 1]

Configuration

If the model run starts when there is no snow on the ground, set SnowInitially = 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

Requirement

Optional

Description

Initial amount of liquid water in the snow on paved surfaces Paved

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowWaterBldgsState

Requirement

Optional

Description

Initial amount of liquid water in the snow on buildings Bldgs

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowWaterEveTrState

Requirement

Optional

Description

Initial amount of liquid water in the snow on evergreen trees EveTr

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowWaterDecTrState

Requirement

Optional

Description

Initial amount of liquid water in the snow on deciduous trees DecTr

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowWaterGrassState

Requirement

Optional

Description

Initial amount of liquid water in the snow on grass surfaces Grass

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowWaterBSoilState

Requirement

Optional

Description

Initial amount of liquid water in the snow on bare soil surfaces BSoil

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowWaterWaterState

Requirement

Optional

Description

Initial amount of liquid water in the snow in water Water

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowPackPaved

Requirement

Optional

Description

Initial snow water equivalent if the snow on paved surfaces Paved

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowPackBldgs

Requirement

Optional

Description

Initial snow water equivalent if the snow on buildings Bldgs

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowPackEveTr

Requirement

Optional

Description

Initial snow water equivalent if the snow on evergreen trees EveTr

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowPackDecTr

Requirement

Optional

Description

Initial snow water equivalent if the snow on deciduous trees DecTr

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowPackGrass

Requirement

Optional

Description

Initial snow water equivalent if the snow on grass surfaces Grass

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowPackBSoil

Requirement

Optional

Description

Initial snow water equivalent if the snow on bare soil surfaces BSoil

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowPackWater

Requirement

Optional

Description

Initial snow water equivalent if the snow on water Water

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowFracPaved

Requirement

Optional

Description

Initial plan area fraction of snow on paved surfaces Paved

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowFracBldgs

Requirement

Optional

Description

Initial plan area fraction of snow on buildings Bldgs

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowFracEveTr

Requirement

Optional

Description

Initial plan area fraction of snow on evergreen trees EveTr

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowFracDecTr

Requirement

Optional

Description

Initial plan area fraction of snow on deciduous trees DecTr

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowFracGrass

Requirement

Optional

Description

Initial plan area fraction of snow on grass surfaces Grass

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowFracBSoil

Requirement

Optional

Description

Initial plan area fraction of snow on bare soil surfaces BSoil

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowFracWater

Requirement

Optional

Description

Initial plan area fraction of snow on water Water

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowDensPaved

Requirement

Optional

Description

Initial snow density on paved surfaces Paved

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowDensBldgs

Requirement

Optional

Description

Initial snow density on buildings Bldgs

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowDensEveTr

Requirement

Optional

Description

Initial snow density on evergreen trees EveTr

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowDensDecTr

Requirement

Optional

Description

Initial snow density on deciduous trees DecTr

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowDensGrass

Requirement

Optional

Description

Initial snow density on grass surfaces Grass

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowDensBSoil

Requirement

Optional

Description

Initial snow density on bare soil surfaces BSoil

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowDensWater

Requirement

Optional

Description

Initial snow density on Water

Configuration

The recommended values can be found from SUEWS_Snow.txt

SnowAlb0

Requirement

Optional

Description

Initial snow albedo

Configuration

The recommended values can be found from SUEWS_Snow.txt

Note

Please report issues with the manual on the GitHub page.

Meteorological Input File

SUEWS is designed to run using commonly measured meteorological variables.

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

• Temporal information (i.e., iy, id, it and imin should be in local time.

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

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

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

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

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

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

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

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

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

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

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

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

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

SSss_YYYY_data_tt.txt

Main meteorological data file.

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

Note

Please report issues with the manual on the GitHub page.

CBL input files

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

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

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

CBL_initial_data.txt

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

Definitions and example file of initial values prepared for Sacramento.

No.	Column name	Description
1	id	Day of year [DOY]
2	zi0	Initial convective boundary layer height (m)
3	gamt_Km	Vertical gradient of potential temperature (K m-1) strength of the inversion
4	gamq_gkgm	Vertical gradient of specific humidity (g kg-1 m-1)
5	Theta+_K	Potential temperature at the top of CBL (K)
6	q+_gkg	Specific humidity at the top of CBL (g kg-1)
7	Theta_K	Potential temperature in CBL (K)
8	q_gkg	Specific humidiy in CBL (g kg-1)

• gamt_Km and gamq_gkgm written to two significant figures are required for the model performance in appropriate ranges [Shiho2015].

id	zi0	gamt_Km	gamq_gkgm	Theta+_K	q+_gkg	theta_K	q_gkg
234	188	0.0032	0.00082	290.4	9.6	288.7	8.3
235	197	0.0089	0.089	290.2	8.4	288.3	8.7
︙	︙	︙	︙	︙	︙	︙	︙
︙	︙	︙	︙	︙	︙	︙	︙

CBLInput.nml

sample file of CBLInput.nml looks like

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

Note

The file contents can be in any order.

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

EntrainmentType QH_Choice InitialData_use Sondeflag CBLday(id)

CO2_included FileSonde(id) InitialDataFileName Wsb

Note

Please report issues with the manual on the GitHub page.

CBLinput

EntrainmentType

Requirement

Required

Description

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

Configuration

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

QH_Choice

Requirement

Required

Description

Determines QH used for CBL model.

Configuration

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

InitialData_use

Requirement

Required

Description

Determines initial values (see CBL_initial_data.txt)

Configuration

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

Sondeflag

Requirement

Required

Description

to fill

Configuration

Value	Comments
0	Does not read radiosonde vertical profile data - Recommended in this version.
1	Reads radiosonde vertical profile data

CBLday(id)

Requirement

Required

Description

Set CBLday(id) = 1 If CBL model is set to run for DOY 175–177, CBLday(175) = 1, CBLday(176) = 1, CBLday(177) = 1

Configuration

to fill

CO2_included

Requirement

Required

Description

Set to zero in current version

Configuration

to fill

FileSonde(id)

Requirement

Required

Description

If Sondeflag=1, write the file name including the path from site directory e.g. FileSonde(id)= ‘CBLinputfilesXXX.txt’, XXX is an arbitrary name.

Configuration

to fill

InitialDataFileName

Requirement

Required

Description

If InitialData_use ≥ 1, write the file name including the path from site directory e.g. InitialDataFileName=’CBLinputfilesCBL_initial_data.txt’

Configuration

to fill

Wsb

Requirement

Required

Description

Subsidence velocity (m s^-1 ) in eq. 1 and 2 of Onomura et al. (2015) [17] . (-0.01 m s^-1 Recommended in this version.)

Configuration

to fill

Note

Please report issues with the manual on the GitHub page.

ESTM-related files

SUEWS_ESTMCoefficients.txt

Note ESTM is under development in this release 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 SSss_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.

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.

A sample file of ESTMinput.nml looks like

&ESTMinput
TsurfChoice= 0
evolveTibld= 0      ! !!!!!FO!!!!! 0 originally
ibldCHmod  = 0
LBC_soil   = 13.00             !!FO!! 4, 8 or 17 degC - could be set as the annual mean air temperature (12.8 degC for London)
THEAT_ON   = 18.
THEAT_OFF  = 22.
THEAT_FIX  = 19.
/

Note

The file contents can be in any order.

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

TsurfChoice evolveTibld IbldCHmod LBC_soil

Theat_fix Theat_off Theat_on

Note

Please report issues with the manual on the GitHub page.

ESTMinput

TsurfChoice

Requirement

Required

Description

Source of surface temperature data used.

Configuration

Value	Comments
0	Tsurf in SSss_YYYY_ESTM_Ts_data_tt.txt used for all surface elements.
1	Input surface temperature are different for ground, roof and wall.
2	Wall surface temperature is different for four directions.

evolveTibld

Requirement

Required

Description

Source of internal building temperature (Tibld)

Configuration

Value	Comments
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

Requirement

Required

Description

Method to calculate internal convective heat exchange coefficients (CH) for internal building, wall and roof if evolveTibld is 1 or 2.

Configuration

Value	Comments
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

Requirement

Required

Description

Soil temperature at lowest boundary condition [˚C]

Configuration

to fill

Theat_fix

Requirement

Required

Description

Ideal internal building temperature [˚C]

Configuration

to fill

Theat_off

Requirement

Required

Description

Temperature at which heat control is turned off (used when evolveTibld=1) [˚C]

Configuration

to fill

Theat_on

Requirement

Required

Description

Temperature at which heat control is turned on (used when evolveTibld =1) [˚C]

Configuration

to fill

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

Note

Please report issues with the manual on the GitHub page.

SUEWS input converter

Note

The SUEWS table converter has been integrated into SuPy as a command line tool suews-convert since v2020a. Please install SuPy and run suews-convert to convert input tables from an older version to a newer one.

Usage

Please refer to the SuPy API page.

Example (from 2018a to 2020a)

Assuming your 2018a files are all included in the folder your_2018a_folder and your desirable converted files should be placed in a new folder your_2020a_folder, please do the following in your command line tool:

suews-convert -f 2018a -t 2020a -i your_2018a_folder -o your_2020a_folder

Tip

suews-convert will use the RunControl.nml file in your original folder to determine the location of input tables.

Note

Please report issues with the manual on the GitHub page.

Output files

Runtime diagnostic information

Error messages: problems.txt

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

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

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

  Run completed.
  0
  

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

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

Warning messages: warnings.txt

• If the program encounters a more minor issue it will not stop but a warning may be written to warnings.txt. It is advisable to check the warnings to ensure there is not a more serious problem.

• The warnings.txt file can be large (over several GBs) given warning messages are written out during a large scale simulation, you can use tail/head to view the ending/starting part without opening the whole file on Unix-like systems (Linux/mac OS), which may slow down your system.

• To prevent warnings.txt from being written, set SuppressWarnings to 1 in RunControl.nml.

• Warning messages are usually written with a grid number, timestamp and error count. If the problem occurs in the initial stages (i.e. before grid numbers and timestamps are assigned, these are printed as 00000).

Summary of model parameters: SS_FileChoices.txt

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

Model output files

SSss_YYYY_SUEWS_TT.txt

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

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

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

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

SSss_DailyState.txt

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

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

InitialConditionsSSss_YYYY.nml

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

SSss_YYYY_snow_TT.txt

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

File format of SSss_YYYY_snow_TT.txt

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

SSss_YYYY_RSL_TT.txt

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

File format of SSss_YYYY_RSL_TT.txt:

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

SSss_YYYY_BL_TT.txt

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

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

SSss_YYYY_ESTM_TT.txt

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

ESTM output file format

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

Note

Please report issues with the manual on the GitHub page.

Troubleshooting

How to report an issue of this manual?

Please submit your issue via our GitHub page.

How to join your email-list?

Please join our email-list here.

How to create a directory?

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

How to unzip a file

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

A text editor

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

Command prompt

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

Day of year [DOY]

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

ESTM output

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

First things to Check if the program seems to have problems

• Check the problems.txt file.

• Check file options – in RunControl.nml.

• Look in the output directory for the SS_FileChoices.txt. This allows you to check all options that were used in the run. You may want to compare it with the original version supplied with the model.

• Note there can not be missing time steps in the data. If you need help with this you may want to checkout UMEP

A pop-up saying “file path not found”

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

• Check that you have created the folder that you specified in RunControl.nml.

• Check does the output directory exist?

• Check that you have a single or double quotes around the FileInputPath, FileOutputPath and FileCode

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

• You don’t need to worry if the temperature should be (is) 0°C.

• If it should not be 0°C this suggests that there is a problem with the data.

%T changed to fit limits

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

%Iteration loop stopped for too stable conditions.

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

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

• Parameter(s) missing from input files.

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

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

Note

Please report issues with the manual on the GitHub page.

Recent publications

Note

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

JHW+19

Järvi, Leena, Havu, Minttu, Ward, Helen C., Bellucco, Veronica, McFadden, Joseph P., Toivonen, Tuuli, Heikinheimo, Vuokko, Kolari, Pasi, Riikonen, Anu, and Grimmond, C. Sue B. Spatial modeling of local-scale biogenic and anthropogenic carbon dioxide emissions in Helsinki. J. Geophys. Res. Atmos., 124(15):8363–8384, August 2019. doi:10.1029/2018jd029576.

SG19

Sun, Ting and Grimmond, Sue. A python-enhanced urban land surface model SuPy (SUEWS in python, v2019.2): Development, deployment and demonstration. Geosci. Model Dev., 12(7):2781–2795, July 2019. doi:10.5194/gmd-12-2781-2019.

KGM+19

Kokkonen, Tom V., Grimmond, Sue, Murto, Sonja, Liu, Huizhi, Sundström, Anu-Maija, and Järvi, Leena. Simulation of the radiative effect of haze on the urban hydrological cycle using reanalysis data in Beijing. Atmos. Chem. Phys., 19(10):7001–7017, May 2019. doi:10.5194/acp-19-7001-2019.

KGC+18

Kokkonen, T. V., Grimmond, C. S. B., Christen, A., Oke, T. R., and Järvi, L. Changes to the water balance over a century of urban development in two neighborhoods: Vancouver, Canada. Water Resour. Res., 54(9):6625–6642, September 2018. doi:10.1029/2017wr022445.

KGR+18

Kokkonen, T.V., Grimmond, C.S.B., Räty, O., Ward, H.C., Christen, A., Oke, T.R., Kotthaus, S., and Järvi, L. Sensitivity of surface urban energy and water balance scheme (SUEWS) to downscaling of reanalysis forcing data. Urban Clim., 23:36–52, March 2018. ICUC9: The 9th International Conference on Urban Climate. doi:10.1016/j.uclim.2017.05.001.

AGW+18

Ao, Xiangyu, Grimmond, C. S. B., Ward, H. C., Gabey, A. M., Tan, Jianguo, Yang, Xiu-Qun, Liu, Dongwei, Zhi, Xing, Liu, Hongya, and Zhang, Ning. Evaluation of the surface urban energy and water balance scheme (SUEWS) at a dense urban site in shanghai: Sensitivity to anthropogenic heat and irrigation. J. Hydrometeor., 19(12):1983–2005, December 2018. doi:10.1175/jhm-d-18-0057.1.

WG17

Ward, H.C. and Grimmond, C.S.B. Assessing the impact of changes in surface cover, human behaviour and climate on energy partitioning across greater London. Landscape Urban Plann., 165:142–161, September 2017. doi:10.1016/j.landurbplan.2017.04.001.

JGM+17

Järvi, L., Grimmond, C. S. B., McFadden, J. P., Christen, A., Strachan, I. B., Taka, M., Warsta, L., and Heimann, M. Warming effects on the urban hydrology in cold climate regions. Sci Rep, 7(1):5833, July 2017. doi:10.1038/s41598-017-05733-y.

WKJG16

Ward, H.C., Kotthaus, S., Järvi, L., and Grimmond, C.S.B. Surface urban energy and water balance scheme (SUEWS): Development and evaluation at two UK sites. Urban Clim., 18:1–32, December 2016. doi:10.1016/j.uclim.2016.05.001.

AGL+16

Ao, Xiangyu, Grimmond, C. S. B., Liu, Dongwei, Han, Zhihui, Hu, Ping, Wang, Yadong, Zhen, Xinrong, and Tan, Jianguo. Radiation fluxes in a business district of shanghai, china. J. Appl. Meteor. Climatol., 55(11):2451–2468, November 2016. doi:10.1175/jamc-d-16-0082.1.

OGL+15

Onomura, S., Grimmond, C.S.B., Lindberg, F., Holmer, B., and Thorsson, S. Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme. Urban Clim., 11:1–23, March 2015. doi:10.1016/j.uclim.2014.11.001.

JGT+14

Järvi, L., Grimmond, C. S. B., Taka, M., Nordbo, A., Setälä, H., and Strachan, I. B. Development of the surface urban energy and water balance scheme (SUEWS) for cold climate cities. Geosci. Model Dev., 7(4):1691–1711, August 2014. doi:10.5194/gmd-7-1691-2014.

Note

Please report issues with the manual on the GitHub page.

SUEWS-related Software

SuPy

SuPy is a Python-enhanced urban climate model with SUEWS as its computation core.

The scientific rigour in SuPy results is thus gurranteed by SUEWS (see SUEWS publications and Parameterisations and sub-models within SUEWS).

Meanwhile, the data analysis ability of SuPy is greatly enhanced by the Python-based SciPy Stack, notably numpy and pandas.

• How to get SuPy?

  SuPy is available on all major platforms (macOS, Windows, Linux) for Python 3.5+ via PyPI:

  python3 -m pip install supy --upgrade
  

• How to use SuPy?

  • Please follow Quickstart of SuPy and other tutorials.

  • Please see SuPy API for usage details of SuPy functions.

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.

• 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 input data

    • SUEWS Prepare

      Preprocessing and preparing input data for the SUEWS model

• Processor

  • Anthropogenic Heat (Q_F)

    • LQF

      Spatial variations anthropogenic heat release for urban areas

    • GQF

      Anthropogenic Heat (Q_F).

  • Urban Energy Balance

    • 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

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.

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) [LG2012] 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-annu al
Unique features:	Calculates active surface and fluxes	Radiation and energy balances	Radiation, energy and water balance (includes LUMPS)

Note

Please report issues with the manual on the GitHub page.

Tutorials

SUEWS

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

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

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS Introduction

Introduction

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

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

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

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

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

SUEWS can be run in a number of different ways:

1. Within UMEP via the Simple selection. This is useful for becoming familiar with the model (Part 1)

2. Within UMEP via the Advanced selection. This can be used to exploit the full capabilities of the model (Part 2)

3. SUEWS standalone (see manual)

4. Within other larger scale models (e.g. WRF).

SUEWS Simple Objectives

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

Steps

1. An introduction to the model and how it is designed.

2. Different kinds of input data that are needed to run the model

3. How to run the model

4. How to examine the model output

Initial Steps

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

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

SUEWS Model Inputs

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

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

How to Run SuewsSimple from the UMEP-plugin

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

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

1. To make use of this dataset click on Add settings from test dataset (see near bottom of the box). The land cover fractions and all other settings originate from Kotthaus and Grimmond (2014). They used a source area model to obtain the different input parameters (their Fig. 7 in Kotthaus and Grimmond, 2014).

2. Before you start the model, change the location of the output data to any location of your choice. Also, make notes on the settings such as Year etc.

3. Do a model run and explore the results by clicking Run. A command window appears, when SUEWS performs the calculations using the settings from the interface. Once the calculations are done, some of the results are shown in two summary plots.

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

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

Model results

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

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

Zoom in on end of March from the daily plot (click on image to make it larger).

Saving a Figure

Use the disk tool in the upper left corner.

1. .jpg

2. .pdf

3. .tif (Recommended)

4. .png

Output data Files

In the output folder (you selected earlier) you will find (at least) three files:

1. Kc98_2012_60.txt – provides the 60 min model results for site “KC1” for the year 2012

2. Kc_FilesChoices.txt – this indicates all options used in the model run see the SUEWS Manual for interpretation of content (this is for when you are doing large number of runs so you know exactly what options were used in each run)

3. Kc98_DailyState.txt – this provides the daily mean state (see SUEWS manual for detailed explanation). This allows you to see, for example, the daily state of the LAI (leaf area index).

4. Kc_OutputFormat.txt – provides detailed information about the output files such as extended descriptions for each column including units.

If you open these files in a text editor. To understand the header variables read the SUEWS manual.

Sensitivity to land surface fractions

Land cover fractions (click on image to make it larger).

The previous results are for a densely build-up area in London, UK. In order to test the sensitivity of SUEWS to some surface properties you can think about changing some of the surface properties in the SUEWS Simple. For example, change the land cover fraction by:

1. Change the land cover fractions as seen in the figure. Feel free to select other values as long as all the fractions add up to 1.0.

2. Save the output to a different folder by selecting output folder.

3. Click Run.

References

• Grimmond CSB and Oke 1999: Aerodynamic properties of urban areas derived, from analysis of surface form. Journal of Applied Climatology 38:9, 1262-1292

• Grimmond et al. 2015: Climate Science for Service Partnership: China, Shanghai Meteorological Servce, Shanghai, China, August 2015.

• Järvi L, Grimmond CSB & Christen A 2011: The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver J. Hydrol. 411, 219-237

• Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H &Strachan IB 2014: Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities, , Geosci. Model Dev. 7, 1691-1711

• Kormann R, Meixner FX 2001: An analytical footprint model for non-neutral stratification. Bound.-Layer Meteorol., 99, 207–224

• Kotthaus S and Grimmond CSB 2014: Energy exchange in a dense urban environment – Part II: Impact of spatial heterogeneity of the surface. Urban Climate 10, 281–307

• Onomura S, Grimmond CSB, Lindberg F, Holmer B, Thorsson S 2015: Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme. Urban Climate. 11:1-23 (link to paper)

• Ward HC, L Järvi, S Onomura, F Lindberg, A Gabey, CSB Grimmond 2016 SUEWS Manual V2016a, http://urban-climate.net/umep/SUEWS Department of Meteorology, University of Reading, Reading, UK

• Ward HC, Kotthaus S, Järvi L and Grimmond CSB 2016b: Surface Urban Energy and Water Balance Scheme (SUEWS): Development and evaluation at two UK sites. Urban Climate http://dx.doi.org/10.1016/j.uclim.2016.05.001

• Ward HC, S Kotthaus, CSB Grimmond, A Bjorkegren, M Wilkinson, WTJ Morrison, JG Evans, JIL Morison, M Iamarino 2015b: Effects of urban density on carbon dioxide exchanges: observations of dense urban, suburban and woodland areas of southern England. Env Pollution 198, 186-200

Authors this document: Lindberg and Grimmond (2016)

Definitions and Notation

To help you find further information about the acronyms they are classified by T: Type of term: C: computer term, S: science term, G: GIS term.

	Definition	T	Ref./Comment
DEM	Digital elevation model	G
DSM	Digital surface model	G
FAI (λF)	Frontal area index	S	Grimmond and Oke (1999)
GUI	Graphical User Interface	C
LAI	Leaf Area Index	S
PAI (λP)	Plan area index	S
png	Portable Network Graphics	C	format for saving plots/figures
QGIS		G	www.qgis.org
SUEWS	Surface Urban Energy and Water Balance Scheme	S
Tif	Tagged Image File Format	C	format for saving plots/figures
UI	user interface	C
UMEP	Urban Multi-scale Environmental predictor	C
z0	Roughness length for momentum	S	Grimmond and Oke (1999)
zd	Zero plane displacement length for momentum	S	Grimmond and Oke (1999)

Further explanation

Morphometric Methods to determine Roughness parameters:

For more and overview and details see Grimmond and Oke (1999) and Kent et al. (2017a). This uses the height and spacing of roughness elements (e.g. buildings, trees) to model the roughness parameters. For more details see Kent et al. (2017a), Kent et al. (2017b) and [Kent et al. (2017c)]. UMEP has tools for doing this: Pre-processor -> Urban Morphology

Source Area Model

For more details see Kotthaus and Grimmond (2014b) and Kent et al. (2017a). The Kormann and Meixner (2001) model is used to determine the probable area that a turbulent flux measurement was impacted by. This is a function of wind direction, stability, turbulence characteristics (friction velocity, variance of the lateral wind velocity) and roughness parameters.

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS Advanced

Introduction

The tutorial Urban Energy Balance - SUEWS Introduction should be completed first. This tutorial is designed to work with QGIS 2.18.

Objectives

1. To explore the link between QGIS and SUEWS to include new site-specific information

2. To examine how it affects the energy fluxes

Overview of steps

1. Initially become familiar with SUEWS advanced which is a plugin that makes it possible for you to set all parameters that can be manipulated in SUEWS as well as execute the model on mutiple grids (Urban Energy Balance - SUEWS Spatial).

2. Derive new surface information

3. Run the model

How to Run from the UMEP-plugin

How to run SUEWS Advanced:

1. Open the plugin which is located at UMEP -> Processor -> Urban Energy Balance -> Urban Energy Balance, SUEWS/BLUEWS (Advanced). This has most of the general settings (e.g. activate the snow module etc.) which are related to RunControl.nml.

2. Use the Input folder:

   • C:/Users/your_user_name/.qgis2/python/plugins/UMEP/suewsmodel/Input

3. Create or enter an Output directory of your choice.

4. From the Input folder - confirm the data are in there.

5. Tick in Obtain temporal… and set Temporal resolution of output (minutes) to 60.

6. Click Run

7. Make sure that output files are created.

8. You can now close the SUEWS/BLUEWS (Advanced)-plugin again.

Interface for SUEWS Advanced version.

Sensitivity Test

The default dataset included in Suews Simple has parameters calculated from a source area model to obtain the appropriate values for the input parameters. Roughness parameters such as roughness length (z₀) and zero plane displacement length (z_d) are calculated using morphometric models. Now you will explore the differences in fluxes using the default settings or using input parameters from the geodata included in the test datasets available for this tutorial. Download the zip-file (see below) and extract the files to a suitable location where you both have reading and writing capabilities.

Data for the tutorial can be downloaded here

Geodata	Name
Ground and building DSM	DSM_LondonCity_1m.tif (m asl)
Vegetation DSM	CDSM_LondonCity_1m.tif (m agl)
DEM (digital elevation model)	DEM_LondonCity_1m.tif (masl)
Land cover	LC_londoncity_UMEP_32631

They are all projected in UTM 31N (EPSG:32631). The three surface models originate from a LiDAR dataset. The land cover data is a mixture of Ordnance Survey and the LiDAR data.

1. Open the geodatasets. Go to Layer > Add layer > Add Raster Layer. Locate the files you downloaded before (see above).

2. A QGIS style file (.qml) is available for the land cover grid. It can found in C:Usersyour_user_name.qgis2pythonpluginsUMEP\ LandCoverReclassifier\. Load it in the Layer > Properties > Style > Style (lower left) Load file.

3. Click Apply before you close so that the names of the classes also load. You can also get the properties of a layer by right-click on a layer in the Layers-window.

4. If you have another land cover dataset you can use the LandCoverReclassifier in the UMEP pre-processor to populate with the correct values suitable for the UMEP plugin environment.

5. Now take a moment and investigate the different geodatasets. What is the sparial (pixel) resolution? How is ground represented in the CDSM?

Generating data from the geodatasets

1. Make certain that you have the geodatafiles open. The file at the top (left hand side (LHS)) of the list is the one that is shown in the centre (figure below). You can swap their order using the LHS box.

2. Open SUEWS Simple.

3. Begin by adding the test dataset again.

4. Update the building morphology parameters (top left panel in Suews Simple).

5. To generate new values, click on Open tool.

6. This is another plugin within UMEP that can be used to generate morphometric parameters

   

   QGIS where Suews Simple and Image Morphometric Parameters (Point) is opened.

7. First, clear the map canvas from your two other plugin windows, e.g. as figure above.

8. If you use the default test data in SUEWS Simple - you can overwrite is as you go.

9. Locate the eddy covariance tower position on the Strand building, King’s College London. To find the position, consult Figure 1 (KSS) in Kotthaus and Grimmond (2014).

10. Use Select point on canvas and put a point at that location (left).

11. Generate a study area. Use 500 m search distance, 5 degree interval and click Generate study area.

12. A circular area will be considered. Enter the DSM and DEM files (i.e. the files you currently have in the viewer)

13. Click Run.

    

    Figure 3. Settings for Image Morphometric Parameters for buildings.

14. In the folder you specified two additional files will be present (i) isotropic - averages of the morphometric parameters (ii) anisotropic - values for each wind sector you specified (5 degrees).

15. Close this plugin

16. Click on Fetch file from… in the building morphology panel

17. Choose the isotropic file (just generated).

18. Do the same for vegetation (upper left panel, right). See figure below.

19. Instead of locating the point again you can use the existing point.

20. You still need to generate a separate study area for the vegetation calculation.

21. Examine the CDSM (vegetation file) in your map canvas. As you can see, this data has no ground heights (ground = 0). Therefore, this time Tick in the box Raster DSM (only buildings) exist.

22. Enter the CDSM as your Raster DSM (only buildings).

    

    Settings for Image Morphometric Parameters for vegetation

23. A warning appears that your vegetation fractions between the morphology dataset and land cover dataset are large. You can ignore this for now since the land cover dataset also will change.

24. Repeat the same procedure for land cover as you did for buildings and vegetation but instead using the Land Cover Fraction (Point) plugin.

25. Enter the meteorological file, Year etc. This should be the same as for the first run you made.

26. Now you are ready to run the model. Click Run.

If you get an error window (figure below). This error is generate by SUEWS as the sum of the land cover fractions is not 1. If you calculate carefully, one part of a thousand is missing (this is probably a rounding error during data extraction). To fix this issue: add 0.001 to e.g. bare soil. Now run again.

Possible error window from running SUEWS with new settings.

The settings for running with geodata derived parameters (old version of GUI).

You are now familiar with the Suews Simple plugin. Your next task is to choose another location within the geodataset domain, generate data and run the model. If you choose an area where the fraction of buildings and paved surfaces are low, consider lowering the population density to get more realistic model outputs. Compare the results for the different area.

References

• Grimmond CSB and Oke 1999: Aerodynamic properties of urban areas derived, from analysis of surface form. Journal of Applied Climatology 38:9, 1262-1292

• Grimmond et al. 2015: Climate Science for Service Partnership: China, Shanghai Meteorological Servce, Shanghai, China, August 2015.

• Järvi L, Grimmond CSB & Christen A 2011: The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver J. Hydrol. 411, 219-237

• Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H &Strachan IB 2014: Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities, , Geosci. Model Dev. 7, 1691-1711

• Kormann R, Meixner FX 2001: An analytical footprint model for non-neutral stratification. Bound.-Layer Meteorol., 99, 207-224

• Kotthaus S and Grimmond CSB 2014: Energy exchange in a dense urban environment - Part II: Impact of spatial heterogeneity of the surface. Urban Climate 10, 281–307

• Onomura S, Grimmond CSB, Lindberg F, Holmer B, Thorsson S 2015: Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme. Urban Climate. 11:1-23 (link to paper)

• Ward HC, L Järvi, S Onomura, F Lindberg, A Gabey, CSB Grimmond 2016 SUEWS Manual V2016a, http://urban-climate.net/umep/SUEWS Department of Meteorology, University of Reading, Reading, UK

• Ward HC, Kotthaus S, Järvi L and Grimmond CSB 2016b: Surface Urban Energy and Water Balance Scheme (SUEWS): Development and evaluation at two UK sites. Urban Climate http://dx.doi.org/10.1016/j.uclim.2016.05.001

• Ward HC, S Kotthaus, CSB Grimmond, A Bjorkegren, M Wilkinson, WTJ Morrison, JG Evans, JIL Morison, M Iamarino 2015b: Effects of urban density on carbon dioxide exchanges: observations of dense urban, suburban and woodland areas of southern England. Env Pollution 198, 186-200

Authors of this document: Lindberg and Grimmond (2016)

Definitions and Notation

To help you find further information about the acronyms they are classified by T: Type of term: C: computer term, S: science term, G: GIS term.

	Definition	T	Reference/Comme nt
DEM	Digital elevation model	G
DSM	Digital surface model	G
FAI (λF)	Frontal area index	S	Grimmond and Oke (1999), their figure 2
GUI	Graphical User Interface	C
LAI	Leaf Area Index	S
PAI (λP)	Plan area index	S
png	Portable Network Graphics	C	format for saving plots/figures
QGIS		G	www.qgis.org
SUEWS	Surface Urban Energy and Water Balance Scheme	S
Tif	Tagged Image File Format	C	format for saving plots/figures
UI	user interface	C
UMEP	Urban Multi-scale Environmental predictor	C
z0	Roughness length for momentum	S	Grimmond and Oke (1999)
zd	Zero plane displacement length for momentum	S	Grimmond and Oke (1999)

Further explanation

Morphometric Methods to determine Roughness parameters:

For more and overview and details see Grimmond and Oke (1999). This uses the height and spacing of roughness elements (e.g. buildings, trees) to model the roughness parameters. UMEP has tools for doing this: Pre-processor -> Urban Morphology

Source Area Model

For more details see Kotthaus and Grimmond (2014b). The Kormann and Meixner (2001) model is used to determine the probable area that a turbulent flux measurement was impacted by. This is a function of wind direction, stability, turbulence characteristics (friction velocity, variance of the lateral wind velocity) and roughness parameters.

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS Spatial

Introduction

In this tutorial you will generate input data for the SUEWS model and simulate spatial (and temporal) variations of energy exchanges within a small area on Manhattan (New York City) with regards to a heat wave event.

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

This tutorial makes use of local high resolution detailed spatial data. If this kind of data are unavailable, other datasets such as local climate zones (LCZ) from the WUDAPT database could be used. The tutorial Urban Energy Balance - SUEWS and WUDAPT is available if you want to know more about using LCZs in SUEWS. However, it is strongly recommended to go through this tutorial before moving on to the WUDAPT/SUEWS tutorial.

Model output may be needed in many formats depending on a users’ needs. Thus, the format must be useful, while ensuring the science included within the model is appropriate. Fig. 9.13 shows the overall structure of UMEP, a city based climate service tool (CBCST) used in this tutorial. Within UMEP there are a number of models which can predict and diagnose a range of meteorological processes.

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

Note

This tutorial is currently designed to work with QGIS 2.18. It is recommended that you have a look at the tutorials Urban Energy Balance - SUEWS Introduction and Urban Energy Balance - SUEWS Advanced before you go through this tutorial.

Objectives

To perform and analyse energy exchanges within a small area on Manhattan, NYC.

Steps to be preformed

1. Pre-process the data and create input datasets for the SUEWS model

2. Run the model

3. Analyse the results

4. Perform simple mitigation measures to see how it affects the model results (optional)

Initial Steps

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

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

Loading and analyzing the spatial data

All the geodata used in this tutorial are from open access sources, primarily from the New York City. Information about the data are found in the table below.

Note

You can download the all the data from here. Unzip and place in a folder that you have read and write access to.

Spatial data used in this tutorial

Geodata	Year	Source	Description
Digital surface model (DSM)	2013 (Lidar), 2016 (building polygons)	United States Geological Survey (USGS). New York CMGP Sandy 0.7m NPS Lidar and NYC Open Data Portal. link	A raster grid including both buildings and ground given in meter above sea level.
Digital elevation model (DEM)	2013	United States Geological Survey (USGS). New York CMGP Sandy 0.7m NPS Lidar. link	A raster grid including only ground heights given in meter above sea level.
Digital canopy model (CDSM)	2013 (August)	United States Geological Survey (USGS). New York CMGP Sandy 0.7m NPS Lidar. link	A vegetation raster grid where vegetation heights is given in meter above ground level. Vegetation lower than 2.5 meter pixels with no vegetation should be zero.
Land cover (UMEP formatted)	2010	New York City Landcover 2010 (3ft version). University of Vermont Spatial Analysis Laboratory and New York City Urban Field Station. link	A raster grid including: 1. Paved surfaces, 2. Building surfaces, 3. Evergreen trees and shrubs, 4. Deciduous trees and shrubs, 5. Grass surfaces, 6. Bare soil, 7. Open water
Population density (residential)	2010	2010 NYC Population by Census Tracts, Department of City Planning (DCP). link)	People per census tract converted to pp/ha. Converted from vector to raster.
Land use	2018	NYC Department of City Planning, Technical Review Division. link	Used to redistribute population during daytime (see text). Converted from vector to raster

• Start by loading all the raster datasets into an empty QGIS project.

The order in the Layers Panel determines what layer is visible. You can choose to show a layer (or not) with the tick box. You can modify layers by right-clicking on a layer in the Layers Panel and choose Properties. Note for example that that CDSM (vegetation) is given as height above ground (meter) and that all non-vegetated pixels are set to zero. This makes it hard to get an overview of all 3D objects (buildings and trees). QGIS default styling for a raster is using the 98 percentile of the values. Therefore, not all the range of the data is shown in the layer window to the left.

• Right-click on your CDSM layer and go to Properties > Style and choose Singleband pseudocolor with a min value of 0 and max of 35. Choose a colour scheme of your liking.

• Go to Transparency and add an additional no data value of 0. Click ok.

• Now put your CDSM layer at the top and your DSM layer second in your Layers Panel. Now you can see both buildings and vegetation 3D object in your map canvas.

DSM and CDSM visible at the same time (click for larger image)

The land cover grid comes with a specific QGIS style file.

• Right-click on the land cover layer (landcover_2010_nyc) and choose Properties. Down to the left you see a Style-button. Choose Load Style and open landcoverstyle.qml and click OK.

• Make only your land cover class layer visible to examine the spatial variability of the different land cover classes.

The land cover grid has already been classified into the seven different classes used in most UMEP applications (see Land Cover Reclassifier). If you have a land cover dataset that is not UMEP formatted you can use the Land Cover Reclassifier found at UMEP > Pre-processor > Urban Land Cover > Land Cover Reclassifier in the menubar to reclassify your data.

Furthermore, a polygon grid (500 m x 500 m) to define the study area and individual grids is included (Grid_500m.shp). Such a grid can be produced directly in QGIS (e.g. Vector > Research Tools > Vector Grid) or an external grid can be used.

• Load the vector layer Grid_500m.shp into your QGIS project.

• In the Style tab in layer Properties, choose a Simple fill with a No Brush fill style to be able to see the spatial data within each grid.

• Also, add the label IDs for the grid to the map canvas in Properties > Labels to make it easier to identify the different grid squares later on in this tutorial.

As you can see the grid does not cover the whole extent of the raster grids. This is to reduce computation time during the tutorial. One grid cell takes ~20 s to model with SUEWS with meteorological forcing data for a full year.

Meteorological forcing data

Meteorological forcing data are mandatory for most of the models within UMEP. The UMEP specific format is given in Table 9.2. Some of the variables are optional and if not available or needed should be set to -999. The columns can not be empty. The needed data for this tutorial are discussed below.

Variables included in UMEP meteorological input file.

No.	Header	Description	Accepted range	Comments
1	iy	Year [YYYY]	Not applicable
2	id	Day of year [DOY]	1 to 365 (366 if leap year)
3	it	Hour [H]	0 to 23
4	imin	Minute [M]	0 to 59
5	qn	Net all-wave radiation [W m-2]	-200 to 800
6	qh	Sensible heat flux [W m-2]	-200 to 750
7	qe	Latent heat flux [W m-2]	-100 to 650
8	qs	Storage heat flux [W m-2]	-200 to 650
9	qf	Anthropogenic heat flux [W m-2]	0 to 1500
10	U	Wind speed [m s-1]	0.001 to 60
11	RH	Relative Humidity [%]	5 to 100
12	Tair	Air temperature [°C]	-30 to 55
13	pres	Surface barometric pressure [kPa]	90 to 107
14	rain	Rainfall [mm]	0 to 30	(per 5 min) this should be scaled based on time step used
15	kdown	Incoming shortwave radiation [W m-2]	0 to 1200
16	snow	Snow [mm]	0 to 300	(per 5 min) this should be scaled based on time step used
17	ldown	Incoming longwave radiation [W m-2]	100 to 600
18	fcld	Cloud fraction [tenths]	0 to 1
19	wuh	External water use [m3]	0 to 10	(per 5 min) scale based on time step being used
20	xsmd	(Observed) soil moisture	0.01 to 0.5	[m3 m-3 or kg kg-1]
21	lai	(Observed) leaf area index [m2 m-2]	0 to 15
22	kdiff	Diffuse shortwave radiation [W m-2]	0 to 600
23	kdir	Direct shortwave radiation [W m-2]	0 to 1200	Should be perpendicular to the Sun beam. One way to check this is to compare direct and global radiation and see if kdir is higher than global radiation during clear weather. Then kdir is measured perpendicular to the solar beam.
24	wdir	Wind direction [°]	0 to 360

The meteorological dataset used in this tutorial (MeteorologicalData_NYC_2010.txt) is from NOAA (most of the meteorological variables) and NREL (solar radiation data). It consists of tab-separated hourly air temperature, relative humidity, incoming shortwave radiation, pressure, precipitation and wind speed for 2010. There are other possibilities within UMEP to acquire meteorological forcing data. The pre-processor plugin WATCH can be used to download the variables needed from the global WATCH forcing datasets (Weedon et al. 2011, 2014).

• Open the meteorological dataset (MeteorologicalData_NYC_2010.txt) in a text editor of your choice. As you can see it does not include all the variables shown in Table 9.2. However, these variables are the mandatory ones that are required to run SUEWS. In order to format (and make a quality check) the data provided into UMEP standard, you will use the MetPreProcessor.

• Open MetDataPreprocessor (UMEP> Pre-Processor -> Meteorological Data > Prepare existing data).

• Load MeteorologicalData_NYC_2010.txt and make the settings as shown below. Name your new dataset NYC_metdata_UMEPformatted.txt.

The settings for formatting met data into UMEP format (click for a larger image)

• Close the Metdata preprocessor and open your newly fomatted datset in a text editor of your choice. Now you see that the forcing data is structured into the UMEP pre-defined format.

• Close your text file and move on to the next section of this tutorial.

Preparing input data for the SUEWS model

A key capability of UMEP is to facilitate preparation of input data for the various models. SUEWS requires input information to model the urban energy balance. The plugin SUEWS Prepare is for this purpose. This tutorial makes use of high resolution data but WUDAPT datasets in-conjuction with the LCZ Converter can be used (UMEP > Pre-Processor > Spatial data > LCZ Converter).

• Open SUEWS Prepare (UMEP > Pre-Processor > SUEWS prepare).

The dialog for the SUEWS Prepare plugin (click for a larger image).

Here you can see the various settings that can be modified. You will focus on the Main Settings tab where the mandatory settings are chosen. The other tabs include the settings for e.g. different land cover classes, human activities etc.

There are 10 frames included in the Main Settings tab where 8 need to be filled in for this tutorial:

1. Polygon grid

2. Building morphology

3. Tree morphology

4. Land cover fractions

5. Meteorological data

6. Population density

7. Daylight savings and UTC

8. Initial conditions

The two optional frames (Land use fractions and Wall area) should be used if the ESTM model is used to estimate the storage energy term (Delta Q_S). In this tutorial we use the OHM modelling scheme so these two tabs can be ignored for now.

• Close SUEWS Prepare

Building morphology

First you will calculate roughness parameters based on the building geometry within your grids.

• Open UMEP > Pre-Processor > Urban Morphology > Morphometric Calculator (Grid).

• Use the settings as in the figure below and press Run.

• When calculation ids done, close the plugin.

Note

For mac users, use this workaround: manually create a directory, go into the folder above and type the folder name. It will give a warning “—folder name–” already exists. Do you want to replace it? Click replace.

The settings for calculating building morphology.

This operation should have produced 17 different text files; 16 (anisotrophic) that include morphometric parameters from each 5 degree section for each grid and one file (isotropic) that includes averaged values for each of the 16 grids. You can open build_IMPGrid_isotropic.txt and compare the different values for a park grid (3054) and an urban grid (3242). Header abbreviations are explained here.

Tree morphology

Now you will calculate roughness parameters based on the vegetation (trees and bushes) within your grids. As you noticed there is only one surface dataset for vegetation present (CDSM_nyc) and if you examine your land cover grid (landcover_2010_nyc) you can see that there is only one class of high vegetation (Deciduous trees) present with our model domain. Therefore, you will not separate between evergreen and deciduous vegetation in this tutorial. As shown in Table 9.1, the tree surface model represents height above ground.

• Again, Open UMEP > Pre-Processor > Urban Morphology > Morphometric Calculator (Grid).

• Use the settings as in the figure below and press Run.

• When calculation is done, close the plugin.

The settings for calculating vegetation morphology.

Land cover fractions

Moving on to land cover fraction calculations for each grid.

• Open UMEP > Pre-Processor > Urban Land Cover > Land Cover Fraction (Grid).

• Use the settings as in the figure below and press Run.

• When calculation is done, close the plugin.

The settings for calculating land cover fractions

Population density

Population density will be used to estimate the anthropogenic heat release (Q_F) in SUEWS. There is a possibility to use both night-time and daytime population densities to make the model more dynamic. You have two different raster grids for night-time (pop_nighttime_perha) and daytime (pop_daytime_perha), respectively. This time you will make use of QGIS built-in function to to acquire the population density for each grid.

• Go to Plugins > Manage and Install Plugins and make sure that the Zonal statistics plugin is ticked. This is a build-in plugin which comes with the QGIS installation.

• Close the Plugin manager and open Raster > Zonal Statistics > Zonal Statistics.

• Choose your pop_daytime_perha layer as Raster layer and your Grid_500m and polygon layer. Use a Output column prefix of PPday and chose only to calculate Mean. Click OK.

• Run the tool again but this time use the night-time dataset.

SUEWS Prepare

Now you are ready to organise all the input data into the SUEWS input format.

• Open SUEWS Prepare

• In the Polygon grid frame, choose your polygon grid (Grid_500m) and choose id as your ID field

• In the Building morphology frame, fetch the file called build_IMPGrid_isotropic.txt.

• In the Land cover fractions frame, fetch the file called lc_LCFG_isotropic.txt.

• In the Tree morphology frame, fetch the file called veg_IMPGrid_isotropic.txt.

• In the Meteorological data frame, fetch your UMEP formatted met forcing data text file.

• In the Population density frame, choose the appropriate attributes created in the previous section for daytime and night-time population density.

• In the Daylight savings and UTC frame, set start and end of the daylight saving to 87 and 304, respectively and choose -5 (i.e. the time zone).

• In the Initial conditions frame, choose Winter (0%) in the Leaf Cycle, 100% Soil moisture state and nyc as a File code.

• In the Anthropogenic tab, change the code to 771. This will make use of settings adjusted for NYC according to Sailor et al. 2015.

• Choose an empty directory as your Output folder in the main tab.

• Press Generate

• When processing is finished, close SUEWS Prepare.

Running the SUEWS model in UMEP

To perform modelling energy fluxes for multiple grids, Urban Energy Balance - SUEWS Advanced can be used.

• Open UMEP > Processor > Urban Energy Balance > SUEWS/BLUEWS, Advanced. Here you can change some of the run control settings in SUEWS. SUEWS can also be executed outside of UMEP and QGIS (see SUEWS Manual. This is recommended when modelling long time series (multiple years) of large model domains (many grid points).

• Change the OHM option to [1]. This allows the anthropogenic energy to be partitioned also into the storage energy term.

• Leave the rest of the combobox settings at the top as default and tick both the Use snow module and the Obtain temporal resolution… box.

• Set the Temporal resolution of output (minutes) to 60.

• Locate the directory where you saved your output from SUEWSPrepare earlier and choose an output folder of your choice.

• Also, Tick the box Apply spin-up using…. This will force the model to run twice using the conditions from the first run as initial conditions for the second run.

• Click Run. This computation will take a while so be patient.

Analysing model reults

UMEP has a tool for basic analysis of any modelling performed with the SUEWS model. The SUEWSAnalyser tool is available from the post-processing section in UMEP.

• Open UMEP > Post-Processor > Urban Energy Balance > SUEWS Analyzer. There are two main sections in this tool. The Plot data-section can be used to make temporal analysis as well as making simple comparisins between two grids or variables. This Spatial data-section can be used to make aggregated maps of the output variables from the SUEWS model. This requires that you have loaded the same polygon grid into your QGIS project that was used when you prepared the input data for SUEWS using SUEWS Prepare earlier in this tutorial.

The dialog for the SUEWS Analyzer tool.

To access the output data from the a model run, the RunControl.nml file for that particular run must be located. If your run has been made through UMEP, this file can be found in your output folder. Otherwise, this file can be located in the same folder from where the model was executed.

• In the top panel of SUEWS Analyzer, load the RunControl.nml located in the output folder.

You will start by plotting basic data for grid 3242 which is one of the most dense urban area in the World.

• In the left panel, choose grid 3242 and year 2010. Tick plot basic data and click Plot. This will display some of the most essential variables such as radiation balance and budget etc. You can use the tools such as the zoom to examine a shorter time period more in detail.

Basic plot for grid 3242. Click on image for enlargement.

Notice e.g. the high Q_F values during winter as well as the low Q_E values throughout the year.

• Close the plot and make the same kind of plot for grid 3054 which is a grid mainly within Central Park. Consider the differences between the plot generated for grid 3242. Close the plot when you are done.

In the left panel, there is also possibilities to examine two different variables in time, either from the same grid or between two different grid points. There is also possible to examine different parameters through scatterplots.

The right panel in SUEWS Analyzer can be used to perform basic spatial analysis on your model results by producing aggragated maps etc. using different variables and time spans. Sensible heat (Q_H) is one variable to visualise warm areas as it is a variable that show the amount of the available energy that will be partitioned into heat.

• Make the settings as shown in the figure below but change the location where you will save your data on your own system.

The dialog for the SUEWS Analyzer tool to produce a mean Q_H for each grid. Click on image for enlargement.

Note that the warmest areas are located in the most dense urban environments and the coolest are found where either vegetation and/or water bodies are present. During 2010 there was a 3-day heat-wave event in the region around NYC that lasted from 5 to 8 July 2010 (Day of Year: 186-189).

• Make a similar average map but this time of 2m air temperature and choose only the heat wave period. Save it as a separate geoTiff.

The influence of mitigation measures on the urban energy balance (optional)

There are different ways of manipulating the data using UMEP as well directly changing the input data in SUEWS to examine the influence of mitigation measures on the UEB. The most detailed way would be to directly changing the surface data by e.g. increasing the number of street trees. This can be done by e.g. using the TreeGenerator-plugin in UMEP. This method would require that you go through the workflow of this tutorial again before you do your new model run. Another way is to directly manipulate input data to SUEWS at grid point level. This can done by e.g. changing the land cover fractions in SUEWS_SiteSelect.txt, the file that includes all grid-specific information used in SUEWS.

• Make a copy of your whole input folder created from SUEWSPRepare earlier and rename it to e.g. Input_mitigation.

• In that folder remove all the files beginning with InitialConditions except the one called InitialConditionsnyc_2010.nml.

• Open SUEWS_SiteSelect.txt in Excel (or similar software).

• Now increace the fraction of decidious trees (Fr_DecTr) for grid 3242 and 3243 by 0.2. As the total land cover fraction has to be 1 you also need to reduce the paved fraction (Fr_Paved) by the same amount.

• Save and close. Remember to keep the format (tab-separated text).

• Create an empty folder called Output_mitigation

• Open SuewsAdvanced and make the same settings as before but change the input and output folders.

• Run the model.

• When finished, create a similar average air temperature map for the heat event and compare the two maps. You can do a difference map by using the Raster Calculator in QGIS (Raster>Raster Calculator…).

Tutorial finished.

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS and WUDAPT

Introduction

Note

This tutorial is not ready for use. Work in progress.

In this tutorial you will generate input data for the SUEWS model and simulate spatial (and temporal) variations of energy exchanges within an area in New York City using local climate zones derived within the WUDAPT project. The World Urban Database and Access Portal Tools project is a community-based project to gather a census of cities around the world.

Note

This tutorial is currently designed to work with QGIS 2.18. It is strongly recommended that you goo through the Urban Energy Balance - SUEWS Spatial tutorial before you go through this tutrial.

Objectives

To prepare input data for the SUEWS model using a WUDAPT dataset and analyse energy exchanges within an area in New York City, US.

Initial Steps

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

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

Loading and analyzing the spatial data

Note

You can download the all the data from here. Unzip and place in a folder where you have read and write access to. The LCZ data for various cities are also available from the WUDAPT portal.

• Start by loading the raster dataset (NYC_LCZ.tif) into an empty QGIS project. This dataset is referenced to the WGS84 CRS (ESPG:4326).

• You can set the correct colors for your LCZ raster by opening the LCZ converter at UMEP > Pre-Processer > Spatial data > LCZ converter. In the upper right corner, choose the LCZ raster and press Color Raster and then close the LCZ Converter.

Vector grid generation

A vector polygon grid is required for specifying the extent and resolution of the modelling.You will make use of a built-in tool in QGIS to generate such a grid.

1. First zoom in to Manhattan as shown in the figure below

Zoom in the Manhattan island.

1. As WGS84 (EPSG:4326) is in degree coordinates and maybe you want to specify your grid in meters, you need to change the CRS of your current QGIS-project. Click on the globe at the bottom right of your QGIS window and select ESPG:26918 as your ‘on the fly’ CRS.

2. Open vector grid at Vector > Research Tools > Vector grid.

3. Select the extend of your canvas by clicking the … next to Grid extent (xmin, xmax, ymin, ymax) and select Use layer/canvas extent.

4. Select Use Canvas Extent.

5. As you can see the units in now in meters and not in degrees. Specify the desired grid spacing to 5000 meters. This will save time later on. Of course you can set it a much smaller number if you have the time to wait when the model performs the calculations later on.

6. Make sure the output is in polygons, not lines.

7. Create as temporary layer.

8. Save your grid by right-click on the new layer in the Layers Panel and choose Save as…. Here it is very imporant that you save in the same CRS as you other layers (ESPG:4326). Save as a shape file.

Population density

Population density is required to estimate the anthropogenic heat release (Q_F) in SUEWS. There is a possibility to make use of both night-time and daytime population densities to make the model more dynamic. In this tutorial you will only use a night-time dataset. This dataset can be aqcuired from the Spatial Data Downloader in UMEP.

1. Open de spatial downloader at UMEP > Pre-Processer > Spatial data > Spatial Data Downloader.

2. Select population density and select the GPWv4: UN-Adjusted Population Density closest to the year you intend to model (2010). The values will be in (pp / square kilometer).

3. Make sure your canvas is zoomed out to the entire LCZ map and click Use canvas extent

4. Now click Get data.

5. Save as a geoTiff (.tif) with the name GPWv4_2010.

6. Now you need to calculate population density per grid in units pp/hectare. First open the QGIS built-in tool Zonal statistics (Raster > Zonal Statistics). If the tool is absent you need to activate it by going to Plugins > Manage and Install Plugins and add Zonal statistics plugin. Open the tool and make the settings as shown below. This will calulate mean population density per grid.

   

   Settings for the Zonal statistics plugin.

7. Open the attribute table for your Grid_5000m-layer (right-click on layer and choose (Open attribute Table).

8. Click the abacus shaped symbol this is the Field calculator.

9. Under Output field name write “pp_ha, the Output field type should be “Decimal number (real)”, and the Output Precision can be set to 2.

10. In the expression dialog box write gpw_mean/100, here gpw_mean is the name of your population density field and the 100 is to convert the data from km² to ha.

11. Click OK and you should have a new field called “pp_ha”.

12. Click the yellow pencil in the top left corner of the attribute table to stop editing and save your changes and close the attribute table.

LCZ converter

Now you will make use of the LCZ Converter-plugin to generate input data for the SUEWS model.

1. Open the LCZ converter at UMEP > Pre-Processer > Spatial data > LCZ converter.

2. Select the LCZ raster layer at ‘’ LCZ raster’‘.

3. Select the vector grid you have just created in step 3 at Vector grid and select the ID field of the polygon grid at ID field.

4. By clicking Adjust default parameters you can edit the table. This table specifies the pervious, trees, grass, etc. fractions for each of the LCZ classes. For more information about each of the classes see LCZConverter. If you choose to edit the table, make sure all fractions add up to 1.0.

5. If you are unsure about the exact fractions for each of the LCZ click the tab Pervious distribution. Select Same for all LCZ’s

Settings for the LCZ converter plugin.

1. Now you can select your best estimate about the distribution of the pervious surface fractions for urban and the tree distribution for rural. In addition, also specify the expected height of the trees.

2. Once you are satisfied click Update Table.

3. Select add results to polygon.

4. Add a file prefix if desired.

5. Finally select an output folder where you would like to receive the text files and click Run.

Note

For mac users use this workaround: manually create a directory, go into the folder above and type the folder name. It will give a warning “—folder name–” already exists. Do you want to replace it? Click replace.

This should generate 3 text files, one with the land cover fractions, one with morphometric parameters for buildings and one for trees for each grid cell of the polygon grid.

SUEWS

Before running SUEWS, you will need to prepare some of the data required to run it.

1. SUEWS prepare requires the grid CRS to be in metres not degrees, therefore we need to reproject the grid. Right-click the vector grid and click save as... Assign a different file name, use CRS ESPG:26918 and click OK.

2. Open SUEWS prepare at: UMEP > Pre-Processer > SUEWS prepare.

3. Under vector polygon grid specify your reprojected vector grid and the ID field.

4. Select the location of the Meteorological file that was included in the input data, the building morphology (_build_), tree morphology (_veg_) and land cover fractions (_LCFGrid_) from the step above and the population density (pp_ha) in the dropdown list.

5. Enter the start and end of day light savings time for 2010 and the UTC offset of New York.

6. Specify the Leaf cycle = winter when initialising in January. Unless the user has better information initialise the Soil moisture state at 100 %.

7. Select an output folder where the initial data to run SUEWS should be saved and press Generate.

8. Open SUEWS at UMEP > Processer > Urban Energy Balance > Urban Energy Balance (SUEWS/BLUEWS, advanced). Using this for the first time, the system will ask you to download the latest version of SUEWS, click OK.

9. Change the OHM option to [1]. This allows the anthropogenic energy to be partitioned also into the storage energy term.

10. Leave the rest of the combobox settings at the top as default and tick both the Use snow module and the Obtain temporal resolution… box.

11. Set the Temporal resolution of output (minutes) to 60.

12. Locate the directory where you saved your output from SUEWSPrepare earlier and choose an output folder of your choice.

13. Also, Tick the box Apply spin-up using…. This will force the model to run twice using the conditions from the first run as initial conditions for the second run.

14. Click Run. This computation will take a while so be patient. If it only takes a very short time (a few seconds) the model has probably crashed. Please consult the problems.txt file for more information.

Analysing model reults

When the model has successfully run, it is time to look at some of the output of the model. The SUEWSAnalyser tool is available from the post-processing section in UMEP.

1. To better visualise what would be interesting to plot, label the grid ID’s of your vector grid. Do this by right-clicking the vector grid, going to properties, under the Labels tab click Show labels for this layer, label with id and select a text format of your choosing.

2. Open UMEP > Post-Processor > Urban Energy Balance > SUEWS Analyzer. There are two main sections in this tool. The Plot data-section can be used to make temporal analysis as well as making simple comparisins between two grids or variables. This Spatial data-section can be used to make aggregated maps of the output variables from the SUEWS model. This requires that you have loaded the same polygon grid into your QGIS project that was used when you prepared the input data for SUEWS using SUEWS Prepare earlier in this tutorial.

3. To access the output data from the a model run, the RunControl.nml file for that particular run must be located. If your run has been made through UMEP, this file can be found in your output folder. Otherwise, this file can be located in the same folder from where the model was executed. In the top panel of SUEWS Analyzer, load the RunControl.nml located in the output folder.

Feel free to try plotting different variables, first let’s try and look at a variable for two different grid cells.

1. Load the RunControl.nml located in the output folder.

2. On the left hand specify a Grid cell that is largely urban, select Year to investigate. Select the desired time period and a variable, for example Sensible heat flux.

3. Comparing with another less urbanised gridcell turn on include another variable and specify the desired Grid, selecting the same Variable (Sensible heat flux).

4. Click plot.

Example of the comparison of the heat flux for two grid cell in the vector grid.

Now we will look at the horizontal distribution of the storage flux. #. On the right-hand side of SUEWS analyser specify the Net Storage flux as a variable to analyse. #. Select the Year to investigate and a time period during the summer season. #. Select the Median and Only daytime. #. Select the Vector polygon grid you have been using and save as a GeoTiff. #. Specify an output filename, and tick Add Geotiff to map canvas and Generate.

Example of the median, night-time net storage flux.

This should generate a geotiff file with a median, night-time net storage flux in the selected timeperiod.

Tutorial finished.

SuPy

For Python users, a Python package SuPy with SUEWS as the calculation kernel is available to conduct SUEWS simulations. SuPy tutorials are provided at its tutorial site.

Note

Please report issues with the manual on the GitHub page.

Development, Suggestions and Support

If you are interested in contributing to the code please contact Sue Grimmond. Please follow Coding Guidelines for coding SUEWS.

Please provide your feedbacks via channels listed here.

Note

Please report issues with the manual on the GitHub page.

Coding Guidelines

If you are interested in contributing to the code please contact Sue Grimmond.

Coding

1. Core physics and calculatoin schemes of SUEWS are written in Fortran 90

2. Code is hosted in GitHub as private repository

3. Variables

   • Names should be defined at least in one place in the code – ideally when defined

   • Implicit None should be used in all subroutines

   • Variable name should include units. e.g. Temp_C, Temp_K

   • Output variable attributes should be provided in the TYPE structure defined in the ctrl_output module as follows:

     : TYPE varAttr
     : CHARACTER(len = 15) :: header ! short name in headers
     : CHARACTER(len = 12) :: unit   ! unit
     : CHARACTER(len = 14) :: fmt    ! output format
     : CHARACTER(len = 50) :: longNm ! long name for detailed description
     : CHARACTER(len = 1)  :: aggreg ! aggregation method
     : CHARACTER(len = 10) :: group  ! group: datetime, default, ESTM, Snow, etc.
     : INTEGER             :: level  ! output priority level: 0 for highest (defualt output)
     : END TYPE varAttr
     

4. Code should be written generally

5. Data set for testing should be provided

6. Demonstration that the model performance has improved when new code has been added or that any deterioration is warranted.

7. Additional requirements for modelling need to be indicated in the manual

8. All code should be commented in the program (with initials of who made the changes – name specified somewhere and institution)

9. The references used in the code and in the equations will be collected to a webpage

10. Current developments that are being actively worked on

Testing

1. The testing of SUEWS is done using Python 3

2. The following tests are done for each release of SUEWS:

1. Working status of all physics schemes

2. Year-grid looping logic

3. Identity of output results with internal test dataset

Please use pre-defined make test option to check if your code can pass all tests or not. If not, the correctness of added code should be justified with caution.

Preparation of SUEWS Manual

1. The SUEWS manual is written in reStructuredText (aka rst) with a Sphinx flavour

2. The SUEWS manual is hosted by readthedocs.org

3. CSV tables used in following pages are automatically generated from the Description field in Input Options by each build, so DON’T manually edit them as your edits will be swiped automatically:

• SUEWS_AnthropogenicEmission.txt

• SUEWS_BiogenCO2.txt

• SUEWS_Conductance.txt

• SUEWS_Irrigation.txt

• SUEWS_NonVeg.txt

• SUEWS_OHMCoefficients.txt

• SUEWS_Profiles.txt

• SUEWS_SiteSelect.txt

• SUEWS_Snow.txt

• SUEWS_Soil.txt

• SUEWS_Veg.txt

• SUEWS_Water.txt

• SUEWS_WithinGridWaterDist.txt

F2PY tips

This includes several DON’T’s that have never been mentioned by F2PY docs:

1. DON’T mix comments as lines into argument list of Fortran subroutines/functions:

DONT:

subroutine(&
! DONT DO this
args&
)

OK:

subroutine(&
args& ! OK this way
)

2. DON’T end a subroutine as ENDSUBROUTINE. Instead, leave a space in between to form END SUBROUTINE. Otherwise, the subroutines won’t be correctly parsed and picked up by F2PY.

Note

Please report issues with the manual on the GitHub page.

Suggestions and Support

Please provide your feedbacks via these channels:

• GitHub issues page of this repository

• Mailing lists:

  • SUEWS

  • UMEP: As UMEP has a number of tools to support SUEWS you may want to join it as well.

Note

Please report issues with the manual on the GitHub page.

Benchmark Report

Since v2018a, SUEWS is benchmarked against observations for assessment of model performance. A site based benchmark report generation system is introduced in v2018c to produce detailed reports for testing sites; the number of sites is expanding and more cases will be added as they are benchmarked.

Each report includes the following parts:

1. Overall performance:

1. Performance Score: Large scores indicate better performance. The scores are calculated according to weighted averages of statistics for selected benchmark variables.

2. Detailed Statistics: Grids are coloured based relative performance between different versions: a greener grid indicates better performance in the chosen variable using the specific release whereas a redder one shows poorer performance; and those with gray backgrounds indicate the same performance across different releases.

2. Cross-comparison in model variables between releases:

1. Detailed statistics tables: statistics for each variable.

2. Pair plots: comparison in simulation results between different version-pairs.

3. Time series plots: comparison in simulated monthly climatologies of diurnal cycles of each variable between different version-pairs.

The latest benchmark reports are available at the SUEWS Benchmark site.

Note

Please report issues with the manual on the GitHub page.

API

This link redirects to the SUEWS API site, which provides documentation of SUEWS source code automatically generated by Doxygen.

SUEWS developers are strongly suggested to use the API site as the main reference for understanding SUEWS source code.

Note

Please report issues with the manual on the GitHub page.

Version History

Note

Please report issues with the manual on the GitHub page.

Version 2020a (Released on 14 May 2020)

Note

In a future release, we will ONLY deliver SUEWS along with SuPy as a command line tool suews-run: release of standalone SUEWS binaries will be stopped to ease our maintenance load and to facilitate rapid developments. Users will need to have Python 3.6+ to install SuPy:

python3 -m pip install -U supy

However, as the source code of SUEWS are public, users can feel free to compile standalone binaries for platforms of their own interests.

• Improvement

  1. A ponding water scheme is added in the automatic irrigation calculation; useful when a certain depth of ponding water to maintain in irrigation (e.g., flooding irrigation in rice crop-field).

  2. Irrigation fraction can be specified for all surfaces (previously only available for vegetated surfaces)

  3. A U-shape approach for calculating HDD/CDD is introduced to account for a wide comfort zone between heating and cooling critical temperatures.

• Changes

  1. A new RoughLenHeatMethod option 5: adaptively choose option 1 for fully pervious surface or 2 otherwise (if any impervious surface exists).

  2. A new column H_maintain is added in SUEWS_Irrigation.txt to set ponding water depth.

  3. New columns to specify irrigation fractions for non-vegetated surfaces in SUEWS_SiteSelect.txt.

  4. A new scheme option BaseTMethod in RunControl.nml to set calculation scheme for HDD/CDD.

• Fix

  NONE.

• Known issues

  1. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2019a (released on 15 November 2019)

• Improvement

  1. An anthropogenic emission module is added. Module details refer to Järvi et al. (2019) [J19].

  2. A canyon profile module is added. Module details refer to Theeuwes et al. (2019) [T19].

• Changes

  1. Input file SUEWS_AnthropogenicHeat.txt is renamed to SUEWS_AnthropogenicEmission.txt with new parameters added: MinFCMetab, MaxFCMetab, FrPDDwe, FcEF_v_kgkmWD and FcEF_v_kgkmWE.

  2. BLUEWS has been recovered; set CBLUse to use it.

  3. Removed features:

  • SOLWEIG: fully removed from code.

  • netCDF: fully removed as this is very infrequently used; users who need this are suggested to use SuPy with help from pandas and xarray to save results in netCDF more elegantly.

• Fix

  1. Fixed a bug in LAI calculation for longterm runs.

  2. Fixed a bug in net all-wave radiation differential calculation for OHM.

  3. Fixed a bug in GDD/SDD calculation that different vegetative land covers could unexpectedly affect each other.

  4. Fixed water redistribution bug in snow module.

• Known issues

  1. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2018c (released on 21 February 2019)

• Improvement

  1. SuPy (SUEWS in Python): a Python-enhanced wrapper of SUEWS, which can facilitate a more fluent workflow of SUEWS-centred urban climate research. More details refer to SuPy documentation site.

  2. Improved benchmark report: More testing sites are added thanks to an automated benchmark report system.

• Changes

  None.

• Fix

  1. Fixed a bug in LAI calculation for longterm runs.

  2. Fixed a bug in net all-wave radiation differential calculation for OHM.

  3. Fixed water redistribution bug in snow module.

• Known issues

  1. BLUEWS is disabled

  2. Observed soil moisture can not be used as an input

  3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2018b (released 17 December 2018)

• Improvement

  1. Improved calculation of OHM-related radiation terms:

     The temporal difference term dQ*/dt is now calculated using the time-step-weighted dQ* of previous time step instead of a series of Q* values from previous time steps, which improves the usage of memory and allows time-step-varying simulations (needed by WRF-SUEWS coupling).

• Changes

  None.

• Fix

  1. Fixed a bug in picking up external water use from meteorological forcing file.

• Known issues

  1. BLUEWS is disabled

  2. Observed soil moisture can not be used as an input

  3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2018a (released 2 August 2018)

• New

  1. Many under-the-hood improvements:

     • Added explicit interface intent for confusion-less coupling between SUEWS modules

     • Restructured layout of physics schemes for better modularity

     • Improved the alignment in output txt files

  2. New readthedocs.org-based documentation system

  3. Added SUEWS input converter for conversion of input files between versions

  4. Added Benchmark Report for recent releases.

• Improvement

  1. Improved the near surface diagnostics scheme (T2, Q2, U10)

  2. Improved skin temperature calculation (Ts)

• Changes

  1. StabilityMethod: recommended option is change from 2 to 3 as options other than 3 have been noticed with numerical issues under several scenarios, which will be fixed in the next release.

  2. Model run - changes in selections moved from SUEWS_SiteSelect.txt to SUEWS_AnthropogenicHeat.txt: EnergyUseProfWD, EnergyUseProfWE, ActivityProfWD, ActivityProfWE.

  3. BiogenCO2Code is added to SUEWS_Veg.txt for looking up biogenic characteristics in the new SUEWS_BiogenCO2.txt file.

  4. TraifficRate and BuildEnergyUse in SUEWS_SiteSelect.txt are expanded to allow weekday and weekend values: TrafficRate_WD, TrafficRate_WE, QF0_BEU_WD, QF0_BEU_WE.

  5. AnthropCO2Method is removed from RunControl.nml.

  6. AnthropHeatMethod is renamed to EmissionsMethod.

  7. AHMin, AHSlope and TCritic are expanded to allow weekday and weekend values by adding _WD and _WE as suffix, of which AHSlope and TCritic are also expanded to allow cooling and heating settings.

• Known issues

  1. BLUEWS is disabled

  2. Observed soil moisture can not be used as an input

  3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2017b (released 2 August 2017)

PDF Manual for v2017b

1. Surface-level diagnostics: T2 (air temperature at 2 m agl), Q2 (air specific humidity at 2 m agl) and U10 (wind speed at 10 m agl) added as default output.

2. Output in netCDF format. Please note this feature is NOT enabled in the public release due to the dependency of netCDF library. Assistance in enabling this feature may be requested to the development team via SUEWS mail list.

3. Edits to the manual.

4. New capabilities being developed, including two new options for calculating storage heat flux (AnOHM, ESTM) and modelling of carbon dioxide fluxes. These are currently under development and should not be used in Version 2017b.

5. Known issues

   1. BLUEWS parameters need to be checked

   2. Observed soil moisture can not be used as an input

   3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2017a (Feb 2017)

1. Changes to input file formats (including RunControl.nml and InitialConditions files) to facilitate setting up and running the model. Met forcing files no longer need two rows of -9 at the end to indicate the end of the file.

2. Changes to output file formats (now option to write out only a subset of variables, rather than all variables).

3. SUEWS can now disaggregate forcing files to the model time-step and aggregate output at the model time-step to lower resolution. This removes the need for the python wrapper used with previous versions.

4. InitialConditions format and requirements changed. A single file can now be provided for multiple grids. SUEWS will approximate most (but not all) of the required initial conditions if values are unknown. (However, if detailed information about the initial conditions is known, this can still be provided to and used by SUEWS.)

5. Leaf area index calculations now use parameters provided for each vegetated surface (previously only the deciduous tree LAI development parameters were applied to all vegetated surfaces).

6. For compatibility with GIS, the sign convention for longitude has been changed. Now negative values are to the west, positive values are to the east. Note this appears to have been incorrectly coded in previous versions (but may not necessarily have been problematic).

7. Storage heat flux calculation adapted for shorter (sub-hourly) model time-step: hysteresis calculation now based on running means over the previous hour.

8. Improved error handling, including separate files for serious errors (problems.txt) and less critical issues (warnings.txt).

9. Edits to the manual.

10. New capabilities being developed, including two new options for calculating storage heat flux (AnOHM, ESTM) and modelling of carbon dioxide fluxes. These are currently under development and should not be used in Version 2017a.

Note

Please report issues with the manual on the GitHub page.

Version 2016a (released 21 June 2016)

PDF Manual for v2016a

1. Major changes to the input file formats to facilitate the running of multiple grids and multiple years. Surface characteristics are provided in SUEWS_SiteSelect.txt and other input files are cross-referenced via codes or profile types.

2. The surface types have been altered:

   • Previously, grass surfaces were entered separately as irrigated grass and unirrigated grass surfaces, whilst the ‘unmanaged’ land cover fraction was assumed by the model to behave as unirrigated grass. There is now a single surface type for grass (total for irrigated plus unirrigated) and a new bare soil surface type.

   • The proportion of irrigated vegetation must now be specified for grass, evergreen trees and deciduous trees individually.

3. The entire model now runs at a time step specified by the user. Note that 5 min is strongly recommended. (Previously only the water balance calculations were done at 5 min with the energy balance calculations at 60 min).

4. Surface conductance now depends on the soil moisture under the vegetated surfaces only (rather than the total soil moisture for the whole study area as previously).

5. Albedo of evergreen trees and grass surfaces can now change with leaf area index as was previously possible for deciduous trees only.

6. New suggestions in Troubleshooting section.

7. Edits to the manual.

8. CBL model included.

9. SUEWS has been incorporated into UMEP

Note

Please report issues with the manual on the GitHub page.

Version 2014b (released 8 October 2014)

PDF Manual for v2014b

These affect the run configuration if previously run with older versions of the model:

1. New input of three additional columns in the Meteorological input file (diffusive and direct solar radiation, and wind direction)

2. Change of input variables in InitialConditions.nml file. Note we now refer to CT as ET (ie. Evergreen trees rather than coniferous trees)

3. In GridConnectionsYYYY.txt, the site names should now be without the underscore (e.g Sm and not Sm_)

Other issues:

1. Number of grid areas that can be modelled (for one grid, one year 120; for one grid two years 80)

2. Comment about Time interval of input data

3. Bug fix: Column headers corrected in 5 min file

4. Bug fix: Surface state 60 min file - corrected to give the last 5 min of the hour (rather than cumulating through the hour)

5. Bug fix: units in the Horizontal soil water transfer

6. ErrorHints: More have been added to the problems.txt file.

7. Manual: new section on running the model appropriately

8. Manual: notation table updated

9. Possibility to add snow accumulation and melt: new paper

Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H, and Strachan IB Version 2014: Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities, Geosci. Model Dev. 7, 1691-1711, doi:10.5194/gmd-7-1691-Version 2014.

Note

Please report issues with the manual on the GitHub page.

Version 2014a.1 (released 26 February 2014)

1. Please see the large number of changes made in the Version 2014a release.

2. This is a minor change to address installing the software.

3. Minor updates to the manual

Note

Please report issues with the manual on the GitHub page.

Version 2014a (released 21 February 2014)

1. Bug fix: External irrigation is calculated as combined from automatic and manual irrigation and during precipitation events the manual irrigation is reduced to 60% of the calculated values. In previous version of the model, the irrigation was in all cases taken 60% of the calculated value, but now this has been fixed.

2. In previous versions of the model, irrigation was only allowed on the irrigated grass surface type. Now, irrigation is also allowed on evergreen and deciduous trees/shrubs surfaces. These are not however treated as separate surfaces, but the amount of irrigation is evenly distributed to the whole surface type in the modelled area. The amount of water is calculated using same equation as for grass surface (equation 5 in Järvi et al. Version 2011), and the fraction of irrigated trees/shrubs (relative to the area of tree/shrubs surface) is set in the gis file (See Table 4.11: SSss_YYYY.gis)

3. In the current version of the model, the user is able to adjust the leaf-on and leaf-off lengths in the FunctionalTypes. nml file. In addition, user can choose whether to use temperature dependent functions or combination of temperature and day length (advised to be used at high-latitudes)

4. In the gis-file, there is a new variable Alt that is the area altitude above sea level. If not known exactly use an approximate value.

5. Snow removal profile has been added to the HourlyProfileSSss_YYYY.txt. Not yet used!

6. Model time interval has been changed from minutes to seconds. Preferred interval is 3600 seconds (1 hour)

7. Manual correction: input variable Soil moisture said soil moisture deficit in the manual – word removed

8. Multiple compiled versions of SUEWS released. There are now users in Apple, Linux and Windows environments. So we will now release compiled versions for more operating systems (section 3).

9. There are some changes in the output file columns so please, check the respective table of each used output file.

10. Bug fix: with very small amount of vegetation in an area – impacted Phenology for LUMPS

Note

Please report issues with the manual on the GitHub page.

Version 2013a

1. Radiation selection bug fixed

2. Aerodynamic resistance – when very low - no longer reverts to neutral (which caused a large jump) – but stays low

3. Irrigation day of week fixed

4. New error messages

5. min file – now includes a decimal time column – see Section 5.4 – Table 5.3

Note

Please report issues with the manual on the GitHub page.

Version 2012b

1. Error message generated if all the data are not available for the surface resistance calculations

2. Error message generated if wind data are below zero plane displacement height.

3. All error messages now written to ‘Problem.txt’ rather than embedded in an ErrorFile. Note some errors will be written and the program will continue others will stop the program.

4. Default variables removed (see below). Model will stop if any data are problematic. File should be checked to ensure that reasonable data are being used. If an error occurs when there should not be one let us know as it may mean we have made the limits too restrictive.

Contents no longer used File defaultFcld=0.1 defaultPres=1013 defaultRH=50 defaultT=10 defaultU=3 RunControl.nml

• Just delete lines from file

• Values you had were likely different from these example value shown here

Note

Please report issues with the manual on the GitHub page.

Version 2012a

1. Improved error messages when an error is encountered. Error message will generally be written to the screen and to the file ‘problems.txt’

2. Format of all input files have changed.

3. New excel spreadsheet and R programme to help prepare required data files. (Not required)

4. Format of coef flux (OHM) input files have changed.

   • This allows for clearer identification for users of the coefficients that are actually to be used

   • This requires an additional file with coefficients. These do not need to be adjusted but new coefficients can be added. We would appreciate receiving additional coefficients so they can be included in future releases – Please email Sue.

5. Storage heat flux (OHM) coefficients can be changed by

   • time of year (summer, winter)

   • surface wetness state

6. New files are written: DailyState.txt

   • Provides the status of variables that are updated on a daily or basis or a snapshot at the end of each day.

7. Surface Types

   • Clarification of surface types has been made. See GIS and OHM related files

Note

Please report issues with the manual on the GitHub page.

Version 2011b

1. Storage heat flux (ΔQs) and anthropogenic heat flux (QF) can be set to be 0 W m^-2

2. Calculation of hydraulic conductivity in soil has been improved and HydraulicConduct in SUEWSInput.nml is replaced with name SatHydraulicConduct

3. Following removed from HeaderInput.nml

   • HydraulicConduct

   • GrassFractionIrrigated

   • PavedFractionIrrigated

   • TreeFractionIrrigated

The lower three are now determined from the water use behaviour used in SUEWS

1. Following added to HeaderInput.nml

   • SatHydraulicConduct

   • defaultQf

   • defaultQs

2. If ΔQs and QF are not calculated in the model but are given as an input, the missing data is replaced with the default values.

3. Added to SAHP input file

   • AHDIUPRF – diurnal profile used if EmissionsMethod = 1

Version 2012a this became obsolete OHM file (SSss_YYYY.ohm)

Note

Please report issues with the manual on the GitHub page.

Acknowledgements

Contributors

Name	Affiliation	Contributions	Versions	Remarks
Prof Sue Grimmond	University of Reading, UK; prior: Indiana University, USA, King’s College London, UK, University of British Columbia, Canada	OHM, Evaporation-Interception, Resistances, NARP, irrigation, anthropogenic heat, etc	v2011b – v2019a	Team Leader
Dr Ting Sun	University of Reading, UK	AnOHM; Documentation system; WRF-SUEWS coupling; SuPy (python wrapper of SUEWS)	v2017b – v2019a	Current Lead Developer
Dr Leena Järvi	University of Helsinki, Finland	Snow-related physics; Anthropogenic emission calculation, CO2	v2011b – v2019a	Lead Developer of v2011b – v2014b
Dr Helen Ward	University of Reading, UK	OHM improvement; Resistance calculation; Anthropogenic heat calculation	v2016a - v2017b	Lead Developer of v2016a - v2017
Dr Fredrik Lindberg	Göteborg University, Sweden	UMEP-related work, NARP, ESTM	v2011b – v2019a	Lead Developer of UMEP
Dr Hamidreza Omidvar	University of Reading, UK	WRF-SUEWS coupling; Documentation system	v2018c – v2019a	Major contributor to WRF(v4.0)-SUEWS(v2018c) coupling
Minttu P. Havu	University of Helsinki, Finland	CO2	v2018c – v2019a
Dr Zhenkun Li	Shanghai Climate Centre, China	WRF-SUEWS coupling	v2018b – v2018c	Major contributor to WRF(v3.9)-SUEWS(v2018b) coupling
Yihao Tang	University of Reading, UK	Stability, air temperature	v2018b - v2018c
Dr Shiho Onomura	Göteborg University, Sweden	BLUEWS, ESTM	v2016a
Dr Thomas Loridan	King’s College London, UK	NARP	v2011a
Dr Brian Offerle	Indiana University, USA	ESTM, NARP	v2011a

Dependency Libraries

Note

We gratefully acknowledge the libraries/code that SUEWS uses as dependency and greatly appreciate their developers for the excellent work. Please let us know if any inapproriate use of these code and we will remove/modify the related parts accordingly.

Library	Remarks
datetime-fortran	date and time related processsing
minpack	AnOHM-related sinusoidal curve fitting
Recursive Fortran 95 quicksort routine	netCDF output for QGIS-compliant grid layout
Fortran Strings Module by Dr George Benthien	string processing

Funding

Note

The following grants are acknowledged for their contribution to model development (D) and/or supportive observations (O).

Funder	Project	D , O
NERC	APEx	D
NERC	COSMA NE/S005889/	D
UKRI	GCRF Urban Disaster Risk Hub	D
Newton/Met Office	CSSP-China (AJYG-DX4P1V HRC,AJYF-2GLAMK EUN, others)	D, O
NERC	ClearfLo Clean Air for London NE/H003231/1	O
NERC/Belmont	TRUC NE/L008971/1, G8MUREFU3FP-2201-075	D, O
EPSRC	LoHCool Low carbon climate-responsive Heating and Cooling of Cities EP/N009797/1	D
NERC	Independent Research Fellowship	D
NSF	BCS-0095284, ATM-0710631, BCS-0221105	D, O
EPSRC	Data Assimilation for the REsilient City (DARE) EP/P002331/1	O
Royal Society/Newton	Mobility funding	O
H2020	UrbanFluxes (637519)	D, O
EUf7	BRIDGE (211345)	D, O
EUf7	emBRACE (283201)	D, O
University of Reading	Sue Grimmond	O, D
KCL	Sue Grimmond	O
EPSRC	EP/I00159X/1 EP/I00159X/2 Materials Innovation Hub: Connecting Materials Culture to Materials Science	O
NERC	Field Spectroscopy Facility (FSF) 616.1110 Investigating the Urban Energy Balance of London	O
EUf7	MEGAPOLI 212520	D
NERC	Airborne Remote Sensing Facility & Field Spectroscopy Facility (GB08/19)	O
CFCAS	Environmental Prediction for Canadian Cities	D, O

Note

Please report issues with the manual on the GitHub page.

Notation

λF

Frontal area index

ΔQS

Storage heat flux

BLUEWS

Boundary Layer part of SUEWS

Relation between BLUEWS and SUEWS

CDD

Cooling degree days

GDD

Growing degree days

HDD

Heating degree days

Bldgs

Building surface

CBL

Convective boundary layer

DEM

Digital Elevation Model

DSM

Digital surface model

DTM

Digital Terrain Model

DecTr

Deciduous trees and shrubs

EveTr

Evergreen trees and shrubs

ESTM

Element Surface Temperature Method (Offerle et al.,2005 [OGF2005])

Grass

Grass surface

BSoil

Unmanaged land and/or bare soil

Runoff

The water that drains freely off the impervious surface

SoilStore

The water stored in the underlying soil that infiltrates from the pervious surface

L↓

Incoming longwave radiation

LAI

Leaf area index

LUMPS

Local-scale Urban Meteorological Parameterization Scheme (Loridan et al. 2011 [L2011])

MU

Parameters which must be supplied and must be specific for the site/grid being run.

MD

Parameters which must be supplied and must be specific for the site/grid being run (but default values may be ok if these values are not known specifically for the site).

O

Parameters that are optional, depending on the model settings in RunControl.nml. Set any parameters that are not used/not known to ‘-999’.

L

Codes that are used to link between the input files. These codes are required but their values are completely arbitrary, providing that they link the input files in the correct way. The user should choose these codes, bearing in mind that the codes they match up with in column 1 of the corresponding input file must be unique within that file. Codes must be integers. Note that the codes must match up with column 1 of the corresponding input file, even if those parameters are not used (in which case set all columns except column 1 to ‘-999’ in the corresponding input file), otherwise the model run will fail.

NARP

Net All-wave Radiation Parameterization (Offerle et al. 2003 [O2003], Loridan et al. 2011 [L2011])

OHM

Objective Hysteresis Model (Grimmond et al. 1991 [G91OHM], Grimmond & Oke 1999a [GO99QS], 2002 [GO2002])

Paved

Paved surface

Q^*

Net all-wave radiation

QE

Latent heat flux

QF

Anthropogenic heat flux

QH

Sensible heat flux

SOLWEIG

The solar and longwave environmental irradiance geometry model (Lindberg et al. 2008 [FL2008], Lindberg and Grimmond 2011 [FL2011])

SVF

Sky view factor

θ

Potential temperature

tt

Time step of data

UMEP

Urban Multi-scale Environmental Predictor

Water

Water surface

WATCH

The WATCH project has produced a large number of data sets which should be of considerable use in regional and global studies of climate and water. see WATCH webpage

zi

Convective boundary layer height

Note

Please report issues with the manual on the GitHub page.

References

J11

Järvi L, Grimmond CSB & Christen A (2011) The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver. J. Hydrol. 411, 219-237.

W16

Ward HC, Kotthaus S, Järvi L and Grimmond CSB 2016: Surface Urban Energy and Water Balance Scheme (SUEWS): development and evaluation at two UK sites. Urban Climate. 18, 1-32 doi: 10.1016/j.uclim.2016.05.001

G91

Grimmond CSB & Oke TR (1991) An Evaporation-Interception Model for Urban Areas. Water Resour. Res. 27, 1739-1755.

O2003

Offerle B, Grimmond CSB & Oke TR (2003) Parameterization of Net All-Wave Radiation for Urban Areas. J. Appl. Meteorol. 42, 1157-1173.

L2011

Loridan T, CSB Grimmond, BD Offerle, DT Young, T Smith, L Järvi, F Lindberg (2011) Local-Scale Urban Meteorological Parameterization Scheme (LUMPS): longwave radiation parameterization & seasonality related developments. Journal of Applied Meteorology & Climatology 50, 185-202, doi: 10.1175/2010JAMC2474.1

lucy

Allen L, F Lindberg, CSB Grimmond (2011) Global to city scale model for anthropogenic heat flux, International Journal of Climatology, 31, 1990-2005.

lucy2

Lindberg F, Grimmond CSB, Nithiandamdan Y, Kotthaus S, Allen L (2013) Impact of city changes and weather on anthropogenic heat flux in Europe 1995–2015, Urban Climate,4,1-13 paper

I11

Iamarino M, Beevers S & Grimmond CSB (2011) High-resolution (space, time) anthropogenic heat emissions: London 1970-2025. International J. of Climatology. 32, 1754-1767.

G91OHM

Grimmond CSB, Cleugh HA & Oke TR (1991) An objective urban heat storage model and its comparison with other schemes. Atmos. Env. 25B, 311-174.

GO99QS

Grimmond CSB & Oke TR (1999a) Heat storage in urban areas: Local-scale observations and evaluation of a simple model. J. Appl. Meteorol. 38, 922-940.

GO2002

Grimmond CSB & Oke TR (2002) Turbulent Heat Fluxes in Urban Areas: Observations and a Local-Scale Urban Meteorological Parameterization Scheme (LUMPS) J. Appl. Meteorol. 41, 792-810.

AnOHM17

Sun T, Wang ZH, Oechel W & Grimmond CSB (2017) The Analytical Objective Hysteresis Model (AnOHM v1.0): Methodology to Determine Bulk Storage Heat Flux Coefficients. Geosci. Model Dev. Discuss. doi: 10.5194/gmd-2016-300.

OGF2005

Offerle B, CSB Grimmond, K Fortuniak (2005) Heat storage & anthropogenic heat flux in relation to the energy balance of a central European city center. International J. of Climatology. 25: 1405–1419 doi: 10.1002/joc.1198

G86

Grimmond CSB, Oke TR and Steyn DG (1986) Urban water-balance 1. A model for daily totals. Water Resour Res 22: 1397-1403.

Leena2014

Järvi L, Grimmond CSB, Taka M, Nordbo A, Setälä H & Strachan IB (2014) Development of the Surface Urban Energy and Water balance Scheme (SUEWS) for cold climate cities, Geosci. Model Dev. 7, 1691-1711, doi:10.5194/gmd-7-1691-2014.

CG2001

Cleugh HA & Grimmond CSB (2001) Modelling regional scale surface energy exchanges and CBL growth in a heterogeneous, urban-rural landscape. Bound.-Layer Meteor. 98, 1-31.

Shiho2015

Onomura S, Grimmond CSB, Lindberg F, Holmer B & Thorsson S (2015) Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme Urban Climate,11, 1-23 doi:10.1016/j.uclim.2014.11.001

FL2008

Lindberg F, Holmer B & Thorsson S (2008) SOLWEIG 1.0 – Modelling spatial variations of 3D radiant fluxes and mean radiant temperature in complex urban settings. International Journal of Biometeorology 52, 697–713.

FL2011

Lindberg F & Grimmond C (2011) The influence of vegetation and building morphology on shadow patterns and mean radiant temperature in urban areas: model development and evaluation. Theoretical and Applied Climatology 105:3, 311-323.

Ko17

Kokkonen TV, Grimmond CSB, Räty O, Ward HC, Christen A, Oke TR, Kotthaus S & Järvi L (in review) Sensitivity of Surface Urban Energy and Water Balance Scheme (SUEWS) to downscaling of reanalysis forcing data.

Best2014

Best MJ & Grimmond CSB (2014) Importance of initial state and atmospheric conditions for urban land surface models’ performance. Urban Climate 10: 387-406. doi: 10.1016/j.uclim.2013.10.006.

D74

Dyer AJ (1974) A review of flux-profile relationships. Boundary-Layer Meteorol. 7, 363-372.

VUH85

Van Ulden AP & Holtslag AAM (1985) Estimation of atmospheric boundary layer parameters for boundary layer applications. J. Clim. Appl. Meteorol. 24, 1196-1207.

CN1988

Campbell GS & Norman JM (1998) Introduction to Environmental Biophysics. Springer Science, US.

B71

Businger JA, Wyngaard JC, Izumi Y & Bradley EF (1971) Flux-Profile Relationships in the Atmospheric Surface Layer. J. Atmos. Sci., 28, 181–189.

Ka09

Kawai T, Ridwan MK & Kanda M (2009) Evaluation of the simple urban energy balance model using selected data from 1-yr flux observations at two cities. J. Appl. Meteorol. Clim. 48, 693-715.

VG00

Voogt JA & Grimmond CSB (2000) Modeling surface sensible heat flux using surface radiative temperatures in a simple urban terrain. J. Appl. Meteorol. 39, 1679-1699.

Ka07

Kanda M, Kanega M, Kawai T, Moriwaki R & Sugawara H (2007). Roughness lengths for momentum and heat derived from outdoor urban scale models. J. Appl. Meteorol. Clim. 46, 1067-1079.

GO99

Grimmond CSB & Oke TR (1999) Aerodynamic properties of urban areas derived from analysis of surface form. J. Appl. Meteorol. 38, 1262-1292.

Mc98

MacDonald RW, Griffiths RF & Hall DJ (1998) An improved method for estimation of surface roughness of obstacle arrays. Atmos. Env. 32, 1857-1864.

FN78

Falk J & Niemczynowicz J, (1978) Characteristics of the above ground runoff in sewered catchments, in Urban Storm Drainage, edited by Helliwell PR, Pentech, London

Ha79

Halldin S, Grip H & Perttu K. (1979) Model for energy exchange of a pine forest canopy. In: Halldin S (Ed.), Comparison of Forest Water and Energy Exchange Models. International Society of Ecological Modeling

CW86

Calder IR and Wright IR (1986) Gamma Ray Attenuation Studies of Interception From Sitka Spruce: Some Evidence for an Additional Transport Mechanism. Water Resour. Res., 22(3), 409–417.

Ok87

Oke TR (1987) Boundary Layer Climates. Routledge, London, UK

Br03

Breuer L, Eckhardt K and Frede H-G (2003) Plant parameter values for models in temperate climates. Ecol. Model. 169, 237-293.

Ja76

Jarvis PG (1976) The interpretation of the variations in leaf water potential and stomatal conductance found in canopies in the field. Philos. Trans. R. Soc. London, Ser. B., 273, 593-610.

Au74

Auer AH (1974) The rain versus snow threshold temperatures. Weatherwise, 27, 67.

SV06

Sailor DJ and Vasireddy C (2006) Correcting aggregate energy consumption data account for variability in local weather. Environ. Modell. Softw. 21, 733-738.

Ko14

Konarska J, Lindberg F, Larsson A, Thorsson S and Holmer B (2014) Transmissivity of solar radiation through crowns of single urban trees—application for outdoor thermal comfort modelling. Theor Appl Climatol 117:363–376.

Re90

Reindl DT, Beckman WA and Duffie JA (1990) Diffuse fraction correlation. Sol Energy 45:1–7.

LG2012

Loridan T and Grimmond CSB (2012) Characterization of energy flux partitioning in urban environments: links with surface seasonal properties. J. of Applied Meteorology and Climatology 51,219-241 doi: 10.1175/JAMC-D-11-038.1

H1988

Högström U (1988) Non-dimensional wind and temperature profiles in the atmospheric surface layer: A re-evaluation. Boundary-Layer Meteorol. 42, 55–78.

Kent2017a

Kent CW, CSB Grimmond, J Barlow, D Gatey, S Kotthaus, F Lindberg, CH Halios 2017a: Evaluation of urban local-scale aerodynamic parameters: implications for the vertical profile of wind and source areas Boundary Layer Meteorology 164,183–213 doi: 10.1007/s10546-017-0248-z

Kent2017b

Kent CW, S Grimmond, D Gatey 2017b: Aerodynamic roughness parameters in cities: inclusion of vegetation Journal of Wind Engineering & Industrial Aerodynamics doi: 10.1016/j.jweia.2017.07.016

S2000

Schmid HP, Grimmond CSB, Cropley F, Offerle B, Su H (2000) Measurements of CO2 and energy fluxes over a mixed hardwood forest in the mid-westerm United States. Agricultural and Forest Meteorology. 103, 357-374.

R95

Ruimy A, Jarvis PG, Baldocchi DD, Saugier B (1995) CO2 Fluxes over Plant Canopies and Solar Radiation: A Review. Advances in Ecological Research, 26.

SL04

Sailor DJ, Lu L (2004) A top-down methodology for developing diurnal and seasonal anthropogenic heating profiles for urban areas. Atmospheric Environment. 38, 2737-2648.

B2017

Bellucco V, Marras S, Grimmond CSB, Jarvi L, Sirca C, Spano D (2017) Modelling the biogenic CO2 exchange in urban and non-urban ecosystems through the assessment of light-response curve parameters. Agricultural and Forest Meteorology. 236, 113-122.

FWC2002

Flanagan LB, Wever LA, Carlson PJ (2002) Seasonal and interannual variation in carbon dioxide exchange and carbon balance in a northern temperate grassland. Global Change Biology. 8, 599-615.

J12

Järvi L, Nordbo A, Junninen H, Riikonen A, Moilanen J, Nikinmaa E, Vesala T (2012) Seasonal and annual variation of carbon dioxide surface fluxes in Helsinki, Finland, in 2006-2010. Atmos. Chem. Phys. 12, 8475-8489.

B05

Brutsaert, W. (2005), Hydrology: an introduction, Cambridge Univ Pr, Cambridge.

HF07

Harman IN, Finnigan JJ (2007) A simple uni ed theory for flow in the canopy and roughness sublayer. Boundary-Layer Meteorol 123(2):339–363

HF08

Harman, IN, Finnigan, JJ (2008) Scalar concentration profiles in the canopy and roughness sublayer. Boundary-layer meteorol, 129(3), 323–351.

T19

Theeuwes NE, Ronda RJ, Harman IN, Christen A, Grimmond CSB (2019) Parametrizing Horizontally Averaged Wind and Temperature Profiles in the Urban Roughness Sublayer. Boundary-Layer Meteorol, 173: 321. https://doi.org/10.1007/s10546-019-00472-1

J19

Järvi, L., Havu, M., Ward, H. C., Bellucco, V., McFadden, J. P., Toivonen, T., et al. (2019). Spatial modeling of local‐scale biogenic and anthropogenic carbon dioxide emissions in Helsinki. Journal of Geophysical Research: Atmospheres, 124. https://doi.org/10.1029/2018JD029576