simsopt.objectives package

class simsopt.objectives.ConstrainedProblem(f_obj: Callable, tuples_nlc: Sequence[Tuple[Callable, Real, Real]] = None, tuple_lc: Tuple[Sequence[Real] | ndarray[tuple[Any, ...], dtype[float64]], Sequence[Real] | ndarray[tuple[Any, ...], dtype[float64]] | Real, Sequence[Real] | ndarray[tuple[Any, ...], dtype[float64]] | Real] = None, fail: float | None = 1000000000000.0)

Bases: Optimizable

Represents a nonlinear, constrained optimization problem implemented using the graph based optimization framework. A ConstrainedProblem instance has 4 basic attributes: an objective, nonlinear constraints, linear constraints, and bound constraints. Problems take the general form:

\[ \begin{align}\begin{aligned}\min_x f(x)\\\text{s.t.}\\l_{\text{nlc}} \leq c(x) \leq u_{\text{nlc}}\\l_{\text{lc}} \leq Ax \leq u_{\text{lc}}\end{aligned}\end{align} \]

Constrained optimization problems can be solved with the constrained_mpi_solve or constrained_serial_solve functions. Typically, this class is used for Stage-I optimization.

Whereas linear and nonlinear constraints are passed as arguments to this class, bound constraints should be specified directly through the Optimizable objects. For instance, with an optimizable object v we can set the upper bounds of the free DOFs associated with the current Optimizable object and those of its ancestors via v.upper_bounds = ub where ub is a 1d-array. To set the upper bounds on the free dofs of a single optimizable object (and not it’s ancestors) use v.local_upper_bounds = ub. The upper bound of a single dof can be set with v.set_upper_bound(dof_name,value).

Parameters:

  • f_obj (Callable) – objective function handle (generally a method of an Optimizable instance)

  • tuples_nlc (list) – Nonlinear constraints as a sequence of triples containing the nonlinear constraint function, \(c\), with lower and upper bounds i.e. [(c,l_{nlc},u_{nlc}), ...]. Each constraint handle, \(c\), can be scalar-valued or be vector valued. Similarly, the constraint bounds \(l_{\text{nlc}}\), \(u_{\text{nlc}}\) can be scalars or 1d-arrays. Use +-np.inf to indicate unbounded components, and define equality constraints by using equal upper and lower bounds.

  • tuple_lc (tuple) – A tuple containing the matrix \(A\), lower and upper bounds, for the linear constraints i.e. \((A, l_{\text{lc}}, u_{\text{lc}})\). Constraint bounds can be 1d-arrays or scalars. Use +-np.inf in the bounds to indicate unbounded components, define equality constraints by using equal upper and lower bounds.

  • fail (float, optional) – If an objective or nonlinear constraint evaluation fails, the value returned is set to this value.

all_funcs(x=None, *args, **kwargs)

Evaluate the objective and nonlinear constraints.

Parameters:

  • x (array, Optional) – Degrees of freedom. If not provided, the current degrees of freedom are used.

  • args – Any additional arguments passed to the objective and nonlinear constraint functions.

  • kwargs – Keyword arguments passed to the objective and nonlinear constraint functions.

Returns:

Array containing the objective and nonlinear constraints, ordered as \([f(x), l_{\text{nlc}} - c(x), c(x) - u_{\text{nlc}},...]\)

nonlinear_constraints(x=None, *args, **kwargs)

Evaluates the nonlinear constraints, \(l_{\text{nlc}} \leq c(x) \leq u_{\text{nlc}}\).

Parameters:

  • x (array, Optional) – Degrees of freedom. If not provided, the current degrees of freedom are used.

  • args – Any additional arguments passed to the nonlinear constraint functions.

  • kwargs – Keyword arguments passed to the nonlinear constraint functions.

Returns:

Array containing the nonlinear constraints, ordered as \([l_{\text{nlc}} - c(x), c(x) - u_{\text{nlc}},...]\).

objective(x=None, *args, **kwargs)

Evaluate the objective function, \(f(x)\).

Parameters:

  • x (array, Optional) – Degrees of freedom. If not provided, the current degrees of freedom are used.

  • args – Any additional arguments passed to the objective function.

  • kwargs – Keyword arguments passed to the objective function.

Returns:

(float) Objective function value.

