Static input file

The static input file encompasses topography information as well as all necessary information file to initialize all land- and urban-type surfaces in the model, such as heat capacities, roughness, albedo, emissivity, etc.. The initialization procedure for the surfaces follows a multi-step approach, depending on the given level of detail of each variable as provided in the static input file. In a first step, surfaces are initialized horizontally homogeneous with a bulk classification for each type (e.g. vegetation or soil), either set by a default value or set by a namelist-provided value, while the bulk classification provides standard values for a variety of parameters. In a second step, surfaces are initialized individually by providing the bulk classification at each grid point individually. In case more detailed information is available, all or even single parameters can be initialized individually at each grid point.

The provided input data is used to classify each surface element according to its treatment, i.e. default-, natural- or urban-type, in order to treat each surface element accordingly. In case no land-surface or urban-surface scheme is applied, all surfaces are classified as default-type. If a surface element has vegetation, pavement or water, it will be classified as natural-type and is treated by the land-surface scheme, while building surfaces will be treated by the urban-surface scheme.

Global attributes

Attribute	Type	Explanation / Remarks
acronym	NC_CHAR	Abbreviation of institution (max. 12 characters)
author	NC_CHAR	first name, last name, email address
campaign	NC_CHAR	User-defined text, max. 12 characters
contact_person	NC_CHAR	first name, last name, email address
creation_time	NC_CHAR	File creation date (UTC), format: YYYY-MM-DD hh:mm:ss +00
comment	NC_CHAR	User-defined text
Conventions(*)	NC_CHAR	Must be set to "CF-1.7".
data_content	NC_CHAR	User-defined text, max. 16 characters
dependencies	NC_CHAR	User-defined text
history	NC_CHAR	Information of data processing, separation by comma, e.g., "2016-04-22 11:45: updated vegetation"
keywords	NC_CHAR	User-defined list, separated by comma
license	NC_CHAR	User-defined text
location	NC_CHAR	User-defined text
origin_lat(*)	NC_FLOAT	Geographical latitude in degrees north. This attribute defines the south boundary of the model domain and overwrites the namelist parameter latitude, which is used e.g. for the Coriolis parameters as well as for the radiation. Please note, in case of a nested run, values of latitude will be synchronized internally to the respective value of the root parent domain.
origin_lon(*)	NC_FLOAT	Geographical longitude in degrees east. This attribute defines the left boundary of the model domain and overwrites the namelist parameter longitude, which is used e.g. for the radiation. Please note, in case of a nested run, values of longitude will be synchronized internally to the respective value of the root parent domain.
origin_time(*?)	NC_CHAR	Reference point in time (UTC) YYYY­-MM­-DD hh:mm:ss +00.
origin_x(*)	NC_FLOAT	Reference x-location in m (UTM) of left model boundary.
origin_y(*)	NC_FLOAT	Reference y-location in m (UTM) of lower model boundary.
origin_z(*)	NC_FLOAT	Reference height in m above sea level after DHHN2016.
palm_version	NC_FLOAT	e.g. "5.0" for compatibility checks
references	NC_CHAR	User-defined text
rotation_angle(*?)	NC_FLOAT	Clockwise angle of rotation in degrees between North positive y axis and the y axis in the data, e.g. 0.0. This value overwrites the namelist parameter rotation_angle, which is used e.g. to calculate the Coriolis force.
site	NC_CHAR	User-defined text
source	NC_CHAR	User-defined text
title	NC_CHAR	Short description, e.g., "PALM input file for scenario 1b"
version	NC_INT	e.g. "1"

(*) are mandatory attributes

List of attributes

The following list gives an overview of attributes that can be assigned to variables in a static driver file.

