Add coil objectives to docs (#1125)

Adds new objectives for coil optimization to public docs.

Also fixes some minor formatting issues.

desc/coils.py

@@ -1158,7 +1158,7 @@ def from_symmetry(cls, coils, NFP=1, sym=False):
 
         Parameters
         ----------
-        coils : Coil, CoilGroup, Coilset
+        coils : Coil, CoilSet
             Coil or collection of coils in one field period or half field period.
         NFP : int (optional)
             Number of field periods for enforcing field period symmetry.
@@ -1537,10 +1537,10 @@ def is_self_intersecting(self, grid=None, tol=None):
             possibly be intersecting.
 
         """
-        from desc.objectives._coils import CoilsetMinDistance
+        from desc.objectives._coils import CoilSetMinDistance
 
         grid = grid if grid else LinearGrid(N=100)
-        obj = CoilsetMinDistance(self, grid=grid)
+        obj = CoilSetMinDistance(self, grid=grid)
         obj.build(verbose=0)
         if tol:
             min_dists = obj.compute(self.params_dict)

desc/objectives/__init__.py

@@ -5,9 +5,9 @@
     CoilCurrentLength,
     CoilCurvature,
     CoilLength,
-    CoilsetMinDistance,
+    CoilSetMinDistance,
     CoilTorsion,
-    PlasmaCoilsetMinDistance,
+    PlasmaCoilSetMinDistance,
     QuadraticFlux,
     ToroidalFlux,
 )

desc/objectives/_coils.py

@@ -695,7 +695,7 @@ def compute(self, params, constants=None):
         return out
 
 
-class CoilsetMinDistance(_Objective):
+class CoilSetMinDistance(_Objective):
     """Target the minimum distance between coils in a coilset.
 
     Will yield one value per coil in the coilset, which is the minimum distance to
@@ -837,7 +837,7 @@ def body(k):
         return min_dist_per_coil
 
 
-class PlasmaCoilsetMinDistance(_Objective):
+class PlasmaCoilSetMinDistance(_Objective):
     """Target the minimum distance between the plasma and coilset.
 
     Will yield one value per coil in the coilset, which is the minimumm distance from
@@ -1125,8 +1125,8 @@ class QuadraticFlux(_Objective):
     eval_grid : Grid, optional
         Collocation grid containing the nodes on the plasma surface at which the
         magnetic field is being calculated and where to evaluate Bn errors.
-        Default grid is: LinearGrid(rho=np.array([1.0]), M=eq.M_grid, N=eq.N_grid,
-            NFP=int(eq.NFP), sym=False)
+        Default grid is: ``LinearGrid(rho=np.array([1.0]), M=eq.M_grid, N=eq.N_grid,
+        NFP=int(eq.NFP), sym=False)``
     field_grid : Grid, optional
         Grid used to discretize field (e.g. grid for the magnetic field source from
         coils). Default grid is determined by the specific MagneticField object, see

docs/api.rst

@@ -159,14 +159,21 @@ Objective Functions
     desc.objectives.BootstrapRedlConsistency
     desc.objectives.BoundaryError
     desc.objectives.BScaleLength
+    desc.objectives.CoilCurrentLength
+    desc.objectives.CoilCurvature
+    desc.objectives.CoilLength
+    desc.objectives.CoilSetMinDistance
+    desc.objectives.CoilTorsion
     desc.objectives.CurrentDensity
     desc.objectives.Elongation
     desc.objectives.Energy
+    desc.objectives.FixAnisotropy
     desc.objectives.FixAtomicNumber
     desc.objectives.FixAxisR
     desc.objectives.FixAxisZ
     desc.objectives.FixBoundaryR
     desc.objectives.FixBoundaryZ
+    desc.objectives.FixCoilCurrent
     desc.objectives.FixCurrent
     desc.objectives.FixElectronDensity
     desc.objectives.FixElectronTemperature
@@ -200,19 +207,23 @@ Objective Functions
     desc.objectives.ObjectiveFromUser
     desc.objectives.ObjectiveFunction
     desc.objectives.Omnigenity
+    desc.objectives.PlasmaCoilSetMinDistance
     desc.objectives.PlasmaVesselDistance
     desc.objectives.Pressure
     desc.objectives.PrincipalCurvature
+    desc.objectives.QuadraticFlux
     desc.objectives.QuasisymmetryBoozer
     desc.objectives.QuasisymmetryTwoTerm
     desc.objectives.QuasisymmetryTripleProduct
     desc.objectives.RadialForceBalance
     desc.objectives.RotationalTransform
     desc.objectives.Shear
     desc.objectives.ToroidalCurrent
+    desc.objectives.ToroidalFlux
     desc.objectives.VacuumBoundaryError
     desc.objectives.Volume
 
+
 Optimize
 ********
 

docs/api_objectives.rst

@@ -88,6 +88,24 @@ Free boundary / Single stage optimization
     desc.objectives.VacuumBoundaryError
 
 
+Coil Optimization
+-----------------
+.. autosummary::
+    :toctree: _api/objectives
+    :recursive:
+    :template: class.rst
+
+
+    desc.objectives.QuadraticFlux
+    desc.objectives.CoilLength
+    desc.objectives.CoilCurvature
+    desc.objectives.CoilTorsion
+    desc.objectives.CoilSetMinDistance
+    desc.objectives.PlasmaCoilSetMinDistance
+    desc.objectives.CoilCurrentLength
+    desc.objectives.ToroidalFlux
+
+
 Profiles
 --------
 .. autosummary::
@@ -121,11 +139,13 @@ Fixing degrees of freedom
     desc.objectives.FixElectronDensity
     desc.objectives.FixElectronTemperature
     desc.objectives.FixIonTemperature
+    desc.objectives.FixAnisotropy
     desc.objectives.FixModeR
     desc.objectives.FixModeZ
     desc.objectives.FixSumModesR
     desc.objectives.FixSumModesZ
     desc.objectives.FixThetaSFL
+    desc.objectives.FixCoilCurrent
     desc.objectives.FixParameters
 
 

docs/notebooks/zernike_eval.ipynb

@@ -357,20 +357,18 @@
     "            Zmn_p = \"\\\\frac{d\" + derv + \"\\\\tilde{Z}_{lm}(x)}{d x\" + derv + \"}\"\n",
     "        if type == \"absolute\":\n",
     "            c = np.max(abs(methods[i] - exact), axis=0)\n",
-    "            title = (\n",
-    "                f\"{algo}:\" + \"$\\\\max_{x \\\\in (0,1)} |\" + Zmn + \"-\" + Zmn_p + \"|$\"\n",
-    "            )\n",
+    "            title = f\"{algo}:\" + \"$\\\\max_{x \\\\in (0,1)} |\" + Zmn + \"-\" + Zmn_p + \"|$\"\n",
     "        else:\n",
     "            c = np.max(abs(methods[i] - exact), axis=0) / np.mean(abs(exact))\n",
-    "            derv = \"'\"*dx if dx >= 1 else \"\"\n",
+    "            derv = \"'\" * dx if dx >= 1 else \"\"\n",
     "            title = (\n",
     "                f\"{algo}:\"\n",
     "                + \"$\\\\max_{x \\\\in (0,1)} |\"\n",
     "                + Zmn\n",
     "                + \"-\"\n",
     "                + Zmn_p\n",
     "                + \"| / |\\\\bar{Z}\"\n",
-    "                + derv   \n",
+    "                + derv\n",
     "                + \"_{lm}|$\"\n",
     "            )\n",
     "        im = ax[i].scatter(\n",

tests/test_examples.py

@@ -35,7 +35,7 @@
     BoundaryError,
     CoilCurvature,
     CoilLength,
-    CoilsetMinDistance,
+    CoilSetMinDistance,
     CoilTorsion,
     CurrentDensity,
     FixBoundaryR,
@@ -56,7 +56,7 @@
     MeanCurvature,
     ObjectiveFunction,
     Omnigenity,
-    PlasmaCoilsetMinDistance,
+    PlasmaCoilSetMinDistance,
     PlasmaVesselDistance,
     PrincipalCurvature,
     QuadraticFlux,
@@ -1383,7 +1383,7 @@ def test(c, method):
 
 @pytest.mark.unit
 def test_coilset_geometry_optimization():
-    """Test optimizations with PlasmaCoilsetMinDistance and CoilsetMinDistance."""
+    """Test optimizations with PlasmaCoilSetMinDistance and CoilSetMinDistance."""
     R0 = 5  # major radius of plasma
     a = 1.2  # minor radius of plasma
     phi0 = np.pi / 12  # initial angle of coil
@@ -1420,7 +1420,7 @@ def test_coilset_geometry_optimization():
     # optimizing for target coil-plasma distance and maximum coil-coil distance
     objective = ObjectiveFunction(
         (
-            PlasmaCoilsetMinDistance(
+            PlasmaCoilSetMinDistance(
                 eq=eq,
                 coils=coils,
                 target=offset,
@@ -1430,7 +1430,7 @@ def test_coilset_geometry_optimization():
                 eq_fixed=True,
                 coils_fixed=False,
             ),
-            CoilsetMinDistance(
+            CoilSetMinDistance(
                 coils,
                 target=2 * np.pi * (R0 - offset) / coils.num_coils,
                 grid=coil_grid,
@@ -1462,7 +1462,7 @@ def test_coilset_geometry_optimization():
     # same optimization as above, but with a fixed surface instead of an equilibrium
     objective = ObjectiveFunction(
         (
-            PlasmaCoilsetMinDistance(
+            PlasmaCoilSetMinDistance(
                 eq=surf,
                 coils=coils,
                 target=offset,
@@ -1472,7 +1472,7 @@ def test_coilset_geometry_optimization():
                 eq_fixed=True,
                 coils_fixed=False,
             ),
-            CoilsetMinDistance(
+            CoilSetMinDistance(
                 coils,
                 target=2 * np.pi * (R0 - offset) / coils.num_coils,
                 grid=coil_grid,
@@ -1509,7 +1509,7 @@ def circle_constraint(params):
 
     objective = ObjectiveFunction(
         (
-            PlasmaCoilsetMinDistance(
+            PlasmaCoilSetMinDistance(
                 eq=surf,
                 coils=coils,
                 target=offset,

tests/test_objective_funs.py

@@ -42,7 +42,7 @@
     CoilCurrentLength,
     CoilCurvature,
     CoilLength,
-    CoilsetMinDistance,
+    CoilSetMinDistance,
     CoilTorsion,
     Elongation,
     Energy,
@@ -57,7 +57,7 @@
     ObjectiveFromUser,
     ObjectiveFunction,
     Omnigenity,
-    PlasmaCoilsetMinDistance,
+    PlasmaCoilSetMinDistance,
     PlasmaVesselDistance,
     Pressure,
     PrincipalCurvature,
@@ -868,7 +868,7 @@ def test_coil_min_distance(self):
         """Tests minimum distance between coils in a coilset."""
 
         def test(coils, mindist, grid=None, expect_intersect=False, tol=None):
-            obj = CoilsetMinDistance(coils, grid=grid)
+            obj = CoilSetMinDistance(coils, grid=grid)
             obj.build()
             f = obj.compute(params=coils.params_dict)
             assert f.size == coils.num_coils
@@ -938,7 +938,7 @@ def test(
             eq_fixed=False,
             coils_fixed=False,
         ):
-            obj = PlasmaCoilsetMinDistance(
+            obj = PlasmaCoilSetMinDistance(
                 eq=eq,
                 coils=coils,
                 plasma_grid=plasma_grid,
@@ -1943,11 +1943,11 @@ class TestComputeScalarResolution:
         CoilCurrentLength,
         CoilCurvature,
         CoilLength,
-        CoilsetMinDistance,
+        CoilSetMinDistance,
         CoilTorsion,
         GenericObjective,
         Omnigenity,
-        PlasmaCoilsetMinDistance,
+        PlasmaCoilSetMinDistance,
         PlasmaVesselDistance,
         QuadraticFlux,
         ToroidalFlux,
@@ -2236,7 +2236,7 @@ def test_compute_scalar_resolution_others(self, objective):
     @pytest.mark.regression
     @pytest.mark.parametrize(
         "objective",
-        [CoilLength, CoilTorsion, CoilCurvature, CoilCurrentLength, CoilsetMinDistance],
+        [CoilLength, CoilTorsion, CoilCurvature, CoilCurrentLength, CoilSetMinDistance],
     )
     def test_compute_scalar_resolution_coils(self, objective):
         """Coil objectives."""
@@ -2271,10 +2271,10 @@ class TestObjectiveNaNGrad:
         CoilLength,
         CoilCurrentLength,
         CoilCurvature,
-        CoilsetMinDistance,
+        CoilSetMinDistance,
         CoilTorsion,
         ForceBalanceAnisotropic,
-        PlasmaCoilsetMinDistance,
+        PlasmaCoilSetMinDistance,
         PlasmaVesselDistance,
         QuadraticFlux,
         ToroidalFlux,
@@ -2418,7 +2418,7 @@ def test_objective_no_nangrad(self, objective):
     @pytest.mark.unit
     @pytest.mark.parametrize(
         "objective",
-        [CoilLength, CoilTorsion, CoilCurvature, CoilCurrentLength, CoilsetMinDistance],
+        [CoilLength, CoilTorsion, CoilCurvature, CoilCurrentLength, CoilSetMinDistance],
     )
     def test_objective_no_nangrad_coils(self, objective):
         """Coil objectives."""