bluemira.equilibria.optimisation.constraints

Equilibrium optimisation constraint classes

Classes

UpdateableConstraint	Abstract base mixin class for an equilibrium optimisation constraint that is
FieldConstraints	Inequality constraints for the poloidal field at certain locations.
CoilFieldConstraints	Inequality constraints on the poloidal field at the middle of the inside edge
CoilForceConstraints	Inequality constraints on the vertical forces in the PF and CS coils.
MagneticConstraint	Abstract base class for a magnetic optimisation constraint.
AbsoluteMagneticConstraint	Abstract base class for absolute magnetic constraints, where the target
RelativeMagneticConstraint	Abstract base class for relative magnetic constraints, where the target
FieldNullConstraint	Magnetic field null constraint. In practice sets the Bx and Bz field components
VerticalFieldConstraint	Absolute vertical field (Bz) constraint.
PsiConstraint	Absolute psi value constraint.
IsofluxConstraint	Isoflux constraint for a set of points relative to a reference point.
PsiBoundaryConstraint	Absolute psi value constraint on the plasma boundary. Gets updated when
MagneticConstraintSet	A set of magnetic constraints to be applied to an equilibrium. The optimisation
AutoConstraints	Utility class for crude reconstruction of magnetic constraints from a

Functions

_get_dummy_equilibrium(equilibrium)

Module Contents

bluemira.equilibria.optimisation.constraints._get_dummy_equilibrium(equilibrium: bluemira.equilibria.equilibrium.Equilibrium)

Returns:

a dummy equilibrium for current optimisation where the background response is solely due to the plasma and passive coils.

Parameters:

equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

Notes

When we do dI (current gradient) optimisation, the background vector includes the contributions from the whole coilset (including active coils).

When we do I (current vector) optimisation, the background vector only includes contributions from the passive coils (plasma).

class bluemira.equilibria.optimisation.constraints.UpdateableConstraint

Bases: abc.ABC

Abstract base mixin class for an equilibrium optimisation constraint that is updateable.

classmethod __init_subclass__(**kwargs)

Create constraint name on definition of subclass

property name: str

The name of the constraint

Return type:

str

abstract prepare(equilibrium: bluemira.equilibria.equilibrium.Equilibrium, *, I_not_dI=False, fixed_coils=False)

Prepare the constraint for use in an equilibrium optimisation problem.

Parameters:

equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

abstract control_response(coilset: bluemira.equilibria.coils.CoilSet)

Calculate control response of a CoilSet to the constraint.

Parameters:

coilset (bluemira.equilibria.coils.CoilSet)

abstract evaluate(equilibrium: bluemira.equilibria.equilibrium.Equilibrium)

Calculate the value of the constraint in an Equilibrium.

Parameters:

equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

abstract f_constraint() → bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction

The numerical non-linear part of the constraint.

Return type:

bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction

class bluemira.equilibria.optimisation.constraints.FieldConstraints(x: float | numpy.ndarray, z: float | numpy.ndarray, B_max: float | numpy.ndarray, tolerance: float | numpy.ndarray | None = None, constraint_type: str = 'inequality')

Bases: UpdateableConstraint

Inequality constraints for the poloidal field at certain locations.

Parameters:

• x (float | numpy.ndarray) – Radial coordinate(s) at which to constrain the poloidal field

• z (float | numpy.ndarray) – Vertical coordinate(s) at which to constrain the poloidal field

• B_max (float | numpy.ndarray) – Maximum poloidal field value(s) at location(s)

• tolerance (float | numpy.ndarray | None) – Tolerance with which the constraint(s) will be met

• constraint_type (str) – Type of constraint

x

z

_args

tolerance = None

f_constraint_type = 'inequality'

prepare(equilibrium: bluemira.equilibria.equilibrium.Equilibrium, *, I_not_dI: bool = False, fixed_coils: bool = False)

Prepare the constraint for use in an equilibrium optimisation problem.

Parameters:

• equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

• I_not_dI (bool)

• fixed_coils (bool)

control_response(coilset: bluemira.equilibria.coils.CoilSet) → tuple[numpy.ndarray, numpy.ndarray]

Calculate control response of a CoilSet to the constraint.

