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
    #- plot       # Generates plots with time-series of vertical profiles
 
# 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_mask:      'CAMS/**/*.nc'
 
    plot:
        #output_dir:     'METEO'
 
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
 
    # Manual shift of terrain in metres. This should be equal to min(zt) of all
    # domains. It is better to generate static drivers with such origin_z that
    # min(zt) of all domains is 0.
    #terrain_offset: 0    #default
    #terrain_offset: auto #calculate from min(zt), only valid for single domain cases
 
    # 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
 
    # Approximation used in PALM. This must match PALM's setting, otherwise
    # mass balancing will be off!
    #approximation: boussinesq #default in pmeteo as well as in PALM
    #approximation: anelastic
 
radiation:
    #enabled: false #off by default, switched on by tasks or manually
 
    #timestep: auto #default: detect from input files (if possible)
    #timestep: 10 m #explicit
 
    # Configure when using external radiation also for spinup (PALM default for
    # spinup is clearsky).
    #spinup_length: 0 h
 
#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
 
compute:
    #nthreads: 1 #number of parallel threads (currently in fortran vinterp)
 
#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:
    #        # The list of vertical profiles of the given quantity, either one
    #        # profile for values constant in time or more as timesteps within
    #        # timeseries
    #        profiles: ~
 
    #        # List of heights of the vertical profile points (m above origin_z)
    #        heights: ~
 
    #        # If specified, allows arbitrary permutation or repetition of
    #        # timesteps from "profiles" (using order numbers starting from 0).
    #        # If unspecified, the profiles are taken sequentially, starting
    #        # over from the first one if there is less of them than "times".
    #        timeseries: ~
 
    #        # Time points for the timeseries. This may be omitted if there is
    #        # exactly one profile (constant in time).
    #        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: ~ #pressure at origin_z (default: calculate from p_sl)
    #p_sl: 100000. #sea level pressure for p_surf calculation
 
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:
    # 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
 
    varnames:
        #latitude: latitude
        #longitude: longitude
 
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
 
plot:
    # List of horizontal positions for which to plot vertical profiles as
    # time-series.
    #positions:
    #    - name: center  #prefix for output files
    #      xpos: 50%     #specified either as grid point (no suffix), distance
    #                    #from origin (suffix m), domain relative (suffix %) or
    #                    #degrees lat/lon (suffix N/E/S/W, may contain °'")
    #      ypos: 50%     #dtto
    #      vars:
    #          # Special variables:
    #          - wind    #wind (plotted as speed + direction)
    #          - temp    #air temperature (plotted as potential + absolute)
    #          # All other named variables from IBC:
    #          - qv      #water vapor mixing ratio
 
    # Fully qualified names of colormaps used for the plots by type. Defaults
    # require only standard matplotlib, recommended are from colorcet.
    colormaps:
        #default: matplotlib.cm.viridis #Default from matplotlib
        #default: colorcet.m_bmy        #Better
        #zero_based: matplotlib.cm.inferno #Default from matplotlib
        #zero_based: colorcet.m_fire       #Better
        #wind_direction: matplotlib.cm.twilight #Default from matplotlib
        #wind_direction: colorcet.m_colorwheel  #Better
 
    #format: png #default
    #format: pdf
 
    #dpi: 300 #also determines sizes for raster outputs

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.