Menu ▾ ▴

User guide from aether

Rasmus Nüß

TM5-4DVAR

DISCLAIMER
This is a dump of the readme file for the CO-branch of the local TM5-4DVAR reposiory available on aether, the HPC of the LAMOS group from Uni Bremen. As such, some information given may not apply to your machine or the branch you are using or may refer to developments that have not yet been published.
However, I still believe that most info given below will be somewhat useful for especially new users. Will be updated whenever I get around to it.
All the best,
Rasmus Nüß

First time setup

Clone the repository

To clone this repository, first fork this repository to your own account on code. To do so, hit the Fork button in the upper right corner of the repository on code. Then login to aether create and change into a 'models' directory in your home directory

mkdir ~/models && cd ~/models

there simply run:

git clone gitea@code.iup.uni-bremen.de:<username>/tm5-4dvar.git

Note that you need to have a ssh key pair between aether and gitea.

Setup environment

To load libraries and set all paths properly simply run

cd ~/models/tm5-4dvar/user/lamos
source setup_env.sh

This needs to be done whenever you restart the shell.

Compile optimizers and f2py code

Next, in ~/models/tm5-4dvar/base/optimizer/congrad/src run

make congrad.exe machine=aether

Also, in ~/models/tm5-4dvar/base/optimizer/m1qn3/src run

make m1qn3.exe machine=aether

And finally in ~/models/tm5-4dvar/base/f2py/src run

./maker

Running the model

The model should not be started from its base directory (~/models/tm5-4dvar), but instead any interaction is designed to happen from the corresponding user directory. The commands in this chapter all assume you did:

cd ~/models/tm5-4dvar/user/lamos

Forward run

A forward run is done by

srun --cpus-per-task=$OMP_NUM_THREADS \
     scripts/run_fwd_mt.py rc/ind_co_slw.rc \
     -s YYYY,MM,DD -e YYYY,MM,DD

Replace the YYYY, MM, DD with the start and end dates of your simulation.

When running for the first time you have to append --compile to compile, --emis to setup the emissions and --meteo to create the coarsend meteo. To recompile append --compile and -n, this might be neccessary after doing changes to the code. The emissions and meteo only need to be redone if the time or region changed. Additionally, selecting different input may make it neccessary to redo emissions, this includes choosing a different (sub)set of stations or a different satellite instrument. The --compile is also necessary after changing the my.project or my.zoom key, to create a new executable.

