geoschem_config.yml
Starting with GEOS-Chem 14.0.0, the input.geos
configuration
file (plain text) has been replaced with by the
geoschem_config.yml
file. This file is in YAML format, which is a text-based markup syntax used
for representing dictionary-like data structures.
The geoschem_config.yml
file contains several sections. Only
The sections relevant to a given type of simulation are present. For
example, fullchem
simulation options (such as aerosol
settings and photolysis settings) are omitted from the
geoschem_config.yml
file for the CH4
simulation.
Note
Settings that are not relevant to GCHP will be excluded from the
geoschem_config.yml
file that ships with the GCHP run
directory. We will note these excluded settings below. All other
settings in geoschem_config.yml
will be treated in
in the same way as in GEOS-Chem Classic.
Simulation settings
#============================================================================
# Simulation settings
#============================================================================
simulation:
name: fullchem
start_date: [20190701, 000000]
end_date: [20190801, 000000]
root_data_dir: /path/to/ExtData
met_field: MERRA2
species_database_file: ./species_database.yml
species_metadata_output_file: OutputDir/geoschem_species_metadata.yml
verbose:
activate: false
on_cores: root # Allowed values: root all
use_gcclassic_timers: false
The simulation
section contains general simulation options:
- name
Specifies the type of GEOS-Chem simulation. Accepted values are
- fullchem
Full-chemistry simulation.
- aerosol
- carbon
Coupled carbon gases simulation (CH4-CO-CO2-OCS), implemented as a KPP mechanism (cf Bukosa et al. [2023]).
You must configure your build with with
-DMECH=carbon
in order to use this simulation. For more information, please see:
- Hg
-
You must configure your build with with
-DMECH=Hg
in order to use this simulation. For more information, please see:
- POPs
Persistent organic pollutants (aka POPs) simulation.
Attention
The POPs simulation is currently stale. We look to members of the GEOS-Chem user community take the lead on updating this simulation.
- tagCH4
Methane simulation with species tagged by geographic region or other criteria.
This simulation will eventually be superseded by the
carbon
simulation.
- tagCO
Carbon dioxide simulation, with species tagged by geographic region and other criteria.
This simulation will eventually be superseded by the
carbon
simulation.
- tagO3
Ozone simulation (using specified production and loss rates), with species tagged by geographical region.
- TransportTracers
Transport Tracers simulation, with both radionuclide and passive_species. Useful for evaluating model transport.
- metals
Trace metals simulation
- start_date
Note
This option is omitted for GCHP. The simulation start date is specified in the
CAP.rc
andcap_restart
files.Specifies the starting date and time of the simulation in list notation
[YYYYMMDD, hhmmss]
.
- end_date
Note
This option is omitted for GCHP. Duration is specified in the
cap_restart
file.Specifies the ending date and time of the simulation in list notation
[YYYYMMDD, hhmmss]
.
- root_data_dir
Note
This option is omitted for GCHP. All data paths (with the exception of the aerosol optics and photolysis paths) are specified in the
ExtData.rc
file.Path to the root data directory. All of the data that GEOS-Chem Classic reads must be located in subfolders of this directory.
- met_field
Note
This option is omitted for GCHP. Met field source is described in file paths of the in the
ExtData.rc
file.Name of the meteorology product that will be used to drive GEOS-Chem. Accepted values are:
- MERRA2
The MERRA-2 meteorology product from NASA/GMAO. MERRA-2 is a stable reanalysis product, and extends from approximately 1980 to present. (Recommended option)
- GEOS-FP
The GEOS-FP meteorology product from NASA/GMAO. GEOS-FP is an operational data product and, unlike MERRA-2, periodically receives science updates.
- GCAP2
The GCAP-2 meteorology product, archived from the GISS-2 GCM. GCAP-2 has hundreds of years of data available, making it useful for simulations of historical climate.
- species_database_file
Path to the GEOS-Chem Species Database file. This is stored in the run directory file
./species_database.yml
. You should not have to edit this setting.
- species_metadata_output_file
Path to the
geoschem-species-metadata.yml
file. This file contains echoback of information from species_database.yml, but only for species that are defined in this simulation (instead of all possible species). This facilitates interfacing GEOS-Chem with external models such as CESM.
- verbose:
Menu controlling verbose printout. Starting with GEOS-Chem 14.2.0 and HEMCO 3.7.0, most informational printouts are now deactivated by default. You may choose to activate them (e.g. for debugging and/or testing) with the options below:
- activate
Activates (
true
) or deactivates (false
) printing extra informational printout to the screen and/or log file.
- on_cores:
Specify on which computational cores informational printout should be done.
- root
Print extra informational output only on the root core. Use this setting for GEOS-Chem Classic.
- all
Print extra informational output on all cores. Consider using this when using GEOS-Chem as GCHP, or in MPI-based external models (NASA GEOS, CESM, etc.).
- use_gcclassic_timers
Note
This setting is omitted for GCHP, as the MAPL library provides all timer functionality.
Activates (
true
) or deactivates (false
) the GEOS-Chem Classic timers. If activated, information about how long each component of GEOS-Chem Classic took to execute will be printed to the screen and/or the log file The same information will also be written in JSON format to a file named gcclassic_timers.json.You can set this option to
false
unless you are running benchmark or timing simulations.
Grid settings
Note
Grid settings are omitted for GCHP. Grid specifications are
contained in the GCHP.rc
file instead.
#============================================================================
# Grid settings
#============================================================================
grid:
resolution: 4.0x5.0
number_of_levels: 72
longitude:
range: [-180.0, 180.0]
center_at_180: true
latitude:
range: [-90.0, 90.0]
half_size_polar_boxes: true
nested_grid_simulation:
activate: true
buffer_zone_NSEW: [0, 0, 0, 0]
The grid
section contains settings that define the grid used
by GEOS-Chem Classic:
- resolution
Specifies the horizontal resolution of the grid. Accepted values are:
- 4.0x5.0
The global \(4^{\circ}{\times}5^{\circ}\) GEOS-Chem Classic grid.
- 2.0x2.5
The global \(2.0^{\circ}{\times}2.5^{\circ}\) GEOS-Chem Classic grid.
- number_of_levels
Number of vertical levels to use in the simulation. Accepted values are:
- longitude
Settings that define the longitude dimension of the grid. There are two sub-options:
- range
The minimum and maximum longitude values (grid box edges), specified in list format.
- center_at_180
If
true
, then westernmost grid boxes are centered at \(-180^{\circ}\) longitude (the International Date Line). This is true for bothMERRA2
andGEOS-FP
.If
false
, then the westernmost grid boxes have their westernmost edges at \(-180^{\circ}\) longitude. This is true for theGCAP2
grid.
- latitude
Settings to define the latitude dimension of the grid. There are two sub-options:
- range
The minimum and maximum latitude values (grid box edges), specified in list format.
- nested_grid_simulation
Settings for nested-grid simulations. There are two sub-options:
- activate
If
true
, this indicates that the simulation will use a sub-window of the horizontal grid.If
false
, this indicates that the simulation will use the entire global grid extent.
- buffer_zone_NSEW
Specifies the nested grid latitude offsets (# of grid boxes) in list format
[N-offset, S-offset, E-offset, W-offset]
. These offsets are used to define an inner window region in which transport is actually done (aka the “transport window”). This “transport window” is always smaller than the actual size of the nested grid region in order to properly account for the boundary conditions.
For global simulations, use:
[0, 0, 0, 0]
.For nested-grid simulations, we recommend using:
[3, 3, 3, 3]
.
Timesteps settings
Note
Timesteps settings are omitted for GCHP. Timesteps are specified
in the CAP.rc
file.
#============================================================================
# Timesteps settings
#============================================================================
timesteps:
transport_timestep_in_s: 600
chemistry_timestep_in_s: 1200
radiation_timestep_in_s: 10800
The timesteps
section specifies the frequency at which
various GEOS-Chem operations occur.
The table below contains our recommended GEOS-Chem Classic timestep settings.
GEOS-Chem Classic Resolution |
Transport |
Chemistry |
---|---|---|
\(4^{\circ}{\times}5^{\circ}\) |
600s (10m) |
1200s (20m) |
\(2^{\circ}{\times}2.5^{\circ}\) |
600s (10m) |
1200s (20m) |
\(0.5^{\circ}{\times}0.625^{\circ}\) |
300s (5m) |
600s (10m) |
\(0.25^{\circ}{\times}0.3125^{\circ}\) |
300s (5m) |
600s (10m) |
\(0.125^{\circ}{\times}0.15625^{\circ}\) |
150s (2.5m) |
300s (5m) |
The Courant limit on the latitude-longitude grid constrains the choice of transport timestep for a given horizontal resolution. We choose a chemistry timestep that is double the transport timestep (i.e. Strang operator splitting).
Note
GCHP, which uses the FVdycore advection scheme on the cubed-sphere grid, does not have similar restrictions for timesteps.
See Philip et al. [2016] for a comprehensive study on GEOS-Chem timesteps. For some practical tips on speeding up your simulations, see:
- transport_timestep_in_s
Specifies the “heartbeat” timestep of GEOS-Chem.. This is the frequency at which transport, cloud convection, PBL mixing, and wet deposition will be done.
- chemistry_timestep_in_s
Specifies the frequency at which chemistry and emissions will be done.
Operations settings
This section of geoschem_config.yml
is included for all
simulations. However, some of the options listed below will be omitted for
simulations that do not require them.
There are several sub-sections under operations
:
Chemistry
#============================================================================
# Settings for GEOS-Chem operations
#============================================================================
operations:
chemistry:
activate: true
linear_chemistry_aloft:
activate: true
use_linoz_for_O3: true
active_strat_H2O:
activate: true
use_static_bnd_cond: true
gamma_HO2: 0.2
autoreduce_solver:
activate: false
use_target_threshold:
activate: true
oh_tuning_factor: 0.00005
no2_tuning_factor: 0.0001
use_absolute_threshold:
scale_by_pressure: true
absolute_threshold: 100.0
keep_halogens_active: false
append_in_internal_timestep: false
# ... following sub-sections omitted ...
The operations:chemistry
section contains settings for chemistry:
- activate
Activates (
true
) or deactivates (false
) chemistry in GEOS-Chem.
- linear_chemistry_aloft
Determines how linearized chemistry will be applied in the stratosphere and/or mesosphere. (Only valid for
fullchem
simulations).There are two sub-options:
- activate
Activates (
true
) or deactivates (false
) linearized stratospheric chemistry in the stratosphere and/or mesosphere.
- use_linoz_for_O3
If
true
, Linoz stratospheric ozone chemistry will be used.If
false
, Synoz (i.e. a synthetic flux of ozone across the tropopause) will be used instead of Linoz.
- active_strat_H2O
Determines if water vapor as modeled by GEOS-Chem will be allowed to influence humidity fields. (Only valid for
fullchem
simulations)There are two sub-options:
- activate
Allows (
true
) or disallows (false
the H2O species in GEOS-Chem to influence specific humidity and relative humidity.
- use_static_bnd_cond
Allows (
true
) or diasallows (false
) a static boundary condition.TODO Clarify this
- gamma_HO2
Specifies \(\gamma\), the uptake coefficient for \(HO_2\) heterogeneous chemistry.
Recommended value:
0.2
.
- autoreduce_solver
Menu for controlling the adaptive mechanism auto-reduction feature, which is available in KPP 3.0.0. and later versions. See Lin et al. [2023] for details.
- activate
If
true
, the mechanism will be integrated using the Rosenbrock method with the adaptive auto-reduction feature.If
false
, the mechanism will be integrated using the traditional Rosenbrock method.Default value:
false
.
- use_target_threshold
Contains options for defining \(\partial\) (the partitioning threshold between “fast” and “slow” species”) by considering the production and loss of key species (OH for daytime, NO2 for nighttime).
- activate
Activates (
true
) or deactivates (false
) using OH and NO2 to determine \(\partial\).Default value:
true
.
- oh_tuning_factor
Specifies \({\alpha}_{OH}\), which is used to compute \(\partial\).
- no2 tuning factor
Specifies \({\alpha}_{NO2}\), which is used to compute \(\partial\).
- use_pressure_threshold
Contains options for setting an absolute threshold \(\partial\) that may be weighted by pressure.
- scale_by_pressure
Activates (
true
) or deactivates (false
) using a pressure-dependent method to determine \(\partial\).
- absolute_threshold
The absolute partitioning threshold \(\partial\).
If
scale_by_pressure
istrue,
anduse_target_threshold:activate
isfalse
, the value for \(\partial\) specified here will be scaled by the ratio \(P / P_{sfc}\). where \(P\) is the grid box pressure and \(P_{sfc}\) is the surface pressure for the column.
- keep_halogens_active
If
true
, then all halogen species will be considered “fast”. This may be necessary in order to obtain realistic results for ozone and other important species.If
false
, then halogen species will be determined as “slow” or “fast” depending on the partitioning threshold \(\partial\).Default value:
true
- append_in_internal_timestep
If
true
, any “slow” species that later become “fast” will be appended to the list of “fast” species.If
false
, any “slow” species that later become “fast” will NOT be appended to the list of “fast” species.Default value:
false
Convection
#============================================================================
# Settings for GEOS-Chem operations
#============================================================================
operations:
# .. preceding sub-sections omitted ...
convection:
activate: true
# ... following sub-sections omitted ...
The operations:convection section contains settings for cloud convection:
- activate
Activates (
true
) or deactivates (false
) cloud convection in GEOS-Chem.
Dry deposition
#============================================================================
# Settings for GEOS-Chem operations
#============================================================================
operations:
# .. preceding sub-sections omitted ...
dry_deposition:
activate: true
CO2_effect:
activate: false
CO2_level: 600.0
reference_CO2_level: 380.0
diag_alt_above_sfc_in_m: 10
# ... following sub-sections omitted ...
The operations:dry_deposition
section contains settings that
for dry deposition:
- activate
Activates (
true
) or deactivates (false
) dry deposition.
- CO2_effect
This sub-section contains options for applying the simple parameterization for the CO2 effect on stomatal resistance.
- activate
Activates (
true
) or deactivates (false
) the CO2 effect on stomatal resistance in dry deposition.Default value:
false
.
- CO2_level
Specifies the CO2 level (in ppb).
- reference_CO2_level
Specifies the reference CO2 level (in ppb).
- diag_alt_above_sfc_in_m:
Specifies the altitude above the surface (in m) to used with the ConcAboveSfc diagnostic collection.
PBL mixing
#============================================================================
# Settings for GEOS-Chem operations
#============================================================================
operations:
# .. preceding sub-sections omitted ...
pbl_mixing:
activate: true
use_non_local_pbl: true
# ... following sub-sections omitted ...
The operations:pbl_mixing
section contains settings that
for planetary boundary layer (PBL) mixing:
- activate
Activates (
true
) or deactivates (false
) planetary boundary layer mixing in GEOS-Chem Classic.
- use_non_local_pbl
If
true
, then the non-local PBL mixing scheme (VDIFF) will be used. (Default option)If
false
, then the full PBL mixing scheme (TURBDAY) will be used.
Photolysis
#============================================================================
# Settings for GEOS-Chem operations
#============================================================================
operations:
# .. preceding sub-sections omitted ...
photolysis:
activate: true
cloud-j:
num_levs_with_cloud: 34
cloud_scheme_flag: 3
opt_depth_increase_factor: 1.050
min_top_inserted_cloud_OD: 0.005
cloud_overlap_correlation: 0.33
num_cloud_overlap_blocks: 6
sphere_correction: 1
num_wavelength_bins: 18
use_H2O_UV_absorption: true
input_directories:
fastjx_input_dir: /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2024-05/
cloudj_input_dir: /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/
overhead_O3:
use_online_O3_from_model: true
use_column_O3_from_met: true
use_TOMS_SBUV_O3: false
photolyze_nitrate_aerosol:
activate: true
NITs_Jscale: 100.0
NIT_Jscale: 100.0
percent_channel_A_HONO: 66.667
percent_channel_B_NO2: 33.333
# ... following sub-sections omitted ...
The operation:photolysis
section contains settings for photolysis.
This section only applies to fullchem, Hg, and aerosol-only simulations.
- activate
Activates (
true
) or deactivates (false
) photolysis.Attention
You should always keep photolysis turned on in your simulations. Disabling photolysis should only be done when debugging.
- cloud-j:
Specifies various options for the Cloud-J photolysis package.
Note
The Cloud-J settings have been preset to the recommended values. You should not need to modify these settings (unless you are investigating how aerosol and cloud interactions impact photolysis).
- num_levs_with_cloud
Specifies the number of levels that can contain clouds, which is a required input for the Cloud-J photolysis module. This value is pre-set to the proper value for the vertical grid that your simulation will use.
GEOS-Chem variable:
Input_Opt%NLevs_Phot_Cloud
Cloud-J variable
LWEPAR
- cloud_scheme_flag
Specifies the cloud option used in the computation of photolyis rates.
GEOS-Chem variable:
Input_Opt%CLDFLAG
Cloud-J variable
LWEPAR
- opt_depth_increase_factor
Specifies the factor increase in cloud optical depth from a given layer to the layer below.
GEOS-Chem variable:
Input_Opt%OD_Increase_Factor
Cloud-J variable
ATAU
- min_top_inserted_cloud_OD
Specifies the minimum cloud OD in the uppermost inserted layer.
GEOS-Chem variable:
Input_Opt%Min_Cloud_OD
Cloud-J variable
ATAU0
- cloud_overlap_correlation
Specifies the cloud de-corellation between max-overlap blocks, where 0.00 is random overlap. This option is only used when
cloud_scheme_flag
is set to 5 or higher.GEOS-Chem variable:
Input_Opt%Cloud_Corr
Cloud-J variable
CLDCOR
- num_cloud_overlap_blocks
Specifies the number of maximum-overlap blocks.
GEOS-Chem variable:
Input_Opt%Num_Max_Overlap
Cloud-J variable
LNRG
- sphere_correction
Specifies the type of spherical correction to be applied.
GEOS-Chem variable:
Input_Opt%OD_Increase_Factor
Cloud-J variable
ATM0
- num_wavelength_bins
Specifies the number of wavelength bins to use in the computation of photolysis reaction rates.
GEOS-Chem variable:
Input_Opt%Num_WV_Bins
Cloud-J variable
ATM0
- use_H2O_UV_absorption
Specifies whether to enable (
true
) or disable (false
) UV absorption of water vapor in the computations for photolysis rates. Default value:true
.GEOS-Chem variable:
Input_Opt%Use_H2O_UV_Abs
Cloud-J variable
USEH2OUV
- input_directories
Specifies the location of directories containing photolysis configuration files.
- fastjx_input_dir
Specifies the path to the legacy FAST_JX configuration files containing information about species cross sections and quantum yields. These are used to define several aerosol optical properties even when FAST-JX is not used.
Note that FAST-JX is off by default and Cloud-J is used instead. You can use legacy FAST-JX instead of Cloud-J by configuring with
-DFASTJX=y
during build.
- cloudj_input_dir
Specifies the path to the Cloud-J configuration files containing information about species cross sections and quantum yields.
- overhead_O3
This section contains settings that control which overhead ozone sources are used for photolysis
- use_online_O3_from_model
Activates (
true
) or deactivates (false
) using online O3 from GEOS-Chem in the extinction calculations for photolysis.Recommended value:
true
- use_column_O3_from_met
Activates (
true
) or deactivates (false
) using ozone columns (e.g. TO3) from the meteorology fields.Recommended value:
true
.
- use_TOMS_SBUV_O3
Activates (
true
) or deactivates (false
) using ozone columns from the TOMS-SBUV archive will be used.Recommended value:
false
.
- photolyze_nitrate_aerosol
This section contains settings that control options for nitrate aerosol photolysis.
- activate
Activates (
true
) or deactivates (false
) nitrate aerosol photolysis.Recommended value:
true
.
- NITs_Jscale
Scale factor (percent) for JNO3 that photolyzes NITs aerosol.
- NIT_Jscale
Scale factor (percent) for JHNO2 that photolyzes NIT aerosol.
- percent_channel_A_HONO
Fraction of JNITs/JNIT in channel A (HNO2) for NITs photolysis.
- percent_channel_B_HO2
Fraction of JNITs/JNIT in channel B (NO2) for NITs photolysis.
RRTMG radiative transfer model
#============================================================================
# Settings for GEOS-Chem operations
#============================================================================
operations:
# .. preceding sub-sections omitted ...
rrtmg_rad_transfer_model:
activate: false
aod_wavelengths_in_nm:
- 550
longwave_fluxes: false
shortwave_fluxes: false
clear_sky_flux: false
all_sky_flux: false
fixed_dyn_heating: false
seasonal_fdh: false
read_dyn_heating: false
co2_ppmv: 390.0
# .. following sub-sections omitted ...
The operations:rrtmg_rad_transfer_model
section contains
settings for the RRTMG radiative transfer model:
This section only applies to fullchem
simultions.
- activate
Activates (
true
) or deactivates (false
) the RRTMG radiative transfer model.Default value:
false
.
- aod_wavelengths_in_nm
Specify wavelength(s) for the aerosol optical properties in nm (in YAML sequence format) Up to three wavelengths can be selected. The specified wavelengths are used for the photolysis mechanism (either legacy FAST-JX or Cloud-J) regardless of whether the RRTMG radiative transfer model is used.
- longwave_fluxes
Activates (
true
) or deactivates (false
) RRTMG longwave flux calculations.Default value:
false
.
- shortwave_fluxes
Activates (
true
) or deactivates (false
) RRTMG shortwave calculations.Default value:
false
.
- clear_sky_flux
Activates (
true
) or deactivates (false
) RRTMG clear-sky flux calculations.Default value:
false
.
- all_sky_flux
Activates (
true
) or deactivates (false
) RRTMG all-sky flux calculations.Default value:
false
.
- fixed_dyn_heating
Activates (
true
) or deactivates (false
) fixed dynamic heating (FDH) approximation as described by Forster et al. [1997].Default value:
false
.
- seasonal_fdh
Activates (
true
) or deactivates (false
) seasonally-evolving fixed dynamic heating (SEFDH) approzimation as described by Kiehl et al. [1999].Attention
This option has not been extensively tested, and is considered experimental.
Default value:
false
.
- read_dyn_heating
Activates (
true
) or deactivates (false
) reading previously-archived dynamical heating outputs from disk.Default value:
false
.
- co2_ppmv
Specify the value of CO2 [in parts per million by volume] to be used in radiative forcing calculations.
Default value:
390.0
.
Transport
#============================================================================
# Settings for GEOS-Chem operations
#============================================================================
operations:
# .. preceding sub-sections omitted ...
transport:
gcclassic_tpcore: # GEOS-Chem Classic only
activate: true # GEOS-Chem Classic only
fill_negative_values: true # GEOS-Chem Classic only
iord_jord_kord: [3, 3, 7] # GEOS-Chem Classic only
transported_species:
- ACET
- ACTA
- AERI
# ... etc more transported species ...
# .. following sub-sections omitted ...
The operations:transport
section contains
settings for species transport:
- gcclassic_tpcore
Note
These settings are omitted for GCHP, which uses the FVdycore advection package instead.
Contains options that control species transport in GEOS-Chem Classic with the TPCORE advection scheme:
- activate
Activates (
true
) or deactivates (false
) species transport in GEOS-Chem Classic.Default value:
true
.
- fill_negative_values
If
true
, negative species concentrations will be replaced with zeros.If
false
, no change will be made to species concentrations.Default value:
true
.
- iord_jord_kord
Specifies advection options (in list format) for TPCORE in the longitude, latitude, and vertical dimensions. The options are listed below:
1st order upstream scheme (use for debugging only)
2nd order van Leer (full monotonicity constraint)
Monotonic PPM
Semi-monotonic PPM (same as 3, but overshoots are allowed)
Positive-definite PPM
Un-constrained PPM (use when fields & winds are very smooth) this option only when the fields and winds are very smooth.
Huynh/Van Leer/Lin full monotonicity constraint (KORD only)
Default (and recommended) value:
[3, 3, 7]
- transported_species
A list of species names (in YAML sequence format) that will be transported by the TPCORE advection scheme.
Wet deposition
#============================================================================
# Settings for GEOS-Chem operations
#============================================================================
operations:
# .. preceding sub-sections omitted ...
wet_deposition:
activate: true
The operations:wet_deposition
section contains settings
for wet deposition.
- activate
Activates (
true
) or deactivates (false
) wet deposition in GEOS-Chem Classic.
Aerosols settings
This section of geoschem_config.yml
is included for
fullchem
and aerosol
simulations.
There are several sub-sections under aerosols
:
Optics
#============================================================================
# Settings for GEOS-Chem aerosols
#============================================================================
aerosols:
optics:
input_dir: /path/to/ExtData/CHEM_INPUTS/Aerosol_Optics/v2024-08/
# .. following sub-sections omitted ...
Carbon aerosols
#============================================================================
# Settings for GEOS-Chem aerosols
#============================================================================
aerosols:
# ... preceding sub-sections omitted ...
carbon:
activate: true
brown_carbon: false
enhance_black_carbon_absorption:
activate: true
hydrophilic: 1.5
hydrophobic: 1.0
# .. following sub-sections omitted ...
The aerosols:carbon
section contains settings for
carbon aerosols:
- activate
Activates (
true
) or deactivates (false
) carbon aerosols in GEOS-Chem.Default value:
true
.
- brown_carbon
Activates (
true
) or deactivates (false
) brown carbon aerosols in GEOS-Chem.Default value:
false
.
- enhance_black_carbon_absorption
Options for enhancing the absorption of black carbon aerosols due to external coating.
- activate
Activates (
true
) or deactivates (false
) black carbon absorption enhancement.Default value:
true
.
- hydrophilic
Absorption enhancement factor for hydrophilic black carbon aerosol (species name BCPI).
Default value:
1.5
- hydrophobic
Absorption enhancement factor for hydrophilic black carbon aerosol (species name BCPO).
Default value:
1.0
Complex SOA
The aerosols:complex_SOA
section contains settings for
the complex SOA scheme used in GEOS-Chem.
#============================================================================
# Settings for GEOS-Chem aerosols
#============================================================================
aerosols:
# ... preceding sub-sections omitted ...
complex_SOA:
activate: true
semivolatile_POA: false
# ... following sub-sections omitted ...
- activate
Activates (
true
) or deactivates (false
) the complex SOA scheme.Default value:
- semivolatile_POA
Activates (
true
) or deactivates (false
) the semi-volatile primary organic aerosol (POA) option.Default value:
false
Mineral dust aerosols
The aerosols:dust
section contains settings for
mineral dust aerosols.
#============================================================================
# Settings for GEOS-Chem aerosols
#============================================================================
aerosols:
# ... preceding sub-sections omitted ...
dust:
activate: true
acid_uptake_on_dust: false
# ... following sub-sections omitted ...
- activate
Activates (
true
) or deactivates (false
) mineral dust aerosols in GEOS-Chem.Default value:
true
- acid_uptake_on_dust
Activates (
true
) or deactivates (false
) the acid uptake on dust option, which includes 12 additional species.Default value:
false
Sea salt aerosols
The aerosols:sea_salt
section contains settings for sea salt
aerosols:
#============================================================================
# Settings for GEOS-Chem aerosols
#============================================================================
aerosols:
# ... preceding sub-sections omitted ...
sea_salt:
activate: true
SALA_radius_bin_in_um: [0.01, 0.5]
SALC_radius_bin_in_um: [0.5, 8.0]
marine_organic_aerosols: false
# ... following sub-sections omitted ...
- activate
Activates (
true
) or deactivates (false
) sea salt aerosols.Default value:
true
- SALA_radius_bin_in_um
Specifies the upper and lower boundaries (in nm) for accumulation-mode sea salt aerosol (aka SALA).
Default value:
0.01 nm - 0.5 nm
- SALC_radius_bin_in_um
Specifies the upper and lower boundaries (in nm) for coarse-mode sea salt aerosol (aka SALC).
Default value:
0.5 nm - 8.0 nm
- marine_organic_aerosols
Activates (
true
) or deactivates (false
) emission of marine primary organic aerosols. This option includes two extra species (MOPO and MOPI).Default value:
false
Stratospheric aerosols
The aerosols:sulfate
section contains settings for
stratopsheric aerosols.
#============================================================================
# Settings for GEOS-Chem aerosols
#============================================================================
aerosols:
# ... preceding sub-sections omitted ...
stratosphere:
settle_strat_aerosol: true
polar_strat_clouds:
activate: true
het_chem: true
allow_homogeneous_NAT: false
NAT_supercooling_req_in_K: 3.0
supersat_factor_req_for_ice_nucl: 1.2
calc_strat_aod: true
# ... following sub-sections omitted ...
- settle_strat_aerosol
Activates (
true
) or deactivates (false
) gravitational settling of stratospheric solid particulate aerosols (SPA, trapezoidal scheme) and stratospheric liquid aerosols (SLA, corrected Stokes’ Law).Default value:
true
- polar_strat_clouds
Contains settings for how aerosols are handled in polar stratospheric clouds (PSC):
- activate
Activates (
true
) or deactivates (false
) formation of polar stratospheric clouds.Default value:
true
- het_chem
Activates (
true
) or deactivates (false
) heterogeneous chemistry within polar stratospheric clouds.Default value:
true
- allow_homogeneous_NAT
Activates (
true
) or deactivates (false
) heterogeneous formation of NAT from freezing of HNO3.Default value:
false
- NAT_supercooling_req_in_K
Specifies the cooling (in K) required for homogeneous NAT nucleation.
Default value:
3.0
- supersat_factor_req_for_ice_nucl
Specifies the supersaturation factor required for ice nucleation.
Recommended values:
1.2
for coarse grids;1.5
for fine grids.
- calc_strat_aod
Includes (
true
) or excludes (false
) online stratospheric aerosols in extinction calculations for photolysis.Default value:
true
Sulfate aerosols
The aerosols:sulfate
section contains settings for sulfate
aerosols:
#============================================================================
# Settings for GEOS-Chem aerosols
#============================================================================
aerosols:
# ... preceding sub-sections omitted ...
sulfate:
activate: true
metal_cat_SO2_oxidation: true
- activate
Activates (
true
) or deactivates (false
) sulfate aerosols.Default value:
true
- metal_cat_SO2_oxidation
Activates (
true
) or deactivates (false
) the metal catalyzed oxidation of SO2.Default value:
true
Extra diagnostics
The extra_diagnostics
section contains settings for GEOS-Chem Classic
diagnostics that are not archived by History diagnostics
or HEMCO.
Obspack diagnostic
Note
These settings are omitted for GCHP, as ObsPack diagnostics can only be used with GEOS-Chem Classic.
The extra_diagnostics:obspack
section contains settings for
the Obspack diagnostic:
#============================================================================
# Settings for diagnostics (other than HISTORY and HEMCO)
#============================================================================
extra_diagnostics:
obspack:
activate: false
quiet_logfile_output: false
input_file: ./obspack_co2_1_OCO2MIP_2018-11-28.YYYYMMDD.nc
output_file: ./OutputDir/GEOSChem.ObsPack.YYYYMMDD_hhmmz.nc4
output_species:
- CO
- 'NO'
- O3
# ... following sub-sections omitted ...
- activate
Activates (
true
) or deactivates (false
) ObsPack diagnostic output.Default value:
true
- quiet_logfile_output
Deactivates (
true
) or activates (false
) printing informational output tostdout
(i.e. the screen or log file).Default value:
false
- input_file
Specifies the path to an ObsPack data file (in netCDF format).
- output_file
Specifies the path to the ObsPack diagnostic output file. This will be a file that contains data at the same locations as specified in
input_file
.
- output_species
A list of GEOS-Chem species (as a YAML sequence) to archive to the output file.
Planeflight diagnostic
Note
These settings are omitted for GCHP, as the Planeflight diagnostics can only be used with GEOS-Chem Classic.
The extra_diagnostics:planeflight
section contains settings for
the GEOS-Chem planeflight diagnostic:
#============================================================================
# Settings for diagnostics (other than HISTORY and HEMCO)
#============================================================================
extra_diagnostics:
# ... preceding sub-sections omitted ...
planeflight:
activate: false
flight_track_file: Planeflight.dat.YYYYMMDD
output_file: plane.log.YYYYMMDD
# ... following sub-sections omitted ...
- activate
Activates (
true
) or deactivates (false
) the Planeflight diagnostic output.Default value:
false
- flight_track_file
Specifies the path to a flight track file. This file contains the coordinates of the plane as a function of time, as well as the requested quantities to archive.
- output_file
Specifies the path to the Planeflight output file. Requested quantities will be archived from GEOS-Chem along the flight track specified in
flight_track_file
.
Hg simulation options
This section of geoschem_config.yml
is included for
the mercury (Hg) simulation:
Hg sources
The Hg_simulation_options:sources
section contains settings
for various mercury sources.
#============================================================================
# Settings specific to the Hg simulation
#============================================================================
Hg_simulation_options:
sources:
use_dynamic_ocean_Hg: false
use_preindustrial_Hg: false
use_arctic_river_Hg: true
# ... following sub-sections omitted ...
- use_dynamic_ocean_Hg
Activates (
true
) or deactivates (false
) the online slab ocean mercury model.Default value:
false
- use_preindustrial_Hg
Activates (
true
) or deactivates (false
) the preindustrial mercury simulation. This will turn off all anthropogenic emissions.Default value:
false
- use_arctic_river_Hg
Activates (
true
) or deactivates (false
) the source of mercury from arctic rivers.Default value:
true
Hg chemistry
The Hg_simulation_options:chemistry
section contains settings
for mercury chemistry:
#============================================================================
# Settings specific to the Hg simulation
#============================================================================
Hg_simulation_options:
# ... preceding sub-sections omitted ...
chemistry:
tie_HgIIaq_reduction_to_UVB: true
# ... following sub-sections omitted ...
- tie_HgIIaq_reduction_to_UVB
Activates (
true
) or deactivates (false
) linking the reduction of aqueous oxidized mercury to UVB radiation. A lifetime of -1 seconds indicates the species has an infinite lifetime.Default value:
true
Options for simulations with carbon gases
These sections of geoschem_config.yml
are included for
simulations with carbon gases (carbon
, CH4
,
CO2
, tagCO
, tagCH4
).
CH4 observational operators
The CH4_simulation_options:use_observational_operators
section
contains options for using satellite observational operators for CH4:
#============================================================================
# Settings specific to the CH4 simulation / Integrated Methane Inversion
#============================================================================
CH4_simulation_options:
use_observational_operators:
AIRS: false
GOSAT: false
TCCON: false
# ... following sub-sections omitted ...
- AIRS
Activates (
true
) or deactivates (false
) the AIRS observational operator.Default value:
false
- GOSAT
Activates (
true
) or deactivates (false
) the GOSAT observational operator.Default value:
false
- TCCON
Activates (
true
) or deactivates (false
) the GOSAT observational operator.Default value:
false
CH4 analytical inversion options
The ch4_simulation_options:analytical_inversion
section
contains options for analytical inversions with the Integrated
Methane Inversion workflow (aka IMI).
The IMI will automatically modify several of these options based on
the inversion parameters that you specify.
#============================================================================
# Settings specific to the CH4 simulation / Integrated Methane Inversion
#============================================================================
CH4_simulation_options:
# ... preceding sub-sections omitted ...
analytical_inversion:
perturb_OH_boundary_conditions: false
CH4_boundary_condition_ppb_increase_NSEW: [0.0, 0.0, 0.0, 0.0]
- perturb_CH4_boundary_conditions
Activates (
true
) or deactivatees (false
) perturbation of CH4 nested-grid boundary conditions in analytical inversions.Default value:
false
- CH4_boundary_condition_ppb_increase_NSEW
Specifies the perturbation amount (in ppbv) to apply to the north, south, east and west CH4 nested-grid boundary conditions. Used in conjunction with the
perturb_CH4_boundary_conditions
option.Default value:
[0.0, 0.0, 0.0, 0.0]
(no perturbation)
CO2 Sources
The CO2_simulation_options:sources
section contains toggles
for activating sources of \(CO_2\):
#============================================================================
# Settings specific to the CO2 simulation
#============================================================================
CO2_simulation_options:
sources:
3D_chemical_oxidation_source: true
# ... following sub-sections omitted ...
- 3D_chemical_oxidation_source
Activates (
true
) or deactivates (false
) \(CO_2\) production by archived chemical oxidation, as read by HEMCO.Default value:
true
CO2 tagged species
The CO2_simulation_options:tagged_species
section contains toggles
for activating tagged \(CO_2\) species:
Attention
Tagged \(CO_2\) tracers should be customized by each user and the present configuration will not work for resolutions other than \(2.0^{\circ} {\times} 2.5^{\circ}\).
#============================================================================
# Settings specific to the CO2 simulation
#============================================================================
CO2_simulation_options:
# ... preceding sub-sections omitted ...
tagged_species:
tag_bio_and_ocean_CO2: false
tag_land_fossil_fuel_CO2: false
# .. following sub-sections omitted ...
- tag_bio_and_ocean_CO2
Activates (
true
) or deactivates (false
) tagging of biosphere regions (28), ocean regions (11), and the rest of the world (ROW) as specified inRegions_land.dat
andRegions_ocean.dat
files.
- tag_land_fossil_fuel_CO2:
Activates (
true
) or deactivates (false
) tagging of land and ocean fossil fuel regions.
CO chemical sources
The tagged_CO_simulation_options
section contains settings
for the carbon
simulation and tagged CO simulation.
#============================================================================
# Settings specific to the tagged CO simulation
#============================================================================
tagged_CO_simulation_options:
use_fullchem_PCO_from_CH4: true
use_fullchem_PCO_from_NMVOC: true