Attribute	Type	Value	Description
_FillValue	Variable-specific	Variable-specific	Fill value for missing data
coordinates	NC_CHAR	"E_UTM N_UTM lon lat" (?)	Coordinate system
flag_meanings	NC_CHAR	Variable-specific	Explanation of the meaning of 0b and 1b for NC_BYTE variables
flag_values	NC_BYTE	0b, 1b	Explanation of the meaning of 0b and 1b for NC_BYTE variables
grid_mapping	NC_CHAR	"crsUTM: E_UTM N_UTM crsETRS: lon lat" (?)	Grid mapping
lod	NC_INT	Variable-specific	Level of detail used for some variables
long_name	NC_CHAR	Variable-specific	Variable long name
res_orig	NC_CHAR	Variable-specific	Resolution of the original data
source	NC_CHAR	Variable-specific	Data source
units	NC_CHAR	Variable-specific	Units of the variable
valid_range	NC_BYTE	0b, 1b	Valid range of values

List of dimensions:

Topography set-up

In order to prescribe topography from the static input file, topography = 'read_from_file' is required.

Input variable	Type	Attributes	Explanation / Remarks
building_id(y,x)	NC_INT	_FillValue=-9999(*) coordinates grid_mapping long_name="building_id_number" res_orig source units="1"	The building ID is used to identify single building envelopes which are composed of a number of grid volumes, and which is used for correct mapping of buildings on top of the underlying terrain, as well as for the indoor_model. Please note, building_id must not contain any _FillValue at grid points where buildings are is defined via building_2d or building_3d.
buildings_2d(y,x)	NC_FLOAT	_FillValue=-9999.f(*) coordinates grid_mapping lod=1 long_name="building_height" res_orig source units="m"	Two-dimensional building height in m relative to the underlying terrain. No holes or overhanging structures are possible. buildings_2d will be mounted on top of the maximum local terrain height occupied by the respective building. Please note, buildings_2d will not be used if buildings_3d is present on file. If buildings_2d is used building_id is required.
buildings_3d(z,y,x)	NC_BYTE	_FillValue=-127b(*) coordinates flag_meanings="no building, building" flag_values=0b, 1b grid_mapping long_name="building_flag" res_orig source units="1" valid_range=0b, 1b	Three-dimensional building topology relative to the underlying terrain. buildings_3d will be mapped on top of the maximum local terrain height occupied by the respective building. Note, buildings_3d does not need to be prescribed beyond the top level of the highest buildings, i.e. z dimension can me minimized accordingly. If buildings_3d is prescribed, building_id is required.
obstruction_uv(azimuth_uv,zenith_uv,y,x)	NC_BYTE	_FillValue=-127b(*) coordinates flag_meanings="no obstruction, obstruction" flag_values=0b, 1b grid_mapping long_name="obstruction" res_orig source units="1" valid_range=0b, 1b	Obstruction of the sky at a pixel location (y,x). This field is needed only if the UV exposure model is used.
zt(y,x)	NC_FLOAT	_FillValue=-9999.f(*) coordinates grid_mapping long_name="terrain_height" res_orig source units="m"	Terrain height in m relative to origin_z. If not provided, the relative terrain height will be set to 0 m all over the model domain. Please note, zt must not contain any _FillValues.

(*) are mandatory attributes

Surface classification

For a proper classification of natural land and water surfaces, pavement_type, soil_type, vegetation_type and water_type are required, which define bulk parameters for albedo, soil, root distribution, leaf-area density, etc. To enable initialization of the land-surface model with input-file-provided variables, the namelist parameter surface_type needs to be set to 'netcdf'. In case more than one of the surface types (vegetation, pavement, water) is given at an (x,y) location, the relative fraction of each of the types must be provided by surface_fraction.

Further, if the urban-surface model is applied, also building_type is required, which defines bulk parameters to run the urban-surface model. Please note, for the sake of consistency, at least one of the variables pavement_type, vegetation_type, water_type or building_type needs to be defined at each (y,x) location if the land- and urban-surface model is applied.

If only the land-surface model is applied but no urban-surface model, one of pavement_type, vegetation_type or water_type needs to be defined at each (y,x) location.