Trouble shooting

  • Make sure the environment is setup properly.
  • Segfaults can point to improper use of OMP. Make sure that you are not running on the login nodes and have set cpu-per-task properly.
  • If compiling the final executable (tm5.x) fails, make sure that there are no temporary files (like emacs #filename# autosave files) anywhere in the code tree.
  • If RunForward dies with OSError: [Errno 2] No such file or directory right after setting up emissins and opening observations, make sure that the executable exists and try rerunning with --compile flag.
  • If any import from tm5_utils fails, make sure you compiled the f2py code, as outlined further above.

Using the script and rc files

What the run does can be set in the script and rc files, by simply commenting in or out specific lines. The scripts and rc files can be found in the subdirectories of ~/models/tm5-4dvar/user/lamos.

In scripts/run_fwd_mt.py you can toggle ...

  • the setup of point (line 138) and satellite (line 141) observations (both are required only once)
  • running the model forward once (line 147) for example to coarse the meteo
  • doing the Adjoint test (lines 160-163)
  • doing the Gradient test (lines 166-168)

Note that if on is commented in, the other must be commented out.

To setup your own experiment create your own (set) rc file(s) (ie by copying rc/ind_co_slw.rc). Do not change the default/example files. An example for a global inversion can be found in rc/glb_co_slw.rc. A more complete documentation of the keys available in the rc files can be found at the end of this document.

Inversion

The optimzer will not:

  • compile the model
  • setup emission
  • setup point or satelite observations
  • automatically reuse meteo (that is, if called with write-coarse-meteo active, it will rewrite the meteo for each iteration!)

Therefore, before running any optimizer, run the forward model once with --emis and --compile and coarse meteo creation active for the full time range, to do all the above. Afterwards, remember to switch to reuse the coarsened meteo before starting the optimizer to save computation time.

The two optimizers are run by either

  • congrad:
srun --cpus-per-task=$OMP_NUM_THREADS \  
     scripts/congrad.py rc/ind_co_slw.rc \       
     -s YYYY,MM,DD -e YYYY,MM,DD
  • or m1qn3:
srun --cpus-per-task=$OMP_NUM_THREADS \
     scripts/m1qn3.py rc/ind_co_slw.rc \
     -s YYYY,MM,DD -e YYYY,MM,DD

Useful srun and sbatch flags

When using srun, the simulation is limited to the interactive nodes and in time. Useful srun flags are -p all to run on any node and -t 360 to increase the jobs time maximum to a time given in minutes (limited to 6 hours, default 1 hour). To use them, insert them directly after srun in above commands.

However, the proper way to start a job on aether is using sbatch, which will sent the job to background immediately (so the terminal may be closed while it is running) and also allows for longer jobs. Simply replace the srun in above commands by sbatch, add the -p all flag and either the -q lamos flag (up to 24 hours, default 12 hours) or the -q long flag (up to 7 days). Do not forget to add the -t flag accordingly to request the time you need.

Output

The output can be found in

/mnt/beegfs/user/<username>/tm5-4dvar/var4d-mt/<tracer>/<region>/ml60/tropo<levels>/\
<my.project>/output/<YYYYMMDDHH>-<YYYYMMDDHH>

Most relevant files are:

  • emission_apri.nc4 and emission_apos.nc4: A priori and a posteriori emissions for each region and inversion timestep in kg/gridbox/second.
  • mass/mix_*.nc4: For each tracer and region the full 3D mixing ratio field in roughly hourly resolution in ppb (for CO, other tracer might have a different unit based on the scaling factor mixrat_unit defined in proj/tracer/<tracer>/src/chem_param.F90).
  • satellite/sat-track_departures_*.nc4: Measured and modeled total coulumn, location and time for each satellite observation. Model data is interpolated to location of observation, the averaging kernel is already applied and data is extracted in the model timestep corresponding to the time of the observation. Units are either molec/cm^2 for IASI or ppb for TROPOMI (both for CO).
  • stations/stations_comp.nc4: For each station time series of the a priori (apri_mix, apr_mix_error) and a posteriori (apos_mix, apos_mix_error) model mixing ratio for each model timestep. Also, all assimilated observations for each station (obs_mix, obs_mix_error) and the temporally cherry picked model a priori (mod_mix_apri) and a posteriori (mod_mix_apos) and their error (mod_mix_err). All model data is given in ppb (for CO) and interpolated to the location of the station. Note that the time series and the cherry picked data are selected using different input files as of now, so they might differ slightly!

There is a script to visualize satellite, station and emission in- and output. It can be run from inside the output directory by:

srun -u path/to/scripts/create_plots.py

Please refer to the script file for further documentation.

RC files and keys

In user/lamos/rc the main rc-files are stored. these give the main outline of what the simulation should do. In the include subdirectory all rc-files that specify how certain things should happen are stored. These files will often be reused without changes if setting up a new experiment.

${KEYNAME} refers to the content of rc-key KEYNAME.

The defaults given below usually refer to a working default setup one could use, rather than any defaults enforced by the model code if a key is omitted. In the latter case this will be noted explicitly.

Bools are either T (true) or F (false).

#include <RCFILE> inserts content of RCFILE into the current rc file.

For the sake of brevity of this document, some keys with the same beginning have been grouped by separating the parts in which they differ by slashes (/). I.e. my.funny.key.min/max stands for two seperate keys: my.funny.key.min and my.funny.key.max

Main rc-file

Basics

#include include/folders.rc: file to generate various paths. Usually no need to touch

include/jobs.rc: Info for job manager, model timestep and which processes to include (slopes, budgets, deposition, ..). Usually no need to touch.

par.nthread: Number of cores to use for OMP. Default is 8 and native maximum is 28 on aether. Going past that with hyperthreading does not improve, and my even degrade, performance.

repeat.adjoint.test: Default 1

my.project: Name of input/output parent folder. Changing this enables one to have multiple model runs in parallel. If this is changed, the model must be recompiled or the existing executable must be copied and named accordingly. Do note that some basic python scripts are only copied to the build directory (but not the run directory) and are later on accessed from there by the model during runtime. However, (re)compiling will delete those scripts and only recopy them as soon as the compilation is completed. This impies, that any model run that switches between forward and adjoint (or vice versa) in that time will break! On the other hand, if the already running model stays in one direction (ie. only accessing the FORTRAN code), during the whole compilation process, there is no issue.

queue: Default dummy (run whereever is space). See aether docu for more info.

my.source.dirs: Where should the model look for code? Default ${my.projects.basic} ${my.projects.output}. Usually do not touch.

Input/Output

<tracer>.<sat/point>.assimilate: Bool, should that dataset for that tracer be assimilated? Default T.

output.satellite: Bool, default T, toggle general satellite output.

adjoint.input.satellite: Bool, default T, toggle output of departure files.

output.satellite.verbose: Bool, default F, print additional information during runtime.

#include include/satellite_parameters.rc: Additional general satellite parameters. Usually no need to touch.

#include include/<instrument>_parameters.rc: Satellite instrument specific parameters. Currently available instruments on aether: iasi (2007-2018) and tropomi (2018). MOPITT (2010-2013) data exists, but the rc-file was not adjusted so far.

output.point, adjoint.input.point (station comp file), output.point.verbose, #include include/point_parameters.rc (error estimation), #include include/<network>_flask_parameters.rc (network: ie. ccgg_co): see keys above, but for point observations. Use caution! All observations are precompiled and saved to ${input.dir} and will therefore not be automatically updated if the optimizer is rerun with changed rc files. Therefore, to make sure a changed station list is used, delete the input directory and rerun the forward model.

output.station.timeseries: Bool, default T, save time series in stations/stations_comp.nc4?

output.station.verbose: Bool, default F, Print additional info during runtime?

#include include/station_parameters.rc: Additional station keys. Usually no need to touch.

output.totalcol: Bool, default F, save column-averaged mixing ratio?

#include include/totalcol_parameters.rc: Additional keys for col-avg output. Usually no need to touch.

output.tccon: Bool, default F, save model data at location of TCCON stations, including meteo?

#include include/tccon_station_parameters.rc: Additional keys for TCCON output. Usually no need to touch.

output.mix: Bool, default T, save 3D model mixing ratio fields per timestep?

#include include/mix_output_parameters.rc: Additional keys for mixing ratio output. Usually no need to touch.

Tracer and Optimizer

my.tracer: Name(s) of tracer(s). Ie CO or CH4 or CO, CH4.

my.tracer.name: Name of <tracer> project folder (proj/tracer/<tracer>). Ie CO to run the CO version of the model.

#include include/<tracer>_parameters.rc: Region- and source category-wise error, correlation and inversion settings. Very important!

emission.read.optimized: Bool, default F, toggle restart from previously optimized emission. Not yet tested on aether.

emission.read.optimized.filename: Path to previous optimization result.

#include include/pyshell_emission.rc: Paths for pyshell to set up emissions. Usually no need to touch.

#include include/CO_emission_parameters_<inventory>.rc: Parameters for inventories used as prior emission. Very important!

optimize.emission: Bool, default T, toogle optimization of emissions.

optimize.initialconcentration: Bool, default F, toggle (additional?) optimization of initial concentration. Not yet tested on aether. (AFAIK development postponed indefinitely.)

optimize.parameter: Bool, default F, toggle optimization of bias parameters. Not yet testedon aether. Only used by nasa for some CO2 inversions.

optimize.gradient.norm.reduction: Default 1e3, inverse of required gradient norm reduction. "By what factor should the cost function be reduced?" Value may vary with quality of the prior, degrees of freedom of the posterior (resolution in space and time, number of optimized categories,..) and aprior error of each category.

optimize.maximum.iterations: Default 200, number of iterations after which the inversion is aborted.

optimize.fixed.iterations: Default 100, number of iterations after which the optimization is considered converged and a stricter convergence will be assumed.

optimize.alpha.start/decrement/minimum: Setttings for alpha parameter in gradient test. Defaults 1.0/0.1/1e-16

#include include/optimizer_<optimizer>.rc: Optimizer- and tracer-specific settings. Usually no need to touch.

#include include/vpp.rc: Var4D PostProcessor settings. Offers tracer aggregation and self-correlation.

optimize.postprocess: Bool, default T, toggles postprocessing.

Technical stuff / machine specifics

my.machine: Default aether

my.build.configure.flags: Default optim-fast

#include include/machine.${my.machine}.rc: Compiler settings and libraries. Usually no need to touch.

my.meteo.resol: Either glb100x100 (run from full resolution archive) or coarsened (use previously created meteo files). See [[Using the script and rc files]] above.

tmm.output: Bool T if meteo should be created, F if running on coarsened.

meteo.coarsened: Bool F if running on archives, T if running on coarsened.

#include include/meteo-ei_cy3.rc: Meteo settings. Usually no need to touch.

my.nlay: Number of vertical model layers to use. Either 34 (more accurate, neccessary if starting from TM5MP see istart:51 below) or 25 (faster, default).

LEVS: Shorthand for vertical meteo resolution. Default tropo${my.nlay}

my.zoom: Name of zooming region. glb6x4 for no zoom. After changing this, the model needs to be recompiled.

#include include/zoom-${my.zoom}.rc: (Zoom) region definition.

istart: How are the starting fields obtained?

  • 1: coldstart with initial fields set to 0
  • 2: coldstart with initial fields computed in sr trace1 in sources_sinks, background set to start.2.iniconc.<tracer>
  • 3: coldstart with initial fields read from model output (save file), prefered option
  • 4: coldstart with initial fields read from model output stored in mixing ratio (no slopes).
  • 5: coldstart with initial fields read from an mmix output file in mixing ratio (in units of current tracer, ie. ppb for CO) (no slopes, missing field set to zero)
  • 51: same as 5, but allows to read in TM5MP mmix files (in mol/mol) properly (this setting is only available on aether).

start.2.iniconc_from_file: Bool, default F, in case of istart:2, should the initial tracer concentrations be read from file?

start.2.iniconc.CO: In case of istart:2, what tracer concentration should be assumed? In ppb

start.3.filename: In case of istart:3, path to the save file that should be used.

start.5.<region>: In case of istart:5 or istart:51, path to the mmix file that should be used. A key must exist for every region and if a file is provided the grid in that file must be identical (in lateral and vertical resolution as well as extent) to that region, however, leaving the key empty will cause the model to attempt to fill the region based on its parent region.

<instrument>-parameters.rc

<tracer>.obs.sat.class: Usually name of instrument, ie IASI or TROPOMI.

<tracer>.departures.sat.class: Usually name of instrument, ie IASI or TROPOMI.

<tracer>.optimize.sat.bias.parameter: Bool, default F, bias parameter only implemented for MOPITT.

<tracer>.sat.bias.num_params: Number of bias parameters, default 0.

satellite.<tracer>.only.obs.error: Bool, default T, optimize based on observational error only (T) or additionally include model error (F)?

satellite.<instrument>.<tracer>.limit_obs.by_region: Bool, default T, reduce amount of assimilated data by region?

satellite.<instrument>.<tracer>.obslimit.region: name of region by which to limit data, ie glb600x400 or ind. Also works with keys like ${my.region1} (for global) or ${my.region3} (for finest).

satellite.<instrument>.<tracer>.minimum/maximum.latitude/longitude: Optional, lat/lon borders of custom region to limit observations.

satellite.<instrument>.<tracer>.sampling.strategy: Default 3

  • 2 (instantaneous): Only sampled with dynamic timestep containing the measurement time. Might be off for very short steps.
  • 3 (sample within ndyn): Sample throughout the window of ndyn_max seconds containing the measurement. More consistent.

satellite.<instrument>.<tracer>.data.folder: Path to folder with observations. Ie /mnt/beegfs/tm_input/tm54dvar/observations/satellite/IASI/CO/FORLI for IASI.

satellite.<instrument>.<tracer>.vertical.levels: Number of levels in satellite retrieval. 19 for IASI/FORLI, 20 for TROPOMI/IUP.

satellite.<instrument>.<tracer>.filename.pattern: Name satellite data file. Shorthands %Y, %m, %d are recognized for numeric year, month, day. Ie. %Y/iasi_CO_LATMOS_ULB_%Y%m%d.txt for IASI.

satellite.<instrument>.<tracer>.grid.observations: Bool, default F, toggle to aggregate all satellite data to resolution of model grid. Faster, but looses spatial information.

satellite.<instrument>.<tracer>.url.pattern: Some instruments allow data download on the fly. URL is then defined here. Shorthands %Y, %m, %d are recognized.

output.satellite.meteo.<tracer>: Bool, default T, should meteo (ie. pressure) at location of observation be written?

satellite.<instrument>.<tracer>.error.inflation: Factor to artifically increase satellite error to give more weight to point measurements. Default 50. Larger values me be required for TROPOMI due to higher observation density.

<tracer>.satellite.unassimilate.mdm: Error of observation in unit of input file (molec/cm^2 for IASI CO, ppb for TROPOMI CO) given to observations that should not be included in the inversion.

output.satellite.split.period: Are satellite files divided per day (d) or per month (m)?

output.satellite.errors: How to estimate model error at point of obs? Irrelevant if satellite.<tracer>.only.obs.error.

  • 2d: Error based on error of total column in cell and 3 nearest neighbours.
  • neighbors: Linearily interpolate profile based on cell and 3 nearest neighbours. Their variance is error.
  • gradient: Calculate model profile in center of all 8 neighbours. Error is variance in profile over all 9 cells.

output.satellite.interpolation: How to extract model mixing ratios, default 3

  • 1: Take value of grid box. No interpolation.
  • 2: Interpolation based on slopes in gridbox.
  • 3: Linear interpolation also considering neighbouring boxes.

<tracer>-parameters.rc

<tracer>.region<#>.categories: Number of categories to consider in that region. Ie 1 if only total emissions or 3 if split into natural, biomass burning and anthropogenic.

<tracer>.region<#>.category<#>: Correlation and error settings for each region. Six entries, seperated by semicolons. Example: natural ; 50.0 ; 1000.0-e ; 9.50-e-monthly ; 0 ; def-def-0. The entries are:

  • Category name. An emission routine will be assigned to each of these later in <tracer>_emission_parameters_<inventory>.rc. Some key words have special meaning, depending on the version of tm54dvar used:
    • "Old" style from Maartens version, still in use at MAQ:
      • total: To be used as sole category on the global level. Expected to point to a routine (TotalEmission) that aggregates BB, FF and VOC. Will be given a vertical distribution that somewhat holds true for the combined emissions.
      • natural: Expected to point to VOC and CH4 emissions.
      • biomass burning: Will use the IS4FIRES injection profiles as vertical distribution, as described below.
      • anthropogenic: Always assumed to be surface emission, without any injection profile.
    • "New" style from Sourish version from sourceforge (no longer supports a total category with a compbined vertical distribution. Instead, use either production and global surface or all seperate categories on a global scale):
      • production: Expected to handle VOCs and CH4 emissions and will be given a proper vertical distribution for that.
      • global surface: Expected to combine BB, FF and natural (but not VOCs and CH4) on a global scale (Global_surface). Will not have any vertical distribution and will therefore be assumed to be surface only.
      • biomass burning: Will use the IS4FIRES injection profiles as vertical distribution, as described below.
      • fossile fuel: Always assumed to be surface emission, without any injection profile.
      • natural: Instead of VOCs and CH4, this is expected to handle Oceanic and Biogenic emissions, which are both assumed to be surface only.
  • A priori error in percent. How far is the inversion result allowed to deviate? Too large/small values my lead to over/underfitting of the observations.
  • Spatial correlation length in km and type (e=exponential, g=gaussian), seperated by a -.
  • Temporal correlation time (in units of months), type and range (eg monthly, daily+3, ..). Range will be the teporal resolution of the optimized emissions. daily+3 for example denotes, that a new set of emissions will be every three days for that category.
  • Bool to toggle optimization of this category. Either 0 or 1.
  • TIPP string. Default def-def-0. Full functionality unused, but land and ocean are supported to constrain the inversion to land and ocean emissions, respectively. Must be one of those three, otherwise the model breaks.

var4d.<tracer>.<category>.optim_emis.type: If something else but 1,2,3 is given, defaults to 3. If not set (missing key), defaults to 1!

  • 1: Linear optimization, allows negative posterior emissions. Prior error is
    land/ocean-mask * apri_error_% * 0.01 * |emission|
  • 2: Same as 1, but always disregards *.enforce.minimum.error.
  • 3: Nonlinear Optimization, usefull if starting from 0 emissions, prevents negative posterior emissions. Prior error is:
    land/ocean_mask * error * 0.01 * ones
    To ensure negative emissions are impossible, emissions are saved as:
    poste = prior * exp(adjoint_emis), where adjoint_emis < 0 poste = prior * (1 + adjoint_emis), where adjoint_emis >= 0

<tracer>.<category>.sep_error: Bool, default F, if reading optimized emissions from a file, allows to use their error as prior error by enabling use of <tracer>.<category>.err.routine to set emission errors. If T emission errors are calculated as fraction of the emission as defined in <tracer>.region<#>.category<#> (see above).

<tracer>.<category>.enforce.minimum.error: Bool, default F, toggles usage of *.minimum.error below.

<tracer>.<category>.minimum.error: Float, prior error becomes:

land/ocean_mask * max(apri_error_%*0.01*|emission|, minimum.error)

<tracer>.<category>.minimum.error.depends.average: Bool, toggles *.minimum.error to instead be applied as:

land/ocean_mask * max(apri_error_%*0.01*|emission|, minimum.error*avg(|emission|))

emission.<tracer>.${my.region<#>}.categories: Fixed to ${<tracer>.region<#>.categories}

emission.<tracer>.${my.region<#>}.category<#>: Fixed to ${<tracer>.region<#>.category<#>}

<tracer>_emission_parameters_<inventory>.rc

CO.NMVOC.production.choice: single Integer, choice for natural CO emissions.

  • in FORTRAN:

  • 1: ECPL, makes use of files pointed to in fvert.* keys. Outdated?

  • 2: TM5-MP, file co_production_2006%m.nc located in NMVOC.TM5.profile.inputdir used.

  • 3, 4: IMAGES apri/apos, file pCO_vmrHCHO_IMAGES_%Y%m.nc located in NMVOC.IMAGES.inputdir used.

  • in python:

  • 1: Natrual_ECPL: NMVOC-CO for 2005. File NMVOC2D_2005_kgs_Correct.nc located in <tracer>.emission.inputdir used.

  • 2: Natural_TM5: Maarten's CO production fields, assume every year as 2006. File co_production_2006%m.nc located in NMVOC.TM5.profile.inputdir used.

NMVOC.TM5.profile.inputdir: Path to precalculated TM5-MP CO-production from CH4 and other VOCs.

CO.NMVOC.contains.CH4: Bool, default T, toggles between inclusion of CH4 in Natural_TM5 and FORTRAN code above or explicit calculation from CH4 and OH in emission_*_CO.F90

<tracer>.emission.class: Name of tracer specific Emission child class. in case of CO: CO_Emissions

<tracer>.emission.inputdir: Path to parent directory of all inventories for specific tracer. In case of CO: ${tm5.data.input.dir}/fluxes/CO

Inventories

The following keys allow for quick selection of different emission inventories. Only works for CO. For more inforamtion on the key words and differences between Maartens and Sourish version see <tracer>-parameters.rc above.

<tracer>.<category>.routine: Decide which inventory to use for each category. The naming convention in Maarten version for these keys is very different and much less unified. Usual choices per category are:

  • biomass burning:
    • BiomassBurning_GFASv12
    • BiomassBurning_GFED41
    • BiomassBurning_GFED4
    • BiomassBurning_GFED
    • BiomassBurning_FINN Reads average BB emissions per time step and grid cell and can add trash emissions as well. Requires FINN.CO.emission.file and FINN.CO.add.trash.emission to be set, both are described below.
    • FINN_daily Read emissions for the first day of the time step only. Therefore, must be used with daily cycle turned on (CO.biomass burning.dailycycle : T)
    • BiomassBurning_GFAS (2003-2013)
    • BiomassBurning_GFED_3hourly
    • BiomassBurning_hybrid_3hourly (combines multiple inventories)
  • total:
    • TotalEmission: CO.anthropogenic.routine * CO.anthropogenic.scale.factor + CO.natural.routine + BiomassBurning, where Biomassburning is CO.biomass burning.routine unless AKFED.CO.substitute is true, in which case self.BiomassBurning_AKFED is used instead. To be used with Maartens version!
  • global surface:
    • Global_Surface: CO.fossile fuel.routine + CO.bb.agg.routine + CO.natural.routine Note that VOC and CH4 emissions are not included here. To be used with Sourish version!
  • anthropogenic: (to be used with Maartens version, for Sourish version use fossile fuel instead, but witht he same input options!)
    • MACCity
    • EDGAR4
    • EDGAR4.2
  • natural: (Note the differend meaning in Sourish' and Maarten's version!)
    • Oceanic: POET data read from CO.oceanic.POET.file
    • Biogenic: MEGAN data read from CO.biogenic.MEGANv2.file
    • Surface_other: Sum of Oceanic and Biogenic, to be used as natural emission in Sourish version. However, on aether we are missing the required input, so this would break. Use NoEmissions instead.
    • NMVOC_TM5, NMVOC_ECPL: Use precalculated CO from TM5 or TM4, as explained for CO.NMVOC.production.choice above. If using Sourish version, this is expected to be production instead.
  • rest: (No longer in use in Sourish version)
    • RestEMission: Read some minor emissions not treated by BB, ant and nat from tm_input/tm54dvar/fluxes/CO/EMISSION_rest_ANT_NAT_1x1.nc4
  • production: (to be used with Sourish version)
    • NMVOC_TM5, NMVOC_ECPL: Use precalculated CO from TM5 or TM4, as explained for CO.NMVOC.production.choice above.
    • CO_prod_IMAGES: VOCs and CH4 from IMAGES read from CO.IMAGES.production.file. Required input data not available on aether.

CO.emission.bb.priors: Optional, set for hybrid biomassburning a priori. Takes list of BB inventories and uses their average as prior.

CO.anthropogenic.scale.factor: MK says anthropogenic inventories are usually too small. Use this for experiments where they should be scaled up.

CO.emission.bb.time_factor: Default None, when set to hodzic2007 applies diurnal cycle based on Hodzic, A., et al, 2007, ACP

CO.biomass burning.err.routine: How to obtain inventory uncertainty? BiomassBurning_error (use *.err.routines), BiomassBurning_3spread (max of average or difference of gfas, finn, gfed41), BiomassBurning_spread (max of avg or diff of gfas, gfed). This requires CO.biomass burning.sep_error:T

CO.biomass burning.err.routines: One or more of the BB versions. Then again Max of avg or dif of those.

CO.biomass.unc.factor.diff, CO.biomass.unc.factor.avg: Scaling/weighting factors for the err.routine(s) above.

error = fmax(factor_diff*interior_spread, factor_avg*average_of_priors)

emission.error.<tracer>.<category>.num_scales: Use DisError (?) if non-zero

GFAS.v12.emission.file: Path includin file name if BiomassBurning_GFASv12 is selected.

CO.emission.gfed3.monthly.file and CO.emission.gfed3.daily.file: Path including file name if BiomassBurning_GFED is selected.

CO.emission.dailycycle: Obsolete flag. Replaced by <tracer>.<category>.dailycycle.

<tracer>.<category>.dailycycle: Bool, default F, toggles daily cycle for specific source category of tracer. If any category has a daily cycle, the whole tracer does. If F concentration increment in kg/cl/timestep is x = emis_factor * dtime

dailycycle.folder: Usually placed in rc/include/pyshell_emissions.rc. Path to input folder.

<tracer>.<category>.prefix: Prefix of daily cycle file.

<tracer>.<category>.type: Default 1. Scaling or anomaly is read from ${dailycycle.folder}/YYYY/MM/${..prefix}YYYYMMDD.nc4

  • 0 for scaling x = emis_factor * dtime * scaling
  • 1 for adding x = emis_factor + dtime * anomaly

dry_deposition.store_vd: Never used in Sourish version.

dry_deposition.store_vd.dir: Where to store vertical distribution of dry deposition.

dry_deposition.inputdir: Input for dry depostion. Never used, see above.

OH.inputdir: Where to find OH data

OH.region.name,OH.hybrid.levels: region and level number of OH input data to use.

oh.choice: Which OH dataset should be used?

  • 1: fields from TM5
  • 2: Bergamaschi (${tipp.bc.inputdir}/k_CH4.hdf)
  • 3: Spivakovsky/Bruehl 2000
  • 4: MESSY

oh.scale: Scaling factor for OH fields. According to Huijen 2010 a reasonable value is 0.92

OH.MESSY.inputdir: Where to find MESSY OH input, if used.

OH.MESSY.outputdir: Where to store intermidiate MESSY OH files, if used.

CO.bb.injection.profile.choice: Use separate IS4FIRES biomass burning injections profiles for day and night time (1) or simply their mean (2)?

IS4FIRES.profile.inputdir: Where to find vertical biomass burning injection profiles.

fvert.inputdir, fvert.nmvoc, fvert.total, fvert.rest: Keys only relevant if reading TM4/ECPL NMVOCs.

ch4.choice: Which CH4 fileds to use. 1 is Sander Houwelings posterior fields

ch4.inputdir: Where to find CH4 fields

CH4.Houweling.storedir Where to save coarsened CH4 fields.

GFAS.v12.emission.file: Where to look for GFAS v1.2 data, if used.

CO.emission.gfed3.monthly/daily/hourly.file: Where to look for GFED3 and GFED4 data of different temporal resolution, if used.

GFED4.dry_matter.file, GFED4.emission_factors: Where to look for additional GFED4 input, if used.

FINN.CO.emission.file : Where to look for FINN input, if used.

FINN.CO.add.trash.emission: Bool, default F, should open waste and trash burning be included?

FINN.CO.trash_burning.file: Where to look for FINN waste and trash burning file.

AKFED.CO.substitute: Bool, default F, should the anthropogenic emissions be replaced by AKFED?

AKFED.CO.burned_area.file: Where to look for AKFED data, if used.

AKFED.CO.emission.factor: Scaling factor for AKFED data, if used.

CO.emission.MACCity.file: Where to look for MACCity data, if used.

optimizer_<optimizer>.rc

my.optimizer.class: Which optimizer to use. m1qn3 or conGrad

optimize.optimizedstate nc-filename for final results (also lists priors for easy comparison).

optimize.<tracer>.precon.minimum.error, optimize.<tracer>.precon.minimum.depends.average, optimize.<tracer>.precon.enforce.minimum.error: Keys for preconditioner, currently not in use.

optimize.m1qn3.exec, optimize.conGrad.exec: Path to compiled optimizer executable.

optimize.communication.file: nc-filename for state trajectory.

correlation.inputdir: Directory where the spatial correlation files should be stored. These need to be created only once per region, so somewhere directly below ${my.scratch_dir} would be suitable.

optimize.monitor.outputs: Bool, default F, force output for specific variables during optimizier run.

optimize.monitor.output.list: Which variable to ourput? (satellite, point, station.timeseries, ...)

topo.database: Where to look for topographic input.

optimize.step_save: Bool, default F, should certain output be created for every iteration?
optimize.step_save.filenames Which files should be created for each iteration? (emission.nc4, adj_emissions.nc4, point/point_*.nc4, satellite/sat-track_*.nc4, ...)

zoom-${my.zoom}.rc

region.dx/dy/dz: Basic/coarsed resolution. x and y in degrees, z always 1.0

my.region1/2/3: Full names of zooming regions. All three keys must always be present; leave empty if not in use.

my.region1s/2s/3s: Short names of zooming regions.

regions: Space separated list of full region names. Default ${my.region1} ${my.region2} ${my.region3}.

my.reglist: Dash sparated list of full region names. Default ${my.region1}-${my.region2}-${my.region3}

region.${my.region1/2/3}.parent: Full name of parent region. For glb600x400 this must be set to globe.

region.${my.region1/2/3}.xcyc: Does the region reach around the globe in x direction (1) or not (0).

region.${my.region1/2/3}.touch_np/sp: Does the region reach the north/south pole (1) or not (0).

region.${my.region1/2/3}.xbeg/ybeg/xend/yend: Limits of the region in degrees. Every rgion must fit seamlessly in the coarsest region. I.e. if 6x4 is the coarsed region and there is a 3x2 intermediate region, even the smallest 1x1 region must be a multiple of 6x4 degree boxes, with its borders aligned to the 6x4 grid.

region.${my.region1/2/3}.im/jm: Number of grid boxes (not degrees!) in the region in x/y direction.

region.${my.region1/2/3}.xref/yref/zerf/tref: Factor by which the resolution increased compared to the global (not the parent) region. zref (height) usually fixed at 1. tref (time) usually same as yref.

region.${my.region1/2/3}.redgrid.nh/sh.n: Number of rings near north/south pole for reduced grid. Set to 0 if not in use.

region.${my.region1/2/3}.redgrid.nh/sh.comb: List of number of boxes to use in each ring of reduced grid, from finest to coarsest.

Related

Wiki: Home

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.