Skip to content

Commit

Permalink
Merge "docs/dev" branch into HEMCO 3.9.2 development stream.
Browse files Browse the repository at this point in the history 
This merge brings documentation updates for the HEMCO 3.9.2 release
from the docs/dev branch into the HEMCO 3.9.2 development stream.

Updates in geos-chem-shared-docs include:
- Updated photolysis section (to reference Cloud-J)
- New Supplemental Guide for GEOS-Chem input data on AWS
- Updated the "View Related documentation" supplemental guide

Updates in docs/source include:
- Changing option tags to subsections in the HEMCO configuration
  documentation and elsewhere, so that they show up in the nav bar
- Updating references from option tags to subsections
- Fixing broken links
- Updating the CONTRIBUTING.md file to instruct users to update
  the CHANGELOG when submitting updates

Also updated the CHANGELOG.md file accordingly

Signed-off-by: Bob Yantosca <[email protected]>
  • Loading branch information
@yantosca
yantosca committed Jul 24, 2024
2 parents 40066bc + 0a610d2 commit 3ecbb3b
Show file tree
Hide file tree
Showing 13 changed files with 1,492 additions and 1,251 deletions.
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased] - TBD
### Changed
- RTD updates: Converted several `:option:` tags to subsections and updated references accordingly

### Fixed
- Typos in RTD doc file `docs/source/hco_ref_guide/hemco-config.rst`

### Removed
- Manual `InvMEGAN` diagnostics from `src/Extensions/hcox_megan_mod.F90`; Activate these with `HEMCO_Diagn.rc` instead

Expand Down
43 changes: 38 additions & 5 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,25 +3,58 @@
Thank you for looking into contributing to HEMCO! HEMCO is a grass-roots model that relies on contributions from community members like you. Whether you're new to HEMCO or a longtime user, you're a valued member of the community, and we want you to feel empowered to contribute.

