Skip to main content

Free boundary Grad-Shafranov solver for tokamak plasma equilibria

Project description

[![License](]( [![py3comp](]( [![Build Status](](

This Python module calculates plasma equilibria for tokamak fusion experiments, by solving the Grad-Shafranov equation with free boundaries. Given a set of coils, plasma profiles and shape, FreeGS finds the currents in the coils which produce a steady-state solution in force balance.

Note This is a work in progress, and probably contains bugs. There is a feature wishlist in issues, suggestions and contributions welcome!


FreeGS is available on PyPI

$ pip install –user freegs

or clone/download this repository and run setup:

$ git clone $ cd freegs $ python install –user


The manual is in the docs subdirectory, and [hosted here on readthedocs](


Unit tests use [pytest]( so after installing, run with:

$ pytest

The tests are in the src/ subdirectory.

A convergence test is [described in the manual]( To run:

$ python


The Jupyter notebooks contain examples wuth additional notes

  • MAST-example.ipynb

There are also some Python scripts to run short tests and examples

$ python

This solves a free boundary problem, specifying the desired location of two X-points. Writes the equilibrium to a G-EQDSK file “lsn.geqdsk”

$ python

Reads in the file “lsn.geqdsk”, inferring the coil currents from the plasma boundary and profiles in the G-EQDSK file.

$ python

Calculates a double-null (CDND) equilibrium for MAST from scratch. Writes solution to G-EQDSK file “mast.geqdsk”

$ python

Reads the file “mast.geqdsk”, inferring the coil currents.

$ python

This example solves a fixed boundary problem, in which the square edges of the domain are fixed. The plasma pressure on axis and plasma current are fixed.

$ python

This demonstrates the coil current control code, finding X-points, and marking core region These routines are used inside the free boundary solver


The “freegs” module consists of the following files:

  • - Operators for applying boundary conditions to plasma psi
  • - Routines for controlling coil currents based on constraints
  • - Finds critical points (O- and X-points)
  • - Represents the plasma equilibrium state
  • - Greens functions and operators for the Grad-Shafranov equation
  • - Routines for calculating toroidal current density (profiles)
  • - Represents the coils and power supply circuits
  • - The multigrid solver for the linear elliptic operator
  • - Nonlinear solver, iterating the profiles and constraints
  • - Plotting routines using matplotlib


Copyright 2016-2021 Ben Dudson, University of York, and other contributors. Email:

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see <>.



0.6.1 11th February 2021
  • Fixes for HDF5 reading and writing
  • Fix Numpy deprecations
  • Catch errors in optimisation measures, making that more robust
  • Fix core mask in geqdsk file reading
  • Flake8 fixes
  • Move to Github actions
0.6.0 29th January 2021
  • Improve separatrix finding (Pablo Rodriguez-Fernandez)
  • Update MAST-U machine description (James Harrison)
  • Updated documentation
  • Add tests for critical point finding
  • Black format all library code
  • Fix wall intersection calculation in optimisation
  • Fix factor of pi in effectiveElongation (Chris Winnard)
  • Miscellaneous fixes and tidying (Chris Winnard)
  • Fix psi_bndry test in critical.core_mask
  • Fix comments in Greens functions (James Morris)
0.5.0 25th March 2020
  • More tests, thanks to @ZedThree.
  • Added more flexible coil types, thanks to Chris Marsden. Includes support for shaped coils, multi-strand coils, and up-down mirrored coils.
  • Basic support for reading and writing AEQDSK files
  • Added h5py to requirements, fixes for latest NumPy
0.4.0 10th November 2019
  • Add optimisation with Differential Evolution
  • More unit testing, documentation
0.3.0 28th July 2019
  • Add 4th-order solver for potential
  • Add convergence test
0.2.0 12th March 2019
  • Add field line tracer, freegs.fieldtracer
  • Add Equilibrium.Btor toroidal field calculation
  • Add Equilibrium.plasmaVolume
  • Fix rlim, zlim saved into GEQDSK files

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for FreeGS, version 0.6.1
Filename, size File type Python version Upload date Hashes
Filename, size FreeGS-0.6.1-py2.py3-none-any.whl (96.9 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size FreeGS-0.6.1.tar.gz (74.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page