Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

SUEWS: Surface Urban Energy and Water Balance Scheme#

Documentation Status

What is SUEWS?#

Surface Urban Energy and Water Balance Scheme (SUEWS) [Järvi et al., 2011, Ward et al., 2016] is a neighbourhood/local-scale urban land surface model to simulate the urban radiation, energy and water balances using only commonly measured meteorological variables and information about the surface cover. SUEWS utilises an evaporation-interception approach [Grimmond and Oke, 1991], 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 seven surface types considered in SUEWS

The seven surface types considered in SUEWS#

How to get SUEWS?#

Please follow the guidance in Installation to get SUEWS.

How to use SUEWS?#

  • For existing users:

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

    Tip

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

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

  • For new users:

    Before performing SUEWS simulations, new users should read the overview Introduction, then follow the steps in Workflow of using SUEWS to prepare input files for SUEWS.

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

How to get help in using SUEWS?#

Please let us know in the UMEP Community. The developers and other users are willing to help you.

How has SUEWS been used?#

The scientific details and application examples of SUEWS can be found in SUEWS-related Publications.

How to cite SUEWS?#

Please go to our Zenodo repository for a proper citation of SUEWS.

Tip

Visit the repositories below for different citation styles.

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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Installation#

Formal releases#

Since 2023, SUEWS is available as a command line tool via its Python wrapper package SuPy (SUEWS in Python) on PyPI and conda-forge.

Note

The Fortran-based binaries build prior to 2023 are still available at the SUEWS download page. However, they are not maintained anymore so users are encouraged to use the Python-based packages instead.

Installing Python#

These instructions will set you up with mamba, which makes it easy to install and manage Python packages.

To install the mamba Python distribution follow the mamba installation instructions.

This makes installing supy and many other packages in the scientific Python ecosystem much easier and quicker. It also provides many pre-compiled binaries that are not available on PyPI.

Tip

mamba is a drop-in replacement for conda (another widely used Python package manager): mamba is faster and solves some common problems with conda. More details about mamba can be found at mamba.

Installing SuPy#

One can install supy using pip:

python3 -m pip install supy --upgrade

Development build#

The development build can be highly unstable and is not recommended for production use. However, it is automatically constructed every week for testing purposes and we are happy to receive feedback on the development build.

To install the development build of SUEWS, you need to install supy in the development mode:

  1. git clone the repository:

    git clone https://github.com/UMEP-dev/SUEWS.git
    
  2. navigate to the directory of the cloned repository:

    cd SUEWS
    
  3. install the package in the development mode:

    make dev
    

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Workflow of using SUEWS#

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, C. S. B., Taka, M., Nordbo, A., Setälä, H., and Strachan, I. B. Development of the surface urban energy and water balance scheme (SUEWS) for cold climate cities. Geosci. Model Dev., 7(4):1691–1711, August 2014. doi:10.5194/gmd-7-1691-2014.

  • Järvi, L., Grimmond, C.S.B., and Christen, A. The surface urban energy and water balance scheme (SUEWS): Evaluation in Los Angeles and Vancouver. J. Hydrol., 411(3-4):219–237, December 2011. doi:10.1016/j.jhydrol.2011.10.001.

  • Ward, H.C., Kotthaus, S., Järvi, L., and Grimmond, C.S.B. Surface urban energy and water balance scheme (SUEWS): Development and evaluation at two UK sites. Urban Clim., 18:1–32, December 2016. doi:10.1016/j.uclim.2016.05.001.

See other publications with example applications

Decide what type of model run you are interested in#

Available in this release

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

Download the program and example data files#

Visit the SUEWS download page to receive a link to download the program and example data files. Select the appropriate compiled version for your platform to download. There is also a python-based version in UMEP under the QGIS environment. For python users, SuPy - a python wrapper for SUEWS - is also available.

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 shipped in the archive with the SUEWS executable, which are based on measurements of 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_***.txt

Property look-up tables

Input text files 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#

Tip

If you need help preparing the data you can use some of the UMEP tools.

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

  • Continuous meteorological forcing data for the entire period to be modelled without gaps.

  • Knowledge of the surface and soil conditions immediately prior to the first model timestep.

    Note

    If these initial conditions are unknown, model spin-up 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). Spin-up is important for getting appropriate initial conditions for the model. An example of a spin-up can be found in Kokkonen et al. [2018].

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

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

    Note

    For guidance on how to derive parameters related to LAI, albedo, surface conductance and surface roughness, the reader is referred to this link.

  • Information about human behaviour, including energy use and water use (e.g. for irrigation or street cleaning) and snow clearing (if applicable).

    Note

    The anthropogenic energy use and water use may be provided as a time series in the meteorological forcing file (by setting EmissionsMethod = 0) 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 [Ward et al., 2016]

  • Accurate meteorological forcing data, particularly precipitation and incoming shortwave radiation [Kokkonen et al., 2018]

  • Initial soil moisture conditions [Best and Grimmond, 2014]

  • Anthropogenic heat flux parameters, particularly if there are considerable energy emissions from transport, buildings, metabolism, etc [Ward et al., 2016].

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

  • Snow clearing (if running the snow option)

  • Surface conductance parameterisation [Järvi et al., 2011, Ward et al., 2016]

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

The first column of SUEWS_SiteSelect.txt the 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 [Allen et al., 2010, Lindberg et al., 2013] 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. Use UMEP.

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

The path separator differs between Windows (backslash: \) and Linux/Mac (slash, or forward slash: /).

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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:

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Scheme options#
CBLUse#
Requirement

Required

Description

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

Configuration

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]. 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]. Zenith angle not accounted for in albedo calculation.

11

Same as 1 but with L↑ modelled using surface temperature Not recommended in this version.

12

Same as 2 but with L↑ modelled using surface temperature Not recommended in this version.

13

Same as 3 but with L↑ modelled using surface temperature Not recommended in this version.

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]. 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]. Zenith angle accounted for in albedo calculation. SSss_YYYY_NARPOut.txt file produced. Not recommended in this version.

1001

Q* modelled with SPARTACUS-Surface (SS) but with L↓ modelled as in 1. Experimental in this version.

1002

Q* modelled with SPARTACUS-Surface (SS) but with L↓ modelled as in 2. Experimental in this version.

1003

Q* modelled with SPARTACUS-Surface (SS) but with L↓ modelled as in 3. Experimental in this version.

BaseTMethod#
Requirement

Required

Description

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

Configuration

Value

Comments

1

V-shape approach: a single BaseT_HC is used

2

U-shape approach: TCritic_Heating_WD (TCritic_Heating_WE) and TCritic_Cooling_WD (TCritic_Cooling_WE) are used for HDD and CDD calculations in weekdays (weekends), respectively.

EmissionsMethod#
Requirement

Required

Description

Determines method for QF calculation.

Configuration

Value

Comments

0

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

1

Not recommended in this version. Calculated according to Loridan et al. [2011] 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] 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] method using daily (not instantaneous) air temperature (HDD(id-1,3)) using coefficients specified in SUEWS_AnthropogenicEmission.txt.

4

Järvi et al. [2019] method, in addition to anthropogenic heat due to building energy use calculated by Järvi et al. [2011], that due to metabolism and traffic is also calculated 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.

StorageHeatMethod#
Requirement

Required

Description

Determines method for calculating storage heat flux ΔQS.

Configuration

Value

Comments

0

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

1

ΔQS modelled using the objective hysteresis model (OHM) [Grimmond et al., 1991] using parameters specified for each surface type.

3

ΔQS modelled using AnOHM [Sun et al., 2017]. Not recommended in this version.

4

ΔQS modelled using the Element Surface Temperature Method (ESTM) [Offerle et al., 2005]. 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] modified by Högström [1988]

    • stable: Van Ulden and Holtslag [1985]

  • Heat: Dyer [1974] modified by Högström [1988]

Not recommended in this version.

3

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

  • Heat

    • unstable: Campbell and Norman [1998]

    • stable: Campbell and Norman [1998]

Recommended in this version.

4

  • Momentum: Businger et al. [1971] modified by Högström [1988]

  • Heat: Businger et al. [1971] modified by Högström [1988]

Not recommended in this version.

RoughLenHeatMethod#
Requirement

Required

Description

Determines method for calculating roughness length for heat.

Configuration

Value

Comments

1

Uses value of 0.1*z0m.

2

Calculated according to Kawai et al. [2009].

3

Calculated according to Voogt and Grimmond [2000].

4

Calculated according to Kanda et al. [2007].

5

Adaptively using z0m based on pervious coverage: if fully pervious, use method 1; otherwise, use method 2.

Recommended in this version.

RoughLenMomMethod#
Requirement

Required

Description

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

Configuration

Value

Comments

1

Values specified in SUEWS_SiteSelect.txt are used.

Tip

Note that UMEP provides tools to calculate these. See Kent et al. [2017] for recommendations on methods. Kent et al. [2017] 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] 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] method using mean building and tree heights, plan area fraction and frontal areal index specified in SUEWS_SiteSelect.txt. z0m and zd are adjusted with time to account for seasonal variation in porosity of deciduous trees.

SMDMethod#
Requirement

Required

Description

Determines method for calculating soil moisture deficit (SMD).

Configuration

Value

Comments

0

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

1

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

2

Observed SM provided in the meteorological forcing file is used. Data are provided as gravimetric soil moisture content. Metadata must be provided in SUEWS_Soil.txt.

SOLWEIGUse#

Deprecated since version v2020a.

Requirement

Required

Description

Determines whether SOLWEIG is used to calculate detailed radiation balance of all facets.

Configuration

Value

Comments

0

SOLWEIG calculations are not performed.

1

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

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.

DiagMethod#
Requirement

Required

Description

Defines how near surface diagnostics are calculated.

Configuration

Value

Comments

0

Use MOST to calculate near surface diagnostics.

1

Use RST to calculate near surface diagnostics.

2

Use a set of criteria based on plan area index, frontal area index and heights of roughness elements to determine if RSL or MOST should be used.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

SUEWS Site Information#

Note

  1. We use the following codes for denoting the requirement level of various input variables/parameters for SUEWS throughout this section:

    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, which must

    • be specified in the correct way to link the main and sub-reference files (similar to key-value pairs);

    • be integers and unique in column 1 of corresponding input files; and

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

  2. We use the following codes for denoting the typical land cover/entity types of SUEWS throughout this section:

    Paved#

    Paved surface

    Bldgs#

    Building surface

    EveTr#

    Evergreen trees and shrubs

    DecTr#

    Deciduous trees and shrubs

    Grass#

    Grass surface

    BSoil#

    Unmanaged land and/or bare soil

    Water#

    Water surface

    Runoff#

    The water that drains freely off the impervious surface

    SoilStore#

    The water stored in the underlying soil that infiltrates from the pervious surface

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

SUEWS_AnthropogenicEmission.txt#

Note

Changed in version v2019a: this file is renamed from SUEWS_AnthropogenicHeat.txt (prior to v2019a) to include more emission related settings.

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

For the method of Järvi et al. [2011] (EmissionsMethod = 2 in RunControl.nml), one can further configure the scheme for calculting HDD/ CDD via BaseTMethod 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.0

Code

L

Code linking to a corresponding look-up table.

2.0

BaseT_HC

MU

Base temperature for heating degree days [°C]

3.0

QF_A_WD

MU O

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

4.0

QF_B_WD

MU O

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

5.0

QF_C_WD

MU O

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

6.0

QF_A_WE

MU O

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

7.0

QF_B_WE

MU O

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

8.0

QF_C_WE

MU O

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

9.0

AHMin_WD

MU O

Minimum QF on weekdays [W m-2]

10.0

AHMin_WE

MU O

Minimum QF on weekends [W m-2]

11.0

AHSlope_Heating_WD

MU O

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

12.0

AHSlope_Heating_WE

MU O

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

13.0

AHSlope_Cooling_WD

MU O

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

14.0

AHSlope_Cooling_WE

MU O

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

15.0

TCritic_Heating_WD

MU O

Critical heating temperature on weekdays [°C]

16.0

TCritic_Heating_WE

MU O

Critical heating temperature on weekends [°C]

17.0

TCritic_Cooling_WD

MU O

Critical cooling temperature on weekdays [°C]

18.0

TCritic_Cooling_WE

MU O

Critical cooling temperature on weekends [°C]

19.0

EnergyUseProfWD

MU O

Code linking to EnergyUseProfWD in SUEWS_Profiles.txt.

20.0

EnergyUseProfWE

MU O

Code linking to EnergyUseProfWE in SUEWS_Profiles.txt.

21.0

ActivityProfWD

MU O

Code linking to ActivityProfWD in SUEWS_Profiles.txt.

22.0

ActivityProfWE

MU O

Code linking to ActivityProfWE in SUEWS_Profiles.txt.

23.0

TraffProfWD

MU O

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

24.0

TraffProfWE

MU O

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

25.0

PopProfWD

MU O

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

26.0

PopProfWE

MU O

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

27.0

MinQFMetab

MU O

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

28.0

MaxQFMetab

MU O

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

29.0

MinFCMetab

MU O

Minimum (night) CO2 from human metabolism. [umol s-1 cap-1]

30.0

MaxFCMetab

MU O

Maximum (day) CO2 from human metabolism. [umol s-1 cap-1]

31.0

FrPDDwe

MU O

Fraction of weekend population to weekday population. [-]

32.0

FrFossilFuel_Heat

MU O

Fraction of fossil fuels used for building heating [-]

33.0

FrFossilFuel_NonHeat

MU O

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

34.0

EF_umolCO2perJ

MU O

Emission factor for fuels used for building heating. [umol CO2 J-1]

35.0

EnEF_v_Jkm

MU O

Emission factor for heat from traffic [J k m-1 ].

36.0

FcEF_v_kgkmWD

MU O

CO2 emission factor for traffic on weekdays [kg km-1]

37.0

FcEF_v_kgkmWE

MU O

CO2 emission factor for traffic on weekends [kg km-1]

38.0

CO2PointSource

MU O

CO2 emission point source within the grid [kgC day-1]

39.0

TrafficUnits

MU O

Units for the traffic rate for the study area. 1 = [veh km m-2 day-1] 2 = [veh km cap-1 day-1]). 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.0

Code

L

Code linking to a corresponding look-up table.

2.0

alpha

MU O

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

3.0

beta

MU O

The light-saturated gross photosynthesis of the canopy describing the maximum photosynthesis the certain vegetation can have. [umol m-2 s-1 ]

4.0

theta

MU O

The convexity of the curve at light saturation. Not in use.

5.0

alpha_enh

MU O

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

6.0

beta_enh

MU O

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

7.0

resp_a

MU O

Soil and vegetation respiration coefficient a.

8.0

resp_b

MU O

Soil and vegetation respiration coefficient b - related to air temperature dependency.

9.0

min_respi

MU O

Minimum soil and vegetation 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

SUEWS_Conductance.txt#

SUEWS_Conductance.txt contains the parameters needed for the Jarvis (1976) [Jarvis, 1976] surface conductance model used in the modelling of evaporation in SUEWS. These values should not be changed independently of each other. The suggested values below have been derived using datasets for Los Angeles and Vancouver (see Järvi et al. [2011]) 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.0

Code

L

Code linking to a corresponding look-up table.

2.0

G1

MD

Related to maximum surface conductance [mm s-1]

3.0

G2

MD

Related to Kdown dependence [W m-2]

4.0

G3

MD

Related to VPD dependence [units depend on gsModel]

5.0

G4

MD

Related to VPD dependence [units depend on gsModel]

6.0

G5

MD

