Note

Please report issues with the manual on the GitHub page.

SUEWS: Surface Urban Energy and Water Balance Scheme

Documentation Status
  • How to get SUEWS?

  • How to use SUEWS?

    • For existing users:

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

    Tip

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

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

    • For new users:

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

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

  • How has SUEWS been used?

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

  • How to cite SUEWS?

    Tip

    Visit the repositories below for different citation styles.

    • Software:

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

    • Manual:

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

  • How to support SUEWS?

    1. Cite SUEWS appropriately in your work.

    2. Contribute to the development.

    3. Report issues via the GitHub page.

    4. Provide suggestions and feedback.

Note

Please report issues with the manual on the GitHub page.

Introduction

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

Overview of SUEWS

Overview of SUEWS

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

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

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

The seven surface types considered in SUEWS

The seven surface types considered in SUEWS

Note

Please report issues with the manual on the GitHub page.

Parameterisations and sub-models within SUEWS

Net all-wave radiation, Q*

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

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

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

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

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

Anthropogenic heat flux, QF

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

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

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

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

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

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

Storage heat flux, ΔQS

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

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

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

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

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

Turbulent heat fluxes, QH and QE

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

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

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

Water balance

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

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

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

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

  • Soil moisture can be calculated by the model.

  • Runoff is permitted:

    • between surface types within each model grid

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

    • to deep soil

    • to pipes.

Snowmelt

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

Convective boundary layer

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

Surface Diagnostics

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

  • T2: air temperature at 2 m agl

  • Q2: air specific humidity at 2 m agl

  • U10: wind speed at 10 m agl

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

Wind, Temperature and Humidity Profiles in the Roughness Sublayer

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

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

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

Here nz = 30.

Note

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

Note

Please report issues with the manual on the GitHub page.

Preparing to run the model

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

Preparatory reading

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

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

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

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

See other publications with example applications

Decide what type of model run you are interested in

Available in this release

LUMPS

Yes – not standalone

SUEWS at a point or for an individual area

Yes

SUEWS for multiple grids or areas

Yes

SUEWS with Boundary Layer (BL)

Yes

SUEWS with snow

Yes

SUEWS with SOLWEIG

No

SUEWS with SOLWEIG and BL

No

Download the program and example data files

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

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

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

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

Filename

Description

Input/output

SSss_data.txt

Meteorological input

Input file (60-min)

SSss_YYYY_data_5.txt

Meteorological input

Input file (5-min)

InitialConditionsSSss

Initial conditions

Input - _YYYY.nml(+) file

SUEWS_SiteInfo_SSss.x

Spreadsheet

Input lsm containing all other input information

RunControl.nml

Sets model run

Input (located in options main directory)

SS_Filechoices.txt

Summary of model run

Output options

SSss_YYYY_5.txt

(Optional) 5-min

Output resolution output file

SSss_YYYY_60.txt

60-min resolution

Output output file

SSss_DailyState.txt

Daily state variables

Output (all years in one file)

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

Run the model for example data

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

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

Please see Troubleshooting if you have problems running the model.

Preparation of data

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

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

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

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

  4. Information about the characteristics of the surface, including land cover, heights of buildings and trees, radiative characteristics (e.g. albedo, emissivity), drainage characteristics, soil characteristics, snow characteristics, phenological characteristics (e.g. seasonal cycle of LAI).

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

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

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

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

  • Initial soil moisture conditions [Best2014]

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

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

  • Snow clearing (if running the snow option)

  • Surface conductance parameterisation [J11] [W16]

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

Preparation of site characteristics and model parameters

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

Land cover

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

Classification

Surface type

File where characteristics are specified

Non-vegetated

Paved surfaces

SUEWS_NonVeg.txt

Building

SUEWS_NonVeg.txt

Bare soil

SUEWS_NonVeg.txt

Vegetation

Evergreen trees

SUEWS_Veg.txt

Deciduous trees

SUEWS_Veg.txt

Grass

SUEWS_Veg.txt

Water

Water

SUEWS_Water.txt

Snow

Snow

SUEWS_Snow.txt

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

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

Anthropogenic heat flux (QF)

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

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

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

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

Other information

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

Data Entry

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

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

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

  3. Use UMEP.

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

If there is a problem

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

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

Note that in all txt files:

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

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

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

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

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

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

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

Preparation of the RunControl file

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

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

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

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

FileOutputPath = “C:\FolderName\SUEWSOutput\”

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

C:\FolderName\SUEWSOutput\SSss_YYYY_TT.txt

Note

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

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

Preparation of the Meteorological forcing data

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

Preparation of the InitialConditions file

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

Run the model for your site

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

Please see Troubleshooting if you have problems running the model.

Analyse the output

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

Characteristic

Things to check

Leaf area index

Does the phenology look appropriate?
  • what does the seasonal cycle of leaf area index (LAI) look like?

  • Are the leaves on the trees at approximately the right time of the year?

Kdown

Is the timing of diurnal cycles correct for the incoming solar radiation?
  • Although Kdown is a required input, it is also included in the output file. It is a good idea to check that the timing of Kdown in the output file is appropriate, as problems can indicate errors with the timestamp, incorrect time settings or problems with the disaggregation. In particular, make sure the sign of the longitude is specified correctly in SUEWS_SiteSelect.txt.

  • Checking solar angles (zenith and azimuth) can also be a useful check that the timing is correct.

Albedo

Is the bulk albedo correct?
  • This is critical because a small error has an impact on all the fluxes (energy and hydrology).

  • If you have measurements of outgoing shortwave radiation compare these with the modelled values.

  • How do the values compare to literature values for your area?

Summary of files

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

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

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

Get in contact

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

  1. Report issues on our GitHub page.

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

Note

Please report issues with the manual on the GitHub page.

Input files

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

Note

Please report issues with the manual on the GitHub page.

RunControl.nml

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

A sample file of RunControl.nml looks like

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

Note

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

  • The file is not case-sensitive.

  • The parameters and variables can appear in any order.

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

Note

Please report issues with the manual on the GitHub page.

Scheme options

CBLuse

Warning

Not available in this version.

Requirement

Required

Description

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

Configuration

Value

Comments

0

CBL model not used. SUEWS and LUMPS use temperature and humidity provided in the meteorological forcing file.

1

CBL model is used to calculate temperature and humidity used in SUEWS and LUMPS.

SnowUse
Requirement

Required

Description

Determines whether the snow part of the model runs.

Configuration

Value

Comments

0

Snow calculations are not performed.

1

Snow calculations are performed.

NetRadiationMethod
Requirement

Required

Description

Determines method for calculation of radiation fluxes.

Configuration

Value

Comments

0

Uses observed values of Q* supplied in meteorological forcing file.

1

Q* modelled with L↓ observations supplied in meteorological forcing file. Zenith angle not accounted for in albedo calculation.

2

Q* modelled with L↓ modelled using cloud cover fraction supplied in meteorological forcing file (Loridan et al. 2011 [L2011]). Zenith angle not accounted for in albedo calculation.

3

Q* modelled with L↓ modelled using air temperature and relative humidity supplied in meteorological forcing file (Loridan et al. 2011 [L2011]). Zenith angle not accounted for in albedo calculation.

100

Q* modelled with L↓ observations supplied in meteorological forcing file. Zenith angle accounted for in albedo calculation. SSss_YYYY_NARPOut.txt file produced. Not recommended in this version.

200

Q* modelled with L↓ modelled using cloud cover fraction supplied in meteorological forcing file (Loridan et al. 2011 [L2011]). Zenith angle accounted for in albedo calculation. SSss_YYYY_NARPOut.txt file produced. Not recommended in this version.

300

Q* modelled with L↓ modelled using air temperature and relative humidity supplied in meteorological forcing file (Loridan et al. 2011 [L2011]). Zenith angle accounted for in albedo calculation. SSss_YYYY_NARPOut.txt file produced. Not recommended in this version.

EmissionsMethod
Requirement

Required

Description

Determines method for QF calculation.

Configuration

Value

Comments

0

Uses values provided in the meteorological forcing file (SSss_YYYY_data_tt.txt). If you do not want to include QF to the calculation of surface energy balance, you should set values in the meteorological forcing file to zero to prevent calculation of QF. UMEP provides two methods to calculate QF LQF which is simpler GQF which is more complete but requires more data inputs

1

Not recommended in this version. Calculated according to Loridan et al. (2011) [L2011] using coefficients specified in SUEWS_AnthropogenicEmission.txt. Modelled values will be used even if QF is provided in the meteorological forcing file.

2

Recommended in this version. Calculated according to Järvi et al. (2011) [J11] using coefficients specified in SUEWS_AnthropogenicEmission.txt and diurnal patterns specified in SUEWS_Profiles.txt. Modelled values will be used even if QF is provided in the meteorological forcing file.

3

Updated Loridan et al. (2011) [L2011] method using daily (not instantaneous) air temperature (HDD(id-1,3)) using coefficients specified in SUEWS_AnthropogenicEmission.txt. Modelled values will be used even if QF is provided in the meteorological forcing file.

StorageHeatMethod
Requirement

Required

Description

Determines method for calculating storage heat flux ΔQS.

Configuration

Value

Comments

1

ΔQS modelled using the objective hysteresis model (OHM) [G91OHM] using parameters specified for each surface type.

2

Uses observed values of ΔQS supplied in meteorological forcing file.

3

ΔQS modelled using AnOHM. Not recommended in this version.

4

ΔQS modelled using the Element Surface Temperature Method (ESTM) (Offerle et al. 2005 [OGF2005] ). Not recommended in this version.

OHMIncQF
Requirement

Required

Description

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

Configuration

Value

Comments

0

ΔQS modelled Q* only.

1

ΔQS modelled using Q*+QF.

StabilityMethod
Requirement

Required

Description

Defines which atmospheric stability functions are used.

Configuration

Value

Comments

0

Not used.

1

Not used.

2

  • Momentum:

    • unstable: Dyer (1974) [D74] modified by Högstrom (1988) [H1988]

    • stable: Van Ulden and Holtslag (1985) [VUH85]

  • Heat: Dyer (1974) [D74] modified by Högstrom (1988) [H1988]

Not recommended in this version.

3

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

  • Heat

Recommended in this version.

4

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

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

Not recommended in this version.

RoughLenHeatMethod
Requirement

Required

Description

Determines method for calculating roughness length for heat.

Configuration

Value

Comments

1

Uses value of 0.1z0m.

2

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

Recommended in this version.

3

Calculated according to Voogt and Grimmond (2000) [VG00].

4

Calculated according to Kanda et al. (2007) [Ka07].

RoughLenMomMethod
Requirement

Required

Description

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

Configuration

Value

Comments

1

Values specified in SUEWS_SiteSelect.txt are used.

Tip

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

2

z0m and zd are calculated using ‘rule of thumb’ (Grimmond and Oke 1999 [GO99]) using mean building and tree height specified in SUEWS_SiteSelect.txt. z0m and zd are adjusted with time to account for seasonal variation in porosity of deciduous trees.

3

z0m and zd are calculated based on the MacDonald et al. (1998) [Mc98] method using mean building and tree heights, plan area fraction and frontal areal index specified in SUEWS_SiteSelect.txt. z0m and zd are adjusted with time to account for seasonal variation in porosity of deciduous trees.

SMDMethod
Requirement

Required

Description

Determines method for calculating soil moisture deficit (SMD).

Configuration

Value

Comments

0

SMD modelled using parameters specified in SUEWS_Soil.txt. Recommended in this version.

1

Observed SM provided in the meteorological forcing file is used. Data are provided as volumetric soil moisture content. Metadata must be provided in SUEWS_Soil.txt. Not available in this version.

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. Not available in this version.

WaterUseMethod
Requirement

Required

Description

Defines how external water use is calculated.

Configuration

Value

Comments

0

External water use modelled using parameters specified in SUEWS_Irrigation.txt.

1

Observations of external water use provided in the meteorological forcing file are used.

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

SUEWS Site Information

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_AnthropogenicEmission.txt

Note

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

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

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

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

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

BaseTHDD

MU

Base temperature for heating degree days [°C]

3

QF_A_WD

MU O

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

4

QF_B_WD

MU O

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

5

QF_C_WD

MU O

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

6

QF_A_WE

MU O

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

7

QF_B_WE

MU O

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

8

QF_C_WE

MU O

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

9

AHMin_WD

MU O

Minimum QF on weekdays [W m-2]

10

AHMin_WE

MU O

Minimum QF on weekends [W m-2]

11

AHSlope_Heating_WD

MU O

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

12

AHSlope_Heating_WE

MU O

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

13

AHSlope_Cooling_WD

MU O

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

14

AHSlope_Cooling_WE

MU O

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

15

TCritic_Heating_WD

MU O

Critical heating temperature on weekdays [°C]

16

TCritic_Heating_WE

MU O

Critical heating temperature on weekends [°C]

17

TCritic_Cooling_WD

MU O

Critical cooling temperature on weekdays [°C]

18

TCritic_Cooling_WE

MU O

Critical cooling temperature on weekends [°C]

19

EnergyUseProfWD

MU O

Code linking to EnergyUseProfWD in SUEWS_Profiles.txt.

20

EnergyUseProfWE

MU O

Code linking to EnergyUseProfWE in SUEWS_Profiles.txt.

21

ActivityProfWD

MU O

Code linking to ActivityProfWD in SUEWS_Profiles.txt.

22

ActivityProfWE

MU O

Code linking to ActivityProfWE in SUEWS_Profiles.txt.

23

TraffProfWD

MU O

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

24

TraffProfWE

MU O

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

25

PopProfWD

MU O

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

26

PopProfWE

MU O

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

27

MinQFMetab

MU O

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

28

MaxQFMetab

MU O

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

29

MinFCMetab

MU O

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

30

MaxFCMetab

MU O

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

31

FrPDDwe

MU O

Fraction of weekend population to weekday population. [-]

32

FrFossilFuel_Heat

MU O

Fraction of fossil fuels used for building heating [-]

33

FrFossilFuel_NonHeat

MU O

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

34

EF_umolCO2perJ

MU O

Emission factor for fuels used for building heating.

35

EnEF_v_Jkm

MU O

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

36

FcEF_v_kgkmWD

MU O

CO2 emission factor for weekdays [kg km-1]

37

FcEF_v_kgkmWE

MU O

CO2 emission factor for weekends [kg km-1]

38

CO2PointSource

MU O

CO2 emission factor [kg km-1]

39

TrafficUnits

MU O

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

An example SUEWS_AnthropogenicEmission.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_BiogenCO2.txt

Caution

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

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

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

alpha

MU O

The mean apparent ecosystem quantum. Represents the initial slope of the light-response curve.

3

beta

MU O

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

4

theta

MU O

The convexity of the curve at light saturation.

5

alpha_enh

MU O

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

6

beta_enh

MU O

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

7

resp_a

MU O

Respiration coefficient a.

8

resp_b

MU O

Respiration coefficient b - related to air temperature dependency.

9

min_respi

MU O

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

An example SUEWS_BiogenCO2.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Conductance.txt

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

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

G1

MD

Related to maximum surface conductance [mm s-1]

3

G2

MD

Related to Kdown dependence [W m-2]

4

G3

MD

Related to VPD dependence [units depend on gsModel]

5

G4

MD

Related to VPD dependence [units depend on gsModel]

6

G5

MD

Related to temperature dependence [°C]

7

G6

MD

Related to soil moisture dependence [mm-1]

8

TH

MD

Upper air temperature limit [°C]

9

TL

MD

Lower air temperature limit [°C]

10

S1

MD

A parameter related to soil moisture dependence [-]

11

S2

MD

A parameter related to soil moisture dependence [mm]

12

Kmax

MD

Maximum incoming shortwave radiation [W m-2]

13

gsModel

MD

Formulation choice for conductance calculation.

An example SUEWS_Conductance.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Irrigation.txt

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

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

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

Ie_start

MU

Day when irrigation starts [DOY]

3

Ie_end

MU

Day when irrigation ends [DOY]

4

InternalWaterUse

MU

Internal water use [mm h-1]

5

Faut

MU

Fraction of irrigated area that is irrigated using automated systems

6

Ie_a1

MD

Coefficient for automatic irrigation model [mm d-1 ]

7

Ie_a2

MD

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

8

Ie_a3

MD

Coefficient for automatic irrigation model [mm d-2 ]

9

Ie_m1

MD

Coefficient for manual irrigation model [mm d-1 ]

10

Ie_m2

MD

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

11

Ie_m3

MD

Coefficient for manual irrigation model [mm d-2 ]

12

DayWat(1)

MU

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

13

DayWat(2)

MU

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

14

DayWat(3)

MU

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

15

DayWat(4)

MU

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

16

DayWat(5)

MU

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

17

DayWat(6)

MU

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

18

DayWat(7)

MU

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

19

DayWatPer(1)

MU

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

20

DayWatPer(2)

MU

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

21

DayWatPer(3)

MU

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

22

DayWatPer(4)

MU

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

23

DayWatPer(5)

MU

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

24

DayWatPer(6)

MU

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

25

DayWatPer(7)

MU

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

An example SUEWS_Irrigation.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_NonVeg.txt

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

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

AlbedoMin

MU

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

3

AlbedoMax

MU

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

4

Emissivity

MU

Effective surface emissivity.

5

StorageMin

MD

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

6

StorageMax

MD

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

7

WetThreshold

MD

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

8

StateLimit

MD

Upper limit to the surface state. [mm]

9

DrainageEq

MD

Calculation choice for Drainage equation

10

DrainageCoef1

MD

Coefficient D0 [mm h-1] used in DrainageEq

11

DrainageCoef2

MD

Coefficient b [-] used in DrainageEq

12

SoilTypeCode

L

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

13

SnowLimPatch

O

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

14

SnowLimRemove

O

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

15

OHMCode_SummerWet

L

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

16

OHMCode_SummerDry

L

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

17

OHMCode_WinterWet

L

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

18

OHMCode_WinterDry

L

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

19

OHMThresh_SW

MD

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

20

OHMThresh_WD

MD

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

21

ESTMCode

L

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

22

AnOHM_Cp

MU

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

23

AnOHM_Kk

MU

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

24

AnOHM_Ch

MU

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

An example SUEWS_NonVeg.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_OHMCoefficients.txt

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

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

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

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

  • Coefficients can be changed depending on:
    1. surface wetness state (wet/dry) based on the calculated surface wetness state and soil moisture.

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

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

Note

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

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

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

a1

MU

Coefficient for Q* term [-]

3

a2

MU

Coefficient for dQ*/dt term [h]

4

a3

MU

Constant term [W m-2]

An example SUEWS_OHMCoefficients.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Profiles.txt

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

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

Profiles are specified for the following

  • Anthropogenic heat flux (weekday and weekend)

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

  • Snow removal (weekday and weekend)

  • Human activity (weekday and weekend).

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

2-25

MU

Multiplier for each hour of the day [-] for energy and water use. For SnowClearing, set those hours to 1 when snow removal from paved and roof surface is allowed (0 otherwise) if the snow removal limits set in the SUEWS_NonVeg.txt (SnowLimR emove column) are exceeded.

An example SUEWS_Profiles.txt can be found below:

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

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

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

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

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


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

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

-9
-9

Note

Please report issues with the manual on the GitHub page.

SUEWS_SiteSelect.txt

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

No.

Column Name

Use

Description

1

Grid

MU

a unique number to represent grid

2

Year

MU

Year [YYYY]

3

StartDLS

MU

Start of the day light savings [DOY]

4

EndDLS

MU

End of the day light savings [DOY]

5

lat

MU

Latitude [deg].

6

lng

MU

longitude [deg]

7

Timezone

MU

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

8

SurfaceArea

MU

Area of the grid [ha].

9

Alt

MU

Altitude of grids [m].

10

z

MU

Measurement height [m].

11

id

MD

Day of year [DOY]

12

ih

MD

Hour [H]

13

imin

MD

Minute [M]

14

Fr_Paved

MU

Surface cover fraction of Paved surfaces [-]

15

Fr_Bldgs

MU

Surface cover fraction of buildings [-]

16

Fr_EveTr

MU

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

17

Fr_DecTr

MU

Surface cover fraction of deciduous trees and shrubs [-]

18

Fr_Grass

MU

Surface cover fraction of Grass [-]

19

Fr_Bsoil

MU

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

20

Fr_Water

MU

Surface cover fraction of open water [-]

21

IrrFr_EveTr

MU

Fraction of evergreen trees that are irrigated [-]

22

IrrFr_DecTr

MU

Fraction of deciduous trees that are irrigated [-]

23

IrrFr_Grass

MU

Fraction of Grass that is irrigated [-]

24

H_Bldgs

MU

Mean building height [m]

25

H_EveTr

MU

Mean height of evergreen trees [m]

26

H_DecTr

MU

Mean height of deciduous trees [m]

27

z0

O

Roughness length for momentum [m]

28

zd

O

Zero-plane displacement [m]

29

FAI_Bldgs

O

Frontal area index for buildings [-]

30

FAI_EveTr

O

Frontal area index for evergreen trees [-]

31

FAI_DecTr

O

Frontal area index for deciduous trees [-]

32

PopDensDay

O

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

33

PopDensNight

O

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

34

TrafficRate_WD

O

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

35

TrafficRate_WE

O

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

36

QF0_BEU_WD

O

Building energy use [W m-2]

37

QF0_BEU_WE

O

Building energy use [W m-2]

38

Code_Paved

L

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

39

Code_Bldgs

L

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

40

Code_EveTr

L

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

41

Code_DecTr

L

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

42

Code_Grass

L

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

43

Code_BSoil

L

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

44

Code_Water

L

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

45

LUMPS_DrRate

MD

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

46

LUMPS_Cover

MD

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

47

LUMPS_MaxRes

MD

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

48

NARP_Trans

MD

Atmospheric transmissivity for NARP [-]

49

CondCode

L

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

50

SnowCode

L

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

51

SnowClearingProfWD

L

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

52

SnowClearingProfWE

L

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

53

AnthropogenicCode

L

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

54

IrrigationCode

L

Code for modelling irrigation linking to Code of SUEWS_Irrigation.txt

55

WaterUseProfManuWD

L

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

56

WaterUseProfManuWE

L

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

57

WaterUseProfAutoWD

L

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

58

WaterUseProfAutoWE

L

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

59

FlowChange

MD

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

60

RunoffToWater

MD MU

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

61

PipeCapacity

MD MU

Storage capacity of pipes [mm]

62

GridConnection1of8

MD MU

Number of the 1st grid where water can flow to

63

Fraction1of8

MD MU

Fraction of water that can flow to GridConnection1of8 [-]

64

GridConnection2of8

MD MU

Number of the 2nd grid where water can flow to

65

Fraction2of8

MD MU

Fraction of water that can flow to GridConnection2of8 [-]

66

GridConnection3of8

MD MU

Number of the 3rd grid where water can flow to

67

Fraction3of8

MD MU

Fraction of water that can flow to GridConnection3of8 [-]

68

GridConnection4of8

MD MU

Number of the 4th grid where water can flow to

69

Fraction4of8

MD MU

Fraction of water that can flow to GridConnection4of8 [-]

70

GridConnection5of8

MD MU

Number of the 5th grid where water can flow to

71

Fraction5of8

MD MU

Fraction of water that can flow to GridConnection5of8 [-]

72

GridConnection6of8

MD MU

Number of the 6th grid where water can flow to

73

Fraction6of8

MD MU

Fraction of water that can flow to GridConnection6of8 [-]

74

GridConnection7of8

MD MU

Number of the 7th grid where water can flow to

75

Fraction7of8

MD MU

Fraction of water that can flow to GridConnection7of8 [-]

76

GridConnection8of8

MD MU

Number of the 8th grid where water can flow to

77

Fraction8of8

MD MU

Fraction of water that can flow to GridConnection8of8 [-]

78

WithinGridPavedCode

L

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

79

WithinGridBldgsCode

L

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

80

WithinGridEveTrCode

L

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

81

WithinGridDecTrCode

L

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

82

WithinGridGrassCode

L

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

83

WithinGridBSoilCode

L

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

84

WithinGridWaterCode

L

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

85

AreaWall

MU

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

86

Fr_ESTMClass_Paved1

MU

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

87

Fr_ESTMClass_Paved2

MU

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

88

Fr_ESTMClass_Paved3

MU

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

89

Code_ESTMClass_Paved1

L

Code linking to SUEWS_ESTMCoefficients.txt

90

Code_ESTMClass_Paved2

L

Code linking to SUEWS_ESTMCoefficients.txt

91

Code_ESTMClass_Paved3

L

Code linking to SUEWS_ESTMCoefficients.txt

92

Fr_ESTMClass_Bldgs1

MU

Surface cover fraction of building class 1 used in ESTM calculations

93

Fr_ESTMClass_Bldgs2

MU

Surface cover fraction of building class 2 used in ESTM calculations

94

Fr_ESTMClass_Bldgs3

MU

Surface cover fraction of building class 3 used in ESTM calculations

95

Fr_ESTMClass_Bldgs4

MU

Surface cover fraction of building class 4 used in ESTM calculations

96

Fr_ESTMClass_Bldgs5

MU

Surface cover fraction of building class 5 used in ESTM calculations

97

Code_ESTMClass_Bldgs1

L

Code linking to SUEWS_ESTMCoefficients.txt

