WRF4PALM v1.0: A Mesoscale Dynamic Driver for the Microscale PALM Model System 6.0

A set of Python-based tools, WRF4PALM, has been developed for offline-nesting of the PALM model system 6.0 into the Weather Research and Forecasting (WRF) modelling system. Time-dependent boundary conditions of the atmosphere are critical for accurate representation of microscale meteorological dynamics in high resolution real-data simulations. WRF4PALM generates initial and boundary conditions from WRF outputs to provide time-varying meteorological forcing for PALM. The WRF model has been used across the atmospheric science community for a broad range of multidisciplinary applications. The PALM model system 6.0 is a turbulence-resolving large-eddy simulation model with an additional Reynolds averaged Navier–Stokes (RANS) mode for atmospheric and oceanic boundary layer studies at microscale (Maronga et al., 2020). Currently PALM has the capability to ingest output from the regional scale Consortium for Small-scale Modelling (COSMO) atmospheric prediction model. However, COSMO is not an open source model which requires a licence agreement for operational use or academic research (). This paper describes and validates the new free and open-source WRF4PALM tools (available on ). Two case studies using WRF4PALM

, operated by the Norwegian Meteorological Institute, to provide realistic boundary conditions in PALM. Similar to COSMO, MEPS is currently not publicly available.
To extend the use of PALM for the scientific community, we have developed a set of Python tools to allow PALM to include mesoscale forcing from the Weather Research and Forecasting modelling system (WRF; http://www.wrf-model.org; Skamarock et al., 2019). These tools are hereafter referred to as WRF4PALM, i.e. tools that process WRF output for use This paper describes WRF4PALM and presents validation of the tools. The PALM dynamical input data standard is described in Sect. 2. A description of the WRF4PALM framework is described in Sect. 3. Sect. 4 shows the validation and initial 65 application of WRF4PALM. Sect. 5 presents conclusions and an outlook for WRF4PALM.

PALM Offline-Nesting and Dynamical Input
The offline-nesting module embedded in PALM works as an interface between a mesoscale atmospheric model and PALM . This interface requires users to provide PALM with a netCDF dynamical driver file as an input (hereafter referred to as the dynamic driver; to be consistent with PALM documentation), which contains the meteorological forcing and 70 initial profiles of atmospheric state variables extracted from the mesoscale model. The dynamic driver created by WRF4PALM focuses solely on correctly and appropriately interpolating the dynamical fields extracted from WRF to fulfil the input data requirements of PALM.
Following the PALM Input Data Standard (PIDS) (https://palm.muk.uni-hannover.de/trac/wiki/doc/app/iofiles/pids), the dynamic driver must include initial vertical profiles of the atmosphere and soil, the lateral and top boundary conditions of the 75 atmosphere and time series of surface pressure (Table 1). Note that the variables listed in Table 1 are based on PIDS v1.9.
While some variable names may be changed in future updates of PALM, these can be modified in WRF4PALM code in such cases.

80
The new WRF4PALM (available on https://github.com/dongqi-DQ/WRF4PALM) is based on WRF2PALM initially developed by Faria (2019). Modifications and changes made to WRF2PALM to create WRF4PALM are described in Appendix A.
The data passed from WRF to PALM include velocity fields, thermodynamic components (pressure, temperature, potential temperature and water vapour mixing ratio), soil features, vertical grid structure (geopotential) and geographical information ( Table 2). The code structure of WRF4PALM is shown in Figure 1. WRF4PALM is written in the Python3 programming lan-85 guage. Two major Python scripts comprise WRF4PALM. One is create_cfg.py which reads user input and specifies the PALM domain within the WRF domain using latitude and longitude bounds. The other is create_dynamic.py which processes WRF dynamical fields to create the PALM dynamic driver. Detailed step-by-step instructions for running WRF4PALM are given in Appendix B.
The PALM grid configuration prescribes how the WRF output needs to be interpolated onto the PALM grid cells along 90 west-east (nx), south-north (ny) and bottom-top (nz) coordinates and the corresponding grid spacing along each direction (dx, dy and dz respectively). The latitude and longitude of the centre of the PALM domain must be provided to specify the PALM domain location in the WRF domain. By obtaining the aforementioned domain configuration information from users, the create_cfg.py script then generates a configuration file containing latitudes and longitudes for the north, south, east, and west lateral boundaries and a grid configuration for the PALM domain. The configuration file then acts as an in-95 put for create_dynamic.py to finish the interpolation. WRF4PALM also allows users to apply stretched grid spacing along the z-direction. Identical to parameters used in PALM input parameter list, users must define dz_stretch_level, dz_stretch_factor, and dz_max for vertically stretched grid spacing.
The create_dynamic.py script requires users to provide their own WRF output. WRF offers abundance of choices of parameterisations for microphysics, radiation, surface layer etc. Users also have a high degree of freedom to choose the meteo-100 rological data for initialisation, geospatial data and projection of the simulation domain. Although optimal WRF configurations will depend on the user's own research interests, any WRF output containing data described in Table 2 is considered applicable   for WRF4PALM. PALM also requires the start and end time stamps (in YYYY, MM, DD, HH format) and lateral and top boundary conditions update frequency to be provided by users. The lateral and top boundary conditions can update from every 1 minute to every 6 105 hours (or more) depending on the temporal frequency of WRF output and the user's own research needs. The thickness of the individual soil layers (dz_soil) to be used in PALM must be specified in create_dynamic.py. The default eight-layer configuration of WRF4PALM is the same as that described in Maronga et al. (2015).
Because both PALM and WRF use the Arakawa Cartesian grid staggering (staggered Arakawa C-grid, Harlow and Welch, 1965;Arakawa and Lamb, 1977), no transformation is required in PALM for staggered data. After reading the input param-110 eters described above, the script first extracts WRF data for the specified period and location required for PALM. Potential temperature, air temperature and pressure fields are read using the getvar function embedded in the WRF-Python package (Ladwig, 2019). Other variables, such as water vapour mixing ratio and wind field, are read using the xarray package (Hoyer and Hamman, 2017). Other than the vertical component of wind (w), all WRF variables are first interpolated on each horizontal field from the WRF domain onto the PALM horizontal Cartesian grid. The horizontal interpolation uses the SciPy package 115 (Virtanen et al., 2020). The WRF data that were horizontally interpolated to the PALM grid are then vertically interpolated onto PALM vertical Cartesian physical height levels. This requires the interplevel function in the WRF-Python package (Ladwig, 2019), which reads the WRF physical height levels and interpolates the given data onto required PALM vertical levels as defined in the PALM domain configuration file created by create_cfg.py. The WRF physical height levels are calculated using: 120 z = (P H + P HB)/g, where PH is the perturbation geopotential in m 2 s −2 , PHB is the base-state geopotential and g is gravitational acceleration (9.81 m 2 s −2 ). Equation (1) where ρ is air density in kg m −3 , f is the Coriolis parameter, P is pressure, x and y are coordinates along west-east and south-north respectively.

135
The height levels in WRF are terrain-following (Skamarock et al., 2019) while the Cartesian topography in PALM allows for explicitly resolving obstacles such as buildings and orography (Maronga et al., 2015). Due to such difference in topography The dynamic driver of PALM generated by the create_dynamic.py script only contains mesoscale dynamics from 155 WRF and does not encompass any turbulence which is completely parameterized in WRF. In order to obtain realistic flow characteristics, non-cyclic boundary conditions must be applied. When non-cyclic boundary conditions are used with offlinenesting, because no turbulence is included in the inflow, either a large domain is required to allow sufficient space and time for turbulence to develop or the synthetic turbulence generator (STG) must be applied (Gronemeier et al., 2015).

160
To resolve and realise near surface microscale structures, PALM can read a netCDF static driver file (hereafter static driver) as an input. The static driver includes information on buildings, streets, vegetation, soil, water bodies etc., in the model domain (Heldens et al., 2020). Due to high variability in geospatial data availability and quality across the world, it is unlikely to have a standard automatic process to generate PALM static driver. WRF4PALM does not require users to provide a static driver, which is applicable to both realistic simulations (with static driver) and relatively idealised simulations (without static driver).

165
However, we recommend users to include static driver in PALM simulations for more realistic and representative results to understand the impact of microscale surface structures. In the case studies described later, a static driver is included. We adopted similar procedure described in Heldens et al. (2020)  zone of mid-latitude westerlies in the Southern Hemisphere. A succession of subtropical anticyclones and depressions progress eastwards over the city (Macara, 2016). Westerly flows over Christchurch usually bring high clouds and sunshine while easterly flows sometimes lead to cloudiness and rainfall in Christchurch. The two case studies shown illustrate two simulation scenarios from real weather events that occurred in Christchurch -representing synoptic forcing from north-westerly airflow and the other 6 https://doi.org/10.5194/gmd-2020-306 Preprint. Discussion started: 1 December 2020 c Author(s) 2020. CC BY 4.0 License.
is from easterly and north-easterly flow modulated by a diurnal forcing. In this study, ground-based measurements are obtained from an automatic weather station (AWS) operated by the New Zealand Meteorological Service (MetService) at Christchurch Airport.

North-Westerly Case
During the late afternoon of 13 February 2017, the AWS operated by NZ MetService situated at the Christchurch airport measured strong north-westerly flows. The PALM simulation domain and the AWS location are shown in Figure 3. The 3.6 215 km (east-west) × 3.6 km (south-north) simulation domain is designed to: 1) include the AWS in order to compare the model data with the observational data and 2) avoid possible artefacts produced by STG near the north and west lateral boundaries. A narrow zone of laminar flows near the lateral boundaries at inflow can appear in the simulation due to the flow adjustment zone created by STG. As shown in Figure 4, this PALM simulation includes the 24-hour period between 1500 NZDT 13 February and 1500 NZDT 14th February 2017, which have seen the sustained north-westerlies over Christchurch. In Figure 4, time 220 series of the WRF modelling data have an hourly temporal interval while both PALM modelling data and observational data are 1 minute averages. Here both PALM and WRF winds are at 10 m in order to compare with 10 m winds measured by the AWS. Both PALM and WRF modelled temperature data shown in Figure 4 are 2-m data to represent surface air temperatures.
The time series of wind direction, wind speed and air temperature show good agreement between the observational data and the modelled data. WRF overestimated wind speed during the first 2 hours shown in Figure 4, and underestimated wind speed 225 between 0500 NZDT and 0800 NZDT 14 February. In addition, the air temperatures simulated by WRF are approximately 2 • C lower than the observed temperature during the entire 24-hour period. Table 4 compares the modelled surface temperature and wind speed with the observational data. The root-mean-square errors (RMSE): and index of agreement (IOA)  the WRF4PALM dynamic driver and PALM are carried out. Figure 5 compares the profiles of the u-component of winds 250 between WRF, the WRF4PALM dynamic driver and PALM. The profiles include 1) the initial vertical profiles and 2) left (west) boundary conditions (south-north vertical cross section at the left boundary). Profiles of other parameters in the dynamic drivers are not shown here. The WRF profiles are interpolated by WRF4PALM to the dynamic driver, which is further used as an input for PALM offline-nesting. As shown in Figure 5, profiles in the dynamic driver are generally identical to profiles in WRF meaning that WRF data are successfully interpolated and processed by WRF4PALM. Differences between profiles in 255 PALM and WRF can be spotted ( Figure 5), which are due to the turbulence generated by the STG embedded in PALM. Figure 5 shows that WRF4PALM successfully interpolates dynamics from WRF and passes them to PALM through the dynamic driver.
The boundary layer height is automatically calculated in PALM, which is 2300 m in Figure 5d. The WRF cross sections presented in Figure 7 are the nearest four WRF grid points (4 km × 4 km) processed to the PALM domain (3.6 km × 3.6 km). The cross sections of the two models show that PALM has strong agreement with WRF. However, WRF is not able to resolve any surface geometries because it is a terrain following model and only simulates mesoscale the intensity is likely to result from underpredictions in night-time turbulence generated by PALM incorporating the STG at inflow or the biases produced in the model due to coarse grid spacing (van Stratum and Stevens, 2015). The spatial resolution used in the PALM simulation is only 10 m, which may not be sufficient to represent the nocturnal boundary layer properly.
Despite the underestimation, PALM is able to reproduce the wind trends and directions. The wind anomalies statistics of WRF are not shown here because 1) the RANS mode of WRF only presents average properties of airflows and 2) the WRF output 290 used here only contains hourly data, which cannot give any wind anomaly information at each hour during the simulation period.