Related to temperature dependence [°C]

7.0

G6

MD

Related to soil moisture dependence [mm-1]

8.0

TH

MD

Upper air temperature limit [°C]

9.0

TL

MD

Lower air temperature limit [°C]

10.0

S1

MD

A parameter related to soil moisture dependence [-]

11.0

S2

MD

A parameter related to soil moisture dependence [mm]

12.0

Kmax

MD

Maximum incoming shortwave radiation [W m-2]

13.0

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

SUEWS_Irrigation.txt#

External water use may be used for a wide range of reasons (e.g. cleaning roads, irrigating plants, fountains, washing cars).

SUEWS has two options for External Water use (if non-zero):

  1. provide observed data in meteorological forcing file in the Wuh column with valid values by setting WaterUseMethod = 1 in RunControl.nml

  2. a simple model that 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 user needs to supply coefficients (XXX) for these relations.

    1. sub-daily pattern of water use is detemined from the daily cycles specified in SUEWS_Profiles.txt.

    2. surface that the water can be applied to is specified by XX.

    3. water can pond.

No.

Column Name

Use

Description

1.0

Code

L

Code linking to a corresponding look-up table.

2.0

Ie_start

MU

Day when irrigation starts [DOY]

3.0

Ie_end

MU

Day when irrigation ends [DOY]

4.0

InternalWaterUse

MU

Internal water use [mm h-1]

5.0

Faut

MU

Fraction of irrigated area that is irrigated using automated systems

6.0

H_maintain

MU

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

7.0

Ie_a1

MD

Coefficient for automatic irrigation model [mm d-1 ]

8.0

Ie_a2

MD

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

9.0

Ie_a3

MD

Coefficient for automatic irrigation model [mm d-2 ]

10.0

Ie_m1

MD

Coefficient for manual irrigation model [mm d-1 ]

11.0

Ie_m2

MD

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

12.0

Ie_m3

MD

Coefficient for manual irrigation model [mm d-2 ]

13.0

DayWat(1)

MU

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

14.0

DayWat(2)

MU

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

15.0

DayWat(3)

MU

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

16.0

DayWat(4)

MU

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

17.0

DayWat(5)

MU

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

18.0

DayWat(6)

MU

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

19.0

DayWat(7)

MU

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

20.0

DayWatPer(1)

MU

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

21.0

DayWatPer(2)

MU

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

22.0

DayWatPer(3)

MU

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

23.0

DayWatPer(4)

MU

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

24.0

DayWatPer(5)

MU

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

25.0

DayWatPer(6)

MU

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

26.0

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.0

Code

L

Code linking to a corresponding look-up table.

2.0

AlbedoMin

MU

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

3.0

AlbedoMax

MU

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

4.0

Emissivity

MU

Effective surface emissivity.

5.0

StorageMin

MD

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

6.0

StorageMax

MD

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

7.0

WetThreshold

MD

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

8.0

StateLimit

MD

Upper limit to the surface state. [mm]

9.0

DrainageEq

MD

Calculation choice for Drainage equation

10.0

DrainageCoef1

MD

Coefficient D0 [mm h-1] used in DrainageEq

11.0

DrainageCoef2

MD

Coefficient b [-] used in DrainageEq

12.0

SoilTypeCode

L

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

13.0

SnowLimPatch

O

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

14.0

SnowLimRemove

O

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

15.0

OHMCode_SummerWet

L

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

16.0

OHMCode_SummerDry

L

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

17.0

OHMCode_WinterWet

L

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

18.0

OHMCode_WinterDry

L

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

19.0

OHMThresh_SW

MD

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

20.0

OHMThresh_WD

MD

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

21.0

ESTMCode

L

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

22.0

AnOHM_Cp

MU

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

23.0

AnOHM_Kk

MU

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

24.0

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

SUEWS_OHMCoefficients.txt#

OHM, the Objective Hysteresis Model [Grimmond et al., 1991] 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.0

Code

L

Code linking to a corresponding look-up table.

2.0

a1

MU

Coefficient for Q* term [-]

3.0

a2

MU

Coefficient for dQ*/dt term [h]

4.0

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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 linearly interpolate the profiles to the resolution of the model time step; some profiles may be normalized either by sum or by mean depending on the activity type while others not(see Normalisation method column of table below). Thus it does not matter whether columns 2-25 add up to, say 1, 24, or another number, because the model will eventually use the normalised values to rescale the results.

Note

  1. Currently, the snow clearing profiles are not interpolated as these are effectively a switch (0 for off and 1 for on).

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

Activity

Description

Normalisation method

Weekday option

Weekend option

Energy use

This profile, in junction with population density (PopDensDay and PopDensNight), determines the overall anthropogenic heat.

mean

EnergyUseProfWD

EnergyUseProfWE

Population density

This profile, in junction with human activity (ActivityProfWD and ActivityProfWE), determines the anthropogenic heat due to metabolism.

None

PopProfWD

PopProfWE

Human activity

This profile, in junction with population density (PopProfWD and PopProfWE), determines the anthropogenic heat due to metabolism.

None

ActivityProfWD

ActivityProfWE

Traffic

This profile determines the anthropogenic heat due to traffic.

mean

TraffProfWD

TraffProfWE

Water use (manual)

This profile determines the irrigation under manual operation.

sum

WaterUseProfManuWD

WaterUseProfManuWE

Water use (automatic)

This profile determines the irrigation under automatic operation.

sum

WaterUseProfAutoWD

WaterUseProfAutoWE

Snow removal

This profile determines if snow removal is conducted at the end of each hour.

None

SnowClearingProfWD

SnowClearingProfWE

  • 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.0

Grid

MU

a unique number to represent grid

2.0

Year

MU

Year [YYYY]

3.0

StartDLS

MU

Start of the day light savings [DOY]

4.0

EndDLS

MU

End of the day light savings [DOY]

5.0

lat

MU

Latitude [deg].

6.0

lng

MU

longitude [deg]

7.0

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

SurfaceArea

MU

Area of the grid [ha].

9.0

Alt

MU

Altitude of grids [m].

10.0

z

MU

Measurement height [m] for all atmospheric forcing variables set in SSss_YYYY_data_tt.txt.

11.0

id

MD

Day of year [DOY]

12.0

ih

MD

Hour [H]

13.0

imin

MD

Minute [M]

14.0

Fr_Paved

MU

Surface cover fraction of Paved surfaces [-]

15.0

Fr_Bldgs

MU

Surface cover fraction of buildings [-]

16.0

Fr_EveTr

MU

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

17.0

Fr_DecTr

MU

Surface cover fraction of deciduous trees and shrubs [-]

18.0

Fr_Grass

MU

Surface cover fraction of Grass [-]

19.0

Fr_Bsoil

MU

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

20.0

Fr_Water

MU

Surface cover fraction of open water [-]

21.0

IrrFr_Paved

MU

Fraction of Paved that is irrigated [-]

22.0

IrrFr_Bldgs

MU

Fraction of Bldgs that is irrigated [-]

23.0

IrrFr_EveTr

MU

Fraction of EveTr that is irrigated [-]

24.0

IrrFr_DecTr

MU

Fraction of DecTr that is irrigated [-]

25.0

IrrFr_Grass

MU

Fraction of Grass that is irrigated [-]

26.0

IrrFr_BSoil

MU

Fraction of BSoil that is irrigated [-]

27.0

IrrFr_Water

MU

Fraction of Water that is irrigated [-]

28.0

H_Bldgs

MU

Mean building height [m]

29.0

H_EveTr

MU

Mean height of evergreen trees [m]

30.0

H_DecTr

MU

Mean height of deciduous trees [m]

31.0

z0

O

Roughness length for momentum [m]

32.0

zd

O

Zero-plane displacement [m]

33.0

FAI_Bldgs

O

Frontal area index for buildings [-]

34.0

FAI_EveTr

O

Frontal area index for evergreen trees [-]

35.0

FAI_DecTr

O

Frontal area index for deciduous trees [-]

36.0

PopDensDay

O

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

37.0

PopDensNight

O

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

38.0

TrafficRate_WD

O

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

39.0

TrafficRate_WE

O

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

40.0

QF0_BEU_WD

O

Building energy use [W m-2]

41.0

QF0_BEU_WE

O

Building energy use [W m-2]

42.0

Code_Paved

L

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

43.0

Code_Bldgs

L

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

44.0

Code_EveTr

L

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

45.0

Code_DecTr

L

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

46.0

Code_Grass

L

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

47.0

Code_BSoil

L

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

48.0

Code_Water

L

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

49.0

LUMPS_DrRate

MD

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

50.0

LUMPS_Cover

MD

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

51.0

LUMPS_MaxRes

MD

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

52.0

NARP_Trans

MD

Atmospheric transmissivity for NARP [-]

53.0

CondCode

L

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

54.0

SnowCode

L

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

55.0

SnowClearingProfWD

L

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

56.0

SnowClearingProfWE

L

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

57.0

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

58.0

IrrigationCode

L

Code for modelling irrigation linking to Code of SUEWS_Irrigation.txt

59.0

WaterUseProfManuWD

L

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

60.0

WaterUseProfManuWE

L

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

61.0

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.

62.0

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.

63.0

FlowChange

MD

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

64.0

RunoffToWater

MD MU

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

65.0

PipeCapacity

MD MU

Storage capacity of pipes [mm]

66.0

GridConnection1of8

MD MU

Number of the 1st grid where water can flow to

67.0

Fraction1of8

MD MU

Fraction of water that can flow to GridConnection1of8 [-]

68.0

GridConnection2of8

MD MU

Number of the 2nd grid where water can flow to

69.0

Fraction2of8

MD MU

Fraction of water that can flow to GridConnection2of8 [-]

70.0

GridConnection3of8

MD MU

Number of the 3rd grid where water can flow to

71.0

Fraction3of8

MD MU

Fraction of water that can flow to GridConnection3of8 [-]

72.0

GridConnection4of8

MD MU

Number of the 4th grid where water can flow to

73.0

Fraction4of8

MD MU

Fraction of water that can flow to GridConnection4of8 [-]

74.0

GridConnection5of8

MD MU

Number of the 5th grid where water can flow to

75.0

Fraction5of8

MD MU

Fraction of water that can flow to GridConnection5of8 [-]

76.0

GridConnection6of8

MD MU

Number of the 6th grid where water can flow to

77.0

Fraction6of8

MD MU

Fraction of water that can flow to GridConnection6of8 [-]

78.0

GridConnection7of8

MD MU

Number of the 7th grid where water can flow to

79.0

Fraction7of8

MD MU

Fraction of water that can flow to GridConnection7of8 [-]

80.0

GridConnection8of8

MD MU

Number of the 8th grid where water can flow to

81.0

Fraction8of8

MD MU

Fraction of water that can flow to GridConnection8of8 [-]

82.0

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.

83.0

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

84.0

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.

85.0

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.

86.0

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.

87.0

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.

88.0

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.

89.0

AreaWall

MU

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

90.0

Fr_ESTMClass_Paved1

MU

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

91.0

Fr_ESTMClass_Paved2

MU

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

92.0

Fr_ESTMClass_Paved3

MU

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

93.0

Code_ESTMClass_Paved1

L

Code linking to SUEWS_ESTMCoefficients.txt

94.0

Code_ESTMClass_Paved2

L

Code linking to SUEWS_ESTMCoefficients.txt

95.0

Code_ESTMClass_Paved3

L

Code linking to SUEWS_ESTMCoefficients.txt

96.0

Fr_ESTMClass_Bldgs1

MU

Surface cover fraction of building class 1 used in ESTM calculations

97.0

Fr_ESTMClass_Bldgs2

MU

Surface cover fraction of building class 2 used in ESTM calculations

98.0

Fr_ESTMClass_Bldgs3

MU

Surface cover fraction of building class 3 used in ESTM calculations

99.0

Fr_ESTMClass_Bldgs4

MU

Surface cover fraction of building class 4 used in ESTM calculations

100.0

Fr_ESTMClass_Bldgs5

MU

Surface cover fraction of building class 5 used in ESTM calculations

101.0

Code_ESTMClass_Bldgs1

L

Code linking to SUEWS_ESTMCoefficients.txt

102.0

Code_ESTMClass_Bldgs2

L

Code linking to SUEWS_ESTMCoefficients.txt

103.0

Code_ESTMClass_Bldgs3

L

Code linking to SUEWS_ESTMCoefficients.txt

104.0

Code_ESTMClass_Bldgs4

L

Code linking to SUEWS_ESTMCoefficients.txt

105.0

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                        102                     103                     104                     105
Grid   Year   StartDLS   EndDLS   lat       lng       Timezone   SurfaceArea   Alt       z         id       ih       imin     Fr_Paved   Fr_Bldgs   Fr_EveTr   Fr_DecTr   Fr_Grass   Fr_Bsoil   Fr_Water   IrrFr_Paved     IrrFr_Bldgs     IrrFr_EveTr   IrrFr_DecTr   IrrFr_Grass   IrrFr_BSoil   IrrFr_Water   H_Bldgs    H_EveTr     H_DecTr     z0          zd           FAI_Bldgs      FAI_EveTr        FAI_DecTr        PopDensDay   PopDensNight   TrafficRate_WD   TrafficRate_WE   QF0_BEU_WD   QF0_BEU_WE   Code_Paved   Code_Bldgs   Code_EveTr   Code_DecTr     Code_Grass    Code_Bsoil     Code_Water   LUMPS_DrRate   LUMPS_Cover   LUMPS_MaxRes         NARP_Trans           CondCode            SnowCode         SnowClearingProfWD   SnowClearingProfWE   AnthropogenicCode    IrrigationCode       WaterUseProfManuWD   WaterUseProfManuWE   WaterUseProfAutoWD   WaterUseProfAutoWE   FlowChange     RunoffToWater        PipeCapacity   GridConnection1of8   Fraction1of8   GridConnection2of8   Fraction2of8   GridConnection3of8   Fraction3of8   GridConnection4of8   Fraction4of8   GridConnection5of8   Fraction5of8   GridConnection6of8   Fraction6of8   GridConnection7of8    Fraction7of8          GridConnection8of8    Fraction8of8          WithinGridPavedCode   WithinGridBldgsCode        WithinGridEveTrCode   WithinGridDecTrCode   WithinGridGrassCode   WithinGridUnmanBSoilCode   WithinGridWaterCode   AreaWall                Fr_ESTMClass_Paved1     Fr_ESTMClass_Paved2     Fr_ESTMClass_Paved3   Code_ESTMClass_Paved1   Code_ESTMClass_Paved2   Code_ESTMClass_Paved3   Fr_ESTMClass_Bldgs1   Fr_ESTMClass_Bldgs2     Fr_ESTMClass_Bldgs3     Fr_ESTMClass_Bldgs4     Fr_ESTMClass_Bldgs5     Code_ESTMClass_Bldgs1      Code_ESTMClass_Bldgs2   Code_ESTMClass_Bldgs3   Code_ESTMClass_Bldgs4   Code_ESTMClass_Bldgs5
1      2004   85         302      57.7700   11.8700   2.0000     1.0000        15.0000   50.0000   1.0000   0.0000   0.0000   0.2000     0.2000     0.2000     0.1000     0.1000     0.1000     0.1000     0.0             0.0             0.0000        0.0000        0.0000        0.0           0.0           15.00      15.000      15.000      0.0100      0.2000       0.3000         0.3000           0.3000           0.0000       0.0000         0.0134           0.0095           0.7442       0.7955       661.0000     662.0000     661.0000     662.0000       663.0000      663.0000       661.0000     0.2500         1.0000        10.0000              1.0000               200.0000            660.0000         660.0000             660.0000             661.0000             660.0000             660.0000             660.0000             660.0000             660.0000             0.0000         0.1000               100.0000       0.0000               0.0000         0.0000               0.0000         0.0000               0.0000         0.0000               0.0000         0.0000               0.0000         0.0000               0.0000         0.0000                0.0000                0.0000                0.0000                661.0000              662.0000                   663.0000              664.0000              665.0000              666.0000                   667.0000              -999.0000               0.0000                  1.0000                  0.0000                99999.0000              807.0000                99999.0000              1.0000                0.0000                  0.0000                  0.0000                  0.0000                  801.0000                   99999.0000              99999.0000              99999.0000              99999.0000
1      2005   85         302      57.7700   11.8700   2.0000     1.0000        15.0000   50.0000   1.0000   0.0000   0.0000   0.2000     0.2000     0.2000     0.1000     0.1000     0.1000     0.1000     0.0             0.0             0.0000        0.0000        0.0000        0.0           0.0           1.00       1.000       1.000       0.0100      0.2000       0.3000         0.3000           0.3000           0.0000       0.0000         0.0134           0.0095           0.7442       0.7955       661.0000     662.0000     661.0000     662.0000       663.0000      663.0000       661.0000     0.2500         1.0000        10.0000              1.0000               200.0000            660.0000         660.0000             660.0000             661.0000             660.0000             660.0000             660.0000             660.0000             660.0000             0.0000         0.1000               100.0000       0.0000               0.0000         0.0000               0.0000         0.0000               0.0000         0.0000               0.0000         0.0000               0.0000         0.0000               0.0000         0.0000                0.0000                0.0000                0.0000                661.0000              662.0000                   663.0000              664.0000              665.0000              666.0000                   667.0000              -999.0000               0.0000                  1.0000                  0.0000                99999.0000              807.0000                99999.0000              1.0000                0.0000                  0.0000                  0.0000                  0.0000                  801.0000                   99999.0000              99999.0000              99999.0000              99999.0000
-9
-9

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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) [Järvi et al., 2014].

