palm_csd 25.10: a processing tool for static input data in the PALM model system

We present palm_csd version 25.10, the current default preprocessing tool for generating the static driver for the building-resolving large-eddy simulation model PALM. The static driver defines the spatial surface characteristics of the simulation domain. This paper provides a technical description of the updated palm_csd workflow, focusing on the processing of buildings, vegetation, pavement, water bodies, terrain height and land cover in compliance with the PALM Input Data Standard (PIDS). Major extensions introduced since the previous description include the processing of georeferenced raster and vector data with automated reprojection, user-defined domain rotation and nesting, enhanced handling of building parameters, optimized generation of resolved vegetation, estimation of leaf area index from vegetation height, and the derivation of static input for non-building-resolving simulations based on Local Climate Zone classifications. We demonstrate the application of palm_csd using publicly available geodata for the city of Berlin (Germany), covering both building-resolving and LCZ-based simulation setups. Common data inconsistencies and sources of uncertainty in urban geodata are discussed. palm_csd 25.10 provides a reproducible, flexible and continuously maintained framework for transforming heterogeneous geospatial datasets into PALM-compatible static drivers to support both detailed urban morphology and coarser-scale urban climate applications.

1 Introduction

With the advent of modern high-performance computing, detailed simulation of the atmospheric flow field in urban areas has become feasible. Large-eddy simulation (LES)-based microscale atmospheric models, once limited to idealized flows, are now routinely applied to complex urban environments and form the basis of microscale urban climate modeling. This progress has been accompanied by advances in numerical methods, turbulence representation and physical parameterizations of energy and mass exchange at the urban surface. State-of-the-art microscale building-resolving models now resolve the coupled processes of momentum, heat and radiation transfer within the urban canopy layer and integrate comprehensive schemes for surface energy balance, radiative exchange and vegetation–atmosphere interactions (Maronga et al., 2020; Salim et al., 2018; Eichhorn and Kniffka, 2010; Bruse and Fleer, 1998). These developments created the methodological foundation for investigating the physical mechanisms governing urban climate and for addressing challenges such as heat stress, ventilation and outdoor comfort in the context of microclimate research for sustainable city development.

Building on these advances, the PALM model system (Maronga et al., 2020) has become one of the most widely used modeling frameworks for microscale urban climate studies. PALM employs a LES approach based on the filtered, incompressible Navier–Stokes equations, with buoyancy treated through the Boussinesq approximation. Its modular structure incorporates specialized components such as the urban surface model (Resler et al., 2017), land surface model (Gehrke et al., 2021), plant canopy model (Maronga et al., 2015), radiative transfer model (Krč et al., 2021; Salim et al., 2022), building energy model (Pfafferott et al., 2021) and atmospheric chemistry module (Khan et al., 2021). These components allow PALM to explicitly resolve the three-dimensional interactions between the built environment and the atmosphere, enabling realistic simulations of urban boundary layers, surface energy fluxes and thermal comfort indicators (Anders et al., 2023, 2025).

Realistic PALM simulations require high-quality input data that represent both the spatial configuration of the urban surface and the time-dependent atmospheric forcing. Two categories of input are required: the static driver, which defines all spatially invariant characteristics of the simulation domain, and the dynamic driver, which provides transient meteorological boundary and initial conditions derived from mesoscale models or observations. The static driver includes elements such as topography, building geometry, land cover and vegetation, and is thus of particular importance because it encodes the physical structure and material properties that govern radiative exchange, energy storage and aerodynamic roughness within the urban canopy. Preparing these data, however, remains a demanding and time-consuming task that involves gathering and harmonizing heterogeneous geospatial sources, translating them into the PALM Input Data Standard (PIDS, Heldens et al., 2020) and ensuring internal consistency across a large number of variables. Manual preparation is feasible for small test cases but becomes impractical for city-scale applications or when high spatial resolution is required.

