Each case for PALM-meteo is configured using one or more YAML configuration files. If more than one files is used, the latter files extend and overwrite the prior files.

Configuration options

The list of all options which are considered user-configurable is supplied in the file template.yaml. This file contains the options with their default values and documentation as comments:

# A template with all user-selectable configuration options. Most options are
# commented out and the values shown are the defaults.
 
############################## GENERIC OPTIONS ##############################
 
#case: #case name (required)
# Optional scenario identification (for preparing multiple scenarios based on
# the same case)
#scenario:
#dnum: 1 #1 for root domain, 2 for nested domain *_N02 etc.
 
# One or more tasks selected by the user will add required plugins and set
# necessary options. Tasks typically select input meteo and/or chemistry data
# sources.
tasks:
    - wrf     # WRF meteo inputs
    #- wrf_rad # WRF radiation inputs
    #- icon    # ICON inputs
    #- aladin  # Aladin inputs
    #- camx    # CAMx chemistry inputs
    #- cams    # CAMS chemistry inputs
 
# Replacement strings to be used in paths. They are valid Python expressions
# and they may reference configuration values such as `dnum` or `scenario`.
path_strings:
    #case: 'case'
    #scenario: 'f"_{scenario}" if scenario else ""'
    #domain: 'f"_N{dnum:02d}" if dnum != 1 else ""'
 
# All paths are either absolute or relative to paths.base. They may contain
# references to entries in path_strings
paths:
    #base: '../JOBS/{case}{scenario}'
 
    palm_input:
        #dynamic_driver: 'INPUT/{case}_dynamic{domain}'
        #static_driver:  'INPUT/{case}_static{domain}'
 
    intermediate:
        #import_data: 'METEO/import{domain}.nc'
        #hinterp:     'METEO/hinterp{domain}.nc'
        #vinterp:     'METEO/vinterp{domain}.nc'
 
    snapshot:
        #setup_model:  'METEO/setup{domain}.pickle'
        #import_data:  'METEO/import{domain}.pickle'
        #hinterp:      'METEO/hinterp{domain}.pickle'
        #vinterp:      'METEO/vinterp{domain}.pickle'
 
    wrf:
        #file_mask:      'WRF/wrfout_*.e000'
        #rad_file_mask:  'WRF/auxhist6_*'
 
    camx:
        #file_mask:      'CAMX/CAMx.*.nc'
 
    icon:
        #file_mask:      'ICON/i?ff[0-9]_*.nc*'
        #static_data:    ~
 
    aladin:
        #output:         'ALADIN/aladin_import.nc'
        #grib_file_mask: 'ALADIN/ALADIN_GRIBS/**/*.grb'
        #soil_depth:     'ALADIN/aladin_soil_depth.grb'
 
    cams:
        #file:           'CAMS'
 
output:
    # Overwrite existing output files? Otherwise create a new file with
    # numerical suffix
    #overwrite: false
 
    # LODs for output variables:
    # LOD2 = 3D data (unchanged, default),
    # LOD1 = vertical profile (via horizontal averaging).
    lod:
        #pt: 2
        #qv: 2
        #uvw: 2
 
    #default_precision: 'f4'
    #fill_value: -9999.0
 
    #check_mass_balance: false #re-verify final mass balance after balancing
 
intermediate_files:
    #after a successful stage, delete the intermediate file from the previous stage
    delete_after_success: false
 
domain:
    #dz: #default=dx
    nz: #required
    #dz_stretch_level: -1.0 #in metres
    #dz_stretch_factor: 1.0
    #dz_max: -1.0 #in metres
    # minimal number of free surface canopy layers above top of terrain with
    # building and plant canopy
    #nscl_free: 3
 
simulation:
    #origin_time: #default: read from static driver
    #timestep: 1 h
    #length: 1 d
 
#radiation: false #off by default, switched on by tasks or manually
 
#chem_species: [] #empty list = disabled chemistry
 
hinterp:
    #validate: false
    #max_input_grid_error: 0.01
 
vinterp:
    # Smoothing of PALM terrain for WRF vertical interpolation to avoid sharp
    # horizontal gradients. Sigma value in grid points.
    #terrain_smoothing: off
 
postproc:
    #nox_post_sum: false
 
verbosity: 1 #can be overwritten by command-line switches -v (=2) or -s (=0)
 
# Workflow: optionally select a subset of stages
#workflow:
#    - check_config
#    - setup_model
#    - import_data
#    - hinterp
#    - vinterp
#    - write
 
######################### PLUGIN-SPECIFIC OPTIONS #########################
 
wrf:
    # Method of stretching vertical levels before vertical interpolation in
    # order to match the target (high-resolution) terrain, while limiting the
    # propagation of surface features to higher levels. May be one of:
    # universal:    A universal method where levels above transition_level are
    #               kept unmodified while the levels below are stretched
    #               gradually
    # hybrid:       Use the WRF hybrid vertical coordinate system from the
    #               WRFOUT input files to stretch the levels. WARNING: the WRF
    #               model must be configured to using hybrid levels, not sigma
    #               leves, there is no check for this!
    # sigma:        Use the WRF sigma levels system from the WRFOUT input
    #               files to stretch the levels. WARNING: the WRF model must be
    #               configured to using sigma levels, not hybrid leves, there
    #               is no check for this!
    #vertical_stretching: universal
    #transition_level: 2000.0 #m above origin_z
 
    #radiation_smoothing_distance: 10000.0
 
    rad_vars:
        #sw_tot_h: SWDOWN #may be also SWDNB
        #sw_dif_h: SWDDIF
        #lw_tot_h: GLW #may be also LWDNB
 
