freegsnke.virtual_circuits module

Defines class that represents the virtual circuits.

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.virtual_circuits.VirtualCircuit(name, eq, profiles, shape_matrix, VCs_matrix, targets, targets_val, targets_options, non_standard_targets, coils)[source]

Bases: object

The class for storing/recording virtual circuits that have been built using the VirtualCircuitHandling class.

__init__(name, eq, profiles, shape_matrix, VCs_matrix, targets, targets_val, targets_options, non_standard_targets, coils)[source]

Store the key quantities from the VirtualCircuitHandling calculations.

Parameters:

  • name (str) – Name to call the VCs (e.g. super-X VCs).

  • eq (object) – The equilibrium object used to build the VCs.

  • profiles (object) – The profiles object used to build the VCs.

  • shape_matrix (np.array) – The array storing the Jacobians between the targets and coils given in ‘targets’ and ‘coils’.

  • VCs_matrix (np.array) – The array storing the VCs between the targets and coils given in ‘targets’ and ‘coils’.

  • targets (list) – The list of targets used to calculate the shape_matrix and VCs_matrix.

  • targets_val (np.array) – The array of target values.

  • targets_options (dict) – Dictionary of additional parameters required to calculate the ‘targets’.

  • non_standard_targets (list) – List of lists of additional (non-standard) target functions to use. Takes the form [[“new_target_name”,…], [function(eq),…]], where function calcualtes the target using the eq object.

  • coils (list) – The list of coils used to calculate the shape_matrix and VCs_matrix.

class freegsnke.virtual_circuits.VirtualCircuitHandling[source]

Bases: object

The virtual circuits handling class.

__init__()[source]

Initialises the virtual circuits.

apply_VC(eq, profiles, VC_object, all_requested_target_shifts, verbose=False)[source]

Here we apply the VC matrix V to requested shifts in the target quantities (dT), obtaining the shift in the currents (in coils, dI) required to achieve this:

dI = V * dT.

Applying the current shifts to the existing currents, we re-solve the equilibrium and return to user.

Parameters:

  • eq (object) – The equilibrium object upon which to apply the VCs.

  • profiles (object) – The profiles object upon which to apply the VCs.

  • VC_object (an instance of the VirtualCircuit class) – Specifies the virtual circuit matrix and properties.

  • all_requested_targets_shift (list) – List of floats containing the shifts in all of the relevant targets. Same order as VC_object.targets. Includes both standard and non-standard targets. Functions to calculate non-standard targets are sourced from the VC_object.

  • verbose (bool) – Display output (or not).

Returns:

  • object – Returns the equilibrium object after applying the shifted currents.

  • object – Returns the profiles object after applying the shifted currents.

  • list – List of strings containing all of targets of interest.

  • np.array – Array of new target values.

  • np.array – Array of old target values.

assign_currents(currents_vec, coils, eq)[source]

For the given equilibrium, this function assigns the coil currents (for those listed in ‘coils’) in the class object.

Parameters:

  • currents_vec (np.array) – Vector of coil currents to be assigned to the eq object using the coil names in ‘coils.

  • eq (object) – The equilibrium object.

  • coils (list) – List of strings containing the names of the coil currents to be assigned.

Returns:

Modifies the class object in place.

Return type:

None

assign_currents_solve_GS(currents_vec, coils, target_relative_tolerance)[source]

Assigns the coil currents in ‘currents_vec’ to a private equilibrium object and then solve using the static GS solver.

Parameters:

  • currents_vec (np.array) – Input current values to be assigned. Format as in self.assign_currents.

  • coils (list) – List of strings containing the names of the coil currents to be assigned.

  • target_relative_tolerance (float) – Target relative tolerance to be met by the solver.

Returns:

Modifies the class (and other private) object(s) in place.

Return type:

None

build_current_vec(eq, coils)[source]

For the given equilibrium, this function stores the coil currents (for those listed in ‘coils’) in the class object.

Parameters:

  • eq (object) – The equilibrium object.

  • coils (list) – List of strings containing the names of the coil currents to be stored.

Returns:

Modifies the class object in place.

Return type:

None

build_dIydI_j(j, coils, targets, targets_options, non_standard_targets=None, verbose=False)[source]

Computes the term d(Iy)/dI_j of the Jacobian as a finite difference derivative, using the value of delta(I_j) inferred earlier by self.prepare_build_dIydI_j.

Here:

  • Iy is the flattened vector of plasma currents (on the computational grid).

  • I_j is the current in the jth coil.

Parameters:

  • j (int) – Index identifying the current to be varied. Indexes as in self.currents_vec.

  • coils (list) – List of strings containing the names of the coil currents to be assigned.

  • targets (list) – List of strings containing the targets of interest. See above for supported targets.

  • targets_options (dict) – Dictionary of additional parameters required to calculate the ‘targets’ (see above).

  • non_standard_targets (list) – List of lists of additional (non-standard) target functions to use. Takes the form [[“new_target_name”,…], [function(eq),…]], where function calcualtes the target using the eq object.

  • verbose (bool) – Display output (or not).