To address this challenge, the Python-based command line palm_csd tool (PALM tool to Create Static Driver) was developed as the standard and officially distributed preprocessor of the PALM model system. palm_csd provides a structured and reproducible workflow for transforming heterogeneous geospatial datasets into PIDS-compliant static drivers. It supports a wide range of input formats, performs automated data consistency checks and ensures that all surface and geometric parameters required by PALM are correctly formatted and physically coherent. The tool was initially established within the MOSAIK project (Maronga et al., 2019; Heldens et al., 2020) to process high-resolution datasets for several German cities and has since become the reference framework upon which more specialized preprocessors, such as the PALM-4U GUI (Winkler et al., 2023), PALM-GEM (Bureš and Resler, 2024), GEO4PALM (Lin et al., 2024) and SanDyPALM (Vogel et al., 2025), have been developed.

Although several new preprocessing tools have emerged recently (Fluck, 2023; Bureš and Resler, 2024; Vogel et al., 2025), palm_csd is designed to be the reference implementation for creating static input data in the PALM model system. Its design follows the PIDS and is continuously updated to reflect ongoing developments and new features in the PALM model itself. This integration ensures that the structure and content of static drivers remain fully compatible with the current PALM release version.

The objective of this paper is to provide a technical description of the palm_csd preprocessor as of version 25.10, including its input data model, internal structure and workflow for generating PALM-compatible static drivers. We describe how the tool processes and validates geospatial input data, assigns surface and material properties, constructs three-dimensional fields such as building masks and leaf area density, and ensures compliance with the PIDS. Furthermore, we highlight recent extensions and improvements introduced in the latest PALM releases, including enhanced data validation, additional input variables and more flexible file handling.

After explaining in detail the features of palm_csd, we present an approach to generate a static driver for Berlin (Germany) based on freely available data, both for detailed building-resolving simulations and for coarse non-building-resolving simulations based on Local Climate Zone data. This is followed by a discussion of palm_csd's features compared to other tools as well as input data availability and the resulting uncertainties.

2 Description of palm_csd

palm_csd supports all maintained Python versions (at the time of writing, 3.10 to 3.14) with extensive automatic tests, including static type checking with mypy, as well as linting and formatting with ruff. All user input is checked for consistency. The configuration file for palm_csd is written in the YAML file format (Schubert, 2026). This tool is extensively documented in the docs folder of the Zenodo code package (Schubert, 2026), with its markdown files referenced throughout this paper, or under https://docs.palm-model.org/25.10/Tools/palm_csd/ (last access: 23 June 2026). For the latest release, replace “25.10” by “latest” in this URL. For all technical details, please refer to this documentation. Besides its different sections, it also features a complete reference of all options in the YAML file (yaml.md).

Compared to the palm_csd version described in Heldens et al. (2020), in addition to many minor enhancements, we mainly

• added direct processing of georeferenced raster and vector data, including the calculation of coordinates with support for arbitrary rotation angles,

• added support for building parameters,

• added an optional removal of buildings in a buffer zone at the borders of a domain,

• optimized the generation of resolved vegetation,

• added estimation of the leaf area index from vegetation height,

• added Local Climate Zone-based input and the generation of parameters for an urban parametrization scheme,

• added input data checks and extensive output messages,

• added a statistics and visualization tool,

• added extensive documentation,

• changed the configuration to the YAML format, and

• added automatic tests and improved the code quality.

In the following, the complete features of palm_csd are explained in detail: the general set-up of the domains and input file handling as well as the processing of buildings, vegetation, pavement, water bodies and terrain height. After that, an alternative approach for non-building-resolving simulations is presented based on Local Climate Zones data input as well as a short section about other tools using palm_csd. Throughout the paper, we use the names of pavement, vegetation and water types as used in the set-up of palm_csd, e.g. bare_soil instead of “bare soil”, to allow for direct usage of these names by the user.

2.1 Domain set-up, input files and their geographic processing

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. 1). The latter is the angle between the projected coordinate system's north axis N_C and the domain's north axis N_D. 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.

Figure 1 Illustration of nested domains. The rotation_angle describes the angle between the projected coordinate system's north axis N_C and the north axis of the domain N_D. Together with the epsg code that describes the coordinate reference system, it is applied to all domains. The other parameters are set on a per-domain basis: grid points in the horizontal and vertical directions, nx+1 and ny+1, horizontal pixel_size (dx and dy in PALM) and the vertical grid spacing dz.

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.

2.2 Buildings

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.

Table 1 Building and building surface parameters of PALM and their dimensions (cf. Table 2). In palm_csd, they can be set individually for each building polygon, read from a raster map and defined globally for all building.