Further, in case data is taken from the static input file, both, the land- and urban-surface model need to be either switched on or off. Applying only one of the energy-balance models is not sufficient and will lead to a controlled termination.

Surface variables:

Input variable	Type	Attributes	Explanation / Remarks
building_type(y,x)	NC_BYTE	_FillValue=-127b(*) coordinates grid_mapping long_name="building type classification" res_orig source units="1"	Building type used to select bulk parameters. building_type is required if the urban-surface model or the indoor_model are applied. Please note, building_type must not contain any _FillValue at grid points where buildings_2d/buildings_3d is defined. building_type Description (use, age) 0 User_defined according to building_pars 1 Residential, < 1950 2 Residential, 1950 - 2000 3 Residential, > 2000 4 Office, < 1950 5 Office, 1950 - 2000 6 Office, > 2000

Input variable	Type	LOD	Explanation / Remarks
albedo_pars (nalbedo_pars,y,x)	NC_FLOAT	none	Spectral and broadband albedo for natural and urban surfaces for (y,x)-locations. When albedo_type = 0, all parameters must be set. Otherwise, single parameters for a given albedo_type can be overwritten, while the remaining parameters must be set to _FillValue.
albedo_type(y,x)	NC_BYTE	none	Optional classification of albedo. Default values for albedo_type are already set in the bulk parametrization of building_type, pavement_type, vegetation_type, water_type, but will be overwritten in case albedo_type is defined. The value of albedo_type will also overwrite the prescribed values in vegetation_pars, water_pars, or pavement_pars. An overview of the different albedo types can be found here​.
building_pars (nbuilding_pars,y,x)	NC_FLOAT	none	Parameters for the building parameterization. When building_type = 0, all parameters must be set. Otherwise, single parameters for a given building_type can be overwritten, while the remaining parameters must be set to _FillValue. building_pars becomes only effective if the urban-surface model or the indoor_model are applied. Building parameters can be distinguished between ground-floor and upper level. For more information, please see here​.
building_surface_pars (nbuilding_surface_pars,s, y,x)	NC_FLOAT	none	Detailed information for specific building surfaces. This variable can contain data for the entire domain or for selected areas where detailed data is available. Setting of building_surface_pars will replace parameter settings made by building_type and building_pars. building_surface_pars becomes only effective if the urban-surface model is applied. For more information, please see here​. Please note: this input variable is currently not implemented.
building_type(y,x)	NC_BYTE	none
pavement_pars (npavement_pars,y,x)	NC_FLOAT	none	Parameters required for the bulk pavement parameterization in the land surface scheme. When pavement_type = 0, all parameters must be set. Otherwise, single parameters for a given pavement_type can be overwritten, while the remaining parameters must be set to _FillValue.
pavement_subsurface_pars (npavement_subsurface_pars, zsoil,y,x)	NC_FLOAT	none	Parameters required for the bulk pavement parameterization. For all zsoil levels where pavement_subsurface_pars is not missing, the settings of the soil model are overwritten, i.e. thermal conductivity and heat capacities are set, and the layers are impermeable for water. When pavement_type = 0, all parameters must be set.
pavement_type(y,x)	NC_BYTE	none	Bulk classification of pavements on soil. At locations where pavement_type is defined, soil_type must not contain any _FillValues. pavement_type overwrites the homogeneously prescribed setting via the namelist parameter pavement_type. An overview of the different pavement types can be found here​.
street_type(y,x)	NC_BYTE	none	Classifcation of street type derived from Open Street Map. street_type is required for application of the parameterized traffic emissions (see emission mode LOD 0 here) and for the multi-agent system. An overview of the different street types can be found here​.
soil_pars (nsoil_pars,(zsoil),y,x)	NC_FLOAT	1, 2	Parameters for soil parametrization. When soil_type = 0, all parameters must be set. Otherwise, single parameters for a given soil_type can be overwritten, while the remaining parameters must be set to _FillValue. In case lod = 1, prescribed parameters are vertically uniform, while in case lod = 2 parameters can be set for each layer individually. An overview of the different soil parameters can be found here​.
soil_type((zsoil),y,x)	NC_BYTE	1, 2	Bulk classification of soil in terms of porosity. soil_type overwrites the homogeneously prescribed setting via the namelist parameter soil_type. In case lod = 1, a 2-dimensional vertically uniform soil texture is prescribed, while in case lod = 2 the 3-dimensional soil_type is set for each layer individually. An overview of the different soil types can be found here​.
surface_fraction (nsurface_fraction,y,x)	NC_FLOAT	none	Relative fraction of the respective surface type given via vegetation_type (nsurface_fraction = 0), pavement_type (nsurface_fraction = 1) and water_type (nsurface_fraction = 2). The sum over all relative fractions must be equal to one for each location. This parameter is only needed at locations (y,x) where more than one surface type (vegetation, pavement, water) is defined. Moreover, if more than one surface type is defined at a location, the relative fractions of the respective surface types must not be 0. Also, if surface_fraction is given for one of the above mentioned surface types, this type need to be defined at this location.
vegetation_pars (nvegetation_pars,y,x)	NC_FLOAT	none	Parameters for the bulk parametrization of non-resolved vegetation in the land-surface model for each (y,x)-location. All/single parameters of vegetation_pars for a given vegetation_type can be overwritten for given (y,x)-location. If only single parameters shall be overwritten, all other parameters must be set to _FillValue. Please note, if vegetation_type = 0, all parameters must be set. An overview of the different vegetation parameters can be found here​.
vegetation_type(y,x)	NC_BYTE	none	Bulk classification of non-resolved vegetation surfaces at natural land surface types. At locations where vegetation_type is defined, soil_type must not contain any _FillValues. vegetation_type overwrites the homogeneously prescribed setting via the namelist parameter vegetation_type. An overview of the different vegetation types can be found here​.
water_pars (nalbedo_pars,y,x)	NC_FLOAT	none	Parameters used for the parameterization of water surfaces. When water_type = 0, all parameters must be set. Otherwise, single parameters for a given water_type can be overwritten, while the remaining parameters must be set to _FillValue.
water_type(y,x)	NC_BYTE	none	Bulk classification of water bodies. water_type overwrites the homogeneously prescribed setting via the namelist parameter water_type. An overview of the different water types can be found here​.

