simsopt.core

Submodules

simsopt.core.dofs module

This module provides the collect_dofs() function, used by least-squares and general optimization problems.

This module should not depend on anything involving communication (e.g. MPI) or on specific types of optimization problems.

class simsopt.core.dofs.Dofs(funcs)

Bases: object

This class holds data related to the vector of degrees of freedom that have been combined from multiple optimizable objects, keeping only the non-fixed dofs.

f(x=None)

Return the vector of function values. Result is a 1D numpy array.

If the argument x is not supplied, the functions will be evaluated for the present state vector. If x is supplied, then first set_dofs() will be called for each object to set the global state vector to x.

fd_jac(x=None, eps=1e-07, centered=False)

Compute the finite-difference Jacobian of the functions with respect to all non-fixed degrees of freedom. Either a 1-sided or centered-difference approximation is used, with step size eps.

If the argument x is not supplied, the Jacobian will be evaluated for the present state vector. If x is supplied, then first get_dofs() will be called for each object to set the global state vector to x.

No parallelization is used here.

jac(x=None)

Return the Jacobian, i.e. the gradients of all the functions that were originally supplied to Dofs(). Result is a 2D numpy array.

If the argument x is not supplied, the Jacobian will be evaluated for the present state vector. If x is supplied, then first set_dofs() will be called for each object to set the global state vector to x.

set(x)

Call set_dofs() for each object, given a global state vector x.

property x

Call get_dofs() for each object, to assemble an up-to-date version of the state vector.

simsopt.core.dofs.get_owners(obj, owners_so_far=[])

Given an object, return a list of objects that own any degrees of freedom, including both the input object and any of its dependendents, if there are any.

simsopt.core.functions module

This module provides a few minimal optimizable objects, each representing a function. These functions are mostly used for testing.

class simsopt.core.functions.Adder(n=3)

Bases: simsopt.core.optimizable.Optimizable

This class defines a minimal object that can be optimized. It has n degrees of freedom, and has a function that just returns the sum of these dofs. This class is used for testing.

J()

Returns the sum of the degrees of freedom.

dJ()
property df

Same as the function dJ(), but a property instead of a function.

property f

Same as the function J(), but a property instead of a function.

get_dofs()
set_dofs(xin)
class simsopt.core.functions.Affine(nparams, nvals)

Bases: simsopt.core.optimizable.Optimizable

This class represents a random affine (i.e. linear plus constant) transformation from R^n to R^m.

J()
dJ()
get_dofs()
set_dofs(x)
class simsopt.core.functions.Identity(x=0.0)

Bases: simsopt.core.optimizable.Optimizable

This class represents a term in an objective function which is just the identity. It has one degree of freedom, and the output of the function is equal to this degree of freedom.

J()
dJ()
property df

Same as the function dJ(), but a property instead of a function.

property f

Same as the function J(), but a property instead of a function.

get_dofs()
set_dofs(xin)
class simsopt.core.functions.Rosenbrock(b=100.0, x=0.0, y=0.0)

Bases: simsopt.core.optimizable.Optimizable

This class defines a minimal object that can be optimized.

dterm1()

Returns the gradient of term1

property dterm1prop

Same as dterm1, but a property rather than a callable function.

dterm2()

Returns the gradient of term2

property dterm2prop

Same as dterm2, but a property rather than a callable function.

dterms()

Returns the 2x2 Jacobian for term1 and term2.

f()

Returns the total function, squaring and summing the two terms.

get_dofs()
set_dofs(xin)
term1()

Returns the first of the two quantities that is squared and summed.

property term1prop

Same as term1, but a property rather than a callable function.

term2()

Returns the second of the two quantities that is squared and summed.

property term2prop

Same as term2, but a property rather than a callable function.

terms()

Returns term1 and term2 together as a 2-element numpy vector.

class simsopt.core.functions.TestObject1(val)

Bases: simsopt.core.optimizable.Optimizable

This is an optimizable object used for testing. It depends on two sub-objects, both of type Adder.

J()
dJ()
property df

Same as dJ() but a property instead of a function.

property f

Same as J() but a property instead of a function.

get_dofs()
set_dofs(x)
class simsopt.core.functions.TestObject2(val1, val2)

Bases: simsopt.core.optimizable.Optimizable

This is an optimizable object used for testing. It depends on two sub-objects, both of type Adder.

J()
dJ()
property df

Same as dJ() but a property instead of a function.

property f

Same as J() but a property instead of a function.

get_dofs()
set_dofs(x)

simsopt.core.least_squares_problem module

This module provides the LeastSquaresProblem class, as well as the associated class LeastSquaresTerm.

class simsopt.core.least_squares_problem.LeastSquaresProblem(terms)

Bases: object

This class represents a nonlinear-least-squares optimization problem. The class stores a list of LeastSquaresTerm objects.

f(x=None)

