bluemira.equilibria.optimisation.constraint_funcs ================================================= .. py:module:: bluemira.equilibria.optimisation.constraint_funcs .. autoapi-nested-parse:: Equilibrium optimisation constraint functions. Constraint functions must be of the form: .. code-block:: python class Constraint(ConstraintFunction): def f_constraint(self, vector: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]: return constraint_calc(vector) def df_constraint(self, vector: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]: return gradient_calc(vector) The constraint function convention is such that c <= 0 is sought. I.e. all constraint values must be negative. Note that the gradient (Jacobian) of the constraint function is of the form: .. math:: \nabla \mathbf{c} = \begin{bmatrix} \dfrac{\partial c_{0}}{\partial x_0} & \dfrac{\partial c_{0}}{\partial x_1} & ... \dfrac{\partial c_{1}}{\partial x_0} & \dfrac{\partial c_{1}}{\partial x_1} & ... ... & ... & ... \end{bmatrix} If the `df_constraint` function is not provided, the constraint can still be used for derivative-free optimisation algorithms, but will need to be updated or approximated for use in derivative based algorithms, such as those utilising gradient descent. Classes ------- .. autoapisummary:: bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction bluemira.equilibria.optimisation.constraint_funcs.AxBConstraint bluemira.equilibria.optimisation.constraint_funcs.L2NormConstraint bluemira.equilibria.optimisation.constraint_funcs.FieldConstraintFunction bluemira.equilibria.optimisation.constraint_funcs.CurrentMidplanceConstraint bluemira.equilibria.optimisation.constraint_funcs.CoilForceConstraintFunctions bluemira.equilibria.optimisation.constraint_funcs.CoilForceConstraint Module Contents --------------- .. py:class:: ConstraintFunction Bases: :py:obj:`abc.ABC` .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.constraint_funcs.ConstraintFunction :parts: 1 :private-bases: Override to define a numerical constraint for a coilset optimisation. .. py:property:: name :type: str | None The name of the constraint .. py:method:: f_constraint(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64] :abstractmethod: The constraint function. .. py:property:: constraint_type :type: Literal['inequality', 'equality'] The type of constraint .. py:class:: AxBConstraint(a_mat: numpy.typing.NDArray[numpy.float64], b_vec: numpy.typing.NDArray[numpy.float64], value: float, scale: float, name: str | None = None) Bases: :py:obj:`ConstraintFunction` .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.constraint_funcs.AxBConstraint :parts: 1 :private-bases: Constraint function of the form: A.x - b < value :param a_mat: Response matrix :param b_vec: Target value vector :param value: Target constraint value :param scale: Current scale with which to calculate the constraints .. py:attribute:: a_mat .. py:attribute:: b_vec .. py:attribute:: value .. py:attribute:: scale .. py:attribute:: name :value: None The name of the constraint .. py:method:: f_constraint(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64] Constraint function .. py:method:: df_constraint(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64] Constraint derivative .. py:class:: L2NormConstraint(a_mat: numpy.typing.NDArray[numpy.float64], b_vec: numpy.typing.NDArray[numpy.float64], value: float, scale: float, name: str | None = None) Bases: :py:obj:`ConstraintFunction` .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.constraint_funcs.L2NormConstraint :parts: 1 :private-bases: Constrain the L2 norm of an Ax = b system of equations. ||(Ax - b)||² < value :param a_mat: Response matrix :param b_vec: Target value vector :param value: Target constraint value :param scale: Current scale with which to calculate the constraints .. py:attribute:: a_mat .. py:attribute:: b_vec .. py:attribute:: value .. py:attribute:: scale .. py:attribute:: name :value: None The name of the constraint .. py:method:: f_constraint(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64] Constraint function .. py:method:: df_constraint(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64] Constraint derivative .. py:class:: FieldConstraintFunction(ax_mat: numpy.typing.NDArray[numpy.float64], az_mat: numpy.typing.NDArray[numpy.float64], bxp_vec: numpy.typing.NDArray[numpy.float64], bzp_vec: numpy.typing.NDArray[numpy.float64], B_max: numpy.typing.NDArray[numpy.float64], scale: float, name: str | None = None, *, round_dp: int = 16) Bases: :py:obj:`ConstraintFunction` .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.constraint_funcs.FieldConstraintFunction :parts: 1 :private-bases: Current optimisation poloidal field constraints at prescribed locations :param ax_mat: Response matrix for Bx (active coil contributions) :param az_mat: Response matrix for Bz (active coil contributions) :param bxp_vec: Background vector for Bx (passive coil contributions) :param bzp_vec: Background vector for Bz (passive coil contributions) :param B_max: Maximum fields inside the coils :param scale: Current scale with which to calculate the constraints :param name: name of constraint (used in error reporting) :param round_dp: round the output of the constraint (to maintain numerical stability) .. py:attribute:: ax_mat .. py:attribute:: az_mat .. py:attribute:: bxp_vec .. py:attribute:: bzp_vec .. py:attribute:: B_max .. py:attribute:: scale .. py:attribute:: name :value: None The name of the constraint .. py:attribute:: _round_dp :value: 16 .. py:method:: f_constraint(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64] Constraint function .. py:method:: df_constraint(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64] Constraint derivative .. py:class:: CurrentMidplanceConstraint(eq: bluemira.equilibria.equilibrium.Equilibrium, radius: float, scale: float, *, inboard: bool, name: str | None = None) Bases: :py:obj:`ConstraintFunction` .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.constraint_funcs.CurrentMidplanceConstraint :parts: 1 :private-bases: Constraint function to constrain the inboard or outboard midplane of the plasma during optimisation. :param eq: Equilibrium to use to fetch last closed flux surface from. :param radius: Toroidal radius at which to constrain the plasma midplane. :param scale: Current scale with which to calculate the constraints :param inboard: Boolean controlling whether to constrain the inboard (if True) or outboard (if False) side of the plasma midplane. .. py:attribute:: eq .. py:attribute:: radius .. py:attribute:: scale .. py:attribute:: inboard .. py:attribute:: name :value: None The name of the constraint .. py:method:: f_constraint(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64] Constraint function .. py:class:: CoilForceConstraintFunctions(a_mat: numpy.typing.NDArray[numpy.float64], b_vec: numpy.typing.NDArray[numpy.float64], n_PF: int, n_CS: int, scale: float = 1000000.0) Constraint functions to constrain the force applied to the coils :param a_mat: Response matrix :param b_vec: Target value vector :param n_PF: Number of PF coils :param n_CS: Number of CS coils :param scale: Force scale with which to calculate the constraints .. py:attribute:: a_mat .. py:attribute:: b_vec .. py:attribute:: n_PF .. py:attribute:: n_CS .. py:attribute:: scale :value: 1000000.0 .. py:attribute:: n_coils .. py:attribute:: _constraint .. py:attribute:: _grad .. py:property:: constraint Constraint .. py:property:: grad Constraint Gradient .. py:method:: calc_f_matx(currents) :returns: Force matrix .. py:method:: calc_df_matx(currents) :returns: Force Jacobian .. py:method:: cs_fz(f_matx) :returns: Vertical forces on CS coils. .. py:method:: pf_z_constraint(f_matx, max_value) Constraint Function Absolute vertical force constraint on PF coils. .. py:method:: pf_z_constraint_grad(f_matx, df_matx) Constraint Derivative: Absolute vertical force constraint on PF coils. .. py:method:: cs_z_constraint(f_matx, max_value) Constraint Function: Absolute sum of vertical force constraint on entire CS stack. .. py:method:: cs_z_grad(f_matx, df_matx) Constraint Derivative: Absolute sum of vertical force constraint on entire CS stack .. py:method:: cs_z_sep_constraint(f_matx, max_value) Constraint Function: CS separation constraints. .. py:method:: cs_z_sep_grad(df_matx) Constraint Derivative: CS separation constraints. .. py:class:: CoilForceConstraint(a_mat: numpy.typing.NDArray[numpy.float64], b_vec: numpy.typing.NDArray[numpy.float64], n_PF: int, n_CS: int, PF_Fz_max: float, CS_Fz_sum_max: float, CS_Fz_sep_max: float, scale: float, name: str | None = None, *, round_dp: int = 16) Bases: :py:obj:`ConstraintFunction`, :py:obj:`CoilForceConstraintFunctions` .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.constraint_funcs.CoilForceConstraint :parts: 1 :private-bases: Combined constraint function for: - PF vertical force, - CS vertical force, - and CS separation. :param a_mat: Response matrix :param b_vec: Target value vector :param n_PF: Number of PF coils :param n_CS: Number of CS coils :param PF_Fz_max: The maximum force in the z direction for a PF coil :param CS_Fz_sum_max: The total maximum force in the z direction for the CS coils :param CS_Fz_sep_max: The individual maximum force in the z direction for the CS coils :param scale: Current scale with which to calculate the constraints :param name: name of constraint (used in error reporting) :param round_dp: round the output of the constraint (to maintain numerical stability) .. py:attribute:: PF_Fz_max .. py:attribute:: CS_Fz_sum_max .. py:attribute:: CS_Fz_sep_max .. py:attribute:: name :value: None The name of the constraint .. py:attribute:: _round_dp :value: 16 .. py:method:: f_constraint(vector) Constraint function :returns: Coil force .. py:method:: df_constraint(vector) Constraint derivative :returns: Derivative of the coil force