Merge pull request #241 from hiddenSymmetries/ml/docs_20220625

Improvements to documentation

Author: mbkumar

docs/source/example_coils.rst

@@ -41,8 +41,7 @@ imports of the classes and functions we will need::
 
   import numpy as np
   from simsopt.util import MpiPartition
-  from simsopt.mhd import Vmec
-  from simsopt.mhd import QuasisymmetryRatioResidual
+  from simsopt.mhd import Vmec, QuasisymmetryRatioResidual
   from simsopt.objectives import LeastSquaresProblem
   from simsopt.solve import least_squares_mpi_solve
 
@@ -235,8 +234,7 @@ As usual, we begin with the necessary imports::
 
   import numpy as np
   from simsopt.util import MpiPartition
-  from simsopt.mhd import Vmec
-  from simsopt.mhd import QuasisymmetryRatioResidual
+  from simsopt.mhd import Vmec, QuasisymmetryRatioResidual
   from simsopt.objectives import LeastSquaresProblem
   from simsopt.solve import least_squares_mpi_solve
 
@@ -274,7 +272,7 @@ axisymmetric::
 
 It can be seen here that we are seeking a configuration with aspect
 ratio 6, and average iota of 0.42, slightly above the resonance at 2 /
-5 = 0.4. The function :func:`simsopt.mhd.vmec.Vmec.mean_iota()` used
+5 = 0.4. The function :func:`simsopt.mhd.Vmec.mean_iota()` used
 here returns :math:`\int_0^1 \iota\, ds` where :math:`s` is the
 toroidal flux normalized by its value at the VMEC boundary.
 
@@ -336,7 +334,7 @@ Bmn objective
 
 Here we show an alternative method of quasisymmetry optimization using
 a different objective function,
-:obj:`simsopt.mhd.boozer.Quasisymmetry`, based on the
+:obj:`simsopt.mhd.Quasisymmetry`, based on the
 symmetry-breaking Fourier mode aplitudes :math:`B_{m,n}` in Boozer
 coordinates.  This example can also be found in the
 ``examples/2_Intermediate`` directory as
@@ -345,8 +343,7 @@ coordinates.  This example can also be found in the
 In this case, the imports needed are::
 
   from simsopt.util import MpiPartition
-  from simsopt.mhd import Vmec
-  from simsopt.mhd import Boozer, Quasisymmetry
+  from simsopt.mhd import Vmec, Boozer, Quasisymmetry
   from simsopt.objectives import LeastSquaresProblem
   from simsopt.solve import least_squares_mpi_solve
 

docs/source/example_quasisymmetry.rst

@@ -60,8 +60,8 @@ For simplicity, MPI parallelization will not be used for now.
 To start, we must import several classes::
 
   from simsopt.mhd import Spec
-  from simsopt.objectives.least_squares import LeastSquaresProblem
-  from simsopt.solve.serial import least_squares_serial_solve
+  from simsopt.objectives import LeastSquaresProblem
+  from simsopt.solve import least_squares_serial_solve
 
 Then we create the equilibrium object, starting from an input file::
 
@@ -141,15 +141,15 @@ computation, or both at the same time.  To introduce MPI we first
 initialize an :obj:`simsopt.util.MpiPartition` object and choose
 the number of worker groups.  The instance is then passed as an
 argument to the Vmec object and to the
-:meth:`simsopt.solver.mpi_solve.least_squares_mpi_solve` function.
+:meth:`simsopt.solve.least_squares_mpi_solve` function.
 For more details about MPI, see :doc:`mpi`.
 
 The complete example is then as follows::
 
-  from simsopt.util.mpi import MpiPartition
+  from simsopt.util import MpiPartition
   from simsopt.mhd import Vmec
   from simsopt.objectives import LeastSquaresProblem
-  from simsopt.solve.mpi import least_squares_mpi_solve
+  from simsopt.solve import least_squares_mpi_solve
 
   # In the next line, we can adjust how many groups the pool of MPI
   # processes is split into.

docs/source/example_vmec_only.rst

@@ -194,7 +194,7 @@ operator creates the latter.)
 
 Example::
 
-   from simsopt.field.magneticfieldclasses import ToroidalField, CircularCoil
+   from simsopt.field import ToroidalField, CircularCoil
    
    field1 = CircularCoil(I=1.e7, r0=1.)
    field2 = ToroidalField(R0=1., B0=1.)

docs/source/fields.rst

@@ -53,15 +53,15 @@ the derivative of quantities such as curvature (via
 ``Curve.dkappa_by_dcoeff()``) or torsion (via
 ``Curve.dtorsion_by_dcoeff()``).
 
-A number of quantities are implemented in
-:obj:`simsopt.geo.curveobjectives` and are computed on a
+A number of objective functions are available in
+:obj:`simsopt.geo` and are computed on a
 :obj:`simsopt.geo.Curve`:
 