Table 2 Dimensions of PALM's building parameters. In addition, building_surface_layer includes surface layers 1 to 4.

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 1) with distinct dimensions (Table 2) 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.

2.3 Vegetation

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:

$$\begin{array}{}\text{(1)}& \mathrm{LAI}=\sum _k{\mathrm{LAD}}_k\mathrm{\Delta }\mathrm{z}.\end{array}$$

Please refer to vegetation.md in the palm_csd package or the corresponding section in the online documentation for all technical details.

2.3.1 Unresolved vegetation

palm_csd supports the direct input of the different vegetation types that PALM supports. Additionally, the LAI can be supplied, which is then used instead of the default values in PALM. Note that vegetation types that represent high (grown) vegetation feature large roughness lengths z₀ and z_0,h for momentum and heat, respectively, with z₀>1 m and $z_{\mathrm{0},h}>\mathrm{1}$ m. These vegetation types are therefore not suitable for the vertical grid spacing typically used in building-resolving simulations. If the vertical grid spacing is close to or smaller than the roughness lengths, PALM will crash or will not provide meaningful results. Thus, by default, high vegetation types are replaced by resolved vegetation depending on what is described below.

Besides supplying the vegetation type directly, it can be derived from a column that includes strings or values that need to be mapped to PALM's vegetation types. This column could possibly also include pavement or water types. Vegetation cover on buildings can be set as a building parameter, as explained above.

2.3.2 Resolved vegetation

palm_csd can generate LAD and BAD fields from two input variants: single tree input and vegetation patch input. In the single tree case, LAD and BAD are generated from detailed information of individual trees, while in the vegetation patch case, when detailed information is missing, LAD is generated from the vegetation height, LAI and patch type information. If not directly available as input, the LAI can be estimated from the vegetation height h with

$$\begin{array}{}\text{(2)}& \mathrm{LAI}={\mathit{\lambda }}_{\mathrm{LAI}}\cdot h,\end{array}$$

with a default value of 0.2 for the factor λ_LAI following Vogel et al. (2025). Alternatively, separate constant LAIs for low and high vegetation can be defined.

The LAD and BAD fields of single trees are generated from single tree information. A single tree is defined by its height, crown diameter, trunk diameter, crown height (all in m) and shape (see Heldens et al., 2020, for the different available shapes). The input quantities can be specified as a single file or as several vector point files, with the columns representing the respective input data or as separate corresponding raster files. In the case of vector point input, the tree type can also be derived from a column that includes the tree species name as text. The content of this column is compared with the species name used in the tree default table (see Heldens et al., 2020). If one of the tree attributes is missing, default values from this table are used.

In order to capture tree-like vegetation in areas where detailed tree data are not available, palm_csd can generate LAD distributions inside these “vegetation patches”; BAD values are currently not generated. A vegetation patch is identified if one of the following conditions is met: (a) the vegetation height is larger than a threshold, (b) a vegetation type defined as “high vegetation” is present, or (c) a defined patch type is present.

Depending on the user's choice, one of the following continuous vertical LAD profiles is assumed for each identified vegetation patch pixel: The profile of Markkanen et al. (2003) is given (up to a normalization constant) by

$$\begin{array}{}\text{(3)}& {\mathrm{LAD}}_{\mathrm{M}\mathrm{03}}\left(z\right)\propto {\left({\displaystyle \frac{z}{h}}\right)}^{\mathit{\alpha }-\mathrm{1}}{\left(\mathrm{1}-{\displaystyle \frac{z}{h}}\right)}^{\mathit{\beta }-\mathrm{1}}\end{array}$$

where α and β are the shape parameters of the profile. The profile of Lalic and Mihailovic (2004) is given by

