Skip to content

Commit

Permalink
RTD updates: Install via Pip, Fix broken refs, Update release guide
Browse files Browse the repository at this point in the history 
docs/source/Getting-Started-with-GCPy.rst
- Add instructions for installation via Pip (for most users), and
  keep instructions for installation from Git w/ Mamba/Conda (for
  developers.
- Updated ref links as necesary

docs/source/Guide-to-Useful-Capabilities.rst
- Update benchmark section
- Update ref links

docs/source/Regridding.rst
- Fix broken ref link

docs/source/Release-Guide
- Add info about using .release/changeVersionNumbers.sh
- Add info about GitHub action push to PyPi

docs/source/index.rst
- Change maxdepth from 3 to 4 in Overview section

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>
  • Loading branch information
@yantosca
yantosca committed May 29, 2024
1 parent ceeb4c9 commit 6d7436a
Show file tree
Hide file tree
Showing 5 changed files with 134 additions and 104 deletions.
115 changes: 84 additions & 31 deletions docs/source/Getting-Started-with-GCPy.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,11 @@

<br/>

.. _install:

###############
Installing GCPy
###############

.. _requirements:
.. _install:

============
Requirements
Expand All @@ -20,7 +18,63 @@ Requirements
#. Windows Subsystem for Linux (running in Microsoft Windows 11)
#. MacOS

To install GCPy, you will need:
You may choose one of the following methods to install GCPy on your
system.

.. _install-pip:

=================================
For most users: Install from PyPi
=================================

If you only plan on using GCPy for visualization of GEOS-Chem
simulation results, we recommend that you install GCPy from the
:program:`Python
Package Index (PyPi)` using the `Pip installer
<https://pypi.org/project/pip/>`_.

If your system does not already have Pip installed, you may install it
with the `get-pip.py
<https://pip.pypa.io/en/stable/installation/#get-pip-py>`_ script.

.. _install-pip-first:

First-time installation with Pip
--------------------------------

Once you are sure that Pip is installed, you may proceed to download
GCPy with this command:

.. code-block:: console
$ pip install geoschem-gcpy
To validate the installation, we recommend running the
:ref:`test-plot` example scruot,

.. _install-pip-update:

Updating to a newer version with Pip
------------------------------------

Use this command to update an existing GCPy installation to a newer version:

.. code-block:: console
$ pip install -U geoschem-gcpy
You may now skip ahead to the :ref:`mpl-backend` chapter.

.. _install-dev:

=====================================
For developers: Install GCPy from Git
=====================================

If you plan on actively developing GCPy, we recommend that you install
GCPy from Git and create a :program:`Mamba` or :program:`Conda`
environment. You will also need:

- **EITHER** a distribution of the :program:`Mamba` package manager
- **OR** a distribution of the :program:`Conda` package manager.
Expand All @@ -39,7 +93,7 @@ environment will contain a version of the Python interpreter
with :program:`Conda`. See the following sections for detailed
instructions.

.. _requirements-mamba:
.. _install-dev-req-mamba:

Check if Mamba is installed
---------------------------
Expand All @@ -57,10 +111,10 @@ If :program:`Mamba` has been installed, you will see output similar to this:
mamba version X.Y.Z
conda version A.B.C
If you see this output, you may skip ahead to the :ref:`gcpy-install`
If you see this output, you may skip ahead to the :ref:`install-dev-gcpy-install`
section.

.. _requirements-conda:
.. _install-dev-req-conda:

Check if Conda is installed
---------------------------
Expand All @@ -81,9 +135,9 @@ printed to the screen:
If neither :program:`Conda` or :program:`Mamba` are installed, we
recommend installing the :program:`Mamba` package manager yourself.
Please proceed to the :ref:`mamba-install` section for instructions.
Please proceed to the :ref:`install-dev-mamba-install` section for instructions.

.. _requirements-conda-older:
.. _install-dev-req-conda-older:

Additional setup for older Conda versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -106,13 +160,12 @@ creation considerably.
The :program:`Mamba` environment solver is used by default in
:program:`Conda` 23.7 and later.

You may now skip ahead to the :ref:`gcpy-install` section.
You may now skip ahead to the :ref:`install-dev-gcpy-install` section.

.. _mamba-install:
.. _install-dev-mamba-install:

==================
Install MambaForge
==================
------------------

We recommend installing the :program:`MambaForge`, distribution, which
is a full implementation of :program:`Mamba` (as opposed to the
Expand All @@ -121,7 +174,7 @@ minimal :program:`MicroMamba` distribution).
Follow the instructions below to install :program:`MambaForge`:

MacOS
-----
~~~~~

#. Install :program:`MambaForge` with `Homebrew <https://brew.sh/>`_:

Expand Down Expand Up @@ -149,11 +202,11 @@ MacOS
#. Exit your current terminal session and open a new terminal
session. This will apply the changes.

You may now skip ahead to the :ref:`gcpy-install` section.
You may now skip ahead to the :ref:`install-dev-gcpy-install` section.


Linux and Windows Subsystem for Linux
--------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. Download the :program:`MambaForge` installer script from the
`conda-forge GitHub releases page
Expand Down Expand Up @@ -243,8 +296,9 @@ Linux and Windows Subsystem for Linux
:program:`MambaForge` will downlad and install Python software
packages into the :file:`pkgs` subfolder of the root
installation path. Similarly, when you :ref:`create Python
environments <gcpy-install>`, these will be installed to the
:file:`envs` subfolder of the root installation path.
environments <install-dev-gcpy-install>`, these will be
installed to the :file:`envs` subfolder of the root installation
path.
|br|

Expand All @@ -262,7 +316,7 @@ Linux and Windows Subsystem for Linux
As long as your :envvar:`PYTHONPATH` environment variable only
contains the path to the root-level GCPy folder, you may safely
ignore this. (More on :envvar:`PYTHONPATH` in the :ref:`next
section <gcpy-install>`.) |br|
section <install-dev-gcpy-install>`.) |br|
|br|

#. Tell the installer to initialize :program:`MambaForge`.
Expand All @@ -283,11 +337,10 @@ Linux and Windows Subsystem for Linux
#. Exit your current terminal session. Start a new terminal session
to apply the updates. You are now ready to install GCPy.

.. _gcpy-install:
.. _install-dev-gcpy-install:

=================================
Install GCPy and its dependencies
=================================
---------------------------------

Once you have made sure that :program:`Mamba` (or :program:`Conda`) is
present on your system, you may create a Python environment for GCPy.
Expand Down Expand Up @@ -405,24 +458,24 @@ Follow these steps:

#. **Perform a simple test:**

Run the following commands in your terminal to check if the
installation was succcesful.
Make sure that you have specified the proper :ref:`mpl-backend` for
your system. Then run the following commands in your terminal:

.. code-block:: console
$ source $HOME/.bashrc # Alternatively close and reopen your terminal
$ echo $PYTHONPATH # Check it contains path to your GCPy clone
$ source $HOME/.bashrc # Alternatively close and reopen your terminal
$ echo $PYTHONPATH # Check it contains path to your GCPy clone
$ mamba activate gcpy_env
$ mamba list # Check it contains contents of gcpy env file
$ python
>>> import gcpy
$ mamba list # Check it contains contents of gcpy env file
$ python -m gcpy.examples.create_test_plot # Create a test plot
If the plot appears on your screen, then the GCPy installation was successful.

If no error messages are displayed, you have successfully installed
GCPy and its dependencies.

=======================
Upgrading GCPy versions
=======================
-----------------------

Sometimes the GCPy dependency list changes with a new GCPy version,
either through the addition of new packages or a change in the minimum
Expand Down
60 changes: 35 additions & 25 deletions docs/source/Guide-to-Useful-Capabilities.rst
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
.. |br| raw:: html

<br/>

.. _capabilities:

########################
Overview of Capabilities
########################

This page outlines the capabilities of GCPy with links to detailed
function documentation.
This page outlines the capabilities of :program:`GCPy` with links to
detailed function documentation.

.. _capabilities-spatial:

Expand Down Expand Up @@ -138,17 +142,18 @@ for :code:`compare_single_level()` and :code:`compare_zonal_mean()`.
Comprehensive benchmark plotting
--------------------------------

The GEOS-Chem Support Team uses comprehensive plotting functions from
module :file:`gcpy.benchmark_funcs` to generate full plots of benchmark
diagnostics. Functions like
:ref:`gcpy.benchmark_funcs.make_benchmark_conc_plots()
<bmk-funcs-plot-conc>` by default create plots for every variable
in a given collection (e.g. :literal:`SpeciesConc`) at multiple
vertical levels (surface, 500hPa, zonal mean) and divide plots into
separate folders based on category (e.g. Chlorine, Aerosols). The
GEOS-Chem Support Team uses benchmark plotting and tabling table
scripts (described in our :ref:`Benchmarking <bmk>` chapter) to
produce plots and tables for official model benchmarks.
The `GEOS-Chem Support Team
<https://geoschem.github.io/support-team>`_ uses comprehensive
plotting functions (stored in modules located in the
:file:`gcpy/benchmark/modules` folder) to generate plots and tables
from of diagnostic output of GEOS-Chem benchmark
simulations. Functions like :ref:`bmk-funcs-plot-conc` generate plots
for every variable in a given collection
(e.g. :literal:`SpeciesConc`) at multiple vertical levels (surface,
500hPa, zonal mean) and divide plots into separate folders based on
category (e.g. Chlorine, Aerosols). For more information about the
benchmark plotting and tabling scripts, please see our
:ref:`Benchmarking <bmk>` chapter.

.. _capabilities-table:

Expand All @@ -171,42 +176,47 @@ the GEOS-Chem :literal:`Budget` diagnostics) or in overall averages for
different aerosols or the Transport Tracers simulation.

