palm_csd supports the generation of a root domain and an arbitrary number of nested domains. It checks for sufficient space at the borders of the domains to the respective parent domain and for any overlap between the domains. If domains overlap, only one-way nesting is allowed. All domains share one target coordinate system and one rotation angle (Fig. ). The latter is the angle between the projected coordinate system's north axis NC and the domain's north axis ND. The input data, when in a georeferenced format as described below, will be automatically reprojected and the rotation angle will be applied. This allows datasets with varying input projections to be used without manual conversion, thereby reducing preprocessing and ensuring a consistent final projection. Please refer to domains_input.md in the palm_csd package or the corresponding section in the online documentation for all technical details.

The position of the domain is set by the coordinates of the lower-left corner of the domain, either in the longitude/latitude system WGS84 or in the target coordinate system. For nested domains, palm_csd will ensure that the nest aligns with its parent by slightly adjusting the lower-left corner coordinates. It will also calculate the distance to the lower-left corner of the root parent domain, which is needed for the set-up of nesting in PALM. Alternatively, this distance can be set directly, without specifying the lower-left corner coordinates of the nest.

palm_csd supports a variety of input file formats, including 2D raster data and vector data. The input files can be in georeferenced formats such as GeoTIFF for rasters or ESRI Shapefiles for vector data. The resampling algorithm can be chosen for the downscaling and upscaling of the input data when reprojecting or changing the grid. In order to preserve the values of categorical data, only nearest-neighbour and mode-resampling are allowed. For all other data types, all algorithms supported by the employed Python GIS package rasterio (https://rasterio.readthedocs.io/en/latest/api/rasterio.enums.html#rasterio.enums.Resampling, last access: 23 June 2026) can be selected. Note that the different methods handle missing values differently. While nearest-neighbour resampling produces a missing value when the centre of the target pixel is closest to a missing value in the source data, the other methods calculate values as soon as a part of the target pixel is covered by a non-missing pixel in the source data. In order to ensure consistency between the different data types, the missing values of nearest-neighbour resampling are applied to all data types.

For palm_csd, each building pixel is defined by a building height, a building type and a unique building identifier (building ID), which is used to associate all pixels belonging to the same building. Please refer to buildings.md in the palm_csd package or the corresponding section in the online documentation for all technical details.

If the building input is given as a vector polygon file, at least the building height column needs to be specified. All polygons with a missing building height are ignored. Optionally, the building type and building ID can be specified. If the building type is not given, it is set to residential_1951_2000 with building surface parameters representing residential buildings built between 1951 and 2000. If the building ID is not given, it is automatically generated with a different value for each polygon.

If the building input is given as raster files, both the building height and the building ID need to be specified, as palm_csd cannot identify separate buildings from the raster data. The building type can be specified as well, but if it is not given, it is set to residential_1951_2000.

In addition to 2D buildings, palm_csd supports bridge-like structures. These are defined by a 2D map of their upper height above the surface and a constant structural depth. The latter is set for the entire domain via the configuration file. Similar to the standard buildings, the bridge height can be given as a column in a vector polygon or as a raster file. In the latter case, the IDs need to be supplied, whereas in the former case, they are optional. The building type of a bridge is set to bridge. When bridges are present in the domain, the generated static driver will include a 3D representation of the buildings, which is required to represent the airspace below the bridges. In all other cases, this field can be enabled manually to, for example, enable the 3D visualization of the domain.

Since the PALM release 24.04, PALM's building parameters, such as building surface albedo, building vegetation cover and building thermal properties, are supplied in the static driver in separate variables (Table ) with distinct dimensions (Table ) instead of the single variable building_pars. In palm_csd, these parameters can be supplied as attributes to building polygons and as raster files for individual buildings. For example, setting the building_heat_conductivity_wall_roof_2 attribute or supplying the respective raster data will set the heat conductivity of the second roof layer with the first layer being the outermost layer. More generally, setting building_heat_conductivity_wall will define the heat conductivity of all layers of all wall materials (ground floor, above ground floor and roof). In addition, default values can be set for the entire domain via the configuration file with a similar nomenclature.

Optionally, palm_csd can ensure that a buffer zone of a chosen width at the borders of the domain is building-free to enhance the stability of the PALM run. To this end, all buildings within that border are replaced by a user-selectable pavement type.

PALM represents vegetation in two ways: as flat, vertically unresolved vegetation types or as resolved vegetation described by the 3D distribution of the density of the vegetation. Unresolved vegetation is represented by vegetation types such as short_grass or evergreen_shrubs together with the leaf area index (LAI). The LAI (unit m² m⁻²) is defined as the one-sided area of leaves per ground area. The unresolved vegetation is used for vegetation that does not cover the full height of a grid cell. Resolved vegetation is defined by the leaf area density (LAD) and the basal area density (BAD). The LAD (unit m² m⁻³) is defined as the one-sided area of leaves per volume, while the BAD is defined as the area of branches per volume. This approach is preferred for vegetation that covers at least the height of a grid cell.

The LAI can be reproduced from the LAD by vertically summing over the LAD multiplied by the vertical grid spacing Δz: 1LAI=∑kLADkΔz. Please refer to vegetation.md in the palm_csd package or the corresponding section in the online documentation for all technical details.

Pavement is characterized by its material type, which is used to determine the energetic interaction with the surface and the atmosphere, and by its street type, which can be used to prescribe traffic-based pollutant emissions. The street types closely follow the OpenStreetMap classification. Street crossings indicate the locations where pedestrians can cross streets and are used by PALM's multi agent system. Please refer to pavement.md in the palm_csd package or the corresponding section in the online documentation for all technical details.

Both pavement and street types can be supplied directly. Alternatively, the pavement type can be derived from a column that includes strings or values that need to be mapped to PALM's pavement types and that possibly also include other types. The only valid value for street crossing is 1 to indicate that pedestrians can cross the street. It can be supplied as vector polygons or as a raster file.

Water surfaces are characterized by their type and a prescribed initial water body temperature. In addition to directly supplying the water type numerically, it can be derived from a column that includes strings or values that need to be mapped to PALM's water types and that possibly also include other types. The water temperature can be set for input polygons, as raster files or in the domain configuration on a per-type basis. Please refer to water_surfaces.md in the palm_csd package or the corresponding section in the online documentation for all technical details.

The terrain height can be supplied as a raster file or as a column in a vector polygon. If no terrain height is given for the entire domain, a default value of 0 m is used. Partially missing values in a domain are not allowed. Please refer to terrain_height.md in the palm_csd package or the corresponding section in the online documentation for all technical details.

palm_csd calculates the minimum terrain height of all domains, subtracts this value from all terrain heights and stores the result in the global origin_z attribute of the resulting static driver. The terrain height of a nested domain is shifted such that its mean is equal to the mean of the parent's terrain height in the nest's area to avoid artificial holes in the ground due to discretization. Furthermore, a gradual overlay of the terrain height is applied to avoid sharp gradients at the nest's boundaries. This is done by replacing the nest's terrain height by a weighted average of the parent's and the nest's terrain height within a 50 grid cell wide border of the nest. The parent's weight linearly decreases from 1 to 0 from the outside to the inside at the border of the nest.

So far, we focused on a detailed representation of the surface properties in the static driver. For coarser, non-building-resolving resolutions, palm_csd can also be used with less detailed Local Climate Zone (LCZ) input data. The LCZ classification consists of 17 classes, with classifications available for many urban areas in the World Urban Database and Access Portal Tool . In addition to standard PALM fields, palm_csd can also generate fields for the urban parametrization scheme DCEP , which calculates the urban radiation and energy fluxes. Buildings are represented by infinitely long street canyons characterized by their building width B, street width W and their building height distribution with the average H. Urban impervious surfaces and vegetation are treated as separate tiles with grid cell fractions furb and 1-furb, respectively.

Instead of the full data set required otherwise, only the input of an LCZ map and an orography map is needed here. Note that DCEP is currently under revision. The LCZ can be provided with either one layer with values from 1 to 17 for the 17 LCZ classes or a three-layer file with the red/green/blue (RGB) values of each LCZ class. Please refer to lcz_dcep.md in the palm_csd package or the corresponding section in the online documentation for all technical details.

The palm_csd package comes with the static_driver_stats tool that calculates statistics and can visualize any static driver (with results, for example, similar to Fig. ).

Furthermore, although palm_csd is a comprehensive stand-alone tool, its flexibility also enables seamless coupling with other applications. For example, the LCZ-wizard facilitates the customization of artificial urban environments by combining built and natural LCZs. It uses small LCZ-units (100×100 m²), which are aggregated into a coherent urban morphology. While the LCZ-wizard can be employed solely to generate building- and vegetation-resolving geodata, its interface with palm_csd extends this functionality by producing consistent static drivers that can be directly applied in PALM microscale simulations. We therefore recommend combining the LCZ-Wizard with palm_csd. Besides supporting the setup of typical urban scenario simulations, this approach is particularly suitable for systematic adaptation scenario studies. It also enables simulations of urban areas with scarce or missing input data, requiring only an LCZ classification map, which is globally available .

This section shows the basic steps for processing data for the city of Berlin (Germany) with palm_csd. The input data are freely available from the Geoportal (https://www.berlin.de/sen/sbw/stadtdaten/geoportal/, last access: 13 May 2025) and the Umweltatlas (https://www.berlin.de/umweltatlas/, last access: 13 May 2025). All required data is available for download as a single archive . While most of the processing steps are done by palm_csd, some preprocessing is required using GIS tools of the user's choice, for example, with the open-source tool QGIS^® . Its routines are mentioned in the following.

Once all input data have been processed as required, the files need to be placed into the input folder that is referenced in the YAML configuration of palm_csd. After all options are set in the YAML file, palm_csd is run with this file as an argument, which creates the static driver file in the output folder. For more technical details of this example, please refer to example.md in the palm_csd package or the corresponding section in the online documentation.

The building height data available for Berlin consist of vector polygons representing the building footprints, along with their attributes, such as building height (Fig. a). In this data set, few building heights are missing, which can be extracted from a normalized digital surface model (nDSM) raster. An nDSM represents the height of objects above ground level and can be calculated from a non-normalized DSM raster (object height above sea level, Fig. a) subtracted by a digital terrain model (DTM) raster (terrain height above sea level, Fig. b). Averages over each building polygon yield the required building heights. In QGIS, both steps are done with the Raster calculator and the Zonal statistics tool, respectively. The building ID is automatically assigned by palm_csd with a different value for each building polygon.

Similarly, other building parameters can be assigned to the building polygons, such as the albedo type, heat conductivity, heat capacity and the surface fractions on a building polygon basis or for the whole domain. In QGIS, this is done by adding a new column in the Attribute table with a user-chosen name. In palm_csd, this column name is then mapped to the respective input data. For example, mapping the column hcon_wa to building_heat_conductivity_wall assigns the heat conductivity of all layers of all wall elements and mapping hcap_wag_1 to building_heat_capacity_wall_gfl_1 assigns the heat capacity of the outermost wall layer of the ground floor. Analogously, by mapping the column bfrac_gr_r to building_fraction_green_roof and bfrac_wa_r to building_fraction_wall_roof, the green roofs are defined with their corresponding green and wall fractions. The fraction of windows is automatically set to 0 and, in general, the corresponding wall, green and windows fractions are normalized to 1.

In order to derive a vegetation, pavement and water type, the land-use data set from ALKIS^® (Amtliche Liegenschaftskatasterinformationssystem) is employed as vector polygons (Fig. b). ALKIS is Germany's official, integrated information system for managing the national real estate cadastre. It combines both textual registers and graphical maps into a single, unified database to describe all land parcels and buildings across the country. For palm_csd, each land-use class from ALKIS is directly mapped to a corresponding PALM type as proposed in Table  for the area of interest. Water surface temperatures are manually added as a column to the ALKIS data in QGIS. Alternatively, water temperatures can be set on a per-type, domain-wide basis in palm_csd's configuration file.

Two single tree data sets, street trees and park trees, are available as vector points for Berlin, which include the crown diameter, tree height, trunk circumference and tree type name (Fig. a). These data sets can be directly used by palm_csd, only the trunk diameter needs to be calculated from the trunk circumference, e.g. with QGIS' Field calculator. In order to include vegetation not captured by both tree data sets, the vegetation height raster available for Berlin can be employed (Fig. b). With this, vegetation patches are identified where this raster is above a certain height threshold.

Alternatively, for domains without precalculated vegetation height, it can be derived from an nDSM. In order to identify vegetation in the nDSM, the normalized difference vegetation index (NDVI) can be used, which is given by: 7NDVI=NIR-RedNIR+Red with Red and NIR standing for the spectral reflectance measurements acquired in the red (visible) and near-infrared regions, respectively (Fig. ). Pixels with an NDVI value greater than a threshold (e.g. 0.22) are classified as vegetation; everything below is classified as non-vegetation. The required reflectances are often available from orthophotos that include the NIR in addition to the Red, Green and Blue values.

The terrain height is directly derived from the DTM (Fig. b).

For the purpose of this example, we generate two static drivers (Fig. ) by defining two domain sections in the configuration file: a root domain and a higher-resolution nest domain. Since all input data are fully georeferenced, the same input data section can be used for both domains.

For non-building-resolving, coarser simulations, the data demand for a basic static driver is much lower. Here, we use the LCZ by and a DTM from the Geoportal of the state of Brandenburg (https://geoportal.brandenburg.de/, last access: 23 June 2026).

With the input in Fig. , the static driver can be generated directly after defining a target domain and geographical projection. Figure  shows the generated urban fraction in each grid cell from this static driver, with higher values in the city centre when using the defaults in Table .