Returns:

• Bx response

• Bz response

Parameters:

coilset (bluemira.equilibria.coils.CoilSet)

Return type:

tuple[numpy.ndarray, numpy.ndarray]

evaluate(equilibrium: bluemira.equilibria.equilibrium.Equilibrium) → tuple[numpy.ndarray, numpy.ndarray]

Calculate the value of the constraint in an Equilibrium.

Returns:

• Bx of equilibrium

• Bz of equilibrium

Parameters:

equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

Return type:

tuple[numpy.ndarray, numpy.ndarray]

f_constraint() → bluemira.equilibria.optimisation.constraint_funcs.FieldConstraintFunction

Calculate the constraint function

Return type:

bluemira.equilibria.optimisation.constraint_funcs.FieldConstraintFunction

__len__() → int

Length of field constraints.

Return type:

int

class bluemira.equilibria.optimisation.constraints.CoilFieldConstraints(coilset: bluemira.equilibria.coils.CoilSet, B_max: float | numpy.ndarray, tolerance: float | numpy.ndarray | None = None)

Bases: FieldConstraints

Inequality constraints on the poloidal field at the middle of the inside edge of the coils, where the field is usually highest.

Parameters:

• coilset (bluemira.equilibria.coils.CoilSet) – Coilset for which to constrain the fields in the coils

• B_max (float | numpy.ndarray) – Maximum field allowed in the coils

• tolerance (float | numpy.ndarray | None) – Tolerance with which the inequality constraints will be met

Notes

This is a fast approximation constraint, and does not solve for the peak field at all points in the coils. Use with caution. TODO: Presently only handles CoilSets with Coils (SymmetricCircuits not yet supported) TODO: Presently only accounts for poloidal field contributions from PF coils and plasma (TF from TF coils not accounted for if PF coils are inside the TF coils.)

static _get_constraint_points(coilset)

prepare(equilibrium: bluemira.equilibria.equilibrium.Equilibrium, *, I_not_dI: bool = False, fixed_coils: bool = False)

Prepare the constraint for use in an equilibrium optimisation problem.

Parameters:

• equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

• I_not_dI (bool)

• fixed_coils (bool)

class bluemira.equilibria.optimisation.constraints.CoilForceConstraints(coilset: bluemira.equilibria.coils.CoilSet, PF_Fz_max: float, CS_Fz_sum_max: float, CS_Fz_sep_max: float, tolerance: float | numpy.ndarray | None = None)

Bases: UpdateableConstraint

Inequality constraints on the vertical forces in the PF and CS coils.

Parameters:

• coilset (bluemira.equilibria.coils.CoilSet) – Coilset for which to constrain the fields in the coils

• PF_Fz_max (float) – Maximum absolute vertical force in a PF coil [MN]

• CS_Fz_sum_max (float) – Maximum absolute vertical force sum in the CS stack [MN]

• CS_Fz_sep_max (float) – Maximum separation vertical force between two CS modules [MN]

• tolerance (float | numpy.ndarray | None) – Tolerance with which the inequality constraints will be met

Notes

TODO: Presently only handles CoilSets with Coils (SymmetricCircuits not yet supported)

_args

tolerance = None

prepare(equilibrium: bluemira.equilibria.equilibrium.Equilibrium, *, I_not_dI: bool = False, fixed_coils: bool = False)

Prepare the constraint for use in an equilibrium optimisation problem.

Parameters:

• equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

• I_not_dI (bool)

• fixed_coils (bool)

static control_response(coilset: bluemira.equilibria.coils.CoilSet) → numpy.ndarray

Calculate control response of a CoilSet to the constraint.

Parameters:

coilset (bluemira.equilibria.coils.CoilSet)

Return type:

numpy.ndarray

static evaluate(equilibrium: bluemira.equilibria.equilibrium.Equilibrium) → numpy.ndarray

Calculate the value of the constraint in an Equilibrium.

Returns:

The force evaluation

Parameters:

equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

Return type:

numpy.ndarray

f_constraint() → bluemira.equilibria.optimisation.constraint_funcs.CoilForceConstraint

Calculate the constraint function

Return type:

bluemira.equilibria.optimisation.constraint_funcs.CoilForceConstraint

class bluemira.equilibria.optimisation.constraints.MagneticConstraint(target_value: float = 0.0, weights: float | numpy.ndarray = 1.0, tolerance: float | numpy.ndarray | None = None, f_constraint: type[bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction] = L2NormConstraint, constraint_type: str = 'inequality')

Bases: UpdateableConstraint

Abstract base class for a magnetic optimisation constraint.

Can be used as a standalone constraint for use in an optimisation problem. In which case the constraint is of the form: ||(Ax - b)||² < target_value

Can be used in a MagneticConstraintSet

Parameters:

• target_value (float)

• weights (float | numpy.ndarray)

• tolerance (float | numpy.ndarray | None)

• f_constraint (type[bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction])

• constraint_type (str)

target_value

weights = 1.0

_f_constraint

_args

tolerance = None

constraint_type = 'inequality'

prepare(equilibrium: bluemira.equilibria.equilibrium.Equilibrium, *, I_not_dI: bool = False, fixed_coils: bool = False)

Prepare the constraint for use in an equilibrium optimisation problem.

Parameters:

• equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

• I_not_dI (bool)

• fixed_coils (bool)

update_target(equilibrium: bluemira.equilibria.equilibrium.Equilibrium)

Update the target value of the magnetic constraint.

Parameters:

equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

abstract plot(ax)

Plot the constraint onto an Axes.

__len__() → int

The mathematical size of the constraint.

Notes

Length of the array if an array is specified, otherwise 1 for a float.

Return type:

int

f_constraint() → bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction

Returns:

The non-linear, numerical, part of the constraint.

Return type:

bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction

class bluemira.equilibria.optimisation.constraints.AbsoluteMagneticConstraint(x: float | numpy.ndarray, z: float | numpy.ndarray, target_value: float, weights: float | numpy.ndarray = 1.0, tolerance: float | numpy.ndarray | None = None, f_constraint: type[bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction] = AxBConstraint, constraint_type: str = 'equality')

Bases: MagneticConstraint

Abstract base class for absolute magnetic constraints, where the target value is prescribed in absolute terms.

Parameters:

• x (float | numpy.ndarray)

• z (float | numpy.ndarray)

• target_value (float)

• weights (float | numpy.ndarray)

• tolerance (float | numpy.ndarray | None)

• f_constraint (type[bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction])

• constraint_type (str)

x

z

class bluemira.equilibria.optimisation.constraints.RelativeMagneticConstraint(x: float | numpy.ndarray, z: float | numpy.ndarray, ref_x: float, ref_z: float, constraint_value: float = 0.0, weights: float | numpy.ndarray = 1.0, tolerance: float | numpy.ndarray | None = None, f_constraint: type[bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction] = L2NormConstraint, constraint_type: str = 'inequality')

Bases: MagneticConstraint

Abstract base class for relative magnetic constraints, where the target value is prescribed with respect to a reference point.

Parameters:

• x (float | numpy.ndarray)

• z (float | numpy.ndarray)

• ref_x (float)

• ref_z (float)

• constraint_value (float)

• weights (float | numpy.ndarray)

• tolerance (float | numpy.ndarray | None)

• f_constraint (type[bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction])

• constraint_type (str)

x

z

ref_x

ref_z

abstract update_target(equilibrium: bluemira.equilibria.equilibrium.Equilibrium)

Update the target value of the magnetic constraint.

Parameters:

equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

class bluemira.equilibria.optimisation.constraints.FieldNullConstraint(x: float | numpy.ndarray, z: float | numpy.ndarray, weights: float | numpy.ndarray = 1.0, tolerance: float | None = None)

Bases: AbsoluteMagneticConstraint

Magnetic field null constraint. In practice sets the Bx and Bz field components to be 0 at the specified location.

Parameters:

• x (float | numpy.ndarray)

• z (float | numpy.ndarray)

• weights (float | numpy.ndarray)

• tolerance (float | None)

control_response(coilset: bluemira.equilibria.coils.CoilSet) → numpy.ndarray

Calculate control response of a CoilSet to the constraint.

Returns:

Bx and Bz response of the coilset

Parameters:

coilset (bluemira.equilibria.coils.CoilSet)

Return type:

numpy.ndarray

evaluate(eq: bluemira.equilibria.equilibrium.Equilibrium) → numpy.ndarray

Calculate the value of the constraint in an Equilibrium.

Returns:

Bx and Bz response of the equilibrium

Parameters:

eq (bluemira.equilibria.equilibrium.Equilibrium)

Return type:

numpy.ndarray

plot(ax)

Plot the constraint onto an Axes.

__len__() → int

The mathematical size of the constraint.

Return type:

int

class bluemira.equilibria.optimisation.constraints.VerticalFieldConstraint(x: float | numpy.ndarray, z: float | numpy.ndarray, target_value: float, weights: float | numpy.ndarray = 1.0, tolerance: float | numpy.ndarray = 1e-06)

Bases: AbsoluteMagneticConstraint

Absolute vertical field (Bz) constraint.

Parameters:

• x (float | numpy.ndarray)

• z (float | numpy.ndarray)

• target_value (float)

• weights (float | numpy.ndarray)

• tolerance (float | numpy.ndarray)

control_response(coilset: bluemira.equilibria.coils.CoilSet) → numpy.ndarray

Calculate control response of a CoilSet to the constraint.

Returns:

Bz response of the coilset

Parameters:

coilset (bluemira.equilibria.coils.CoilSet)

Return type:

numpy.ndarray

evaluate(eq: bluemira.equilibria.equilibrium.Equilibrium) → numpy.ndarray

Calculate the value of the constraint in an Equilibrium.

Returns:

Bz value of the equilibrium

Parameters:

eq (bluemira.equilibria.equilibrium.Equilibrium)

Return type:

numpy.ndarray

plot(ax)

Plot the constraint onto an Axes.

class bluemira.equilibria.optimisation.constraints.PsiConstraint(x: float | numpy.ndarray, z: float | numpy.ndarray, target_value: float, weights: float | numpy.ndarray = 1.0, tolerance: float | numpy.ndarray | None = None)

Bases: AbsoluteMagneticConstraint

Absolute psi value constraint.

Parameters:

• x (float | numpy.ndarray)

• z (float | numpy.ndarray)

• target_value (float)

• weights (float | numpy.ndarray)

• tolerance (float | numpy.ndarray | None)

control_response(coilset: bluemira.equilibria.coils.CoilSet) → numpy.ndarray

Calculate control response of a CoilSet to the constraint.

Returns:

The coilset psi response

Parameters:

coilset (bluemira.equilibria.coils.CoilSet)

Return type:

numpy.ndarray

evaluate(eq: bluemira.equilibria.equilibrium.Equilibrium) → numpy.ndarray

Calculate the value of the constraint in an Equilibrium.

Returns:

The equilibrium psi

Parameters:

eq (bluemira.equilibria.equilibrium.Equilibrium)

Return type:

numpy.ndarray

plot(ax)

Plot the constraint onto an Axes.

class bluemira.equilibria.optimisation.constraints.IsofluxConstraint(x: float | numpy.ndarray, z: float | numpy.ndarray, ref_x: float, ref_z: float, constraint_value: float = 0.0, weights: float | numpy.ndarray = 1.0, tolerance: float | None = None)

Bases: RelativeMagneticConstraint

Isoflux constraint for a set of points relative to a reference point.

Parameters:

• x (float | numpy.ndarray)

• z (float | numpy.ndarray)

• ref_x (float)

• ref_z (float)

• constraint_value (float)

• weights (float | numpy.ndarray)

• tolerance (float | None)

control_response(coilset: bluemira.equilibria.coils.CoilSet) → numpy.ndarray

Calculate control response of a CoilSet to the constraint.

Returns:

The difference in coilset psi response with the reference

Parameters:

coilset (bluemira.equilibria.coils.CoilSet)

Return type:

numpy.ndarray

evaluate(eq: bluemira.equilibria.equilibrium.Equilibrium) → numpy.ndarray

Calculate the value of the constraint in an Equilibrium.

Returns:

The equilibrium psi

Parameters:

eq (bluemira.equilibria.equilibrium.Equilibrium)

