Update API docs

README.rst

@@ -9,61 +9,84 @@ Stellarator Optimization Package
 
 |Docs| |UnitTests| |RegressionTests| |Codecov|
 
-DESC solves for and optimizes 3D MHD equilibria using pseudo-spectral numerical methods and automatic differentiation.
+DESC solves for and optimizes 3D MHD equilibria using pseudo-spectral numerical methods
+and automatic differentiation.
+
+The theoretical approach and implementation details used by DESC are presented in the
+following papers and documented at Theory_. Please cite our work if you use DESC!
+
+- Dudt, D. & Kolemen, E. (2020). DESC: A Stellarator Equilibrium Solver.
+  [`Physics of Plasmas <https://doi.org/10.1063/5.0020743>`__]
+  [`pdf <https://github.com/PlasmaControl/DESC/blob/master/publications/dudt2020/dudt2020desc.pdf>`__]
+- Panici, D. et al (2023). The DESC Stellarator Code Suite Part I: Quick and accurate equilibria computations.
+  [`Journal of Plasma Physics <https://doi.org/10.1017/S0022377823000272>`__]
+  [`pdf <https://github.com/PlasmaControl/DESC/blob/master/publications/panici2022/Panici_DESC_Stellarator_suite_part_I_quick_accurate_equilibria.pdf>`__]
+- Conlin, R. et al. (2023). The DESC Stellarator Code Suite Part II: Perturbation and continuation methods.
+  [`Journal of Plasma Physics <https://doi.org/10.1017/S0022377823000399>`__]
+  [`pdf <https://github.com/PlasmaControl/DESC/blob/master/publications/conlin2022/conlin2022perturbations.pdf>`__]
+- Dudt, D. et al. (2023). The DESC Stellarator Code Suite Part III: Quasi-symmetry optimization.
+  [`Journal of Plasma Physics <https://doi.org/10.1017/S0022377823000235>`__]
+  [`pdf <https://github.com/PlasmaControl/DESC/blob/master/publications/dudt2022/dudt2022optimization.pdf>`__]
 
-The theoretical approach and implementation details used by DESC are presented in these papers [1]_ [2]_ [3]_ [4]_ and documented at Theory_.
-Please cite our work if you use DESC!
-
-.. [1] Dudt, D. & Kolemen, E. (2020). DESC: A Stellarator Equilibrium Solver. [`Physics of Plasmas <https://doi.org/10.1063/5.0020743>`__]    [`pdf <https://github.com/PlasmaControl/DESC/blob/master/publications/dudt2020/dudt2020desc.pdf>`__]
-.. [2] Panici, D. et al (2023). The DESC Stellarator Code Suite Part I: Quick and accurate equilibria computations. [`JPP <https://doi.org/10.1017/S0022377823000272>`__]    [`pdf <https://github.com/PlasmaControl/DESC/blob/master/publications/panici2022/Panici_DESC_Stellarator_suite_part_I_quick_accurate_equilibria.pdf>`__]
-.. [3] Conlin, R. et al. (2023). The DESC Stellarator Code Suite Part II: Perturbation and continuation methods. [`JPP <https://doi.org/10.1017/S0022377823000399>`__]    [`pdf <https://github.com/PlasmaControl/DESC/blob/master/publications/conlin2022/conlin2022perturbations.pdf>`__]
-.. [4] Dudt, D. et al. (2023). The DESC Stellarator Code Suite Part III: Quasi-symmetry optimization. [`JPP <https://doi.org/10.1017/S0022377823000235>`__]    [`pdf <https://github.com/PlasmaControl/DESC/blob/master/publications/dudt2022/dudt2022optimization.pdf>`__]
 .. _Theory: https://desc-docs.readthedocs.io/en/latest/theory_general.html
 
 Quick Start
 ===========
 
-.. role:: console(code)
-   :language: console
-
-The easiest way to install DESC is from pypi: :console:`pip install desc-opt`
+The easiest way to install DESC is from PyPI: ``pip install desc-opt``
 
 For more detailed instructions on installing DESC and its dependencies, see Installation_.