North-Easterly Case
In the late afternoons on 15 February 2017, easterly-north-easterly flows were observed over Christchurch airport. During the early mornings on 16 February 2017, calm northerlies were recorded. Similar to the north-westerly case described in Sect. and winds as well as in the north-westerly case described above. For the period after 0700 NZDT 16 February (see Figure   10), PALM follows the increasing trends of surface temperature and wind speed in WRF, but the underestimation of surface temperature in PALM is significant. Wind speed in PALM is approximately 2 m s −1 lower than both the WRF modelled data and the observational data. The largest difference in surface temperature between PALM and both WRF and the observational 305 data is approximately 7 • C. In terms of the RMSE and IOA for this case shown in Table 4, PALM has worse scores than WRF, despite the fact that PALM still has adequate agreement with WRF (IOA of 0.66 and 0.79 for surface temperature and wind speed, respectively). The wind anomaly analysis for the hourly averaged wind speed during the entire 24-hour simulation period is shown in Figure 14. In this case, PALM only has an adequate performance in terms of modelling wind anomalies. There could be several reasons for the bias in PALM. Regardless of different initialization situations between the two case 315 studies, cloud cover is suspected to be one particular reason causing errors in PALM. In both PALM simulations, the clear-sky radiation scheme is used. This radiation scheme is the simplest scheme in the PALM modelling system and neglects all clouds.
The observed cloud height and WRF-modelled clouds are shown in Figures 4 and 10. Here the variable cloud fraction is used to represent cloud cover in WRF. The grey shaded periods in Figures 4 and 10 represent when cloud fraction in WRF is greater than zero. Cloud fractions in WRF were averaged over the closest ten grid cells over the Christchurch airport. In the north-320 westerly case, most of the simulation period saw clear skies and only a small number of high clouds (above approximately 7500 m) were observed above the Christchurch airport and WRF generally has correct prediction of cloud cover (see Figure 4). In contrast, the period between 0400 NZDT and 1700 NZDT 16 February saw sustained low level clouds (1000 m to 3000 m) (see are required to investigate why PALM underestimates surface temperature and wind speed. However, this is beyond the scope of this study as here we only aim to validate WRF4PALM. Although PALM provides several radiation scheme options and has the bulk cloud module embedded, the detailed dynamics in simulations may vary case by case and hence the optimal simulation setup of PALM must be examined in future simulations.

340
This study describes a utility WRF4PALM that is developed to generate mesoscale forcing from WRF output for the PALM model system 6.0. Results of the application are also validated by two case studies in Christchurch, New Zealand for summer season. WRF4PALM does not require users to pre-process any data manually, but users need to provide their WRF output and PALM domain configuration. WRF4PALM only encompasses mesoscale dynamics from WRF and does not require a static driver of PALM. In order to include surface heterogeneities, the PALM static driver is used in this study when it is 345 necessary to realise microstructures in urban environment and hence to achieve realistic and representative results in PALM simulations. In the case studies, WRF4PALM was applied to two weather events simulated by WRF for a north-westerly case and a north-easterly case in Christchurch, New Zealand. The case studies are designed to demonstrate the numerical stability of WRF4PALM rather than properly validate meteorology in the simulations. As shown in the case studies, overall WRF4PALM is considered to have good stability and is able to process dynamics from WRF to PALM successfully. While PALM inherited 350 most of the characteristics from WRF through the WRF4PALM dynamic driver, PALM's ability to resolve turbulence structure is essential to realise and represent microscale dynamics in urban environment. Comparison of wind anomalies statistics also show satisfactory agreement between PALM and the AWS observational data.
For future use, the domain size, grid spacing, radiation scheme and all other model setup of WRF and PALM need to be evaluated subject to users' own objectives and scope of research questions. In this study, the lateral and top boundary conditions 355 in the WRF-PALM offline-nesting are updated every 1 hour meaning PALM is significantly impacted and constrained by WRF.
The sensitivity to the relaxation time and the STG configuration to develop initial turbulence need further assessment.
WRF4PALM is distributed as a free and open-source tool. In the future development, we aim to optimise WRF4PALM in terms of computation time and to further automate the process. As described in the PALM input data standard, the dynamic driver of PALM can also include boundary conditions of chemistry species, such as PM 10 , NO x (NO 2 , NO) and SO 4 etc., to 360 simulate air pollution in urban environments. WRF4PALM has the potential to process chemistry data from WRF-Chem (the WRF model coupled with chemistry, Grell et al., 2005) to PALM using the similar interpolation technique described in Sect.
3.1. Although several tests and validations have been carried out for WRF4PALM, they may not be conclusive. To improve and extend the use of WRF4PALM, we welcome all users to optimise, modify and contribute to the code.

370
Sample availability. The WRF4PALM dynamic driver and the corresponding configuration file are available in the supplements for the north-westerly case study described in Sect. 4.2. All PALM input files to simulate the north-westerly case will also be provided in the supplements.

Appendix A: WRF4PALM Development
Based on ideas and techniques applied in WRF2PALM, the following changes have been made to develop WRF4PALM:

375
-Add initial vertical profiles interpolated from WRF to initialise PALM -Modify geostrophic wind calculation -Add create_cfg.py script to read user input to reduce manual processing -Improve methods for PALM domain configuration, which is almost identical to PALM input parameters -Adjust physical heights calculated from WRF for vertical interpolation.
-Adjust horizontal interpolation method for boundary conditions.   Run create_cfg.py to create a configuration file containing the domain information for create_dynamic.py.

B2
Step 2 Process WRF for PALM       Figure 14, but for the north-easterly case.