Skip to content

Commit

Permalink
Additional ReadTheDocs updates for 14.4.0
Browse files Browse the repository at this point in the history 
- Add descriptions of Cloud-J, HETP, geos-chem-shared-docs submodules
- Updated doc about data portals
- Add info about the AWS S3 Explorer
- Replace "CH4" with "carbon" simulation
- Update geoschem-config.yml doc
- Restored history.rst page to point to supplemental guide
- Added references for Cloud-J and HETP to bibliography
- Updated folder tree
- Now point to HISTORY.rc section in history-diag-guide.rst

Signed-off-by: Bob Yantosca <[email protected]>
  • Loading branch information
@yantosca
yantosca committed May 16, 2024
1 parent ef7af4d commit 53faa34
Show file tree
Hide file tree
Showing 26 changed files with 495 additions and 525 deletions.
114 changes: 65 additions & 49 deletions docs/source/gcclassic-user-guide/compile-cmake.rst
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
.. |br| raw:: html

<br/>

.. _compile-cmake:

####################
Expand Down Expand Up @@ -142,11 +146,12 @@ build's configuration.
The text :literal:`X.Y.Z`, :literal:`A.B.C`, :literal:`D.E.F.`,
and :literal:`G`
refer to the version numbers (in `semantic versioning
<https://semver.org>`_ style) of the GCClassic, HEMCO, HETP,
and Cloud-J repositories.
<https://semver.org>`_ style) of the :ref:`get-code-repos-gcclassic`,
:ref:`get-code-repos-hemco`, :ref:`get-code-repos-other-hetp`, and
:ref:`get-code-repos-other-cloudj` repositories, respectively.

The GEOS-Chem "science codebase" repository and GCClassic
repository wrapper share the same version number :literal:`X.Y.Z`.
The :ref:`get-code-repos-gc-sci` and GCClassic repositories share
the same version number :literal:`X.Y.Z`.


.. _compile-cmake-step4:
Expand Down Expand Up @@ -341,7 +346,8 @@ options, unless you explicitly specify otherwise.
.. option:: FASTJX

Configures GEOS-Chem to use the legacy FAST-JX v7.0 photolysis
mechanism instead of its successor Cloud-J.
mechanism instead of its successor
:ref:`get-code-repos-other-cloudj`.

.. note::

Expand Down Expand Up @@ -411,64 +417,73 @@ Understand CMake output
=======================

As you can see from the example CMake output listed above, GEOS-Chem
Classic contains code from 3 independent repositories:
Classic contains code from the various repositories:

1. `GCClassic wrapper (aka "the superproject") <https://github.com/geoschem/GCClassic.git>`_:
#. `GCClassic wrapper (aka "the superproject") <https://github.com/geoschem/GCClassic.git>`_:

.. code-block:: none
.. code-block:: none
=================================================================
GCClassic X.Y.Z (superproject wrapper)
Current status: X.Y.Z
=================================================================
=================================================================
GCClassic X.Y.Z (superproject wrapper)
Current status: X.Y.Z
=================================================================
where :literal:`X.Y.Z` specifies the GEOS-Chem Classic "major",
"minor", and "patch" version numbers.
where :literal:`X.Y.Z` specifies the GEOS-Chem Classic "major",
"minor", and "patch" version numbers.

.. note::
.. note::

If you are cloning GEOS-Chem Classic between official releases, you
may the see :code:`Current status` reported like this:

.. code-block:: console
X.Y.Z-alpha.n-C-gabcd1234.dirty or
X.Y.Z.rc.n-C.gabcd1234.dirty
We will explain these formats below.

2. `HEMCO (Harmonized Emissions Component) submodule <https://github.com/geoschem/hemco.git>`_:

.. code-block:: none
=================================================================
HEMCO A.B.C
Current status: A.B.C
=================================================================
where :literal:`A.B.C` specifies the HEMCO "major", "minor", and
"patch" version numbers. The HEMCO version number differs from
GEOS-Chem because it is kept in a separate repository, and is
considered a separate package.

3. `GEOS-Chem submodule <https://github.com/geoschem/geos-chem.git>`_:

.. code-block:: none
=================================================================
GEOS-Chem X.Y.Z (science codebase)
Current status: X.Y.Z
=================================================================
The GEOS-Chem science codebase and GEOS-Chem Classic wrapper will
always share the same version number.

During the build configuration stage, CMake will display the **version
number** (e.g. :literal:`X.Y.Z`) as well as the **current status of the Git
repository** (e.g. :literal:`TAG-C-gabcd1234.dirty`) for GCClassic,
GEOS-Chem, and HEMCO.

We will explain these formats below. |br|
|br|

#. `HEMCO (Harmonized Emissions Component) submodule <https://github.com/geoschem/hemco.git>`_:

.. code-block:: none
=================================================================
HEMCO A.B.C
Current status: A.B.C
=================================================================
where :literal:`A.B.C` specifies the HEMCO "major", "minor", and
"patch" version numbers. The HEMCO version number differs from
GEOS-Chem because it is kept in a separate repository, and is
considered a separate package. |br|
|br|

#. `GEOS-Chem submodule <https://github.com/geoschem/geos-chem.git>`_:

.. code-block:: none
=================================================================
GEOS-Chem X.Y.Z (science codebase)
Current status: X.Y.Z
=================================================================
The GEOS-Chem science codebase and GEOS-Chem Classic wrapper will
always share the same version number.

During the build configuration stage, CMake will display the **version
number** (e.g. :literal:`X.Y.Z`) as well as the **current status of the Git
repository** (e.g. :literal:`TAG-C-gabcd1234.dirty`) for GCClassic,
GEOS-Chem, and HEMCO. |br|
|br|