$$\begin{array}{}\text{(4)}& \begin{array}{rl}& {\mathrm{LAD}}_{\mathrm{LM}\mathrm{2004}}\left(z\right)=L_m{\left({\displaystyle \frac{h-z_m}{h-z}}\right)}^n\exp \left[n\left(\mathrm{1}-{\displaystyle \frac{h-z_m}{h-z}}\right)\right]\\ & \text{with}n=\left\{\begin{array}{ll}\mathrm{6}& \text{for }\mathrm{0}\le z<z_m\\ \mathrm{0.5}& \text{for }{z}_m\le z\le h\end{array}\right..\end{array}\end{array}$$

Here, z_m is the relative height of the highest LAD value L_m and a parameter of this profile. L_m is given by the normalization of the profile to the LAI. In order to support the choice of a profile, palm_csd comes with an interactive tool to visualize the different profiles depending on α, β and z_m, respectively.

In order to discretize the LAD profile for the PALM grid, the LAD is integrated over the vertical grid spacing Δz and averaged over the grid cell height z_k to z_k+1, where z_k is the lower height of the grid cell and z_k+1 is the upper height of the grid cell. The resulting LAD value for each grid cell is given by

$$\begin{array}{}\text{(5)}& {\mathrm{LAD}}_k={\displaystyle \frac{\mathrm{1}}{\mathrm{\Delta }z}}\underset{z_k}{\overset{z_{k+\mathrm{1}}}{\int }}\mathrm{LAD}\left(z\right)\mathrm{d}z.\end{array}$$

When evaluated with the profiles (3) and (4), the expressions include the regularized incomplete beta function and the non-regularized upper incomplete gamma function, respectively. Both functions are taken from the SciPy package (Virtanen et al., 2020).

For both single trees and vegetation patches, it is ensured that there are no LAD and BAD fields within buildings. High vegetation types for which resolved vegetation is generated are replaced by a chosen vegetation type.

2.4 Pavement, street surfaces and street crossings

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.

2.5 Water surfaces

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.

2.6 Terrain height

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.

2.7 Local Climate Zone based input for non-building-resolving simulation

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 (Stewart and Oke, 2012) consists of 17 classes, with classifications available for many urban areas in the World Urban Database and Access Portal Tool (Ching et al., 2018). In addition to standard PALM fields, palm_csd can also generate fields for the urban parametrization scheme DCEP (Schubert et al., 2012), 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 f_urb and 1−f_urb, 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.

2.7.1 PALM parameters

For each LCZ class, several PALM properties are assigned (Table 3): a vegetation type, a water type and a leaf area index for winter and summer. These values can also be adjusted by the user. The vegetation type interrupted_forest is assigned to urban LCZ classes under the assumption of low and high vegetation in these areas. The only additionally required data input is the orography.

Table 3 Assigned default parameters of each Local Climate Zone.

2.7.2 Derivation of DCEP parameters

According to the definition of the LCZ classification, valid minimum and maximum values of the following parameters are assigned to each LCZ class (Table 4): mean building-height-to-street-width ratio (aspect ratio) λ_S, building surface fraction λ_B, impervious (without buildings) and pervious fraction λ_I and λ_V, and average roughness element height H. For LCZ 1 and LCZ 4, a maximum building height was not defined. We follow Demuzere et al. (2022a) and set these values to 75 m. For the derivation of the required PALM input values, one value within the defined valid range of each parameter is used. This value can be set by the user. The default values are taken from the W2W default values (https://github.com/matthiasdemuzere/w2w/blob/main/w2w/resources/LCZ_UCP_lookup.csv, last access: 23 June 2026).

Table 4 Minimum (min), default (def) and maximum (max) value of LCZ parameters: mean building-height-to-street-width ratio (aspect ratio) λ_S, building surface fraction λ_B, impervious (without buildings) and pervious fraction λ_I and λ_V, and average roughness element height H. The latter represents the average building height in the case of urban LCZs. Their default values (avg) is the arithmetic or the geometric mean value of the minimum and maximum value, respectively.

The input parameters of DCEP are derived from the LCZ parameters as follows: The urban fraction f_urb of a grid cell is considered to be the total impervious fraction of a grid cell $f_{\text{urb}}={\mathit{\lambda }}_{\mathrm{B}}+{\mathit{\lambda }}_{\mathrm{I}}$. The street width W is calculated from the average building height and the aspect ratio with $W=H/{\mathit{\lambda }}_{\mathrm{S}}$. The building width B is given by $B={\mathit{\lambda }}_{\mathrm{B}}/{\mathit{\lambda }}_{\mathrm{I}}\cdot W$.

We follow the approach of Demuzere et al. (2022a) in the calculation of the distribution of building height: With the probability density function f of a normal distribution with the mean value H and a standard deviation $(H_{\text{max}}-H_{\text{min}})/\mathrm{4}$, the fraction p of buildings at a height h is given by

$$\begin{array}{}\text{(6)}& p\left(h\right)=\underset{h-\mathrm{\Delta }H/\mathrm{2}}{\overset{h+\mathrm{\Delta }H/\mathrm{2}}{\int }}f\left(x\right)\mathrm{d}x,\end{array}$$

with ΔH being the layer thickness. Numerically, the integral is calculated directly using the cumulative distribution function of the given normal distribution from SciPy (Virtanen et al., 2020). In contrast to Demuzere et al. (2022a), the user can choose between H representing the arithmetic or the geometric mean of building heights. The calculations in Eq. (6) are adjusted accordingly. In the original tool, only the arithmetic average is used, while the LCZ definition in Stewart and Oke (2012) is based on the geometric mean.

2.8 Coupling and other tools

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

Furthermore, although palm_csd is a comprehensive stand-alone tool, its flexibility also enables seamless coupling with other applications. For example, the LCZ-wizard (Anders and Maronga, 2025) 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 (Demuzere et al., 2022b, 2023).

3 Application example: Berlin, Germany

3.1 Building-resolving set-up

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 (Schubert and State of Berlin, Germany, 2026). 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^® (Graser et al., 2025). 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.

Figure 2 Vector polygons for the area of Tiergarten and its surrounding in Berlin (Germany) in UTM Zone 33N projection with north at the top.

Figure 3 Height rasters for the area of Tiergarten and its surrounding in Berlin (Germany) in UTM Zone 33N projection with north at the top.

The building height data available for Berlin consist of vector polygons representing the building footprints, along with their attributes, such as building height (Fig. 2a). 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. 3a) subtracted by a digital terrain model (DTM) raster (terrain height above sea level, Fig. 3b). 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.

Table 5 Proposed mapping of the ALKIS classes to PALM pavement, vegetation and water types when applied to Berlin (Germany).

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. 2b). 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 5 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.

