Tabling

This page describes the tabling capabilities of GCPy, including possible argument values for every tabling function. These functions are primarily used for model benchmarking purposes. All tables are printed to text files.

Emissions tables

def make_benchmark_emis_tables(reflist, refstr, devlist,
    devstr, dst="./benchmark", refmet=None, devmet=None,
    overwrite=False, ref_interval=[2678400.0], dev_interval=[2678400.0],
    spcdb_dir=os.path.dirname(__file__)
):
    """
    Creates a text file containing emission totals by species and
    category for benchmarking purposes.
    """

Arguments:

reflist: list of str: List with the path names of the emissions file or files (multiple months) that will constitute the “Ref” (aka “Reference”) data set.

refstr : str: A string to describe ref (e.g. version number)

devlist : list of str: List with the path names of the emissions file or files (multiple months) that will constitute the “Dev” (aka “Development”) data set

devstr : str: A string to describe dev (e.g. version number)

Keyword arguments:

dst : str

A string denoting the destination folder where the file containing emissions totals will be written.

Default value: ./benchmark

refmet : str

Path name for ref meteorology

Default value: None

devmet : str

Path name for dev meteorology

Default value: None

overwrite : bool

Set this flag to True to overwrite files in the destination folder (specified by the dst argument).

Default value: False

ref_interval : list of float

The length of the ref data interval in seconds. By default, interval is set to [2678400.0], which is the number of seconds in July (our 1-month benchmarking month).

Default value: [2678400.0]

dev_interval : list of float

The length of the dev data interval in seconds. By default, interval is set to [2678400.0], which is the number of seconds in July (our 1-month benchmarking month).

Default value: [2678400.0]

spcdb_dir : str

Directory of species_datbase.yml file

Default value: Directory of GCPy code repository

gcpy.benchmark.make_benchmark_emis_tables() generates tables of total emissions categorized by species or by inventory. These tables contain total global emissions over the lengths of the Ref and Dev datasets, as well as the differences between totals across the two datasets. Passing a list of datasets as Ref or Dev (e.g. multiple months of emissions files) will result in printing totals emissions summed across all files in the list. Make sure to update the ref_interval and/or dev_interval arguments if you pass input that does not correspond with 1 31 day month.

Mass Tables

def make_benchmark_mass_tables(ref, refstr, dev, devstr,
   varlist=None, dst="./benchmark", subdst=None, overwrite=False,
   verbose=False, label="at end of simulation", spcdb_dir=os.path.dirname(__file__),
   ref_met_extra='', dev_met_extra=''
):
   """
   Creates a text file containing global mass totals by species and
   category for benchmarking purposes.
   """

Arguments:

reflist : str: Pathname that will constitute the “Ref” (aka “Reference”) data set.

refstr : str: A string to describe ref (e.g. version number)

dev : list of str: Pathname that will constitute the “Dev” (aka “Development”) data set. The “Dev” data set will be compared against the “Ref” data set.

devstr : str: A string to describe dev (e.g. version number)

Keyword arguments:

varlist : list of str

List of variables to include in the list of totals. If omitted, then all variables that are found in either “Ref” or “Dev” will be included. The varlist argument can be a useful way of reducing the number of variables during debugging and testing.

Default value: None

dst : str

A string denoting the destination folder where the file containing emissions totals will be written.

Default value: ./benchmark

subdst : str

A string denoting the sub-directory of dst where PDF files containing plots will be written. In practice, subdst is only needed for the 1-year benchmark output, and denotes a date string (such as “Jan2016”) that corresponds to the month that is being plotted.

Default value: None

overwrite : bool

Set this flag to True to overwrite files in the destination folder (specified by the dst argument).

Default value: False

verbose : bool

Set this flag to True to print extra informational output.

Default value: False.

spcdb_dir : str

Directory of species_datbase.yml file

Default value: Directory of GCPy code repository

ref_met_extra : str: Path to ref Met file containing area data for use with restart files which do not contain the Area variable. Default value : ‘’

dev_met_extra : str

Path to dev Met file containing area data for use with restart files which do not contain the Area variable.

Default value: ‘’

gcpy.benchmark.make_benchmark_mass_tables is used to create global mass tables of GEOS-Chem species from a Restart file. This function will create one table of total mass by species from the earth’s surface to the top of the stratosphere and one table for only the troposphere. The tables contain total mass for each of the ref and dev datasets in Gg, as well as absolute and percentage difference between the two datasets. If your restart files do not contain an Area variable ("AREA for GEOS-Chem Classic or "Met_AREAM2 for GCHP) then you will need to use the ref_met_extra and/or dev_met_extra arguments to pass the paths of NetCDF files containing the corresponding area variables (usually contained in meteorology diagnostic output).

Operations Budget Tables

def make_benchmark_operations_budget(refstr, reffiles, devstr,
   devfiles, ref_interval, dev_interval, benchmark_type=None,
   label=None, col_sections=["Full", "Trop", "PBL", "Strat"],
   operations=["Chemistry","Convection","EmisDryDep","Mixing",
"Transport","WetDep"], compute_accum=True,
   require_overlap=False, dst='.', species=None, overwrite=True
):
   """
   Prints the "operations budget" (i.e. change in mass after
   each operation) from a GEOS-Chem benchmark simulation.
   """

Arguments:

refstr : str: Labels denoting the “Ref” versions

reffiles : list of str: Lists of files to read from the “Ref” version.

devstr : str: Labels denoting the “Dev” versions

devfiles : list of str: Lists of files to read from “Dev” version.

interval : float: Number of seconds in the diagnostic interval.

Keyword arguments:

benchmark_type : str

“TransportTracersBenchmark” or “FullChemBenchmark”.

Default value: None

label : str

Contains the date or date range for each dataframe title.

Default value: None

col_sections : list of str

List of column sections to calculate global budgets for. May include Strat eventhough not calculated in GEOS-Chem, but Full and Trop must also be present to calculate Strat.

Default value: [“Full”, “Trop”, “PBL”, “Strat”]

operations : list of str

List of operations to calculate global budgets for. Accumulation should not be included. It will automatically be calculated if all GEOS-Chem budget operations are passed and optional arg compute_accum is True.

Default value: [“Chemistry”,”Convection”,”EmisDryDep”,: “Mixing”,”Transport”,”WetDep”]

compute_accum : bool

Optionally turn on/off accumulation calculation. If True, will only compute accumulation if all six GEOS-Chem operations budgets are computed. Otherwise a message will be printed warning that accumulation will not be calculated.

Default value: True

require_overlap : bool

Whether to calculate budgets for only species that are present in both Ref or Dev.

Default value: False

dst : str

Directory where plots & tables will be created.

Default value: ‘.’ (directory in which function is called)

species : list of str

List of species for which budgets will be created.

Default value: None (all species)

overwrite : bool

Denotes whether to overwrite existing budget file.

Default value: True

gcpy.benchmark.make_benchmark_operations_budget() creates tables of budgets for species separated by model operation. The tables show budgets for each of the ref and dev datasets in Gg, as well as absolute and percentage difference between the two datasets. Note that total accumulation across all operations will only be printed if you set compute_accum==True and all operations are included in operations. Note also that when using the non-local mixing scheme (default), 'Mixing' includes emissions and dry deposition applied below the PBL. 'EmisDryDep' therefore only captures fluxes above the PBL. When using full mixing, 'Mixing' and 'EmisDryDep' are fully separated.

Aerosol Budgets and Burdens

def make_benchmark_aerosol_tables(devdir, devlist_aero, devlist_spc,
   devlist_met, devstr, year, days_per_mon, dst='./benchmark',
      overwrite=False, is_gchp=False, spcdb_dir=os.path.dirname(__file__)
):
   """
   Compute FullChemBenchmark aerosol budgets & burdens
   """

Arguments:

devdir: str: Path to development (“Dev”) data directory

devlist_aero : list of str: List of Aerosols collection files (different months)

devlist_spc : list of str: List of SpeciesConc collection files (different months)

devlist_met : list of str: List of meteorology collection files (different months)

devstr : str: Descriptive string for datasets (e.g. version number)

year : str: The year of the benchmark simulation (e.g. ‘2016’).

days_per_mon : list of int: List of number of days per month for all months

Keyword arguments:

dst : str

Directory where budget tables will be created.

Default value: ‘./benchmark’

overwrite : bool

Overwrite burden & budget tables? (default=True)

Default value: False

is_gchp : bool

Whether datasets are for GCHP

Default value: False

spcdb_dir : str

Directory of species_datbase.yml file

Default value: Directory of GCPy code repository

gcpy.benchmark.make_benchmark_aerosol_tables() generates two different tables using output from a single dataset. One contains annual mean aerosol burdens in Tg in the stratosphere, troposphere, and combined stratosphere and troposphere. The other table shows annual global mean AOD in the stratosphere, troposphere, and combined stratosphere and troposphere. Aerosol species used are pre-defined in aod_species.yml: BCPI, OCPI, SO4, DST1, SALA, and SALC.