= Chemistry model parameters =
[[TracNav(doc/app/partoc|nocollapse)]]


'''Steering:'''
 '''[#chempar Chemistry namelist]'''\\
 '''[#output Output steering in 'runtime_parameters']'''\\
 '''[#init Initialisation steering in 'initialization_parameters']'''

----

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. 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 PALM4U 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 PALM4U 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)\\

Additionally 'mechanisms' are available that describes only the transport of one and two passive Tracers, respectively:\\
   * PASSIVE1: Passive tracers (1 compound, 0 reactions)\\
   * PASSIVE: Passive tracers (2 compounds, 0 reactions)\\
The list will be extended further. 

Ready-to-use chem_gasphase_mod.f90 files for each of the mechanisms are supplied in the subdirectories `Util/chemistry/gasphase_preproc/mechanisms/def_MECH`, where 'MECH' stands for any of the available mechanisms. 
For using a different chemical mechanism than the one that comes with checkout of PALM4U (currently PASSIVE), copy your preferred mechanism into the `SOURCE`directory. 

For details about preparing a chem_gasphase_mod.f90 from scratch see `Readme_KPP4PALM.odt` in the PALM4U subdirectory `UTIL/chemistry/gasphase_preproc`. 

A main factor influencing atmospheric chemistry are the emissions of reactive compounds. In PALM4U 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 beow. 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.\\
    * PREPROCESSED: Preprocessed hourly (other temporal intervals will be possible in later versions) 3-d emission fields must be supplied by the user.
    

Chemistry is automatically activated when a {{{chemistry_parameters}}} namelist is set in the parameter file ({{{_p3d}}}). 