98

Code_ESTMClass_Bldgs2

L

Code linking to SUEWS_ESTMCoefficients.txt

99

Code_ESTMClass_Bldgs3

L

Code linking to SUEWS_ESTMCoefficients.txt

100

Code_ESTMClass_Bldgs4

L

Code linking to SUEWS_ESTMCoefficients.txt

101

Code_ESTMClass_Bldgs5

L

Code linking to SUEWS_ESTMCoefficients.txt

Attention

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

  • In this file the column order is important.

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

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

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

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

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

Tip

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

Day Light Savings (DLS)

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

Tip

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

  • For northern hemisphere, use: 180 181

  • For southern hemisphere, use:  365 1

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

Year

start of daylight savings

end of daylight savings

2008

170

240

2009

172

242

Grid Connections (water flow between grids)

Caution

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

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

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

Example grid connections showing water flow between grids.

Note

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

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

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

An example SUEWS_SiteSelect.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Snow.txt

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

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

RadMeltFactor

MU

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

3

TempMeltFactor

MU

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

4

AlbedoMin

MU

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

5

AlbedoMax

MU

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

6

Emissivity

MU

Effective surface emissivity.

7

tau_a

MD

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

8

tau_f

MD

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

9

PrecipLimAlb

MD

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

10

SnowDensMin

MD

Fresh snow density [kg m-3]

11

SnowDensMax

MD

Maximum snow density [kg m-3]

12

tau_r

MD

Time constant for snow density ageing [-]

13

CRWMin

MD

Minimum water holding capacity of snow [mm]

14

CRWMax

MD

Maximum water holding capacity of snow [mm]

15

PrecipLimSnow

MD

Temperature limit when precipitation falls as snow [°C]

16

OHMCode_SummerWet

L

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

17

OHMCode_SummerDry

L

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

18

OHMCode_WinterWet

L

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

19

OHMCode_WinterDry

L

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

20

OHMThresh_SW

MD

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

21

OHMThresh_WD

MD

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

22

ESTMCode

L

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

23

AnOHM_Cp

MU

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

24

AnOHM_Kk

MU

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

25

AnOHM_Ch

MU

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

An example SUEWS_Snow.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Soil.txt

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

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

Caution

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

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

SoilDepth

MD

Depth of soil beneath the surface [mm]

3

SoilStoreCap

MD

Limit value for SoilDepth [mm]

4

SatHydraulicCond

MD

Hydraulic conductivity for saturated soil [mm s-1]

5

SoilDensity

MD

Soil density [kg m-3]

6

InfiltrationRate

O

Infiltration rate.

7

OBS_SMDepth

O

The depth of soil moisture measurements. [mm]

8

OBS_SMCap

O

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

9

OBS_SoilNotRocks

O

Fraction of soil without rocks. [-]

An example SUEWS_Soil.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Veg.txt

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

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

AlbedoMin

MU

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

3

AlbedoMax

MU

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

4

Emissivity

MU

Effective surface emissivity.

5

StorageMin

MD

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

6

StorageMax

MD

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

7

WetThreshold

MD

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

8

StateLimit

MD

Upper limit to the surface state. [mm]

9

DrainageEq

MD

Calculation choice for Drainage equation

10

DrainageCoef1

MD

Coefficient D0 [mm h-1] used in DrainageEq

11

DrainageCoef2

MD

Coefficient b [-] used in DrainageEq

12

SoilTypeCode

L

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

13

SnowLimPatch

O

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

14

BaseT

MU

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

15

BaseTe

MU

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

16

GDDFull

MU

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

17

SDDFull

MU

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

18

LAIMin

MD

leaf-off wintertime value

19

LAIMax

MD

full leaf-on summertime value

20

PorosityMin

MD

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

21

PorosityMax

MD

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

22

MaxConductance

MD

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

23

LAIEq

MD

LAI calculation choice.

24

LeafGrowthPower1

MD

a parameter required by LAI calculation in LAIEq

25

LeafGrowthPower2

MD

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

26

LeafOffPower1

MD

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

27

LeafOffPower2

MD

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

28

OHMCode_SummerWet

L

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

29

OHMCode_SummerDry

L

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

30

OHMCode_WinterWet

L

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

31

OHMCode_WinterDry

L

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

32

OHMThresh_SW

MD

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

33

OHMThresh_WD

MD

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

34

ESTMCode

L

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

35

AnOHM_Cp

MU

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

36

AnOHM_Kk

MU

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

37

AnOHM_Ch

MU

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

38

BiogenCO2Code

MU

Code linking to the Code column in SUEWS_BiogenCO2.txt.

An example SUEWS_Veg.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_Water.txt

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

No.

Column Name

Use

Description

1

Code

L

Code linking to a corresponding look-up table.

2

AlbedoMin

MU

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

3

AlbedoMax

MU

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

4

Emissivity

MU

Effective surface emissivity.

5

StorageMin

MD

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

6

StorageMax

MD

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

7

WetThreshold

MD

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

8

StateLimit

MU

Upper limit to the surface state. [mm]

9

WaterDepth

MU

Water depth [mm].

10

DrainageEq

MD

Calculation choice for Drainage equation

11

DrainageCoef1

MD

Coefficient D0 [mm h-1] used in DrainageEq

12

DrainageCoef2

MD

Coefficient b [-] used in DrainageEq

13

OHMCode_SummerWet

L

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

14

OHMCode_SummerDry

L

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

15

OHMCode_WinterWet

L

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

16

OHMCode_WinterDry

L

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

17

OHMThresh_SW

MD

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

18

OHMThresh_WD

MD

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

19

ESTMCode

L

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

20

AnOHM_Cp

MU

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

21

AnOHM_Kk

MU

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

22

AnOHM_Ch

MU

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

An example SUEWS_Water.txt can be found below:

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

Note

Please report issues with the manual on the GitHub page.

SUEWS_WithinGridWaterDist.txt

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

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

Note

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

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

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

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

In the table below, for example,

  • All flow from paved surfaces goes to runoff;

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

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

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

No.

Column Name

Use

Description

1

ToPaved

MU

Fraction of water going to Paved

2

ToBldgs

MU

Fraction of water going to Bldgs

3

ToEveTr

MU

Fraction of water going to EveTr

4

ToDecTr

MU

Fraction of water going to DecTr

5

ToGrass

MU

Fraction of water going to Grass

6

ToBSoil

MU

Fraction of water going to BSoil

7

ToWater

MU

Fraction of water going to Water

8

ToRunoff

MU

Fraction of water going to Runoff

9

ToSoilStore

MU

Fraction of water going to SoilStore

An example SUEWS_WithinGridWaterDist.txt can be found below:

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

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

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

Note

Please report issues with the manual on the GitHub page.

Input Options

a1
Description