-- ``CurveLength``: computes the length of the ``Curve``.
-- ``LpCurveCurvature``: computes a penalty based on the :math:`L_p` norm of the curvature on a curve.
-- ``LpCurveTorsion``: computes a penalty based on the :math:`L_p` norm of the torsion on a curve.
-- ``CurveCurveDistance``: computes a penalty term on the minimum distance between a set of curves.
-- ``CurveSurfaceDistance``: computes a penalty term on the minimum distance between a set of curves and a surface.
+- :obj:`~simsopt.geo.CurveLength`: computes the length of the ``Curve``.
+- :obj:`~simsopt.geo.LpCurveCurvature`: computes a penalty based on the :math:`L_p` norm of the curvature on a curve.
+- :obj:`~simsopt.geo.LpCurveTorsion`: computes a penalty based on the :math:`L_p` norm of the torsion on a curve.
+- :obj:`~simsopt.geo.CurveCurveDistance`: computes a penalty term on the minimum distance between a set of curves.
+- :obj:`~simsopt.geo.CurveSurfaceDistance`: computes a penalty term on the minimum distance between a set of curves and a surface.
 
 The value of the quantity and its derivative with respect to the curve
 dofs can be obtained by calling e.g., ``CurveLength.J()`` and
@@ -152,10 +152,10 @@ the :obj:`~simsopt.geo.Curve` class:
 - ``Surface.second_fund_form()``: returns a ``(n_phi, n_theta, 3)`` array containing :math:`[\hat{\textbf{n}}(\phi_i, \theta_j) \cdot \partial^2_{\phi,\phi} \Gamma(\phi_i, \theta_j), \hat{\textbf{n}}(\phi_i, \theta_j) \cdot \partial^2_{\phi,\theta} \Gamma(\phi_i, \theta_j), \hat{\textbf{n}}(\phi_i, \theta_j) \cdot \partial^2_{\theta,\theta} \Gamma(\phi_i, \theta_j)]` for :math:`i\in\{1, \ldots, n_\phi\}, j\in\{1, \ldots, n_\theta\}` where :math:`\hat{\textbf{n}}` is the unit normal.
 - ``Surface.surface_curvatures()``: returns a ``(n_phi, n_theta, 4)`` array containing :math:`[H(\phi_i, \theta_j),K(\phi_i, \theta_j),\kappa_1(\phi_i, \theta_j),\kappa_2(\phi_i, \theta_j)]` for :math:`i\in\{1, \ldots, n_\phi\}, j\in\{1, \ldots, n_\theta\}` where :math:`H` is the mean curvature, :math:`K` is the Gaussian curvature, and :math:`\kappa_{1,2}` are the principal curvatures with :math:`\kappa_1>\kappa_2`.
 
-A number of quantities are implemented in :obj:`simsopt.geo.surfaceobjectives` and are computed on a :obj:`simsopt.geo.Surface`:
+A number of objective functions related to surfaces are available in :obj:`simsopt.geo`:
 
-- ``ToroidalFlux``: computes the flux through a toroidal cross section of a ``Surface``.
-- ``PrincipalCurvature``: computes a metric which penalizes large values of the principal curvatures of a given ``Surface``.
+- :obj:`~simsopt.geo.ToroidalFlux`: computes the flux through a toroidal cross section of a ``Surface``.
+- :obj:`~simsopt.geo.PrincipalCurvature`: computes a metric which penalizes large values of the principal curvatures of a given ``Surface``.
 
 The value of the quantity and its derivative with respect to the surface dofs can be obtained by calling e.g., ``ToroidalFlux.J()`` and ``ToroidalFlux.dJ_dsurfacecoefficients()``.
 
@@ -185,12 +185,12 @@ plotting engine by passing the ``engine`` keyword argument, e.g. if
 can use the ``close`` argument to control whether segments are drawn
 between the last quadrature point and the first. For these and other
 options, see the API documentation for
-:func:`simsopt.geo.curve.Curve.plot()` and
-:func:`simsopt.geo.surface.Surface.plot()`.
+:func:`simsopt.geo.Curve.plot()` and
+:func:`simsopt.geo.Surface.plot()`.
 
 If you have multiple curve and/or surface objects, a convenient way to
 plot them together on the same axes is the function
-:func:`simsopt.geo.plotting.plot()`, which accepts a list of objects as
+:func:`simsopt.geo.plot()`, which accepts a list of objects as
 its argument. Any keywords passed to this function are passed to the
 ``.plot()`` methods of the individual objects, so you may wish to pass
 keywords such as ``engine`` or ``close``.  Alternatively, you can also
@@ -201,6 +201,6 @@ It is also possible to export curve and surface objects in VTK format,
 so they can be viewed in Paraview.  This functionality requires the
 python package ``pyevtk``, which can be installed via ``pip install
 pyevtk``. A list of curve objects can be exported using the function
-:func:`simsopt.geo.curve.curves_to_vtk()`. To export a VTK file for a
+:func:`simsopt.geo.curves_to_vtk()`. To export a VTK file for a
 surface, call the ``.to_vtk(filename)`` function of the object.  See
-:func:`simsopt.geo.surface.Surface.to_vtk()` for more details.
+:func:`simsopt.geo.Surface.to_vtk()` for more details.

docs/source/geo.rst

