freegsnke.circuit_eq_metal module

Defines the metal_currents Object, which handles the circuit equations of all metal structures in the tokamak - both active PF coils and passive structures.

Copyright 2025 UKAEA, UKRI-STFC, and The Authors, as per the COPYRIGHT and README files.

This file is part of FreeGSNKE.

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

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

You should have received a copy of the GNU Lesser General Public License along with FreeGSNKE. If not, see <http://www.gnu.org/licenses/>.

class freegsnke.circuit_eq_metal.metal_currents(eq, flag_vessel_eig, flag_plasma, max_mode_frequency, max_internal_timestep, full_timestep, plasma_pts=None, coil_resist=None, coil_self_ind=None, verbose=True)[source]

Bases: object

IdtoIvessel(Id)[source]

Given Id, returns Ivessel.

IvesseltoId(Ivessel)[source]

Given the vector of currents in the metals basis, Ivessel, returns Id the vector of currents in the eigenmodes basis.

Parameters:

Ivessel (np.ndarray) – Vessel currents.

Returns:

Id

Return type:

np.ndarray

Mey(eq)[source]

Calculates the matrix of mutual inductance values between plasma grid points included in the dynamics calculations and all vessel coils.

Parameters:

eq (class) – FreeGSNKE equilibrium Object

Returns:

Mey – Array of mutual inductances between plasma grid points and all vessel coils

Return type:

np.ndarray

__init__(eq, flag_vessel_eig, flag_plasma, max_mode_frequency, max_internal_timestep, full_timestep, plasma_pts=None, coil_resist=None, coil_self_ind=None, verbose=True)[source]

Sets up framework to solve the dynamical evolution of all metal currents. Can be used by itself to solve metal circuit equations for vacuum shots, i.e. when in the absence of the plasma.

Parameters:

  • eq (FreeGSNKE equilibrium Object) – Initial equilibrium. This is used to set the domain/grid properties as well as the machine properties. Furthermore, eq will be used to set up the linearization used by the linear evolutive solver. It can be changed later by initializing a new set of initial conditions. Note however that, to change either the machine or limiter properties it will be necessary to instantiate a new nl_solver object.

  • flag_vessel_eig (bool) – Flag re whether vessel eigenmodes are used or not.

  • flag_plasma (bool) – Whether to include plasma in circuit equation. If True, plasma_pts must be provided.

  • plasma_pts (freegsnke.limiter_handler.plasma_pts) – Domain points in the domain that are included in the evolutive calculations. A typical choice would be all domain points inside the limiter. Defaults to None.

  • max_mode_frequency (float) – Maximum frequency of vessel eigenmodes to include in circuit equation. Defaults to 1. Unit is s^-1.

  • max_internal_timestep (float) – Maximum value of the ‘internal’ timestep for implicit euler solver. Defaults to .0001. The ‘internal’ timestep is the one actually used by the solver.

  • full_timestep (float) – Timestep by which the equations are advanced. If full_timestep>max_internal_timestep multiple ‘internal’ steps are executed. Defaults to .0001.

  • coil_resist (np.array) – 1d array of resistance values for all conducting elements in the machine, including both active coils and passive structures. Defaults to None, meaning the values calculated by default in tokamak will be sourced and used.

  • coil_self_ind (np.array) – 2d matrix of mutual inductances between all pairs of machine conducting elements, including both active coils and passive structures Defaults to None, meaning the values calculated by default in tokamak will be sourced and used.

forcing_term_eig_no_plasma(active_voltage_vec, Iydot=0)[source]

Right-hand-side of circuit equation in eigenmode basis without plasma.

Parameters:

  • active_voltage_vec (np.ndarray) – Vector of active coil voltages.

  • Iydot (np.ndarray, optional) – This is not used.

Returns:

all_Us – Effective voltages in eigenmode basis.

Return type:

np.ndarray

forcing_term_eig_plasma(active_voltage_vec, Iydot)[source]

Right-hand-side of circuit equation in eigenmode basis with plasma.

Parameters:

  • active_voltage_vec (np.ndarray) – Vector of active coil voltages.

  • Iydot (np.ndarray) – Vector of rate of change of plasma currents.

Returns:

all_Us – Effective voltages in eigenmode basis.

Return type:

np.ndarray

forcing_term_no_eig_no_plasma(active_voltage_vec, Iydot=0)[source]

Right-hand-side of circuit equation in normal mode basis without plasma.

Parameters:

  • active_voltage_vec (np.ndarray) – Vector of active coil voltages.

  • Iydot (np.ndarray, optional) – This is not used.

Returns:

all_Us – Effective voltages in metals basis.

Return type:

np.ndarray

forcing_term_no_eig_plasma(active_voltage_vec, Iydot)[source]

Right-hand-side of circuit equation in normal mode basis with plasma.

Parameters:

  • active_voltage_vec (np.ndarray) – Vector of active coil voltages.

  • Iydot (np.ndarray) – Vector of rate of change of plasma currents.

Returns:

all_Us – Effective voltages in metals basis.

Return type:

np.ndarray

initialize_for_eig(selected_modes_mask=None, mode_coupling_masks=None, verbose=True)[source]

Initializes the metal_currents object for the case where vessel eigenmodes are used.

Parameters:

mode_coupling_metric_masks ((np.ndarray of booles, np.ndarray of booles))

initialize_for_no_eig()[source]

Initializes the metal currents object for the case where vessel eigenmodes are not used.

make_selected_mode_mask(mode_coupling_masks, verbose)[source]

Creates a mask for the vessel normal modes to include in the circuit equations, based on the maximum frequency of the selected modes.

reset_mode(flag_vessel_eig, flag_plasma, plasma_pts=None, max_mode_frequency=1, max_internal_timestep=0.0001, full_timestep=0.0001)[source]

Resets init inputs.

flag_vessel_eigbool

Flag re whether vessel eigenmodes are used or not.

flag_plasmabool

Whether to include plasma in circuit equation. If True, plasma_pts must be provided.

plasma_ptsfreegsnke.limiter_handler.plasma_pts

Domain points in the domain that are included in the evolutive calculations. A typical choice would be all domain points inside the limiter. Defaults to None.

max_mode_frequencyfloat

Maximum frequency of vessel eigenmodes to include in circuit equation. Defaults to 1. Unit is s^-1.

max_internal_timestepfloat

Maximum value of the ‘internal’ timestep for implicit euler solver. Defaults to .0001. The ‘internal’ timestep is the one actually used by the solver.

full_timestepfloat

Timestep by which the equations are advanced. If full_timestep>max_internal_timestep multiple ‘internal’ steps are executed. Defaults to .0001.

reset_timesteps(max_internal_timestep, full_timestep)[source]

Resets the timesteps

Parameters:

  • max_internal_timestep (float) – Maximum value of the ‘internal’ timestep for implicit euler solver. The ‘internal’ timestep is the one actually used by the solver.

  • full_timestep (float) – Timestep by which the equations are advanced. If full_timestep>max_internal_timestep multiple ‘internal’ steps are executed.

stepper(It, active_voltage_vec, Iydot=0)[source]

Steps the circuit equation forward in time.

Parameters:

  • It (np.ndarray) – Currents at time t.

  • active_voltage_vec (np.ndarray) – Vector of active coil voltages.

  • Iydot (np.ndarray or float, optional) – Vector of rate of change of plasma currents. Defaults to 0.

Returns:

It – Currents at time t+dt.

Return type:

np.ndarray