PALM-meteo: PALM-meteo configuration

PALM-meteo

PALM-meteo configuration

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.