.. _pg_usage: Using Postgkyl ============== Postgkyl is, at its core, a Python library. When properly installed (see :ref:`pg_install`), it can be loaded in any Python script or interactive environment like `IPython `_ or `JupyterLab `_. .. code-block:: python import postgkyl Postgkyl can be used to read all the Gkeyll data outputs (including the legacy Gkeyll 1 files), can transform the raw expansion coefficients of Gkeyll basis functions to finite-volume style data, and also contains many postprocessing functions. See the following sections for more details. .. toctree:: :maxdepth: 1 keyconcepts loading colormaps What makes Postgkyl quite unique, is the wrapping of all the *functions* into command line *commands* using the `Click `_ Python package. In other words, almost the full functionality of Postgkyl can be used directly in any terminal. This has beneficts for everyday work where typing a single command is faster than writing a Python script and also for work with remote machines and supercomputers, which are primarily accessed through a terminal. However, the classical way of using Postgkyl in a script still provides more control and is well suited, for example, for long and complex scripts for publication level figures. The command line executable for Postgkyl is called ``pgkyl`` and its call has the following synopsis: .. code-block:: bash pgkyl [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]... Here, the ``COMMAND`` represents either data to :ref:`load ` or an opperation to be performed on the loaded data. All the available options can be listed using the inbuilt help, ``pgkyl --help`` or ``pgkyl -h`` for short. Note that Postgkyl supports an arbitrary number of commands. Similar to piping in Linux, results of one command are passed to another. This allows Postgkyl to perform even a rather complex diagnostics and create complicated plots straight up from the terminal. However, this puts a responsibility on the user to ensure that the commands are called in a logical order. Similarly to the main part of ``pgkyl``, ``--help`` can be called for each individual command which will provide additional information. Finally, it is worth mentioning that it is not necessary to write the full names of each command and the shortest unique sequence is good enough. Still, full names will be used through this documentation for clarity.