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
    #- aladin_rad # Aladin inputs
    #- camx       # CAMx chemistry inputs
    #- cams       # CAMS chemistry inputs
    #- synthetic  # Profiles and other synthetic inputs
    #- winddamp   # Postprocessor for wind damping near walls
 
# 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.zst'
        #import_data:  'METEO/import{domain}.pickle.zst'
        #hinterp:      'METEO/hinterp{domain}.pickle.zst'
        #vinterp:      'METEO/vinterp{domain}.pickle.zst'
 
    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
 
    #geostrophic_wind: false #not available with all plugins
 
    # 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
 
    # Check minimum number of free surface canopy layers above the top of
    # terrain, buildings and plant canopy
    #nscl_free: 3
 
    # Ignore buildings in the static driver (for nscl_free and wind damping)
    #ignore_buildings: false
 
simulation:
    #origin_time: #default: read from static driver
    #timestep: 1 h
    #length: 1 d
 
    #timestep_rad: auto # default: detect from input files (if possible)
    #timestep_rad: 10 m # explicit
 
#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
 
    # Upper limit of vertical adaptation for terrain matching
    # [metres above highest obstacles]
    #transition_level: 300.0
 
    # code used for the interpolation
    #interpolator: prepared  #pure-Python interpolator with prepared weights (default)
    #interpolator: metpy     #legacy interpolator from the MetPy library (slow)
    #interpolator: fortran   #Fortran-based interpolator (fastest, must be compiled using f2py)
 
    #wind_power_law: false #off by default
    #wind_power_law: 0.147
 
postproc:
    #nox_post_sum: false
 
#verbosity: 1 #can be overwritten by command-line switches -v (=2) or -s (=0)
#log_datetime: true #prepend each log message with date+time
 
# Workflow: optionally select a subset of stages
#workflow:
#    - check_config
#    - setup_model
#    - import_data
#    - hinterp
#    - vinterp
#    - write
 
######################### PLUGIN-SPECIFIC OPTIONS #########################
 
wrf:
    # Compose continuous timeseries for the simululation using one or more
    # forecast/assimilation cycles from the set of input files
    assim_cycles:
        # Interval between assimilation cycles to be used (a larger time
        # interval can be specified in order to use every nth cycle).
        #cycles_used: 3 h    # time interval
        #cycles_used: single # use one specified cycle
        #cycles_used: all    # default: use all files, assume they are continuous
 
        # Datetime for the reference cycle from which the selected cycle
        # intervals are counted, or the selected cycle if cycles_used=single.
        # Default: 00:00 UTC from the first day of simulation.
        #reference_cycle:
 
        # Earliest horizon (time since cycle time) to be used in the
        # simulation. If set to higher than 0, the 0th file of each cycle must
        # still be available to load the level heights (HHL).
        #earliest_horizon: 0 h
 
    # Method of stretching or squeezing of the intermediate-height levels
    # before vertical interpolation in order to match the target
    # (high-resolution) terrain, while limiting the propagation of
    # surface-reltaed effects to higher levels. (Do not confuse with PALM's
    # vertically stretched grid as in dz_stretch_level and dz_stretch_factor.)
    # May be one of:
    # universal:    A universal method where levels above
    #               vinterp:transition_level are kept unmodified while the
    #               levels below are stretched/squeezed 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_adaptation: universal
 
    #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:
    #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_adaptation: universal
 
    #radiation_smoothing_distance: 10000.0
 
    #soil_depth_default: 0.40
    #soil_avg_point: [ 14.418540, 50.073658 ]
 
icon:
    # Compose continuous timeseries for the simululation using one or more
    # forecast/assimilation cycles from the set of input files
    assim_cycles:
        # Interval between assimilation cycles to be used (a larger time
        # interval can be specified in order to use every nth cycle).
        #cycles_used: 3 h    # default: time interval
        #cycles_used: single # use one specified cycle
 
        # Datetime for the reference cycle from which the selected cycle
        # intervals are counted, or the selected cycle if cycles_used=single.
        # Default: 00:00 UTC from the first day of simulation.
        #reference_cycle:
 
        # Earliest horizon (time since cycle time) to be used in the
        # simulation. If set to higher than 0, the 0th file of each cycle must
        # still be available to load the level heights (HHL).
        #earliest_horizon: 0 h
 
    # The disaggregated values (radiation) represent centres of intervals
    # between timesteps, therefore to cover the full duration of the
    # simulation, one more time interval before and after the simulation are
    # required. Enable this to allow skipping them using extrapolation.
    #allow_skip_first_disaggr: true
    #allow_skip_last_disaggr: true
 
    # 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
 
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 #default
    #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.