Skip to content

Pre-processing

This guide explains how to set up the input files of your simulation. The idea is that you already have a simulation set up, and now you want to modify some of the parameters of your simulation. If you do not have a simulation yet, have a look at the set-up section in our getting started guide.

The parameters of the simulation are set in the namoptions file of your experiment. Some parameter changes require the additional input files to be re-written, which will be done automatically by the pre-processing. The next section provides an overview of these parameters.

Pre-processing parameters

Some parameters used by uDALES are also used in the pre-processing. They are the following:

&DOMAIN

  • imax: number of cells in x-direction. Default: 64.
  • jtot: number of cells in y-direction. Default: 64.
  • kmax: number of cells in z-direction. Default: 96.
  • xsize: domain size in x-direction (metres).
  • ysize: domain size in y-direction (metres).

&WALLS

  • nblocks: number of blocks. The value is generated by the pre-processing routines, so if this parameter is omitted, write_inputs.sh (see below) will write it and its value. If it given, write_inputs.sh will overwrite the value.
  • nfcts: number of facets. The value is generated by the pre-processing routines, so if this parameter is omitted, write_inputs.sh (see below) will write it and its value. If it given, write_inputs.sh will overwrite the value.

&PHYSICS

  • luoutflowr: switch that determines whether u-velocity is corrected to get a fixed outflow rate Default: false.
  • lvoutflowr: switch that determines whether v-velocity is corrected to get a fixed outflow rate. Default: false.
  • luvolflowr: switch that determines whether u-velocity is corrected to get a fixed volume flow rate. Default: false.
  • lvvolflowr: switch that determines whether v-velocity is corrected to get a fixed volume flow rate. Default: false.
  • lcoriol: switch for coriolis force. Default: false.
  • lprofforc: switch for nudging flow to a profile. Default: false.

Note only one forcing should be specified, i.e. one of luoutflowr/lvoutflowr,luvolflowr/lvvolflowr, lprofforc, or lcoriol.

&ENERGYBALANCE

  • lEB: switch for energy balance. Default: false.

&CHEMISTRY

  • lchem: switch for chemistry.

&SCALARS

  • nsv: number of scalar variables. Default: 0. Note that nsv > 0 is not yet supported in the pre-processing.

&INPS

The parameters under the &INPS header are used only in the pre-processing.

  • zsize: size of domain in z direction (metres).
  • maxsize: maximum size of facets (metres or cells?). Default: 10 if using energy balance, infinity otherwise.
  • lzstretch: switch for stretched z grid. Default: false.
  • lstretchexp: switch for z grid stretched using exp function. Default: false.
  • lstretchtanh: switch for z grid stretched using tanh function. Default: false.
  • lstretch2tanh: switch for z grid stretched using 2tanh function. Default: false.
  • stretchconst: stretch constant. Default: 0.01.
  • u0: initial u-velocity (m/s). Also applied as geostrophic term where applicable. Default: 0.
  • v0: initial v-velocity (m/s). Also applied as geostrophic term where applicable. Default: 0.
  • dpdx: pressure gradient in x direction (Pa/m). Default: 0.
  • dpdy: pressure gradient in y direction (Pa/m). Default: 0.
  • thl0: temperature at z = 0. Default: 288.
  • facT: facet temperature, or if lEB = .true. then initial facet temperature. Default: 288.
  • qt0: specific humidity at z = 0. Default: 0.
  • lapse: lapse rate (K/m). Default: 0.
  • w_s: subsidence. Default: 0.
  • R: radiative forcing (W/m^2). Default: 0.
  • NOb: initial concentration of NO. Default: 0.
  • NO2b: initial concentration of NO2b. Default: 0.
  • O3b: initial concentration of O3b. Default: 0.

If using the energy balance, the following parameters can also be specified.

  • solaz: solar azimuth (degrees). Default: 135.
  • Z: solar zenith (degrees). Default: 28.4066.
  • I: direct solar radiation (W/m^2). Default: 184.8775.
  • Dsk: diffuse incoming radiation (W/m^2). Default: 418.8041.

The following parameters relate to generating blocks.inp. Only one of the following three methods should be used.

Generate blocks from a given file

  • lblocksfile: switch for generating blocks from a given file.
  • blocksfile: name of blocks file (must be specified if lblocksfile is used).
  • ltxtblocks: switch for generating blocks from a 2D ascii array
  • txtblocksfile: name of blocks file (must be specified if ltxtblocks is used).

Generate blocks from LIDAR data

  • llidar: switch for generating blocks from LIDAR data. Default: false.
  • sourcename: name of image file.
  • dxinp: resolution of image in x direction (metres per pixel). Default: 1.
  • dyinp: resolution of image in y direction (metres per pixel). Default: 1.
  • centeri: center of area of interest in image (horizontal pixel). Default: 0.
  • centerj: center of area of interest in image (vertical pixel). Default: 0.
  • maxh: maximum height of buildings in image (metres). Default: 0.
  • pad: padding (metres). Default: 5.
  • smallarea: objects smaller than this area (metres) will be deleted. Default: round(150 / (dx * dy)), where dx = xsize / imax and dy = ysize / jtot.