Resolved plant canopy:

In order to consider resolved plant canopy, the plant-canopy model need to be switched on and setting of canopy_mode = 'read_from_file_3d' is required.

Input variable	Type	LOD	Explanation / Remarks
lad (zlad,y,x)	NC_FLOAT	none	Vegetation resolved by the plant-canopy model in terms of a three­ dimensional leaf area density (LAD). Please note, plant canopy is prescribed relative to the underlying topography and will be mounted on top of the terrain. A preprocessor tool is available to convert arbitrary vegetation information to an LAD field. If lad is set, all settings of LAD-related parameters made in the namelist &plant_canopy_parameters will be ignored. Please note, unresolved vegetation is already treated via the land-surface model considered by vegetation_type. Please check for possible double counting of similar vegetation in case vegetation_type and lad is set at (y,x)-location.
bad (zlad,y,x)	NC_FLOAT	none	Basal area in m2 (i.e. trunk area) per grid volume. A preprocessor tool is available to convert arbritrary vegetation information to an basal area density field. The dimension of the field must be equal to that of the leaf area density. Please note, basal area is prescribed relative to the underlying topography.
root_area_dens_r (zsoil,y,x)	NC_FLOAT	none	Root area of the resolved vegetation in the soil.
root_area_dens_s (zsoil,y,x)	NC_FLOAT	none	Root area of the parameterized vegetation in the soil that is set via vegetation_type. When vegetation_type = 0, the root_area_density_s must be set.

Example static driver file:

soon.