Installing GCPy
Requirements
GCPy is currently supported on the following platforms:
Linux (x86_64)
Windows Subsystem for Linux (running in Microsoft Windows 11)
MacOS
You may choose one of the following methods to install GCPy on your system.
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 Python Package Index (PyPi) using the Pip installer.
If your system does not already have Pip installed, you may install it with the get-pip.py script.
First-time installation with Pip
Once you are sure that Pip is installed, you may proceed to download GCPy with this command:
$ pip install geoschem-gcpy
To validate the installation, we recommend running the Create a Test Plot example scruot,
Updating to a newer version with Pip
Use this command to update an existing GCPy installation to a newer version:
$ pip install -U geoschem-gcpy
You may now skip ahead to the Specify backend for Matplotlib chapter.
For developers: Install GCPy from Git
If you plan on actively developing GCPy, we recommend that you install GCPy from Git and create a Mamba or Conda environment. You will also need:
EITHER a distribution of the Mamba package manager
OR a distribution of the Conda package manager.
Mamba is a fast drop-in replacement for the widely-used Conda package manager. We recommend using Mamba to create a Python environment for GCPy. This environment will contain a version of the Python interpreter (in this case, Python 3.9) plus packages upon which GCPy depends.
Note
If your system has an existing Conda installation, and/or you do not wish to upgrade from Conda to Mamba, you may create the Python environment for GCPy with Conda. See the following sections for detailed instructions.
Check if Mamba is installed
Check if you already have Mamba on your system:
$ mamba --version
If 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 Install GCPy and its dependencies section.
Check if Conda is installed
If your system does not have Mamba installed, check if Conda is already present on your system:
$ conda --version
If a Conda version exists, you will see its version number printed to the screen:
conda version A.B.C
If neither Conda or Mamba are installed, we recommend installing the Mamba package manager yourself. Please proceed to the Install MambaForge section for instructions.
Additional setup for older Conda versions
If your Conda version is earlier than 23.7, you will need to do the following additional steps.
$ conda install -n base conda-libmamba-solver
$ conda config --set solver libmamba
This will install the fast Mamba environment solver into your Conda base environment. Using the Mamba solver within Conda will speed up the Python environment creation considerably.
Note
The Mamba environment solver is used by default in Conda 23.7 and later.
You may now skip ahead to the Install GCPy and its dependencies section.
Install MambaForge
We recommend installing the MambaForge, distribution, which is a full implementation of Mamba (as opposed to the minimal MicroMamba distribution).
Follow the instructions below to install MambaForge:
MacOS
Install MambaForge with Homebrew:
$ brew install mambaforge
Initialize Mamba for your shell. Type one of the following commands:
$ mamba init bash # If you use the bash shell (recommended!) $ mamba init zsh # If you use the zsh shell $ mamba init fish # If you use the fish shell
Mamba will add some code to your
~/.bash_profile
startup script that will tell your shell where to look for Python environments.Exit your current terminal session and open a new terminal session. This will apply the changes.
You may now skip ahead to the Install GCPy and its dependencies section.
Linux and Windows Subsystem for Linux
Download the MambaForge installer script from the conda-forge GitHub releases page:
$ wget https://github.com/conda-forge/miniforge/releases/download/23.3.1-0/Mambaforge-23.3.1-0-Linux-x86_64.sh
This will download the MambaForge installer script
Mambaforge-23.3.1-0-Linux-x86_64.sh
to your computer.Note
As of this writing (August 2023), the latest MambaForge version is
23.1.0-0
. If you find that the version has since been updated, simply replace the version number23.3.1-0
in the above command with the most recent version number.Change the permission of the MambaForge installer script so that it is executable.
$ chmod 755 Mambaforge-23.3.1-0-Linux-x86_64.sh
Execute the Mambaforge installer script.
$ ./Mambaforge-23.3.1-0-Linux-x86_64.sh
To update an older version of Mamba, add the
-u
option to the above command.
Review and accept the license agreement.
In order to continue the installation process, please review the license agreement. Please, press ENTER to continue >>>
Press
ENTER
and thenSPACE
until you reach the end of the license agreement. Then you will be asked:Do you accept the license terms? [yes|no] [no] >>>
Type
yes
and hitENTER
.
Specify the root installation path for MambaForge.
Mambaforge will now be installed into this location: /home/YOUR-USER-NAME/mambaforge - Press ENTER to confirm the location - Press CTRL-C to abort the installation - Or specify a different location below [/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 software into a different location (e.g. if there is a faster filesystem available than the home directory filesystem). Consult your sysadmin or IT staff if you are unsure where to install MambaForge.
Press the
ENTER
key to accept the default installation path or type a new path and then pressENTER
.: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 <install-dev-gcpy-install>`, these will be installed to the :file:`envs` subfolder of the root installation path.
You may see this warning:
WARNING: You currently have a PYTHONPATH environment variable set. This may cause unexpected behavior when running the Python interpreter in Mambaforge. For best results, please verify that your PYTHONPATH only points to directories of packages that are compatible with the Python interpreter in Mambaforge: /home/YOUR-USER-NAMEb/mambaforge
As long as your
PYTHONPATH
environment variable only contains the path to the root-level GCPy folder, you may safely ignore this. (More onPYTHONPATH
in the next section.)
Tell the installer to initialize MambaForge.
Do you wish the installer to initialize Mambaforge by running conda init? [yes|no] [no] >>>
Type
yes
and thenENTER
. The installer script will add some code to your~/.bashrc
system startup file that will tell your shell where to find Python environments.
Exit your current terminal session. Start a new terminal session to apply the updates. You are now ready to install GCPy.
Install GCPy and its dependencies
Once you have made sure that Mamba (or Conda) is present on your system, you may create a Python environment for GCPy. Follow these steps:
Download the GCPy source code.
Create and go to the directory in which you would like to store GCPy. In this example we will store GCPy in your
$HOME/python/
path, but you can store it wherever you wish. You can also name the GCPy download whatever you want. In this example the GCPy directory is calledGCPy
.$ cd $HOME/python $ git clone https://github.com/geoschem/gcpy.git GCPy $ cd GCPy
Create a new Python virtual environment for GCPy.
A Python virtual environment is a named set of Python installs, e.g. packages, that are independent of other virtual environments. Using an environment dedicated to GCPy is useful to maintain a set of package dependencies compatible with GCPy without interfering with Python packages you use for other work. You can create a Python virtual environment from anywhere on your system. It will be stored in your Mamba (or Conda installation rather than the directory from which you create it).
You can create a Python virtual environment using a file that lists all packages and their versions to be included in the environment. GCPy includes such as file,
environment.yml
, located in the top-level directory of the package.Run one of the following commands at the command prompt to create a virtual environment for use with GCPy. You can name environment whatever you wish. This example names it
gcpy_env
.$ mamba env create -n gcpy_env --file=environment.yml # If using Mamba $ conda env create -n gcpy_env --file=environment.yml # If using Conda
A list of packages to be downloaded will be displayed. A confirmation message will ask you if you really wish to install all of the listed packages. Type Y to proceed or n to abort.
Once successfully created you can activate the environment with one of these commands:
$ mamba activate gcpy_env # If using Mamba $ conda activate gcpy_env # If using Conda
To exit the environment, use one of these commands:
$ mamba deactivate # If using Mamba $ conda deactivate # If using Conda
Add GCPy to
PYTHONPATH
The environment variable
PYTHONPATH
specifies the locations of Python libraries on your system that were not installed by Mamba.Add the path to your GCPy source code folder
~/.bashrc
file:export PYTHONPATH=$PYTHONPATH:$HOME/python/GCPy
and then use
$ source ~/.bashrc
to apply the change.
Set the
MPLBACKEND
environment variableThe environment variable
MPLBACKEND
specifies the X11 backend that the Matplotlib package will use to render plots to the screen.Add this line to your
~/.bashrc
file on your local PC/Mac and on any remote computer systems where you will use GCPy:export MPLBACKEND=tkagg
And then use:
$ source ~/.bashrc
to apply the change.
Perform a simple test:
Make sure that you have specified the proper Specify backend for Matplotlib for your system. Then run the following commands in your terminal:
$ 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 -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 version. You can always update to the latest GCPy version from within you GCPy clone, and then update your virtual environment using the environment.yml file included in the package.
Run the following commands to update both your GCPy version to the latest available.
$ cd $HOME/python/GCPy
$ git fetch -p
$ git checkout main
$ git pull
You can also checkout an older version by doing the following:
$ cd $HOME/python/GCPy
$ git fetch -p
$ git tag
$ git checkout tags/version_you_want
Once you have the version you wish you use you can do the following commands to then update your virtual environment:
$ mamba activate gcpy_env
$ cd $HOME/python/GCPy
$ mamba env update --file environment.yml --prune