add docstrings to adjoint solver

python/adjoint/objective.py

@@ -147,7 +147,7 @@ def _create_time_profile(self, fwidth_frac=0.1, adj_cutoff=5):
 
 
 class EigenmodeCoefficient(ObjectiveQuantity):
-    """A frequency-dependent eigenmode coefficient.
+    """A differentiable frequency-dependent eigenmode coefficient.
     Attributes:
         volume: the volume over which the eigenmode coefficient is calculated.
         mode: the eigenmode number.
@@ -158,6 +158,10 @@ class EigenmodeCoefficient(ObjectiveQuantity):
         kpoint_func_overlap_idx: the index of the mode coefficient to return when
           specifying `kpoint_func`. When specified, this overrides the effect of
           `forward` and should have a value of either 0 or 1.
+        decimation_factor: an integer so that the DFT fields are updated at every
+          decimation_factor timesteps. The default is 0, at which the value is
+          automatically determined from the Nyquist rate of the bandwidth-limited
+          sources and the DFT monitor. It can be turned off by setting it to 1.
         subtracted_dft_fields: the DFT fields obtained using `get_flux_data` from
           a previous normalization run. This is subtracted from the DFT fields
           of this mode monitor in order to improve the accuracy of the
@@ -257,6 +261,11 @@ def place_adjoint_source(self, dJ):
         return [source]
 
     def __call__(self):
+        """The values of eigenmode coefficient at each frequency
+
+        Returns:
+            1D array of eigenmode coefficients corresponding to each of self.frequencies
+        """
         if self.kpoint_func:
             kpoint_func = self.kpoint_func
             overlap_idx = self.kpoint_func_overlap_idx
@@ -284,11 +293,30 @@ def __call__(self):
 
 
 class FourierFields(ObjectiveQuantity):
