GCPy: The GEOS-Chem Python toolkit

Welcome to the GCPy ReadTheDocs documentation! This site provides documentation on the functionality of GCPy and instructions for common use cases.

GCPy is a Python-based toolkit containing useful functions for working specifically with the GEOS-Chem model of atmospheric chemistry and composition. GCPy is primarily used for plotting/tabling GEOS-Chem output and regridding input files in special cases.

For documentation on setting up and running GEOS-Chem please see our list of manuals for GEOS-Chem and related software.

Overview

• About GCPy
  • What GCPy was intended to do
  • What GCPy was not intended to do
  • License
  • Requesting support
  • Submitting new features
• Installing GCPy
  • Requirements
    • Platforms
    • Software dependencies
  • Methods for installing GCPy
  • Install GCPy from conda-forge
    • 1. Create and activate a Python virtual environment
    • 2. Install GCPy with Conda
    • 3. Verify the installation
    • 4. Deactivate the Python environment
  • Download GCPy with Git and build a Python virtual environment
    • Install GCPy and its dependencies
      • 1. Download the GCPy source code
      • 2. Create a new Python virtual environment for GCPy
      • 3. Add GCPy to PYTHONPATH
      • 4. Set the MPLBACKEND environment variable
      • 5. Perform a simple test
    • Upgrading GCPy versions
• Specify backend for Matplotlib
  • For MacOSX
  • For Linux
• Overview of Capabilities
  • Spatial plotting
    • Single panel plots
    • Six-panel comparison plots
    • Comprehensive benchmark plotting
  • Table creation
    • Budget tables
    • Mass tables
    • Emissions tables
  • Regridding
    • General regridding rules

Using GCPy

• Plotting
  • Six-panel comparison plots
    • Panels with nothing to show
    • Function compare_single_level
    • Function compare_zonal_mean
    • Shared structure
    • Example script
  • Single panel plots
• Regridding
  • Using Online Regridding Weights
    • Examples
  • Using Offline Regridding Weights
    • Example 1: Standard Lat-Lon to Cubed-Sphere Regridding
    • Example 2: Standard Cubed-Sphere to Cubed-Sphere Regridding
    • Example 3: Standard to Stretched Cubed-Sphere Regridding
  • Regridding for Plotting in GCPy
    • Pass stretched-grid file paths
    • Pass vertical grid parameters for non-72/47-level grids
    • Automatic regridding decision process
• Benchmarking
  • Location of benchmark plotting scripts
  • Observational data used for 1-year fullchem benchmarks
  • Steps to create benchmark plots
  • Benchmark plotting functions
  • Benchmark tabling functions
  • Standalone benchmark utility scripts
    • benchmark_gcclassic_stats.py
    • benchmark_gchp_stats.py
    • benchmark_species_changes.py

Examples

• Create a Test Plot
• Single Panel Plotting
• Six Panel Plotting
• Compare diagnostic outputs
• Plotting output from code profilers
• Check GCHP emission diagnostics
• Display GEOS-Chem Classic grid info
• Visualizing KPP-Standalone box model output
• Example scripts for use with HEMCO
• GEOS-Chem Support Team (GCST) utility scripts

Community Contributions

• Format netCDF files for input to HEMCO
  • Source code
  • Usage
• Create a coordinates file for the GEOS-Chem ObsPack diagnostic
  • Source code
  • Usage

Supplemental Guides

• Install the Conda Python package manager
  • Check if Conda is already installed
  • Install the Miniforge distribution

GCPy API

• API Reference

Help & Reference

• Known bugs and issues
• Contributing Guidelines
• Support Guidelines
• Editing this User Guide
• Releasing new versions (GCST only)