A brief description of the chemistry model will follow here (see [wiki:doc/app/lsmpar#LandSurfaceParameters LSM description] as an example).

\\\\
NAMELIST group name: [=#chempar '''chemistry_parameters''']\\


----
\\\\
[=#steering '''Steering:]\\
||='''Parameter Name'''  =||='''[[../fortrantypes|FORTRAN]]\\[[../fortrantypes|Type]]'''  =||='''Default\\Value'''  =||='''Explanation'''  =||
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#bc_cs_b '''bc_cs_b''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
C*20
}}}
{{{#!td style="vertical-align:top; width: 75px"
'dirichlet'
}}}
{{{#!td
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. 
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#bc_cs_t '''bc_cs_t''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
C*20
}}}
{{{#!td style="vertical-align:top; width: 75px"
'initial_gradient'
}}}
{{{#!td
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.
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#call_chem_at_all_substeps '''call_chem_at_all_substeps''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
L
}}}
{{{#!td style="vertical-align:top; width: 75px"
.FALSE.
}}}
{{{#!td
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.
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#chem_debug0 '''chem_debug0 ''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
L
}}}
{{{#!td style="vertical-align:top; width: 75px"
.FALSE.
}}}
{{{#!td
Extra print output of chemistry variables. 
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#chem_gasphase_on '''chem_gasphase_on''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
L
}}}
{{{#!td style="vertical-align:top; width: 75px"
.TRUE.
}}}
{{{#!td
Switch for switching off the chemical reactions but still doing the transport for all chemical compounds. Useful for test purposes.
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#cs_heights '''cs_heights''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
R(99,100)
}}}
{{{#!td style="vertical-align:top; width: 75px"
9999999.9_wp
}}}
{{{#!td
Height levels above ground (in m) to go with [#cs_profile 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\\
The chem
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#cs_name '''cs_name''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
C*11(99)
}}}
{{{#!td style="vertical-align:top; width: 75px"
'novalue'
}}}
{{{#!td
Names of chemical species where surface concentrations or profiles 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.
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#cs_profile '''cs_profile''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
R(99,100)
}}}
{{{#!td style="vertical-align:top; width: 75px"
9999999.9_wp
}}}
{{{#!td
Concentration values of chemical species (gases in ppm, particulate matter in kg m^-3^) at [#cs_heights 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 cs_name]
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#cs_surface '''cs_surface''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
R
}}}
{{{#!td style="vertical-align:top; width: 75px"
0.0
}}}
{{{#!td
Concentration value for chemical species at the surface (gases in ppm, particulate matter in kg m^-3^).

}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#cs_surface_initial_change '''cs_surface_initial_change''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
Not required. Copied from passive scalar. We can use emissions instead, so no idea what it is still good for.
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#cs_vertical_gradient '''cs_vertical_gradient''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
Not used, as we set initial values of cs by specifying values at given heights, not vertical gradients
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#cs_vertical_gradient_level '''cs_vertical_gradient_level''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
dto
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#daytype_mdh '''daytype_mdh''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
C*80
}}}
{{{#!td style="vertical-align:top; width: 75px"

}}}
{{{#!td
Type of weekday required for the MDH case of the DEFAULT mode of the emissions module.
Possible values are: workday, weekend, holiday
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#decycle_chem_lr '''decycle_chem_lr''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#decycle_chem_ns '''decycle_chem_ns''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
L
}}}
{{{#!td style="vertical-align:top; width: 75px"
.FALSE.
}}}
{{{#!td
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 boundary.
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#decycle_method '''decycle_method''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
C*20(4)
}}}
{{{#!td style="vertical-align:top; width: 75px"
'dirichlet'
}}}
{{{#!td
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
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#do_emis '''do_emis''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
L
}}}
{{{#!td style="vertical-align:top; width: 75px"
.FALSE.
}}}
{{{#!td
Switches the chem_emission module ON (.TRUE.) or OFF (.FALSE.)
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#emiss_factor_main '''emiss_factor_main''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#emiss_factor_side '''emiss_factor_side''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#icntrl '''icntrl''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
I(20)
}}}
{{{#!td style="vertical-align:top; width: 75px"
0
}}}
{{{#!td
Selection and steering of the chemistry solver. 

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)
         1 :    Ros2
         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

See http://people.cs.vt.edu/asandu/Software/Kpp/
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#main_street_id '''main_street_id''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#max_street_id '''max_street_id''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#mode_emis '''mode_emis''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
C*80
}}}
{{{#!td style="vertical-align:top; width: 75px"
PARAMETERIZED
}}}
{{{#!td
Mode of chemistry emissions.
Possible values are: DEFAULT, EXPERT and PARAMETERIZED (at the moment the values have to be in capital letters)
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#my_steps '''my_steps''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#nest_chemistry '''nest_chemistry''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#photolysis_scheme '''photolysis_scheme''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#rcntrl '''rcntrl''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
R(20)
}}}
{{{#!td style="vertical-align:top; width: 75px"
0.0 and see below
}}}
{{{#!td
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/
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#side_street_id '''side_street_id''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#surface_csflux '''surface_csflux''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
R(99)
}}}
{{{#!td style="vertical-align:top; width: 75px"
0.0
}}}
{{{#!td
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/m^2*s,
while for PMs, input emission values have to be in kg/m^2*s.
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#surface_csflux_name '''surface_csflux_name''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
C*11(99)
}}}
{{{#!td style="vertical-align:top; width: 75px"
'novalue'

}}}
{{{#!td
Names of chemical species which are emitted. Required only for  [#mode_emis 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.
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#time_fac_type '''time_fac_type''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#top_csflux '''top_csflux''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------
{{{#!td style="vertical-align:top; width: 150px"
[=#wall_csflux '''wall_csflux''']
}}}
{{{#!td style="vertical-align:top; width: 50px"
XXX
}}}
{{{#!td style="vertical-align:top; width: 75px"
YYY
}}}
{{{#!td
ZZZ
}}}
|----------------

 [=#output Output steering in `runtime_parameters`]

 [=#init Initialisation steering in `initialization_parameters`]