class simsopt.objectives.LeastSquaresProblem(goals: Real | Sequence[Real] | ndarray[tuple[Any, ...], dtype[float64]], weights: Real | Sequence[Real] | ndarray[tuple[Any, ...], dtype[float64]], funcs_in: Sequence[Callable] = None, depends_on: Optimizable | Sequence[Optimizable] = None, opt_return_fns: Sequence | Sequence[Sequence[str]] = None, fail: None | float = 1000000000000.0)

Bases: Optimizable

Represents a nonlinear-least-squares problem implemented using the graph based optimization framework. A LeastSquaresProblem instance has 3 basic attributes: a set of functions (f_in), target values for each of the functions (goal), and weights. The residual (f_out) for each of the f_in is defined as:

\[f_{out} = weight * (f_{in} - goal) ^ 2\]
Parameters:

  • goals – Targets for residuals in optimization

  • weights – Weight associated with each of the residual

  • funcs_in – Input functions (Generally one of the output functions of the Optimizable instances

  • depends_on – (Alternative initialization) Instead of specifying funcs_in, one could specify the Optimizable objects

  • opt_return_fns – (Alternative initialization) If using depends_on, specify the return functions associated with each Optimizable object

classmethod from_sigma(goals: Real | Sequence[Real] | ndarray[tuple[Any, ...], dtype[float64]], sigma: Real | Sequence[Real] | ndarray[tuple[Any, ...], dtype[float64]], funcs_in: Sequence[Callable] = None, depends_on: Optimizable | Sequence[Optimizable] = None, opt_return_fns: Sequence | Sequence[Sequence[str]] = None, fail: None | float = 1000000000000.0) → LeastSquaresProblem

Define the LeastSquaresProblem with

\[\begin{split}\sigma = 1/\sqrt{weight}, \text{so} \\ f_{out} = \left(\frac{f_{in} - goal}{\sigma}\right) ^ 2.\end{split}\]
Parameters:

  • goals – Targets for residuals in optimization

  • sigma – Inverse of the sqrt of the weight associated with each of the residual

  • funcs_in – Input functions (Generally one of the output functions of the Optimizable instances

  • depends_on – (Alternative initialization) Instead of specifying funcs_in, one could specify the Optimizable objects

  • opt_return_fns – (Alternative initialization) If using depends_on, specify the return functions associated with each Optimizable object

classmethod from_tuples(tuples: Sequence[Tuple[Callable, Real, Real]], fail: None | float = 1000000000000.0) → LeastSquaresProblem

Initializes graph based LeastSquaresProblem from a sequence of tuples containing f_in, goal, and weight.

Parameters:

tuples – A sequence of tuples containing (f_in, goal, weight) in each tuple (the specified order matters).

objective(x=None, *args, **kwargs)

Return the least squares sum

Parameters:

  • x – Degrees of freedom or state

  • args – Any additional arguments

  • kwargs – Keyword arguments

residuals(x=None, *args, **kwargs)

Return the weighted residuals

Parameters:

  • x – Degrees of freedom or state

  • args – Any additional arguments

  • kwargs – Keyword arguments

return_fn_map: Dict[str, Callable] = {'objective': <function LeastSquaresProblem.objective>, 'residuals': <function LeastSquaresProblem.residuals>}
unweighted_residuals(x=None, *args, **kwargs)

Return the unweighted residuals (f_in - goal)

Parameters:

  • x – Degrees of freedom or state

  • args – Any additional arguments

  • kwargs – Keyword arguments

class simsopt.objectives.MPIObjective(objectives, comm, needs_splitting=False)

Bases: Optimizable

J()
__init__(objectives, comm, needs_splitting=False)

Compute the mean of a list of objectives in parallel using MPI.

Parameters:

  • objectives – A python list of objectives that provide .J() and .dJ() functions.

  • comm – The MPI communicator to use.

  • needs_splitting – if set to True, then the list of objectives is split into disjoint partitions and only one part is worked on per mpi rank. If set to False, then we assume that the user constructed the list of objectives so that it only contains the objectives relevant to that mpi rank.

dJ(*args, partials=False, **kwargs)
class simsopt.objectives.MPIOptimizable(optimizables, attributes, comm)

Bases: Optimizable

__init__(optimizables, attributes, comm)

Ensures that a list of Optimizables on separate ranks have a consistent set of attributes on all ranks. For example, say that all ranks have the list optimizables. Rank i modifies attributes of optimizable[i]. The value attribute attr, i.e., optimizables[i].attr potentially will be different on ranks i and j, for i not equal to j. This class ensures that if the cache is invalidated on the Optimizables in the list optimizables, then when the list is accessed, the attributes in attributes will be communicated accross all ranks.

Parameters:

  • objectives – A python list of Optimizables with attributes in attributes that can be communicated using mpi4py.

  • attributes – A python list of strings corresponding to the list of attributes that is to be maintained consistent across all ranks.

  • comm – The MPI communicator to use.

communicate()
recompute_bell(parent=None)

Function to be called whenever new DOFs input is given or if the parent Optimizable’s data changed, so the output from the current Optimizable object is invalid.

This method gets called by various DOF setters. If only the local DOFs of an object are being set, the recompute_bell method is called in that object and also in the descendent objects that have a dependency on the object, whose local DOFs are being changed. If gloabl DOFs of an object are being set, the recompute_bell method is called in the object, ancestors of the object, as well as the descendents of the object.

Need to be implemented by classes that provide a dof_setter for external handling of DOFs.

class simsopt.objectives.QuadraticPenalty(obj, cons=0.0, f='identity')

Bases: Optimizable

J()
__init__(obj, cons=0.0, f='identity')

A quadratic penalty function of the form \(0.5f(\text{obj}.J() - \text{cons})^2\) for an underlying objective obj and wrapping function f. This can be used to implement a barrier penalty function for (in)equality constrained optimization problem. The wrapping function defaults to "identity".

Parameters:

  • obj – the underlying objective. It should provide a .J() and .dJ() function.

  • cons – constant

  • f – the function that wraps the difference \(obj-\text{cons}\). The options are "min", "max", or "identity". which respectively return \(\min(\text{obj}-\text{cons}, 0)\), \(\max(\text{obj}-\text{cons}, 0)\), and \(\text{obj}-\text{cons}\).

dJ(*args, partials=False, **kwargs)
return_fn_map: Dict[str, Callable] = {'J': <function QuadraticPenalty.J>, 'dJ': <function derivative_dec.<locals>._derivative_dec>}
class simsopt.objectives.SquaredFlux(surface, field, target=None, definition='quadratic flux')

Bases: Optimizable

Objective representing quadratic-flux-like quantities, useful for stage-2 coil optimization. Several variations are available, which can be selected using the definition argument. For definition="quadratic flux" (the default), the objective is defined as

\[J = \frac12 \int_{S} (\mathbf{B}\cdot \mathbf{n} - B_T)^2 ds,\]

where \(\mathbf{n}\) is the surface unit normal vector and \(B_T\) is an optional (zero by default) target value for the magnetic field. Also \(\int_{S} ds\) indicates a surface integral. For definition="normalized", the objective is defined as

\[J = \frac12 \frac{\int_{S} (\mathbf{B}\cdot \mathbf{n} - B_T)^2 ds} {\int_{S} |\mathbf{B}|^2 ds}.\]

For definition="local", the objective is defined as

\[J = \frac12 \int_{S} \frac{(\mathbf{B}\cdot \mathbf{n} - B_T)^2}{|\mathbf{B}|^2} ds.\]

The definition "quadratic flux" has the advantage of simplicity, and it is used in other contexts such as REGCOIL. However for stage-2 optimization, the optimizer can “cheat”, lowering this objective by reducing the magnitude of the field. The definitions "normalized" and "local" close this loophole.

Parameters:

  • surface – A simsopt.geo.surface.Surface object on which to compute the flux

  • field – A simsopt.field.magneticfield.MagneticField for which to compute the flux.

  • target – A nphi x ntheta numpy array containing target values for the flux. Here nphi and ntheta correspond to the number of quadrature points on surface in phi and theta direction.

  • definition – A string to select among the definitions above. The available options are "quadratic flux", "normalized", and "local".

J()
dJ(*args, partials=False, **kwargs)
class simsopt.objectives.Weight(value)

Bases: object

simsopt.objectives.forward_backward(P, L, U, rhs, iterative_refinement=False)

Solve a linear system of the form (PLU)^T*adj = rhs for adj.

Parameters:

  • P – permutation matrix

  • L – lower triangular matrix

  • U – upper triangular matrix

  • iterative_refinement – when true, applies iterative refinement which can improve the accuracy of the computed solution when the matrix is particularly ill-conditioned.