From b1e34eb66667a300bb8f8c90c1da2156d0ce0c45 Mon Sep 17 00:00:00 2001
From: Kian Orr <orrk931@gmail.com>
Date: Mon, 5 Feb 2024 19:22:52 -0500
Subject: [PATCH] add docstrings and grid option

---
 desc/objectives/_geometry.py | 74 +++++++++++++++++++++++++++++++++---
 1 file changed, 69 insertions(+), 5 deletions(-)

diff --git a/desc/objectives/_geometry.py b/desc/objectives/_geometry.py
index a1c7aae7fe..eaceb250ae 100644
--- a/desc/objectives/_geometry.py
+++ b/desc/objectives/_geometry.py
@@ -460,20 +460,60 @@ def compute(self, params, constants=None):
 
 
 class CoilLength(_Objective):
-    """Coil length."""
+    """Plasma volume.
+
+    Parameters
+    ----------
+    coil : FourierPlanarCoil or FourierXYZCoil
+        Coil for which the length will be found.
+    target : {float, ndarray}, optional
+        Target value(s) of the objective. Only used if bounds is None.
+        Must be broadcastable to Objective.dim_f.
+    bounds : tuple of {float, ndarray}, optional
+        Lower and upper bounds on the objective. Overrides target.
+        Both bounds must be broadcastable to to Objective.dim_f
+    weight : {float, ndarray}, optional
+        Weighting to apply to the Objective, relative to other Objectives.
+        Must be broadcastable to to Objective.dim_f
+    normalize : bool, optional
+        Whether to compute the error in physical units or non-dimensionalize.
+    normalize_target : bool, optional
+        Whether target and bounds should be normalized before comparing to computed
+        values. If `normalize` is `True` and the target is in physical units,
+        this should also be set to True.
+        be set to True.
+    loss_function : {None, 'mean', 'min', 'max'}, optional
+        Loss function to apply to the objective values once computed. This loss function
+        is called on the raw compute value, before any shifting, scaling, or
+        normalization. Note: Has no effect for this objective.
+    deriv_mode : {"auto", "fwd", "rev"}
+        Specify how to compute jacobian matrix, either forward mode or reverse mode AD.
+        "auto" selects forward or reverse mode based on the size of the input and output
+        of the objective. Has no effect on self.grad or self.hess which always use
+        reverse mode and forward over reverse mode respectively.
+    grid : Grid, optional
+        Collocation grid containing the nodes to evaluate at.
+    name : str, optional
+        Name of the objective function.
+
+    """
 
     def __init__(
         self,
         coil,
-        target=2 * np.pi,
+        target=None,
         bounds=None,
         weight=1,
         normalize=True,
         normalize_target=True,
         loss_function=None,
         deriv_mode="auto",
+        grid=None,
         name="coil-length",
     ):
+        if target is None and bounds is None:
+            target = 2 * np.pi
+        self._grid = grid
         super().__init__(
             things=coil,
             target=target,
@@ -487,17 +527,27 @@ def __init__(
         )
 
     def build(self, use_jit=True, verbose=1):
-        """Build objective function."""
+        """Build constant arrays.
+
+        Parameters
+        ----------
+        use_jit : bool, optional
+            Whether to just-in-time compile the objective and derivatives.
+        verbose : int, optional
+            Level of output.
+
+        """
         coil = self.things[0]
         self._dim_f = 1
         self._data_keys = ["length"]
+        if self._grid is None:
+            grid = LinearGrid(N=32)
 
         timer = Timer()
         if verbose > 0:
             print("Precomputing transforms")
         timer.start("Precomputing transforms")
 
-        grid = LinearGrid(N=32)
         profiles = get_profiles(self._data_keys, obj=coil, grid=grid)
         transforms = get_transforms(self._data_keys, obj=coil, grid=grid)
         self._constants = {
@@ -512,7 +562,21 @@ def build(self, use_jit=True, verbose=1):
         super().build(use_jit=use_jit, verbose=verbose)
 
     def compute(self, params, constants=None):
-        """Compute length of coil."""
+        """Compute length of coil.
+
+        Parameters
+        ----------
+        params : dict
+            Dictionary of the coil's degrees of freedom.
+        constants : dict
+            Dictionary of constant data, eg transforms, profiles etc. Defaults to
+            self._constants.
+
+        Returns
+        -------
+        f : float
+            Coil length.
+        """
         if constants is None:
             constants = self._constants