@@ -87,15 +87,10 @@ optimization.  Others include `STELLOPT
 
 .. toctree::
    :maxdepth: 3
-   :caption: API
+   :caption: API reference
 
-   simsopt <simsopt_user>
-
-.. toctree::
-   :maxdepth: 3
-   :caption: Developer's API
-
-   simsopt
+   Public functions and classes <simsopt_user>
+   Full listing (for developers) <simsopt>
 
 Indices and tables
 ==================

docs/source/index.rst

@@ -25,7 +25,7 @@ algorithms.
 
 Users can create their own optimizable objects in two ways. One method
 is to create a standard python function, and apply the
-:obj:`simsopt.make_optimizable()` function to it, as explained
+:meth:`simsopt.make_optimizable()` function to it, as explained
 below. Or, you can directly subclass
 :obj:`simsopt._core.Optimizable`.
 
@@ -533,7 +533,7 @@ Specifying least-squares objective functions
 
 A common use case is to minimize a nonlinear least-squares objective
 function, which consists of a sum of several terms. In this case the
-:obj:`simsopt.objectives.least_squares.LeastSquaresProblem`
+:obj:`simsopt.objectives.LeastSquaresProblem`
 class can be used.  Suppose we want to solve a least-squares
 optimization problem in which an
 :obj:`~simsopt._core.Optimizable` object ``obj`` has
@@ -562,18 +562,18 @@ The corresponding objective funtion is then ``weight1 *
 scalar functions and by 1D numpy array-valued functions.  Note that
 the function handles that are specified should be members of an
 :obj:`~simsopt._core.Optimizable` object.  As
-:obj:`~simsopt.objectives.least_squares.LeastSquaresProblem` is
+:obj:`~simsopt.objectives.LeastSquaresProblem` is
 a subclass of :obj:`~simsopt._core.Optimizable`, the
 free dofs of all the objects that go into the objective function are
 available in the global state vector ``prob.x``. The overall scalar
 objective function is available from
-:func:`simsopt.objectives.least_squares.LeastSquaresProblem.objective`.
+:func:`simsopt.objectives.LeastSquaresProblem.objective`.
 The vector of residuals before scaling by the ``weight`` factors
 ``obj.func() - goal`` is available from
-:func:`simsopt.objectives.least_squares.LeastSquaresProblem.unweighted_residuals`.
+:func:`simsopt.objectives.LeastSquaresProblem.unweighted_residuals`.
 The vector of residuals after scaling by the ``weight`` factors,
 ``sqrt(weight) * (obj.func() - goal)``, is available from
-:func:`simsopt.objectives.least_squares.LeastSquaresProblem.residuals`.
+:func:`simsopt.objectives.LeastSquaresProblem.residuals`.
 
 Least-squares problems can also be defined in an alternative way::
   

docs/source/optimizable.rst

@@ -25,9 +25,9 @@ Simsopt does not use input data files to define optimization problems,
 in contrast to ``STELLOPT``. Rather, problems are specified using a
 python driver script, in which objects are defined and
 configured. However, objects related to specific physics codes may use
-their own input files. In particular, a :obj:`simsopt.mhd.vmec.Vmec` object
+their own input files. In particular, a :obj:`simsopt.mhd.Vmec` object
 can be initialized using a standard VMEC ``input.*`` input file, and a
-:obj:`simsopt.mhd.spec.Spec` object can be initialized using a standard
+:obj:`simsopt.mhd.Spec` object can be initialized using a standard
 SPEC ``*.sp`` input file.
 
 
@@ -72,18 +72,18 @@ Some typical objects are a MHD equilibrium represented by the VMEC or
 SPEC code, or some electromagnetic coils. To define objective
 functions, a variety of additional objects can be defined that depend
 on the MHD equilibrium or coils, such as a
-:obj:`simsopt.mhd.boozer.Boozer` object for Boozer-coordinate
-transformation, a :obj:`simsopt.mhd.spec.Residue` object to represent
+:obj:`simsopt.mhd.Boozer` object for Boozer-coordinate
+transformation, a :obj:`simsopt.mhd.Residue` object to represent
 Greene's residue of a magnetic island, or a
-:obj:`simsopt.geo.objectives.LpCurveCurvature` penalty on coil
+:obj:`simsopt.geo.LpCurveCurvature` penalty on coil
 curvature.
 
 More details about setting degrees of freedom and defining
 objective functions can be found on the :doc:`optimizable` page.
 
 For the solution step, two functions are provided presently,
-:meth:`simsopt.solve.serial.least_squares_serial_solve` and
-:meth:`simsopt.solve.mpi.least_squares_mpi_solve`.  The first
+:meth:`simsopt.solve.least_squares_serial_solve` and
+:meth:`simsopt.solve.least_squares_mpi_solve`.  The first
 is simpler, while the second allows MPI-parallelized finite differences
 to be used in the optimization.
 

docs/source/overview.rst

@@ -18,7 +18,7 @@ Particle motion in cylindrical coordinates
 ------------------------------------------
 
 The main function to use in this case is
-:obj:`simsopt.field.tracing.trace_particles` (click the link for more
+:obj:`simsopt.field.trace_particles` (click the link for more
 information on the input and output parameters) and it is able to use
 two different sets of equations depending on the input parameter
 ``mode``: