From 9364861feccb9f84f2f868117f097f188ff2405d Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 20 Nov 2023 11:31:37 -0500 Subject: [PATCH] Update documentation for GCPy 1.4.0 release docs/source/Benchmark.rst - Add missing section about make_benchmark_mass_table function docs/source/Getting-Started-with-GCPy.rst - Replace "bob" with "YOUR-USER-NAME" in MambaForge installation example - Add section about setting the MPLBACKEND environment variable docs/source/Guide-to-Useful-Capabilities.rst - Fixed typo: "eegridding" -> "regridding" docs/source/Regridding.rst - Add note to use the offline regridding weights method if regridding to or from GCHP stretched grid restart files Signed-off-by: Bob Yantosca --- docs/source/Benchmarking.rst | 86 +++++++++++++++++++- docs/source/Getting-Started-with-GCPy.rst | 26 +++++- docs/source/Guide-to-Useful-Capabilities.rst | 2 +- docs/source/Regridding.rst | 6 ++ 4 files changed, 115 insertions(+), 5 deletions(-) diff --git a/docs/source/Benchmarking.rst b/docs/source/Benchmarking.rst index 66d03d44..1d6b2f7a 100644 --- a/docs/source/Benchmarking.rst +++ b/docs/source/Benchmarking.rst @@ -1174,13 +1174,94 @@ inventory) from the output of GEOS-Chem benchmark simulations. """ +.. _bmk-funcs-table-mass: + +make_benchmark_mass_tables +-------------------------- + +This function creates tables of total mass for species in two +different GEOS-Chem benchmark simulations. + +.. code-block:: python + + 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=None, + dev_met_extra=None + ): + """ + Creates a text file containing global mass totals by species and + category for benchmarking purposes. + + Args: + 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 Args (optional): + 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: '' + """ + .. _bmk-funcs-table-accum: make_benchmark_mass_accumulation_tables --------------------------------------- -This function creates tables of total mass for species in two -different data set from GEOS-Chem benchmark simulation output. +This function creates tables of mass accumulation over time for species in two +different GEOS-Chem benchmark simulations. .. code-block:: python @@ -1260,6 +1341,7 @@ different data set from GEOS-Chem benchmark simulation output. YAML file called "species_database.yml". """ + .. _bmk-funcs-table-cons: make_benchmark_mass_conservation_table diff --git a/docs/source/Getting-Started-with-GCPy.rst b/docs/source/Getting-Started-with-GCPy.rst index a2824ec8..6fe74133 100644 --- a/docs/source/Getting-Started-with-GCPy.rst +++ b/docs/source/Getting-Started-with-GCPy.rst @@ -226,7 +226,7 @@ Linux and Windows Subsystem for Linux - Press ENTER to confirm the location - Press CTRL-C to abort the installation - Or specify a different location below - [/home/bob/mambaforge] >>> + [/home/YOUR-USER-NAME/mambaforge] >>> In most cases, it should be OK to accept the default installation location. But on some systems, users may be encouraged to install @@ -366,7 +366,7 @@ Follow these steps: locations of Python libraries on your system that were not installed by :program:`Mamba`. - Add the path to your GCPy source code folder :file:`~/.bashrc` file: + Add the path to your GCPy source code folder :file:`~/.bashrc` file: .. code-block:: bash @@ -381,6 +381,28 @@ Follow these steps: to apply the change. |br| |br| +#. **Set the** :envvar:`MPLBACKEND` **environment variable** + + The environment variable :envvar:`MPLBACKEND` specifies the X11 + backend that the Matplotlib package will use to render plots to the + screen. + + Add this line to your :file:`~/.bashrc` file on your local PC/Mac + and on any remote computer systems where you will use GCPy: + + .. code-block:: bash + + export MPLBACKEND=tkagg + + And then use: + + .. code-block:: console + + $ source ~/.bashrc + + to apply the change. |br| + |br| + #. **Perform a simple test:** Run the following commands in your terminal to check if the diff --git a/docs/source/Guide-to-Useful-Capabilities.rst b/docs/source/Guide-to-Useful-Capabilities.rst index 04c6383c..473adb5c 100644 --- a/docs/source/Guide-to-Useful-Capabilities.rst +++ b/docs/source/Guide-to-Useful-Capabilities.rst @@ -215,7 +215,7 @@ Regridding .. _capabilities-regridding-rules: -General eegridding rules +General regridding rules ------------------------ GCPy supports regridding between all horizontal GEOS-Chem grid types, diff --git a/docs/source/Regridding.rst b/docs/source/Regridding.rst index 7b4ccd09..4a4eac4e 100644 --- a/docs/source/Regridding.rst +++ b/docs/source/Regridding.rst @@ -51,6 +51,12 @@ directly from the command line (:ref:`see the examples below `) or from a Python script or interpreter (:code:`gcpy.file_regrid.file_regrid()`) +.. note:: + + For regridding to or from GCHP stretched-grid restart files, we + recommend using the :ref:`offline regridding weights method + `. + The syntax of :code:`file_regrid` is as follows: .. code-block:: python