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
Grid mapping
Grid mapping is defined via variable crs which is defined as:
| Variable | Type | Attributes | Remarks |
|---|---|---|---|
| crs | NC_INT | See list below | Attributes of crs define the grid mapping. It has no dimensions (single integer) and its value does not need to be set. |
The following list defines the attributes of the grid-mapping variable crs. Given values are an example of how to define "EPSG:25833" (ETRS89 / UTM zone 33N).
| Attribute | Type | Value |
|---|---|---|
| long_name | NC_CHAR | "coordinate reference system" |
| grid_mapping_name | NC_CHAR | "transverse_mercator" |
| semi_major_axis | NC_FLOAT | 6378137.0 |
| inverse_flattening | NC_FLOAT | 298.257222101 |
| longitude_of_prime_meridian | NC_FLOAT | 0.0 |
| longitude_of_central_meridian | NC_FLOAT | 15.0 |
| latitide_of_projection_origin | NC_FLOAT | 0.0 |
| scale_factor_at_central_meridian | NC_FLOAT | 0.9996 |
| false_easting | NC_FLOAT | 500000.0 |
| false_northing | NC_FLOAT | 0.0 |
| units | NC_CHAR | "m" |
| epsg_code | NC_CHAR | "EPSG:25833" |
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 x y z time" | 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 | "crs" | 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
The following list provides an overview of all dimension variables that can be used in a static driver file. All dimensions should start with 0, except for ns, which has to start with 1.
| Dimension | Type | Value | Description |
|---|---|---|---|
| nalbedo_pars | NC_INT | 8 | number of elements in albedo_pars |
| nbuilding_surface_pars | NC_INT | 28 | number of elements in building_surface_pars |
| npavement_pars | NC_INT | 4 | number of elements in pavement_pars |
| npavement_subsurface_pars | NC_INT | 2 | number of elements in pavement_subsurface_pars |
| ns | NC_INT | - | number of surface elements used in building_surface_pars. |
| nsoil_pars | NC_INT | 8 | number of elements in soil_pars |
| nsurface_fraction | NC_INT | 3 | number of elements in surface_fraction |
| nvegetation_pars | NC_INT | 12 | number of elements in vegetation_pars |
| nwater_pars | NC_INT | 7 | number of elements in water_pars |
List of coordinate variables
The following list provides an overview of all coordinate variables that can be used in a static driver file.
| Variable | Type | Attributes | Remarks |
|---|---|---|---|
| azimuth | NC_FLOAT | long_name="azimuth angle" units="degrees" | Azimuth angle of surface element (ns) orientation: up- and downward-facing (-9999), northward-facing (0), eastward-facing (90), southward-facing (180), westward-facing (270) |
| azimuth_uv | NC_FLOAT | long_name="azimuth angle for uv exposure" units="degrees" | Azimuth angle for obstruction_uv input |
| Es_UTM | NC_FLOAT | long_name="projection x coordinate" units="m" | Projection of x-coordinate for surface element (ns) |
| lats | NC_FLOAT | long_name="latitude" units="degrees_north" | Latitude of surface element (ns) |
| lons | NC_FLOAT | long_name="longitude" units="degrees_east" | Longitude of surface element (ns) |
| Ns_UTM | NC_FLOAT | long_name="projection y coordinate" units="m" | Projection of y-coordinate for surface element (ns) |
| x | NC_FLOAT | axis="X" long_name="distance to origin in x-direction units="m" | |
| xs | NC_FLOAT | axis="X" long_name="distance to origin in x-direction units="m" | Distance of origin to building surface element (ns) in x-direction |
| y | NC_FLOAT | axis="Y" long_name="distance to origin in y-direction units="m" | |
| ys | NC_FLOAT | axis="Y" long_name="distance to origin in y-direction units="m" | Distance of origin to building surface element (ns) in y-direction |
| z | NC_FLOAT | axis="Z" long_name="height above origin" positive="up" standard_name="height_above_mean_sea_level" units="m" | |
| zs | NC_FLOAT | axis="Z" long_name="height above origin" positive="up" standard_name="height_above_mean_sea_level" units="m" | Height above origin of building surface element (ns) |
| zenith | NC_FLOAT | long_name="zenith angle" units="degrees" | Zenith angle of surface element orientation: upward (0), downward (180), vertical surface (90) |
| zenith_uv | NC_FLOAT | long_name="zenith angle for uv exposure" units="degrees" | Zenith angle for obstruction_uv input |
| zlad | NC_FLOAT | axis="Z" long_name="height above ground" positive="up" units="m" | z-location in m above the ground for mapping vegetation, used in lad, bad, and tree_id. Note, zlad must start at zero height. |
| zsoil | NC_FLOAT | axis="Z" long_name="depth in the soil" positive="down" units="m" | z-location in m within the soil (positive downward), used in soil_type |
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. There is no specification or limitation for the ID numbers, except that each building must have a unique number which need to fit into the representable area of a 32-bit integer variable (i.e. -2147483647 to +2147483647). |
| 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. |
| shf(y,x) | NC_FLOAT | _FillValue=-9999.f(*) coordinates grid_mapping long_name="surface sensible heat flux" res_orig source units="m" | Time-constant surface sensible heat flux. Note that input of shf is only useful for default-type surfaces, i.e., for simulations without land surface model and urban surface model. |
| qsws(y,x) | NC_FLOAT | _FillValue=-9999.f(*) coordinates grid_mapping long_name="surface latent heat flux" res_orig source units="m" | Time-constant surface latent heat flux. Note that input of qsws is only useful for default-type surfaces, i.e., for simulations without land surface model and urban surface model. |
| ssws(y,x) | NC_FLOAT | _FillValue=-9999.f(*) coordinates grid_mapping long_name="surface passive scalar flux" res_orig source units="kg m /( kg s )" | Time-constant surface passive scalar flux. |
| z0(y,x) | NC_FLOAT | _FillValue=-9999.f(*) coordinates grid_mapping long_name="roughness length for momentum" res_orig source units="m" | Roughness length for momentum. Note that input of z0 is only useful for default-type surfaces, i.e., for simulations without land surface model and urban surface model. |
(*) are mandatory attributes
Main 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.
| Input variable | Type | Attributes | Explanation / Remarks | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
albedo_type(y,x) | NC_BYTE |
_FillValue=-127b(*) | 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. For details, see albedo_type. Please note, setting of albedo_type = 0 (user defined) in the static file is not allowed. To specify albedo values further, please set respective albedo_pars in the static input file. Albedo values will be updated accordingly. | ||||||||||||||||||||||||||||||||||||||||
building_type(y,x) | NC_BYTE |
_FillValue=-127b(*) | 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.
For details, see building_type. Please note, setting of building_type = 0 (user defined) in the static file is not allowed. To specify building parameters further, please set respective building_pars in the static input file. Building parameters will be updated accordingly. The building parameters defined in a building_pars layer within the static file will supercede the predefined values set when using building_type values 1-7. | ||||||||||||||||||||||||||||||||||||||||
pavement_type(y,x) | NC_BYTE |
_FillValue=-127b(*) | 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. Please note, setting of pavement_type = 0 (user defined) in the static file is not allowed. To specify pavement parameters further, please set respective pavement_pars in the static input file. Pavement parameters will be updated accordingly. | ||||||||||||||||||||||||||||||||||||||||
soil_type((zsoil,)y,x) | NC_BYTE |
_FillValue=-127b(*) | Bulk classification of soil in terms of porosity. soil_type overwrites the homogeneously prescribed setting via the namelist parameter soil_type. A soil type is need at all locations where either a vegetation_type or a pavement_type is set. 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. For details, see soil_type. Please note, setting of soil_type = 0 (user defined) in the static file is not allowed. To specify soil parameters further, please set respective soil_pars in the static input file. Soil parameters will be updated accordingly. | ||||||||||||||||||||||||||||||||||||||||
street_crossing(y,x) | NC_BYTE |
_FillValue=-127b(*) | Localization of street crossings that can be used by pedestrians (traffic lights, zebra crossings, crosswalks). The only valid number is 1b. street_crossing will be required for application of the multi-agent system in near future. | ||||||||||||||||||||||||||||||||||||||||
street_type(y,x) | NC_BYTE |
_FillValue=-127b(*) | Classification of streets, closely following the Open Street Map classification. street_type is required for application of the parameterized traffic emissions (see emission mode LOD 0 here) and for the multi-agent system.
| ||||||||||||||||||||||||||||||||||||||||
surface_fraction(nsurface_fraction,y,x) | NC_FLOAT |
_FillValue=-127b(*) | 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_type(y,x) | NC_BYTE |
_FillValue=-127b(*) | Bulk classification of non-resolved (i.e. flat) 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. For details, see vegetation_type. Please note, setting of vegetation_type = 0 (user defined) in the static file is not allowed. To specify vegetation parameters further, please set respective vegetation_pars in the static input file. Vegetation parameters will be updated accordingly. | ||||||||||||||||||||||||||||||||||||||||
water_type(y,x) | NC_BYTE |
_FillValue=-127b(*) | Bulk classification of water bodies. water_type overwrites the homogeneously prescribed setting via the namelist parameter water_type. For details, see water_type. Please note, setting of water_type = 0 (user defined) in the static file is not allowed. To specify water parameters further, please set respective water_pars in the static input file. Water parameters will be updated accordingly. |
Pixel-based surface and sub-surface parameters
While the *_type classification will set all required surface and sub-surface parameters automatically, the *_pars variables listed below allow for overwriting single or multiple parameters at single or multiple pixel locations (y,x). The use of these variables is optional.
| Variable | Type | Attributes | Explanation / Remarks |
|---|---|---|---|
| albedo_pars(nalbedo_pars,y,x) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="albedo parameters" res_orig source | Pixel-specific settings for surface albedo. For details, see albedo_pars. |
| building_pars(nbuilding_pars,y,x) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="building parameters" res_orig source | Pixel-specific settings for buildings. For details, see building_pars. |
| pavement_pars(npavement_pars,y,x) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="pavement surface parameters" res_orig source | Pixel-specific settings for pavement surfaces. For details, see pavement_pars. |
| pavement_subsurface_pars(npavement_subsurface_pars,zsoil,y,x) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="pavement subsurface parameters" res_orig source | Pixel-specific settings for pavement sub-surface properties. For details, see pavement_subsurface_pars. |
| vegetation_pars(nvegetation_pars,y,x) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="vegetation parameters" res_orig source | Pixel-specific settings for unresolved vegetation. For details, see vegetation_pars. |
| water_pars(nwater_pars,y,x) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="water parameters" res_orig source | Pixel-specific settings for water bodies. For details, see water_pars. |
(*) are mandatory attributes
Vegetation parameters
The vegetation_type will set bulk properties for unresolved vegetation, i.e., vegetation that is considered to be flat. For high vegetation such as trees, the canopy model can be used to prescribe resolved vegetation, i.e., vegetation that is represented by multiple grid volumes. The following list gives an overview of the vegetation variables that can be set to represent three-dimensional vegetation.
| Variable | Type | Attributes | Explanation / Remarks |
|---|---|---|---|
| lad(zlad,y,x) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="leaf area density" res_orig source units="m2 m-3" | Vegetation resolved by the canopy model in terms of a three-dimensional leaf area density (LAD). The dimension zlad can be limited to the maximum canopy height. |
| bad(zlad,y,x) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="basal area density" res_orig source units="m2 m-3" | Basal area density (BAD) in m² per m³ grid volume, representing trunk an branches within the respective grid volume. The dimension zlad can be limited to the maximum canopy height. |
| root_area_dens_r(zsoil,y,x) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="root area density of resolved vegetation" res_orig source units="1" | Root area of resolved vegetation, provided via an LAD field, in the soil. |
| root_area_dens_s(zsoil,y,x) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="root area density of parameterized vegetation" res_orig source units="1" | Root area of parameterized (i.e. flat) vegetation, treated by the land surface model. |
| tree_id(y,x) | NC_INT | _FillValue=-9999 (*) coordinates grid_mapping long_name="tree id" res_orig source units="1" | ID of the tree which belongs to the specific grid volume. |
| tree_type(zlad,y,x) | NC_INT | _FillValue=-9999 (*) coordinates grid_mapping long_name="tree type" res_orig source units="1" | Tree type for each grid volume containing a leaf area density value. Positive values refer to the tree types defined in the tree type database (see here) and which is applied for single trees where the species is known. In case the leaf area density was calculated by the patch generator, the species is unknown. In this case, tree type contains the value of vegetation_type (see here) that was used to create the patch. In order to distinguish between the two, the latter are output using a minus sign. |
Surface-based building parameters
While the *_pars variables allow only to overwrite settings for buildings at location (y,x), the surface-based building parameters allow for overwriting properties of individual surface elements. The use of these variables is optional.
| Variable | Type | Attributes | Explanation / Remarks |
|---|---|---|---|
| building_surface_pars(nbuilding_surface_pars,ns) | NC_FLOAT | _FillValue=-9999.f (*) coordinates grid_mapping long_name="building surface parameters" res_orig source | Settings for individual building surfaces. For details, see building_surface_pars. |