Generate simple block geometry

  • lflat: switch for no blocks. Default: false.
  • lcube: switch for linear cubes. Default: false.
  • lstaggered: switch for staggered cubes. Default: false.
  • lcanyons: switch for inifite canyons. Default: false.
  • lfloors: switch for just floor facets. Default: false.
  • blockheight: height of blocks (cells). Default: 16.
  • blockwidth: width of blocks (cells). Default: 16.
  • canyonwidth: width of canyon (cells). Default: 16.

Run

The write_inputs.sh shell script is a wrapper around the MATALB pre-processing functions of preprocessing.m. For more info about the functions see Developer's guide. The script requires several variables to be set up. Below is an example setup for copying and pasting. You can also specify these parameters in a config.sh file within the experiment directory, which is then read by the scripts.

# We assume you are running the following commands from your
# top-level project directory.

export DA_TOOLSDIR=$(pwd)/u-dales/tools # Directory of the scripts
export DA_EXPDIR=$(pwd)/experiments #  The top-level directory of the simulation setups

Then, to start the pre-processing, run:

# We assume you are running the following commands from your
# top-level project directory.

# General syntax: write_inputs.sh exp_id
./u-dales/tools/write_inputs.sh 009

Replace 009 with the number of your simulation.

Developer's guide

The u-dales/tools/preprocessing.m matlab class contains the functionality for preprocessing. The constructor reads the parameters in namoptions and stores them as member variables, and defines default variables for those not specified. These are then used in the member functions. In these member functions, additional data structures are also stored as member variables, including those used repeatedly and those eventually written to files, so that one can easily view and manipulate them using the matlab IDE.

The u-dales/tools/write_inputs.m matlab script calls member functions of preprocessing.m in order to write the necessary input files for uDALES. It is intended to be as short and readable as possible, with the goal being that a developer can edit for a particular purpose, perhaps by calling a member function they have added to preprocessing.m. It will work simply as a normal script using the matlab IDE, but when doing this, ensure that DA_EXPDIR = <top level directory>/experiments/ and DA_TOOLSDIR = <top level directory>/u-dales/tools/ are defined.

The u-dales/tools/write_inputs.sh shell script acts as a wrapper around write_inputs.m. Before running the matlab script, it will run the shell script config.sh located in the experiment directory, which defines environmental variables DA_EXPDIR and DA_TOOLSDIR. After running the script, it will also write the correct number of blocks and facets to namoptions. It is intended to be run from the top level project directory.

# We assume you are running the following commands from your
# top-level project directory.

# General syntax: write_inputs.sh exp_id
./u-dales/tools/write_inputs.sh 009

Input files

uDALES requires a number of input files, all suffixed by the experiment number, which is omitted in the following documentation. The namoptions.inp file contains a list of parameters for uDALES and the pre-processing routines, and the pre-processing is intended to run using solely this file (with some exceptions). The input files are:

  • xgrid.inp: list of x grid values
  • zgrid.inp: list of z grid values.
  • prof.inp: initial profiles of flow variables (described in DALES documentation).
  • lscale.inp: large-scale forcings (described in DALES documentation).
  • blocks.inp: block position and corresponding facets (described below).
  • facets.inp: facet orientation and corresponding block (described below).
  • Tfacinit.inp: list of initial facet temperatures.
  • walltypes.inp: a description of the properties of different types of facet (described below). This is copied to the experiment directory automatically.

If using scalars, scalar.inp is also required to specifiy the initial scalar profiles. When using the energy balance, the following additional files are required:

  • facetarea.inp: list of the areas of facets.
  • vf.nc.inp: view factors of facets (stored as a netcdf file).
  • svf.inp: list of the sky view factors of facets.
  • netsw.inp: list of net shortwave radiation on facets.

Structure of blocks.inp

Each row describes a block, with the first 6 columns giving the lower (l) and upper (u) limit in each direction (i,j,k), in the order: il, iu, jl, ju, kl, ku. The next 5 columns give the facets that make up the faces of the block, in the order: top, west, east, north, south. (Note east is assumed to be aligned with the i-direction).

Structure of facets.inp

Each row describes a facet, with columns giving the orientation, wall type id, block id, and building id.

Structure of walltypes.inp

Each row describes a wall type, with the first 6 columns being: wall type id, a boolean for whether it is a 'green' facet or not, momentum roughness length, heat roughness length, albedo, and emissivity. Assuming that each facet is composed of 3 layers, the next 3 columns give the thickness of each, the next 3 give the volumetric heat capacity, the next 3 give the heat conductivity, and the final 4 give the thermal diffusivity at each interface between the layers.

For examples, please refer to the example simulations.

Visualising geometries

There are a number of functions in the preprocessing class that can be called from the Matlab editor in order to visualise the geometry. Assuming the instance of the preprocessing class is named r, plot_bl(r) plots the buildings, plot_blocks(r) plots the buildings and the roads, and plot_facets(r) plots all the facets.