No.

Column Name

Use

Description

1.0

Code

L

Code linking to a corresponding look-up table.

2.0

RadMeltFactor

MU

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

3.0

TempMeltFactor

MU

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

4.0

AlbedoMin

MU

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

5.0

AlbedoMax

MU

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

6.0

Emissivity

MU

Effective surface emissivity.

7.0

tau_a

MD

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

8.0

tau_f

MD

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

9.0

PrecipLimAlb

MD

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

10.0

SnowDensMin

MD

Fresh snow density [kg m-3]

11.0

SnowDensMax

MD

Maximum snow density [kg m-3]

12.0

tau_r

MD

Time constant for snow density ageing [-]

13.0

CRWMin

MD

Minimum water holding capacity of snow [mm]

14.0

CRWMax

MD

Maximum water holding capacity of snow [mm]

15.0

PrecipLimSnow

MD

Temperature limit when precipitation falls as snow [°C]

16.0

OHMCode_SummerWet

L

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

17.0

OHMCode_SummerDry

L

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

18.0

OHMCode_WinterWet

L

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

19.0

OHMCode_WinterDry

L

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

20.0

OHMThresh_SW

MD

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

21.0

OHMThresh_WD

MD

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

22.0

ESTMCode

L

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

23.0

AnOHM_Cp

MU

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

24.0

AnOHM_Kk

MU

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

25.0

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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 (the xsmd column when SMDMethod = 1 or 2 in RunControl.nml) and providing some soil properties here, or modelled by SUEWS (SMDMethod = 0 in RunControl.nml).

No.

Column Name

Use

Description

1.0

Code

L

Code linking to a corresponding look-up table.

2.0

SoilDepth

MD

Depth of soil beneath the surface [mm]

3.0

SoilStoreCap

MD

Limit value for SoilDepth [mm]

4.0

SatHydraulicCond

MD

Hydraulic conductivity for saturated soil [mm s-1]

5.0

SoilDensity

MD

Soil density [kg m-3]

6.0

InfiltrationRate

O

Infiltration rate.

7.0

OBS_SMDepth

O

The depth of soil moisture measurements. [mm]

8.0

OBS_SMCap

O

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

9.0

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.0

Code

L

Code linking to a corresponding look-up table.

2.0

AlbedoMin

MU

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

3.0

AlbedoMax

MU

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

4.0

Emissivity

MU

Effective surface emissivity.

5.0

StorageMin

MD

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

6.0

StorageMax

MD

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

7.0

WetThreshold

MD

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

8.0

StateLimit

MD

Upper limit to the surface state. [mm]

9.0

DrainageEq

MD

Calculation choice for Drainage equation

10.0

DrainageCoef1

MD

Coefficient D0 [mm h-1] used in DrainageEq

11.0

DrainageCoef2

MD

Coefficient b [-] used in DrainageEq

12.0

SoilTypeCode

L

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

13.0

SnowLimPatch

O

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

14.0

BaseT

MU

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

15.0

BaseTe

MU

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

16.0

GDDFull

MU

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

17.0

SDDFull

MU

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

18.0

LAIMin

MD

leaf-off wintertime value

19.0

LAIMax

MD

full leaf-on summertime value

20.0

PorosityMin

MD

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

21.0

PorosityMax

MD

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

22.0

MaxConductance

MD

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

23.0

LAIEq

MD

LAI calculation choice.

24.0

LeafGrowthPower1

MD

a parameter required by LAI calculation in LAIEq

25.0

LeafGrowthPower2

MD

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

26.0

LeafOffPower1

MD

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

27.0

LeafOffPower2

MD

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

28.0

OHMCode_SummerWet

L

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

29.0

OHMCode_SummerDry

L

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

30.0

OHMCode_WinterWet

L

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

31.0

OHMCode_WinterDry

L

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

32.0

OHMThresh_SW

MD

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

33.0

OHMThresh_WD

MD

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

34.0

ESTMCode

L

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

35.0

AnOHM_Cp

MU

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

36.0

AnOHM_Kk

MU

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

37.0

AnOHM_Ch

MU

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

38.0

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.0

Code

L

Code linking to a corresponding look-up table.

2.0

AlbedoMin

MU

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

3.0

AlbedoMax

MU

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

4.0

Emissivity

MU

Effective surface emissivity.

5.0

StorageMin

MD

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

6.0

StorageMax

MD

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

7.0

WetThreshold

MD

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

8.0

StateLimit

MU

Upper limit to the surface state. [mm]

9.0

WaterDepth

MU

Water depth [mm].

10.0

DrainageEq

MD

Calculation choice for Drainage equation

11.0

DrainageCoef1

MD

Coefficient D0 [mm h-1] used in DrainageEq

12.0

DrainageCoef2

MD

Coefficient b [-] used in DrainageEq

13.0

OHMCode_SummerWet

L

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

14.0

OHMCode_SummerDry

L

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

15.0

OHMCode_WinterWet

L

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

16.0

OHMCode_WinterDry

L

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

17.0

OHMThresh_SW

MD

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

18.0

OHMThresh_WD

MD

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

19.0

ESTMCode

L

Code for ESTM coefficients linking to SUEWS_ESTMCoefficients.txt

20.0

AnOHM_Cp

MU

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

21.0

AnOHM_Kk

MU

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

22.0

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.0

ToPaved

MU

Fraction of water going to Paved

2.0

ToBldgs

MU

Fraction of water going to Bldgs

3.0

ToEveTr

MU

Fraction of water going to EveTr

4.0

ToDecTr

MU

Fraction of water going to DecTr

5.0

ToGrass

MU

Fraction of water going to Grass

6.0

ToBSoil

MU

Fraction of water going to BSoil

7.0

ToWater

MU

Fraction of water going to Water

8.0

ToRunoff

MU

Fraction of water going to Runoff

9.0

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.

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.

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. Not in use [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:

EmissionsMethod = 21, 22, 23, 24, 25, or 26: 0.031 [Bellucco et al., 2017] EmissionsMethod = 31, 32, 33, 34, 35, 36: 0.005 [Bellucco et al., 2017]

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) [ m2 ].

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

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

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 of Järvi et al. [2014]. Example values: 5 for EveTr [Järvi et al., 2011]

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] ; Appendix A Järvi et al. [2014] . Example values: 10 EveTr Järvi et al. [2011]

BaseT_HC#
Description

Base temperature for heating degree days [°C]

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU

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

beta#
Description

The light-saturated gross photosynthesis of the canopy describing the maximum photosynthesis the certain vegetation can have. [umol m-2 s-1 ]

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

Example values: EmissionsMethod = 45 (Recommended): - 8.35 (Street tree Tilia) [Havu et al., 2022] - 13.18 (Street tree Alnus) [Havu et al., 2022] - 5.5 (Lawn): [Zheng et al., 2023]

Not recommended: EmissionsMethod = 11 - 16:

EmissionsMethod = 21 - 26: 17.793 [Bellucco et al., 2017] EmissionsMethod = 31 - 36: 8.474 [Bellucco et al., 2017]

theta#
Description

The convexity of the curve at light saturation. Not in use.

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] EmissionsMethod = 31, 32, 33, 34, 35, 36: 0.96 [Bellucco et al., 2017]

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]

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]

resp_a#
Description

Soil and vegetation respiration coefficient a.

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

Example values:

  • 0.78 (Tilia street tree

no soil

Helsinki) [Havu et al., 2022]

  • 1.11 (Alnus street tree

no soil

Helsinki) [Havu et al., 2022]

resp_b#
Description

Soil and vegetation respiration coefficient b - related to air temperature dependency.

Configuration

Referencing Table

Requirement

Comment

SUEWS_BiogenCO2.txt

MU O

Example values:

  • 0.08 (Tilia street tree

no soil

Helsinki) [Havu et al., 2022]

  • 0.08 (Alnus street tree

no soil

Helsinki) [Havu et al., 2022]

min_respi#
Description

Minimum soil and vegetation 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.

CO2PointSource#
Description

CO2 emission point source within the grid [kgC day-1]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

CO2 emission point source within the grid [kgC day-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] parameterisation of surface conductance. Value of integer is arbitrary but must match code specified in column 1 of SUEWS_Conductance.txt. e.g. 33 means use the characteristics specified in the row of input file SUEWS_Conductance.txt which has 33 in column 1 (Code).

CRWMax#
Description