Coefficient for Q* term [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_OHMCoefficients.txt

MU

Coefficient for Q* term [-]

a2
Description

Coefficient for dQ*/dt term [h]

Configuration

Referencing Table

Requirement

Comment

SUEWS_OHMCoefficients.txt

MU

Coefficient for dQ*/dt term [h]

a3
Description

Constant term [W m-2]

Configuration

Referencing Table

Requirement

Comment

SUEWS_OHMCoefficients.txt

MU

Constant term [W m-2]

ActivityProfWD
Description

Code linking to ActivityProfWD in SUEWS_Profiles.txt.

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

L

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

Not used in this version.

ActivityProfWE
Description

Code linking to ActivityProfWE in SUEWS_Profiles.txt.

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

L

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

Not used in this version.

AHMin_WD
Description

Minimum QF on weekdays [W m-2]

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 1

AHMin_WE
Description

Minimum QF on weekends [W m-2]

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 1

AHSlope_Heating_WD
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 1

AHSlope_Heating_WE
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 1

AHSlope_Cooling_WD
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 1

AHSlope_Cooling_WE
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 1

AlbedoMax
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MU

Effective surface albedo (middle of the day value) for summertime. View factors should be taken into account.

SUEWS_Veg.txt

MU

Example values [-]

SUEWS_Water.txt

MU

Example values [-]

SUEWS_Snow.txt

MU

Example values [-]

AlbedoMin
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MU

Not currently used for non-vegetated surfaces – set the same as AlbedoMax.

SUEWS_Veg.txt

MU

Example values [-]

SUEWS_Water.txt

MU

Not currently used for water surface - set same as AlbedoMax.

SUEWS_Snow.txt

MU

Example values [-]

alpha
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

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

Alt
Description

Altitude of grids [m].

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Used for both the radiation and water flow between grids. Not available in this version.

AnOHM_Ch
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MU

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

SUEWS_Veg.txt

MU

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

SUEWS_Water.txt

MU

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

SUEWS_Snow.txt

MU

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

AnOHM_Cp
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MU

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

SUEWS_Veg.txt

MU

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

SUEWS_Water.txt

MU

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

SUEWS_Snow.txt

MU

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

AnOHM_Kk
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MU

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

SUEWS_Veg.txt

MU

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

SUEWS_Water.txt

MU

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

SUEWS_Snow.txt

MU

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

AnthropogenicCode
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

Value of integer is arbitrary but must match code specified in column 1 of SUEWS_AnthropogenicEmission.txt.

AreaWall
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

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

BaseT
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MU

See section 2.2 Järvi et al. (2011); Appendix A Järvi et al. (2014). Example values: 5 for EveTr Järvi et al. (2011) [J11]

BaseTe
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MU

See section 2.2 Järvi et al. (2011) [J11] ; Appendix A Järvi et al. (2014) [Leena2014] . Example values: 10 EveTr Järvi et al. (2011) [J11]

BaseTHDD
Description

Base temperature for heating degree days [°C]

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU

Base temperature for heating degree days [°C] e.g. Sailor and Vasireddy (2006) [SV06]

beta
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

Example values:

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

theta
Description

The convexity of the curve at light saturation.

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

Example value: EmissionsMethod = 21, 22, 23, 24, 25, 26: 0.723 Bellucco et al. (2017) [B2017] EmissionsMethod = 31, 32, 33, 34, 35, 36: 0.96 Bellucco et al. (2017) [B2017]

alpha_enh
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

Example value: 0.016 Bellucco et al. (2017) [B2017]

beta_enh
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

Example values: 33.454 Bellucco et al. (2017) [B2017]

resp_a
Description

Respiration coefficient a.

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

Example values: 1.08 Schmid et al. (2000) [S2000], 3.229 Järvi et al. (2012) [J12]

resp_b
Description

Respiration coefficient b - related to air temperature dependency.

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

Example values: 0.0064 Schmid et al. (2000) [S2000], 0.0329 Järvi et al. (2012) [J12].

min_respi
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

Example values: 0.6 estimate from Hyytiälä forest site.

BiogenCO2Code
Description

Code linking to the Code column in SUEWS_BiogenCO2.txt.

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

L

Code linking to the Code column in SUEWS_BiogenCO2.txt.

QF0_BEU_WD
Description

Building energy use [W m-2]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

Weekday building energy use [W m-2] Can be used for CO2 flux calculation.

QF0_BEU_WE
Description

Building energy use [W m-2]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

Can be used for CO2 flux calculation. set to -999 Not used in this version.

CO2PointSource
Description

CO2 emission factor [kg km-1]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

CO2 emission factor [kg km-1]

Code
Description

Code linking to a corresponding look-up table.

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

L

Code linking to SUEWS_SiteSelect.txt for paved surfaces (Code_Paved), buildings (Code_Bldgs) and bare soil surfaces (Code_BSoil). Value of integer is arbitrary but must match codes specified in SUEWS_SiteSelect.txt.

SUEWS_Veg.txt

L

Code linking to SUEWS_SiteSelect.txt for evergreen trees and shrubs (Code_EveTr), deciduous trees and shrubs (Code_DecTr) and grass surfaces (Code_Grass). Value of integer is arbitrary but must match codes specified in SUEWS_SiteSelect.txt.

SUEWS_Water.txt

L

Code linking to SUEWS_SiteSelect.txt for water surfaces (Code_Water). Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.

SUEWS_Snow.txt

L

Code linking to SUEWS_SiteSelect.txt for snow surfaces (SnowCode). Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.

SUEWS_Soil.txt

L

Code linking to the SoilTypeCode column in SUEWS_NonVeg.txt (for Paved, Bldgs and BSoil surfaces) and SUEWS_Veg.txt (for EveTr, DecTr and Grass surfaces). Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.

SUEWS_Conductance.txt

L

Code linking to the CondCode column in SUEWS_SiteSelect.txt . Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.

SUEWS_AnthropogenicEmission.txt

L

Code linking to the AnthropogenicCode column in SUEWS_SiteSelect.txt . Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.

SUEWS_Irrigation.txt

L

Code linking to SUEWS_SiteSelect.txt for irrigation modelling (IrrigationCode). Value of integer is arbitrary but must match codes specified in SUEWS_SiteSelect.txt.

SUEWS_OHMCoefficients.txt

L

Code linking to the OHMCode_SummerWet, OHMCode_SummerDry, OHMCode_WinterWet and OHMCode_WinterDry columns in SUEWS_NonVeg.txt, SUEWS_Veg.txt, SUEWS_Water.txt and SUEWS_Snow.txt files. Value of integer is arbitrary but must match code specified in SUEWS_SiteSelect.txt.

SUEWS_ESTMCoefficients.txt

L

For buildings and paved surfaces, set to zero if there is more than one ESTM class per grid and the codes and surface fractions specified in SUEWS_SiteSelect.txt will be used instead.

SUEWS_BiogenCO2.txt

L

Code linking to the BiogenCO2Code column in SUEWS_Veg.txt.

Code_Bldgs
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

Code_BSoil
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

Value of integer is arbitrary but must match code specified in column 1 of SUEWS_NonVeg.txt.

Code_DecTr
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

Code_ESTMClass_Bldgs1
Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Bldgs2
Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Bldgs3
Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Bldgs4
Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Bldgs5
Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Paved1
Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Paved2
Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

Code linking to SUEWS_ESTMCoefficients.txt

Code_ESTMClass_Paved3
Description

Code linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

Code linking to SUEWS_ESTMCoefficients.txt

Code_EveTr
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

Code_Grass
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

Code_Paved
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

Code_Water
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

CondCode
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

CRWMax
Description

Maximum water holding capacity of snow [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MD

Maximum water holding capacity of snow [mm]

CRWMin
Description

Minimum water holding capacity of snow [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MD

Minimum water holding capacity of snow [mm]

DayWat(1)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(2)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(3)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(4)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(5)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(6)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(7)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(1)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(2)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(3)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(4)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(5)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(6)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(7)
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DrainageCoef1
Description

Coefficient D0 [mm h-1] used in DrainageEq

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

SUEWS_Veg.txt

MD

  • 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

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 [-]

SUEWS_Water.txt

MU

Example values [-]

  • 0.95 Water Oke (1987) [Ok87]

SUEWS_Snow.txt

MU

Example values [-]

EndDLS
Description

End of the day light savings [DOY]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

End of the day light savings [DOY] See Day Light Savings (DLS).

EnEF_v_Jkm
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

Emission factor for heat [J k|m^-1|]. Example values: 3.97e6 Sailor and Lu (2004) [SL04]

EnergyUseProfWD
Description

Code linking to EnergyUseProfWD in SUEWS_Profiles.txt.

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

L

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

EnergyUseProfWE
Description

Code linking to EnergyUseProfWE in SUEWS_Profiles.txt.

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

L

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

ESTMCode
Description

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

L

For paved and building surfaces, it is possible to specify multiple codes per grid (3 for paved, 5 for buildings) using SUEWS_SiteSelect.txt . In this case, set ESTMCode here to zero.

SUEWS_Veg.txt

L

Code for ESTM coefficients to use for this surface. Links to SUEWS_ESTMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_ESTMCoefficients.txt.

SUEWS_Water.txt

L

Code for ESTM coefficients to use for this surface. Links to SUEWS_ESTMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_ESTMCoefficients.txt.

SUEWS_Snow.txt

L

For paved and building surfaces, it is possible to specify multiple codes per grid (3 for paved, 5 for buildings) using SUEWS_SiteSelect.txt . In this case, set ESTM code here to zero.

FAI_Bldgs
Description

Frontal area index for buildings [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

Frontal area index for buildings [-] Required if RoughLenMomMethod = 3 in RunControl.nml .

FAI_DecTr
Description

Frontal area index for deciduous trees [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

Frontal area index for deciduous trees [-] Required if RoughLenMomMethod = 3 in RunControl.nml .

FAI_EveTr
Description

Frontal area index for evergreen trees [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

Frontal area index for evergreen trees [-] Required if RoughLenMomMethod = 3 in RunControl.nml .

Faut
Description

Fraction of irrigated area that is irrigated using automated systems

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

Fraction of irrigated area that is irrigated using automated systems (e.g. sprinklers).

FcEF_v_kgkmWD
Description

CO2 emission factor for weekdays [kg km-1]

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

CO2 emission factor for weekdays [kg km-1] Can be used for CO2 flux calculation.

FcEF_v_kgkmWE
Description

CO2 emission factor for weekends [kg km-1]

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

CO2 emission factor for weekdays [kg km-1] Can be used for CO2 flux calculation.

FcEF_v_Jkm
Description

Traffic emission factor for CO2.

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

Weekday building energy use [W m-2] Can be used for CO2 flux calculation.

fcld
Description

Cloud fraction [tenths]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Cloud fraction [tenths]

FlowChange
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

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

Fraction1of8
Description

Fraction of water that can flow to GridConnection1of8 [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Fraction of water that can flow to the grid specified in previous column [-]

Fraction2of8
Description

Fraction of water that can flow to GridConnection2of8 [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Fraction of water that can flow to the grid specified in previous column [-]

Fraction3of8
Description

Fraction of water that can flow to GridConnection3of8 [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Fraction of water that can flow to the grid specified in previous column [-]

Fraction4of8
Description

Fraction of water that can flow to GridConnection4of8 [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Fraction of water that can flow to the grid specified in previous column [-]

Fraction5of8
Description

Fraction of water that can flow to GridConnection5of8 [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Fraction of water that can flow to the grid specified in previous column [-]

Fraction6of8
Description

Fraction of water that can flow to GridConnection6of8 [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Fraction of water that can flow to the grid specified in previous column [-]

Fraction7of8
Description

Fraction of water that can flow to GridConnection7of8 [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Fraction of water that can flow to the grid specified in previous column [-]

Fraction8of8
Description

Fraction of water that can flow to GridConnection8of8 [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Fraction of water that can flow to the grid specified in previous column [-]

Fr_Bldgs
Description

Surface cover fraction of buildings [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Surface cover fraction of buildings [-]

Fr_Bsoil
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

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

Fr_DecTr
Description

Surface cover fraction of deciduous trees and shrubs [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Surface cover fraction of deciduous trees and shrubs [-]

Fr_ESTMClass_Bldgs1
Description

Surface cover fraction of building class 1 used in ESTM calculations

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Columns 94-98 must add up to 1

Fr_ESTMClass_Bldgs2
Description

Surface cover fraction of building class 2 used in ESTM calculations

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Columns 94-98 must add up to 1

Fr_ESTMClass_Bldgs3
Description

Surface cover fraction of building class 3 used in ESTM calculations

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Columns 94-98 must add up to 1

Fr_ESTMClass_Bldgs4
Description

Surface cover fraction of building class 4 used in ESTM calculations

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Columns 94-98 must add up to 1

Fr_ESTMClass_Bldgs5
Description

Surface cover fraction of building class 5 used in ESTM calculations

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Columns 94-98 must add up to 1

Fr_ESTMClass_Paved1
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Columns 88-90 must add up to 1

Fr_ESTMClass_Paved2
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Columns 88-90 must add up to 1

Fr_ESTMClass_Paved3
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Columns 88-90 must add up to 1

Fr_EveTr
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Surface cover fraction of evergreen trees and shrubs [-]

Fr_Grass
Description

Surface cover fraction of Grass [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Surface cover fraction of grass [-]

Fr_Paved
Description

Surface cover fraction of Paved surfaces [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Columns 14 to 20 must sum to 1 .

Fr_Water
Description

Surface cover fraction of open water [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Surface cover fraction of open water [-] (e.g. river, lakes, ponds, swimming pools)

FrFossilFuel_Heat
Description

Fraction of fossil fuels used for building heating [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

Weekday building energy use [W m-2] Can be used for CO2 flux calculation.

FrFossilFuel_NonHeat
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

Weekday building energy use [W m-2] Can be used for CO2 flux calculation.

FrPDDwe
Description

Fraction of weekend population to weekday population. [-]

Configuration

G1
Description

Related to maximum surface conductance [mm s-1]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Related to maximum surface conductance [mm s-1]

G2
Description

Related to Kdown dependence [W m-2]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Related to Kdown dependence [W m-2]

G3
Description

Related to VPD dependence [units depend on gsModel]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Related to VPD dependence [units depend on gsChoice in RunControl.nml ]

G4
Description

Related to VPD dependence [units depend on gsModel]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Related to VPD dependence [units depend on gsChoice in RunControl.nml ]

G5
Description

Related to temperature dependence [°C]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Related to temperature dependence [°C]

G6
Description

Related to soil moisture dependence [mm-1]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Related to soil moisture dependence [mm-1]

gamq_gkgm
Description

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

Configuration

Referencing Table

Requirement

Comment

CBL_initial_data.txt

MU

vertical gradient of specific humidity (g kg-1 m-1 )

gamt_Km
Description

vertical gradient of potential temperature [K m-1]

Configuration

Referencing Table

Requirement

Comment

CBL_initial_data.txt

MU

vertical gradient of potential temperature (K m-1 ) strength of the inversion

GDDFull
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MU

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

Grid
Description

a unique number to represent grid

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

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

GridConnection1of8
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

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

GridConnection2of8
Description

Number of the 2nd grid where water can flow to

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Number of the grid where water can flow to

GridConnection3of8
Description

Number of the 3rd grid where water can flow to

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Number of the grid where water can flow to

GridConnection4of8
Description

Number of the 4th grid where water can flow to

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Number of the grid where water can flow to

GridConnection5of8
Description

Number of the 5th grid where water can flow to

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Number of the grid where water can flow to

GridConnection6of8
Description

Number of the 6th grid where water can flow to

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Number of the grid where water can flow to

GridConnection7of8
Description

Number of the 7th grid where water can flow to

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Number of the grid where water can flow to

GridConnection8of8
Description

Number of the 8th grid where water can flow to

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Number of the grid where water can flow to

gsModel
Description

Formulation choice for conductance calculation.

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

  • 1 Järvi et al. (2011) [J11]

  • 2 (Recommended) Ward et al. (2016) [W16]

H_Bldgs
Description

Mean building height [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Mean building height [m]

H_DecTr
Description

Mean height of deciduous trees [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Mean height of deciduous trees [m]

H_EveTr
Description

Mean height of evergreen trees [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Mean height of evergreen trees [m]

id
Description

Day of year [DOY]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

Not used: set to 1 in this version.

SSss_YYYY_ESTM_Ts_data_tt.txt

MU

Day of year [DOY]

SSss_YYYY_data_tt.txt

MU

Day of year [DOY]

CBL_initial_data.txt

MU

Day of year [DOY]

Ie_a1
Description

Coefficient for automatic irrigation model [mm d-1 ]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

Coefficient for automatic irrigation model [mm d -1 ]

Ie_a2
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

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

Ie_a3
Description

Coefficient for automatic irrigation model [mm d-2 ]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

Coefficient for automatic irrigation model [mm d -2 ]

Ie_end
Description

Day when irrigation ends [DOY]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

Day when irrigation ends [DOY]

Ie_m1
Description

Coefficient for manual irrigation model [mm d-1 ]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

Coefficient for manual irrigation model [mm d -1 ]

Ie_m2
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

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

Ie_m3
Description

Coefficient for manual irrigation model [mm d-2 ]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

Coefficient for manual irrigation model [mm d -2 ]

Ie_start
Description

Day when irrigation starts [DOY]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

Day when irrigation starts [DOY]

ih
Description

Hour [H]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

Hour [H] Not used: set to 0 in this version.

imin
Description

Minute [M]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

Minute [M] Not used: set to 0 in this version.

SSss_YYYY_ESTM_Ts_data_tt.txt

MU

Minute [M]

SSss_YYYY_data_tt.txt

MU

Minute [M]

InfiltrationRate
Description

Infiltration rate.

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

O

Not currently used

Internal_albedo
Description

Albedo of all internal elements for building surfaces only

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

Albedo of all internal elements for building surfaces only

Internal_CHbld
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_CHroof
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_CHwall
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_emissivity
Description

Emissivity of all internal elements for building surfaces only

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

Emissivity of all internal elements for building surfaces only

Internal_k1
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

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

Internal_k2
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_k3
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_k4
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_k5
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_rhoCp1
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

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

Internal_rhoCp2
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_rhoCp3
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_rhoCp4
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_rhoCp5
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_thick1
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

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

Internal_thick2
Description

Thickness of the second layer [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_thick3
Description

Thickness of the third layer [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_thick4
Description

Thickness of the fourth layer [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_thick5
Description

Thickness of the fifth layer [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

InternalWaterUse
Description

Internal water use [mm h-1]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

Internal water use [mm h-1]

IrrFr_DecTr
Description

Fraction of deciduous trees that are irrigated [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Fraction of deciduous trees that are irrigated [-]

IrrFr_EveTr
Description

Fraction of evergreen trees that are irrigated [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Fraction of evergreen trees that are irrigated [-] e.g. 50% of the evergreen trees/shrubs are irrigated

IrrFr_Grass
Description

Fraction of Grass that is irrigated [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Fraction of grass that is irrigated [-]

IrrigationCode
Description

Code for modelling irrigation linking to Code of SUEWS_Irrigation.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

it
Description

Hour [H]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_ESTM_Ts_data_tt.txt

MU

Hour [H]

SSss_YYYY_data_tt.txt

MU

Hour [H]

iy
Description

Year [YYYY]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_ESTM_Ts_data_tt.txt

MU

Year [YYYY]

SSss_YYYY_data_tt.txt

MU

Year [YYYY]

kdiff
Description

Diffuse radiation [W m-2].

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Recommended if SOLWEIGUse = 1

kdir
Description

Direct radiation [W m-2].

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Recommended if SOLWEIGUse = 1

kdown
Description

Incoming shortwave radiation [W m-2].

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

MU

Must be > 0 W m-2 .

Kmax
Description

Maximum incoming shortwave radiation [W m-2]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Maximum incoming shortwave radiation [W m-2]

lai
Description

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

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

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

LAIEq
Description

LAI calculation choice.

Note

North and South hemispheres are treated slightly differently.

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

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

Options

LAIMax
Description

full leaf-on summertime value

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

full leaf-on summertime value Example values: - 5.1 EveTr Breuer et al. (2003) [Br03] - 5.5 DecTr Breuer et al. (2003) [Br03] - 5.9 Grass Breuer et al. (2003) [Br03]

LAIMin
Description

leaf-off wintertime value

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

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

lat
Description

Latitude [deg].

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

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

ldown
Description

Incoming longwave radiation [W m-2]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Incoming longwave radiation [W m-2]

LeafGrowthPower1
Description

a parameter required by LAI calculation in LAIEq

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

Example values

LeafGrowthPower2
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

Example values

LeafOffPower1
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

Example values

LeafOffPower2
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

Example values

lng
Description

longitude [deg]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

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

LUMPS_Cover
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

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

LUMPS_DrRate
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

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

LUMPS_MaxRes
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

Maximum water bucket reservoir [mm] Used for LUMPS surface wetness control. Default recommended value of 10 mm from Loridan et al. (2011) [L2011] .

MaxQFMetab
Description

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

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

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

MaxFCMetab
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

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

MaxConductance
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

Example values [mm s-1]

  • 7.4: EveTr Järvi et al. (2011) [J11]

  • 11.7: DecTr Järvi et al. (2011) [J11]

  • 33.1: Grass (unirrigated) Järvi et al. (2011) [J11]

  • 40.: Grass (irrigated) Järvi et al. (2011) [J11]

MinQFMetab
Description

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

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

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

MinFCMetab
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

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

NARP_Trans
Description

Atmospheric transmissivity for NARP [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

Atmospheric transmissivity for NARP [-] Value must in the range 0-1. Default recommended value of 1.

nroom
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

Number of rooms per floor for building surfaces only

OBS_SMCap
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

O

Use only if soil moisture is observed and provided in the met forcing file and SMDMethod = 1 or 2. Use of observed soil moisture not currently tested

OBS_SMDepth
Description

The depth of soil moisture measurements. [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

O

Use only if soil moisture is observed and provided in the met forcing file and SMDMethod = 1 or 2. Use of observed soil moisture not currently tested

OBS_SoilNotRocks
Description

Fraction of soil without rocks. [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

O

Use only if soil moisture is observed and provided in the met forcing file and SMDMethod = 1 or 2. Use of observed soil moisture not currently tested

OHMCode_SummerDry
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

L

Code for OHM coefficients to use for this surface during dry conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Veg.txt

L

Code for OHM coefficients to use for this surface during dry conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Water.txt

L

Code for OHM coefficients to use for this surface during dry conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Snow.txt

L

Code for OHM coefficients to use for this surface during dry conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

OHMCode_SummerWet
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

L

Code for OHM coefficients to use for this surface during wet conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Veg.txt

L

Code for OHM coefficients to use for this surface during wet conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Water.txt

L

Code for OHM coefficients to use for this surface during wet conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Snow.txt

L

Code for OHM coefficients to use for this surface during wet conditions in summer. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

OHMCode_WinterDry
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

L

Code for OHM coefficients to use for this surface during dry conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Veg.txt

L

Code for OHM coefficients to use for this surface during dry conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Water.txt

L

Code for OHM coefficients to use for this surface during dry conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Snow.txt

L

Code for OHM coefficients to use for this surface during dry conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

OHMCode_WinterWet
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

L

Code for OHM coefficients to use for this surface during wet conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Veg.txt

L

Code for OHM coefficients to use for this surface during wet conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Water.txt

L

Code for OHM coefficients to use for this surface during wet conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

SUEWS_Snow.txt

L

Code for OHM coefficients to use for this surface during wet conditions in winter. Links to SUEWS_OHMCoefficients.txt . Value of integer is arbitrary but must match code specified in column 1 of SUEWS_OHMCoefficients.txt.

OHMThresh_SW
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

Temperature threshold determining whether summer/winter OHM coefficients are applied [°C] If 5-day running mean air temperature is greater than or equal to this threshold, OHM coefficients for summertime are applied; otherwise coefficients for wintertime are applied.

SUEWS_Veg.txt

MD

Temperature threshold determining whether summer/winter OHM coefficients are applied [°C] If 5-day running mean air temperature is greater than or equal to this threshold, OHM coefficients for summertime are applied; otherwise coefficients for wintertime are applied.

SUEWS_Water.txt

MD

Temperature threshold determining whether summer/winter OHM coefficients are applied [°C] If 5-day running mean air temperature is greater than or equal to this threshold, OHM coefficients for summertime are applied; otherwise coefficients for wintertime are applied.

SUEWS_Snow.txt

MD

Not actually used for Snow surface as winter wet conditions always assumed.

OHMThresh_WD
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

Not actually used for building and paved surfaces (as impervious).

SUEWS_Veg.txt

MD

Note that OHM coefficients for wet conditions are applied if the surface is wet.

SUEWS_Water.txt

MD

Not actually used for water surface (as no soil surface beneath).

SUEWS_Snow.txt

MD

Not actually used for Snow surface as winter wet conditions always assumed.

PipeCapacity
Description

Storage capacity of pipes [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Storage capacity of pipes [mm] Runoff amounting to less than the value specified here is assumed to be removed by pipes.

PopDensDay
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

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

PopDensNight
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

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

PopProfWD
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

Weekday building energy use [W m-2] Can be used for CO2 flux calculation.

PopProfWE
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

Weekday building energy use [W m-2] Can be used for CO2 flux calculation.

PorosityMax
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

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

PorosityMin
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

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

PrecipLimAlb
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MD

Limit for hourly precipitation when the ground is fully covered with snow. Then snow albedo is reset to AlbedoMax [mm]

PrecipLimSnow
Description

Temperature limit when precipitation falls as snow [°C]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MD

Auer (1974) [Au74]

pres
Description

Barometric pressure [kPa]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

MU

Barometric pressure [kPa]

qe
Description

Latent heat flux [W m-2]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Latent heat flux [W m-2]

qf
Description

Anthropogenic heat flux [W m-2]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Anthropogenic heat flux [W m-2]

QF_A_WD
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 2

Example values:

QF_A_WE
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 2

Example values:

QF_B_WD
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 2

Example values:

QF_B_WE
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 2

Example values:

QF_C_WD
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 2

Example values:

QF_C_WE
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Example values:

q+_gkg
Description

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

Configuration

Referencing Table

Requirement

Comment

CBL_initial_data.txt

MU

specific humidity at the top of CBL (g kg-1 )

q_gkg
Description

specific humidiy in CBL [g kg-1]

Configuration

Referencing Table

Requirement

Comment

CBL_initial_data.txt

MU

specific humidiy in CBL (g kg-1 )

qh
Description

Sensible heat flux [W m-2]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Sensible heat flux [W m-2]

qn
Description

Net all-wave radiation [W m-2]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Required if NetRadiationMethod = 1.

qs
Description

Storage heat flux [W m-2]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Storage heat flux [W m-2]

RadMeltFactor
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MU

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

rain
Description

Rainfall [mm]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

MU

Rainfall [mm]

RH
Description

Relative Humidity [%]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

MU

Relative Humidity [%]

RunoffToWater
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD MU

Fraction of above-ground runoff flowing to water surface during flooding [-] Value must be in the range 0-1. Fraction of above-ground runoff that can flow to the water surface in the case of flooding.

S1
Description

A parameter related to soil moisture dependence [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Related to soil moisture dependence [-] These will change in the future to ensure consistency with soil behaviour

S2
Description

A parameter related to soil moisture dependence [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Related to soil moisture dependence [mm] These will change in the future to ensure consistency with soil behaviour

SatHydraulicCond
Description

Hydraulic conductivity for saturated soil [mm s-1]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

MD

Hydraulic conductivity for saturated soil [mm s-1]

SDDFull
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MU

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

Example values:

  • -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:

SUEWS_Veg.txt

O

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

Example values:

SnowLimRemove
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

O

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

Example values [mm]

SoilDensity
Description

Soil density [kg m-3]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

MD

Soil density [kg m-3]

SoilDepth
Description

Depth of soil beneath the surface [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

MD

Depth of sub-surface soil store [mm] i.e. the depth of soil beneath the surface

SoilStoreCap
Description

Limit value for SoilDepth [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

MD

SoilStoreCap must not be greater than SoilDepth.

SoilTypeCode
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

L

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

SUEWS_Veg.txt

L

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

StartDLS
Description

Start of the day light savings [DOY]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Start of the day light savings [DOY] See Day Light Savings (DLS).

StateLimit
Description

Upper limit to the surface state. [mm]

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

Currently only used for the water surface

SUEWS_Veg.txt

MD

Currently only used for the water surface

SUEWS_Water.txt

MU

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

StorageMax
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

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

Example values:

  • 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

    1. BSoil

SUEWS_Veg.txt

MD

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

Example values:

  • 1.8 EveTr

    1. DecTr

    1. Grass

SUEWS_Water.txt

MD

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

Example values:

  • 0.5 Water

WithinGridBldgsCode
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

WithinGridBSoilCode
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

WithinGridDecTrCode
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

WithinGridEveTrCode
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

WithinGridGrassCode
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

WithinGridPavedCode
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

WithinGridWaterCode
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

Wuh
Description

External water use [m3]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

External water use [ m3]

xsmd
Description

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

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

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

Year
Description

Year [YYYY]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

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

z
Description

Measurement height [m].

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

z must be greater than the displacement height. Forcing data should be representative of the local-scale, i.e. above the height of the roughness elements.

z0
Description

Roughness length for momentum [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

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

zd
Description

Zero-plane displacement [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

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

zi0
Description

initial convective boundary layer height (m)

Configuration

Referencing Table

Requirement

Comment

CBL_initial_data.txt

MU

initial convective boundary layer height [m]

Note

Please report issues with the manual on the GitHub page.

Typical Values

Other values to add - please let us know

Generic Properties

Property

General Type

Value

Description

Reference

Albedo

Non Vegetated

0.09

Paved Helsinki

Järvi et al. (2014)

Albedo

Non Vegetated

0.15

Buildings Helsinki

Järvi et al. (2014)

Albedo

Non Vegetated

0.19

Bare Soil, Helsinki

Järvi et al. (2014)

Albedo

Non Vegetated

0.12

Paved

Oke (1987)

Albedo

Non Vegetated

0.15

Buildings

Oke (1987)

Albedo

Non Vegetated

0.21

Bare Soil

Oke (1987)

Emissivity

Non Vegetated

0.95

Paved

Oke (1987)

Emissivity

Non Vegetated

0.91

Buildings

Oke (1987)

Emissivity

Non Vegetated

0.93

Bare Soil

Oke (1987)

Surface Water storage capacity

Non Vegetated

0.48

Paved

Davies and Hollis (1981)

Surface Water storage capacity

Non Vegetated

0.25

Buildings

Falk and Niemczynowicz (1978)

Albedo

Vegetation

0.10

EveTr

Albedo

Vegetation

0.12

DecTr

Albedo

Vegetation

0.18

Grass

Albedo

Vegetated

0.10

EveTr Helsinki

Järvi et al. (2014)

Albedo

Vegetated

0.16

DecTr Helsinki

Järvi et al. (2014)

Albedo

Vegetated

0.19

Grass Helsinki

Järvi et al. (2014)

Albedo

Vegetated

0.10

EveTr

Oke (1987)

Albedo

Vegetated

0.18

DecTr

Oke (1987)

Albedo

Vegetated

0.21

Grass

Oke (1987)

Emissivity

Vegetated

0.98

EveTr

Oke (1987)

Emissivity

Vegetated

0.98

DecTr

Oke (1987)

Emissivity

Vegetated

0.93

Grass

Oke (1987)

water Storage Minimum capacity (mm)

Vegetated

1.3

EveTr

Breuer et al. (2003)

water Storage Minimum capacity (mm)

Vegetated

0.3

DecTr

Breuer et al. (2003)

water Storage Minimum capacity (mm)

Vegetated

1.9

Grass

Breuer et al. (2003)

Maximum water storage capacity of this surface [mm]

Vegetated

1.3

EveTr

Breuer et al. (2003)

Maximum water storage capacity of this surface [mm]

Vegetated

0.8

DecTr

Grimmond and Oke (1991)

Maximum water storage capacity of this surface [mm]

Vegetated

1.9

Grass

Breuer et al. (2003)

Albedo Max(leaf on)

Vegetated

0.12

DecTr

Albedo Max(leaf on)

Vegetated

0.18

Grass

Albedo Max(leaf on)

Vegetated

0.10

EveTr Helsinki

Järvi et al. (2014)

Albedo Max(leaf on)

Vegetated

0.16

DecTr Helsinki

Järvi et al. (2014)

Albedo Max(leaf on)

Vegetated

0.19

Grass Helsinki

Järvi et al. (2014)

Albedo Max(leaf on)

Vegetated

0.10

EveTr

Oke (1987)

Albedo Max(leaf on)

Vegetated

0.18

DecTr

Oke (1987)

Albedo Max(leaf on)

Vegetated

0.21

Grass

Oke (1987)

Emissivity *View factors should be taken into account

Vegetated

0.98

EveTr

Oke (1987)

Emissivity *View factors should be taken into account

Vegetated

0.98

DecTr

Oke (1987)

Emissivity *View factors should be taken into account

Vegetated

0.93

Grass

Oke (1987)

Minimum water storage capacity of this surface [mm] *Min & max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces).

Vegetated

1.3

EveTr

Breuer et al. (2003)

Minimum water storage capacity of this surface [mm]*Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces).

Vegetated

0.3

DecTr

Breuer et al. (2003)

Minimum water storage capacity of this surface [mm] *Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces).

Vegetated

1.9

Grass

Breuer et al. (2003)

Maximum water storage capacity of this surface [mm] *Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces)

Vegetated

1.3

EveTr

Breuer et al. (2003)

Maximum water storage capacity of this surface [mm] *Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces)

Vegetated

0.8

DecTr

Grimmond and Oke (1991)

Maximum water storage capacity of this surface [mm] *Min and max values are to account for seasonal variation (e.g. leaf-on/leaf-off differences for vegetated surfaces)

Vegetated

1.9

Grass

Breuer et al. (2003)

AlbedoMin

Water

0.1

Water

Oke (1987)

AlbedoMax

Water

0.1

Water

Oke (1987)

Emissivity

Water

0.95

Water

Oke (1987)

Minimum water storage capacity of this surface [mm]

Water

0.5

Water

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

Water

0.5

Water

WetThreshold

water

0.5

Water

StateLimit *Upper limit to the surface state [mm] *State cannot exceed this value. *Set to a large value (e.g. 20000 mm = 20 m) if the water body is substantial (lake| river| etc) or a small value (e.g. 10 mm) if water bodies are very shallow (e.g. fountains).

Water

20000

Water

RadMeltFactor

Snow

0.0016

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

TempMeltFactor

Snow

0.12

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

AlbedoMin

Snow

0-1

Minimum snow albedo [-] - 0.18

Järvi et al. (2014)

AlbedoMax *Maximum snow albedo (fresh snow) [-]

Snow

0.85

Järvi et al. (2014)

Emissivity *Effective surface emissivity. *View factors should be taken into account

Snow

0.99

Snow

Järvi et al. (2014)

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

Snow

0.018

Järvi et al. (2014)

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

Snow

0.11

Järvi et al. (2014)

PrecipiLimAlb

Snow

2

Limit for hourly precipitation when the ground is fully covered with snow. Then snow albedo is reset to AlbedoMax [mm]

snowDensMin

Snow

100

Fresh snow density [kg m-3]

snowDensMax

Snow

400

Maximum snow density [kg m-3]

tau_r *Time constant for snow density ageing [-]

Snow

0.043

Järvi et al. (2014)

CRWMin *Minimum water holding capacity of snow [mm]

Snow

0.05

Järvi et al. (2014)

CRWMax *Maximum water holding capacity of snow [mm]

Snow

0.20

Järvi et al. (2014)

PrecipLimSnow

Snow

2.2

Temperature limit when precipitation falls as snow [°C]

Auer (1974) [Au74]

SoilDepth

Snow

350

Depth of sub-surface soil store [mm] *depth of soil beneath the surface

SoilStoreCap

Soil

150

  • Capacity of sub-surface soil store [mm]

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

  • (SoilStoreCap must not be greater than SoilDepth.)

SatHydraulicCond

Soil

0.0005

Hydraulic conductivity for saturated soil [mm s-1]

SoilDensity

Soil

1.16

Soil density [kg m-3]

InfiltrationRate

Soil

Infiltration rate [mm h-1]

OBS_SMDepth

Soil

Depth of soil moisture measurements [mm]

OBS_SMCap

Soil

Maxiumum observed soil moisture [m3 m-3 or kg kg-1]

OBS_SoilNotRocks

Soil

Fraction of soil without rocks [-]

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

Tip

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

Note

Please report issues with the manual on the GitHub page.

Initial Conditions file

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

A sample file of InitialConditionsSSss_YYYY.nml looks like

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

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

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

Note

Variables can be in any order

Note

Please report issues with the manual on the GitHub page.

Soil moisture states

SoilstorePavedState
Requirement

Required

Description

Initial water stored in soil beneath Paved surface [mm]

Configuration

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

SoilstoreBldgsState
Requirement

Required

Description

Initial water stored in soil beneath Bldgs surface [mm]

Configuration

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

SoilstoreEveTrState
Requirement

Required

Description

Initial water stored in soil beneath EveTr surface [mm]

Configuration

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

SoilstoreDecTrState
Requirement

Required

Description

Initial water stored in soil beneath DecTr surface [mm]

Configuration

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

SoilstoreGrassState
Requirement

Required

Description

Initial water stored in soil beneath Grass surface [mm]

Configuration

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

SoilstoreBSoilState
Requirement

Required

Description

Initial water stored in soil beneath BSoil surface [mm]

Configuration

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

Note

Please report issues with the manual on the GitHub page.

Vegetation parameters

LeavesOutInitially
Requirement

Optional

Description

Flag for initial leave status [1 or 0]

Configuration

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

GDD_1_0
Requirement

Optional

Description

GDD related initial value

Configuration

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

GDD_2_0
Requirement

Optional

Description

GDD related initial value

Configuration

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

LAIinitialEveTr
Requirement

Optional

Description

Initial LAI for evergreen trees EveTr.

Configuration

The recommended values can be found from SUEWS_Veg.txt

LAIinitialDecTr
Requirement

Optional

Description

Initial LAI for deciduous trees DecTr.

Configuration

The recommended values can be found from SUEWS_Veg.txt

LAIinitialGrass
Requirement

Optional

Description

Initial LAI for irrigated grass Grass.

Configuration

The recommended values can be found from SUEWS_Veg.txt

albEveTr0
Requirement

Optional

Description

Albedo of evergreen surface EveTr on day 0 of run

Configuration

The recommended values can be found from SUEWS_Veg.txt

albDecTr0
Requirement

Optional

Description

Albedo of deciduous surface DecTr on day 0 of run

Configuration

The recommended values can be found from SUEWS_Veg.txt

albGrass0
Requirement

Optional

Description

Albedo of grass surface Grass on day 0 of run

Configuration

The recommended values can be found from SUEWS_Veg.txt

decidCap0
Requirement

Optional

Description

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

Configuration

The recommended values can be found from SUEWS_Veg.txt

porosity0
Requirement

Optional

Description

Porosity of deciduous vegetation on day 0 of run.

Configuration

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

Note

Please report issues with the manual on the GitHub page.

Recent meteorology

DaysSinceRain
Requirement

Optional

Description

Days since rain [d]

Configuration

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

Temp_C0
Requirement

Optional

Description

Initial air temperature [degC]

Configuration

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

Note

Please report issues with the manual on the GitHub page.

Above ground state

PavedState
Requirement

Optional

Description

Initial wetness condition on Paved

Configuration

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

BldgsState
Requirement

Optional

Description

Initial wetness condition on Bldgs

Configuration

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

EveTrState
Requirement

Optional

Description

Initial wetness condition on EveTr

Configuration

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

DecTrState
Requirement

Optional

Description

Initial wetness condition on DecTr

Configuration

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

GrassState
Requirement

Optional

Description

Initial wetness condition on Grass

Configuration

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

BSoilState
Requirement

Optional

Description

Initial wetness condition on BSoil

Configuration

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

WaterState
Requirement

Optional

Description

Initial wetness condition on Water

Configuration

For a large water body (e.g. river, sea, lake) set WaterState to a large value, e.g. 20000 mm; for small water bodies (e.g. ponds, fountains) set WaterState to smaller value, e.g. 1000 mm. This value must not exceed StateLimit specified in SUEWS_Water.txt . If unknown, model uses value of WaterDepth specified in SUEWS_Water.txt .

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

Meteorological Input File

SUEWS is designed to run using commonly measured meteorological variables.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

SSss_YYYY_data_tt.txt

Main meteorological data file.

No.

Use

Column Name

Description

1

MU

iy

Year [YYYY]

2

MU

id

Day of year [DOY]

3

MU

it

Hour [H]

4

MU

imin

Minute [M]

5

O

qn

Net all-wave radiation [W m-2] Required if NetRadiationMethod = 0.

6

O

qh

Sensible heat flux [W m-2]

7

O

qe

Latent heat flux [W m-2]

8

O

qs

Storage heat flux [W m-2]

9

O

qf

Anthropogenic heat flux [W m-2]

10

MU

U

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

11

MU

RH

Relative Humidity [%]

12

MU

Tair

Air temperature [°C]

13

MU

pres

Barometric pressure [kPa]

14

MU

rain

Rainfall [mm]

15

MU

kdown

Incoming shortwave radiation [W m-2] Must be > 0 W m-2.

16

O

snow

Snow cover fraction (0 – 1) [-] Required if SnowUse = 1

17

O

ldown

Incoming longwave radiation [W m-2]

18

O

fcld

Cloud fraction [tenths]

19

O

Wuh

External water use [m3]

20

O

xsmd

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

21

O

lai

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

22

O

kdiff

Diffuse radiation [W m-2] Recommended in this version. if SOLWEIGUse = 1

23

O

kdir

Direct radiation [W m-2] Recommended in this version. if SOLWEIGUse = 1

24

O

wdir

Wind direction [°] Not available in this version.

Note

Please report issues with the manual on the GitHub page.

CBL input files

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

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

Filename

Purpose

CBL_initial_data.txt

Gives initial data every morning * when CBL slab model starts running. * filename must match the InitialData_FileName in CBLInput.nml * fixed formats.

CBLInput.nml

Specifies run options, parameters and input file names. * Can be in any order

CBL_initial_data.txt

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

Definitions and example file of initial values prepared for Sacramento.

No.

Column name

Description

1

id

Day of year [DOY]

2

zi0

Initial convective boundary layer height (m)

3

gamt_Km

Vertical gradient of potential temperature (K m-1) strength of the inversion

4

gamq_gkgm

Vertical gradient of specific humidity (g kg-1 m-1)

5

Theta+_K

Potential temperature at the top of CBL (K)

6

q+_gkg

Specific humidity at the top of CBL (g kg-1)

7

Theta_K

Potential temperature in CBL (K)

8

q_gkg

Specific humidiy in CBL (g kg-1)

  • gamt_Km and gamq_gkgm written to two significant figures are required for the model performance in appropriate ranges [Shiho2015].

id

zi0

gamt_Km

gamq_gkgm

Theta+_K

q+_gkg

theta_K

q_gkg

234

188

0.0032

0.00082

290.4

9.6

288.7

8.3

235

197

0.0089

0.089

290.2

8.4

288.3

8.7

CBLInput.nml

sample file of CBLInput.nml looks like

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

Note

The file contents can be in any order.

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

Note

Please report issues with the manual on the GitHub page.

CBLinput
EntrainmentType
Requirement

Required

Description

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

Configuration

Value

Comments

1

Tennekes and Driedonks (1981) - Recommended in this version.

2

McNaughton and Springs (1986)

3

Rayner and Watson (1991)

4

Tennekes (1973)

QH_Choice
Requirement

Required

Description

Determines QH used for CBL model.

Configuration

Value

Comments

1

QH modelled by SUEWS

2

QH modelled by LUMPS

3

Observed QH values are used from the meteorological input file

InitialData_use
Requirement

Required

Description

Determines initial values (see CBL_initial_data.txt)

Configuration

Value

Comments

0

All initial values are calculated. Not available in this version.

1

Take zi0, gamt_Km and gamq_gkgm from input data file. Theta+_K, q+_gkg, Theta_K and q_gkg are calculated using Temp_C, avrh and Pres_kPa in meteorological input file.

2

Take all initial values from input data file (see CBL_Initial_data.txt).

Sondeflag
Requirement

Required

Description

to fill

Configuration

Value

Comments

0

Does not read radiosonde vertical profile data - Recommended in this version.

1

Reads radiosonde vertical profile data

CBLday(id)
Requirement

Required

Description

Set CBLday(id) = 1 If CBL model is set to run for DOY 175–177, CBLday(175) = 1, CBLday(176) = 1, CBLday(177) = 1

Configuration

to fill

CO2_included
Requirement

Required

Description

Set to zero in current version

Configuration

to fill

FileSonde(id)
Requirement

Required

Description

If Sondeflag=1, write the file name including the path from site directory e.g. FileSonde(id)= ‘CBLinputfilesXXX.txt’, XXX is an arbitrary name.

Configuration

to fill

InitialDataFileName
Requirement

Required

Description

If InitialData_use ≥ 1, write the file name including the path from site directory e.g. InitialDataFileName=’CBLinputfilesCBL_initial_data.txt’

Configuration

to fill

Wsb
Requirement

Required

Description

Subsidence velocity (m s-1 ) in eq. 1 and 2 of Onomura et al. (2015) [17] . (-0.01 m s-1 Recommended in this version.)

Configuration

to fill

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

SUEWS input converter

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

How to use

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

  1. fromVer: which version to convert from.

  2. toVer: which version to convert to.

  3. fromDir: where the input files are located.

  4. toDir: where the converted files are produced.

Downloads

Description of rules

The converter currently picks up the following types of actions:

  1. Add: New entries or files to be added with default values.

  2. Rename: Entries to be renamed from one version to another.

  3. Delete: Entries to be deleted from one version to another.

Note

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

The current available rules are listed below:

From

To

Action

File

Variable

Column

Value

2017a

2018a

Delete

RunControl.nml

anthropco2method

-999

-999

2017a

2018a

Rename

RunControl.nml

AnthropHeatMethod

-999

EmissionsMethod

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

AHMin_WD

9

15

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

AHMin_WE

10

15

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

AHSlope_Heating_WD

11

2.7

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

AHSlope_Heating_WE

12

2.7

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

AHSlope_Cooling_WD

13

2.7

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

AHSlope_Cooling_WE

14

2.7

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

TCritic_Heating_WD

15

7

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

TCritic_Heating_WE

16

7

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

TCritic_Cooling_WD

17

7

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

TCritic_Cooling_WE

18

7

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

EnergyUseProfWD

19

44

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

EnergyUseProfWE

20

45

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

ActivityProfWD

21

55663

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

ActivityProfWE

22

55664

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

TraffProfWD

23

701

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

TraffProfWE

24

702

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

PopProfWD

25

801

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

PopProfWE

26

802

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

MinQFMetab

27

75

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

MaxQFMetab

28

175

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

FrFossilFuel_Heat

29

0.05

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

FrFossilFuel_NonHeat

30

0

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

EF_umolCO2perJ

31

1.159

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

EnEF_v_Jkm

32

3.97E+06

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

FcEF_v_kgkm

33

0.285

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

TrafficUnits

34

1

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

EnergyUseProfWD

19

-999

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

EnergyUseProfWE

20

-999

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

ActivityProfWD

21

-999

2017a

2018a

Add

SUEWS_AnthropogenicHeat.txt

ActivityProfWE

22

-999

2017a

2018a

Delete

SUEWS_AnthropogenicHeat.txt

AHMin

-999

-999

2017a

2018a

Delete

SUEWS_AnthropogenicHeat.txt

AHSlope

-999

-999

2017a

2018a

Delete

SUEWS_AnthropogenicHeat.txt

TCritic

-999

-999

2017a

2018a

Rename

SUEWS_AnthropogenicHeat.txt

QF_A_Weekday

-999

QF_A_WD

2017a

2018a

Rename

SUEWS_AnthropogenicHeat.txt

QF_B_Weekday

-999

QF_B_WD

2017a

2018a

Rename

SUEWS_AnthropogenicHeat.txt

QF_C_Weekday

-999

QF_C_WD

2017a

2018a

Rename

SUEWS_AnthropogenicHeat.txt

QF_A_Weekend

-999

QF_A_WE

2017a

2018a

Rename

SUEWS_AnthropogenicHeat.txt

QF_B_Weekend

-999

QF_B_WE

2017a

2018a

Rename

SUEWS_AnthropogenicHeat.txt

QF_C_Weekend

-999

QF_C_WE

2017a

2018a

Add

SUEWS_BiogenCO2.txt

Code

1

31

2017a

2018a

Add

SUEWS_BiogenCO2.txt

alpha

2

0.004

2017a

2018a

Add

SUEWS_BiogenCO2.txt

beta

3

8.747

2017a

2018a

Add

SUEWS_BiogenCO2.txt

theta

4

0.96

2017a

2018a

Add

SUEWS_BiogenCO2.txt

alpha_enh

5

0.016

2017a

2018a

Add

SUEWS_BiogenCO2.txt

beta_enh

6

33.353

2017a

2018a

Add

SUEWS_BiogenCO2.txt

resp_a

7

2.43

2017a

2018a

Add

SUEWS_BiogenCO2.txt

resp_b

8

0

2017a

2018a

Add

SUEWS_BiogenCO2.txt

min_respi

9

0.6

2017a

2018a

Delete

SUEWS_SiteSelect.txt

TrafficRate

-999

-999

2017a

2018a

Delete

SUEWS_SiteSelect.txt

BuildEnergyUse

-999

-999

2017a

2018a

Delete

SUEWS_SiteSelect.txt

EnergyUseProfWD

-999

-999

2017a

2018a

Delete

SUEWS_SiteSelect.txt

EnergyUseProfWE

-999

-999

2017a

2018a

Delete

SUEWS_SiteSelect.txt

ActivityProfWD

-999

-999

2017a

2018a

Delete

SUEWS_SiteSelect.txt

ActivityProfWE

-999

-999

2017a

2018a

Add

SUEWS_SiteSelect.txt

TrafficRate_WD

34

0.01

2017a

2018a

Add

SUEWS_SiteSelect.txt

TrafficRate_WE

35

0.01

2017a

2018a

Add

SUEWS_SiteSelect.txt

QF0_BEU_WD

36

0.88

2017a

2018a

Add

SUEWS_SiteSelect.txt

QF0_BEU_WE

37

0.88

2017a

2018a

Add

SUEWS_Veg.txt

BiogenCO2Code

38

31

2016a

2017a

Add

SUEWS_Conductance.txt

gsModel

13

1

2016a

2017a

Add

SUEWS_NonVeg.txt

OHMThresh_SW

19

10

2016a

2017a

Add

SUEWS_NonVeg.txt

OHMThresh_WD

20

0.9

2016a

2017a

Add

SUEWS_NonVeg.txt

ESTMCode

21

806

2016a

2017a

Add

SUEWS_NonVeg.txt

AnOHM_Cp

22

20000000

2016a

2017a

Add

SUEWS_NonVeg.txt

AnOHM_Kk

23

1.2

2016a

2017a

Add

SUEWS_NonVeg.txt

AnOHM_Ch

24

4

2016a

2017a

Add

SUEWS_Snow.txt

OHMThresh_SW

20

10

2016a

2017a

Add

SUEWS_Snow.txt

OHMThresh_WD

21

0.9

2016a

2017a

Add

SUEWS_Snow.txt

ESTMCode

22

61

2016a

2017a

Add

SUEWS_Snow.txt

AnOHM_Cp

23

100000

2016a

2017a

Add

SUEWS_Snow.txt

AnOHM_Kk

24

1.2

2016a

2017a

Add

SUEWS_Snow.txt

AnOHM_Ch

25

4

2016a

2017a

Add

SUEWS_Water.txt

WaterDepth

9

0

2016a

2017a

Add

SUEWS_Water.txt

OHMThresh_SW

17

10

2016a

2017a

Add

SUEWS_Water.txt

OHMThresh_WD

18

0.9

2016a

2017a

Add

SUEWS_Water.txt

ESTMCode

19

60

2016a

2017a

Add

SUEWS_Water.txt

AnOHM_Cp

20

100000

2016a

2017a

Add

SUEWS_Water.txt

AnOHM_Kk

21

1.2

2016a

2017a

Add

SUEWS_Water.txt

AnOHM_Ch

22

4

2016a

2017a

Add

SUEWS_Veg.txt

PorosityMin

20

-999

2016a

2017a

Add

SUEWS_Veg.txt

PorosityMax

21

-999

2016a

2017a

Add

SUEWS_Veg.txt

OHMThresh_SW

32

10

2016a

2017a

Add

SUEWS_Veg.txt

OHMThresh_WD

33

0.9

2016a

2017a

Add

SUEWS_Veg.txt

ESTMCode

34

200

2016a

2017a

Add

SUEWS_Veg.txt

AnOHM_Cp

35

100000

2016a

2017a

Add

SUEWS_Veg.txt

AnOHM_Kk

36

1.2

2016a

2017a

Add

SUEWS_Veg.txt

AnOHM_Ch

37

4

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Code

1

800

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_thick1

2

0.1

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_k1

3

0.74

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_rhoCp1

4

1500000

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_thick2

5

0.1

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_k2

6

0.93

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_rhoCp2

7

1500000

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_thick3

8

0.05

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_k3

9

0.06

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_rhoCp3

10

70000

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_thick4

11

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_k4

12

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_rhoCp4

13

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_thick5

14

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_k5

15

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Surf_rhoCp5

16

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_thick1

17

0.1

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_k1

18

1

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_rhoCp1

19

1600000

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_thick2

20

0.1

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_k2

21

1

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_rhoCp2

22

1600000

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_thick3

23

0.1

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_k3

24

1

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_rhoCp3

25

1600000

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_thick4

26

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_k4

27

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_rhoCp4

28

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_thick5

29

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_k5

30

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Wall_rhoCp5

31

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_thick1

32

0.05

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_k1

33

0.5

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_rhoCp1

34

1500000

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_thick2

35

0.05

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_k2

36

0.5

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_rhoCp2

37

1500000

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_thick3

38

0.05

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_k3

39

0.5

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_rhoCp3

40

1500000

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_thick4

41

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_k4

42

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_rhoCp4

43

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_thick5

44

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_k5

45

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_rhoCp5

46

-999

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

nroom

47

10

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_albedo

48

0.5

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_emissivity

49

1

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_CHwall

50

0.001

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_CHroof

51

0.001

2016a

2017a

Add

SUEWS_ESTMCoefficients.txt

Internal_CHbld

52

0.001

2016a

2017a

Add

SUEWS_SiteSelect.txt

Timezone

7

0

2016a

2017a

Add

SUEWS_SiteSelect.txt

z

10

999

2016a

2017a

Add

SUEWS_SiteSelect.txt

TrafficRate

34

99999

2016a

2017a

Add

SUEWS_SiteSelect.txt

BuildEnergyUse

35

99999

2016a

2017a

Add

SUEWS_SiteSelect.txt

ActivityProfWD

54

5663

2016a

2017a

Add

SUEWS_SiteSelect.txt

ActivityProfWE

55

5664

2016a

2017a

Add

SUEWS_SiteSelect.txt

AreaWall

87

7000

2016a

2017a

Add

SUEWS_SiteSelect.txt

Fr_ESTMClass_Paved1

88

0

2016a

2017a

Add

SUEWS_SiteSelect.txt

Fr_ESTMClass_Paved2

89

1

2016a

2017a

Add

SUEWS_SiteSelect.txt

Fr_ESTMClass_Paved3

90

0

2016a

2017a

Add

SUEWS_SiteSelect.txt

Code_ESTMClass_Paved1

91

806

2016a

2017a

Add

SUEWS_SiteSelect.txt

Code_ESTMClass_Paved2

92

807

2016a

2017a

Add

SUEWS_SiteSelect.txt

Code_ESTM_Paved3

93

808

2016a

2017a

Add

SUEWS_SiteSelect.txt

Fr_ESTMClass_Bldgs1

94

1

2016a

2017a

Add

SUEWS_SiteSelect.txt

Fr_ESTMClass_Bldgs2

95

0

2016a

2017a

Add

SUEWS_SiteSelect.txt

Fr_ESTMClass_Bldgs3

96

0

2016a

2017a

Add

SUEWS_SiteSelect.txt

Fr_ESTMClass_Bldgs4

97

0

2016a

2017a

Add

SUEWS_SiteSelect.txt

Fr_ESTMClass_Blgds5

98

0

2016a

2017a

Add

SUEWS_SiteSelect.txt

Code_ESTMClass_Bldgs1

99

801

2016a

2017a

Add

SUEWS_SiteSelect.txt

Code_ESTMClass_Bldgs2

100

802

2016a

2017a

Add

SUEWS_SiteSelect.txt

Code_ESTMClass_Bldgs3

101

803

2016a

2017a

Add

SUEWS_SiteSelect.txt

Code_ESTMClass_Bldgs4

102

804

2016a

2017a

Add

SUEWS_SiteSelect.txt

Code_ESTMClass_Bldgs5

103

805

2016a

2017a

Rename

RunControl.nml

AnthropHeatChoice

-999

AnthropHeatMethod

2016a

2017a

Rename

RunControl.nml

CBLuse

-999

CBLUse

2016a

2017a

Rename

RunControl.nml

NetRadiationChoice

-999

NetRadiationMethod

2016a

2017a

Rename

RunControl.nml

RoughLen_heat

-999

RoughLenHeatMethod

2016a

2017a

Rename

RunControl.nml

smd_choice

-999

SMDMethod

2016a

2017a

Rename

RunControl.nml

WU_choice

-999

WaterUseMethod

2016a

2017a

Rename

RunControl.nml

z0_method

-999

RoughLenMomMethod

2016a

2017a

Delete

RunControl.nml

gsChoice

-999

-999

2016a

2017a

Delete

RunControl.nml

SkipHeaderSiteInfo

-999

-999

2016a

2017a

Delete

RunControl.nml

SkipHeaderMet

-999

-999

2016a

2017a

Delete

RunControl.nml

SnowFractionChoice

-999

-999

2016a

2017a

Delete

RunControl.nml

TIMEZONE

-999

-999

2016a

2017a

Delete

RunControl.nml

z

-999

-999

2016a

2017a

Rename

RunControl.nml

SOLWEIGuse

-999

SOLWEIGUse

2016a

2017a

Rename

RunControl.nml

QSChoice

-999

StorageHeatMethod

2016a

2017a

Add

RunControl.nml

AnthropCO2Method

-999

1

2016a

2017a

Add

RunControl.nml

MultipleMetFiles

-999

0

2016a

2017a

Add

RunControl.nml

MultipleInitFiles

-999

0

2016a

2017a

Add

RunControl.nml

MultipleESTMFiles

-999

0

2016a

2017a

Add

RunControl.nml

ResolutionFilesIn

-999

3600

2016a

2017a

Add

RunControl.nml

ResolutionFilesInESTM

-999

3600

2016a

2017a

Add

RunControl.nml

ResolutionFilesOut

-999

3600

2016a

2017a

Add

RunControl.nml

DissagMethod

-999

1

2016a

2017a

Add

RunControl.nml

RainDissagMethod

-999

100

2016a

2017a

Add

RunControl.nml

SuppressWarnings

-999

1

2016a

2017a

Add

RunControl.nml

ncMode

-999

0

2016a

2017a

Add

RunControl.nml

nRow

-999

0

2016a

2017a

Add

RunControl.nml

nCol

-999

0

2016a

2017a

Add

RunControl.nml

Diagnose

-999

0

2016a

2017a

Rename

RunControl.nml

WriteSurfsFile

-999

WriteOutOption

Note

Please report issues with the manual on the GitHub page.

Output files

Runtime diagnostic information

Error messages: problems.txt

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

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

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

    Run completed.
    0
    

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

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

Warning messages: warnings.txt

  • If the program encounters a more minor issue it will not stop but a warning may be written to warnings.txt. It is advisable to check the warnings to ensure there is not a more serious problem.

  • The warnings.txt file can be large (over several GBs) given warning messages are written out during a large scale simulation, you can use tail/head to view the ending/starting part without opening the whole file on Unix-like systems (Linux/mac OS), which may slow down your system.

  • To prevent warnings.txt from being written, set SuppressWarnings to 1 in RunControl.nml.

  • Warning messages are usually written with a grid number, timestamp and error count. If the problem occurs in the initial stages (i.e. before grid numbers and timestamps are assigned, these are printed as 00000).

Summary of model parameters: SS_FileChoices.txt

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

Model output files

SSss_YYYY_SUEWS_TT.txt

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

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

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

Column

Name

WriteOutOption

Description

1

Year

0,1,2

Year [YYYY]

2

DOY

0,1,2

Day of year [DOY]

3

Hour

0,1,2

Hour [H]

4

Min

0,1,2

Minute [M]

5

Dectime

0,1,2

Decimal time [-]

6

Kdown

0,1,2

Incoming shortwave radiation [W m-2]

7

Kup

0,1,2

Outgoing shortwave radiation [W m-2]

8

Ldown

0,1,2

Incoming longwave radiation [W m-2]

9

Lup

0,1,2

Outgoing longwave radiation [W m-2]

10

Tsurf

0,1,2

Bulk surface temperature [°C]

11

QN

0,1,2

Net all-wave radiation [W m-2]

12

QF

0,1,2

Anthropogenic heat flux [W m-2]

13

QS

0,1,2

Storage heat flux [W m-2]

14

QH

0,1,2

Sensible heat flux (calculated using SUEWS) [W m-2]

15

QE

0,1,2

Latent heat flux (calculated using SUEWS) [W m-2]

16

QHlumps

0,1

Sensible heat flux (calculated using LUMPS) [W m-2]

17

QElumps

0,1

Latent heat flux (calculated using LUMPS) [W m-2]

18

QHresis

0,1

Sensible heat flux (calculated using resistance method) [W m-2]

19

Rain

0,1,2

Rain [mm]

20

Irr

0,1,2

Irrigation [mm]

21

Evap

0,1,2

Evaporation [mm]

22

RO

0,1,2

Runoff [mm]

23

TotCh

0,1,2

Change in surface and soil moisture stores [mm]

24

SurfCh

0,1,2

Change in surface moisture store [mm]

25

State

0,1,2

Surface wetness state [mm]

26

NWtrState

0,1,2

Surface wetness state (for non-water surfaces) [mm]

27

Drainage

0,1,2

Drainage [mm]

28

SMD

0,1,2

Soil moisture deficit [mm]

29

FlowCh

0,1

Additional flow into water body [mm]

30

AddWater

0,1

Additional water flow received from other grids [mm]

31

ROSoil

0,1

Runoff to soil (sub-surface) [mm]

32

ROPipe

0,1

Runoff to pipes [mm]

33

ROImp

0,1

Above ground runoff over impervious surfaces [mm]

34

ROVeg

0,1

Above ground runoff over vegetated surfaces [mm]

35

ROWater

0,1

Runoff for water body [mm]

36

WUInt

0,1

Internal water use [mm]

37

WUEveTr

0,1

Water use for irrigation of evergreen trees [mm]

38

WUDecTr

0,1

Water use for irrigation of deciduous trees [mm]

39

WUGrass

0,1

Water use for irrigation of grass [mm]

40

SMDPaved

0,1

Soil moisture deficit for paved surface [mm]

41

SMDBldgs

0,1

Soil moisture deficit for building surface [mm]

42

SMDEveTr

0,1

Soil moisture deficit for evergreen surface [mm]

43

SMDDecTr

0,1

Soil moisture deficit for deciduous surface [mm]

44

SMDGrass

0,1

Soil moisture deficit for grass surface [mm]

45

SMDBSoil

0,1

Soil moisture deficit for bare soil surface [mm]

46

StPaved

0,1

Surface wetness state for paved surface [mm]

47

StBldgs

0,1

Surface wetness state for building surface [mm]

48

StEveTr

0,1

Surface wetness state for evergreen tree surface [mm]

49

StDecTr

0,1

Surface wetness state for deciduous tree surface [mm]

50

StGrass

0,1

Surface wetness state for grass surface [mm]

51

StBSoil

0,1

Surface wetness state for bare soil surface [mm]

52

StWater

0,1

Surface wetness state for water surface [mm]

53

Zenith

0,1,2

Solar zenith angle [°]

54

Azimuth

0,1,2

Solar azimuth angle [°]

55

AlbBulk

0,1,2

Bulk albedo [-]

56

Fcld

0,1,2

Cloud fraction [-]

57

LAI

0,1,2

Leaf area index [m 2 m-2]

58

z0m

0,1

Roughness length for momentum [m]

59

zdm

0,1

Zero-plane displacement height [m]

60

ustar

0,1,2

Friction velocity [m s-1]

61

Lob

0,1,2

Obukhov length [m]

62

RA

0,1

Aerodynamic resistance [s m-1]

63

RS

0,1

Surface resistance [s m-1]

64

Fc

0,1,2

CO2 flux [umol m-2 s-1]

65

FcPhoto

0,1

CO2 flux from photosynthesis [umol m-2 s-1]

66

FcRespi

0,1

CO2 flux from respiration [umol m-2 s-1]

67

FcMetab

0,1

CO2 flux from metabolism [umol m-2 s-1]

68

FcTraff

0,1

CO2 flux from traffic [umol m-2 s-1]

69

FcBuild

0,1

CO2 flux from buildings [umol m-2 s-1]

70

FcPoint

0,1

CO2 flux from point source [umol m-2 s-1]

71

QNSnowFr

1

Net all-wave radiation for snow-free area [W m-2]

72

QNSnow

1

Net all-wave radiation for snow area [W m-2]

73

AlbSnow

1

Snow albedo [-]

74

QM

1

Snow-related heat exchange [W m-2]

75

QMFreeze

1

Internal energy change [W m-2]

76

QMRain

1

Heat released by rain on snow [W m-2]

77

SWE

1

Snow water equivalent [mm]

78

MeltWater

1

Meltwater [mm]

79

MeltWStore

1

Meltwater store [mm]

80

SnowCh

1

Change in snow pack [mm]

81

SnowRPaved

1

Snow removed from paved surface [mm]

82

SnowRBldgs

1

Snow removed from building surface [mm]

83

Ts

0,1,2

Skin temperature [°C]

84

T2

0,1,2

Air temperature at 2 m agl [°C]

85

Q2

0,1,2

Air specific humidity at 2 m agl [g kg-1]

86

U10

0,1,2

Wind speed at 10 m agl [m s-1]

87

RH2

0,1,2

Relative humidity at 2 m agl [%]

SSss_DailyState.txt

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

Column

Name

Description

1

Year

Year [YYYY]

2

DOY

Day of year [DOY]

3

Hour

Hour of the last timestep of a day [HH]

4

Min

Minute of the last timestep of a day [MM]

5

HDD1_h

Heating degree days [°C d]

6

HDD2_c

Cooling degree days [°C d]

7

HDD3_Tmean

Average daily air temperature [°C]

8

HDD4_T5d

5-day running-mean air temperature [°C]

9

P_day

Daily total precipitation [mm]

10

DaysSR

Days since rain [days]

11

GDD_EveTr

Growing degree days for evergreen eree [°C d]

12

GDD_DecTr

Growing degree days for deciduous tree [°C d]

13

GDD_Grass

Growing degree days for grass [°C d]

14

SDD_EveTr

Senescence degree days for evergreen eree [°C d]

15

SDD_DecTr

Senescence degree days for deciduous tree [°C d]

16

SDD_Grass

Senescence degree days for grass [°C d]

17

Tmin

Daily minimum temperature [°C]

18

Tmax

Daily maximum temperature [°C]

19

DLHrs

Day length [h]

20

LAI_EveTr

Leaf area index of evergreen trees [m-2 m-2]

21

LAI_DecTr

Leaf area index of deciduous trees [m-2 m-2]

22

LAI_Grass

Leaf area index of grass [m-2 m-2]

23

DecidCap

Moisture storage capacity of deciduous trees [mm]

24

Porosity

Porosity of deciduous trees [-]

25

AlbEveTr

Albedo of evergreen trees [-]

26

AlbDecTr

Albedo of deciduous trees [-]

27

AlbGrass

Albedo of grass [-]

28

WU_EveTr1

Total water use for evergreen trees [mm]

29

WU_EveTr2

Automatic water use for evergreen trees [mm]

30

WU_EveTr3

Manual water use for evergreen trees [mm]

31

WU_DecTr1

Total water use for deciduous trees [mm]

32

WU_DecTr2

Automatic water use for deciduous trees [mm]

33

WU_DecTr3

Manual water use for deciduous trees [mm]

34

WU_Grass1

Total water use for grass [mm]

35

WU_Grass2

Automatic water use for grass [mm]

36

WU_Grass3

Manual water use for grass [mm]

37

deltaLAI

Change in leaf area index (normalised 0-1) [-]

38

LAIlumps

Leaf area index used in LUMPS (normalised 0-1) [-]

39

AlbSnow

Snow albedo [-]

40

DensSnow_Paved

Snow density - paved surface [kg m-3]

41

DensSnow_Bldgs

Snow density - building surface [kg m-3]

42

DensSnow_EveTr

Snow density - evergreen surface [kg m-3]

43

DensSnow_DecTr

Snow density - deciduous surface [kg m-3]

44

DensSnow_Grass

Snow density - grass surface [kg m-3]

45

DensSnow_BSoil

Snow density - bare soil surface [kg m-3]

46

DensSnow_Water

Snow density - water surface [kg m-3]

47

a1

OHM cofficient a1 - [-]

48

a2

OHM cofficient a2 [W m-2 h-1]

49

a3

OHM cofficient a3 - [W m-2]

InitialConditionsSSss_YYYY.nml

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

SSss_YYYY_snow_TT.txt

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

File format of SSss_YYYY_snow_TT.txt

Column

Name

Description

1

iy

Year [YYYY]

2

id

Day of year [DOY]

3

it

Hour [H]

4

imin

Minute [M]

5

dectime

Decimal time [-]

6

SWE_Paved

Snow water equivalent – paved surface [mm]

7

SWE_Bldgs

Snow water equivalent – building surface [mm]

8

SWE_EveTr

Snow water equivalent – evergreen surface [mm]

9

SWE_DecTr

Snow water equivalent – deciduous surface [mm]

10

SWE_Grass

Snow water equivalent – grass surface [mm]

11

SWE_BSoil

Snow water equivalent – bare soil surface [mm]

12

SWE_Water

Snow water equivalent – water surface [mm]

13

Mw_Paved

Meltwater – paved surface [mm h-1]

14

Mw_Bldgs

Meltwater – building surface [mm h-1]

15

Mw_EveTr

Meltwater – evergreen surface [mm h-1]

16

Mw_DecTr

Meltwater – deciduous surface [mm h-1]

17

Mw_Grass

Meltwater – grass surface [mm h-1 1]

18

Mw_BSoil

Meltwater – bare soil surface [mm h-1]

19

Mw_Water

Meltwater – water surface [mm h-1]

20

Qm_Paved

Snowmelt-related heat – paved surface [W m-2]

21

Qm_Bldgs

Snowmelt-related heat – building surface [W m-2]

22

Qm_EveTr

Snowmelt-related heat – evergreen surface [W m-2]

23

Qm_DecTr

Snowmelt-related heat – deciduous surface [W m-2]

24

Qm_Grass

Snowmelt-related heat – grass surface [W m-2]

25

Qm_BSoil

Snowmelt-related heat – bare soil surface [W m-2]

26

Qm_Water

Snowmelt-related heat – water surface [W m-2]

27

Qa_Paved

Advective heat – paved surface [W m-2]

28

Qa_Bldgs

Advective heat – building surface [W m-2]

29

Qa_EveTr

Advective heat – evergreen surface [W m-2]

30

Qa_DecTr

Advective heat – deciduous surface [W m-2]

31

Qa_Grass

Advective heat – grass surface [W m-2]

32

Qa_BSoil

Advective heat – bare soil surface [W m-2]

33

Qa_Water

Advective heat – water surface [W m-2]

34

QmFr_Paved

Heat related to freezing of surface store – paved surface [W m-2]

35

QmFr_Bldgs

Heat related to freezing of surface store – building surface [W m-2]

36

QmFr_EveTr

Heat related to freezing of surface store – evergreen surface [W m-2]

37

QmFr_DecTr

Heat related to freezing of surface store – deciduous surface [W m-2]

38

QmFr_Grass

Heat related to freezing of surface store – grass surface [W m-2]

39

QmFr_BSoil

Heat related to freezing of surface store – bare soil surface [W m-2]

40

QmFr_Water

Heat related to freezing of surface store – water [W m-2]

41

fr_Paved

Fraction of snow – paved surface [-]

42

fr_Bldgs

Fraction of snow – building surface [-]

43

fr_EveTr

Fraction of snow – evergreen surface [-]

44

fr_DecTr

Fraction of snow – deciduous surface [-]

45

fr_Grass

Fraction of snow – grass surface [-]

46

Fr_BSoil

Fraction of snow – bare soil surface [-]

47

RainSn_Paved

Rain on snow – paved surface [mm]

48

RainSn_Bldgs

Rain on snow – building surface [mm]

49

RainSn_EveTr

Rain on snow – evergreen surface [mm]

50

RainSn_DecTr

Rain on snow – deciduous surface [mm]

51

RainSn_Grass

Rain on snow – grass surface [mm]

52

RainSn_BSoil

Rain on snow – bare soil surface [mm]

53

RainSn_Water

Rain on snow – water surface [mm]

54

qn_PavedSnow

Net all-wave radiation – paved surface [W m-2]

55

qn_BldgsSnow

Net all-wave radiation – building surface [W m-2]

56

qn_EveTrSnow

Net all-wave radiation – evergreen surface [W m-2]

57

qn_DecTrSnow

Net all-wave radiation – deciduous surface [W m-2]

58

qn_GrassSnow

Net all-wave radiation – grass surface [W m-2]

59

qn_BSoilSnow

Net all-wave radiation – bare soil surface [W m-2]

60

qn_WaterSnow

Net all-wave radiation – water surface [W m-2]

61

kup_PavedSnow

Reflected shortwave radiation – paved surface [W m-2]

62

kup_BldgsSnow

Reflected shortwave radiation – building surface [W m-2]

63

kup_EveTrSnow

Reflected shortwave radiation – evergreen surface [W m-2]

64

kup_DecTrSnow

Reflected shortwave radiation – deciduous surface [W m-2]

65

kup_GrassSnow

Reflected shortwave radiation – grass surface [W m-2]

66

kup_BSoilSnow

Reflected shortwave radiation – bare soil surface [W m-2]

67

kup_WaterSnow

Reflected shortwave radiation – water surface [W m-2]

68

frMelt_Paved

Amount of freezing melt water – paved surface [mm]

69

frMelt_Bldgs

Amount of freezing melt water – building surface [mm]

70

frMelt_EveTr

Amount of freezing melt water – evergreen surface [mm]

71

frMelt_DecTr

Amount of freezing melt water – deciduous surface [mm]

72

frMelt_Grass

Amount of freezing melt water – grass surface [mm]

73

frMelt_BSoil

Amount of freezing melt water – bare soil surface [mm]

74

frMelt_Water

Amount of freezing melt water – water surface [mm]

75

MwStore_Paved

Melt water store – paved surface [mm]

76

MwStore_Bldgs

Melt water store – building surface [mm]

77

MwStore_EveTr

Melt water store – evergreen surface [mm]

78

MwStore_DecTr

Melt water store – deciduous surface [mm]

79

MwStore_Grass

Melt water store – grass surface [mm]

80

MwStore_BSoil

Melt water store – bare soil surface [mm]

81

MwStore_Water

Melt water store – water surface [mm]

82

DensSnow_Paved

Snow density – paved surface [kg m-3]

83

DensSnow_Bldgs

Snow density – building surface [kg m-3]

84

DensSnow_EveTr

Snow density – evergreen surface [kg m-3]

85

DensSnow_DecTr

Snow density – deciduous surface [kg m-3]

86

DensSnow_Grass

Snow density – grass surface [kg m-3]

87

DensSnow_BSoil

Snow density – bare soil surface [kg m-3]

88

DensSnow_Water

Snow density – water surface [kg m-3]

89

Sd_Paved

Snow depth – paved surface [mm]

90

Sd_Bldgs

Snow depth – building surface [mm]

91

Sd_EveTr

Snow depth – evergreen surface [mm]

92

Sd_DecTr

Snow depth – deciduous surface [mm]

93

Sd_Grass

Snow depth – grass surface [mm]

94

Sd_BSoil

Snow depth – bare soil surface [mm]

95

Sd_Water

Snow depth – water surface [mm]

96

Tsnow_Paved

Snow surface temperature – paved surface [°C]

97

Tsnow_Bldgs

Snow surface temperature – building surface [°C]

98

Tsnow_EveTr

Snow surface temperature – evergreen surface [°C]

99

Tsnow_DecTr

Snow surface temperature – deciduous surface [°C]

100

Tsnow_Grass

Snow surface temperature – grass surface [°C]

101

Tsnow_BSoil

Snow surface temperature – bare soil surface [°C]

102

Tsnow_Water

Snow surface temperature – water surface [°C]

SSss_YYYY_RSL_TT.txt

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

File format of SSss_YYYY_RSL_TT.txt:

Column

Name

Description

1

Year

Year [YYYY]

2

DOY

Day of year [DOY]

3

Hour

Hour [H]

4

Min

Minute [M]

5

Dectime

Decimal time [-]

6

z_1

Height at level 1 [m]

7

z_2

Height at level 2 [m]

8

z_3

Height at level 3 [m]

9

z_4

Height at level 4 [m]

10

z_5

Height at level 5 [m]

11

z_6

Height at level 6 [m]

12

z_7

Height at level 7 [m]

13

z_8

Height at level 8 [m]

14

z_9

Height at level 9 [m]

15

z_10

Height at level 10 [m]

16

z_11

Height at level 11 [m]

17

z_12

Height at level 12 [m]

18

z_13

Height at level 13 [m]

19

z_14

Height at level 14 [m]

20

z_15

Height at level 15 [m]

21

z_16

Height at level 16 [m]

22

z_17

Height at level 17 [m]

23

z_18

Height at level 18 [m]

24

z_19

Height at level 19 [m]

25

z_20

Height at level 20 [m]

26

z_21

Height at level 21 [m]

27

z_22

Height at level 22 [m]

28

z_23

Height at level 23 [m]

29

z_24

Height at level 24 [m]

30

z_25

Height at level 25 [m]

31

z_26

Height at level 26 [m]

32

z_27

Height at level 27 [m]

33

z_28

Height at level 28 [m]

34

z_29

Height at level 29 [m]

35

z_30

Height at level 30 [m]

36

U_1

Wind speed at level 1 [m s-1]

37

U_2

Wind speed at level 2 [m s-1]

38

U_3

Wind speed at level 3 [m s-1]

39

U_4

Wind speed at level 4 [m s-1]

40

U_5

Wind speed at level 5 [m s-1]

41

U_6

Wind speed at level 6 [m s-1]

42

U_7

Wind speed at level 7 [m s-1]

43

U_8

Wind speed at level 8 [m s-1]

44

U_9

Wind speed at level 9 [m s-1]

45

U_10

Wind speed at level 10 [m s-1]

46

U_11

Wind speed at level 11 [m s-1]

47

U_12

Wind speed at level 12 [m s-1]

48

U_13

Wind speed at level 13 [m s-1]

49

U_14

Wind speed at level 14 [m s-1]

50

U_15

Wind speed at level 15 [m s-1]

51

U_16

Wind speed at level 16 [m s-1]

52

U_17

Wind speed at level 17 [m s-1]

53

U_18

Wind speed at level 18 [m s-1]

54

U_19

Wind speed at level 19 [m s-1]

55

U_20

Wind speed at level 20 [m s-1]

56

U_21

Wind speed at level 21 [m s-1]

57

U_22

Wind speed at level 22 [m s-1]

58

U_23

Wind speed at level 23 [m s-1]

59

U_24

Wind speed at level 24 [m s-1]

60

U_25

Wind speed at level 25 [m s-1]

61

U_26

Wind speed at level 26 [m s-1]

62

U_27

Wind speed at level 27 [m s-1]

63

U_28

Wind speed at level 28 [m s-1]

64

U_29

Wind speed at level 29 [m s-1]

65

U_30

Wind speed at level 30 [m s-1]

66

T_1

Air temperature at level 1 [°C]

67

T_2

Air temperature at level 2 [°C]

68

T_3

Air temperature at level 3 [°C]

69

T_4

Air temperature at level 4 [°C]

70

T_5

Air temperature at level 5 [°C]

71

T_6

Air temperature at level 6 [°C]

72

T_7

Air temperature at level 7 [°C]

73

T_8

Air temperature at level 8 [°C]

74

T_9

Air temperature at level 9 [°C]

75

T_10

Air temperature at level 10 [°C]

76

T_11

Air temperature at level 11 [°C]

77

T_12

Air temperature at level 12 [°C]

78

T_13

Air temperature at level 13 [°C]

79

T_14

Air temperature at level 14 [°C]

80

T_15

Air temperature at level 15 [°C]

81

T_16

Air temperature at level 16 [°C]

82

T_17

Air temperature at level 17 [°C]

83

T_18

Air temperature at level 18 [°C]

84

T_19

Air temperature at level 19 [°C]

85

T_20

Air temperature at level 20 [°C]

86

T_21

Air temperature at level 21 [°C]

87

T_22

Air temperature at level 22 [°C]

88

T_23

Air temperature at level 23 [°C]

89

T_24

Air temperature at level 24 [°C]

90

T_25

Air temperature at level 25 [°C]

91

T_26

Air temperature at level 26 [°C]

92

T_27

Air temperature at level 27 [°C]

93

T_28

Air temperature at level 28 [°C]

94

T_29

Air temperature at level 29 [°C]

95

T_30

Air temperature at level 30 [°C]

96

q_1

Specific humidity at level 1 [g kg-1]

97

q_2

Specific humidity at level 2 [g kg-1]

98

q_3

Specific humidity at level 3 [g kg-1]

99

q_4

Specific humidity at level 4 [g kg-1]

100

q_5

Specific humidity at level 5 [g kg-1]

101

q_6

Specific humidity at level 6 [g kg-1]

102

q_7

Specific humidity at level 7 [g kg-1]

103

q_8

Specific humidity at level 8 [g kg-1]

104

q_9

Specific humidity at level 9 [g kg-1]

105

q_10

Specific humidity at level 10 [g kg-1]

106

q_11

Specific humidity at level 11 [g kg-1]

107

q_12

Specific humidity at level 12 [g kg-1]

108

q_13

Specific humidity at level 13 [g kg-1]

109

q_14

Specific humidity at level 14 [g kg-1]

110

q_15

Specific humidity at level 15 [g kg-1]

111

q_16

Specific humidity at level 16 [g kg-1]

112

q_17

Specific humidity at level 17 [g kg-1]

113

q_18

Specific humidity at level 18 [g kg-1]

114

q_19

Specific humidity at level 19 [g kg-1]

115

q_20

Specific humidity at level 20 [g kg-1]

116

q_21

Specific humidity at level 21 [g kg-1]

117

q_22

Specific humidity at level 22 [g kg-1]

118

q_23

Specific humidity at level 23 [g kg-1]

119

q_24

Specific humidity at level 24 [g kg-1]

120

q_25

Specific humidity at level 25 [g kg-1]

121

q_26

Specific humidity at level 26 [g kg-1]

122

q_27

Specific humidity at level 27 [g kg-1]

123

q_28

Specific humidity at level 28 [g kg-1]

124

q_29

Specific humidity at level 29 [g kg-1]

125

q_30

Specific humidity at level 30 [g kg-1]

SSss_YYYY_BL.txt

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

Column

Name

Description

Units

1

iy

Year [YYYY]

2

id

Day of year [DoY]

3

it

Hour [H]

4

imin

Minute [M]

5

dectime

Decimal time [-]

6

zi

Convectibe boundary layer height

m

7

Theta

Potential temperature in the inertial sublayer

K

8

Q

Specific humidity in the inertial sublayer

g kg-1

9

theta+

Potential temperature just above the CBL

K

10

q+

Specific humidity just above the CBL

g kg-1

11

Temp_C

Air temperature

°C

12

RH

Relative humidity

%

13

QH_use

Sensible heat flux used for calculation

W m-2

14

QE_use

Latent heat flux used for calculation

W m-2

15

Press_hPa

Pressure used for calculation

hPa

16

avu1

Wind speed used for calculation

m s-1

17

ustar

Friction velocity used for calculation

m s-1

18

avdens

Air density used for calculation

kg m-3

19

lv_J_kg

Latent heat of vaporization used for calculation

J kg-1

20

avcp

Specific heat capacity used for calculation

J kg-1 K-1

21

gamt

Vertical gradient of potential temperature

K m-1

22

gamq

Vertical gradient of specific humidity

kg kg-1 m-1

SSss_YYYY_ESTM_TT.txt

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

ESTM output file format

Column

Name

Description

Units

1

iy

Year

2

id

Day of year

3

it

Hour

4

imin

Minute

5

dectime

Decimal time

6

QSnet

Net storage heat flux (QSwall+QSground+QS)

W m-2

7

QSair

Storage heat flux into air

W m-2

8

QSwall

Storage heat flux into wall

W m-2

9

QSroof

Storage heat flux into roof

W m-2

10

QSground

Storage heat flux into ground

W m-2

11

QSibld

Storage heat flux into internal elements in buildling

W m-2

12

Twall1

Temperature in the first layer of wall (outer-most)

K

13

Twall2

Temperature in the first layer of wall

K

14

Twall3

Temperature in the first layer of wall

K

15

Twall4

Temperature in the first layer of wall

K

16

Twall5

Temperature in the first layer of wall (inner-most)

K

17

Troof1

Temperature in the first layer of roof (outer-most)

K

18

Troof2

Temperature in the first layer of roof

K

19

Troof3

Temperature in the first layer of roof

K

20

Troof4

Temperature in the first layer of roof

K

21

Troof5

Temperature in the first layer of ground (inner-most)

K

22

Tground1

Temperature in the first layer of ground (outer-most)

K

23

Tground2

Temperature in the first layer of ground

K

24

Tground3

Temperature in the first layer of ground

K

25

Tground4

Temperature in the first layer of ground

K

26

Tground5

Temperature in the first layer of ground (inner-most)

K

27

Tibld1

Temperature in the first layer of internal elements

K

28

Tibld2

Temperature in the first layer of internal elements

K

29

Tibld3

Temperature in the first layer of internal elements

K

30

Tibld4

Temperature in the first layer of internal elements

K

31

Tibld5

Temperature in the first layer of internal elements

K

32

Tabld

Air temperature in buildings

K

Note

Please report issues with the manual on the GitHub page.

Troubleshooting

How to report an issue of this manual?

Please submit your issue via our GitHub page.

How to join your email-list?

Please join our email-list here.

How to create a directory?

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

How to unzip a file

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

A text editor

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

Command prompt

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

Day of year [DOY]

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

ESTM output

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

First things to Check if the program seems to have problems

  • Check the problems.txt file.

  • Check file options – in RunControl.nml.

  • Look in the output directory for the SS_FileChoices.txt. This allows you to check all options that were used in the run. You may want to compare it with the original version supplied with the model.

  • Note there can not be missing time steps in the data. If you need help with this you may want to checkout UMEP

A pop-up saying “file path not found”

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

  • Check that you have created the folder that you specified in RunControl.nml.

  • Check does the output directory exist?

  • Check that you have a single or double quotes around the FileInputPath, FileOutputPath and FileCode

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

  • You don’t need to worry if the temperature should be (is) 0°C.

  • If it should not be 0°C this suggests that there is a problem with the data.

%T changed to fit limits

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

%Iteration loop stopped for too stable conditions.

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

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

  • Parameter(s) missing from input files.

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

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.

topic

Application and evalution in cold climates. Implications of warming

citation

Järvi L, S Grimmond, JP McFadden, A Christen, I Strachan, M Taka, L Warsta, M Heimann 2017: Warming effects on the urban hydrology in cold climate regions Scientific Reports 7: 5833

topic

Downscaling climate (rainfall) data to 1 h

citation

Kokkonen T, CSB Grimmond, O Räty, HC Ward, A Christen, T Oke, S Kotthaus, L Järvi 2017: Sensitivity of Surface Urban Energy and Water Balance Scheme (SUEWS)

topic

for example applications:

citation

Ward HC, S Grimmond 2017: Using biophysical modelling to assess the impact of various scenarios on summertime urban climate across Greater London Landscape and Urban Planning 165, 142–161

topic

evaluation in Singapore and comparison with other urban land surface models

citation

Demuzere M, S Harshan, L Järvi, M Roth, CSB Grimmond, V Masson, KW Oleson, E Velasco H Wouters 2017: Impact of urban canopy models and external parameters on the modelled urban energy balance QJRMS, 143, Issue 704, Part A, 1581–1596

topic

Evaluation of SUEWS model

citation

Ward HC, Kotthaus S, Järvi L and Grimmond CSB (2016) Surface Urban Energy and Water Balance Scheme (SUEWS): Development and evaluation at two UK sites. Urban Climate

topic

Evaluation of radiation in Shanghai

citation

Ao XY, CSB Grimmond, DW Liu, ZH Han, P Hu, YD Wang, XR Zhen, JG Tan 2016: Radiation fluxes in a business district of Shanghai JAMC, 55, 2451-2468

topic

Boundary layer modelling

citation

Onomura S, Grimmond CSB, Lindberg F, Holmer B & Thorsson S (2015) Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme Urban Climate, 11, 1-23

topic

Snow melt model development

citation

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

Other papers

Note

Please report issues with the manual on the GitHub page.

Note

Please report issues with the manual on the GitHub page.

Tutorials

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

Topic

Application

Urban Energy Balance - SUEWS Introduction

Energy, water and radiation fluxes for one location

Urban Energy Balance - SUEWS Advanced

Energy, water and radiation fluxes for one location

Urban Energy Balance - SUEWS Spatial

Energy, water and radiation fluxes for a spatial grid

Urban Energy Balance - SUEWS and WUDAPT

Making use of WUDAPT local climate zones in SUEWS

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS Introduction

Introduction

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

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

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

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

none

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

SUEWS can be run in a number of different ways:

  1. Within UMEP via the Simple selection. This is useful for becoming familiar with the model (Part 1)

  2. Within UMEP via the Advanced selection. This can be used to exploit the full capabilities of the model (Part 2)

  3. SUEWS standalone (see manual)

  4. Within other larger scale models (e.g. WRF).

SUEWS Simple Objectives

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

Steps
  1. An introduction to the model and how it is designed.

  2. Different kinds of input data that are needed to run the model

  3. How to run the model

  4. How to examine the model output

Initial Steps

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

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

SUEWS Model Inputs

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

Type

Definition

Reference/Comments

Building/ Tree Morphology

Mean height of Building/Trees (m)

Grimmond and Oke (1999)

Frontal area index

Area of the front face of a roughness element exposed to the wind relative to the plan area.

Grimmond and Oke (1999), Fig 2

Plan area index

Area of the roughness elements relative to the total plan area.

Grimmond and Oke (1999), Fig 2

Land cover fraction

Should sum to 1

Paved

Roads, sidewalks, parking lots, impervious surfaces that are not buildings

Buildings

Buildings

Same as the plan area index of buildings in the morphology section.

Evergreen trees

Trees/shrubs that retain their leaves/needles all year round

Tree plan area index will be the sum of evergreen and deciduous area. Note: this is the same as the plan area index of vegetation in the morphology section.

Deciduous trees

Trees/shrubs that lose their leaves

Same as above

Grass

Grass

Bare soil

Bare soil – non vegetated but water can infilitrate

Water

River, ponds, swimming pools, fountains

Initial conditions

What is the state of the conditions when the model run begins?

Days since rain (days)

This will influence irrigation behaviour in the model. If there has been rain recently then it will be longer before irrigiation occurs.

If this is a period or location when no irrigation is permitted/occurring then this is not critical as the model will calculate from this point going forward.

Daily mean temperature (°C)

Influences irrigation and anthropogenic heat flux

Soil mositure status (%)

This will influence both evaporation and runoff processes

If close to 100% then there is plenty of water for evaporation but also a higher probability of flooding if intense precipitation occurs.

Other

Year

What days are weekdays/weekends

Latitude (°)

Solar related calculations

Longitude (°)

Solar related calculations

UTC (h)

Time zone

Influences solar related calculations

How to Run SuewsSimple from the UMEP-plugin

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

none

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

  1. To make use of this dataset click on Add settings from test dataset (see near bottom of the box). The land cover fractions and all other settings originate from Kotthaus and Grimmond (2014). They used a source area model to obtain the different input parameters (their Fig. 7 in Kotthaus and Grimmond, 2014).

  2. Before you start the model, change the location of the output data to any location of your choice. Also, make notes on the settings such as Year etc.

  3. Do a model run and explore the results by clicking Run. A command window appears, when SUEWS performs the calculations using the settings from the interface. Once the calculations are done, some of the results are shown in two summary plots.

none

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

none

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

Model results

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

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

none

Zoom in on end of March from the daily plot (click on image to make it larger).

Saving a Figure

Use the disk tool in the upper left corner.

  1. .jpg

  2. .pdf

  3. .tif (Recommended)

  4. .png

Output data Files

In the output folder (you selected earlier) you will find (at least) three files:

  1. Kc98_2012_60.txt – provides the 60 min model results for site “KC1” for the year 2012

  2. Kc_FilesChoices.txt – this indicates all options used in the model run see the SUEWS Manual for interpretation of content (this is for when you are doing large number of runs so you know exactly what options were used in each run)

  3. Kc98_DailyState.txt – this provides the daily mean state (see SUEWS manual for detailed explanation). This allows you to see, for example, the daily state of the LAI (leaf area index).

  4. Kc_OutputFormat.txt – provides detailed information about the output files such as extended descriptions for each column including units.

If you open these files in a text editor. To understand the header variables read the SUEWS manual.

Sensitivity to land surface fractions

none

Land cover fractions (click on image to make it larger).

The previous results are for a densely build-up area in London, UK. In order to test the sensitivity of SUEWS to some surface properties you can think about changing some of the surface properties in the SUEWS Simple. For example, change the land cover fraction by:

  1. Change the land cover fractions as seen in the figure. Feel free to select other values as long as all the fractions add up to 1.0.

  2. Save the output to a different folder by selecting output folder.

  3. Click Run.

References

  • Grimmond CSB and Oke 1999: Aerodynamic properties of urban areas derived, from analysis of surface form. Journal of Applied Climatology 38:9, 1262-1292

  • Grimmond et al. 2015: Climate Science for Service Partnership: China, Shanghai Meteorological Servce, Shanghai, China, August 2015.

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

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

  • Kormann R, Meixner FX 2001: An analytical footprint model for non-neutral stratification. Bound.-Layer Meteorol., 99, 207–224

  • Kotthaus S and Grimmond CSB 2014: Energy exchange in a dense urban environment – Part II: Impact of spatial heterogeneity of the surface. Urban Climate 10, 281–307

  • Onomura S, Grimmond CSB, Lindberg F, Holmer B, Thorsson S 2015: Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme. Urban Climate. 11:1-23 (link to paper)

  • Ward HC, L Järvi, S Onomura, F Lindberg, A Gabey, CSB Grimmond 2016 SUEWS Manual V2016a, http://urban-climate.net/umep/SUEWS Department of Meteorology, University of Reading, Reading, UK

  • Ward HC, Kotthaus S, Järvi L and Grimmond CSB 2016b: Surface Urban Energy and Water Balance Scheme (SUEWS): Development and evaluation at two UK sites. Urban Climate http://dx.doi.org/10.1016/j.uclim.2016.05.001

  • Ward HC, S Kotthaus, CSB Grimmond, A Bjorkegren, M Wilkinson, WTJ Morrison, JG Evans, JIL Morison, M Iamarino 2015b: Effects of urban density on carbon dioxide exchanges: observations of dense urban, suburban and woodland areas of southern England. Env Pollution 198, 186-200

Authors this document: Lindberg and Grimmond (2016)

Definitions and Notation

To help you find further information about the acronyms they are classified by T: Type of term: C: computer term, S: science term, G: GIS term.

Definition

T

Ref./Comment

DEM

Digital elevation model

G

DSM

Digital surface model

G

FAI (λF)

Frontal area index

S

Grimmond and Oke (1999)

GUI

Graphical User Interface

C

LAI

Leaf Area Index

S

PAI (λP)

Plan area index

S

png

Portable Network Graphics

C

format for saving plots/figures

QGIS

G

www.qgis.org

SUEWS

Surface Urban Energy and Water Balance Scheme

S

Tif

Tagged Image File Format

C

format for saving plots/figures

UI

user interface

C

UMEP

Urban Multi-scale Environmental predictor

C

z0

Roughness length for momentum

S

Grimmond and Oke (1999)

zd

Zero plane displacement length for momentum

S

Grimmond and Oke (1999)

Further explanation

Morphometric Methods to determine Roughness parameters:

For more and overview and details see Grimmond and Oke (1999) and Kent et al. (2017a). This uses the height and spacing of roughness elements (e.g. buildings, trees) to model the roughness parameters. For more details see Kent et al. (2017a), Kent et al. (2017b) and [Kent et al. (2017c)]. UMEP has tools for doing this: Pre-processor -> Urban Morphology

Source Area Model

For more details see Kotthaus and Grimmond (2014b) and Kent et al. (2017a). The Kormann and Meixner (2001) model is used to determine the probable area that a turbulent flux measurement was impacted by. This is a function of wind direction, stability, turbulence characteristics (friction velocity, variance of the lateral wind velocity) and roughness parameters.

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS Advanced

Introduction

The tutorial Urban Energy Balance - SUEWS Introduction should be completed first. This tutorial is designed to work with QGIS 2.18.

Objectives
  1. To explore the link between QGIS and SUEWS to include new site-specific information

  2. To examine how it affects the energy fluxes

Overview of steps
  1. Initially become familiar with SUEWS advanced which is a plugin that makes it possible for you to set all parameters that can be manipulated in SUEWS as well as execute the model on mutiple grids (Urban Energy Balance - SUEWS Spatial).

  2. Derive new surface information

  3. Run the model

How to Run from the UMEP-plugin

How to run SUEWS Advanced:

  1. Open the plugin which is located at UMEP -> Processor -> Urban Energy Balance -> Urban Energy Balance, SUEWS/BLUEWS (Advanced). This has most of the general settings (e.g. activate the snow module etc.) which are related to RunControl.nml.

  2. Use the Input folder:

    • C:/Users/your_user_name/.qgis2/python/plugins/UMEP/suewsmodel/Input

  3. Create or enter an Output directory of your choice.

  4. From the Input folder - confirm the data are in there.

  5. Tick in Obtain temporal… and set Temporal resolution of output (minutes) to 60.

  6. Click Run

  7. Make sure that output files are created.

  8. You can now close the SUEWS/BLUEWS (Advanced)-plugin again.

Interface for SUEWS Advanced version.

Interface for SUEWS Advanced version.

Sensitivity Test

The default dataset included in Suews Simple has parameters calculated from a source area model to obtain the appropriate values for the input parameters. Roughness parameters such as roughness length (z0) and zero plane displacement length (zd) are calculated using morphometric models. Now you will explore the differences in fluxes using the default settings or using input parameters from the geodata included in the test datasets available for this tutorial. Download the zip-file (see below) and extract the files to a suitable location where you both have reading and writing capabilities.

Data for the tutorial can be downloaded here

Geodata

Name

Ground and building DSM

DSM_LondonCity_1m.tif (m asl)

Vegetation DSM

CDSM_LondonCity_1m.tif (m agl)

DEM (digital elevation model)

DEM_LondonCity_1m.tif (masl)

Land cover

LC_londoncity_UMEP_32631

They are all projected in UTM 31N (EPSG:32631). The three surface models originate from a LiDAR dataset. The land cover data is a mixture of Ordnance Survey and the LiDAR data.

  1. Open the geodatasets. Go to Layer > Add layer > Add Raster Layer. Locate the files you downloaded before (see above).

  2. A QGIS style file (.qml) is available for the land cover grid. It can found in C:Usersyour_user_name.qgis2pythonpluginsUMEP\ LandCoverReclassifier\. Load it in the Layer > Properties > Style > Style (lower left) Load file.

  3. Click Apply before you close so that the names of the classes also load. You can also get the properties of a layer by right-click on a layer in the Layers-window.

  4. If you have another land cover dataset you can use the LandCoverReclassifier in the UMEP pre-processor to populate with the correct values suitable for the UMEP plugin environment.

  5. Now take a moment and investigate the different geodatasets. What is the sparial (pixel) resolution? How is ground represented in the CDSM?

Generating data from the geodatasets

  1. Make certain that you have the geodatafiles open. The file at the top (left hand side (LHS)) of the list is the one that is shown in the centre (figure below). You can swap their order using the LHS box.

  2. Open SUEWS Simple.

  3. Begin by adding the test dataset again.

  4. Update the building morphology parameters (top left panel in Suews Simple).

  5. To generate new values, click on Open tool.

  6. This is another plugin within UMEP that can be used to generate morphometric parameters

    None

    QGIS where Suews Simple and Image Morphometric Parameters (Point) is opened.

  7. First, clear the map canvas from your two other plugin windows, e.g. as figure above.

  8. If you use the default test data in SUEWS Simple - you can overwrite is as you go.

  9. Locate the eddy covariance tower position on the Strand building, King’s College London. To find the position, consult Figure 1 (KSS) in Kotthaus and Grimmond (2014).

  10. Use Select point on canvas and put a point at that location (left).

  11. Generate a study area. Use 500 m search distance, 5 degree interval and click Generate study area.

  12. A circular area will be considered. Enter the DSM and DEM files (i.e. the files you currently have in the viewer)

  13. Click Run.

    None

    Figure 3. Settings for Image Morphometric Parameters for buildings.

  14. In the folder you specified two additional files will be present (i) isotropic - averages of the morphometric parameters (ii) anisotropic - values for each wind sector you specified (5 degrees).

  15. Close this plugin

  16. Click on Fetch file from… in the building morphology panel

  17. Choose the isotropic file (just generated).

  18. Do the same for vegetation (upper left panel, right). See figure below.

  19. Instead of locating the point again you can use the existing point.

  20. You still need to generate a separate study area for the vegetation calculation.

  21. Examine the CDSM (vegetation file) in your map canvas. As you can see, this data has no ground heights (ground = 0). Therefore, this time Tick in the box Raster DSM (only buildings) exist.

  22. Enter the CDSM as your Raster DSM (only buildings).

    None

    Settings for Image Morphometric Parameters for vegetation

  23. A warning appears that your vegetation fractions between the morphology dataset and land cover dataset are large. You can ignore this for now since the land cover dataset also will change.

  24. Repeat the same procedure for land cover as you did for buildings and vegetation but instead using the Land Cover Fraction (Point) plugin.

  25. Enter the meteorological file, Year etc. This should be the same as for the first run you made.

  26. Now you are ready to run the model. Click Run.

If you get an error window (figure below). This error is generate by SUEWS as the sum of the land cover fractions is not 1. If you calculate carefully, one part of a thousand is missing (this is probably a rounding error during data extraction). To fix this issue: add 0.001 to e.g. bare soil. Now run again.

None

Possible error window from running SUEWS with new settings.

None

The settings for running with geodata derived parameters (old version of GUI).

You are now familiar with the Suews Simple plugin. Your next task is to choose another location within the geodataset domain, generate data and run the model. If you choose an area where the fraction of buildings and paved surfaces are low, consider lowering the population density to get more realistic model outputs. Compare the results for the different area.

References

  • Grimmond CSB and Oke 1999: Aerodynamic properties of urban areas derived, from analysis of surface form. Journal of Applied Climatology 38:9, 1262-1292

  • Grimmond et al. 2015: Climate Science for Service Partnership: China, Shanghai Meteorological Servce, Shanghai, China, August 2015.

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

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

  • Kormann R, Meixner FX 2001: An analytical footprint model for non-neutral stratification. Bound.-Layer Meteorol., 99, 207-224

  • Kotthaus S and Grimmond CSB 2014: Energy exchange in a dense urban environment - Part II: Impact of spatial heterogeneity of the surface. Urban Climate 10, 281–307

  • Onomura S, Grimmond CSB, Lindberg F, Holmer B, Thorsson S 2015: Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme. Urban Climate. 11:1-23 (link to paper)

  • Ward HC, L Järvi, S Onomura, F Lindberg, A Gabey, CSB Grimmond 2016 SUEWS Manual V2016a, http://urban-climate.net/umep/SUEWS Department of Meteorology, University of Reading, Reading, UK

  • Ward HC, Kotthaus S, Järvi L and Grimmond CSB 2016b: Surface Urban Energy and Water Balance Scheme (SUEWS): Development and evaluation at two UK sites. Urban Climate http://dx.doi.org/10.1016/j.uclim.2016.05.001

  • Ward HC, S Kotthaus, CSB Grimmond, A Bjorkegren, M Wilkinson, WTJ Morrison, JG Evans, JIL Morison, M Iamarino 2015b: Effects of urban density on carbon dioxide exchanges: observations of dense urban, suburban and woodland areas of southern England. Env Pollution 198, 186-200

Authors of this document: Lindberg and Grimmond (2016)

Definitions and Notation

To help you find further information about the acronyms they are classified by T: Type of term: C: computer term, S: science term, G: GIS term.

Definition

T

Reference/Comme nt

DEM

Digital elevation model

G

DSM

Digital surface model

G

FAI (λF)

Frontal area index

S

Grimmond and Oke (1999), their figure 2

GUI

Graphical User Interface

C

LAI

Leaf Area Index

S

PAI (λP)

Plan area index

S

png

Portable Network Graphics

C

format for saving plots/figures

QGIS

G

www.qgis.org

SUEWS

Surface Urban Energy and Water Balance Scheme

S

Tif

Tagged Image File Format

C

format for saving plots/figures

UI

user interface

C

UMEP

Urban Multi-scale Environmental predictor

C

z0

Roughness length for momentum

S

Grimmond and Oke (1999)

zd

Zero plane displacement length for momentum

S

Grimmond and Oke (1999)

Further explanation

Morphometric Methods to determine Roughness parameters:

For more and overview and details see Grimmond and Oke (1999). This uses the height and spacing of roughness elements (e.g. buildings, trees) to model the roughness parameters. UMEP has tools for doing this: Pre-processor -> Urban Morphology

Source Area Model

For more details see Kotthaus and Grimmond (2014b). The Kormann and Meixner (2001) model is used to determine the probable area that a turbulent flux measurement was impacted by. This is a function of wind direction, stability, turbulence characteristics (friction velocity, variance of the lateral wind velocity) and roughness parameters.

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS Spatial

Introduction

In this tutorial you will generate input data for the SUEWS model and simulate spatial (and temporal) variations of energy exchanges within a small area on Manhattan (New York City) with regards to a heat wave event.

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

This tutorial makes use of local high resolution detailed spatial data. If this kind of data are unavailable, other datasets such as local climate zones (LCZ) from the WUDAPT database could be used. The tutorial Urban Energy Balance - SUEWS and WUDAPT is available if you want to know more about using LCZs in SUEWS. However, it is strongly recommended to go through this tutorial before moving on to the WUDAPT/SUEWS tutorial.

Model output may be needed in many formats depending on a users’ needs. Thus, the format must be useful, while ensuring the science included within the model is appropriate. Fig. 9.13 shows the overall structure of UMEP, a city based climate service tool (CBCST) used in this tutorial. Within UMEP there are a number of models which can predict and diagnose a range of meteorological processes.

_images/SUEWSIntro_UMEP_overview.png

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

Note

This tutorial is currently designed to work with QGIS 2.18. It is recommended that you have a look at the tutorials Urban Energy Balance - SUEWS Introduction and Urban Energy Balance - SUEWS Advanced before you go through this tutorial.

Objectives

To perform and analyse energy exchanges within a small area on Manhattan, NYC.

Steps to be preformed
  1. Pre-process the data and create input datasets for the SUEWS model

  2. Run the model

  3. Analyse the results

  4. Perform simple mitigation measures to see how it affects the model results (optional)

Initial Steps

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

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

Loading and analyzing the spatial data

All the geodata used in this tutorial are from open access sources, primarily from the New York City. Information about the data are found in the table below.

Note

You can download the all the data from here. Unzip and place in a folder that you have read and write access to.

Spatial data used in this tutorial

Geodata

Year

Source

Description

Digital surface model (DSM)

2013 (Lidar), 2016 (building polygons)

United States Geological Survey (USGS). New York CMGP Sandy 0.7m NPS Lidar and NYC Open Data Portal. link

A raster grid including both buildings and ground given in meter above sea level.

Digital elevation model (DEM)

2013

United States Geological Survey (USGS). New York CMGP Sandy 0.7m NPS Lidar. link

A raster grid including only ground heights given in meter above sea level.

Digital canopy model (CDSM)

2013 (August)

United States Geological Survey (USGS). New York CMGP Sandy 0.7m NPS Lidar. link

A vegetation raster grid where vegetation heights is given in meter above ground level. Vegetation lower than 2.5 meter pixels with no vegetation should be zero.

Land cover (UMEP formatted)

2010

New York City Landcover 2010 (3ft version). University of Vermont Spatial Analysis Laboratory and New York City Urban Field Station. link

A raster grid including: 1. Paved surfaces, 2. Building surfaces, 3. Evergreen trees and shrubs, 4. Deciduous trees and shrubs, 5. Grass surfaces, 6. Bare soil, 7. Open water

Population density (residential)

2010

2010 NYC Population by Census Tracts, Department of City Planning (DCP). link)

People per census tract converted to pp/ha. Converted from vector to raster.

Land use

2018

NYC Department of City Planning, Technical Review Division. link

Used to redistribute population during daytime (see text). Converted from vector to raster

  • Start by loading all the raster datasets into an empty QGIS project.

The order in the Layers Panel determines what layer is visible. You can choose to show a layer (or not) with the tick box. You can modify layers by right-clicking on a layer in the Layers Panel and choose Properties. Note for example that that CDSM (vegetation) is given as height above ground (meter) and that all non-vegetated pixels are set to zero. This makes it hard to get an overview of all 3D objects (buildings and trees). QGIS default styling for a raster is using the 98 percentile of the values. Therefore, not all the range of the data is shown in the layer window to the left.

  • Right-click on your CDSM layer and go to Properties > Style and choose Singleband pseudocolor with a min value of 0 and max of 35. Choose a colour scheme of your liking.

  • Go to Transparency and add an additional no data value of 0. Click ok.

  • Now put your CDSM layer at the top and your DSM layer second in your Layers Panel. Now you can see both buildings and vegetation 3D object in your map canvas.

none

DSM and CDSM visible at the same time (click for larger image)

The land cover grid comes with a specific QGIS style file.

  • Right-click on the land cover layer (landcover_2010_nyc) and choose Properties. Down to the left you see a Style-button. Choose Load Style and open landcoverstyle.qml and click OK.

  • Make only your land cover class layer visible to examine the spatial variability of the different land cover classes.

The land cover grid has already been classified into the seven different classes used in most UMEP applications (see Land Cover Reclassifier). If you have a land cover dataset that is not UMEP formatted you can use the Land Cover Reclassifier found at UMEP > Pre-processor > Urban Land Cover > Land Cover Reclassifier in the menubar to reclassify your data.

Furthermore, a polygon grid (500 m x 500 m) to define the study area and individual grids is included (Grid_500m.shp). Such a grid can be produced directly in QGIS (e.g. Vector > Research Tools > Vector Grid) or an external grid can be used.

  • Load the vector layer Grid_500m.shp into your QGIS project.

  • In the Style tab in layer Properties, choose a Simple fill with a No Brush fill style to be able to see the spatial data within each grid.

  • Also, add the label IDs for the grid to the map canvas in Properties > Labels to make it easier to identify the different grid squares later on in this tutorial.

As you can see the grid does not cover the whole extent of the raster grids. This is to reduce computation time during the tutorial. One grid cell takes ~20 s to model with SUEWS with meteorological forcing data for a full year.

Meteorological forcing data

Meteorological forcing data are mandatory for most of the models within UMEP. The UMEP specific format is given in Table 9.2. Some of the variables are optional and if not available or needed should be set to -999. The columns can not be empty. The needed data for this tutorial are discussed below.

Variables included in UMEP meteorological input file.

No.

Header

Description

Accepted range

Comments

1

iy

Year [YYYY]

Not applicable

2

id

Day of year [DOY]

1 to 365 (366 if leap year)

3

it

Hour [H]

0 to 23

4

imin

Minute [M]

0 to 59

5

qn

Net all-wave radiation [W m-2]

-200 to 800

6

qh

Sensible heat flux [W m-2]

-200 to 750

7

qe

Latent heat flux [W m-2]

-100 to 650

8

qs

Storage heat flux [W m-2]

-200 to 650

9

qf

Anthropogenic heat flux [W m-2]

0 to 1500

10

U

Wind speed [m s-1]

0.001 to 60

11

RH

Relative Humidity [%]

5 to 100

12

Tair

Air temperature [°C]

-30 to 55

13

pres

Surface barometric pressure [kPa]

90 to 107

14

rain

Rainfall [mm]

0 to 30

(per 5 min) this should be scaled based on time step used

15

kdown

Incoming shortwave radiation [W m-2]

0 to 1200

16

snow

Snow [mm]

0 to 300

(per 5 min) this should be scaled based on time step used

17

ldown

Incoming longwave radiation [W m-2]

100 to 600

18

fcld

Cloud fraction [tenths]

0 to 1

19

wuh

External water use [m3]

0 to 10

(per 5 min) scale based on time step being used

20

xsmd

(Observed) soil moisture

0.01 to 0.5

[m3 m-3 or kg kg-1]

21

lai

(Observed) leaf area index [m2 m-2]

0 to 15

22

kdiff

Diffuse shortwave radiation [W m-2]

0 to 600

23

kdir

Direct shortwave radiation [W m-2]

0 to 1200

Should be perpendicular to the Sun beam. One way to check this is to compare direct and global radiation and see if kdir is higher than global radiation during clear weather. Then kdir is measured perpendicular to the solar beam.

24

wdir

Wind direction [°]

0 to 360

The meteorological dataset used in this tutorial (MeteorologicalData_NYC_2010.txt) is from NOAA (most of the meteorological variables) and NREL (solar radiation data). It consists of tab-separated hourly air temperature, relative humidity, incoming shortwave radiation, pressure, precipitation and wind speed for 2010. There are other possibilities within UMEP to acquire meteorological forcing data. The pre-processor plugin WATCH can be used to download the variables needed from the global WATCH forcing datasets (Weedon et al. 2011, 2014).

  • Open the meteorological dataset (MeteorologicalData_NYC_2010.txt) in a text editor of your choice. As you can see it does not include all the variables shown in Table 9.2. However, these variables are the mandatory ones that are required to run SUEWS. In order to format (and make a quality check) the data provided into UMEP standard, you will use the MetPreProcessor.

  • Open MetDataPreprocessor (UMEP> Pre-Processor -> Meteorological Data > Prepare existing data).

  • Load MeteorologicalData_NYC_2010.txt and make the settings as shown below. Name your new dataset NYC_metdata_UMEPformatted.txt.

none

The settings for formatting met data into UMEP format (click for a larger image)

  • Close the Metdata preprocessor and open your newly fomatted datset in a text editor of your choice. Now you see that the forcing data is structured into the UMEP pre-defined format.

  • Close your text file and move on to the next section of this tutorial.

Preparing input data for the SUEWS model

A key capability of UMEP is to facilitate preparation of input data for the various models. SUEWS requires input information to model the urban energy balance. The plugin SUEWS Prepare is for this purpose. This tutorial makes use of high resolution data but WUDAPT datasets in-conjuction with the LCZ Converter can be used (UMEP > Pre-Processor > Spatial data > LCZ Converter).

  • Open SUEWS Prepare (UMEP > Pre-Processor > SUEWS prepare).

none

The dialog for the SUEWS Prepare plugin (click for a larger image).

Here you can see the various settings that can be modified. You will focus on the Main Settings tab where the mandatory settings are chosen. The other tabs include the settings for e.g. different land cover classes, human activities etc.

There are 10 frames included in the Main Settings tab where 8 need to be filled in for this tutorial:

  1. Polygon grid

  2. Building morphology

  3. Tree morphology

  4. Land cover fractions

  5. Meteorological data

  6. Population density

  7. Daylight savings and UTC

  8. Initial conditions

The two optional frames (Land use fractions and Wall area) should be used if the ESTM model is used to estimate the storage energy term (Delta QS). In this tutorial we use the OHM modelling scheme so these two tabs can be ignored for now.

  • Close SUEWS Prepare

Building morphology

First you will calculate roughness parameters based on the building geometry within your grids.

  • Open UMEP > Pre-Processor > Urban Morphology > Morphometric Calculator (Grid).

  • Use the settings as in the figure below and press Run.

  • When calculation ids done, close the plugin.

Note

For mac users, use this workaround: manually create a directory, go into the folder above and type the folder name. It will give a warning “—folder name–” already exists. Do you want to replace it? Click replace.

none

The settings for calculating building morphology.

This operation should have produced 17 different text files; 16 (anisotrophic) that include morphometric parameters from each 5 degree section for each grid and one file (isotropic) that includes averaged values for each of the 16 grids. You can open build_IMPGrid_isotropic.txt and compare the different values for a park grid (3054) and an urban grid (3242). Header abbreviations are explained here.

Tree morphology

Now you will calculate roughness parameters based on the vegetation (trees and bushes) within your grids. As you noticed there is only one surface dataset for vegetation present (CDSM_nyc) and if you examine your land cover grid (landcover_2010_nyc) you can see that there is only one class of high vegetation (Deciduous trees) present with our model domain. Therefore, you will not separate between evergreen and deciduous vegetation in this tutorial. As shown in Table 9.1, the tree surface model represents height above ground.

  • Again, Open UMEP > Pre-Processor > Urban Morphology > Morphometric Calculator (Grid).

  • Use the settings as in the figure below and press Run.

  • When calculation is done, close the plugin.

_images/SUEWSSpatial_IMCGVeg.png

The settings for calculating vegetation morphology.

Land cover fractions

Moving on to land cover fraction calculations for each grid.

  • Open UMEP > Pre-Processor > Urban Land Cover > Land Cover Fraction (Grid).

  • Use the settings as in the figure below and press Run.

  • When calculation is done, close the plugin.

_images/SUEWSSpatial_LCF.png

The settings for calculating land cover fractions

Population density

Population density will be used to estimate the anthropogenic heat release (QF) in SUEWS. There is a possibility to use both night-time and daytime population densities to make the model more dynamic. You have two different raster grids for night-time (pop_nighttime_perha) and daytime (pop_daytime_perha), respectively. This time you will make use of QGIS built-in function to to acquire the population density for each grid.

  • Go to Plugins > Manage and Install Plugins and make sure that the Zonal statistics plugin is ticked. This is a build-in plugin which comes with the QGIS installation.

  • Close the Plugin manager and open Raster > Zonal Statistics > Zonal Statistics.

  • Choose your pop_daytime_perha layer as Raster layer and your Grid_500m and polygon layer. Use a Output column prefix of PPday and chose only to calculate Mean. Click OK.

  • Run the tool again but this time use the night-time dataset.

SUEWS Prepare

Now you are ready to organise all the input data into the SUEWS input format.

  • Open SUEWS Prepare

  • In the Polygon grid frame, choose your polygon grid (Grid_500m) and choose id as your ID field

  • In the Building morphology frame, fetch the file called build_IMPGrid_isotropic.txt.

  • In the Land cover fractions frame, fetch the file called lc_LCFG_isotropic.txt.

  • In the Tree morphology frame, fetch the file called veg_IMPGrid_isotropic.txt.

  • In the Meteorological data frame, fetch your UMEP formatted met forcing data text file.

  • In the Population density frame, choose the appropriate attributes created in the previous section for daytime and night-time population density.

  • In the Daylight savings and UTC frame, set start and end of the daylight saving to 87 and 304, respectively and choose -5 (i.e. the time zone).

  • In the Initial conditions frame, choose Winter (0%) in the Leaf Cycle, 100% Soil moisture state and nyc as a File code.

  • In the Anthropogenic tab, change the code to 771. This will make use of settings adjusted for NYC according to Sailor et al. 2015.

  • Choose an empty directory as your Output folder in the main tab.

  • Press Generate

  • When processing is finished, close SUEWS Prepare.

Running the SUEWS model in UMEP

To perform modelling energy fluxes for multiple grids, Urban Energy Balance - SUEWS Advanced can be used.

  • Open UMEP > Processor > Urban Energy Balance > SUEWS/BLUEWS, Advanced. Here you can change some of the run control settings in SUEWS. SUEWS can also be executed outside of UMEP and QGIS (see SUEWS Manual. This is recommended when modelling long time series (multiple years) of large model domains (many grid points).

  • Change the OHM option to [1]. This allows the anthropogenic energy to be partitioned also into the storage energy term.

  • Leave the rest of the combobox settings at the top as default and tick both the Use snow module and the Obtain temporal resolution… box.

  • Set the Temporal resolution of output (minutes) to 60.

  • Locate the directory where you saved your output from SUEWSPrepare earlier and choose an output folder of your choice.

  • Also, Tick the box Apply spin-up using…. This will force the model to run twice using the conditions from the first run as initial conditions for the second run.

  • Click Run. This computation will take a while so be patient.

Analysing model reults

UMEP has a tool for basic analysis of any modelling performed with the SUEWS model. The SUEWSAnalyser tool is available from the post-processing section in UMEP.

  • Open UMEP > Post-Processor > Urban Energy Balance > SUEWS Analyzer. There are two main sections in this tool. The Plot data-section can be used to make temporal analysis as well as making simple comparisins between two grids or variables. This Spatial data-section can be used to make aggregated maps of the output variables from the SUEWS model. This requires that you have loaded the same polygon grid into your QGIS project that was used when you prepared the input data for SUEWS using SUEWS Prepare earlier in this tutorial.

none

The dialog for the SUEWS Analyzer tool.

To access the output data from the a model run, the RunControl.nml file for that particular run must be located. If your run has been made through UMEP, this file can be found in your output folder. Otherwise, this file can be located in the same folder from where the model was executed.

  • In the top panel of SUEWS Analyzer, load the RunControl.nml located in the output folder.

You will start by plotting basic data for grid 3242 which is one of the most dense urban area in the World.

  • In the left panel, choose grid 3242 and year 2010. Tick plot basic data and click Plot. This will display some of the most essential variables such as radiation balance and budget etc. You can use the tools such as the zoom to examine a shorter time period more in detail.

none

Basic plot for grid 3242. Click on image for enlargement.

Notice e.g. the high QF values during winter as well as the low QE values throughout the year.

  • Close the plot and make the same kind of plot for grid 3054 which is a grid mainly within Central Park. Consider the differences between the plot generated for grid 3242. Close the plot when you are done.

In the left panel, there is also possibilities to examine two different variables in time, either from the same grid or between two different grid points. There is also possible to examine different parameters through scatterplots.

The right panel in SUEWS Analyzer can be used to perform basic spatial analysis on your model results by producing aggragated maps etc. using different variables and time spans. Sensible heat (QH) is one variable to visualise warm areas as it is a variable that show the amount of the available energy that will be partitioned into heat.

  • Make the settings as shown in the figure below but change the location where you will save your data on your own system.

none

The dialog for the SUEWS Analyzer tool to produce a mean QH for each grid. Click on image for enlargement.

Note that the warmest areas are located in the most dense urban environments and the coolest are found where either vegetation and/or water bodies are present. During 2010 there was a 3-day heat-wave event in the region around NYC that lasted from 5 to 8 July 2010 (Day of Year: 186-189).

  • Make a similar average map but this time of 2m air temperature and choose only the heat wave period. Save it as a separate geoTiff.

The influence of mitigation measures on the urban energy balance (optional)

There are different ways of manipulating the data using UMEP as well directly changing the input data in SUEWS to examine the influence of mitigation measures on the UEB. The most detailed way would be to directly changing the surface data by e.g. increasing the number of street trees. This can be done by e.g. using the TreeGenerator-plugin in UMEP. This method would require that you go through the workflow of this tutorial again before you do your new model run. Another way is to directly manipulate input data to SUEWS at grid point level. This can done by e.g. changing the land cover fractions in SUEWS_SiteSelect.txt, the file that includes all grid-specific information used in SUEWS.

  • Make a copy of your whole input folder created from SUEWSPRepare earlier and rename it to e.g. Input_mitigation.

  • In that folder remove all the files beginning with InitialConditions except the one called InitialConditionsnyc_2010.nml.

  • Open SUEWS_SiteSelect.txt in Excel (or similar software).

  • Now increace the fraction of decidious trees (Fr_DecTr) for grid 3242 and 3243 by 0.2. As the total land cover fraction has to be 1 you also need to reduce the paved fraction (Fr_Paved) by the same amount.

  • Save and close. Remember to keep the format (tab-separated text).

  • Create an empty folder called Output_mitigation

  • Open SuewsAdvanced and make the same settings as before but change the input and output folders.

  • Run the model.

  • When finished, create a similar average air temperature map for the heat event and compare the two maps. You can do a difference map by using the Raster Calculator in QGIS (Raster>Raster Calculator…).

Tutorial finished.

Note

Please report issues with the manual on the GitHub page.

Urban Energy Balance - SUEWS and WUDAPT

Introduction

Note

This tutorial is not ready for use. Work in progress.

In this tutorial you will generate input data for the SUEWS model and simulate spatial (and temporal) variations of energy exchanges within an area in New York City using local climate zones derived within the WUDAPT project. The World Urban Database and Access Portal Tools project is a community-based project to gather a census of cities around the world.

Note

This tutorial is currently designed to work with QGIS 2.18. It is strongly recommended that you goo through the Urban Energy Balance - SUEWS Spatial tutorial before you go through this tutrial.

Objectives

To prepare input data for the SUEWS model using a WUDAPT dataset and analyse energy exchanges within an area in New York City, US.

Initial Steps

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

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

Loading and analyzing the spatial data

Note

You can download the all the data from here. Unzip and place in a folder where you have read and write access to. The LCZ data for various cities are also available from the WUDAPT portal.

  • Start by loading the raster dataset (NYC_LCZ.tif) into an empty QGIS project. This dataset is referenced to the WGS84 CRS (ESPG:4326).

  • You can set the correct colors for your LCZ raster by opening the LCZ converter at UMEP > Pre-Processer > Spatial data > LCZ converter. In the upper right corner, choose the LCZ raster and press Color Raster and then close the LCZ Converter.

Vector grid generation

A vector polygon grid is required for specifying the extent and resolution of the modelling.You will make use of a built-in tool in QGIS to generate such a grid.

  1. First zoom in to Manhattan as shown in the figure below

none

Zoom in the Manhattan island.

  1. As WGS84 (EPSG:4326) is in degree coordinates and maybe you want to specify your grid in meters, you need to change the CRS of your current QGIS-project. Click on the globe at the bottom right of your QGIS window and select ESPG:26918 as your ‘on the fly’ CRS.

  2. Open vector grid at Vector > Research Tools > Vector grid.

  3. Select the extend of your canvas by clicking the … next to Grid extent (xmin, xmax, ymin, ymax) and select Use layer/canvas extent.

  4. Select Use Canvas Extent.

  5. As you can see the units in now in meters and not in degrees. Specify the desired grid spacing to 5000 meters. This will save time later on. Of course you can set it a much smaller number if you have the time to wait when the model performs the calculations later on.

  6. Make sure the output is in polygons, not lines.

  7. Create as temporary layer.

  8. Save your grid by right-click on the new layer in the Layers Panel and choose Save as…. Here it is very imporant that you save in the same CRS as you other layers (ESPG:4326). Save as a shape file.

Population density

Population density is required to estimate the anthropogenic heat release (QF) in SUEWS. There is a possibility to make use of both night-time and daytime population densities to make the model more dynamic. In this tutorial you will only use a night-time dataset. This dataset can be aqcuired from the Spatial Data Downloader in UMEP.

  1. Open de spatial downloader at UMEP > Pre-Processer > Spatial data > Spatial Data Downloader.

  2. Select population density and select the GPWv4: UN-Adjusted Population Density closest to the year you intend to model (2010). The values will be in (pp / square kilometer).

  3. Make sure your canvas is zoomed out to the entire LCZ map and click Use canvas extent

  4. Now click Get data.

  5. Save as a geoTiff (.tif) with the name GPWv4_2010.

  6. Now you need to calculate population density per grid in units pp/hectare. First open the QGIS built-in tool Zonal statistics (Raster > Zonal Statistics). If the tool is absent you need to activate it by going to Plugins > Manage and Install Plugins and add Zonal statistics plugin. Open the tool and make the settings as shown below. This will calulate mean population density per grid.

    none

    Settings for the Zonal statistics plugin.

  7. Open the attribute table for your Grid_5000m-layer (right-click on layer and choose (Open attribute Table).

  8. Click the abacus shaped symbol this is the Field calculator.

  9. Under Output field name write “pp_ha, the Output field type should be “Decimal number (real)”, and the Output Precision can be set to 2.

  10. In the expression dialog box write gpw_mean/100, here gpw_mean is the name of your population density field and the 100 is to convert the data from km2 to ha.

  11. Click OK and you should have a new field called “pp_ha”.

  12. Click the yellow pencil in the top left corner of the attribute table to stop editing and save your changes and close the attribute table.

LCZ converter

Now you will make use of the LCZ Converter-plugin to generate input data for the SUEWS model.

  1. Open the LCZ converter at UMEP > Pre-Processer > Spatial data > LCZ converter.

  2. Select the LCZ raster layer at ‘’ LCZ raster’’.

  3. Select the vector grid you have just created in step 3 at Vector grid and select the ID field of the polygon grid at ID field.

  4. By clicking Adjust default parameters you can edit the table. This table specifies the pervious, trees, grass, etc. fractions for each of the LCZ classes. For more information about each of the classes see LCZConverter. If you choose to edit the table, make sure all fractions add up to 1.0.

  5. If you are unsure about the exact fractions for each of the LCZ click the tab Pervious distribution. Select Same for all LCZ’s

none

Settings for the LCZ converter plugin.

  1. Now you can select your best estimate about the distribution of the pervious surface fractions for urban and the tree distribution for rural. In addition, also specify the expected height of the trees.

  2. Once you are satisfied click Update Table.

  3. Select add results to polygon.

  4. Add a file prefix if desired.

  5. Finally select an output folder where you would like to receive the text files and click Run.

Note

For mac users use this workaround: manually create a directory, go into the folder above and type the folder name. It will give a warning “—folder name–” already exists. Do you want to replace it? Click replace.

This should generate 3 text files, one with the land cover fractions, one with morphometric parameters for buildings and one for trees for each grid cell of the polygon grid.

SUEWS

Before running SUEWS, you will need to prepare some of the data required to run it.

  1. SUEWS prepare requires the grid CRS to be in metres not degrees, therefore we need to reproject the grid. Right-click the vector grid and click save as... Assign a different file name, use CRS ESPG:26918 and click OK.

  2. Open SUEWS prepare at: UMEP > Pre-Processer > SUEWS prepare.

  3. Under vector polygon grid specify your reprojected vector grid and the ID field.

  4. Select the location of the Meteorological file that was included in the input data, the building morphology (_build_), tree morphology (_veg_) and land cover fractions (_LCFGrid_) from the step above and the population density (pp_ha) in the dropdown list.

  5. Enter the start and end of day light savings time for 2010 and the UTC offset of New York.

  6. Specify the Leaf cycle = winter when initialising in January. Unless the user has better information initialise the Soil moisture state at 100 %.

  7. Select an output folder where the initial data to run SUEWS should be saved and press Generate.

  8. Open SUEWS at UMEP > Processer > Urban Energy Balance > Urban Energy Balance (SUEWS/BLUEWS, advanced). Using this for the first time, the system will ask you to download the latest version of SUEWS, click OK.

  9. Change the OHM option to [1]. This allows the anthropogenic energy to be partitioned also into the storage energy term.

  10. Leave the rest of the combobox settings at the top as default and tick both the Use snow module and the Obtain temporal resolution… box.

  11. Set the Temporal resolution of output (minutes) to 60.

  12. Locate the directory where you saved your output from SUEWSPrepare earlier and choose an output folder of your choice.

  13. Also, Tick the box Apply spin-up using…. This will force the model to run twice using the conditions from the first run as initial conditions for the second run.

  14. Click Run. This computation will take a while so be patient. If it only takes a very short time (a few seconds) the model has probably crashed. Please consult the problems.txt file for more information.

Analysing model reults

When the model has successfully run, it is time to look at some of the output of the model. The SUEWSAnalyser tool is available from the post-processing section in UMEP.

  1. To better visualise what would be interesting to plot, label the grid ID’s of your vector grid. Do this by right-clicking the vector grid, going to properties, under the Labels tab click Show labels for this layer, label with id and select a text format of your choosing.

  2. Open UMEP > Post-Processor > Urban Energy Balance > SUEWS Analyzer. There are two main sections in this tool. The Plot data-section can be used to make temporal analysis as well as making simple comparisins between two grids or variables. This Spatial data-section can be used to make aggregated maps of the output variables from the SUEWS model. This requires that you have loaded the same polygon grid into your QGIS project that was used when you prepared the input data for SUEWS using SUEWS Prepare earlier in this tutorial.

  3. To access the output data from the a model run, the RunControl.nml file for that particular run must be located. If your run has been made through UMEP, this file can be found in your output folder. Otherwise, this file can be located in the same folder from where the model was executed. In the top panel of SUEWS Analyzer, load the RunControl.nml located in the output folder.

Feel free to try plotting different variables, first let’s try and look at a variable for two different grid cells.

  1. Load the RunControl.nml located in the output folder.

  2. On the left hand specify a Grid cell that is largely urban, select Year to investigate. Select the desired time period and a variable, for example Sensible heat flux.

  3. Comparing with another less urbanised gridcell turn on include another variable and specify the desired Grid, selecting the same Variable (Sensible heat flux).

  4. Click plot.

none

Example of the comparison of the heat flux for two grid cell in the vector grid.

Now we will look at the horizontal distribution of the storage flux. #. On the right-hand side of SUEWS analyser specify the Net Storage flux as a variable to analyse. #. Select the Year to investigate and a time period during the summer season. #. Select the Median and Only daytime. #. Select the Vector polygon grid you have been using and save as a GeoTiff. #. Specify an output filename, and tick Add Geotiff to map canvas and Generate.

none

Example of the median, night-time net storage flux.

This should generate a geotiff file with a median, night-time net storage flux in the selected timeperiod.

Tutorial finished.

Note

Please report issues with the manual on the GitHub page.

Development, Suggestions and Support

If you are interested in contributing to the code please contact Sue Grimmond. Please follow Coding Guidelines for coding SUEWS.

Please provide your feedbacks via channels listed here.

Note

Please report issues with the manual on the GitHub page.

Coding Guidelines

If you are interested in contributing to the code please contact Sue Grimmond.

Coding

  1. Core physics and calculatoin schemes of SUEWS are written in Fortran 90

  2. Code is hosted in GitHub as private repository

  3. Variables

    • Names should be defined at least in one place in the code – ideally when defined

    • Implicit None should be used in all subroutines

    • Variable name should include units. e.g. Temp_C, Temp_K

    • Output variable attributes should be provided in the TYPE structure defined in the ctrl_output module as follows:

      : TYPE varAttr
      : CHARACTER(len = 15) :: header ! short name in headers
      : CHARACTER(len = 12) :: unit   ! unit
      : CHARACTER(len = 14) :: fmt    ! output format
      : CHARACTER(len = 50) :: longNm ! long name for detailed description
      : CHARACTER(len = 1)  :: aggreg ! aggregation method
      : CHARACTER(len = 10) :: group  ! group: datetime, default, ESTM, Snow, etc.
      : INTEGER             :: level  ! output priority level: 0 for highest (defualt output)
      : END TYPE varAttr
      
  4. Code should be written generally

  5. Data set for testing should be provided

  6. Demonstration that the model performance has improved when new code has been added or that any deterioration is warranted.

  7. Additional requirements for modelling need to be indicated in the manual

  8. All code should be commented in the program (with initials of who made the changes – name specified somewhere and institution)

  9. The references used in the code and in the equations will be collected to a webpage

  10. Current developments that are being actively worked on

Testing

  1. The testing of SUEWS is done using Python 3

  2. The following tests are done for each release of SUEWS:

  1. Working status of all physics schemes

  2. Year-grid looping logic

  3. Identity of output results with internal test dataset

Please use pre-defined make test option to check if your code can pass all tests or not. If not, the correctness of added code should be justified with caution.

Preparation of SUEWS Manual

  1. The SUEWS manual is written in reStructuredText (aka rst) with a Sphinx flavour

  2. The SUEWS manual is hosted by readthedocs.org

  3. CSV tables used in following pages are automatically generated from the Description field in Input Options by each build, so DON’T manually edit them as your edits will be swiped automatically:

F2PY tips

This includes several DON’T’s that have never been mentioned by F2PY docs:

  1. DON’T mix comments as lines into argument list of Fortran subroutines/functions:

DONT:

subroutine(&
! DONT DO this
args&
)

OK:

subroutine(&
args& ! OK this way
)

2. DON’T end a subroutine as ENDSUBROUTINE. Instead, leave a space in between to form END SUBROUTINE. Otherwise, the subroutines won’t be correctly parsed and picked up by F2PY.

Note

Please report issues with the manual on the GitHub page.

Suggestions and Support

Please provide your feedbacks via these channels:

Note

Please report issues with the manual on the GitHub page.

Benchmark Report

Since v2018a, SUEWS is benchmarked against observations for assessment of model performance. A site based benchmark report generation system is introduced in v2018c to produce detailed reports for testing sites; the number of sites is expanding and more cases will be added as they are benchmarked.

Each report includes the following parts:

  1. Overall performance:

  1. Performance Score: Large scores indicate better performance. The scores are calculated according to weighted averages of statistics for selected benchmark variables.

  2. Detailed Statistics: Grids are coloured based relative performance between different versions: a greener grid indicates better performance in the chosen variable using the specific release whereas a redder one shows poorer performance; and those with gray backgrounds indicate the same performance across different releases.

  1. Cross-comparison in model variables between releases:

  1. Detailed statistics tables: statistics for each variable.

  2. Pair plots: comparison in simulation results between different version-pairs.

  3. Time series plots: comparison in simulated monthly climatologies of diurnal cycles of each variable between different version-pairs.

The latest benchmark reports are available at the SUEWS Benchmark site.

Note

Please report issues with the manual on the GitHub page.

API

This link redirects to the SUEWS API site, which provides documentation of SUEWS source code automatically generated by Doxygen.

SUEWS developers are strongly suggested to use the API site as the main reference for understanding SUEWS source code.

Note

Please report issues with the manual on the GitHub page.

Version History

Note

Please report issues with the manual on the GitHub page.

Version 2019a (released on 11 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. Observed soil moisture can not be used as an input

    2. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2018c (released on 21 February 2019)

  • Improvement

    1. SuPy (SUEWS in Python): a Python-enhanced wrapper of SUEWS, which can facilitate a more fluent workflow of SUEWS-centred urban climate research. More details refer to SuPy documentation site.

    2. Improved benchmark report: More testing sites are added thanks to an automated benchmark report system.

  • Changes

    None.

  • Fix

    1. Fixed a bug in LAI calculation for longterm runs.

    2. Fixed a bug in net all-wave radiation differential calculation for OHM.

    3. Fixed water redistribution bug in snow module.

  • Known issues

    1. BLUEWS is disabled

    2. Observed soil moisture can not be used as an input

    3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2018b (released 17 December 2018)

  • Improvement

    1. Improved calculation of OHM-related radiation terms:

      The temporal difference term dQ*/dt is now calculated using the time-step-weighted dQ* of previous time step instead of a series of Q* values from previous time steps, which improves the usage of memory and allows time-step-varying simulations (needed by WRF-SUEWS coupling).

  • Changes

    None.

  • Fix

    1. Fixed a bug in picking up external water use from meteorological forcing file.

  • Known issues

    1. BLUEWS is disabled

    2. Observed soil moisture can not be used as an input

    3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2018a (released 2 August 2018)

  • New

    1. Many under-the-hood improvements:

      • Added explicit interface intent for confusion-less coupling between SUEWS modules

      • Restructured layout of physics schemes for better modularity

      • Improved the alignment in output txt files

    2. New readthedocs.org-based documentation system

    3. Added SUEWS input converter for conversion of input files between versions

    4. Added Benchmark Report for recent releases.

  • Improvement

    1. Improved the near surface diagnostics scheme (T2, Q2, U10)

    2. Improved skin temperature calculation (Ts)

  • Changes

    1. StabilityMethod: recommended option is change from 2 to 3 as options other than 3 have been noticed with numerical issues under several scenarios, which will be fixed in the next release.

    2. Model run - changes in selections moved from SUEWS_SiteSelect.txt to SUEWS_AnthropogenicHeat.txt: EnergyUseProfWD, EnergyUseProfWE, ActivityProfWD, ActivityProfWE.

    3. BiogenCO2Code is added to SUEWS_Veg.txt for looking up biogenic characteristics in the new SUEWS_BiogenCO2.txt file.

    4. TraifficRate and BuildEnergyUse in SUEWS_SiteSelect.txt are expanded to allow weekday and weekend values: TrafficRate_WD, TrafficRate_WE, QF0_BEU_WD, QF0_BEU_WE.

    5. AnthropCO2Method is removed from RunControl.nml.

    6. AnthropHeatMethod is renamed to EmissionsMethod.

    7. AHMin, AHSlope and TCritic are expanded to allow weekday and weekend values by adding _WD and _WE as suffix, of which AHSlope and TCritic are also expanded to allow cooling and heating settings.

  • Known issues

    1. BLUEWS is disabled

    2. Observed soil moisture can not be used as an input

    3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2017b (released 2 August 2017)

PDF Manual for v2017b

  1. Surface-level diagnostics: T2 (air temperature at 2 m agl), Q2 (air specific humidity at 2 m agl) and U10 (wind speed at 10 m agl) added as default output.

  2. Output in netCDF format. Please note this feature is NOT enabled in the public release due to the dependency of netCDF library. Assistance in enabling this feature may be requested to the development team via SUEWS mail list.

  3. Edits to the manual.

  4. New capabilities being developed, including two new options for calculating storage heat flux (AnOHM, ESTM) and modelling of carbon dioxide fluxes. These are currently under development and should not be used in Version 2017b.

  5. Known issues

    1. BLUEWS parameters need to be checked

    2. Observed soil moisture can not be used as an input

    3. Wind direction is not currently downscaled so non -999 values will cause an error.

Note

Please report issues with the manual on the GitHub page.

Version 2017a (Feb 2017)

  1. Changes to input file formats (including RunControl.nml and InitialConditions files) to facilitate setting up and running the model. Met forcing files no longer need two rows of -9 at the end to indicate the end of the file.

  2. Changes to output file formats (now option to write out only a subset of variables, rather than all variables).

  3. SUEWS can now disaggregate forcing files to the model time-step and aggregate output at the model time-step to lower resolution. This removes the need for the python wrapper used with previous versions.

  4. InitialConditions format and requirements changed. A single file can now be provided for multiple grids. SUEWS will approximate most (but not all) of the required initial conditions if values are unknown. (However, if detailed information about the initial conditions is known, this can still be provided to and used by SUEWS.)

  5. Leaf area index calculations now use parameters provided for each vegetated surface (previously only the deciduous tree LAI development parameters were applied to all vegetated surfaces).

  6. For compatibility with GIS, the sign convention for longitude has been changed. Now negative values are to the west, positive values are to the east. Note this appears to have been incorrectly coded in previous versions (but may not necessarily have been problematic).

  7. Storage heat flux calculation adapted for shorter (sub-hourly) model time-step: hysteresis calculation now based on running means over the previous hour.

  8. Improved error handling, including separate files for serious errors (problems.txt) and less critical issues (warnings.txt).

  9. Edits to the manual.

  10. New capabilities being developed, including two new options for calculating storage heat flux (AnOHM, ESTM) and modelling of carbon dioxide fluxes. These are currently under development and should not be used in Version 2017a.

Note

Please report issues with the manual on the GitHub page.

Version 2016a (released 21 June 2016)

PDF Manual for v2016a

  1. Major changes to the input file formats to facilitate the running of multiple grids and multiple years. Surface characteristics are provided in SUEWS_SiteSelect.txt and other input files are cross-referenced via codes or profile types.

  2. The surface types have been altered:

    • Previously, grass surfaces were entered separately as irrigated grass and unirrigated grass surfaces, whilst the ‘unmanaged’ land cover fraction was assumed by the model to behave as unirrigated grass. There is now a single surface type for grass (total for irrigated plus unirrigated) and a new bare soil surface type.

    • The proportion of irrigated vegetation must now be specified for grass, evergreen trees and deciduous trees individually.

  3. The entire model now runs at a time step specified by the user. Note that 5 min is strongly recommended. (Previously only the water balance calculations were done at 5 min with the energy balance calculations at 60 min).

  4. Surface conductance now depends on the soil moisture under the vegetated surfaces only (rather than the total soil moisture for the whole study area as previously).

  5. Albedo of evergreen trees and grass surfaces can now change with leaf area index as was previously possible for deciduous trees only.

  6. New suggestions in Troubleshooting section.

  7. Edits to the manual.

  8. CBL model included.

  9. SUEWS has been incorporated into UMEP

Note

Please report issues with the manual on the GitHub page.

Version 2014b (released 8 October 2014)

PDF Manual for v2014b

These affect the run configuration if previously run with older versions of the model:

  1. New input of three additional columns in the Meteorological input file (diffusive and direct solar radiation, and wind direction)

  2. Change of input variables in InitialConditions.nml file. Note we now refer to CT as ET (ie. Evergreen trees rather than coniferous trees)

  3. In GridConnectionsYYYY.txt, the site names should now be without the underscore (e.g Sm and not Sm_)

Other issues:

  1. Number of grid areas that can be modelled (for one grid, one year 120; for one grid two years 80)

  2. Comment about Time interval of input data

  3. Bug fix: Column headers corrected in 5 min file

  4. Bug fix: Surface state 60 min file - corrected to give the last 5 min of the hour (rather than cumulating through the hour)

  5. Bug fix: units in the Horizontal soil water transfer

  6. ErrorHints: More have been added to the problems.txt file.

  7. Manual: new section on running the model appropriately

  8. Manual: notation table updated

  9. Possibility to add snow accumulation and melt: new paper

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

Note

Please report issues with the manual on the GitHub page.

Version 2014a.1 (released 26 February 2014)

  1. Please see the large number of changes made in the Version 2014a release.

  2. This is a minor change to address installing the software.

  3. Minor updates to the manual

Note

Please report issues with the manual on the GitHub page.

Version 2014a (released 21 February 2014)

  1. Bug fix: External irrigation is calculated as combined from automatic and manual irrigation and during precipitation events the manual irrigation is reduced to 60% of the calculated values. In previous version of the model, the irrigation was in all cases taken 60% of the calculated value, but now this has been fixed.

  2. In previous versions of the model, irrigation was only allowed on the irrigated grass surface type. Now, irrigation is also allowed on evergreen and deciduous trees/shrubs surfaces. These are not however treated as separate surfaces, but the amount of irrigation is evenly distributed to the whole surface type in the modelled area. The amount of water is calculated using same equation as for grass surface (equation 5 in Järvi et al. Version 2011), and the fraction of irrigated trees/shrubs (relative to the area of tree/shrubs surface) is set in the gis file (See Table 4.11: SSss_YYYY.gis)

  3. In the current version of the model, the user is able to adjust the leaf-on and leaf-off lengths in the FunctionalTypes. nml file. In addition, user can choose whether to use temperature dependent functions or combination of temperature and day length (advised to be used at high-latitudes)

  4. In the gis-file, there is a new variable Alt that is the area altitude above sea level. If not known exactly use an approximate value.

  5. Snow removal profile has been added to the HourlyProfileSSss_YYYY.txt. Not yet used!

  6. Model time interval has been changed from minutes to seconds. Preferred interval is 3600 seconds (1 hour)

  7. Manual correction: input variable Soil moisture said soil moisture deficit in the manual – word removed

  8. Multiple compiled versions of SUEWS released. There are now users in Apple, Linux and Windows environments. So we will now release compiled versions for more operating systems (section 3).

  9. There are some changes in the output file columns so please, check the respective table of each used output file.

  10. Bug fix: with very small amount of vegetation in an area – impacted Phenology for LUMPS

Note

Please report issues with the manual on the GitHub page.

Version 2013a

  1. Radiation selection bug fixed

  2. Aerodynamic resistance – when very low - no longer reverts to neutral (which caused a large jump) – but stays low

  3. Irrigation day of week fixed

  4. New error messages

  5. min file – now includes a decimal time column – see Section 5.4 – Table 5.3

Note

Please report issues with the manual on the GitHub page.

Version 2012b

  1. Error message generated if all the data are not available for the surface resistance calculations

  2. Error message generated if wind data are below zero plane displacement height.

  3. All error messages now written to ‘Problem.txt’ rather than embedded in an ErrorFile. Note some errors will be written and the program will continue others will stop the program.

  4. Default variables removed (see below). Model will stop if any data are problematic. File should be checked to ensure that reasonable data are being used. If an error occurs when there should not be one let us know as it may mean we have made the limits too restrictive.

Contents no longer used File defaultFcld=0.1 defaultPres=1013 defaultRH=50 defaultT=10 defaultU=3 RunControl.nml

  • Just delete lines from file

  • Values you had were likely different from these example value shown here

Note

Please report issues with the manual on the GitHub page.

Version 2012a

  1. Improved error messages when an error is encountered. Error message will generally be written to the screen and to the file ‘problems.txt’

  2. Format of all input files have changed.

  3. New excel spreadsheet and R programme to help prepare required data files. (Not required)

  4. Format of coef flux (OHM) input files have changed.

    • This allows for clearer identification for users of the coefficients that are actually to be used

    • This requires an additional file with coefficients. These do not need to be adjusted but new coefficients can be added. We would appreciate receiving additional coefficients so they can be included in future releases – Please email Sue.

  5. Storage heat flux (OHM) coefficients can be changed by

    • time of year (summer, winter)

    • surface wetness state

  6. New files are written: DailyState.txt

    • Provides the status of variables that are updated on a daily or basis or a snapshot at the end of each day.

  7. Surface Types

    • Clarification of surface types has been made. See GIS and OHM related files

Note

Please report issues with the manual on the GitHub page.

Version 2011b

  1. Storage heat flux (ΔQs) and anthropogenic heat flux (QF) can be set to be 0 W m-2

  2. Calculation of hydraulic conductivity in soil has been improved and HydraulicConduct in SUEWSInput.nml is replaced with name SatHydraulicConduct

  3. Following removed from HeaderInput.nml

    • HydraulicConduct

    • GrassFractionIrrigated

    • PavedFractionIrrigated

    • TreeFractionIrrigated

The lower three are now determined from the water use behaviour used in SUEWS

  1. Following added to HeaderInput.nml

    • SatHydraulicConduct

    • defaultQf

    • defaultQs

  2. If ΔQs and QF are not calculated in the model but are given as an input, the missing data is replaced with the default values.

  3. Added to SAHP input file

    • AHDIUPRF – diurnal profile used if EmissionsMethod = 1

Version 2012a this became obsolete OHM file (SSss_YYYY.ohm)

Note

Please report issues with the manual on the GitHub page.

Acknowledgements

Contributors

Name

Affiliation

Contributions

Versions

Remarks

Prof Sue Grimmond

University of Reading, UK; prior: Indiana University, USA, King’s College London, UK, University of British Columbia, Canada

OHM, Evaporation-Interception, Resistances, NARP, irrigation, anthropogenic heat, etc

v2011b – v2019a

Team Leader

Dr Ting Sun

University of Reading, UK

AnOHM; Documentation system; WRF-SUEWS coupling; SuPy (python wrapper of SUEWS)

v2017b – v2019a

Current Lead Developer

Dr Leena Järvi

University of Helsinki, Finland

Snow-related physics; Anthropogenic emission calculation, CO2

v2011b – v2019a

Lead Developer of v2011b – v2014b

Dr Helen Ward

University of Reading, UK

OHM improvement; Resistance calculation; Anthropogenic heat calculation

v2016a - v2017b

Lead Developer of v2016a - v2017

Dr Fredrik Lindberg

Göteborg University, Sweden

UMEP-related work, NARP, ESTM

v2011b – v2019a

Lead Developer of UMEP

Dr Hamidreza Omidvar

University of Reading, UK

WRF-SUEWS coupling; Documentation system

v2018c – v2019a

Major contributor to WRF(v4.0)-SUEWS(v2018c) coupling

Minttu P. Havu

University of Helsinki, Finland

CO2

v2018c – v2019a

Dr Zhenkun Li

Shanghai Climate Centre, China

WRF-SUEWS coupling

v2018b – v2018c

Major contributor to WRF(v3.9)-SUEWS(v2018b) coupling

Yihao Tang

University of Reading, UK

Stability, air temperature

v2018b - v2018c

Dr Shiho Onomura

Göteborg University, Sweden

BLUEWS, ESTM

v2016a

Dr Thomas Loridan

King’s College London, UK

NARP

v2011a

Dr Brian Offerle

Indiana University, USA

ESTM, NARP

v2011a

Dependency Libraries

Note

We gratefully acknowledge the libraries/code that SUEWS uses as dependency and greatly appreciate their developers for the excellent work. Please let us know if any inapproriate use of these code and we will remove/modify the related parts accordingly.

Library

Remarks

datetime-fortran

date and time related processsing

minpack

AnOHM-related sinusoidal curve fitting

Recursive Fortran 95 quicksort routine

netCDF output for QGIS-compliant grid layout

Fortran Strings Module by Dr George Benthien

string processing

Funding

Note

The following grants are acknowledged for their contribution to model development (D) and/or supportive observations (O).

Funder

Project

D , O

NERC

APEx

D

NERC

COSMA NE/S005889/

D

UKRI

GCRF Urban Disaster Risk Hub

D

Newton/Met Office

CSSP-China (AJYG-DX4P1V HRC,AJYF-2GLAMK EUN, others)

D, O

NERC

ClearfLo Clean Air for London NE/H003231/1

O

NERC/Belmont

TRUC NE/L008971/1, G8MUREFU3FP-2201-075

D, O

EPSRC

LoHCool Low carbon climate-responsive Heating and Cooling of Cities EP/N009797/1

D

NERC

Independent Research Fellowship

D

NSF

BCS-0095284, ATM-0710631, BCS-0221105

D, O

EPSRC

Data Assimilation for the REsilient City (DARE) EP/P002331/1

O

Royal Society/Newton

Mobility funding

O

H2020

UrbanFluxes (637519)

D, O

EUf7

BRIDGE (211345)

D, O

EUf7

emBRACE (283201)

D, O

University of Reading

Sue Grimmond

O, D

KCL

Sue Grimmond

O

EPSRC

EP/I00159X/1 EP/I00159X/2 Materials Innovation Hub: Connecting Materials Culture to Materials Science

O

NERC

Field Spectroscopy Facility (FSF) 616.1110 Investigating the Urban Energy Balance of London

O

EUf7

MEGAPOLI 212520

D

NERC

Airborne Remote Sensing Facility & Field Spectroscopy Facility (GB08/19)

O

CFCAS

Environmental Prediction for Canadian Cities

D, O

Note

Please report issues with the manual on the GitHub page.

Notation

λF

Frontal area index

ΔQS

Storage heat flux

BLUEWS

Boundary Layer part of SUEWS

Relation between BLUEWS and SUEWS

Relation between BLUEWS and SUEWS

CDD

Cooling degree days

GDD

Growing degree days

HDD

Heating degree days

Bldgs

Building surface

CBL

Convective boundary layer

DEM

Digital Elevation Model

DSM

Digital surface model

DTM

Digital Terrain Model

DecTr

Deciduous trees and shrubs

EveTr

Evergreen trees and shrubs

ESTM

Element Surface Temperature Method (Offerle et al.,2005 [OGF2005])

Grass

Grass surface

BSoil

Unmanaged land and/or bare soil

Runoff

The water that drains freely off the impervious surface

SoilStore

The water stored in the underlying soil that infiltrates from the pervious surface

L↓

Incoming longwave radiation

LAI

Leaf area index

LUMPS

Local-scale Urban Meteorological Parameterization Scheme (Loridan et al. 2011 [L2011])

MU

Parameters which must be supplied and must be specific for the site/grid being run.

MD

Parameters which must be supplied and must be specific for the site/grid being run (but default values may be ok if these values are not known specifically for the site).

O

Parameters that are optional, depending on the model settings in RunControl.nml. Set any parameters that are not used/not known to ‘-999’.

L

Codes that are used to link between the input files. These codes are required but their values are completely arbitrary, providing that they link the input files in the correct way. The user should choose these codes, bearing in mind that the codes they match up with in column 1 of the corresponding input file must be unique within that file. Codes must be integers. Note that the codes must match up with column 1 of the corresponding input file, even if those parameters are not used (in which case set all columns except column 1 to ‘-999’ in the corresponding input file), otherwise the model run will fail.

NARP

Net All-wave Radiation Parameterization (Offerle et al. 2003 [O2003], Loridan et al. 2011 [L2011])

OHM

Objective Hysteresis Model (Grimmond et al. 1991 [G91OHM], Grimmond & Oke 1999a [GO99QS], 2002 [GO2002])

Paved

Paved surface

Q*

Net all-wave radiation

QE

Latent heat flux

QF

Anthropogenic heat flux

QH

Sensible heat flux

SOLWEIG

The solar and longwave environmental irradiance geometry model (Lindberg et al. 2008 [FL2008], Lindberg and Grimmond 2011 [FL2011])

SVF

Sky view factor

θ

Potential temperature

tt

Time step of data

UMEP

Urban Multi-scale Environmental Predictor

Water

Water surface

WATCH

The WATCH project has produced a large number of data sets which should be of considerable use in regional and global studies of climate and water. see WATCH webpage

zi

Convective boundary layer height

Note

Please report issues with the manual on the GitHub page.

References

J11

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

W16

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

G91

Grimmond CSB & Oke TR (1991) An Evaporation-Interception Model for Urban Areas. Water Resour. Res. 27, 1739-1755.

O2003

Offerle B, Grimmond CSB & Oke TR (2003) Parameterization of Net All-Wave Radiation for Urban Areas. J. Appl. Meteorol. 42, 1157-1173.

L2011

Loridan T, CSB Grimmond, BD Offerle, DT Young, T Smith, L Järvi, F Lindberg (2011) Local-Scale Urban Meteorological Parameterization Scheme (LUMPS): longwave radiation parameterization & seasonality related developments. Journal of Applied Meteorology & Climatology 50, 185-202, doi: 10.1175/2010JAMC2474.1

lucy

Allen L, F Lindberg, CSB Grimmond (2011) Global to city scale model for anthropogenic heat flux, International Journal of Climatology, 31, 1990-2005.

lucy2

Lindberg F, Grimmond CSB, Nithiandamdan Y, Kotthaus S, Allen L (2013) Impact of city changes and weather on anthropogenic heat flux in Europe 1995–2015, Urban Climate,4,1-13 paper

I11

Iamarino M, Beevers S & Grimmond CSB (2011) High-resolution (space, time) anthropogenic heat emissions: London 1970-2025. International J. of Climatology. 32, 1754-1767.

G91OHM

Grimmond CSB, Cleugh HA & Oke TR (1991) An objective urban heat storage model and its comparison with other schemes. Atmos. Env. 25B, 311-174.

GO99QS

Grimmond CSB & Oke TR (1999a) Heat storage in urban areas: Local-scale observations and evaluation of a simple model. J. Appl. Meteorol. 38, 922-940.

GO2002

Grimmond CSB & Oke TR (2002) Turbulent Heat Fluxes in Urban Areas: Observations and a Local-Scale Urban Meteorological Parameterization Scheme (LUMPS) J. Appl. Meteorol. 41, 792-810.

AnOHM17

Sun T, Wang ZH, Oechel W & Grimmond CSB (2017) The Analytical Objective Hysteresis Model (AnOHM v1.0): Methodology to Determine Bulk Storage Heat Flux Coefficients. Geosci. Model Dev. Discuss. doi: 10.5194/gmd-2016-300.

OGF2005

Offerle B, CSB Grimmond, K Fortuniak (2005) Heat storage & anthropogenic heat flux in relation to the energy balance of a central European city center. International J. of Climatology. 25: 1405–1419 doi: 10.1002/joc.1198

G86

Grimmond CSB, Oke TR and Steyn DG (1986) Urban water-balance 1. A model for daily totals. Water Resour Res 22: 1397-1403.

Leena2014

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

CG2001

Cleugh HA & Grimmond CSB (2001) Modelling regional scale surface energy exchanges and CBL growth in a heterogeneous, urban-rural landscape. Bound.-Layer Meteor. 98, 1-31.

Shiho2015

Onomura S, Grimmond CSB, Lindberg F, Holmer B & Thorsson S (2015) Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme Urban Climate,11, 1-23 doi:10.1016/j.uclim.2014.11.001

FL2008

Lindberg F, Holmer B & Thorsson S (2008) SOLWEIG 1.0 – Modelling spatial variations of 3D radiant fluxes and mean radiant temperature in complex urban settings. International Journal of Biometeorology 52, 697–713.

FL2011

Lindberg F & Grimmond C (2011) The influence of vegetation and building morphology on shadow patterns and mean radiant temperature in urban areas: model development and evaluation. Theoretical and Applied Climatology 105:3, 311-323.

Ko17

Kokkonen TV, Grimmond CSB, Räty O, Ward HC, Christen A, Oke TR, Kotthaus S & Järvi L (in review) Sensitivity of Surface Urban Energy and Water Balance Scheme (SUEWS) to downscaling of reanalysis forcing data.

Best2014

Best MJ & Grimmond CSB (2014) Importance of initial state and atmospheric conditions for urban land surface models’ performance. Urban Climate 10: 387-406. doi: 10.1016/j.uclim.2013.10.006.

D74

Dyer AJ (1974) A review of flux-profile relationships. Boundary-Layer Meteorol. 7, 363-372.

VUH85

Van Ulden AP & Holtslag AAM (1985) Estimation of atmospheric boundary layer parameters for boundary layer applications. J. Clim. Appl. Meteorol. 24, 1196-1207.

CN1988

Campbell GS & Norman JM (1998) Introduction to Environmental Biophysics. Springer Science, US.

B71

Businger JA, Wyngaard JC, Izumi Y & Bradley EF (1971) Flux-Profile Relationships in the Atmospheric Surface Layer. J. Atmos. Sci., 28, 181–189.

Ka09

Kawai T, Ridwan MK & Kanda M (2009) Evaluation of the simple urban energy balance model using selected data from 1-yr flux observations at two cities. J. Appl. Meteorol. Clim. 48, 693-715.

VG00

Voogt JA & Grimmond CSB (2000) Modeling surface sensible heat flux using surface radiative temperatures in a simple urban terrain. J. Appl. Meteorol. 39, 1679-1699.

Ka07

Kanda M, Kanega M, Kawai T, Moriwaki R & Sugawara H (2007). Roughness lengths for momentum and heat derived from outdoor urban scale models. J. Appl. Meteorol. Clim. 46, 1067-1079.

GO99

Grimmond CSB & Oke TR (1999) Aerodynamic properties of urban areas derived from analysis of surface form. J. Appl. Meteorol. 38, 1262-1292.

Mc98

MacDonald RW, Griffiths RF & Hall DJ (1998) An improved method for estimation of surface roughness of obstacle arrays. Atmos. Env. 32, 1857-1864.

FN78

Falk J & Niemczynowicz J, (1978) Characteristics of the above ground runoff in sewered catchments, in Urban Storm Drainage, edited by Helliwell PR, Pentech, London

Ha79

Halldin S, Grip H & Perttu K. (1979) Model for energy exchange of a pine forest canopy. In: Halldin S (Ed.), Comparison of Forest Water and Energy Exchange Models. International Society of Ecological Modeling

CW86

Calder IR and Wright IR (1986) Gamma Ray Attenuation Studies of Interception From Sitka Spruce: Some Evidence for an Additional Transport Mechanism. Water Resour. Res., 22(3), 409–417.

Ok87

Oke TR (1987) Boundary Layer Climates. Routledge, London, UK

Br03

Breuer L, Eckhardt K and Frede H-G (2003) Plant parameter values for models in temperate climates. Ecol. Model. 169, 237-293.

Ja76

Jarvis PG (1976) The interpretation of the variations in leaf water potential and stomatal conductance found in canopies in the field. Philos. Trans. R. Soc. London, Ser. B., 273, 593-610.

Au74

Auer AH (1974) The rain versus snow threshold temperatures. Weatherwise, 27, 67.

SV06

Sailor DJ and Vasireddy C (2006) Correcting aggregate energy consumption data account for variability in local weather. Environ. Modell. Softw. 21, 733-738.

Ko14

Konarska J, Lindberg F, Larsson A, Thorsson S and Holmer B (2014) Transmissivity of solar radiation through crowns of single urban trees—application for outdoor thermal comfort modelling. Theor Appl Climatol 117:363–376.

Re90

Reindl DT, Beckman WA and Duffie JA (1990) Diffuse fraction correlation. Sol Energy 45:1–7.

LG2012

Loridan T and Grimmond CSB (2012) Characterization of energy flux partitioning in urban environments: links with surface seasonal properties. J. of Applied Meteorology and Climatology 51,219-241 doi: 10.1175/JAMC-D-11-038.1

H1988

Högström U (1988) Non-dimensional wind and temperature profiles in the atmospheric surface layer: A re-evaluation. Boundary-Layer Meteorol. 42, 55–78.

Kent2017a

Kent CW, CSB Grimmond, J Barlow, D Gatey, S Kotthaus, F Lindberg, CH Halios 2017a: Evaluation of urban local-scale aerodynamic parameters: implications for the vertical profile of wind and source areas Boundary Layer Meteorology 164,183–213 doi: 10.1007/s10546-017-0248-z

Kent2017b

Kent CW, S Grimmond, D Gatey 2017b: Aerodynamic roughness parameters in cities: inclusion of vegetation Journal of Wind Engineering & Industrial Aerodynamics doi: 10.1016/j.jweia.2017.07.016

S2000

Schmid HP, Grimmond CSB, Cropley F, Offerle B, Su H (2000) Measurements of CO2 and energy fluxes over a mixed hardwood forest in the mid-westerm United States. Agricultural and Forest Meteorology. 103, 357-374.

R95

Ruimy A, Jarvis PG, Baldocchi DD, Saugier B (1995) CO2 Fluxes over Plant Canopies and Solar Radiation: A Review. Advances in Ecological Research, 26.

SL04

Sailor DJ, Lu L (2004) A top-down methodology for developing diurnal and seasonal anthropogenic heating profiles for urban areas. Atmospheric Environment. 38, 2737-2648.

B2017

Bellucco V, Marras S, Grimmond CSB, Jarvi L, Sirca C, Spano D (2017) Modelling the biogenic CO2 exchange in urban and non-urban ecosystems through the assessment of light-response curve parameters. Agricultural and Forest Meteorology. 236, 113-122.

FWC2002

Flanagan LB, Wever LA, Carlson PJ (2002) Seasonal and interannual variation in carbon dioxide exchange and carbon balance in a northern temperate grassland. Global Change Biology. 8, 599-615.

J12

Järvi L, Nordbo A, Junninen H, Riikonen A, Moilanen J, Nikinmaa E, Vesala T (2012) Seasonal and annual variation of carbon dioxide surface fluxes in Helsinki, Finland, in 2006-2010. Atmos. Chem. Phys. 12, 8475-8489.

B05

Brutsaert, W. (2005), Hydrology: an introduction, Cambridge Univ Pr, Cambridge.

HF07

Harman IN, Finnigan JJ (2007) A simple uni ed theory for flow in the canopy and roughness sublayer. Boundary-Layer Meteorol 123(2):339–363

HF08

Harman, IN, Finnigan, JJ (2008) Scalar concentration profiles in the canopy and roughness sublayer. Boundary-layer meteorol, 129(3), 323–351.

T19

Theeuwes NE, Ronda RJ, Harman IN, Christen A, Grimmond CSB (2019) Parametrizing Horizontally Averaged Wind and Temperature Profiles in the Urban Roughness Sublayer. Boundary-Layer Meteorol, 173: 321. https://doi.org/10.1007/s10546-019-00472-1

J19

Järvi, L., Havu, M., Ward, H. C., Bellucco, V., McFadden, J. P., Toivonen, T., et al. (2019). Spatial modeling of local‐scale biogenic and anthropogenic carbon dioxide emissions in Helsinki. Journal of Geophysical Research: Atmospheres, 124. https://doi.org/10.1029/2018JD029576