Return type:

numpy.ndarray

update_target(eq: bluemira.equilibria.equilibrium.Equilibrium)

We need to update the target value, as it is a relative constraint.

Parameters:

eq (bluemira.equilibria.equilibrium.Equilibrium)

plot(ax)

Plot the constraint onto an Axes.

class bluemira.equilibria.optimisation.constraints.PsiBoundaryConstraint(x: float | numpy.ndarray, z: float | numpy.ndarray, target_value: float, weights: float | numpy.ndarray = 1.0, tolerance: float | numpy.ndarray | None = None)

Bases: AbsoluteMagneticConstraint

Absolute psi value constraint on the plasma boundary. Gets updated when the plasma boundary flux value is changed.

Parameters:

• x (float | numpy.ndarray)

• z (float | numpy.ndarray)

• target_value (float)

• weights (float | numpy.ndarray)

• tolerance (float | numpy.ndarray | None)

control_response(coilset: bluemira.equilibria.coils.CoilSet) → numpy.ndarray

Calculate control response of a CoilSet to the constraint.

Returns:

The coilset psi response

Parameters:

coilset (bluemira.equilibria.coils.CoilSet)

Return type:

numpy.ndarray

evaluate(eq: bluemira.equilibria.equilibrium.Equilibrium) → numpy.ndarray

Calculate the value of the constraint in an Equilibrium.

Returns:

The equilibrium psi

Parameters:

eq (bluemira.equilibria.equilibrium.Equilibrium)

Return type:

numpy.ndarray

plot(ax)

Plot the constraint onto an Axes.

class bluemira.equilibria.optimisation.constraints.MagneticConstraintSet(constraints: list[MagneticConstraint])

A set of magnetic constraints to be applied to an equilibrium. The optimisation problem is of the form:

[A][x] = [b]

where:

[b] = [target] - [background]

The target vector is the vector of desired values. The background vector is the vector of values due to uncontrolled current terms (plasma and passive coils).

Use of class:

• Inherit from this class

• Add a __init__(args) method

• Populate constraints with super().__init__(List[MagneticConstraint])

Parameters:

constraints (list[MagneticConstraint])

__slots__ = ('A', 'background', 'coilset', 'constraints', 'eq', 'target', 'w')

constraints

eq = None

A = None

target = None

background = None

__call__(equilibrium: bluemira.equilibria.equilibrium.Equilibrium, *, I_not_dI: bool = False, fixed_coils: bool = False)

Update the MagneticConstraintSet

Parameters:

• equilibrium (bluemira.equilibria.equilibrium.Equilibrium)

• I_not_dI (bool)

• fixed_coils (bool)

__len__() → int

The mathematical size of the constraint set.

Return type:

int

get_weighted_arrays() → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Get [A] and [b] scaled by weight matrix. Weight matrix assumed to be diagonal.

Returns:

• weights – the weight matrix

• weighted_a – A scaled by the weight matrix

• weighted_b – b scaled by the weight matrix

Return type:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

build_weight_matrix()

Build the weight matrix used in optimisation. Assumed to be diagonal.

build_control_matrix()

Build the control response matrix used in optimisation.

build_target()

Build the target value vector.

build_background()

Build the background value vector.

property b: numpy.ndarray

The b vector of target - background values.

Return type:

numpy.ndarray

update_psi_boundary(psi_bndry: float)

Update the target value for all PsiBoundaryConstraints.

Parameters:

psi_bndry (float) – The target psi boundary value [V.s/rad]

plot(ax=None)

Plots constraints

Returns:

The plot axis

class bluemira.equilibria.optimisation.constraints.AutoConstraints(x: numpy.ndarray, z: numpy.ndarray, psi_boundary: float | None = None, n_points: int = 40)

Bases: MagneticConstraintSet

Utility class for crude reconstruction of magnetic constraints from a specified LCFS set of coordinates.

Parameters:

• x (numpy.ndarray) – The x coordinates of the LCFS

• z (numpy.ndarray) – The z coordinates of the LCFS

• psi_boundary (float | None) – The psi boundary value to use as a constraint. If None, an isoflux constraint is used.

• n_points (int) – The number of interpolated points to use