-The code is run using the syntax :console:`desc <path/to/inputfile>` and the full list of command line options are given in `Command Line Interface`_. (Note that you may have to prepend the command with :console:`python -m`)
 
-DESC can be ran in two ways:
+The best place to start learning about DESC is our tutorials:
 
-The first is through an input file specifying the equilibrium and solver options, this way can also can also accept VMEC input files.
+- `Basic fixed boundary equilibrium`_: running from a VMEC input, creating an equilibrium from scratch
+- `Advanced equilibrium`_: continuation and perturbation methods.
+- `Free boundary equilibrium`_: vacuum and or finite beta with external field.
+- `Using DESC outputs`_: analysis, plotting, saving to VMEC format.
+- `Basic optimization`_: specifying objectives, fixing degrees of freedom.
+- `Advanced optimization`_: advanced constraints, precise quasi-symmetry, constrained optimization.
+- `Near axis constraints`_: loading solutions from QSC/QIC and fixing near axis expansion.
 
-The second is through a python script, where the equilibrium and solver options are specified programmatically, this method offers much more flexibility over what types of equilibrium solution, optimization and analysis can be performed.
-See the tutorial `Script Interface`_ for more detailed information.
+For details on the various objectives, constraints, optimizable objects and more, see
+the full `api documentation`_.
 
-Refer to `Inputs`_ for documentation on how to format the input file.
-The equilibrium solution is output in a HDF5 binary file, whose format is detailed in `Outputs`_.
+If all you need is an equilibrium solution, the simplest method is through the command
+line by giving an input file specifying the equilibrium and solver options, this
+way can also can also accept VMEC input files.
 
-As an example usage of the input file method, to use DESC to solve for the equilibrium of the high-beta, D-shaped plasma described with the DSHAPE input file, the command from the :console:`DESC` directory is
-:console:`desc -p desc/examples/DSHAPE`, where the :console:`-p` flag tells DESC to plot the results once it finishes.
+The code is run using the syntax ``desc <path/to/inputfile>`` and the full list
+of command line options are given in `Command Line Interface`_. (Note that you may have
+to prepend the command with ``python -m``)
 
-An example of the script usage to solve and optimize an equilibrium, refer to the python script `desc/examples/precise_QA.py`, which can be run from the :console:`DESC` directory from the command line with :console:`python3 desc/examples/precise_QA.py`
+Refer to `Inputs`_ for documentation on how to format the input file.
+
+The equilibrium solution is output in a HDF5 binary file, whose format is detailed in `Outputs`_.
 
 .. _Installation: https://desc-docs.readthedocs.io/en/latest/installation.html
 .. _Command Line Interface: https://desc-docs.readthedocs.io/en/latest/command_line.html
 .. _Inputs: https://desc-docs.readthedocs.io/en/latest/input.html
 .. _Outputs: https://desc-docs.readthedocs.io/en/latest/output.html
-.. _Script Interface: https://desc-docs.readthedocs.io/en/latest/notebooks/tutorials/02_Script_Interface.html
+.. _Basic fixed boundary equilibrium: https://desc-docs.readthedocs.io/en/latest/notebooks/tutorials/basic_equilibrium.html
+.. _Advanced equilibrium: https://desc-docs.readthedocs.io/en/latest/notebooks/tutorials/advanced_equilibrium_continuation.html
+.. _Free boundary equilibrium: https://desc-docs.readthedocs.io/en/latest/notebooks/tutorials/free_boundary_equilibrium.html
+.. _Using DESC outputs: https://desc-docs.readthedocs.io/en/latest/notebooks/tutorials/use_outputs.html
+.. _Basic optimization: https://desc-docs.readthedocs.io/en/latest/notebooks/tutorials/basic_optimization.html
+.. _Advanced optimization: https://desc-docs.readthedocs.io/en/latest/notebooks/tutorials/advanced_optimization.html
+.. _Near axis constraints: https://desc-docs.readthedocs.io/en/latest/notebooks/tutorials/nae_constraint.html
+.. _api documentation: https://desc-docs.readthedocs.io/en/latest/api.html
 
 Repository Contents
 ===================
 
 - desc_ contains the source code including the main script and supplemental files. Refer to the API_ documentation for details on all of the available functions and classes.
 - docs_ contains the documentation files.