## We use GitHub and ReadTheDocs
We use GitHub to host the HEMCO source code, to track issues, user questions, and feature requests, and to accept pull requests: [https://github.com/geoschem/geos-chem](https://github.com/geoschem/HEMCO). Please help out as you can in response to issues and user questions.
We use GitHub to host the HEMCO source code, to track issues, user questions, and feature requests, and to accept pull requests: [https://github.com/geoschem/HEMCO](https://github.com/geoschem/HEMCO). Please help out as you can in response to issues and user questions.

HEMCO documentation can be found at [hemco.readthedocs.io](https://hemco.readthedocs.io).

## When should I submit updates?

Submit bug fixes right away, as these will be given the highest priority. Please see **[Support Guidelines](https://hemco.readthedocs.io/en/stable/reference/SUPPORT.html)** for more information.

Submit updates (code and/or data) for mature model developments once you have submitted a paper on the topic.

## How can I submit updates?
We use [GitHub Flow](https://guides.github.com/introduction/flow/index.html), so all changes happen through pull requests. This workflow is [described here](https://guides.github.com/introduction/flow/index.html).
We use **GitHub Flow**, so all changes happen through [pull requests](https://help.github.com/articles/creating-a-pull-request/). This workflow is [described here](https://docs.github.com/en/get-started/using-github/github-flow).

As the author you are responsible for:
- Testing your changes
- Updating the user documentation (if applicable)
- Supporting issues and questions related to your changes

### Coding conventions
The HEMCO codebase dates back several years and includes contributions from many people and multiple organizations. Therefore, some inconsistent conventions are inevitable, but we ask that you do your best to be consistent with nearby code.
The HEMCO codebase dates back several decades and includes contributions from many people and multiple organizations. Therefore, some inconsistent conventions are inevitable, but we ask that you do your best to be consistent with nearby
code.

### Checklist for submitting code updates

1. Use Fortran-90 free format instead of Fortran-77 fixed format.
2. Include thorough comments in all submitted code.
3. Include full citations for references at the top of relevant source code modules.
4. Check that you have updated the `CHANGELOG.md` file.
5. Remove extraneous code updates (e.g. testing options, other science).
6. Submit any related code or configuration files for [GCHP](https://gchp.readthedocs.io) along with code or configuration files for [GEOS-Chem Classic](https://geos-chem.readthedocs.io).

### Checklist for submitting data files

1. Choose a final file naming convention before submitting data files for inclusion to GEOS-Chem.
2. Make sure that all netCDF files [adhere to the COARDS conventions](https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/coards-guide.html).
3. [Concatenate netCDF files](https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/netcdf-guide.html#concatenate-netcdf-files) to reduce the number of files that need to be opened. This results in more efficient I/O operations.
4. [Chunk and deflate netCDF](https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/netcdf-guide.html#chunk-and-deflate-a-netcdf-file-to-improve-i-o) files in order to improve file I/O.
5. Include an updated [HEMCO configuration file](https://hemco.readthedocs.io/en/latest/hco-ref-guide/hemco-config.html) corresponding to the new data.
6. Include a README file detailing data source, contents, etc.
7. Include script(s) used to process original data.
8. Include a summary or description of the expected results (e.g. emission totals for each species).

Also follow these additional steps to ensure that your data can be read by GCHP:

1. All netCDF data variables should be of type `float` (aka `REAL*4`) or `double` (aka `REAL*8`).
2. Use a recent reference datetime (i.e. after `1900-01-01`) for the netCDF `time:units` attribute.
3. The first time value in each file should be 0, corresponding with the reference datetime.

## How can I request a new feature?
We accept feature requests through issues on GitHub. To request a new feature, **[open a new issue](https://github.com/geoschem/hemco/issues/new/choose)** and select the feature request template. Please include your name, institution, motivation for the feature, and all other relevant information.
We accept feature requests through issues on GitHub. To request a new feature, **[open a new issue](https://github.com/geoschem/HEMCO/issues/new/choose)** and select the feature request template. Please include all the information that migth be relevant, including the motivation for the feature.

## How to report a bug
## How can I report a bug?
Please see **[Support Guidelines](https://hemco.readthedocs.io/en/stable/reference/SUPPORT.html)**.

## Where can I ask for help?
Expand Down
2 changes: 1 addition & 1 deletion docs/source/geos-chem-shared-docs
Submodule geos-chem-shared-docs updated 6 files
+132 −0 supplemental-guides/data-on-aws.rst
+25 −0 supplemental-guides/geos-chem-input-data-on-aws.rst
+90 −0 supplemental-guides/getting-started-aws.rst
+14 −14 supplemental-guides/related-docs.rst
+5 −3 supplemental-guides/using-kpp-with-gc.rst
+21 −0 supplemental-guides/why-on-cloud.rst
17 changes: 9 additions & 8 deletions docs/source/hco-ref-guide/basic-examples.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -187,9 +187,9 @@ changed since :ref:`the previous example <edit-hco-cfg-ex1>`.

Note the increased hierarchy (:literal:`2`) of the regional EMEP
inventory compared to the global MACCity emissions (:literal:`1`) in
column :option:`Hier`. This will cause the EMEP emissions to replace
the MACCity emissions in the region where EMEP is defined, which is
specified by the MASK_EUROPE variable.
column :ref:`hco-cfg-base-hier`. This will cause the EMEP emissions to
replace the MACCity emissions in the region where EMEP is defined,
which is specified by the MASK_EUROPE variable.

.. _edit-hco-cfg-ex3:

Expand Down Expand Up @@ -232,9 +232,10 @@ modify the :ref:`configuration file <hco-cfg>` accordingly:
### END SECTION BASE EMISSIONS ###
Note the change in the emission category (column :option:`Cat`) from
:literal:`1` to :literal:`2`. In this example, category 1 represents
anthropogenic emissions and category 2 represents aircraft emissions.
Note the change in the emission category (column
:ref:`hco-cfg-base-cat`) from :literal:`1` to :literal:`2`. In this
example, category 1 represents anthropogenic emissions and category 2
represents aircraft emissions.

.. _edit-hco-cfg-ex4:

Expand All @@ -251,8 +252,8 @@ implemented as a HEMCO Extension, can be added to the simulation by:
Emissions**.

The extension number defined in the **Extension Switches** section
must match the corresponding :option:`ExtNr` entry in the Base
Emissions section (in this example, :literal:`111`).
must match the corresponding :ref:`hco-cfg-ext-switches-extnr` entry
in the Base Emissions section (in this example, :literal:`111`).

.. code-block:: kconfig
Expand Down
145 changes: 62 additions & 83 deletions docs/source/hco-ref-guide/diagnostics.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ Overview
HEMCO diagnostics are organized in **collections**, with each
collection consisting of a dynamic number of diagnostic fields (aka
**diagnostic containers**). Each collection has a fixed output
frequency (:option:`DiagnFreq`) assigned to it. All fields within a
collection are written out at the same interval: :option:`Hourly`,
:option:`Daily`, etc.
frequency (:ref:`hco-cfg-set-diagnfreq`) assigned to it. All fields
within a collection are written out at the same interval:
:literal:`Hourly`, :literal:`Daily`, etc.

The contents of a collection (i.e. the diagnostics containers) are
defined at the beginning of a simulation and become continuously updated
Expand All @@ -39,21 +39,17 @@ averaging method.

Currently supported averaging methods are:

.. option:: instantaneous

Instantaneous values (recommended method).

.. option:: mean

Arithmetic mean over the diagnostic interval.

.. option:: sum

Total sum over the diagnostic interval.

.. option:: cumulsum

Cumulative sum since simulation start.
+-------------------+------------------------------------------------+
| Value | What it does |
+===================+================================================+
| ``instantaneous`` | Instantaneous values (recommended method). |
+-------------------+------------------------------------------------+
| ``mean`` | Arithmetic mean over the diagnostic interval. |
+-------------------+------------------------------------------------+
| ``sum`` | Total sum over the diagnostic interval. |
+-------------------+------------------------------------------------+
| ``cumulsum`` | Cumulative sum since simulation start. |
+-------------------+------------------------------------------------+

Explicitly setting the averaging method will disable automatic unit
conversion and the fields passed to this diagnostic will be stored as
Expand Down Expand Up @@ -87,28 +83,27 @@ The Default collection
The **Default** collection contains emission diagnostics intended to
be written to disk, e.g. for analysis purposes. All fields of the
default collection are written out at the frequency provided in
setting :option:`DiagnFreq` in the settings section of the HEMCO
configuration file. The name of the corresponding diagnostics files
can be specified via the :code:`DiagnPrefix` setting. The simulation
date at the time of output will be appended to the diagnostics prefix,
e.g. the diagnostics for Aug 1, 2008 will be written as
:file:`HEMCO_Diagnostics.200808010000.nc`. The datetime can denote
the beginning, middle, or end (default) of the time interval, as
specified by setting :option:`DiagnTimeStamp` (see below).

Several :ref:`options for the default diagnostic collection
<hco-cfg-settings-diagnostics>` can be specified at the top of the
:ref:`HEMCO configuration file <hco-cfg>` file. Commonly-used options
are :option:`DiagnFile`, :option:`DiagnFreq`, and
:option:`DiagnPrefix`.
setting :ref:`hco-cfg-set-diagnfreq` in the settings section of the
HEMCO configuration file. The name of the corresponding diagnostics files
can be specified via the :ref:`hco-cfg-set-diagnprefix` setting. The
simulation date at the time of output will be appended to the
diagnostics prefix, e.g. the diagnostics for Aug 1, 2008 will be
written as :file:`HEMCO_Diagnostics.200808010000.nc`. The datetime
can denote the beginning, middle, or end (default) of the time
interval, as specified by setting ::ref:`hco-cfg-set-diagntimestamp`.

Several options for the default diagnostic collection can be specified
at the top of the :ref:`HEMCO configuration file <hco-cfg>` file.
Commonly-used options are :ref:`hco-cfg-set-diagnfile`,
:ref:`hco-cfg-set-diagnfreq`, and :ref:`hco-cfg-set-diagnprefix`.

.. _hco-diag-configfile:

Configuration file for the Default collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You may specify the name of the Default diagnostics configuration file
with the :option:`DiagnFile` option in :ref:`the
with the :ref:`hco-cfg-set-diagnfile` option in :ref:`the
HEMCO configuration file <hco-cfg>`. This file, which is customarily
named :file:`HEMCO_Diagn.rc`, uses the following format:

Expand All @@ -119,58 +114,42 @@ named :file:`HEMCO_Diagn.rc`, uses the following format:
The columns of :file:`HEMCO_Diagn.rc` allow you to specify several options:

.. option:: Name

netCDF variable name under which this diagnostic quantity will be
named in the HEMCO diagnostic output files.

.. option:: Spec

Species short name (same as in :ref:`the HEMCO configuration file
<hco-cfg>`) .

.. option:: ExtNr

Extension number (same as in :ref:`the HEMCO configuration file
<hco-cfg>`) .

The :literal:`-1` value means to sum over all extensions.

.. option:: Cat

Category (same as in :ref:`the HEMCO configuration file
<hco-cfg>`).

The :literal:`-1` value means to sum over all categories.

.. option:: Hier

Hierarchy (same as in :ref:`the HEMCO configuration file
<hco-cfg>`).

The :literal:`-1` value means to sum over all categories.

.. option:: Dim

Number of dimensions that you wish this diagnostic to have:

- :literal:`1`: Scalar
- :literal:`2`: Lat-lon or X-Y
- :literal:`3`: Lat-lon-lev or X-Y-Z

.. option:: LongName

A longer descriptive name for the diagnostic. This will be used to
define the netCDF :literal:`long_name` variable attribute in the
HEMCO diagnostic files.
+---------------+------------------------------------------------------------------+
| Option | What it does |
+===============+==================================================================+
| ``Name`` | netCDF variable name under which this diagnostic quantity will |
| | stored in the HEMCO diagnostic output files. |
+---------------+------------------------------------------------------------------+
| ``Spec`` | :ref:`Species short name <hco-cfg-base-species>` as listed in |
| | :ref:`the HEMCO configuration file <hco-cfg>`. |
+---------------+------------------------------------------------------------------+
| ``ExtNr`` | :ref:`Extension number <hco-cfg-ext-switches-extnr>`. |
| | The :literal:`-1` value means to sum over all extensions. |
+---------------+------------------------------------------------------------------+
| ``Cat`` | :ref:`Emission Category <hco-cfg-base-cat>`. |
| | The :literal:`-1` value means to sum over all categories. |
+---------------+------------------------------------------------------------------+
| ``Hier`` | :ref:`Emission Hierarchy <hco-cfg-base-hier>`. |
| | The :literal:`-1` value means to sum over all hierarchies. |
+---------------+------------------------------------------------------------------+
| ``Dim`` | Number of dimensions that you wish this diagnostic to have: |
| | |
| | - :literal:`1`: Scalar |
| | - :literal:`2`: Lat-lon or X-Y |
| | - :literal:`3`: Lat-lon-lev or X-Y-Z |
+---------------+------------------------------------------------------------------+
| ``LongName`` | A longer descriptive name for the diagnostic. This will define |
| | the netCDF :literal:`long_name` variable attribute in the |
| | HEMCO diagnostic files. |
+---------------+------------------------------------------------------------------+

Here are a few examples.

#. **Basic usage**

Adding these entries to :file:`HEMCO_Config.rc` will make HEMCO write
out total NO and CO emissions, as well as GFED biomass burning CO
emissions (e.g. only emissions from :option:`ExtNr` 111):
emissions (e.g. only emissions from :ref:`hco-cfg-ext-switches-extnr` 111):

.. code-block:: kconfig
Expand All @@ -182,10 +161,10 @@ Here are a few examples.
#. **Archive diagnostics for regional emissions**

To diagnose regional emissions, you must set :option:`ExtNr`,
:option:`Cat`, and :option:`Hier` accordingly. The example below
defines a diagnostic entry for CO emissions from the EPA16 USA
inventory:
To diagnose regional emissions, you must set
:ref:`hco-cfg-ext-switches-extnr`, :ref:`hco-cfg-base-cat`, and
:ref:`hco-cfg-base-hier` accordingly. The example below defines
a diagnostic entry for CO emissions from the EPA16 USA inventory:

.. code-block:: kconfig
Expand Down Expand Up @@ -262,7 +241,7 @@ Importing diagnostic content into an external model

The content of the :ref:`Default collection <hco-diag-default>` can
be specified through the HEMCO diagnostics definitions file (specified
by the :option:`DiagnFile` option).
by the :ref:`hco-cfg-set-diagnfile` option).

The content of the :ref:`Manual <hco-diag-manual>` and
:ref:`Restart <hco-diag-restart>` collections currently need to
Expand Down
Loading

0 comments on commit 3ecbb3b

Please sign in to comment.