Installing GCPy

Requirements

GCPy is currently supported on the following platforms:

Linux (x86_64)
Windows Subsystem for Linux (running in Microsoft Windows 11)
MacOS

To install GCPy, you will 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 number 23.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 then SPACE 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 hit ENTER.

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 press ENTER.

: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.

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 on PYTHONPATH 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 then ENTER. 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 called GCPy.
```
$ 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 variable

The 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:

Run the following commands in your terminal to check if the installation was succcesful.

$ 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

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