This method returns the vector of residuals for a given state vector x. This function is passed to scipy.optimize, and could be passed to other optimization algorithms too. This function differs from Dofs.f() because it shifts and scales the terms.

If the argument x is not supplied, the residuals will be evaluated for the present state vector. If x is supplied, then first set_dofs() will be called for each object to set the global state vector to x.

f_from_unshifted(f_unshifted)

This function takes a vector of function values, as returned by dofs, and shifts and scales them. This function does not actually evaluate the dofs.

jac(x=None, **kwargs)

This method gives the Jacobian of the residuals with respect to the parameters, if it is available, given the state vector x. This function is passed to scipy.optimize, and could be passed to other optimization algorithms too. This Jacobian differs from the one returned by Dofs() because it accounts for the ‘weight’ scale factors.

If the argument x is not supplied, the Jacobian will be evaluated for the present state vector. If x is supplied, then first set_dofs() will be called for each object to set the global state vector to x.

kwargs is passed to Dofs.fd_jac().

objective(x=None)

Return the value of the total objective function, by summing the terms.

If the argument x is not supplied, the objective will be evaluated for the present state vector. If x is supplied, then first set_dofs() will be called for each object to set the global state vector to x.

objective_from_shifted_f(f)

Given a vector of functions that has already been evaluated, and already shifted and scaled, convert the result to the overall scalar objective function, without any further function evaluations. This routine is useful if we have already evaluated the residuals and we want to convert the result to the overall scalar objective without the computational expense of further function evaluations.

objective_from_unshifted_f(f_unshifted)

Given a vector of functions that has already been evaluated, but not yet shifted and scaled, convert the result to the overall scalar objective function, without any further function evaluations. This routine is useful if we have already evaluated the residuals and we want to convert the result to the overall scalar objective without the computational expense of further function evaluations.

scale_dofs_jac(jmat)

Given a Jacobian matrix j for the Dofs() associated to this least-squares problem, return the scaled Jacobian matrix for the least-squares residual terms. This function does not actually compute the Dofs() Jacobian, since sometimes we would compute that directly whereas other times we might compute it with serial or parallel finite differences. The provided jmat is scaled in-place.

property x

Return the state vector.

class simsopt.core.least_squares_problem.LeastSquaresTerm(f_in, goal, weight)

Bases: object

This class represents one term in a nonlinear-least-squares problem. A LeastSquaresTerm instance has 3 basic attributes: a function (called f_in), a goal value (called goal), and a weight (sigma). The overall value of the term is:

f_out = weight * (f_in - goal) ** 2.

f_out()

Return the overall value of this least-squares term.

classmethod from_sigma(f_in, goal, sigma)

Define the LeastSquaresTerm with sigma = 1 / sqrt(weight), so

f_out = ((f_in - goal) / sigma) ** 2.

simsopt.core.optimizable module

This module provides classes and functions that are useful for setting up optimizable objects and objective functions.

class simsopt.core.optimizable.Optimizable

Bases: object

This base class provides some useful features for optimizable functions.

all_fixed(fixed_new=True)

Set the ‘fixed’ attribute for all degrees of freedom.

get(dof_str)

Return a degree of freedom specified by its string name.

get_dofs()
get_fixed(dof_str)

Return the fixed attribute for a given degree of freedon, specified by dof_str.

index(dof_str)

Given a string dof_str, returns the index in the dof array whose name matches dof_str. If dof_str does not match any of the names, ValueError will be raised.

set(dof_str, newval)

Set a degree of freedom specified by its string name.

set_dofs(x)
set_fixed(dof_str, fixed_new=True)

Set the fixed attribute for a given degree of freedom, specified by dof_str.

class simsopt.core.optimizable.Target(obj, attr)

Bases: simsopt.core.optimizable.Optimizable

Given an attribute of an object, which typically would be a @property, form a callable function that can be used as a target for optimization.

J()
get_dofs()
set_dofs(v)
simsopt.core.optimizable.function_from_user(target)

Given a user-supplied “target” to be optimized, extract the associated callable function.

simsopt.core.optimizable.optimizable(obj)

Given any object, add attributes like fixed, mins, and maxs. fixed = False by default. Also, add the other methods of Optimizable to the object.

simsopt.core.surface module

This module provides several classes for representing toroidal surfaces. There is a base class Surface, and several child classes corresponding to different discrete representations.

class simsopt.core.surface.Surface(nfp=1, stelsym=True)

Bases: simsopt.core.optimizable.Optimizable

Surface is a base class for various representations of toroidal surfaces in simsopt.

to_RZFourier()

Return a SurfaceRZFourier instance corresponding to the shape of this surface. All subclasses should implement this abstract method.

class simsopt.core.surface.SurfaceGarabedian(nfp=1, mmax=1, mmin=0, nmax=0, nmin=None)

Bases: simsopt.core.surface.Surface

SurfaceGarabedian represents a toroidal surface for which the shape is parameterized using Garabedian’s Delta_{m,n} coefficients.