-- examples_ contains example input files along with corresponding DESC solutions, which are also accessible using the `desc.examples.get` function.
 - tests_ contains routines for automatic testing.
+- publications_ contains PDFs of publications by the DESC group, as well as scripts and data to reproduce the results of these papers.
 
 .. _desc: https://github.com/PlasmaControl/DESC/tree/master/desc
 .. _docs: https://github.com/PlasmaControl/DESC/tree/master/docs
-.. _examples: https://github.com/PlasmaControl/DESC/tree/master/desc/examples
 .. _tests: https://github.com/PlasmaControl/DESC/tree/master/tests
+.. _publications: https://github.com/PlasmaControl/DESC/tree/master/publications
 .. _API: https://desc-docs.readthedocs.io/en/latest/api.html
 
 Contribute

desc/magnetic_fields.py

@@ -1493,14 +1493,14 @@ def odefun(rpz, s):
 class CurrentPotentialField(_MagneticField, FourierRZToroidalSurface):
     """Magnetic field due to a surface current potential on a toroidal surface.
 
-        surface current K is assumed given by
-         K = n x ∇ Φ
-        where:
-               n is the winding surface unit normal.
-               Phi is the current potential function,
-                which is a function of theta and zeta.
-        This function then uses biot-savart to find the
-        B field from this current density K on the surface.
+    Surface current K is assumed given by K = n x ∇ Φ
+    where:
+
+        - n is the winding surface unit normal.
+        - Phi is the current potential function, which is a function of theta and zeta.
+
+    This function then uses biot-savart to find the B field from this current
+    density K on the surface.
 
     Parameters
     ----------
@@ -1636,7 +1636,7 @@ def potential_dzeta(self, new):
     def save(self, file_name, file_format=None, file_mode="w"):
         """Save the object.
 
-        **Not supported for this object!
+        **Not supported for this object!**
 
         Parameters
         ----------
@@ -1752,19 +1752,20 @@ class FourierCurrentPotentialField(
 ):
     """Magnetic field due to a surface current potential on a toroidal surface.
 
-        surface current K is assumed given by
+    Surface current K is assumed given by
+
+    K = n x ∇ Φ
+
+    Φ(θ,ζ) = Φₛᵥ(θ,ζ) + Gζ/2π + Iθ/2π
 
-        K = n x ∇ Φ
-        Φ(θ,ζ) = Φₛᵥ(θ,ζ) + Gζ/2π + Iθ/2π
+    where:
+        - n is the winding surface unit normal.
+        - Phi is the current potential function, which is a function of theta and zeta,
+          and is given as a secular linear term in theta/zeta and a double Fourier
+          series in theta/zeta.
 
-        where:
-              n is the winding surface unit normal.
-              Phi is the current potential function,
-                which is a function of theta and zeta,
-                and is given as a secular linear term in theta/zeta
-                and a double Fourier series in theta/zeta.
-        This function then uses biot-savart to find the
-        B field from this current density K on the surface.
+    This function then uses biot-savart to find the B field from this current
+    density K on the surface.
 
     Parameters
     ----------

docs/Makefile

@@ -18,9 +18,23 @@ variables.csv:
 optimizers.csv:
 	python write_optimizers.py
 
+clean:
+# generated by sphinx
+	rm -rf _build/
+	rm -rf _api/
+# generated by us
+	rm -f desc*.csv
+	rm -f optimizers.csv
+	rm -f variables.csv
+	rm -f variables.rst
+
 .PHONY: help Makefile variables.csv optimizers.csv
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile variables.csv optimizers.csv
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	rm -f desc*.csv
+	rm -f optimizers.csv
+	rm -f variables.csv
+	rm -f variables.rst

docs/api.rst

@@ -1,6 +1,6 @@
-=================
-API Documentation
-=================
+====================
+Alphabetical Listing
+====================
 
 Basis
 *****
@@ -123,7 +123,6 @@ IO
     :recursive:
     :template: class.rst
 
-    desc.io.InputReader
     desc.io.load
 
 Magnetic Fields
@@ -134,6 +133,8 @@ Magnetic Fields
     :recursive:
     :template: class.rst
 
+    desc.magnetic_fields.CurrentPotentialField
+    desc.magnetic_fields.FourierCurrentPotentialField
     desc.magnetic_fields.ScaledMagneticField
     desc.magnetic_fields.SumMagneticField
     desc.magnetic_fields.ToroidalMagneticField
@@ -187,6 +188,7 @@ Objective Functions
     desc.objectives.GoodCoordinates
     desc.objectives.HelicalForceBalance
     desc.objectives.Isodynamicity
+    desc.objectives.LinearObjectiveFromUser
     desc.objectives.MagneticWell
     desc.objectives.MeanCurvature
     desc.objectives.MercierStability

docs/api_continuation.rst

@@ -0,0 +1,31 @@
+======================
+Solving and Perturbing
+======================
+
+Continuation
+************
+``desc.continuation`` contains the methods used for solving equilibrium problems.
+``solve_continuation_automatic`` is usually the easiest method, users desiring more
+control over the process can also use ``solve_continuation``.
+
+.. autosummary::
+    :toctree: _api/continuation
+    :recursive:
+
+    desc.continuation.solve_continuation_automatic
+    desc.continuation.solve_continuation
+
+
+Perturbations
+*************
+``desc.perturbations.perturb`` is used inside of the continuation methods but can
+also be used alone to perform sensitivity analysis or perform parameter scans.
+``optimal_perturb`` is effectively a single step of a constrained optimization solver.
+
+.. autosummary::
+    :toctree: _api/perturbations
+    :recursive:
+
+    desc.perturbations.perturb
+    desc.perturbations.optimal_perturb
+    desc.perturbations.get_deltas

docs/api_equilibrium.rst

@@ -0,0 +1,69 @@
+==========================================
+Equilibrium, Surfaces, and Profile classes
+==========================================
+
+
+Equilibrium
+***********
+The ``Equilibrium`` is the core class representing an MHD equilibrium configuration.
+An ``EquilibriaFamily`` is a ``list`` like object for storing multiple equilibria.
+
+.. autosummary::
+    :toctree: _api/equilibrium
+    :recursive:
+    :template: class.rst
+
+    desc.equilibrium.Equilibrium
+    desc.equilibrium.EquilibriaFamily
+
+
+Geometry
+********
+The ``desc.geometry`` module contains important classes such as ``FourierRZToroidalSurface``
+for representing the shape of the plasma boundary, as well as classes for representing
+the magnetic axis, cross section, and various space curves.
+
+.. autosummary::
+   :toctree: _api/geometry/
+   :recursive:
+   :template: class.rst
+
+    desc.geometry.FourierRZToroidalSurface
+    desc.geometry.FourierRZCurve
+    desc.geometry.FourierXYZCurve
+    desc.geometry.FourierPlanarCurve
+    desc.geometry.SplineXYZCurve
+    desc.geometry.ZernikeRZToroidalSection
+
+
+Profiles
+********
+``desc.profiles`` contains objects representing 1-D flux functions such as pressure,
+current, rotational transform, temperature, or density. It is also possible to combine
+profiles together by addition, multiplication, or scaling.
+
+.. autosummary::
+    :toctree: _api/profiles
+    :recursive:
+    :template: class.rst
+
+    desc.profiles.PowerSeriesProfile
+    desc.profiles.SplineProfile
+    desc.profiles.MTanhProfile
+    desc.profiles.ScaledProfile
+    desc.profiles.SumProfile
+    desc.profiles.ProductProfile
+
+
+Utilities
+*********
+``desc.compat`` has utility functions for enforcing sign conventions or rescaling
+equilibria to a given size and/or field strength.
+
+.. autosummary::
+    :toctree: _api/compat
+    :recursive:
+
+    desc.compat.ensure_positive_jacobian
+    desc.compat.flip_helicity
+    desc.compat.rescale