!!! Currently under construction !!'''

PALM-4U provides a standardized way via the NetCDF data format to input e.g. global attributes, topography data or surface properties, vegetation properties, etc., as well as initialization data and boundary conditions for the prognostic variables.

Input variables are distinguished between static, dynamic, radiation and chemistry input variables, while for each type a separate input file exists. The static input file, indicated by the filename supplement _STATIC, contains all static information, such as topography, geographical latitude and longitude, surface property and vegetation information. The dynamic input file, indicated by the filename supplement _STATIC, contains dynamic information on the initial state of the atmosphere or time-dependent boundary conditions. The radiation input file, indicated by _RAD, contains static and dynamic information on radiation properties such as trace gas profiles or sky-view factors. The chemistry input file, indicated by _CHEM, contains static and dynamic information on chemical species and emissions.

The initialization procedure for the surface elements follows a multi-step approach, depending on the given level of detail. In a first step, surfaces elements 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, surface elements are initialized individually by providing the bulk classification at each grid point. In case more detailed information is available, all/single parameters can also 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.

After reading the input files, PALM-4U performs consistency checks on the provided data. All applied input variables are listed and explained below and additional remarks on restrictions and initialization are given. Please note, this documentation does not comprise all possible global and variables attributes, only those which are required for read by PALM. More detailed information on variable attributes can be found in the Palm input data standard.

Static input file

Global attributes:

Attribute	Type	Explanation / Remarks
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_z	NC_FLOAT	Reference height in m above sea level after DHHN2016.

Topography:

In order to prescribe topography from the static input file, topography = 'read_from_file' is required. The minimum requirement for proper topography input is orography_2D.

Input variable	Type	LOD	Explanation / Remarks
orography_2D(y,x)	NC_FLOAT	none	Terrain height in m relative to origin_z. If not provided, the relative terrain height will be set to 0 all over the model domain. Please note, orography_2D must not contain any _FillValues.
buildings_2D(y,x)	NC_FLOAT	1	2-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 are prescribed, building_id is required.
buildings_3D(z,y,x)	NC_BYTE	2	3-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 do not need to be prescribed beyond the top level of the highest buildings. If buildings_3D are prescribed, building_id is required.
building_id(y,x)	NC_INT	none	Building ID is used to identify single building envelopes, 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_2D/3D is defined.

Surface variables:

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 need to be set to 'netcdf'. 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 need to be defined at each 'xy' location if the land- and urban-surface model is applied. Further, in case data is taken from the static input file, both, the land- and urban-surface model need to be either switched on or off. Applying only one of the energy-balance models is not sufficient and will lead to an controlled termination.

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

Resolved plant canopy:

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

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

Dynamic input file

The dynamic input file (see PIDS_DYNAMIC) comprises all data which might change depending on the day of year, such as initialization data, large-scale forcing tendencies or boundary data. Utilizing the pre-processing tool inifor, the respective data can be derived directly from the larger-scale ​COSMO model (except for active or passive chemical components which are not considered in the COSMO model). This way, the dynamic input file acts as a interface between a larger-scale model and PALM-4U, being a so-called offline nesting. In case of a nested model run (online), only the parent domain considers the dynamic input_file for inititialization and offline-nesting, while embedded child models itself will be initialized and forced via its parent domains. In order to activate input from the dynamic input file, setting of initializing_actions = 'inifor' is required. For more information of how to create a dynamic input file, please see the inifor documention. For more detailed documentation of the input variables, please see Palm input data standard.

Input variable	Type	LOD	Explanation / Remarks
init_atmosphere_pt (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of potential temperature. lod=2: Initial volume data of potential temperature.
init_atmosphere_qv (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of mixing ratio. lod=2: Initial volume data of mixing_ratio. Input of this quantity becomes only effective if humidity = .T..
init_atmosphere_u (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of the wind component in the x-direction. lod=2: Initial volume data of the wind component in the x-direction.
init_atmosphere_v (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of the wind component in the y-direction. lod=2: Initial volume data of the wind component in the y-direction.
init_atmosphere_w (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of the wind component in the z-direction. lod=2: Initial volume data of the wind component in the z-direction.
init_atmosphere_s (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of any passive scalar. lod=2: Initial volume data of any passive scalar. Input of this quantity becomes only effective if passive_scalar = .T.. Please note, this quantity is currently not provided by inifor.
init_atmosphere_no (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of nitrogen monoxide. lod=2: Initial volume data of nitrogen monoxide. Input of this quantity becomes only effective if the chemistry model is switched on. Please note, this quantity is currently not provided by inifor.
init_atmosphere_no2 (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of nitrogen dioxide. lod=2: Initial volume data of nitrogen dioxide. Input of this quantity becomes only effective if the chemistry model is switched on. Please note, this quantity is currently not provided by inifor.
init_atmosphere_no3 (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of nitrate. lod=2: Initial volume data of nitrate. Input of this quantity becomes only effective if the chemistry model is switched on. Please note, this quantity is currently not provided by inifor.
init_atmosphere_pm10 (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of PM10. lod=2: Initial volume data of PM10. Input of this quantity becomes only effective if the chemistry model is switched on. Please note, this quantity is currently not provided by inifor.
init_atmosphere_hn03 (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of nitric acid. lod=2: Initial volume data of nitric acid. Input of this quantity becomes only effective if the chemistry model is switched on. Please note, this quantity is currently not provided by inifor.
init_atmosphere_so4 (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of sulfate. lod=2: Initial volume data of sulfate. Input of this quantity becomes only effective if the chemistry model is switched on. Please note, this quantity is currently not provided by inifor.
init_atmosphere_yyy (z,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial profile of any further species. lod=2: Initial volume data of any further species. Input of this quantity becomes only effective if the chemistry model is switched on. Please note, this quantity is currently not provided by inifor.
init_building_temperature ((s),(nwall),y,x)	NC_FLOAT	1, 2, 3	Initialization of walls and indoor temperatures with varying level of detail. Requires the urban-surface model to become effective. lod=1: The same wall temperature is assumed for all walls of the building at location (y,x). lod=2: The wall layer temperatures of a building at (y,x) are provided individually for each layer. lod=3: The wall temperatures are provided individually for each surface element and for each wall layer.
init_pavement_temperature (zsoil,(y),(x))	NC_FLOAT	1, 2	Initialization of the pavement temperature. Requires the land-surface model to become effective. lod=1: For all paved surface elements the same pavement temperature profile is prescribed. lod=2: The pavement temperature profile is prescribed for each (y,x)-location individually.
init_soil_t (zsoil,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial vertical profile of soil temperature. lod=2: Initial volume data of soil temperature. Input of this quantity becomes only effective if the land-surface model is switched on. In case of a nested run, soil temperature in the child domain will be initialized by horizontal mean vertical soil-temperature profiles derived from the respective parent (even if volume data is provided in the dynamic input file). Moreover, please note zsoil need to have the same dimensions as in the static input file
init_soil_m (zsoil,(y),(x))	NC_FLOAT	1, 2	lod=1: Initial vertical profile of soil moisture. lod=2: Initial volume data of soil moisture. Input of this quantity becomes only effective if the land-surface model is switched on. In case of a nested run, soil moisture in the child domain will be initialized by horizontal mean vertical soil-moisture profiles derived from the respective parent (even if volume data is provided in the dynamic input file). Moreover, please note zsoil need to have the same dimensions as in the static input file
init_water_temperature (y,x)	NC_FLOAT	none	Initialization of the water temperature at location (y,x). Requires the land-surface model to become effective.
nudging_pt (time,z)	NC_FLOAT	none	Nudging data for potential temperature. Requires cyclic boundary conditions as well as nudging = .T. to become effective.
nudging_qv (time,z)	NC_FLOAT	none	Nudging data for the mixing ratio. Requires cyclic boundary conditions as well as nudging = .T. and humidity = .T. to become effective.
nudging_u (time,z)	NC_FLOAT	none	Nudging data for the wind in the x-direction. Requires cyclic boundary conditions to become effective.
nudging_v (time,z)	NC_FLOAT	none	Nudging data for the wind in the y-direction. Requires cyclic boundary conditions to become effective.
nudging_w (time,z)	NC_FLOAT	none	Nudging data for the wind in the z-direction. Requires cyclic boundary conditions to become effective.
nudging_s (time,z)	NC_FLOAT	none	Nudging data for a passive scalar. Requires cyclic boundary conditions as well as nudging = .T. and passive_scalar = .T. to become effective.
nudging_tau (time,z)	NC_FLOAT	none	Nudging relaxation time scale. Requires cyclic boundary conditions as well as nudging = .T. to become effective.
ls_forcing_ug (time,z)	NC_FLOAT	none	Large­-scale forcing data for the geostrophic wind component in x-direction. Requires cyclic boundary conditions as well as large_scale_forcing = .T. to become effective.
ls_forcing_vg (time,z)	NC_FLOAT	none	Large­-scale forcing data for the geostrophic wind component in y-direction. Requires cyclic boundary conditions as well as large_scale_forcing = .T. to become effective.
ls_forcing_sub_w (time,z)	NC_FLOAT	none	Large­-scale forcing data for the subsidence velocity. Requires cyclic boundary conditions as well as large_scale_forcing = .T. to become effective.
ls_forcing_adv_lpt (time,z)	NC_FLOAT	none	Large­-scale forcing data for the advection tendency of potential temperature. Requires cyclic boundary conditions as well as large_scale_forcing = .T. to become effective.
ls_forcing_adv_qv (time,z)	NC_FLOAT	none	Large­-scale forcing data for the advection tendency of mixing ratio. Requires cyclic boundary conditions as well as large_scale_forcing = .T. to become effective.
ls_forcing_left_pt (time,z)	NC_FLOAT	none	Boundary condition at left (west) model boundary for the potential temperature. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_left_qv (time,z)	NC_FLOAT	none	Boundary condition at left (west) model boundary for the mixing ratio. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_left_u (time,z)	NC_FLOAT	none	Boundary condition at left (west) model boundary for the wind component in x-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_left_v (time,z)	NC_FLOAT	none	Boundary condition at left (west) model boundary for the wind component in y-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_left_w (time,z)	NC_FLOAT	none	Boundary condition at left (west) model boundary for the wind component in z-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_right_pt (time,z)	NC_FLOAT	none	Boundary condition at right model boundary for the potential temperature. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_right_qv (time,z)	NC_FLOAT	none	Boundary condition at right (east) model boundary for the mixing ratio. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_right_u (time,z)	NC_FLOAT	none	Boundary condition at right (east) model boundary for the wind component in x-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_right_v (time,z)	NC_FLOAT	none	Boundary condition at right (east) model boundary for the wind component in y-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_right_w (time,z)	NC_FLOAT	none	Boundary condition at right (east) model boundary for the wind component in z-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_front_pt (time,z)	NC_FLOAT	none	Boundary condition at front (south) model boundary for the potential temperature. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_front_qv (time,z)	NC_FLOAT	none	Boundary condition at front (south) model boundary for the mixing ratio. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_front_u (time,z)	NC_FLOAT	none	Boundary condition at front (south) model boundary for the wind component in x-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_front_v (time,z)	NC_FLOAT	none	Boundary condition at front (south) model boundary for the wind component in y-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_front_w (time,z)	NC_FLOAT	none	Boundary condition at front (south) model boundary for the wind component in z-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_back_pt (time,z)	NC_FLOAT	none	Boundary condition at back (north) model boundary for the potential temperature. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_back_qv (time,z)	NC_FLOAT	none	Boundary condition at back (north) model boundary for the mixing ratio. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_back_u (time,z)	NC_FLOAT	none	Boundary condition at back (north) model boundary for the wind component in x-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_back_v (time,z)	NC_FLOAT	none	Boundary condition at back (north) model boundary for the wind component in y-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_back_w (time,z)	NC_FLOAT	none	Boundary condition at back (north) model boundary for the wind component in z-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_top_pt (time,z)	NC_FLOAT	none	Boundary condition at top model boundary for the potential temperature. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_top_qv (time,z)	NC_FLOAT	none	Boundary condition at top model boundary for the mixing ratio. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_top_u (time,z)	NC_FLOAT	none	Boundary condition at top model boundary for the wind component in x-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_top_v (time,z)	NC_FLOAT	none	Boundary condition at top model boundary for the wind component in y-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.
ls_forcing_top_w (time,z)	NC_FLOAT	none	Boundary condition at top model boundary for the wind component in z-direction. Requires non-cyclic boundary conditions as well as forcing = .T. to become effective.

Radiation input file

Please note, radiation input is currently not implemented in PALM-4U, but will follow soon.

Input variable	Type	LOD	Explanation / Remarks
rad_swd_dif_0 (time,y,x)	NC_FLOAT	none	Incoming diffuse shortwave radiative flux at the surface. Requires the radiation model switched on to become effective.
rad_swd_dir_0 (time,y,x)	NC_FLOAT	none	Incoming direct shortwave radiative flux at the surface. Requires the radiation model switched on to become effective.
rad_swu_dif_0 (time,y,x)	NC_FLOAT	none	Outcoming diffuse shortwave radiative flux at the surface. Requires the radiation model switched on to become effective.
rad_swu_dir_0 (time,y,x)	NC_FLOAT	none	Outcoming direct shortwave radiative flux at the surface. Requires the radiation model switched on to become effective.

Chemistry input file