+    """A differentiable frequency-dependent Fourier Fields (dft_fields)
+    Attributes:
+        volume: the volume over which the Fourier Fields are calculated. Due to an unsolved bug,
+          the size must not be zero in at least one direction.
+        component: field component (e.g. mp.Ex, mp.Hz, etc.)
+        yee_grid: if True, the Fourier fields evaluated at corresponding Yee grid point
+          are returned; otherwise, interpolated fields at the center of each voxel
+          are returned
+        decimation_factor: an integer so that the DFT fields are updated at every
+          decimation_factor timesteps. The default is 0, at which the value is
+          automatically determined from the Nyquist rate of the bandwidth-limited
+          sources and the DFT monitor. It can be turned off by setting it to 1.
+        subtracted_dft_fields: the DFT fields obtained using `get_flux_data` from
+          a previous normalization run. This is subtracted from the DFT fields
+          of this mode monitor in order to improve the accuracy of the
+          reflectance measurement (i.e., the $S_{11}$ scattering parameter).
+          Default is None.
+    """
+
     def __init__(
         self,
         sim: mp.Simulation,
         volume: mp.Volume,
-        component: List[int],
+        component: int,
         yee_grid: Optional[bool] = False,
         decimation_factor: Optional[int] = 0,
         subtracted_dft_fields: Optional[FluxData] = None,
@@ -375,6 +403,13 @@ def place_adjoint_source(self, dJ):
         return sources
 
     def __call__(self):
+        """The values of Fourier Fields at each frequency
+
+        Returns:
+            array of Fourier Fields with dimension k+1 where k is the dimension of self.volume
+            The first axis corresponds to the index of frequency, and the rest k axis are for
+            the spatial indices of points in the monitor
+        """
         self._eval = np.array(
             [
                 self.sim.get_dft_array(self._monitor, self.component, i)
@@ -385,6 +420,24 @@ def __call__(self):
 
 
 class Near2FarFields(ObjectiveQuantity):
+    """A differentiable near2far field transformation
+    Attributes:
+        Near2FarRegions: List of mp.Near2FarRegion over which the near fields are collected
+        far_pts: list of far points at which fields are computed
+        nperiods: If nperiods > 1, sum of 2*nperiods+1 Bloch-periodic copies of near fields
+          is computed to approximate the lattice sum with Bloch periodic condition.
+          Default is 1 (no sum).
+        decimation_factor: an integer so that the DFT fields are updated at every
+          decimation_factor timesteps. The default is 0, at which the value is
+          automatically determined from the Nyquist rate of the bandwidth-limited
+          sources and the DFT monitor. It can be turned off by setting it to 1.
+        norm_near_fields: the DFT fields obtained using `get_near2far_data` from
+          a previous normalization run. This is subtracted from the DFT fields
+          of this near2far monitor in order to improve the accuracy of the
+          reflectance measurement (i.e., the $S_{11}$ scattering parameter).
+          Default is None.
+    """
+
     def __init__(
         self,
         sim: mp.Simulation,
@@ -461,13 +514,29 @@ def place_adjoint_source(self, dJ):
         return sources
 
     def __call__(self):
+        """The values of far fields at each points at each frequency
+
+        Returns:
+            3D array of far fields. The first axis is the index of far field points in self.far_pts;
+            the second axis is the index of frequency; and the third is the index of component in
+            [mp.Ex(mp.Er), mp.Ey(mp.Ep), mp.Ez, mp.Hx(mp.Hr), mp.Hy(mp.Hp), mp.Hz]
+        """
         self._eval = np.array(
             [self.sim.get_farfield(self._monitor, far_pt) for far_pt in self.far_pts]
         ).reshape((self._nfar_pts, self.num_freq, 6))
         return self._eval
 
 
 class LDOS(ObjectiveQuantity):
+    """A differentiable LDOS
+
+    Attributes:
+    decimation_factor: an integer so that the DFT fields are updated at every
+      decimation_factor timesteps. The default is 0, at which the value is
+      automatically determined from the Nyquist rate of the bandwidth-limited
+      sources and the DFT monitor. It can be turned off by setting it to 1.
+    """
+
     def __init__(
         self, sim: mp.Simulation, decimation_factor: Optional[int] = 0, **kwargs
     ):
@@ -530,6 +599,11 @@ def place_adjoint_source(self, dJ):
         return sources
 
     def __call__(self):
+        """The values of ldos_Jdata at each frequency
+
+        Returns:
+            1D array of LDOS corresponding to each of self.frequencies
+        """
         self._eval = self.sim.ldos_data
         self.ldos_scale = self.sim.ldos_scale
         self.ldos_Jdata = self.sim.ldos_Jdata

python/adjoint/optimization_problem.py

@@ -21,6 +21,27 @@ class OptimizationProblem:
     calculation) and optionally its gradient (adjoint calculation).
     This is done by the __call__ method.
 
+    Attributes:
+        simulation: The corresponding Meep `Simulation` object that describes
+          the problem (e.g. sources, geometry)
+        objective_functions: list of objective functions on objective_arguments
+        objective_arguments: list of differential objective quantities as arguments
+          of objective functions
+        design_regions: list of design regions to be optimized
+        frequencies: list of frequencies in the problem
+        fcen: center frequency
+        df: range of frequencies
+        nf: number of frequencies
+        decay_by: simulation stops once all the field components and frequencies of
+          every DFT object have decayed by at least this amount. Default is 1e-11.
+        decimation_factor: an integer so that the DFT fields are updated at every
+          decimation_factor timesteps. The default is 0, at which the value is
+          automatically determined from the Nyquist rate of the bandwidth-limited
+          sources and the DFT monitor. It can be turned off by setting it to 1
+        minimum_run_time: minimum runtime for each simulation. Default is 0
+        maximum_run_time: maximum runtime for each simulation
+        finite_difference_step: step size for calculation of finite difference gradients
+        step_funcs: list of step functions to be called at each timestep
     """
 
     def __init__(
@@ -40,13 +61,7 @@ def __init__(
         finite_difference_step: Optional[float] = utils.FD_DEFAULT,
         step_funcs: list = None,
     ):
-        """
-        + **`simulation` [ `Simulation` ]** — The corresponding Meep
-        `Simulation` object that describes the problem (e.g. sources,
-        geometry)
 
-        + **`objective_functions` [ `list of ` ]** —
-        """
         self.step_funcs = step_funcs if step_funcs is not None else []
         self.sim = simulation
 
@@ -123,7 +138,29 @@ def __call__(
         need_gradient: bool = True,
         beta: float = None,
     ) -> Tuple[List[np.ndarray], List[List[np.ndarray]]]:
-        """Evaluate value and/or gradient of objective function."""
+        """Evaluate value and/or gradient of objective function.
+
+        Args:
+            rho_vector: lists of design variables. Each list represents design variables
+              of one design region. The design is updated to the specified values; functions
+              and gradients will then be evaluated at this configuration of design variables.
+            need_value: whether forward evaluations are needed. Default is True.
+            need_gradient: whether adjoint and gradients evaluatiosn are needed. Default is True.
+            beta: the strength of projection of rho_vector. Default to None.
+
+        Returns:
+            A tuple (f0, gradient) where:
+            f0 is the list of objective functions values when design variables
+              are set to rho_vector
+            gradient is the lists of gradients of objective functions with respect to
+              the design variables when they are set to rho_vector. There is a list of
+              gradients for each design region and for each objective functions. Generally,
+              the first axis is the index of objective functions and the second is the index
+              of design region; and each gradient is a 2d array where the first axis is for
+              the design variables, and the second is the index of frequency. Empty dimensions
+              are squeezed.
+
+        """
         if rho_vector:
             self.update_design(rho_vector=rho_vector, beta=beta)
 
@@ -320,7 +357,7 @@ def calculate_gradient(self):
         elif len(self.gradient[0]) == 1:
             self.gradient = [
                 g[0] for g in self.gradient
-            ]  # multiple objective functions bu one design region
+            ]  # multiple objective functions but one design region
         # Return optimizer's state to initialization
         self.current_state = "INIT"