Maximum water holding capacity of snow [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MD

Maximum water holding capacity of snow [mm]

CRWMin#
Description

Minimum water holding capacity of snow [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MD

Minimum water holding capacity of snow [mm]

DayWat(1)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(2)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(3)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(4)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(5)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(6)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWat(7)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(1)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(2)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(3)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(4)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(5)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(6)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DayWatPer(7)#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

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

DrainageCoef1#
Description

Coefficient D0 [mm h-1] used in DrainageEq

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

SUEWS_Veg.txt

MD

SUEWS_Water.txt

MD

Not currently used for water surface

DrainageCoef2#
Description

Coefficient b [-] used in DrainageEq

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

SUEWS_Veg.txt

MD

SUEWS_Water.txt

MD

Not currently used for water surface

DrainageEq#
Description

Calculation choice for Drainage equation

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

  • Options:

SUEWS_Veg.txt

MD

  • Options:

    • 1: Falk and Niemczynowicz [1978]

    • 2: Halldin et al. [1979] (Rutter eqn corrected for c=0, see Calder & Wright (1986) [Calder and Wright, 1986] )

    • 3: for EveTr, DecTr, Grass (unirrigated) see Falk and Niemczynowicz [1978]. 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. [umol CO2 J-1]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

O

Used with EmissionMethod = 4 to calculate building CO2 emissions.

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

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 from traffic [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) [Sailor and Lu, 2004]

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 traffic on 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 traffic on 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

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Fraction of weekend population to weekday population. [-]

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] ; Appendix A Järvi et al. [2014] for more details. Example values: 300 for EveTr Järvi et al. [2011]

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

but using 2 meter air temperature

but using 2 meter air temperature

H_Bldgs#
Description

Mean building height [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Mean building height [m]

H_DecTr#
Description

Mean height of deciduous trees [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Mean height of deciduous trees [m]

H_EveTr#
Description

Mean height of evergreen trees [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Mean height of evergreen trees [m]

H_maintain#
Description

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

Note

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

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

water depth to maintain used in automatic irrigation.

id#
Description

Day of year [DOY]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

Not used: set to 1 in this version.

SSss_YYYY_ESTM_Ts_data_tt.txt

MU

Day of year [DOY]

SSss_YYYY_data_tt.txt

MU

Day of year [DOY]

CBL_initial_data.txt

MU

Day of year [DOY]

Ie_a1#
Description

Coefficient for automatic irrigation model [mm d-1 ]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

Coefficient for automatic irrigation model [mm d -1 ]

Ie_a2#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

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

Ie_a3#
Description

Coefficient for automatic irrigation model [mm d-2 ]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

Coefficient for automatic irrigation model [mm d -2 ]

Ie_end#
Description

Day when irrigation ends [DOY]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

Day when irrigation ends [DOY]

Ie_m1#
Description

Coefficient for manual irrigation model [mm d-1 ]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

Coefficient for manual irrigation model [mm d -1 ]

Ie_m2#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

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

Ie_m3#
Description

Coefficient for manual irrigation model [mm d-2 ]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MD

Coefficient for manual irrigation model [mm d -2 ]

Ie_start#
Description

Day when irrigation starts [DOY]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

Day when irrigation starts [DOY]

ih#
Description

Hour [H]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

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

imin#
Description

Minute [M]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MD

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

SSss_YYYY_ESTM_Ts_data_tt.txt

MU

Minute [M]

SSss_YYYY_data_tt.txt

MU

Minute [M]

InfiltrationRate#
Description

Infiltration rate.

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

O

Not currently used

Internal_albedo#
Description

Albedo of all internal elements for building surfaces only

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

Albedo of all internal elements for building surfaces only

Internal_CHbld#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_CHroof#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_CHwall#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_emissivity#
Description

Emissivity of all internal elements for building surfaces only

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

Emissivity of all internal elements for building surfaces only

Internal_k1#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

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

Internal_k2#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_k3#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_k4#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_k5#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_rhoCp1#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

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

Internal_rhoCp2#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_rhoCp3#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_rhoCp4#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_rhoCp5#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_thick1#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

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

Internal_thick2#
Description

Thickness of the second layer [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_thick3#
Description

Thickness of the third layer [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_thick4#
Description

Thickness of the fourth layer [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Internal_thick5#
Description

Thickness of the fifth layer [m]

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

InternalWaterUse#
Description

Internal water use [mm h-1]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Irrigation.txt

MU

Internal water use [mm h-1]

IrrFr_Paved#
Description

Fraction of Paved that is irrigated [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Fraction of paved surfaces that are irrigated [-]

IrrFr_Bldgs#
Description

Fraction of Bldgs that is irrigated [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Fraction of rooftop of buildings (e.g., green roofs) that are irrigated [-]

IrrFr_DecTr#
Description

Fraction of DecTr that is irrigated [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Fraction of deciduous trees that are irrigated [-]

IrrFr_EveTr#
Description

Fraction of EveTr that is irrigated [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

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

IrrFr_Grass#
Description

Fraction of Grass that is irrigated [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Fraction of grass that is irrigated [-]

IrrFr_BSoil#
Description

Fraction of BSoil that is irrigated [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Fraction of bare soil that are irrigated [-]

IrrFr_Water#
Description

Fraction of Water that is irrigated [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Fraction of water that are irrigated [-]

IrrigationCode#
Description

Code for modelling irrigation linking to Code of SUEWS_Irrigation.txt

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

it#
Description

Hour [H]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_ESTM_Ts_data_tt.txt

MU

Hour [H]

SSss_YYYY_data_tt.txt

MU

Hour [H]

iy#
Description

Year [YYYY]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_ESTM_Ts_data_tt.txt

MU

Year [YYYY]

SSss_YYYY_data_tt.txt

MU

Year [YYYY]

kdiff#
Description

Diffuse radiation [W m-2].

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Recommended if SOLWEIGUse = 1

kdir#
Description

Direct radiation [W m-2].

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Recommended if SOLWEIGUse = 1

kdown#
Description

Incoming shortwave radiation [W m-2].

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

MU

Must be > 0 W m-2 .

Kmax#
Description

Maximum incoming shortwave radiation [W m-2]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Maximum incoming shortwave radiation [W m-2]

lai#
Description

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

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

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

LAIEq#
Description

LAI calculation choice.

Note

North and South hemispheres are treated slightly differently.

Configuration

Referencing Table

Requirement

Comment

SUEWS_Veg.txt

MD

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

Options

  • 0 Järvi et al. [2011]

  • 1 Järvi et al. [2014]

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) [Breuer et al., 2003] - 5.5 DecTr Breuer et al. (2003) [Breuer et al., 2003] - 5.9 Grass Breuer et al. (2003) [Breuer et al., 2003]

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] - 1. DecTr [Järvi et al., 2011] - 1.6 Grass [Grimmond and Oke, 1991]

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

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

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

MaxQFMetab#
Description

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

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

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. [umol s-1 cap-1]

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]

MinQFMetab#
Description

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

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

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. [umol s-1 cap-1]

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

Code for population density profile (weekdays).

PopProfWE#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

Code for population density profile (weekends)

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]

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 of Järvi et al. [2011] and Appendix A of Järvi et al. [2014] for more details.

Example values:

snow#
Description

Snowfall [mm]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

O

Required if SnowUse = 1

SnowClearingProfWD#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

SnowClearingProfWE#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

SnowCode#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

L

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

SnowDensMax#
Description

Maximum snow density [kg m-3]

Configuration

SnowDensMin#
Description

Fresh snow density [kg m-3]

Configuration

SnowLimPatch#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

O

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

Example values:

SUEWS_Veg.txt

O

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

Example values:

SnowLimRemove#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

O

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

Example values [mm]

SoilDensity#
Description

Soil density [kg m-3]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

MD

Soil density [kg m-3]

SoilDepth#
Description

Depth of soil beneath the surface [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

MD

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

SoilStoreCap#
Description

Limit value for SoilDepth [mm]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Soil.txt

MD

SoilStoreCap must not be greater than SoilDepth.

SoilTypeCode#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

L

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

SUEWS_Veg.txt

L

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

StartDLS#
Description

Start of the day light savings [DOY]

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

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

StateLimit#
Description

Upper limit to the surface state. [mm]

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

Currently only used for the water surface

SUEWS_Veg.txt

MD

Currently only used for the water surface

SUEWS_Water.txt

MU

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

StorageMax#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

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

Example values:

SUEWS_Veg.txt

MD

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

Example values:

SUEWS_Water.txt

MD

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

StorageMin#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_NonVeg.txt

MD

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

Example values:

SUEWS_Veg.txt

MD

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

Example values:

SUEWS_Water.txt

MD

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

Example values:

-0.5 Water

SurfaceArea#
Description

Area of the grid [ha].

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

Area of the grid [ha].

Surf_k1#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

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

Surf_k2#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_k3#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_k4#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_k5#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_rhoCp1#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

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

Surf_rhoCp2#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_rhoCp3#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_rhoCp4#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_rhoCp5#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_thick1#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

MU

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

Surf_thick2#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_thick3#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_thick4#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Surf_thick5#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_ESTMCoefficients.txt

O

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

Tair#
Description

Air temperature [°C]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_data_tt.txt

MU

Air temperature [°C]

tau_a#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MD

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

tau_f#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MD

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

tau_r#
Description

Time constant for snow density ageing [-]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MD

Time constant for snow density ageing [-]

TCritic_Heating_WD#
Description

Critical heating temperature on weekdays [°C]

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 1

TCritic_Heating_WE#
Description

Critical heating temperature on weekends [°C]

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 1

TCritic_Cooling_WD#
Description

Critical cooling temperature on weekdays [°C]

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 1

TCritic_Cooling_WE#
Description

Critical cooling temperature on weekends [°C]

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

MU O

Use with EmissionsMethod = 1

TempMeltFactor#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_Snow.txt

MU

Hourly temperature melt factor of snow [mm K-1 h-1] (In previous model version, this parameter was 0.12)

TH#
Description

Upper air temperature limit [°C]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Upper air temperature limit [°C]

Theta+_K#
Description

potential temperature at the top of CBL [K]

Configuration

Referencing Table

Requirement

Comment

CBL_initial_data.txt

MU

potential temperature at the top of CBL (K)

Theta_K#
Description

potential temperature in CBL [K]

Configuration

Referencing Table

Requirement

Comment

CBL_initial_data.txt

MU

potential temperature in CBL (K)

Tiair#
Description

Indoor air temperature [˚C]

Configuration

Referencing Table

Requirement

Comment

SSss_YYYY_ESTM_Ts_data_tt.txt

MU

Indoor air temperature [˚C]

Timezone#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_SiteSelect.txt

MU

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

TL#
Description

Lower air temperature limit [°C]

Configuration

Referencing Table

Requirement

Comment

SUEWS_Conductance.txt

MD

Lower air temperature limit [°C]

ToBldgs#
Description

Fraction of water going to Bldgs

Configuration

Referencing Table

Requirement

Comment

SUEWS_WithinGridWaterDist.txt

MU

Fraction of water going to Bldgs

ToBSoil#
Description

Fraction of water going to BSoil

Configuration

Referencing Table

Requirement

Comment

SUEWS_WithinGridWaterDist.txt

MU

Fraction of water going to BSoil

ToDecTr#
Description

Fraction of water going to DecTr

Configuration

Referencing Table

Requirement

Comment

SUEWS_WithinGridWaterDist.txt

MU

Fraction of water going to DecTr

ToEveTr#
Description

Fraction of water going to EveTr

Configuration

Referencing Table

Requirement

Comment

SUEWS_WithinGridWaterDist.txt

MU

Fraction of water going to EveTr

ToGrass#
Description

Fraction of water going to Grass

Configuration

Referencing Table

Requirement

Comment

SUEWS_WithinGridWaterDist.txt

MU

Fraction of water going to Grass

ToPaved#
Description

Fraction of water going to Paved

Configuration

Referencing Table

Requirement

Comment

SUEWS_WithinGridWaterDist.txt

MU

Fraction of water going to Paved

ToRunoff#
Description

Fraction of water going to Runoff

Configuration

Referencing Table

Requirement

Comment

SUEWS_WithinGridWaterDist.txt

MU

Fraction of water going to Runoff

ToSoilStore#
Description

Fraction of water going to SoilStore

Configuration

Referencing Table

Requirement

Comment

SUEWS_WithinGridWaterDist.txt

MU

Fraction of water going to SoilStore

ToWater#
Description

Fraction of water going to Water

Configuration

Referencing Table

Requirement

Comment

SUEWS_WithinGridWaterDist.txt

MU

Fraction of water going to Water

TraffProfWD#
Description

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

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

Used with EmissionMethod=4 to calculate CO2 and heat emissions.

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

Used with EmissionMethod=4 to calculate CO2 and heat emissions.

TrafficUnits#
Description

Units for the traffic rate for the study area. 1 = [veh km m-2 day-1] 2 = [veh km cap-1 day-1]). Not used in v2018a.

Configuration

Referencing Table

Requirement

Comment

SUEWS_AnthropogenicEmission.txt

O

Used with EmissionMethod=4.

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]. Used with EmissionMethod=4 to calculate CO2 and heat emissions.

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]. Used with EmissionMethod=4 to calculate CO2 and heat emissions.

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; can be provided either as volumetric ([m3 m-3] when SMDMethod = 1) or gravimetric quantity ([kg kg-1] when SMDMethod = 2). This should be used in conjunction with other soil properties in SUEWS_Soil.txt.

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] for all atmospheric forcing variables set in SSss_YYYY_data_tt.txt.

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]

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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]

Non Vegetated

0.15

Buildings Helsinki

Järvi et al. [2014]

Non Vegetated

0.19

Bare Soil, Helsinki

Järvi et al. [2014]

Non Vegetated

0.12

Paved

Oke [2002]

Non Vegetated

0.15

Buildings

Oke [2002]

Non Vegetated

0.21

Bare Soil

Oke [2002]

Emissivity

Non Vegetated

0.95

Paved

Oke [2002]

Non Vegetated

0.91

Buildings

Oke [2002]

Non Vegetated

0.93

Bare Soil

Oke [2002]

Surface Water storage capacity

Non Vegetated

0.48

Paved

Davies and Hollis [1981]

Non Vegetated

0.25

Buildings

Falk and Niemczynowicz [1978]

Albedo

Vegetation

0.1

EveTr

Vegetation

0.12

DecTr

Vegetation

0.18

Grass

Vegetated

0.1

EveTr Helsinki

Järvi et al. [2014]

Vegetated

0.16

DecTr Helsinki

Järvi et al. [2014]

Vegetated

0.19

Grass Helsinki

Järvi et al. [2014]

Vegetated

0.1

EveTr

Oke [2002]

Vegetated

0.18

DecTr

Oke [2002]

Vegetated

0.21

Grass

Oke [2002]

Emissivity

Vegetated

0.98

EveTr

Oke [2002]

Vegetated

0.98

DecTr

Oke [2002]

Vegetated

0.93

Grass

Oke [2002]

water Storage Minimum capacity (mm)

Vegetated

1.3

EveTr

Breuer et al. [2003]

Vegetated

0.3

DecTr

Breuer et al. [2003]

Vegetated

1.9

Grass

Breuer et al. [2003]

Maximum water storage capacity of this surface [mm]

Vegetated

1.3

EveTr

Breuer et al. [2003]

Vegetated

0.8

DecTr

Grimmond and Oke (1991)

Vegetated

1.9

Grass

Breuer et al. [2003]

Albedo Max (leaf on)

Vegetated

0.12

DecTr

Vegetated

0.18

Grass

Vegetated

0.1

EveTr Helsinki

Järvi et al. [2014]

Vegetated

0.16

DecTr Helsinki

Järvi et al. [2014]

Vegetated

0.19

Grass Helsinki

Järvi et al. [2014]

Vegetated

0.1

EveTr

Oke [2002]

Vegetated

0.18

DecTr

Oke [2002]

Vegetated

0.21

Grass

Oke [2002]

Emissivity *View factors should be taken into account

Vegetated

0.98

EveTr

Oke [2002]

Emissivity *View factors should be taken into account

Vegetated

0.98

DecTr

Oke [2002]

Emissivity *View factors should be taken into account

Vegetated

0.93

Grass

Oke [2002]

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]

Vegetated

0.3

DecTr

Breuer et al. [2003]

Vegetated

1.9

Grass

Breuer et al. [2003]

Vegetated

1.3

EveTr

Breuer et al. [2003]

Vegetated

0.8

DecTr

Grimmond and Oke (1991)

Vegetated

1.9

Grass

Breuer et al. [2003]

AlbedoMin

Water

0.1

Water

Oke [2002]

AlbedoMax

Water

0.1

Water

Oke [2002]

Emissivity

Water

0.95

Water

Oke [2002]

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

Järvi et al. [2014]

PrecipLimSnow

Snow

2.2

Temperature limit when precipitation falls as snow [°C]

Auer [1974]

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

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

  2. Typical values for various properties can be found here.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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 .

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Meteorological Input File#

SUEWS is designed to run using commonly measured meteorological variables (e.g. incoming solar radiation, air temperature, relative humidity, pressure, wind speed, etc.).

When preparing this input file, please note the following:

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

  • Temporal information (i.e., iyidit and imin) should be in local time and indicate the ending timestamp of corresponding periods: e.g. for hourly data, 2021-09-12 13:00 indicates a record for the period between 2021-09-12 12:00 (inclusive) and 2021-09-12 13:00 (exclusive).

  • The table below gives the must-use (MU) and optional (O) additional input variables. If an optional input variable (O) is not available or will not be used by the model, enter ‘-999’ for this 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.

  • 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: tt in 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#

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

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] (measurement height (z) is needed in SUEWS_SiteSelect.txt)

11

MU

RH

Relative Humidity [%] (measurement height (z) is needed in SUEWS_SiteSelect.txt)

12

MU

Tair

Air temperature [°C] (measurement height (z) is needed in SUEWS_SiteSelect.txt)

13

MU

pres

Barometric pressure [kPa] (measurement height (z) is needed in SUEWS_SiteSelect.txt)

14

MU

rain

Rainfall [mm] (measurement height (z) is needed in SUEWS_SiteSelect.txt)

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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

CBL input files#

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

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 [Onomura et al., 2015].

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:

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

ESTM input files#

SUEWS_ESTMCoefficients.txt#

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

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

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

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

  • If less than five layers are used, the parameters for unused layers should be set to -999.

  • The ESTM coefficients with the prefix Surf_ must be specified for each surface type (plus snow) but the Wall_ and Internal_ variables apply to the building surfaces only.

  • For each grid, one set of ESTM coefficients must be specified for each surface type; for paved and building surfaces it is possible to specify up to three and five sets of coefficients per grid (e.g. to represent different building materials) using the relevant columns in SUEWS_SiteSelect.txt. For the model to use these columns in site select, the ESTMCode column in SUEWS_NonVeg.txt should be set to zero.

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

ESTMinput.nml#

ESTMinput.nml specifies the model settings and default values.

A sample file of ESTMinput.nml looks like

&ESTMinput
TsurfChoice= 0
evolveTibld= 0      ! !!!!!FO!!!!! 0 originally
ibldCHmod  = 0
LBC_soil   = 13.00             !!FO!! 4, 8 or 17 degC - could be set as the annual mean air temperature (12.8 degC for London)
THEAT_ON   = 18.
THEAT_OFF  = 22.
THEAT_FIX  = 19.
/

Note

The file contents can be in any order.

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

ESTMinput#
TsurfChoice#
Requirement

Required

Description

Source of surface temperature data used.

Configuration

Value

Comments

0

Tsurf in SSss_YYYY_ESTM_Ts_data_tt.txt used for all surface elements.

1

Input surface temperature are different for ground, roof and wall.

2

Wall surface temperature is different for four directions.

evolveTibld#
Requirement

Required

Description

Source of internal building temperature (Tibld)

Configuration

Value

Comments

0

Tiair in SSss_YYYY_ESTM_Ts_data_tt.txt used.

1

Tibld calculated considering the effect of anthropogenic heat from HVAC

2

Tibld calculated without considering the influence of HVAC.

IbldCHmod#
Requirement

Required

Description

Method to calculate internal convective heat exchange coefficients (CH) for internal building, wall and roof if evolveTibld is 1 or 2.

Configuration

Value

Comments

0

CHs are read from SUEWS_ESTMcoefficients.txt.

1

CHs are calculated based on ASHRAE (2001)

2

CHs are calculated based on Awbi (1998).

LBC_soil#
Requirement

Required

Description

Soil temperature at lowest boundary condition [˚C]

Configuration

to fill

Theat_fix#
Requirement

Required

Description

Ideal internal building temperature [˚C]

Configuration

to fill

Theat_off#
Requirement

Required

Description

Temperature at which heat control is turned off (used when evolveTibld=1) [˚C]

Configuration

to fill

Theat_on#
Requirement

Required

Description

Temperature at which heat control is turned on (used when evolveTibld =1) [˚C]

Configuration

to fill

SSss_YYYY_ESTM_Ts_data_tt.txt#

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

No.

Column Name

Use

Description

1

iy

MU

Year [YYYY]

2

id

MU

Day of year [DOY]

3

it

MU

Hour [H]

4

imin

MU

Minute [M]

5

Tiair

MU

Indoor air temperature [˚C]

6

Tsurf

MU

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

7

Troof

MU

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

8

Troad

MU

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

9

Twall

MU

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

10

Twall_n

MU

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

11

Twall_e

MU

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

12

Twall_s

MU

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

13

Twall_w

MU

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

SUEWS-SPARTACUS (SS) input files#

To run SUEWS-SS the SS specific files that need to be modified are:

Non-SS specific SUEWS input file parameters also need to have appropriate values. For example, LAI, albedos and emissivities are used by SUEWS-SS as explained in More background information.

RunControl.nml#

See NetRadiationMethod (sensible values are 1001, 1002 or 1003) in RunControl.nml parameter.

SUEWS_SPARTACUS.nml#

This file is used to specify the SS model options when coupled to SUEWS.

A sample file of SUEWS_SPARTACUS.nml is shown below:

&Spartacus
nlayers = 1
use_sw_direct_albedo = false
n_vegetation_region_urban = 1
nsw = 1
nlw = 1
nspec = 1
n_stream_sw_urban = 8
n_stream_lw_urban = 8
sw_dn_direct_frac = 0.0
air_ext_sw = 0.0
air_ssa_sw = 0.95
veg_ssa_sw = 0.13
air_ext_lw = 0.0
air_ssa_lw = 0.0
veg_ssa_lw = 0.01
ground_albedo_dir_mult_fact = 1.
/

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

SUEWS input converter#

Note

The SUEWS table converter has been integrated into SuPy as a command line tool suews-convert since v2020a. Please install SuPy and run suews-convert to convert input tables from an older version to a newer one.

Usage#

Please refer to the SuPy API page.

Example (from 2018a to 2020a)#

Assuming your 2018a files are all included in the folder your_2018a_folder and your desirable converted files should be placed in a new folder your_2020a_folder, please do the following in your command line tool:

suews-convert -f 2018a -t 2020a -i your_2018a_folder -o your_2020a_folder

Tip

suews-convert will use the RunControl.nml file in your original folder to determine the location of input tables.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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 Error messages: 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 Workflow of using SUEWS).

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#

Note

Temporal information in output files (i.e., iyidit and imin if existing) are in local time (i.e. consistent with Meteorological Input File) and indicate the ending timestamp of corresponding periods: e.g. for hourly data, 2021-09-12 13:00 indicates a record for the period between 2021-09-12 12:00 (inclusive) and 2021-09-12 13:00 (exclusive).

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 in forcing data [°C]

8

HDD4_T5d

5-day running-mean air temperature in forcing data [°C]

9

P_day

Daily total precipitation [mm]

10

DaysSR

Days since rain [days]

11

GDD_EveTr

Growing degree days for evergreen tree [°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 tree [°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 in forcing data [°C]

18

Tmax

Daily maximum temperature in forcing data [°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

LAIlumps

Leaf area index used in LUMPS (normalised 0-1) [-]

38

AlbSnow

Snow albedo [-]

39

DensSnow_Paved

Snow density - paved surface [kg m-3]

40

DensSnow_Bldgs

Snow density - building surface [kg m-3]

41

DensSnow_EveTr

Snow density - evergreen surface [kg m-3]

42

DensSnow_DecTr

Snow density - deciduous surface [kg m-3]

43

DensSnow_Grass

Snow density - grass surface [kg m-3]

44

DensSnow_BSoil

Snow density - bare soil surface [kg m-3]

45

DensSnow_Water

Snow density - water surface [kg m-3]

46

a1

OHM cofficient a1 - [-]

47

a2

OHM cofficient a2 [W m-2 h-1]

48

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 (see Wind, Temperature and Humidity Profiles in the Roughness Sublayer level details).

File format of SSss_YYYY_RSL_TT.txt:

Column

Name

Description

1

Year

Year [YYYY]

2

DOY

Day of year [DOY]

3

Hour

Hour [H]

4

Min

Minute [M]

5

Dectime

Decimal time [-]

6

z_1

Height at level 1 [m]

7

z_2

Height at level 2 [m]

8

z_3

Height at level 3 [m]

9

z_4

Height at level 4 [m]

10

z_5

Height at level 5 [m]

11

z_6

Height at level 6 [m]

12

z_7

Height at level 7 [m]

13

z_8

Height at level 8 [m]

14

z_9

Height at level 9 [m]

15

z_10

Height at level 10 [m]

16

z_11

Height at level 11 [m]

17

z_12

Height at level 12 [m]

18

z_13

Height at level 13 [m]

19

z_14

Height at level 14 [m]

20

z_15

Height at level 15 [m]

21

z_16

Height at level 16 [m]

22

z_17

Height at level 17 [m]

23

z_18

Height at level 18 [m]

24

z_19

Height at level 19 [m]

25

z_20

Height at level 20 [m]

26

z_21

Height at level 21 [m]

27

z_22

Height at level 22 [m]

28

z_23

Height at level 23 [m]

29

z_24

Height at level 24 [m]

30

z_25

Height at level 25 [m]

31

z_26

Height at level 26 [m]

32

z_27

Height at level 27 [m]

33

z_28

Height at level 28 [m]

34

z_29

Height at level 29 [m]

35

z_30

Height at level 30 [m]

36

U_1

Wind speed at level 1 [m s-1]

37

U_2

Wind speed at level 2 [m s-1]

38

U_3

Wind speed at level 3 [m s-1]

39

U_4

Wind speed at level 4 [m s-1]

40

U_5

Wind speed at level 5 [m s-1]

41

U_6

Wind speed at level 6 [m s-1]

42

U_7

Wind speed at level 7 [m s-1]

43

U_8

Wind speed at level 8 [m s-1]

44

U_9

Wind speed at level 9 [m s-1]

45

U_10

Wind speed at level 10 [m s-1]

46

U_11

Wind speed at level 11 [m s-1]

47

U_12

Wind speed at level 12 [m s-1]

48

U_13

Wind speed at level 13 [m s-1]

49

U_14

Wind speed at level 14 [m s-1]

50

U_15

Wind speed at level 15 [m s-1]

51

U_16

Wind speed at level 16 [m s-1]

52

U_17

Wind speed at level 17 [m s-1]

53

U_18

Wind speed at level 18 [m s-1]

54

U_19

Wind speed at level 19 [m s-1]

55

U_20

Wind speed at level 20 [m s-1]

56

U_21

Wind speed at level 21 [m s-1]

57

U_22

Wind speed at level 22 [m s-1]

58

U_23

Wind speed at level 23 [m s-1]

59

U_24

Wind speed at level 24 [m s-1]

60

U_25

Wind speed at level 25 [m s-1]

61

U_26

Wind speed at level 26 [m s-1]

62

U_27

Wind speed at level 27 [m s-1]

63

U_28

Wind speed at level 28 [m s-1]

64

U_29

Wind speed at level 29 [m s-1]

65

U_30

Wind speed at level 30 [m s-1]

66

T_1

Air temperature at level 1 [°C]

67

T_2

Air temperature at level 2 [°C]

68

T_3

Air temperature at level 3 [°C]

69

T_4

Air temperature at level 4 [°C]

70

T_5

Air temperature at level 5 [°C]

71

T_6

Air temperature at level 6 [°C]

72

T_7

Air temperature at level 7 [°C]

73

T_8

Air temperature at level 8 [°C]

74

T_9

Air temperature at level 9 [°C]

75

T_10

Air temperature at level 10 [°C]

76

T_11

Air temperature at level 11 [°C]

77

T_12

Air temperature at level 12 [°C]

78

T_13

Air temperature at level 13 [°C]

79

T_14

Air temperature at level 14 [°C]

80

T_15

Air temperature at level 15 [°C]

81

T_16

Air temperature at level 16 [°C]

82

T_17

Air temperature at level 17 [°C]

83

T_18

Air temperature at level 18 [°C]

84

T_19

Air temperature at level 19 [°C]

85

T_20

Air temperature at level 20 [°C]

86

T_21

Air temperature at level 21 [°C]

87

T_22

Air temperature at level 22 [°C]

88

T_23

Air temperature at level 23 [°C]

89

T_24

Air temperature at level 24 [°C]

90

T_25

Air temperature at level 25 [°C]

91

T_26

Air temperature at level 26 [°C]

92

T_27

Air temperature at level 27 [°C]

93

T_28

Air temperature at level 28 [°C]

94

T_29

Air temperature at level 29 [°C]

95

T_30

Air temperature at level 30 [°C]

96

q_1

Specific humidity at level 1 [g kg-1]

97

q_2

Specific humidity at level 2 [g kg-1]

98

q_3

Specific humidity at level 3 [g kg-1]

99

q_4

Specific humidity at level 4 [g kg-1]

100

q_5

Specific humidity at level 5 [g kg-1]

101

q_6

Specific humidity at level 6 [g kg-1]

102

q_7

Specific humidity at level 7 [g kg-1]

103

q_8

Specific humidity at level 8 [g kg-1]

104

q_9

Specific humidity at level 9 [g kg-1]

105

q_10

Specific humidity at level 10 [g kg-1]

106

q_11

Specific humidity at level 11 [g kg-1]

107

q_12

Specific humidity at level 12 [g kg-1]

108

q_13

Specific humidity at level 13 [g kg-1]

109

q_14

Specific humidity at level 14 [g kg-1]

110

q_15

Specific humidity at level 15 [g kg-1]

111

q_16

Specific humidity at level 16 [g kg-1]

112

q_17

Specific humidity at level 17 [g kg-1]

113

q_18

Specific humidity at level 18 [g kg-1]

114

q_19

Specific humidity at level 19 [g kg-1]

115

q_20

Specific humidity at level 20 [g kg-1]

116

q_21

Specific humidity at level 21 [g kg-1]

117

q_22

Specific humidity at level 22 [g kg-1]

118

q_23

Specific humidity at level 23 [g kg-1]

119

q_24

Specific humidity at level 24 [g kg-1]

120

q_25

Specific humidity at level 25 [g kg-1]

121

q_26

Specific humidity at level 26 [g kg-1]

122

q_27

Specific humidity at level 27 [g kg-1]

123

q_28

Specific humidity at level 28 [g kg-1]

124

q_29

Specific humidity at level 29 [g kg-1]

125

q_30

Specific humidity at level 30 [g kg-1]

SSss_YYYY_BL_TT.txt#

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

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

SSss_YYYY_SPARTACUS_TT.txt#

If the SPARTACUS model option is run, the following output file is created.

SPARTACUS output file format

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

alb

Albedo at top-of-canopy. Average of diffuse and direct albedos weighted by the amount of diffuse and direct shortwave radiation.

7

emis

Emissivity at top-of-canopy

8

Lemission

Longwave upward emission at top-of-canopy [W m-2]

9

Lup

Longwave upward (emission+reflected) at top-of-canopy [W m-2]

10

Kup

Shortwave upward (reflected) at top-of-canopy [W m-2]

11

Qn

Net all-wave radiation at top-of-canopy [W m-2]

12

LCAAbs1

Longwave absorption rate in clear-air part of layer 1 [W m-2]

13

LCAAbs2

Longwave absorption rate in clear-air part of layer 2 [W m-2]

14

LCAAbs3

Longwave absorption rate in clear-air part of layer 3 [W m-2]

15

LCAAbs4

Longwave absorption rate in clear-air part of layer 4 [W m-2]

16

LCAAbs5

Longwave absorption rate in clear-air part of layer 5 [W m-2]

17

LCAAbs6

Longwave absorption rate in clear-air part of layer 6 [W m-2]

18

LCAAbs7

Longwave absorption rate in clear-air part of layer 7 [W m-2]

19

LCAAbs8

Longwave absorption rate in clear-air part of layer 8 [W m-2]

20

LCAAbs9

Longwave absorption rate in clear-air part of layer 9 [W m-2]

21

LCAAbs10

Longwave absorption rate in clear-air part of layer 10 [W m-2]

22

LCAAbs11

Longwave absorption rate in clear-air part of layer 11 [W m-2]

23

LCAAbs12

Longwave absorption rate in clear-air part of layer 12 [W m-2]

24

LCAAbs13

Longwave absorption rate in clear-air part of layer 13 [W m-2]

25

LCAAbs14

Longwave absorption rate in clear-air part of layer 14 [W m-2]

26

LCAAbs15

Longwave absorption rate in clear-air part of layer 15 [W m-2]

27

LWallNet1

Net longwave flux into walls in layer 1 [W m-2]

28

LWallNet2

Net longwave flux into walls in layer 2 [W m-2]

29

LWallNet3

Net longwave flux into walls in layer 3 [W m-2]

30

LWallNet4

Net longwave flux into walls in layer 4 [W m-2]

31

LWallNet5

Net longwave flux into walls in layer 5 [W m-2]

32

LWallNet6

Net longwave flux into walls in layer 6 [W m-2]

33

LWallNet7

Net longwave flux into walls in layer 7 [W m-2]

34

LWallNet8

Net longwave flux into walls in layer 8 [W m-2]

35

LWallNet9

Net longwave flux into walls in layer 9 [W m-2]

36

LWallNet10

Net longwave flux into walls in layer 10 [W m-2]

37

LWallNet11

Net longwave flux into walls in layer 11 [W m-2]

38

LWallNet12

Net longwave flux into walls in layer 12 [W m-2]

39

LWallNet13

Net longwave flux into walls in layer 13 [W m-2]

40

LWallNet14

Net longwave flux into walls in layer 14 [W m-2]

41

LWallNet15

Net longwave flux into walls in layer 15 [W m-2]

42

LRfNet1

Net longwave flux into roofs in layer 1 [W m-2]

43

LRfNet2

Net longwave flux into roofs in layer 2 [W m-2]

44

LRfNet3

Net longwave flux into roofs in layer 3 [W m-2]

45

LRfNet4

Net longwave flux into roofs in layer 4 [W m-2]

46

LRfNet5

Net longwave flux into roofs in layer 5 [W m-2]

47

LRfNet6

Net longwave flux into roofs in layer 6 [W m-2]

48

LRfNet7

Net longwave flux into roofs in layer 7 [W m-2]

49

LRfNet8

Net longwave flux into roofs in layer 8 [W m-2]

50

LRfNet9

Net longwave flux into roofs in layer 9 [W m-2]

51

LRfNet10

Net longwave flux into roofs in layer 10 [W m-2]

52

LRfNet11

Net longwave flux into roofs in layer 11 [W m-2]

53

LRfNet12

Net longwave flux into roofs in layer 12 [W m-2]

54

LRfNet13

Net longwave flux into roofs in layer 13 [W m-2]

55

LRfNet14

Net longwave flux into roofs in layer 14 [W m-2]

56

LRfNet15

Net longwave flux into roofs in layer 15 [W m-2]

57

LRfIn1

Longwave flux into roofs in layer 1 [W m-2]

58

LRfIn2

Longwave flux into roofs in layer 2 [W m-2]

59

LRfIn3

Longwave flux into roofs in layer 3 [W m-2]

60

LRfIn4

Longwave flux into roofs in layer 4 [W m-2]

61

LRfIn5

Longwave flux into roofs in layer 5 [W m-2]

62

LRfIn6

Longwave flux into roofs in layer 6 [W m-2]

63

LRfIn7

Longwave flux into roofs in layer 7 [W m-2]

64

LRfIn8

Longwave flux into roofs in layer 8 [W m-2]

65

LRfIn9

Longwave flux into roofs in layer 9 [W m-2]

66

LRfIn10

Longwave flux into roofs in layer 10 [W m-2]

67

LRfIn11

Longwave flux into roofs in layer 11 [W m-2]

68

LRfIn12

Longwave flux into roofs in layer 12 [W m-2]

69

LRfIn13

Longwave flux into roofs in layer 13 [W m-2]

70

LRfIn14

Longwave flux into roofs in layer 14 [W m-2]

71

LRfIn15

Longwave flux into roofs in layer 15 [W m-2]

72

LTopNet

Top-of-canopy net longwave flux [W m-2]

73

LGrndNet

Net longwave flux into the ground [W m-2]

74

LTopDn

Top-of-canopy downwelling longwave flux [W m-2]

75

KCAAbs1

Shortwave absorption rate in clear-air part of layer 1 [W m-2]

76

KCAAbs2

Shortwave absorption rate in clear-air part of layer 2 [W m-2]

77

KCAAbs3

Shortwave absorption rate in clear-air part of layer 3 [W m-2]

78

KCAAbs4

Shortwave absorption rate in clear-air part of layer 4 [W m-2]

79

KCAAbs5

Shortwave absorption rate in clear-air part of layer 5 [W m-2]

80

KCAAbs6

Shortwave absorption rate in clear-air part of layer 6 [W m-2]

81

KCAAbs7

Shortwave absorption rate in clear-air part of layer 7 [W m-2]

82

KCAAbs8

Shortwave absorption rate in clear-air part of layer 8 [W m-2]

83

KCAAbs9

Shortwave absorption rate in clear-air part of layer 9 [W m-2]

84

KCAAbs10

Shortwave absorption rate in clear-air part of layer 10 [W m-2]

85

KCAAbs11

Shortwave absorption rate in clear-air part of layer 11 [W m-2]

86

KCAAbs12

Shortwave absorption rate in clear-air part of layer 12 [W m-2]

87

KCAAbs13

Shortwave absorption rate in clear-air part of layer 13 [W m-2]

88

KCAAbs14

Shortwave absorption rate in clear-air part of layer 14 [W m-2]

89

KCAAbs15

Shortwave absorption rate in clear-air part of layer 15 [W m-2]

90

KWallNet1

Net shortwave flux into walls in layer 1 [W m-2]

91

KWallNet2

Net shortwave flux into walls in layer 2 [W m-2]

92

KWallNet3

Net shortwave flux into walls in layer 3 [W m-2]

93

KWallNet4

Net shortwave flux into walls in layer 4 [W m-2]

94

KWallNet5

Net shortwave flux into walls in layer 5 [W m-2]

95

KWallNet6

Net shortwave flux into walls in layer 6 [W m-2]

96

KWallNet7

Net shortwave flux into walls in layer 7 [W m-2]

97

KWallNet8

Net shortwave flux into walls in layer 8 [W m-2]

98

KWallNet9

Net shortwave flux into walls in layer 9 [W m-2]

99

KWallNet10

Net shortwave flux into walls in layer 10 [W m-2]

100

KWallNet11

Net shortwave flux into walls in layer 11 [W m-2]

101

KWallNet12

Net shortwave flux into walls in layer 12 [W m-2]

102

KWallNet13

Net shortwave flux into walls in layer 13 [W m-2]

103

KWallNet14

Net shortwave flux into walls in layer 14 [W m-2]

104

KWallNet15

Net shortwave flux into walls in layer 15 [W m-2]

105

KRfNet1

Net shortwave flux into roofs in layer 1 [W m-2]

106

KRfNet2

Net shortwave flux into roofs in layer 2 [W m-2]

107

KRfNet3

Net shortwave flux into roofs in layer 3 [W m-2]

108

KRfNet4

Net shortwave flux into roofs in layer 4 [W m-2]

109

KRfNet5

Net shortwave flux into roofs in layer 5 [W m-2]

110

KRfNet6

Net shortwave flux into roofs in layer 6 [W m-2]

111

KRfNet7

Net shortwave flux into roofs in layer 7 [W m-2]

112

KRfNet8

Net shortwave flux into roofs in layer 8 [W m-2]

113

KRfNet9

Net shortwave flux into roofs in layer 9 [W m-2]

114

KRfNet10

Net shortwave flux into roofs in layer 10 [W m-2]

115

KRfNet11

Net shortwave flux into roofs in layer 11 [W m-2]

116

KRfNet12

Net shortwave flux into roofs in layer 12 [W m-2]

117

KRfNet13

Net shortwave flux into roofs in layer 13 [W m-2]

118

KRfNet14

Net shortwave flux into roofs in layer 14 [W m-2]

119

KRfNet15

Net shortwave flux into roofs in layer 15 [W m-2]

120

KRfIn1

Shortwave flux into roofs in layer 1 [W m-2]

121

KRfIn2

Shortwave flux into roofs in layer 2 [W m-2]

122

KRfIn3

Shortwave flux into roofs in layer 3 [W m-2]

123

KRfIn4

Shortwave flux into roofs in layer 4 [W m-2]

124

KRfIn5

Shortwave flux into roofs in layer 5 [W m-2]

125

KRfIn6

Shortwave flux into roofs in layer 6 [W m-2]

126

KRfIn7

Shortwave flux into roofs in layer 7 [W m-2]

127

KRfIn8

Shortwave flux into roofs in layer 8 [W m-2]

128

KRfIn9

Shortwave flux into roofs in layer 9 [W m-2]

129

KRfIn10

Shortwave flux into roofs in layer 10 [W m-2]

130

KRfIn11

Shortwave flux into roofs in layer 11 [W m-2]

131

KRfIn12

Shortwave flux into roofs in layer 12 [W m-2]

132

KRfIn13

Shortwave flux into roofs in layer 13 [W m-2]

133

KRfIn14

Shortwave flux into roofs in layer 14 [W m-2]

134

KRfIn15

Shortwave flux into roofs in layer 15 [W m-2]

135

KTopDnDir

Direct shortwave flux into roofs [W m-2]

136

KTopNet

Top-of-canopy net shortwave flux [W m-2]

137

KGrndDnDir

Direct downwelling shortwave flux into the ground [W m-2]

138

KGrndNet

Net shortwave flux into the ground [W m-2]

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Troubleshooting#

How to report an issue of this manual?#

Please click the link in the top banner of each page to report page-specific issues.

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Tutorials#

SUEWS#

To help users getting started with SUEWS, the community is working on setting up tutorials and instructions for different parts of SUEWS and related tool.

The tutorials are available are found in the table below.

Note

the following tutorials are hosted on a separate website including other UMEP related tutorials.

Topic

Application

IntroductionToSuews

Energy, water and radiation fluxes for one location

SUEWSAdvanced

Energy, water and radiation fluxes for one location

SUEWSSpatial

Energy, water and radiation fluxes for a spatial grid

SUEWSWUDAPT

Making use of WUDAPT local climate zones in SUEWS

SuPy#

For Python users, a Python package SuPy with SUEWS as the calculation kernel is available to conduct SUEWS simulations. SuPy tutorials are provided at its tutorial site.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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

CBL#

Convective boundary layer

DEM#

Digital Elevation Model

DSM#

Digital surface model

DTM#

Digital Terrain Model

ESTM#

Element Surface Temperature Method [Offerle et al., 2005]

L↓#

Incoming longwave radiation

LAI#

Leaf area index

LUMPS#

Local-scale Urban Meteorological Parameterization Scheme [Loridan et al., 2011]

NARP#

Net All-wave Radiation Parameterization [Loridan et al., 2011, Offerle et al., 2003]

OHM#

Objective Hysteresis Model [Grimmond and Oke, 1999, Grimmond and Oke, 2002, Grimmond et al., 1991]

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 and Grimmond, 2011, Lindberg et al., 2008]

SVF#

Sky view factor

θ#

Potential temperature

tt#

Time step of data

UMEP#

Urban Multi-scale Environmental Predictor

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Contributing Guide#

Note

This guide is heavily inspired by the excellent work by the xarray project: much appreciated!

Warning

This guide is incomplete and under construction: information here might be INCORRECT.

We welcome all contributions – bug reports/fixes, documentation corrctions/improments, enhancements, and ideas – as long as they apply to the SUEWS domain, please follow these guides:

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Bug reports and enhancement requests#

where to report a bug?

how to report a bug? what to be included? - version info - MWE (minimal working example) to reproduce the issue

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Documentation Guide#

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Development Guide#

Note

If you are interested in contributing to the code please open a new discussion in the UMEP Community to illustrate your proposal: we are happy to collaborate in an open development mode.

Essential pre-requisites#

compliation

git

testing

Code guidelines#

If you are interested in contributing to the code please contact Sue Grimmond.

Coding#
  1. Core physics and calculation 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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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 – onwards

Team Leader

Dr Ting Sun

University of Reading, UK

AnOHM; Documentation system; WRF-SUEWS coupling; SuPy (python wrapper of SUEWS)

v2017b – onwards

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 – owards

Lead Developer of UMEP

Dr Lewis Blunn

University of Reading, UK

SUEWS-SPARTACUS coupling; RSL improvement

v2021a

Major contributor to SUEWS-SPARTACUS coupling

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

ERC Synergy

urbisphere 855005

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version History#

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Warning

Information here is ONLY for developers.

Version 2021a (in development)#

  • Improvement

    1. Added a new RoughLenMomMethod (4) to calculate roughness and displacement height as a function of plan area index and effective height of roughness elements following the ensemble mean of Fig 1a in [Grimmond and Oke, 1999]

    2. Coupled SPARCATUS into SUEWS for detailed modelling of radiation balance.

    3. Added a new option DiagMethod in RunControl.nml to control the output of radiation balance.

  • Changes

    1. TO ADD

  • Fix

    1. fixed a bug in radiation scheme: observed incoming longwave radiation cannot be used.

  • Known issues

    1. Wind direction is not currently downscaled so non -999 values will cause an error.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version 2020a (released on 14 May 2020)#

Note

In a future release, we will ONLY deliver SUEWS along with SuPy as a command line tool suews-run: release of standalone SUEWS binaries will be stopped to ease our maintenance load and to facilitate rapid developments. Users will need to have Python 3.6+ to install SuPy:

python3 -m pip install -U supy

However, as the source code of SUEWS are public, users can feel free to compile standalone binaries for platforms of their own interests.

  • Improvement

    1. A ponding water scheme is added in the automatic irrigation calculation; useful when a certain depth of ponding water to maintain in irrigation (e.g., flooding irrigation in rice crop-field).

    2. Irrigation fraction can be specified for all surfaces (previously only available for vegetated surfaces)

    3. A U-shape approach for calculating HDD/CDD is introduced to account for a wide comfort zone between heating and cooling critical temperatures.

  • Changes

    1. A new RoughLenHeatMethod option 5: adaptively choose option 1 for fully pervious surface or 2 otherwise (if any impervious surface exists).

    2. A new column H_maintain is added in SUEWS_Irrigation.txt to set ponding water depth.

    3. New columns to specify irrigation fractions for non-vegetated surfaces in SUEWS_SiteSelect.txt.

    4. A new scheme option BaseTMethod in RunControl.nml to set calculation scheme for HDD/CDD.

  • Fix

    NONE.

  • Known issues

    1. Wind direction is not currently downscaled so non -999 values will cause an error.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version 2019a (released on 15 November 2019)#

  • Improvement

    1. An anthropogenic emission module is added. Module details refer to Järvi et al. (2019) [Järvi et al., 2019].

    2. A canyon profile module is added. Module details refer to Theeuwes et al. (2019) [Theeuwes et al., 2019].

  • Changes

    1. Input file SUEWS_AnthropogenicHeat.txt is renamed to SUEWS_AnthropogenicEmission.txt with new parameters added: MinFCMetab, MaxFCMetab, FrPDDwe, FcEF_v_kgkmWD and FcEF_v_kgkmWE.

    2. BLUEWS has been recovered; set CBLUse to use it.

    3. Removed features:

    • SOLWEIG: fully removed from code.

    • netCDF: fully removed as this is very infrequently used; users who need this are suggested to use SuPy with help from pandas and xarray to save results in netCDF more elegantly.

  • Fix

    1. Fixed a bug in LAI calculation for longterm runs.

    2. Fixed a bug in net all-wave radiation differential calculation for OHM.

    3. Fixed a bug in GDD/SDD calculation that different vegetative land covers could unexpectedly affect each other.

    4. Fixed water redistribution bug in snow module.

  • Known issues

    1. Wind direction is not currently downscaled so non -999 values will cause an error.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version 2018c (released on 21 February 2019)#

Download page (under assets)

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version 2018b (released on 17 December 2018)#

Download page (under assets)

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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version 2018a (released on 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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version 2017b (released on 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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version 2017a (released on 1 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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version 2016a (released on 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version 2014b (released on 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.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Version 2014a (released on 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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)

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo 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) [Loridan et al., 2011, Offerle et al., 2003] scheme calculates outgoing shortwave and incoming and outgoing longwave radiation components based on incoming shortwave radiation, temperature, relative humidity and surface characteristics (albedo, emissivity).

  5. SPARTACUS-Surface (SS) computes the 3D interaction of shortwave and longwave radiation with complex surface canopies, including vegetated and urban canopies (with or without vegetation). More details can be found in the SPARTACUS-Surface (SS) section.

Anthropogenic heat flux, QF#

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

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

    • Loridan et al. [2011] 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:

Storage heat flux, ΔQS#

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

    • OHM (Objective Hysteresis Model) [Grimmond and Oke, 1999, Grimmond and Oke, 2002, Grimmond et al., 1991]. 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]. OHM approach using analytically-derived coefficients. Not recommended in this version.

    • ESTM (Element Surface Temperature Method) [Offerle et al., 2005]. 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 and Oke, 2002] 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 [Järvi et al., 2011] [Ward et al., 2016]. 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] and urban evaporation-interception scheme of Grimmond and Oke [1991].

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

  • Irrigation can be modelled [Järvi et al., 2011] 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]. 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] calculates the CBL height, temperature and humidity during daytime [Onomura et al., 2015].

Wind, Temperature and Humidity Profiles in the Roughness Sublayer#

A dignostic RSL scheme for calculating the wind, temperature and humidity profiles in the roughness sublayer is implemented in 2020a following Harman and Finnigan [2007], Harman and Finnigan [2008] and Theeuwes et al. [2019]. An recent application of this RSL scheme can be found in Tang et al. [2021].

The diagnostic profiles are outputed in 30 uneven levels between the ground and forcing height, which are divided into two groups:

  • One group of levels are evenly distributed within the urban canopy layer characterised by mean height of roughness elements (e.g. buildings, trees, etc.) \(z_H\), which determines the number of layers within urban canopy \(n_{can}\):

\[ n_{can} = \begin{cases} 3 & \text{if } z_H \leq \text{2 m} \\ 10 & \text{if } \text{2 m} \lt z_H \leq \text{10 m} \\ 15 & \text{if } z_H \gt \text{10 m} \\ \end{cases} \]
  • The other levels are evenly distributed between the urban canopy layer top and forcing height.

Note

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

Common near-surface diagnostics:

  • T2: air temperature at 2 m agl

  • Q2: air specific humidity at 2 m agl

  • RH2: air relative humidity at 2 m agl

  • U10: wind speed at 10 m agl

are calculated by the RSL scheme by interpolating RSL profile results to the corresponding diagnostic heights.

SPARTACUS-Surface (SS)#

Warning

This module is highly experimental and not yet fully tested: description here is not yet complete, either. Please refer to the original SPARTACUS-Surface page for more details, which may differ from the coupled version in SUEWS described below due to possibly different implementations.

Note

Future Work

  • New SUEWS input table containing SPARTACUS profiles

  • Add check for consistency of SUEWS and SS surface fractions

  • Include snow

Introduction to SS#

The SPARTACUS-Surface module computes the 3D interaction of shortwave and longwave radiation with complex surface canopies, including vegetated and urban canopies (with or without vegetation).

Multi-layer structure of SS

Multi-layer structure (horizontal dashed lines) used in SS to characterise differences in the canopy (Cyan building, Green – vegetation). Source: SPARTACUS-Surface GH page#

It uses a multi-layer description of the canopy (Fig. 1.1), with a statistical description of the horizontal distribution of trees and buildings. Assumptions include:

  • Trees are randomly distributed.

  • Wall-to-wall separation distances follow an exponential probability distribution.

  • From a statistical representation of separation distances one can determine the probabilities of light being intercepted by trees, walls and the ground.

In the tree canopy (i.e. between buildings) there are two or three regions (based on user choice) (Fig. 1.2): clear-air and either one vegetated region or two vegetated regions of equal fractional cover but different extinction coefficient. Assumptions include:

  • The rate of exchange of radiation between the clear and vegetated parts of a layer are assumed to be proportional to the length of the interface between them.

  • Likewise for the rate of interception of radiation by building walls.

Areas between trees

Areas between trees. Source: SPARTACUS-Surface GH page#

Each time light is intercepted it can undergo diffuse or specular reflection, be absorbed or be transmitted (as diffuse radiation). The probabilities for buildings and the ground are determined by albedos and emissivities, and for trees are determined by extinction coefficients and single scattering albedos.

SUEWS-SS Implementation#
  • Maximum of 15 vertical layers.

  • Building and tree fractions, building and tree dimensions, building albedo and emissivity, and diffuse versus specular reflection, can be treated as vertically heterogenous or uniform with height depending on parameter choices.

  • As tree fraction increases towards 1 it is assumed that the tree crown merges when calculating tree perimeters.

  • Representing horizontal heterogeneity in the tree crowns is optional. When represented it is assumed that heterogeneity in leaf area index is between the core and periphery of the tree, not between trees.

  • When calculating building perimeters it is assumed that buildings do not touch (analogous to crown shyness) as building fraction increases towards 1.

  • Vegetation extinction coefficients (calculated from leaf area index, LAI) are assumed to be the same in all vegetated layers.

  • Building facet and ground temperatures are equal to SUEWS TSfc_C (i.e.surface temperature) 1.

  • Leaf temperatures are equal to SUEWS temp_C (i.e. air temperature within the canopy) 2.

  • Ground albedo and emissivity are an area weighted average of SUEWS paved, grass, bare soil and water values.

  • Inputs from SUEWS: sfr, zenith_deg, TSfc_C, avKdn, ldown, temp_c, alb_next, emis, LAI_id.

  • SS specific input parameters: read in from SUEWS_SPARTACUS.nml.

  • Outputs used by SUEWS: alb_spc, emis_spc, lw_emission_spc.

  • Although the radiation is calculated in multiple vertical layers within SS it is only the upwelling top-of-canopy fluxes: alb_spc*avKdn, (emis_spc)*ldown, and lw_emission_spc that are used by SUEWS.

  • Output variables (including multi-layer ones) are in SUEWS-SS output file SSss_YYYY_SPARTACUS.txt. 3

RSL and SS Canopy Representation Comparison#
  • The RSL has 30 levels but when the average building height is <2 m, < 12 m and > 12 m there are 3, 10 and 15 evenly spaced layers in the canopy.

  • The remaining levels are evenly spaced up to the forcing level (Fig. 1.3).

  • The buildings are assumed to be uniform height.

SUEWS-RSL

SUEWS-RSL module assumes the RSL has 30 layers that are spread between the canopy and within the atmosphere above#

A maximum of 15 layers are used by SS (vertial_layers_SS-RSL), with the top of the highest layer at the tallest building height. The layer heights are user defined and there is no limit on maximum building height. The buildings are allowed to vary in height.

Vertical layers used by SS

Vertical layers used by SS#

How to use SUEWS-SS#
Inputs#

To run SUEWS-SS the SS specific files that need to be modified are:

Note

Non-SS specific SUEWS input file parameters also need to have appropriate values. For example, LAI, albedos and emissivities are used by SUEWS-SS as explained in More background information.

More background information#
Vegetation single scattering albedo (SSA)#

The shortwave broadband SSA is equal to the sum of the broadband reflectance \(R\) and broadband transmittance \(T\) [Yang et al., 2020]. Given reflectance \(r\) and transmittance \(t\) spectra the SSA is calculated to modify equation

\[\text{SSA} = \ \frac{\int_{\sim 400\ \text{nm}}^{\sim 2200\ \text{nm}}{r \times S}\text{dλ}}{\int_{\sim 400\ \text{nm}}^{\sim 2200\ \text{nm}}S\text{dλ}} + \frac{\int_{\sim 400\ \text{nm}}^{\sim 2200\ \text{nm}}{t \times S}\text{dλ}}{\int_{\sim 400\ \text{nm}}^{\sim 2200\ \text{nm}}S\text{dλ}}\]

where \(S\) clear-sky surface spectrum :numfig:`rami5`.

The integrals are performed between 400 nm and 2200 nm because this is the spectral range that RAMI55 Järvselja birch stand forest spectra are available. This is a reasonable approximation since it is where the majority of incoming SW energy resides (as seen from the clear-sky surface spectrum in Fig. 6).

Users can use the default value of 0.46, from RAMI5 Järvselja birch stand forest tree types or calculate their own SSA (Fig. 1.5). There are more tree R and T profiles here5,

Overview of SUEWS

RAMI55 data used to calculate R, T, and SSA, and R, T, and SSA values: (a) top-of-atmosphere incoming solar flux and clear-sky surface spectrum [Hogan and Matricardi, 2020] (b) RAMI5 r and t spectra, and (c) calculated broadband R, T, and SSA values.#

The longwave broadband SSA could be calculated in the same way but with the integral over the thermal infra-red (8-14 𝜇m), S replaced with the Plank function at Earth surface temperature, and r and t for the spectra for the thermal infra-red. The approximation that R + T = 2R can be made. r for different materials is available at https://speclib.jpl.nasa.gov/library. The peak in the thermal infra-red is ~10 𝜇m. Based on inspection of r profiles for several tree species SSA=0.06 is the default value.

Building albedo and emissivity#

Use broadband values in Table C.1 of Kotthaus et al. [2014]. Full spectra can be found in the spectral library documentation.

Ground albedo and emissivity#

In SUEWS-SS this is calculated as:

(𝛼(1)*sfr(PavSurf)+𝛼(5)*sfr(GrassSurf)+𝛼(6)*sfr(BSoilSurf)+𝛼(7)*sfr(WaterSurf))/ (sfr(PavSurf) + sfr(GrassSurf) + sfr(BSoilSurf) + sfr(WaterSurf))

where 𝛼 is either the ground albedo or emissivity.

𝛼 values for the surfaces should be set by specifying surface codes in SUEWS_SiteSelect.txt. Codes should correspond to existing appropriate surfaces in SUEWS_NonVeg.txt and SUEWS_NonVeg.txt. Alternatively, new surfaces can be made in SUEWS_NonVeg.txt and SUEWS_NonVeg.txt with 𝛼 values obtained for example from the spectral library.

Consistency of SUEWS and SS parameters#

SUEWS building and tree (evergreen+deciduous) fractions in SUEWS_SiteSelect.txt should be consistent with the SUEWS_SPARTACUS.nml building_frac and veg_frac of the lowest model layer.

Leaf area index (LAI)#

The total vertically integrated LAI provided by SUEWS is used in SS to determine the LAI and vegetation extinction coefficient in each layer. Surface codes in SUEWS_SiteSelect.txt should correspond to appropriate LAI values in SUEWS_Veg.txt.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

References#

Allen et al. 2010

Allen, L., Lindberg, F., and Grimmond, C. S. B. Global to city scale urban anthropogenic heat flux: Model and variability. Int. J. Climatol., 31(13):1990–2005, September 2010. doi:10.1002/joc.2210.

Anandakumar 1999

Anandakumar, K. A study on the partition of net radiation into heat fluxes on a dry asphalt surface. Atmos. Environ., 33(24-25):3911–3918, October 1999. doi:10.1016/s1352-2310(99)00133-8.

Asaeda and Ca 1993

Asaeda, Takashi and Ca, Vu Thanh. The subsurface transport of heat and moisture and its effect on the environment: A numerical model. Boundary-Layer Meteorol, 65(1-2):159–179, July 1993. doi:10.1007/bf00708822.

Auer 1974

Auer, August H. The rain versus snow threshold temperatures. Weatherwise, 27(2):67–67, April 1974. doi:10.1080/00431672.1974.9931684.

Bellucco et al. 2017

Bellucco, Veronica, Marras, Serena, Grimmond, C. Susan B., Järvi, Leena, Sirca, Costantino, and Spano, Donatella. Modelling the biogenic CO 2 exchange in urban and non-urban ecosystems through the assessment of light-response curve parameters. Agr. Forest Meteorol., 236:113–122, April 2017. doi:10.1016/j.agrformet.2016.12.011.

Berrizbeitia et al. 2020

Berrizbeitia, Saioa Etxebarria, Jadraque Gago, Eulalia, and Muneer, Tariq. Empirical Models for the Estimation of Solar Sky-Diffuse Radiation. A Review and Experimental Analysis. Energies, 13(3):701, Feb 2020. doi:10.3390/en13030701.

Best and Grimmond 2014

Best, M.J. and Grimmond, C.S.B. Importance of initial state and atmospheric conditions for urban land surface models' performance. Urban Clim., 10:387–406, December 2014. doi:10.1016/j.uclim.2013.10.006.

Breuer et al. 2003

Breuer, Lutz, Eckhardt, Klaus, and Frede, Hans-Georg. Plant parameter values for models in temperate climates. Ecol. Model., 169(2-3):237–293, November 2003. doi:10.1016/s0304-3800(03)00274-6.

Businger et al. 1971

Businger, J. A., Wyngaard, J. C., Izumi, Y., and Bradley, E. F. Flux-profile relationships in the atmospheric surface layer. J. Atmos. Sci., 28(2):181–189, March 1971. doi:10.1175/1520-0469(1971)028<0181:fprita>2.0.co;2.

Calder and Wright 1986

Calder, I. R. and Wright, I. R. Gamma ray attenuation studies of interception from sitka spruce: Some evidence for an additional transport mechanism. Water Resour. Res., 22(3):409–417, March 1986. doi:10.1029/wr022i003p00409.

Campbell and Norman 1998

Campbell, Gaylon S. and Norman, John M. Wind, chapter Wind, pages 63–75. Springer New York, New York, NY, 1998. doi:10.1007/978-1-4612-1626-1_5.

Cleugh and Grimmond 2001

Cleugh, H. A. and Grimmond, C. S. B. Modelling regional scale surface energy exchanges and cbl growth in a heterogeneous, urban-rural landscape. Bound.-Layer Meteorol., 98(1):1–31, January 2001. doi:10.1023/a:1018798928158.

Davies and Hollis 1981

Davies, Hilary and Hollis, T. Measurements of rainfall-runoff volume relationships and water balance for roofs and roads. In Second International Conference on Urban Storm Drainage, volume 434, 441. 1981.

Doll et al. 1985

Doll, Dennis, Ching, J. K. S., and Kaneshiro, Jack. Parameterization of subsurface heating for soil and concrete using net radiation data. Boundary-Layer Meteorol, 32(4):351–372, August 1985. doi:10.1007/bf00122000.

Dyer 1974

Dyer, A. J. A review of flux-profile relationships. Boundary-Layer Meteorol, 7(3):363–372, November 1974. doi:10.1007/bf00240838.

Falk and Niemczynowicz 1978

Falk, J. and Niemczynowicz, J. Characteristics of the above ground runoff in sewered catchments. In Proc. Internat. Conf. on Urban Storm Drainage, 159–171. John Wiley and Sons, New York, 1978.

Flanagan et al. 2002

Flanagan, Lawrence B., Wever, Linda A., and Carlson, Peter J. Seasonal and interannual variation in carbon dioxide exchange and carbon balance in a northern temperate grassland. Global Change Biol., 8(7):599–615, June 2002. doi:10.1046/j.1365-2486.2002.00491.x.

Fuchs and Hadas 1972

Fuchs, Marcel and Hadas, Amos. The heat flux density in a non-homogeneous bare loessial soil. Boundary-Layer Meteorol, 3(2):191–200, December 1972. doi:10.1007/bf02033918.

Grimmond 1992

Grimmond, C. S. B. The suburban energy balance: Methodological considerations and results for a mid-latitude west coast city under winter and spring conditions. Int. J. Climatol., 12(5):481–497, July 1992. doi:10.1002/joc.3370120506.

Grimmond and Oke 1991

Grimmond, C. S. B. and Oke, T. R. An evapotranspiration-interception model for urban areas. Water Resour. Res., 27(7):1739–1755, July 1991. doi:10.1029/91wr00557.

Grimmond and Oke 1999

Grimmond, C. S. B. and Oke, T. R. Heat storage in urban areas: Local-scale observations and evaluation of a simple model. J. Appl. Meteor., 38(7):922–940, July 1999. doi:10.1175/1520-0450(1999)038<0922:hsiual>2.0.co;2.

Grimmond and Oke 2002

Grimmond, C. S. B. and Oke, T. R. Turbulent heat fluxes in urban areas: Observations and a local-scale urban meteorological parameterization scheme (LUMPS). J. Appl. Meteor., 41(7):792–810, July 2002. doi:10.1175/1520-0450(2002)041<0792:thfiua>2.0.co;2.

Grimmond et al. 1986

Grimmond, C. S. B., Oke, T. R., and Steyn, D. G. Urban water balance: 1. a model for daily totals. Water Resour. Res., 22(10):1397–1403, September 1986. doi:10.1029/wr022i010p01397.

Grimmond et al. 1991

Grimmond, C.S.B., Cleugh, H.A., and Oke, T.R. An objective urban heat storage model and its comparison with other schemes. Atmospheric Environment. Part B. Urban Atmosphere, 25(3):311–326, January 1991. doi:10.1016/0957-1272(91)90003-w.

Halldin et al. 1979

Halldin, S., Grip, H., and Perttu, K. Model for energy exchange of a pine forest canopy. In Comparison of Forest Water and Energy Exchange Models, pages 59–75. Elsevier, 1979. doi:10.1016/b978-0-444-41844-9.50012-3.

Harman and Finnigan 2007

Harman, Ian N. and Finnigan, John J. A simple unified theory for flow in the canopy and roughness sublayer. Boundary-Layer Meteorol, 123(2):339–363, March 2007. doi:10.1007/s10546-006-9145-6.

Harman and Finnigan 2008

Harman, Ian N. and Finnigan, John J. Scalar concentration profiles in the canopy and roughness sublayer. Boundary-Layer Meteorol, 129(3):323–351, October 2008. doi:10.1007/s10546-008-9328-4.

Havu et al. 2022

Havu, M., Kulmala, L., Kolari, P., Vesala, T., Riikonen, A., and Järvi, L. Carbon sequestration potential of street tree plantings in Helsinki. Biogeosciences, 19(8):2121–2143, April 2022. doi:10.5194/bg-19-2121-2022.

Hogan 2019

Hogan, Robin J. Flexible Treatment of Radiative Transfer in Complex Urban Canopies for Use in Weather and Climate Models. Boundary-Layer Meteorol., 173(1):53–78, Oct 2019. doi:10.1007/s10546-019-00457-0.

Hogan and Matricardi 2020

Hogan, Robin J. and Matricardi, Marco. Evaluating and improving the treatment of gases in radiation schemes: the Correlated K-Distribution Model Intercomparison Project (CKDMIP). Geosci. Model Dev., 13(12):6501–6521, Dec 2020. doi:10.5194/gmd-13-6501-2020.

Hogan et al. 2018

Hogan, Robin J., Quaife, Tristan, and Braghiere, Renato. Fast matrix treatment of 3-D radiative transfer in vegetation canopies: SPARTACUS-Vegetation 1.1. Geosci. Model Dev., 11(1):339–350, Jan 2018. doi:10.5194/gmd-11-339-2018.

Högström 1988

Högström, Ulf. Non-dimensional wind and temperature profiles in the atmospheric surface layer: A re-evaluation. Boundary-Layer Meteorol, 42(1-2):55–78, January 1988. doi:10.1007/bf00119875.

Iamarino et al. 2011

Iamarino, Mario, Beevers, Sean, and Grimmond, C. S. B. High-resolution (space, time) anthropogenic heat emissions: London 1970-2025. Int. J. Climatol., 32(11):1754–1767, July 2011. doi:10.1002/joc.2390.

Jarvis 1976

Jarvis, P. G. The interpretation of the variations in leaf water potential and stomatal conductance found in canopies in the field. Phil. Trans. R. Soc. Lond. B, 273(927):593–610, February 1976. doi:10.1098/rstb.1976.0035.

Järvi et al. 2014

Järvi, L., Grimmond, C. S. B., Taka, M., Nordbo, A., Setälä, H., and Strachan, I. B. Development of the surface urban energy and water balance scheme (SUEWS) for cold climate cities. Geosci. Model Dev., 7(4):1691–1711, August 2014. doi:10.5194/gmd-7-1691-2014.

Järvi et al. 2011

Järvi, L., Grimmond, C.S.B., and Christen, A. The surface urban energy and water balance scheme (SUEWS): Evaluation in Los Angeles and Vancouver. J. Hydrol., 411(3-4):219–237, December 2011. doi:10.1016/j.jhydrol.2011.10.001.

Järvi et al. 2019

Järvi, Leena, Havu, Minttu, Ward, Helen C., Bellucco, Veronica, McFadden, Joseph P., Toivonen, Tuuli, Heikinheimo, Vuokko, Kolari, Pasi, Riikonen, Anu, and Grimmond, C. Sue B. Spatial modeling of Local-Scale biogenic and anthropogenic carbon dioxide emissions in Helsinki. J. Geophys. Res. Atmos., 124(15):8363–8384, August 2019. doi:10.1029/2018jd029576.

Kanda et al. 2007

Kanda, M., Kanega, M., Kawai, T., Moriwaki, R., and Sugawara, H. Roughness lengths for momentum and heat derived from outdoor urban scale models. J. Appl. Meteorol. Clim., 46(7):1067–1079, July 2007. doi:10.1175/jam2500.1.

Kawai et al. 2009

Kawai, Toru, Ridwan, Mohammad Kholid, and Kanda, Manabu. Evaluation of the simple urban energy balance model using selected data from 1-yr flux observations at two cities. J. Appl. Meteorol. Clim., 48(4):693–715, April 2009. doi:10.1175/2008jamc1891.1.

Kent et al. 2017a

Kent, Christoph W., Grimmond, Sue, Barlow, Janet, Gatey, David, Kotthaus, Simone, Lindberg, Fredrik, and Halios, Christos H. Evaluation of urban local-scale aerodynamic parameters: Implications for the vertical profile of wind speed and for source areas. Boundary-Layer Meteorol, 164(2):183–213, April 2017. doi:10.1007/s10546-017-0248-z.

Kent et al. 2017b

Kent, Christoph W., Grimmond, Sue, and Gatey, David. Aerodynamic roughness parameters in cities: Inclusion of vegetation. J. Wind Eng. Ind. Aerod., 169:168–176, October 2017. doi:10.1016/j.jweia.2017.07.016.

Kokkonen et al. 2018a

Kokkonen, T. V., Grimmond, C. S. B., Christen, A., Oke, T. R., and Järvi, L. Changes to the water balance over a century of urban development in two neighborhoods: Vancouver, Canada. Water Resour. Res., 54(9):6625–6642, September 2018. doi:10.1029/2017wr022445.

Kokkonen et al. 2018b

Kokkonen, T.V., Grimmond, C.S.B., Räty, O., Ward, H.C., Christen, A., Oke, T.R., Kotthaus, S., and Järvi, L. Sensitivity of surface urban energy and water balance scheme (SUEWS) to downscaling of reanalysis forcing data. Urban Clim., 23:36–52, March 2018. ICUC9: The 9th International Conference on Urban Climate. doi:10.1016/j.uclim.2017.05.001.

Konarska et al. 2013

Konarska, Janina, Lindberg, Fredrik, Larsson, Annika, Thorsson, Sofia, and Holmer, Björn. Transmissivity of solar radiation through crowns of single urban trees—application for outdoor thermal comfort modelling. Theor Appl Climatol, 117(3-4):363–376, September 2013. doi:10.1007/s00704-013-1000-3.

Kotthaus et al. 2014

Kotthaus, Simone, Smith, Thomas E. L., Wooster, Martin J., and Grimmond, C. S. B. Derivation of an urban materials spectral library through emittance and reflectance spectroscopy. ISPRS J. Photogramm. Remote Sens., 94:194–212, Aug 2014. doi:10.1016/j.isprsjprs.2014.05.005.

Lindberg et al. 2013

Lindberg, F., Grimmond, C.S.B., Yogeswaran, N., Kotthaus, S., and Allen, L. Impact of city changes and weather on anthropogenic heat flux in Europe 1995–2015. Urban Clim., 4:1–15, July 2013. doi:10.1016/j.uclim.2013.03.002.

Lindberg and Grimmond 2011

Lindberg, Fredrik and Grimmond, C. S. B. The influence of vegetation and building morphology on shadow patterns and mean radiant temperatures in urban areas: Model development and evaluation. Theor Appl Climatol, 105(3-4):311–323, January 2011. doi:10.1007/s00704-010-0382-8.

Lindberg et al. 2008

Lindberg, Fredrik, Holmer, Björn, and Thorsson, Sofia. SOLWEIG 1.0 – modelling spatial variations of 3D radiant fluxes and mean radiant temperature in complex urban settings. Int J Biometeorol, 52(7):697–713, June 2008. doi:10.1007/s00484-008-0162-7.

Loridan and Grimmond 2012

Loridan, Thomas and Grimmond, C. S. B. Characterization of energy flux partitioning in urban environments: Links with surface seasonal properties. J. Appl. Meteorol. Clim., 51(2):219–241, February 2012. doi:10.1175/jamc-d-11-038.1.

Loridan et al. 2011

Loridan, Thomas, Grimmond, C. S. B., Offerle, Brian D., Young, Duick T., Smith, Thomas E. L., Järvi, Leena, and Lindberg, Fredrik. Local-scale urban meteorological parameterization scheme (LUMPS): Longwave radiation parameterization and seasonality-related developments. J. Appl. Meteorol. Clim., 50(1):185–202, January 2011. doi:10.1175/2010jamc2474.1.

Macdonald et al. 1998

Macdonald, R.W., Griffiths, R.F., and Hall, D.J. An improved method for the estimation of surface roughness of obstacle arrays. Atmos. Environ., 32(11):1857–1864, June 1998. doi:10.1016/s1352-2310(97)00403-2.

McCaughey 1985

McCaughey, J. H. Energy balance storage terms in a mature mixed forest at petawawa, Ontario ? a case study. Boundary-Layer Meteorol, 31(1):89–101, January 1985. doi:10.1007/bf00120036.

Meyn and Oke 2009

Meyn, Stephanie K. and Oke, T.R. Heat fluxes through roofs and their relevance to estimates of urban heat storage. Energ. Buildings, 41(7):745–752, July 2009. doi:10.1016/j.enbuild.2009.02.005.

NARITA et al. 1984

NARITA, Ken-ichi, SEKINE, Takeshi, and TOKUOKA, Toshikazu. Thermal properties of urban surface materials. Geogr. Rev. Jpn, Ser. A, Chirigaku Hyoron, 57(9):639–651, September 1984. doi:10.4157/grj1984a.57.9_639.

Novak 1981

Novak, Michael David. The moisture and thermal regimes of a bare soil in the lower Fraser Valley during spring. PhD thesis, University of British Columbia, 1981. doi:10.14288/1.0095282.

Nunez and Oke 1977

Nunez, M. and Oke, T. R. The energy balance of an urban canyon. J. Appl. Meteor., 16(1):11–19, January 1977. doi:10.1175/1520-0450(1977)016<0011:teboau>2.0.co;2.

Offerle et al. 2005

Offerle, B., Grimmond, C. S. B., and Fortuniak, K. Heat storage and anthropogenic heat flux in relation to the energy balance of a central European city centre. Int. J. Climatol., 25(10):1405–1419, August 2005. doi:10.1002/joc.1198.

Offerle et al. 2003

Offerle, B., Grimmond, C. S. B., and Oke, T. R. Parameterization of net all-wave radiation for urban areas. J. Appl. Meteor., 42(8):1157–1173, August 2003. doi:10.1175/1520-0450(2003)042<1157:ponarf>2.0.co;2.

Oke 2002

Oke, T. R. Boundary Layer Climates. Routledge, September 2002. ISBN 9781134951345. doi:10.4324/9780203407219.

Onomura et al. 2015

Onomura, S., Grimmond, C.S.B., Lindberg, F., Holmer, B., and Thorsson, S. Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme. Urban Clim., 11:1–23, March 2015. doi:10.1016/j.uclim.2014.11.001.

Reindl et al. 1990

Reindl, D.T., Beckman, W.A., and Duffie, J.A. Diffuse fraction correlations. Sol. Energy, 45(1):1–7, 1990. doi:10.1016/0038-092x(90)90060-p.

Ruimy et al. 1995

Ruimy, A., Jarvis, P.G., Baldocchi, D.D., and Saugier, B. CO2 fluxes over plant canopies and solar radiation: A review. In Advances in Ecological Research, pages 1–68. Elsevier, 1995. doi:10.1016/s0065-2504(08)60063-x.

Sailor and Lu 2004

Sailor, David J. and Lu, Lu. A top–down methodology for developing diurnal and seasonal anthropogenic heating profiles for urban areas. Atmos. Environ., 38(17):2737–2748, June 2004. doi:10.1016/j.atmosenv.2004.01.034.

Sailor and Vasireddy 2006

Sailor, David J. and Vasireddy, Chittaranjan. Correcting aggregate energy consumption data to account for variability in local weather. Environ. Modell. Softw., 21(5):733–738, May 2006. doi:10.1016/j.envsoft.2005.08.001.

Schmid 2000

Schmid, H. Measurements of CO2 and energy fluxes over a mixed hardwood forest in the mid-western united states. Agr. Forest Meteorol., 103(4):357–374, July 2000. doi:10.1016/s0168-1923(00)00140-4.

South et al. 1998

South, Catherine, Susan, C., Grimmond, B., and Wolfe, Charlotte P. Evapotranspiration rates from wetlands with different disturbance histories: Indiana dunes national lakeshore. Wetlands, 18(2):216–229, June 1998. doi:10.1007/bf03161657.

Sun et al. 2017

Sun, Ting, Wang, Zhi-Hua, Oechel, Walter C., and Grimmond, Sue. The analytical objective hysteresis model (AnOHM v1.0): Methodology to determine bulk storage heat flux coefficients. Geosci. Model Dev., 10(7):2875–2890, July 2017. doi:10.5194/gmd-10-2875-2017.

Taesler 1980

Taesler, Roger. Studies of the development and thermal structure of the urban boundary layer in uppsala. Part 1: Experimental program and Part 2: Data analysis and results. Rep. 61. Uppsala, Sweden : Uppsala Universitetet. Uppsala, Sweden : Uppsala Universitetet, 1980. ISBN 221015643.

Tang et al. 2021

Tang, Yihao, Sun, Ting, Luo, Zhiwen, Omidvar, Hamidreza, Theeuwes, Natalie, Xie, Xiaoxiong, Xiong, Jie, Yao, Runming, and Grimmond, Sue. Urban meteorological forcing data for building energy simulations. Building and Environment, 204:108088, October 2021. doi:10.1016/j.buildenv.2021.108088.

Theeuwes et al. 2019

Theeuwes, Natalie E., Ronda, Reinder J., Harman, Ian N., Christen, Andreas, and Grimmond, C. Sue B. Parametrizing horizontally-averaged wind and temperature profiles in the urban roughness sublayer. Boundary-Layer Meteorol, 173(3):321–348, September 2019. doi:10.1007/s10546-019-00472-1.

Van Ulden and Holtslag 1985

Van Ulden, A. P. and Holtslag, A. A. M. Estimation of atmospheric boundary layer parameters for diffusion applications. J. Climate Appl. Meteor., 24(11):1196–1207, November 1985. doi:10.1175/1520-0450(1985)024<1196:eoablp>2.0.co;2.

Voogt and Grimmond 2000

Voogt, J. A. and Grimmond, C. S. B. Modeling surface sensible heat flux using surface radiative temperatures in a simple urban area. J. Appl. Meteorol., 39(10):1679–1699, October 2000. doi:10.1175/1520-0450-39.10.1679.

Ward et al. 2016

Ward, H.C., Kotthaus, S., Järvi, L., and Grimmond, C.S.B. Surface urban energy and water balance scheme (SUEWS): Development and evaluation at two UK sites. Urban Clim., 18:1–32, December 2016. doi:10.1016/j.uclim.2016.05.001.

Yang et al. 2020

Yang, Bin, He, Yuhao, and Chen, Wei. A simple method for estimation of leaf dry matter content in fresh leaves using leaf scattering albedo. Global Ecol. Conserv., 23:e01201, Sep 2020. doi:10.1016/j.gecco.2020.e01201.

Yap 1973

Yap, David Hamilton. Sensible heat fluxes measured in and near Vancouver, B.C. PhD thesis, University of British Columbia, 1973. doi:10.14288/1.0101037.

Yoshida et al. 1990

Yoshida, Atsumasa, Tominaga, Kazuhide, and Watatani, Shigeru. Field measurements on energy balance of an urban canyon in the summer season. Energ. Buildings, 15(3-4):417–423, January 1990. doi:10.1016/0378-7788(90)90016-c.

Zheng et al. 2023

Zheng, Y., Havu, M., Liu, H., Cheng, X., Wen, Y., Lee, H. S., Ahongshangbam, J., and Järvi, L. Simulating heat and CO$_2$ fluxes in Beijing using SUEWS V2020b: sensitivity to vegetation phenology and maximum conductance. Geoscientific Model Development, 16(15):4551–4579, August 2023. doi:10.5194/gmd-16-4551-2023.