Postgkyl

This is the Postgkyl project. It is both Python library and command-line tool designed to provide unified access to Gkeyll data together with a broad variety of analytical and visualization tools.

Documentation

Full documentation of the Gkeyll project is available at ReadTheDocs.

Dependencies and Installation

Postgkyl requires the following packages:

• click
• matplotlib
• msgpack
• numpy
• scipy
• sympy
• tables

Note that Posgkyl currently does not work with NumPy >= 2.0; the update is in the works. In addition, there are two optional dependencies:

• adios2
• pytest

ADIOS 2 is required for reading Gkeyll 2 bp output files and it is not needed when working only with gkylzero. pytest is required only for developers.

Setting up virtual environment (recommended)

We strongly recommend creating a virtual Python environment for everybody working with more than one Python project (this includes even using both Postgkyl and Sphinx). The two recommended options are venv and mamba.

With venv, one can create the virtual environment with:

python -m venv /path/to/new/virtual/environments/pgkyl

then activate it with:

| bash/zsh | source <venv>/bin/activate | | fish | source <venv>/bin/activate.fish | | csh/tcsh | source <venv>/bin/activate.csh |

and deactivate with:

deactivate

With mamba, one can create the virtual environment with:

mamba create -n pgkyl

then activate with:

mamba activate pgkyl

and deactivate with:

mamba deactivate

Note that with mamba, one can also use the provided environment.yml file, which also includes dependency specifications:

mamba env create -f environment.yml

Installing Postgkyl

The Postgkyl itself is installed with pip.¹ Developers and uses who want to have the most up-to-date version should install Postgkyl from the source code:

git clone https://github.com/ammarhakim/postgkyl.git
cd postgkyl
pip install -e .[adios,test]

Alternatively, Postgkyl can be installed directly from PyPI:

pip install -e postgkyl[adios,test]

Note that ADIOS2 is not available on PyPI for Mac OSX; therefore, Mac users who want to use it need to install the dependency from elsewhere, for example, using the above-mentioned mamba and then do not use the adios tag with pip.

Optional path to Gkeyll

Some features require telling postgkyl the location of the core library of Gkeyll. After installing postgkyl you can optionally write a postgkyl config file storing the location of Gkeyll's gkylsoft/ installation library by invoking the postgkyl config command, e.g.

pgkyl config -g <path_to_gkylsoft>/gkylsoft/ -c ~/.postgkyl/gkylsoft_path

Testing

Postgkyl utilizes pytest for testing. The tests can be called manually from the root Postgkyl directory simply by using:

pytest [-v]

Authors

The full list of authors can be found here.

License

Postgkyl is distributed under the MIT License.

Footnotes

1. This does not require any additional modifications of PYTHONPATH. If Postgkyl was used previously through PYTHONPATH, we strongly recommend removing the path to the Postgkyl repository from the variable. ↩