The present implementation assumes stellarator symmetry. Note that non-stellarator-symmetric surfaces require that the Delta_{m,n} coefficients be imaginary.

allocate()

Create the array for the Delta_{m,n} coefficients.

area()

Return the area of the surface.

area_volume()

Compute the surface area and the volume enclosed by the surface.

fixed_range(mmin, mmax, nmin, nmax, fixed=True)

Set the ‘fixed’ property for a range of m and n values.

All modes with m in the interval [mmin, mmax] and n in the interval [nmin, nmax] will have their fixed property set to the value of the ‘fixed’ parameter. Note that mmax and nmax are included (unlike the upper bound in python’s range(min, max).)

get_Delta(m, n)

Return a particular Delta_{m,n} coefficient.

get_dofs()

Return a 1D numpy array with all the degrees of freedom.

set_Delta(m, n, val)

Set a particular Delta_{m,n} coefficient.

set_dofs(v)

Set the shape coefficients from a 1D list/array

to_RZFourier()

Return a SurfaceRZFourier object with the identical shape.

For a derivation of the transformation here, see https://terpconnect.umd.edu/~mattland/assets/notes/toroidal_surface_parameterizations.pdf

volume()

Return the volume of the surface.

class simsopt.core.surface.SurfaceRZFourier(nfp=1, stelsym=True, mpol=1, ntor=0)

Bases: simsopt.core.surface.Surface

SurfaceRZFourier is a surface that is represented in cylindrical coordinates using the following Fourier series:

r(theta, phi) = sum_{m=0}^{mpol} sum_{n=-ntor}^{ntor} [

r_{c,m,n} cos(m heta - n nfp phi) + r_{s,m,n} sin(m heta - n nfp phi) ]

and the same for z(theta, phi).

Here, (r, phi, z) are standard cylindrical coordinates, and theta is any poloidal angle.

allocate()

Create the arrays for the rc, rs, zc, and zs coefficients.

area()

Return the area of the surface.

area_volume()

Compute the surface area and the volume enclosed by the surface.

change_resolution(mpol, ntor)

Change the values of mpol and ntor. Any new Fourier amplitudes will have a magnitude of zero. Any previous nonzero Fourier amplitudes that are not within the new range will be discarded.

darea()

Return the area of the surface.

darea_volume()

Compute the derivative of the surface area and the volume enclosed by the surface.

dvolume()

Return the volume of the surface.

fixed_range(mmin, mmax, nmin, nmax, fixed=True)

Set the ‘fixed’ property for a range of m and n values.

All modes with m in the interval [mmin, mmax] and n in the interval [nmin, nmax] will have their fixed property set to the value of the ‘fixed’ parameter. Note that mmax and nmax are included (unlike the upper bound in python’s range(min, max).)

classmethod from_focus(filename)

Read in a surface from a FOCUS-format file.

get_dofs()

Return a 1D numpy array with all the degrees of freedom.

get_rc(m, n)

Return a particular rc Parameter.

get_rs(m, n)

Return a particular rs Parameter.

get_zc(m, n)

Return a particular zc Parameter.

get_zs(m, n)

Return a particular zs Parameter.

make_names(prefix, include0)

Form a list of names of the rc, zs, rs, or zc array elements.

set_dofs(v)

Set the shape coefficients from a 1D list/array

set_rc(m, n, val)

Set a particular rc Parameter.

set_rs(m, n, val)

Set a particular rs Parameter.

set_zc(m, n, val)

Set a particular zc Parameter.

set_zs(m, n, val)

Set a particular zs Parameter.

to_Garabedian()

Return a SurfaceGarabedian object with the identical shape.

For a derivation of the transformation here, see https://terpconnect.umd.edu/~mattland/assets/notes/toroidal_surface_parameterizations.pdf

to_RZFourier()

No conversion necessary.

volume()

Return the volume of the surface.

simsopt.core.surface.area_volume_pure(rc, rs, zc, zs, stelsym, nfp, mpol, ntor, ntheta, nphi)

Compute the area and volume of a surface. This pure function is designed for automatic differentiation.

simsopt.core.surface.jit_area_volume_pure(rc, rs, zc, zs, stelsym, nfp, mpol, ntor, ntheta, nphi)

Compute the area and volume of a surface. This pure function is designed for automatic differentiation.

simsopt.core.util module

This module contains small utility functions and classes.

class simsopt.core.util.Struct

Bases: object

This class is just a dummy mutable object to which we can add attributes.

simsopt.core.util.isbool(val)

Test whether val is any boolean type, either the native python bool or numpy’s bool_.

simsopt.core.util.isnumber(val)

Test whether val is any kind of number, including both native python types or numpy types.

simsopt.core.util.unique(inlist)

Given a list or tuple, return a list in which all duplicate entries have been removed. Unlike a python set, the order of entries in the original list will be preserved. There is surely a faster algorithm than the one used here, but this function will not be used in performance-critical code.

Module contents