forge.critical

Routines to find critical points (O- and X-points).

Based on critical.py from FreeGS (https://github.com/freegs-plasma/freegs), with modifications for FORGE.

Copyright 2016 Ben Dudson, University of York. Email: benjamin.dudson@york.ac.uk Copyright 2025-2026 Chris Marsden

This file is part of FORGE.

FORGE 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.

FORGE 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 FORGE. If not, see <http://www.gnu.org/licenses/>.

forge.critical.find_critical(R, Z, psi, discard_xpoints=True)[source]

Finds critical points in psi.

Locates X-points and O-points on a 2D (R,Z) grid of poloidal magnetic flux - psi.

Parameters:

  • R (2D numpy array) – R(nr, nz) 2D array of major radii.

  • Z (2D numpy array) – Z(nr, nz) 2D array of heights.

  • psi (2D numpy array) – psi(nr, nz) 2D array of psi values.

  • discard_xpoints (bool) – Flag for discarding those X-points that do not lie on a line between the said X-point and the O-points, along which psi changes monotonically.

Returns:

  • opoint (list) – List of O-point locations and flux values.

  • xpoint (list) – List of X-point locations and flux values.

  • Each of these is a list of tuples with (R, Z, psi) points.

  • The first opoint tuple is the primary O-point (magnetic axis).

  • The first xpoint tuple is the primary X-point (separatrix).

forge.critical.core_mask(R, Z, psi, opoint, xpoint=[], psi_bndry=None)[source]

Mark the parts of the domain which are in the core.

Creates a mask of points in the equilibrium grid that lie inside the core plasma region.

Parameters:

  • R (2D numpy array) – 2D array of major radius (R) values.

  • Z (2D numpy array) – 2D array of height (Z) values.

  • psi (2D numpy array) – 2D array of poloidal magnetic flux values.

  • opoint (List) – List of O-point tuples, returned by find_critical.

  • xpoint (List) – List of X-point tuples, returned by find_critical.

  • psi_bndry (float) – Value of poloidal magnetic flux at the separatrix. If provided will be used to find the separatrix. If None, the X-points will be used.

Returns:

mask – 2D numpy array which is 1 for points intside the core and 0 for points outside.

forge.critical.find_psisurface(eq, psifunc, r0, z0, r1, z1, psival=1.0, n=100, axis=None)[source]

Locates the flux surface of a given value of normalised poloidal magnetic flux.

Parameters:

  • eq (forge.equilibrium.Equilibrium object) – A FORGE Equilibrium object representing the plasma.

  • psifunc (scipy.interpolate.RectBivariateSpline interpolator object) – A 2D (R,Z) interpolator for the poloidal magnetic flux psi.

  • r0 (float) – R coordinate of the starting location inside the separatrix.

  • z0 (float) – Z coordinate of the starting location inside the separatrix.

  • r1 (float) – R coordinate of the end location outside the separatrix.

  • z1 (float) – Z coordinate of the end location outside the separatrix.

  • psival (float) – Value of normalised poloidal magnetic flux psi of the flux surface that is to be located.

  • n (float) – Number of starting points to use.

  • axis (matplotlib.pyplot Axes object) – Optional axes to plot the located flux surface on. If None, no plotting will occur.

Returns:

  • r – 1D array of the R coordinates of the located flux surface.

  • z – 1D array of the Z coordinates of the located flux surface.

forge.critical.find_separatrix(eq, opoint=None, xpoint=None, ntheta=20, psi=None)[source]

Locates the separatrix and returns its coordinates.

Finds the (R,Z) coordinates of points along the separatrix, with points being equally spaced in geometric poloidal angle.

Parameters:

  • eq (forge.equilibrium.Equilibrium object) – A FORGE Equilibrium object representing the plasma.

  • opoint (List) – List of O-point tuples of (R, Z, psi)

  • xpoint (List) – List of X-point tuples of (R, Z, psi)

  • ntheta (float) – Number of points to find

  • psi (2D numpy array) – 2D array of poloidal magnetic flux values.

Returns:

  • R – List of the R coordinates of the located separatrix.

  • Z – List of the Z coordinates of the located separatrix.