FreeQDSK

Published: Apr 6, 2023 by Liam Pattinson

FreeQDSK is a Python library for reading/writing EQDSK files. These file formats are widely used within tokamak plasma research, but each code that uses them tends to include it’s own reader/writer functionality, and the availability of reliable open-source documentation is lacking. We hope that FreeQDSK can provide an easier way for plasma scientists to use these files in their own work.

EQDSK formats originated with the software ‘EFIT’, which is used to determine information such as tokamak plasma equilibria and kinetic profiles from experimental data (it can also be used as a standalone Grad-Shafranov equilibrium solver). To aid data interoperability and reuse within tokamak research, the formats were subsequently adopted by many other projects. However, EQDSK files tend to be awkwardly formatted and aren’t self-describing; both G-EQDSK and A-EQDSK files consist of a short header followed by large blocks of unlabelled scalars and/or arrays written using Fortran fixed-width text formatting. The EQDSK formats were never officially standardised, so the interpretation of these formats varies between codes, and sometimes even between different versions of the same code.

FreeQDSK was spun off from FreeGS, a Grad-Shafranov plasma equilibrium solver, in early 2020, but it wasn’t developed much further until the beginning of 2023. We were prompted to develop FreeQDSK due to our work on Pyrokinetics, which was dependent on FreeGS purely for its G-EQDSK reader utilities, although this functionality was not part of the FreeGS public API. This arrangement appeared to be unsustainable in the long term, and there was talk of overhauling the G-EQDSK reader in FreeGS anyway, so we decided to develop FreeQDSK so it could be used by both FreeGS and Pyrokinetics, as well as any other plasma physics projects that might find it helpful.

We started by updating the packaging system to the PEP 517/518/621 standards (i.e. using pyproject.toml for everything), and then updated the docs. The G-EQDSK and A-EQDSK readers/writers were refactored to make use of the FortranFormat library, which allows us to exactly match the fixed-width Fortran IO used by EFIT and other Fortran codes that read/write EQDSK files. We also expanded the project’s test suite and set up automated testing and publishing workflows. The final addition to the library was some utilities for reading/writing p-files, which describe kinetics profiles (here called ‘P-EQDSK’ files, though this may not be entirely accurate).

Not all EQDSK files are currently supported. In a future update, we hope to add functions to read and write K-, M- and S-files, and the library may also be expanded to include similar file formats used throughtout plasma physics. We would also like to update the code so it can handle the many variations on G-EQDSK and A-EQDSK files that may be encountered in the wild.