Figure 4 Single tree vector points and vegetation height raster for the area of Tiergarten and its surrounding in Berlin (Germany) in UTM Zone 33N projection with north at the top.

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. 4a). 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. 4b). With this, vegetation patches are identified where this raster is above a certain height threshold.

Figure 5 NDVI raster based on orthophotos from August 2020 for the area of Tiergarten and its surrounding in Berlin (Germany) in UTM Zone 33N projection with north at the top.

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:

$$\begin{array}{}\text{(7)}& \mathrm{NDVI}={\displaystyle \frac{\mathrm{NIR}-\mathrm{Red}}{\mathrm{NIR}+\mathrm{Red}}}\end{array}$$

with Red and NIR standing for the spectral reflectance measurements acquired in the red (visible) and near-infrared regions, respectively (Fig. 5). 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. 3b).

Figure 6 Visualization of the generated static drivers in UTM Zone 33N projection with north at the top. The black rectangle in (a) indicates the position of the domain in (b).

For the purpose of this example, we generate two static drivers (Fig. 6) 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.

3.2 Non-building-resolving set-up based on LCZ input

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

Figure 7 Raster input data for the non-building-resolving static driver generation in UTM Zone 33N projection with north at the top.

Figure 8 Fraction of the urban surfaces in a grid cell from the generated static driver.

With the input in Fig. 7, the static driver can be generated directly after defining a target domain and geographical projection. Figure 8 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 4.

4 Discussion

palm_csd is a comprehensive open-source tool for creating the static driver for PALM, with well defined input data. It is a Python-based command line program without a graphical user interface, intended to be used in conjunction with any GIS application such as QGIS (Graser et al., 2025). It offers detailed handling of building parameters and vegetation. While palm_csd's standard settings work for most situations, palm_csd can be adjusted for different circumstances, including idealized data input. It supports arbitrary rotation angles and domain nesting. palm_csd is well documented, actively maintained, closely following the development of PALM and is easy to install using only widely-used Python packages.

