GCS in Python

Python 3 implementation of the Graduated Cylindrical Shell model (GCS, Thernisien, 2011). Based on the existing IDL implementation in SolarSoft (cmecloud.pro, shellskeleton.pro).

The code in gcs/geometry.py provides the basic implementation of the GCS geometry, while the Qt-based GUI in gcs/gui.py uses SunPy and Matplotlib to plot the model on top of coronagraph images provided by Helioviewer.org.

A more detailed description of the GCS model, this Python implementation and its validation is given in this excerpt from my PhD thesis.

Note

This code is still in a quite early stage. It has been compared with the original IDL/SolarSoft version to verify the results, but only for a few case studies. Please be careful when using it and compare to IDL when in doubt.

If you find a bug, run into technical problems during the installation, or have suggestions for improvement, please create a GitHub issue. As I have since left the Heliophysics field and am no longer actively using the tool myself, I can't promise timely responses. But it is still preferrable compared to writing me an email in private, as other users can also help you.

If you have fixed a bug or implemented improvements, please feel free to open a Pull Request!

If you use this code in a publication, please cite it using the DOI generated by Zenodo. I would also appreciate it if you drop me an email and tell me what you used it for :)

How to install and run the GUI

Python 3.7 or later and Git are required for installation.

# install GCS
pip3 install git+https://github.com/johan12345/gcs_python.git

# run GCS GUI, providing a date/time and the spacecraft to use
gcs_gui "2020-04-15 06:00" STA SOHO

Information on the available command line arguments for the GUI is given when you run the help option:

gcs_gui -h

Common issues

• command not found: gcs_gui
  This sounds like the directory where pip installs executables (on Linux this is typically ~/.local/bin) is not on your PATH. pip probably printed a warning about this when you were installing the package.
• RuntimeError: You must have a version of OpenJPEG at least as high as 2.3.0 before you can read JPEG2000 images with glymur.
  Loading Helioviewer images with SunPy requires the OpenJPEG library to be available on your PATH. You can install it through your system package manager (e.g., apt install libopenjp2-7-dev), through conda or manually, as you prefer.

How to use the GCS geometry in your own plotting code

Simply install GCS (as seen above) and use

import gcs.geometry

to import the code from the GCS package. You can find some examples what you can do with it in the files sample.py and sample_sunpy.py.

Development setup

First, clone the git repository:

git@github.com:johan12345/gcs_python.git

It is recommended to use a virtual environment so that the Python packages you install as dependencies of GCS don't interfere with your globally installed packages. On some Linux distributions, the additional python3-venv package needs to be installed for this to work.

python3 -m venv env
. env/bin/activate

Then, install the dependencies:

# install requirements
python3 -m pip install --upgrade pip setuptools
pip3 install -r requirements.txt

and test the GUI using

python -m gcs.gui "2020-04-15 06:00" STA SOHO