Returns:

VC object modifed in place.

Return type:

None

calculate_VC(eq, profiles, coils, targets, targets_options, non_standard_targets=None, target_dIy=0.001, starting_dI=None, min_starting_dI=50, verbose=False, VC_name=None)[source]

Calculate the “virtual circuits” matrix:

V = (S^T S)^(-1) S^T,

which is the Moore-Penrose pseudo-inverse of the shape (Jacobian) matrix S:

S_ij = dT_i / dI_j.

This represents the sensitivity of target parameters T_i to changes in coil currents I_j.

Parameters:

  • eq (object) – The equilibrium object.

  • profiles (object) – The profiles object.

  • coils (list) – List of strings containing the names of the coil currents to be assigned.

  • targets (list) – List of strings containing the targets of interest. See above for supported targets.

  • targets_options (dict) – Dictionary of additional parameters required to calculate the ‘targets’ (see above).

  • non_standard_targets (list) – List of lists of additional (non-standard) target functions to use. Takes the form [[“new_target_name”,…], [function(eq),…]], where function calcualtes the target using the eq object.

  • target_dIy (float) – Target value for the norm of delta(I_y), from which the finite difference derivative is calculated.

  • starting_dI (float) – Initial value to be used as delta(I_j) to infer the slope of norm(delta(I_y))/delta(I_j).

  • min_starting_dI (float) – Minimum starting_dI value to be used as delta(I_j): to infer the slope of norm(delta(I_y))/delta(I_j).

  • verbose (bool) – Display output (or not).

  • VC_name (str) – Name to store the VC under (in the ‘VirtualCircuit’ class).

Returns:

Modifies the class (and other private) object(s) in place.

Return type:

None

calculate_targets(eq, targets, targets_options=None, non_standard_targets=None)[source]

For the given equilibrium, this function calculates the targets specified in the targets list.

Parameters:

  • eq (object) – The equilibrium object.

  • targets (list) – List of strings containing the targets of interest. Currently supported targets are: - “R_in”: inner midplane radius. - “R_out”: outer midplane radius. - “Rx_lower”: lower X-point (radial) position. - “Zx_lower”: lower X-point (vertical) position. - “Rx_upper”: upper X-point (radial) position. - “Zx_upper”: upper X-point (vertical) position. - “Rs_lower_outer”: lower strikepoint (radial) position. - “Rs_upper_outer”: upper strikepoint (radial) position.

  • targets_options (dict) – Dictionary of additional parameters required to calculate the ‘targets’. Options are required for: - “Rx_lower”: approx. (R,Z) position of the lower X-point. - “Zx_lower”: approx. (R,Z) position of the lower X-point. - “Rx_upper”: approx. (R,Z) position of the upper X-point. - “Zx_upper”: approx. (R,Z) position of the upper X-point. - “Rs_lower_outer”: approx. (R,Z) position of the lower outer strikepoint. - “Rs_upper_outer”: approx. (R,Z) position of the upper outer strikepoint.

  • non_standard_targets (list) – List of lists of additional (non-standard) target functions to use. Takes the form [[“new_target_name”,…], [function(eq),…]], where function calcualtes the target using the eq object.

Returns:

  • list – Returns the original list of targets (plus any additional tagets specified in non_standard_targets).

  • np.array – Returns a 1D array of the target values (in same order as ‘targets’ input).

define_solver(solver, target_relative_tolerance=1e-07)[source]

Sets the solver in the VC class.

Parameters:

  • solver (object) – The static Grad-Shafranov solver object.

  • target_relative_tolerance (float) – Target relative tolerance to be met by the solver.

Returns:

Modifies the class object in place.

Return type:

None

prepare_build_dIydI_j(j, coils, target_dIy, starting_dI, min_curr=0.0001, max_curr=300)[source]

Prepares to compute the term d(Iy)/dI_j of the Jacobian by inferring the value of delta(I_j) corresponding to a change delta(I_y) with norm(delta(I_y)) = target_dIy.

Here:

  • Iy is the flattened vector of plasma currents (on the computational grid).

  • I_j is the current in the jth coil.

Parameters:

  • j (int) – Index identifying the current to be varied. Indexes as in self.currents_vec.

  • coils (list) – List of strings containing the names of the coil currents to be assigned.

  • target_dIy (float) – Target value for the norm of delta(I_y), from which the finite difference derivative is calculated.

  • starting_dI (float) – Initial value to be used as delta(I_j) to infer the slope of norm(delta(I_y))/delta(I_j).

  • min_curr (float, optional, by default 1e-4) – If inferred current value is below min_curr, clip to min_curr.

  • max_curr (int, optional, by default 300) – If inferred current value is above max_curr, clip to max_curr.

Returns:

Modifies the class (and other private) object(s) in place.

Return type:

None