Depending on the availability, consistency and accuracy of the available urban data, the preprocessing steps for palm_csd can be labour-intensive. There are no consistent, world-wide available, high-resolution urban morphology and land cover data sets. Thus, static driver processing tools offering general data access (e.g. Lin et al., 2024) can only use data that are too coarse for fine building-resolving simulations. For national states (e.g. Germany) or larger administrative units (e.g. the European Union), suitable and complete data sets are usually also not available, for example, because of incomplete or coarse building height data (Bernard et al., 2022; Szatmári et al., 2022). However, initiatives like the Infrastructure for Spatial Information in the European Community (INSPIRE) of the European Union (European Union, 2024) aim at the consolidation and public availability of geodata. Still, an international standard for geodata is lacking. Thus, currently, data preparation beyond political borders might require intensive data preparation, even within single national states (e.g. across the federal borders of Germany), which is often time-consuming and requires expert knowledge (Masson et al., 2020).

Out of the required input data of palm_csd, vegetation data, in particular the LAI, are usually the most difficult to acquire on a fine scale. For example, satellite derived LAI, as calculated by the SENTINEL2 Toolbox (Weiss et al., 2020), has a resolution that is equal to or coarser than 10 m. When comparing to in situ measurements, it shows overall good performance but with an underestimation over heterogeneous canopies (Brown et al., 2021), which are likely to occur in urban areas. Zhang et al. (2019) showed for a forest in northeast China that LAI tends to linearly increase with tree height, among other variables, which justifies our approximation in Eq. (2) to a certain extent. In addition, the literature on LAD profiles is sparse and mostly focusses on forests (e.g. Markkanen et al., 2003; Lalic and Mihailovic, 2004) rather than urban trees. Variations in quality can result in varying quality of the static driver that might even be visible in the PALM simulation results. Detailed local measurements using e.g. airborne laser scanning or terrestrial laser scanning (D'hont et al., 2024) offer the possibility to directly derive the LAD and BAD (Li et al., 2017; Kamoske et al., 2019) but are very resource-intensive, both in terms of scanning and computation.

Uncertainties in the input data can have considerable effects on the PALM results (cf. Belda et al., 2021; Resler et al., 2021). In addition, data are seldom up-to-date, especially in cities. Building data and land-cover data often represent different points in time and might not fit together perfectly. For small focus areas, this always requires careful data preparation.

Currently, as of version 25.10, palm_csd creates building data from 2D input data only. For standard buildings, this means that only 2.5D structures can be generated, i.e. buildings with horizontally varying height but without vertical gaps or holes. The only exceptions are bridge structures. Here, however, the structural depth is constant for each domain and input data is usually not readily available. For both building and bridges, building surface parameters can only be assigned for ground floor, above ground floor and roof levels (see Table 2a and c). Support for fully 3D structures including downward-facing surfaces was recently added to PALM's default radiation scheme for the urban canopy, RTM (Radović et al., 2026). Thus, for future versions of palm_csd, we plan to add support for the input of 3D building data, e.g. in the CityGML format (Open Geospatial Consortium, 2023). In particular, parameters for the newly developed cut-cell method will be implemented once it is fully evaluated and documented. Currently, only PALM-GEM can generate the required input parameters but also requires the set-up of a PostgreSQL database on the system. For our extension, the per-surface definition of building surface parameters will depend on the capabilities of the input format and the availability of tools to define these parameters in a 3D way. Note that it is not planned to extend palm_csd with a graphical editor for input data.

In addition, we also plan to extend the tree database with species-dependent allometric functions (e.g. Moser-Reischl et al., 2025) to more realistically represent trees of different ages. Furthermore, we will add support for generating fields for the single-layer urban canopy parametrization scheme PALM-SLUrb (Karttunen et al., 2025).

5 Conclusions

palm_csd allows the user of PALM working with realistic set-ups to create the complex input data required to represent the study domain. Although data preparation is still mandatory, palm_csd guides the user in collecting data and opens a wide range of options to include realism in the domain set-up. palm_csd answers the question of how to get surface-coverage data into the PALM simulation and simultaneously leaves the user enough room to construct a detailed built-up and vegetated study domain using already existing and well-established GIS tools.

As palm_csd is shipped with PALM, it always generates input data compatible with the latest PALM release. In order to ensure that, palm_csd is continuously developed further and automatically tested for each release.