The numerical approach of pyqg was originally inspired by a MATLAB code by Glenn Flierl of MIT, who was a teacher and mentor to Ryan and Malte. It would be hard to find anyone in the world who knows more about this sort of model than Glenn. Malte implemented a python version of the two-layer model while at GFDL. In the summer of 2014, while both were at the WHOI GFD Summer School, Ryan worked with Malte refactor the code into a proper python package. Cesar got involved and brought pyfftw into the project. Ryan implemented a cython kernel. Cesar and Francis implemented the barotropic and sqg models.


By adopting open-source best practices, we hope pyqg will grow into a widely used, community-based project. We know that many other research groups have their own “in house” QG models. You can get involved by trying out the model, filing issues if you find problems, and making pull requests if you make improvements.

Develpment Workflow

Anyone interested in helping to develop pyqg needs to create their own fork of our git repository. (Follow the github forking instructions. You will need a github account.)

Clone your fork on your local machine.

$ git clone

(In the above, replace USERNAME with your github user name.)

Then set your fork to track the upstream pyqg repo.

$ cd pyqg
$ git remote add upstream git://

You will want to periodically sync your master branch with the upstream master.

$ git fetch upstream
$ git rebase upstream/master

Never make any commits on your local master branch. Instead open a feature branch for every new development task.

$ git checkout -b cool_new_feature

(Replace cool_new_feature with an appropriate description of your feature.) At this point you work on your new feature, using git add to add your changes. When your feature is complete and well tested, commit your changes

$ git commit -m 'did a bunch of great work'

and push your branch to github.

$ git push origin cool_new_feature

At this point, you go find your fork on and create a pull request. Clearly describe what you have done in the comments. If your pull request fixes an issue or adds a useful new feature, the team will gladly merge it.

After your pull request is merged, you can switch back to the master branch, rebase, and delete your feature branch. You will find your new feature incorporated into pyqg.

$ git checkout master
$ git fetch upstream
$ git rebase upstream/master
$ git branch -d cool_new_feature

Virtual Environment

This is how to create a virtual environment into which to test-install pyqg, install it, check the version, and tear down the virtual environment.

$ conda create --yes -n test_env python=3.9 pip nose numpy cython scipy nose
$ conda install --yes -n test_env -c conda-forge pyfftw
$ source activate test_env
$ pip install pyqg
$ python -c 'import pyqg; print(pyqg.__version__);'
$ conda deactivate
$ conda env remove --yes -n test_env

Release Procedure

Once we are ready for a new release, someone needs to make a pull request which updates docs/whats-new.rst in preparation for the new version. Then, you can simply create a new release in Github, adding a new tag for the new version (following semver) and clicking “Auto-generate release notes” to summarize changes since the last release (with further elaboration if necessary).

After the release is created, a new version should be published to pypi automatically.

However, before creating the release, it’s worth checking testpypi to ensure the new version works. You can do that by:

  1. Verifying the most recent test publish succeeded (and is for the most recent commit)

  2. Finding the corresponding pre-release version in pyqg’s TestPyPI history (should look like X.Y.Z.devN)

  3. Installing that version locally as follows:

# Create a temporary directory with a fresh conda environment
$ mkdir ~/tmp
$ cd ~/tmp
$ conda create --yes -n test_env python=3.9 pip nose numpy cython scipy nose setuptools setuptools_scm
$ source activate test_env
$ pip install pyfftw # or install with conda-forge

# Install the latest pre-release version of pyqg
$ pip install -i --extra-index-url --no-cache-dir pyqg==X.Y.Z.devN

# Ensure this imports successfully and prints out the pre-release version (X.Y.Z.devN)
$ python -c 'import pyqg; print(pyqg.__version__);'

# Clean up and remove the test environment
$ conda deactivate
$ conda env remove --yes -n test_env

If this all works, then you should be ready to create the Github release.