#. Similar messages will be displayed for the
:ref:`get-code-repos-other-cloudj` and
:ref:`get-code-repos-other-hetp` repositories. |br|
|br|


Let's take the Git repository status of GCClassic as our example. The
status string uses the same format as the :command:`git describe
--tags` command, namely:
Expand Down Expand Up @@ -514,3 +529,4 @@ where

Under each header are printed the various :ref:`options that have been
selected <cfg>`.

42 changes: 22 additions & 20 deletions docs/source/gcclassic-user-guide/dry-run-download.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,13 @@ several locations, which are described in the following sections.
Choose a data portal
====================

You can download input data data from one of the following locations:
You can :ref:`download input data <data>` from one of the following
locations:

.. _dry-run-download-washu:

The geoschemdata.wustl.edu site (aka WashU)
---------------------------------------------
The :file:`geoschemdata.wustl.edu` site (aka WashU)
---------------------------------------------------

If you are using GEOS-Chem on your institutional computer cluster, we
recommend that you **download data from the WashU (Washington
Expand All @@ -64,12 +65,12 @@ for GEOS-Chem.

.. _dry-run-download-aws:

The s3://gcgrid bucket (aka Amazon)
-----------------------------------
The :file:`s3://gcgrid` bucket (aka Amazon)
-------------------------------------------

If you are running GEOS-Chem Classic on the Amazon Web Services cloud,
you can quickly **download the necessary data for your GEOS-Chem
simulation from the :file:`s3://gcgrid` bucket** to the Elastic Block
simulation from the** :file:`s3://gcgrid` **bucket** to the Elastic Block
Storage (EBS) volume attached to your cloud instance.

Navigate to your GEOS-Chem Classic run directory and type:
Expand All @@ -83,22 +84,23 @@ commands, which should execute much more quickly than if you were to
download the data from another location. It will also produce a
**log of unique data files**.

.. important::
.. note::

Copying data from :file:`s3://gcgrid` to the EBS volume of an
Amazon EC2 cloud instance is always free. But if you download data
from :file:`s3://gcgrid` to your own computer system, you will
incur an egress fee. **PROCEED WITH CAUTION!**
Downloading from the Amazon Data Portal will NOT incur any
egress charges. This is because the data is covered under the
`AWS Open Data Sponsorship Program
<https://aws.amazon.com/opendata/?wwps-cards.sort-by=item.additionalFields.sortDate&wwps-cards.sort-order=desc>`_.

.. _dry-run-download-rochester:

The atmos.earth.rochester.edu site (aka Rochester)
----------------------------------------------------
The :file:`atmos.earth.rochester.edu` site (aka Rochester)
----------------------------------------------------------

The U. Rochester site (which is maintained by Lee Murray's research
there) contains the GCAP 2.0 met field data. This met field data is
useful if you wish to perform simulations stretching back into the
preindustrial period, or running into the future.
The U. Rochester site (which is maintained by Lee Murray's (GitHub:
:literal:`@ltmurray`) research there) contains the GCAP 2.0 met field
data. This met field data is useful if you wish to perform
simulations stretching back into the preindustrial period, or running
into the future.

To download data from the Rochester site, type:

Expand All @@ -108,9 +110,9 @@ To download data from the Rochester site, type:
.. _dry-run-download-data:

======================================================
Run the download_data.py script on the dryrun log file
======================================================
==============================================================
Run the :file:`download_data.py` script on the dryrun log file
==============================================================

Navigate to your GEOS-Chem run directory where you executed the dry-run
and type:
Expand Down
8 changes: 4 additions & 4 deletions docs/source/gcclassic-user-guide/dry-run-run.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ files <cfg>`:
.. option:: geoschem_config.yml

#. :option:`start_date`: Set the start date and time for your simulation.
#. :option:`end_date`: Setthe end date and time for your simulation.
#. :option:`end_date`: Set the end date and time for your simulation.
#. :option:`met_field`: Check if the meteorology setting
(:option:`GEOS-FP`, :option:`MERRA2`, :option:`GCAP2`) is
correct for your simulation.
Expand All @@ -40,9 +40,9 @@ files <cfg>`:

.. option:: HISTORY.rc

#. Set the frequency and duration for the :ref:`HISTORY diagnostic
<history-diagnostics>` collections to be consistent with the
settings in :option:`geoschem_config.yml`.
#. Set the frequency and duration for each :ref:`diagnostic
collection <histguide-collections>` to be consistent with the
settings in :option:`geoschem_config.yml`.

.. option:: HEMCO_Config.rc

Expand Down
6 changes: 3 additions & 3 deletions docs/source/gcclassic-user-guide/dry-run.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ Download data with a dry-run simulation
have already been downloaded and stored in a commmon directory on
your system. Ask your sysadmin or IT support staff.

Another way to download and manage GEOS-Chem input data is with the
:ref:`bashdatacatalog <bashdatacatalog>` tool.
Please see our :ref:`input-overview` chapter for other ways in
which you can download the necessary input data for GEOS-Chem.

A "dry-run" is a is a :program:`GEOS-Chem Classic` simulation that
steps through time, but does not perform computations or read data
Expand All @@ -23,7 +23,7 @@ or if it is missing. This output can be fed to a script which will
download the missing data files to your computer system.

You may generate dry-run output for any of the GEOS-Chem Classic
simulation types (:option:`fullchem`, :option:`CH4`,
simulation types (:option:`fullchem`, :option:`carbon`,
:option:`TransportTracers`, etc.)

In the following chapters, you will learn how to you can download data
Expand Down
Loading

0 comments on commit 53faa34

Please sign in to comment.