Operations budget tables are created using the
:ref:`gcpy.benchmark_funcs.make_benchmark_operations_budget()
<bmk-funcs-table-ops>` function and appear as follows:
:ref:`bmk-funcs-table-ops` function and appear as follows:

.. image:: _static/images/budget\_table.png
:align: center

|br|

.. _capabilities-tables-mass:

Mass tables
-----------

The :ref:`gcpy.benchmark_funcs.make_benchmark_mass_tables()
<bmk-funcs-table-mass>` function uses species concentrations and info
from meteorology files to generate the total mass of species in
certain segments of the atmosphere (currently global or only the
The :ref:`bmk-funcs-table-mass` function uses species concentrations
and info from meteorology files to generate the total mass of species
in certain segments of the atmosphere (currently global or only the
troposphere). An example table is shown below:

.. image:: _static/images/mass\_table.png
:align: center

|br|

.. _capabilities-tables-emissions:

Emissions tables
----------------

The :ref:`gcpy.benchmark_funcs.make_benchmark_emis_tables()
<bmk-funcs-table-emis>` function creates tables of total emissions
categorized by species or by inventory. Examples of both emissions
table types are shown below:
The :ref:`bmk-funcs-table-emis` function creates tables of total
emissions categorized by species or by inventory. Examples of both
emissions table types are shown below:

.. image:: _static/images/emissions\_totals.png
:align: center

|br|

.. image:: _static/images/inventory\_totals.png
:align: center

|br|

.. _capabilities-regridding:

==========
Expand Down Expand Up @@ -241,8 +251,8 @@ and B coefficients of the hybrid vertical grid
<wiki.seas.harvard.edu/geos-chem/index.php/GEOS-Chem_vertical_grids>`__.

When plotting data of differing grid types or horizontal resolutions
using :ref:`compare_single_level() <plot-csl>`
or :ref:`compare_zonal_mean() <plot-czm>`, you
using :ref:`compare_single_level <plot-csl>`
or :ref:`compare_zonal_mean <plot-czm>`, you
can specify a comparison resolution using the :literal:`cmpres`
argument. This resolution will be used for the difference panels in
each plot (the bottom four panels rather than the top two raw data
Expand Down
2 changes: 1 addition & 1 deletion docs/source/Regridding.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,7 @@ three stage process:
.. note::

As of GCPy 1.4.0, the :ref:`default GCPy environment
<gcpy_install>` (aka :literal:`gcpy_env`) now contains
<install>` (aka :literal:`gcpy_env`) now contains
:literal:`gridspec` and :literal:`sparselt` packages. You no
longer need to use the separate :literal:`gchp_regridding`
environment as in prior versions.
Expand Down
Loading

0 comments on commit 6d7436a

Please sign in to comment.