camx:
    # True: model grid is Lambert Conformal Conic from the coupled WRF model.
    # This uses bilinear inteprolation based on WRF-specific ellipsoid. False
    # (default): use universal triangular interpolation.
    #uses_wrf_lambert_grid: false
 
    # Python-code checks on input file variables and attributes. May also be
    # extended by individual output variables.
    #validations: []
 
    # A list of variables loaded for processing. May also be extended by
    # individual output variables.
    #loaded_vars: []
 
    # An optional preprocessing Python code on loaded variables, as triggered
    # by individual output variables.
    #preprocessors:
    #    PM25: 'PM25 = PSO4+PNO3+PNH4+POA+PEC+FPRM+SOA1+SOA2+SOA3+SOA4+SOPA+SOPB'
 
synthetic:
    #transition_level: 2000.0 #m above origin_z
 
    #prof_vars:
    #    u: {profiles: ~, heights: ~, timeseries: ~, times: ~}
    #    v: {profiles: ~, heights: ~, timeseries: ~, times: ~}
    #    w: {profiles: ~, heights: ~, timeseries: ~, times: ~}
    #    pt: {profiles: ~, heights: ~, timeseries: ~, times: ~}
    #    qv: {profiles: ~, heights: ~, timeseries: ~, times: ~}
    #    soil_t: {profiles: ~, heights: ~, timeseries: ~, times: ~}
    #    soil_m: {profiles: ~, heights: ~, timeseries: ~, times: ~}
 
    #p_surf: ~
    #p_sl: 100000.
 
aladin:
    #load_gribs: true
    #vertical_stretching: universal
    #transition_level: 2000.0 #m above origin_z
 
    #radiation_smoothing_distance: 10000.0
 
    #soil_depth_default: 0.40
    #soil_avg_point: [ 14.418540, 50.073658 ]
 
icon:
    # List of assimilation cycles specified as timedeltas after midnight UTC
    #input_assim_cycles: [0 h, 3 h, 6 h, 9 h, 12 h, 15 h, 18 h, 21 h]
 
    # First and last forecast horizon taken from each cycle. Must match
    # assimilation cycles in such a way that a full, continuous day is formed.
    # For aggregated values, the last horizon is exactly 1 timestep further.
    #input_fcst_horizon_range: [0 h, 2 h]
 
    # Distance [km] for selecting nearby grid points usable for interpolation.
    # Recommended value: original grid resolution × 3
    #point_selection_buffer: 20.0
 
    #radiation_smoothing_distance: 30.0 #km
 
    #transition_level: 2000.0 #m above origin_z
 
    # Smoothing of PALM terrain for vertical interpolation to avoid sharp
    # horizontal gradients. Sigma value in grid points.
    #terrain_smoothing: off
 
cams:
 
winddamp:
    # Distance in number of grid cells from the wall which have some wind
    # damping. Cells further from the wall will have no damping.
    #damping_dist: 2
 
    # Distance in number of grid cells from the wall which are damped to zero.
    # The next cells further from the wall have a damping factor which
    # increases linearly to 1.
    #num_zeroed: 1
 
    # Method of staggering the damping factor for the U, V and W wind
    # components by taking adjacent cells in the respective dimension.
    #stagger_method: average
    #stagger_method: minimum
 

This file may be used as a template for a new PALM-meteo configuration by uncommenting the values that the user wants to change.

Any valid options not listed in the file template.yaml are intended for developers only.

Specifying paths

The option paths.base specifies the base path for all other paths. It may be either an absolute path or a path relative to the current directory (the directory from which PALM-meteo was started). All other paths are either absolute or relative to paths.base.

Any path option may contain replacement strings in curly braces. These are used to simplify the specification of typical paths. For example, the string {domain} is (by default) replaced either with _N02, _N03 etc. or with an empty string for domain number 1, so that it represents a typical file suffix for PALM input and output files (such as the dynamic or static driver).

Even the replacement strings may be customized using the configuration section path_strings:; each item specifies a Python expression which gets evaluated as a replacement string and it may reference other configuration options.

The default configuration of paths expects a typical PALM setup: the JOBS directory placed next to the PALM-meteo instalation directory, within which there are input and output files for individual jobs. Apart from PALM's standard per-job subdirectories such as INPUT, PALM-meteo adds the subdirectory METEO with its intermediate files. In addition to that, some standard plugins expect other directories with their inputs (such as the WRF directory with WRFOUT files, unless configured otherwise).

Specifying time durations

The configuration options which expect duration (not absolute time), such as simulation.length and simulation.timestep, are specified as a number and unit, which is one of: d (days), h (hours), m (minutes) or s (seconds).

The number and unit are separated by space(s). You may also use decimal numbers or combine multiple units, so the string 1 d 3.5 h translates to 27.5 hours.