Chemistry model parameters

Steering:

Chemistry namelist
Output steering in 'runtime_parameters'
Initialisation steering in 'initialization_parameters'
test setups

---

Since Version 5.0 a chemistry model is available in PALM which computes chemical conversion and tranport of reactive trace gases. In addition, this module permits also the simulation of passive compounds in the gas phase and particulate matter.

All parts of code that are related to chemistry start with chem_. The main routines and the driver of the chemistry module is included in chemistry_model_mod.f90​, subroutines are in chem_gasphase_mod.f90, chem_photolysis_mod.f90, and chem_emissions.f90.

The module chem_gasphase_mod.f90, where the gas phase chemistry rate equations are solved within PALM-4U depends on the chosen chemical mechanism. chem_gasphase_mod.f90 is generated by a preprocessor that is based on the Kinetic Pre-Processor KPP (Damian et al., 2002, Sandu et al., 2006), Release 2.2.3 from November 2012 (​http://people.cs.vt.edu/asandu/Software/Kpp/, kpp-2.2.3.tar.gz) and an adapted version of the KPP postprocessor KP4 (Jöckel et al, 2010, ​https://www.geosci-model-dev.net/3/717/2010/). This adapted Version of KP4 which converts the KPP-generated code to a PALM-4U module is named kpp4palm.

The chemical preprocessor is located in the subdirectory UTIL/chemistry/gasphase_preproc.

Currently PALM-4U includes the following sample of chemistry mechanisms:

• cbm4: Carbon Bond Mechanism (Gery et al. 1989, 32 compounds, 81 reactions)
  
• smog: Photochemical smog mechanism (13 compounds, 12 reactions)
  
• simple: Simplified version of SMOG (9 compounds, 7 reactions)
  
• simplep: SIMPLE plus one tracer named PM10 (10 compounds, 7 real reactions plus one dummy 'reaction')
  
• phstat: Photo-stationary state (3 compounds, 2 reactions)
  

Additional 'mechanisms' are available that describe the transport of one or two passive tracers, i.e. no chemical reactions are necessary:

• passive1: Passive tracers (1 compound, 0 reactions)
  
• passive: Passive tracers (2 compounds, 0 reactions)
  

This list will be extended further in the future.

In order to select and apply a certain mechanism from this sample, please copy the repctive ready-to-use chem_gasephase_mod.f90 from UTIL/chemistry/gasphase_preproc/mechanisms/def_MECH (where MECH stands for any of the available mechanisms) into the USER_CODE directory of the respective simulation Setup, i.e. .../JOBS/<run_identifier>/USER_CODE/chem_gasphase_mod.f90.

Alternatively, the chemistry preprocessor can be executed also for the available machanism (although for the available mechanisms this is not necessary because the chem_gasphase_mod.f90 files are already existing) instead of copying chem_gasphase_mod.f90: Enter the directory UTIL/chemistry/gasphase_preproc and apply the run script, i.e. run_kpp4palm.ksh -m MECH, where MECH stands for any of the mechanisms listed above. The resulting chem_gasphase_mod.f90 will be copied directly into the SOURCE directory.

In order to find out which reactions and compounds are included in the different mechanisms, please have a look into the files MECH.eqn and MECH.spc in UTIL/chemistry/gasphase_preproc/mechanisms/def_MECH.

How to implement a new chemical mechanism or add further passive Tracers see the Readme-File. If more than two passive tracers or different names of the passive tracers are desired, a new 'mechanism' must be created as described in the Readme file. The Readme file is also available in the PALM-4U subdirectory UTIL/chemistry/gasphase_preproc.

Currently, areosol compounds can be considered either as passive compounds or the sectional aerosol module SALSA wiki/doc/app/salsa? (Kokkola et al., 2008 Atmos. Chem. Phys., 8, 2469–2483, 2008) can be used to simulate the aerosol particle concentrations, and size distributions.

Deposition processes are also taken into account in the chemistry model. The deposition of particles is derived following Zhang et al. (2001) while gases are deposited using the DEPAC model following van Zanten et al. (2010).

A main factor influencing atmospheric chemistry are the emissions of reactive compounds. In PALM-4U emissions can be applied in three different ways:

• PARAMETERIZED: Traffic emissions are parameterized depending on the the values of street_type in the static file. Emission values for each street type and chemical compound must be supplied in the namelist as described below. No other emissions are considered. street_type can be obtained from Openstreetmap.
  
• DEFAULT: Gridded yearly emissions must be supplied by the user as specified in the PIDS document (see sample emissions file). Typical temporal variations are apllied by PALM4U.
  
• PRE-PROCESSED: Preprocessed hourly (other temporal intervals will be possible in later versions) 3-d emission fields must be supplied by the user.

Importantly, for the DEFAULT and the PRE-PROCESSED mode of the emissions, the exact date of the start of the simulation must be indicated through the namelist parameter date_init of the date_and_time_mod module.

IMPORTANT: In the PRE-PROCESSED mode the initial date of the simulation has to coincide with the first day for which emission values are available.

Find a more detailed description of the PALM-4U emission input in the corresponding attached document here.

The chemistry model is automatically activated when a chemistry_parameters namelist is included in the parameter file (<run_identifier>_p3d).

---

Steering:

NAMELIST group name: chemistry_parameters

Parameter Name	FORTRAN Type	Default Value	Explanation
bc_cs_b	C*20	'dirichlet'	Bottom boundary condition of the chemical species (cs) concentration. Allowed values are 'dirichlet' (cs(k=0) = const. = cs_surface + cs_surface_initial_change; When a constant surface concentration flux is used (surface_cs_flux) or emissions are applied (do_emis = .T.), bc_cs_b = 'neumann' must be used.
bc_cs_t	C*20	'initial_gradient'	Top boundary condition of the scalar concentration. Allowed are the values 'dirichlet' (cs(k=nz+1) does not change during the run), 'neumann' (cs(k=nz+1) = cs(k=nz)), and 'initial_gradient' . With the 'initial_gradient' boundary condition the value of the scalar concentration gradient at the top is calculated from the initial scalar concentration profile (see cs_surface, cs_vertical_gradient) by: bc_cs_t_val = (cs_init(k=nz) - ss_init(k=nz-1)) / dzu(nz). Using this value (assumed constant during the run) the concentration boundary values are calculated as cs(k=nz+1) = cs(k=nz) + bc_cs_t_val * dzu(nz+1) (up to k=nz the prognostic equation for the chemical species concentration is solved). When a constant cs flux is used at the top boundary (top_csflux), bc_cs_t = 'neumann' must be used, because otherwise the resolved scale may contribute to the top flux so that a constant value cannot be guaranteed.
call_chem_at_all_substeps	L	.FALSE.	Switch whether chemistry is called at each substep of the Runge-Kutta scheme or just at each full dynamical time step 'dt'. The latter will do since the chemistry solvers are using their own timestep steering.
chem_debug0	L	.FALSE.	Extra print output of chemistry variables.
chem_gasphase_on	L	.TRUE.	Switch for switching off the chemical reactions but still doing the transport for all chemical compounds. Useful for test purposes.
cs_heights	R(99,100)	9999999.9	Height levels above ground (in m) to go with cs_profile in order to define initial profiles of chemical species. The first index refers to the chemical compound, the second to height level. Example: cs_heights(1,:) = 0.0, 5.0, 15.0, 25.0, 35.0, 45.0, 55.0, 65.0, 75.0, 85.0, 95.0, ! heights for profile of first chemical species cs_heights(2,:) = 0.0, 5.0, 15.0, 25.0, 35.0, 45.0, 55.0, 65.0, 75.0, 85.0, 95.0, ! heights for profile of second chemical species
cs_name	C*11(99)	'novalue'	Names of chemical species where surface concentrations or concentration profiles (cs_profile) are prescribed. Example: cs_name = 'O3', 'NO', 'NO2', 'CO', 'RCHO', 'PM10', 'PM25', It is not necessary to specify cs_name (and cs_surface and cs_profile/cs_heights-pairs) for all compounds of the chosen chemical mechanism. Names of compounds which do not occur mechanism are ignored.
cs_profile	R(99,100)	9999999.9	Concentration values of chemical species (gases in ppm, particulate matter in kg m-3) at cs_heights. Example: cs_profile(1,:) = 0.020, 0.023, 0.026, 0.029, 0.032, 0.035, 0.038, 0.041, 0.044, 0.047, 0.050, !Values for initial profile of first species cs_profile(2,:) = 0.080, 0.073, 0.064, 0.057, 0.050, 0.043, 0.036, 0.029, 0.022, 0.015, 0.007, !Values for initial profile of second species The individual chemical species are identified using cs_name. These initial profiles become only effective when 'set_constant_profiles' is set for initializing_actions. 'set_constant_profiles' can be combined with 'inifor' if the file from inifor contails only meteorological variables and constant profiles are only set for chemistry.
cs_surface	R	0.0	Concentration value for chemical species at the surface (gases in ppm, particulate matter in kg m-3).
daytype_mdh	C*80		Type of weekday required for the MDH (MonthDayHour?)case of the DEFAULT mode of the emissions module. Possible values are: workday, weekend, holiday
decycle_chem_lr	L	.FALSE.	Cyclic boundary conditions for chemistry may result in accumluation of chemical compounds. If decycle_chem_lr is set to true, initial concentration values are fixed at the left or right inflow boundary.
decycle_chem_ns	L	.FALSE.	Cyclic boundary conditions for chemistry may result in accumluation of chemical compounds. If decycle_chem_ns is set to true, initial concentration values are fixed at the southern or northern inflow boundary.
decycle_method	C*20(4)	'dirichlet'	Decycling method at horizontal boundaries (1=left, 2=right, 3=south, 4=north) 'dirichlet' = initial size distribution and chemical composition set for the ghost points and first three grid points 'neumann' = zero gradient
do_depo	L	.FALSE.	Switches the deposition calculation for particles and gases ON (.TRUE.) or OFF (.FALSE.)
do_emis	L	.FALSE.	Switches the chem_emission module ON (.TRUE.) or OFF (.FALSE.)
emiss_factor_main	R(99)	-9999.0	Constant emission scaling factor for MAIN street types, used in the PARAMETERIZED mode of chem_emission module. The number and the order of the values has to correspond to the names of the emission species provided for surface_csflux_name.
emiss_factor_side	R(99)	-9999.0	Constant emission scaling factor for SIDE (secondary) street types, used in the PARAMETERIZED mode of chem_emission module. The number and the order of the values has to correspond to the names of the emission species provided for surface_csflux_name.
icntrl	I(20)	0	Selection and steering of the chemistry solver. In order to offer more control over the integrator, the KPP-generated Integrator subroutine (e.g. SUBROUTINE rosenbrock in chem_gasphase_mod.f90) provides the optional input parameters ICNTRL_U and RCNTRL_U. Each of them is an array of 20 elements that allow the fine-tuning of the integrator, e.g. by setting a particular Integrator method, tolerances, minimum and maximum step sizes, etc. Note: For input parameters equal to zero the default values of the corresponding variables are used. ICNTRL(1) = 1: F = F(y) Independent of T (AUTONOMOUS), = 0: F = F(t,y) Depends on T (NON-AUTONOMOUS) ICNTRL(2) = 0: abstol, reltol are N-dimensional vectors, = 1: Abstol, Reltol are scalars ICNTRL(3) -> selection of a particular Rosenbrock method 0 : Rodas3 (Default from KPP) 1 : Ros2 (Simplest Rosenbrock solver, will also do) 2 : Ros3 3 : Ros4 4 : Rodas3 5 : Rodas4 ICNTRL(4) -> maximum number of integration steps; For ICNTRL(4) =0) the default value of 100000 is used Example: icntrl(3) = 1, ! ros2 (a bit less time consuming than the Rodas3 solver recommended by KPP) icntrl(4) = 500, ! berlin setup max. number of chem-substeps See ​http://people.cs.vt.edu/asandu/Software/Kpp/
main_street_id	I(99)	0	Index for identifying MAIN streets following street type classes from OpenStreetMap.
max_street_id	I(99)	0	Maximum index value for identifying ALL (MAIN and SIDE) streets following street type classes from OpenStreetMap.
mode_emis	C*80	'PARAMETERIZED'	Mode of chemistry emissions. Possible values are: 'DEFAULT' Input of yearly gridded emissions and MDH courses. 'PRE-PROCESSED' Input of fully preprocessed emissions at fixed time intervals (currently only hourly intervals) 'PARAMETERIZED' Parameterized traffic emissions based on street types supplied additionally in the _static input file (e.g from OpenStreetMap). At the moment the values have to be in capital letters.
my_steps	I(50)	0	List of fixed timesteps: my_step(1) = 0.0 automatic stepping Is ignored in scalar mode. Only relvant for vector mode, i.e. the vectorized Rosenbrock solvers.
nest_chemistry	L	.TRUE.	Flag for nesting mode of chemical species, independent on parent or not.
photolysis_scheme	C*10	'simple'	Currently two somple photolysis Options are available: 'constant' and 'simple' 'constant' uses photolysis frequencies at a zenith angle of 45 degrees. 'simple' describes parameterized time-dependent photolysis frequencies as supplied with MCM (​http://mcm.leeds.ac.uk/MCM, Saunders et al., 2003, Atmos. Chem. Phys., 3, 161-180 ​https://www.atmos-chem-phys.net/3/161/2003/). As the solar zenith angle must be available for this scheme, at least the simple clear sky radiation scheme must be active.
rcntrl	R(20)	0.0 and see below	Steering of the chemistry solver. RCNTRL(1) -> Hmin, lower bound for the integration step size. It is strongly recommended to keep Hmin = ZERO RCNTRL(2) -> Hmax, upper bound for the integration step size RCNTRL(3) -> Hstart, starting value for the integration step size RCNTRL(4) -> Facmin (lower bound on step decrease factor, default=0.2) RCNTRL(5) -> Facmax (upper bound on step increase factor, default=6) RCNTRL(6) -> Facrej (step decrease factor after multiple rejections) RCNTRL(7) -> Facsafe (by which the new step is slightly smaller than the predicted value, default=0.9) See ​http://people.cs.vt.edu/asandu/Software/Kpp/ Example: rcntrl(3) = 0.1, ! hstart in sec. Setting of hstart can result in savoings of computstinal time of 30% and more.
side_street_id	I(99)	0	Index for identifying SIDE streets following street type classes from OpenStreetMap?
surface_csflux	R(99)	0.0	Values of surface fluxes of chemistry emissions to be used in the PARAMETERIZED mode. The number and the order of the values has to correspond to the names of the emission species provided to surface_csflux_name. Units of the input values differ between gases and PMs. In the first case, emissions must be provided in micromole/m2*s, while for PMs, input emission values have to be in kg/m2*s.
surface_csflux_name	C*11(99)	'novalue'	Names of chemical species which are emitted. Required only for mode_emis = 'PARAMETERIZED',. Example: surface_csflux_name = 'NO', 'NO2', 'CO', 'RCHO', 'PM10', 'PM25', It is not necessary to specify surface_csflux_name for all compounds of the chosen chemical mechanism. Names of compounds which do not occur in the mechanism are ignored. Name of species can also be written in small letters. Nevertheless, the name of each species must be either in capital or in small letters.
time_fac_type	C*80	MDH	Type of time treatment for DEFAULT mode of the chem_emission module. Possible values are: HOUR or MDH

Output steering in runtime_parameters

Output of chemistry variables follows the usual output steering as described in https://palm.muk.uni-hannover.de/trac/wiki/doc/app/d3par#output.

Names of chemistry variables must be preceded by kc_'.

Example:

    data_output = 'w',  'w_av',
                  'q',  'q_av',
                  'kc_PM10', 'kc_NO2', 'kc_PM10_av', 'kc_NO2_av',

Initialisation steering in initialization_parameters

If large-scale forcings from INIFOR are used only for meteorology, then user defined initial concentration and initial vertical profiles can be activated by combining set_constant_profiles with inifor separated by a space only in the initializing_parameters namelist.

Example:

initializing_actions = 'inifor set_constant_profiles',

Test setups:

Test setups are attached here for the small test_urban setup with two passive compounds and a 1km x 1km model domain with 10 m grid width, which is centered around the Ernst-Reuter-Platz in Berlin. For this domain, example input files are supplied for two chemsitry settings:

two passive compounds ('passive')
the 'smog' mechanism

Please note that PALM-4U comes by default with the code for two passive tracers, i.e. chem_gashase_mod.f90 is prepared for 'passive'. In order to run PALM-4U with the 'smog' mechanism, copy the chem_gashase_mod.f90, which is supplied in UTIL/chemistry/gasphase_preproc/mechanisms/def_smog into SOURCE (or execute run_kpp4palm.ksh -m smog.

So far, all example setups are supplied for 'PARAMETERIZED' emissions. Example emissions files for 'PREPROCESSED' and 'DEFAULT' emissions will be supplied here at a later time.