Cleanup type hints + spelling, source API links (#64)

* OptimizeResult import

* one more fix

* some spelling clean up

* logging level -> ERROR; spelling typos

* spelling typos

* one more

* logging level -> INFO; hyperlink to logging levels

* correct Callable type hint syntax

* hyperlink to source API

* Use 'Optional' type hint

CHANGES.md

@@ -30,7 +30,7 @@
 **Bug fixes**
 
 * Correct dependency name for jupyter-notebook
-* Move jupyter-notebook to base install dependecy
+* Move jupyter-notebook to base install dependency
 
 **New features**
 

docs/source/theory.rst

@@ -91,7 +91,7 @@ Consider, for example, a general case without a controller structure, in which :
 For a wave tank scale device, one might expect velocities of :math:`\mathcal{O}(1e-1)`, but the forces could be :math:`\mathcal{O}(1e3)`.
 For larger WECs, this discrepancy in the orders of magnitude may be even worse.
 Scaling mismatches in the decision variable :math:`x` and with the objective function :math:`J(x)` can lead to problems with convergence.
-To alleviate this issue, WecOptTool allows users to set scale factors for the components of :math:`x` as well as the objective function (see :meth:`wecopttool.WEC.solve`).
+To alleviate this issue, WecOptTool allows users to set scale factors for the components of :math:`x` as well as the objective function (see :meth:`wecopttool.core.WEC.solve`).
 Additionally, you may set :code:`import logging, logging.basicConfig(level=logging.INFO)` to output the mean values of `x` and the objective function during the solution process.
 
 Constraints
@@ -100,7 +100,7 @@ Constraints, such as maximum PTO force, maximum piston force, or maintaining ten
 This functionality is well-illustrated in :doc:`_examples/tutorial_1_wavebot`.
 An important practical factor when using this functionality is to make sure that the constraint is evaluated at a sufficient number of collocation points.
 It may be required to enforce constraints at more points than the dynamics (as defined by the frequency array).
-In WecOptTool's example PTO module, this is controlled by the :code:`nsubsteps` argument (see, e.g., :py:meth:`pto.PseudoSpectralPTO.force`).
+In WecOptTool's example PTO module, this is controlled by the :code:`nsubsteps` argument (see, e.g., :py:meth:`wecopttool.pto.PseudoSpectralPTO.force`).
 
 Buoyancy/gravity
 ^^^^^^^^^^^^^^^^

docs/source/tutorials.rst

@@ -5,7 +5,7 @@ The tutorials are written as Jupyter Notebooks which are available in the `GitHu
 The two tutorials use the `WaveBot`_ WEC, which is a single-body WEC developed at Sandia.
 The tutorials are meant to be sequential.
 The first tutorial solves only the inner optimization loop, and serves as an introduction to WecOptTool.
-The second tutorial builds on the first to solve a design opotimization problem, using both the inner and outer optimization loops, and is more reflective of the optimization problems WecOptTool is designed to solve.
+The second tutorial builds on the first to solve a design optimization problem, using both the inner and outer optimization loops, and is more reflective of the optimization problems WecOptTool is designed to solve.
 
 - :doc:`_examples/tutorial_1_wavebot`: Simple example of the *inner loop* using a single-body WEC moving in one degree of freedom in regular waves. The example finds the optimal control strategy for a fixed WEC design. See :cite:`Coe2020Initial` for further discussion of this example.
 - :doc:`_examples/tutorial_2_wavebot_optimization`: Simple example of a design optimization problem (*outer* and *inner* optimization loops). The example optimizes the WEC geometry (outer loop) while finding the optimal control strategy for each design considered (inner loop).

wecopttool/core.py

@@ -22,7 +22,7 @@
 from autograd import grad, jacobian
 import xarray as xr
 import capytaine as cpy
-from scipy.optimize import minimize
+from scipy.optimize import minimize, OptimizeResult
 from scipy.linalg import block_diag
 import matplotlib.pyplot as plt
 import matplotlib as mpl
@@ -53,8 +53,8 @@ class WEC:
 
     def __init__(self, fb: cpy.FloatingBody, mass: np.ndarray,
                  hydrostatic_stiffness: np.ndarray, f0: float, nfreq: int,
-                 dissipation: np.ndarray | None = None,
-                 stiffness: np.ndarray | None = None,
+                 dissipation: Optional[np.ndarray] = None,
+                 stiffness: Optional[np.ndarray] = None,
                  f_add: Optional[Mapping[str, Callable[[WEC, np.ndarray, np.ndarray], np.ndarray]]] = None,
                  constraints: list[dict] = [],
                  rho: float = _default_parameters['rho'],
@@ -68,15 +68,15 @@ def __init__(self, fb: cpy.FloatingBody, mass: np.ndarray,
         mass: np.ndarray
             Mass matrix shape of (``ndof`` x ``ndof``).
         hydrostatic_stiffness: np.ndarray
-            Hydrstatic stiffness matrix matrix of shape
+            Hydrostatic stiffness matrix matrix of shape
             (``ndof`` x ``ndof``).
         f0: float
             Initial frequency (in Hz) for frequency array.
             Frequency array given as [``f0``, 2 ``f0``, ..., ``nfreq f0``].
         nfreq: int
             Number of frequencies in frequency array. See ``f0``.
         dissipation: np.ndarray
-            Additional dissipiation for the impedance calculation in
+            Additional dissipation for the impedance calculation in
             ``capytaine.post_pro.impedance``. Shape:
             (``ndof`` x ``ndof`` x ``1``) or (``ndof`` x ``ndof`` x ``nfreq``).
         stiffness: np.ndarray
@@ -588,9 +588,9 @@ def natural_frequency(self):
 
     # methods: solve
     def _get_state_scale(self,
-                         scale_x_wec: list | None = None,
+                         scale_x_wec: Optional[list] = None,
                          scale_x_opt: npt.ArrayLike | float = 1.0,
-                         nstate_opt: int | None = None):
+                         nstate_opt: Optional[int] = None):
         """Create a combined scaling array for the state vector. """
         # scale for x_wec
         if scale_x_wec == None:
@@ -612,16 +612,16 @@ def solve(self,
               waves: xr.Dataset,
               obj_fun: Callable[[WEC, np.ndarray, np.ndarray], float],
               nstate_opt: int,
-              x_wec_0: np.ndarray | None = None,
-              x_opt_0: np.ndarray | None = None,
-              scale_x_wec: list | None = None,
+              x_wec_0: Optional[np.ndarray] = None,
+              x_opt_0: Optional[np.ndarray] = None,
+              scale_x_wec: Optional[list] = None,
               scale_x_opt: npt.ArrayLike | float = 1.0,
               scale_obj: float = 1.0,
               optim_options: dict[str, Any] = {},
               use_grad: bool = True,
               maximize: bool = False,
               ) -> tuple[xr.Dataset, xr.Dataset, np.ndarray, np.ndarray, float,
-                         optimize.optimize.OptimizeResult]:
+                         OptimizeResult]:
         """Solve the WEC co-design problem.
 
         Parameters
@@ -898,11 +898,11 @@ def real_to_complex_amplitudes(fd: np.ndarray, first_row_is_mean: bool = True
     return np.concatenate((mean, fd[0::2, :] - 1j*fd[1::2, :]), axis=0)
 
 
-def fd_to_td(fd: np.ndarray, n: int | None = None) -> np.ndarray:
+def fd_to_td(fd: np.ndarray, n: Optional[int] = None) -> np.ndarray:
     return np.fft.irfft(fd/2, n=n, axis=0, norm='forward')
 
 
-def td_to_fd(td: np.ndarray, n: int | None = None) -> np.ndarray:
+def td_to_fd(td: np.ndarray, n: Optional[int] = None) -> np.ndarray:
     return np.fft.rfft(td*2, n=n, axis=0, norm='forward')
 
 
@@ -928,7 +928,7 @@ def scale_dofs(scale_list: list[float], ncomponents: int) -> np.ndarray:
 
 
 def complex_xarray_from_netcdf(fpath: str | Path) -> xr.Dataset:
-    """Read a NetCDF file with commplex entries as an xarray dataSet.
+    """Read a NetCDF file with complex entries as an xarray dataSet.
     """
     with xr.open_dataset(fpath) as ds:
         ds.load()
@@ -1130,7 +1130,7 @@ def natural_frequency(impedance: npt.ArrayLike, freq: npt.ArrayLike
 def plot_impedance(impedance: npt.ArrayLike, freq: npt.ArrayLike,
                    style: str = 'Bode',
                    option: str = 'diagonal', show: bool = False,
-                   dof_names: list[str] | None = None
+                   dof_names: Optional[list[str]] = None
                    ) -> tuple[mpl.figure.Figure, np.ndarray]:
     """Plot the impedance matrix.
 
@@ -1270,7 +1270,7 @@ def delaxes(axs, idof, jdof, ndof):
 
 
 def post_process_continuous_time(results: xr.DataArray
-                                 ) -> Callable[float, float]:
+                                 ) -> Callable[[float], float]:
     """Create a continuous function from the results in an xarray
     DataArray.