forge.equilibrium

Contains the Equilibrium Class used to define the equilibrium state of the plasma being optimised.

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

class forge.equilibrium.Equilibrium(eq_data=None, tokamak=None, calculate_flux_from_coils=False)

Bases: object

Object representing an equilibrium state of the plasma. This is a single time instance.

Parameters:

• eq_data (dict) – A dictionary of equilibrium data used to initialise the Equilibrium object.

• tokamak (floatforge.magnets.Machine object) – Machine object containing the PF coil set, wall, and additional structures.

• calculate_flux_from_coils (bool) – Flag for whether or not to calculate the PF coil set flux using their initial coil currents. If False, the flux from the plasma’s internal current profiles will instead be calculated first, with the PF coil set flux calculated as the difference between the full flux and the plasma flux.

calc_fluxes()

Calculates the poloidal magnetic flux from the plasma and from the machine.

pprime(psin)

Returns pprime as a function of normalised poloidal magnetic flux.

ffprime(psin)

Returns ffprime as a function of normalised poloidal magnetic flux.

psiRZ(R, Z)

Returns the poloidal magnetic flux at given (R,Z) location(s).

psi_plasRZ(R, Z)

Returns the poloidal magnetic flux from the plasma at given (R,Z) location(s).

psi_machRZ(R, Z)

Returns the poloidal magnetic flux from the machine at given (R,Z) location(s).

dpsi_dR_RZ(R, Z)

Returns dpsi/dR at given (R,Z) location(s).

dpsi_plas_dR_RZ(R, Z)

Returns dpsi/dR from the plasma at given (R,Z) location(s).

dpsi_mach_dR_RZ(R, Z)

Returns dpsi/dR from the machine at given (R,Z) location(s).

dpsi_dZ_RZ(R, Z)

Returns dpsi/dZ at given (R,Z) location(s).

dpsi_plas_dZ_RZ(R, Z)

Returns dpsi/dZ from the plasma at given (R,Z) location(s).

dpsi_mach_dZ_RZ(R, Z)

Returns dpsi/dZ from the machine at given (R,Z) location(s).

BrRZ(R, Z)

Returns the radial magnetic field at given (R,Z) location(s).

Br_plasRZ(R, Z)

Returns the radial magnetic field from the plasma at given (R,Z) location(s).

Br_machRZ(R, Z)

Returns the radial magnetic field from the machine at given (R,Z) location(s).

BzRZ(R, Z)

Returns the vertical magnetic field at given (R,Z) location(s).

Bz_plasRZ(R, Z)

Returns the vertical magnetic field from the plasma at given (R,Z) location(s).

Bz_machRZ(R, Z)

Returns the vertical magnetic field from the machine at given (R,Z) location(s).

BpolRZ(R, Z)

Returns the poloidal magnetic field at given (R,Z) location(s).

BtorRZ(R, Z)

Returns the toroidal magnetic field at given (R,Z) location(s) outside the plasma.

BtotRZ(R, Z)

Returns the total magnetic field at given (R,Z) location(s) outside the plasma.

dBp_plasRZ(R, Z, deriv=None)

Calculates the relevant derivative of the poloidal field from the plasma at (R,Z).

Options for deriv:

“dBr_dZ” - d(Br)/dZ - vertical derivative of the radial field “dBr_dR” - d(Br)/dR - radial derivative of the radial field “dBz_dZ” - d(Bz)/dZ - vertical derivative of the vertical field “dBz_dR” - d(Bz)/dR - radial derivative of the vertical field

Bpol_jacobian_plasRZ(R, Z)

Computes the 2x2 Jacobian matrix of the poloidal field from the plasma about the point (R,Z).

J = [[dBr/dR,dBr/dZ],

[dBz/dR,dBz/dZ]]

plot_profiles()

Plots the pprime and ffprime profiles.

plot_equilibrium(axis=None)

Plots the equilibrium.

plot_fluxes()

Plots the total, plasma and machine fluxes.

plot_fields()

Plots the total, plasma and machine field components, Br and Bz.

check_geometry()

Analyses the geometry of the core plasma.

Analysis routine that identifies key geometrical and topological features of the core plasma, such as locating X-points and O-points, identifying whether the plasma is in a single/double/disconnected-double null, find key points such as the maximum/minimum radial and vertical extrema points along the separatrix as well as identifying the location of points along the separatrix.

generate_separatrix_interpolator()

Separatrix (R,Z) points interpolator.

Creates an interpolator for points (R,Z) as a function of normalised distance along the separatrix (0,1).

get_points_along_separatrix(npoints=360)

Locates points along the separatrix.

Returns the (R,Z) coordinates of npoints evenly spaced points along the separatrix around the core plasma.

modify_wall(R_min=None, R_max=None, Z_min=None, Z_max=None)

Interactive editor for the tokamak wall structure.

Takes as input the minimum/maximum (R,Z) coordinates for plotting. Prints the (R,Z) coordinates of the modified wall.

create_eq_with_new_grid(new_grid_R_min, new_grid_R_max, new_grid_Z_min, new_grid_Z_max, new_grid_nR, new_grid_nZ)

Creates a copy of Equilibrium on a new (R,Z) grid.

Creates and returns a new forge.equilibrium Equilibrium object that is a copy of the exisiting equilibrium on an (R,Z) grid different to the original one. This is useful if for instance you want to extend the grid to encompass a new divertor structure.