Make integration stuff visible to users and update dev guide (#1212)

This PR moves the integration utilities to their own subfolder so that
they are visible to users. We have decided not to include in public API,
because that's for optimization stuff.

- [x] Increase visibility of integration utilities.
- [x] Resolve #723 by adding link to tutorial in docstring of
`surface_integrals.py`.
- [x] Update `grid.py` developer guide.
- Cherry picked from #353 with the new section from #1101 that
emphasizes poloidal midplane symmetry is not stellarator symmetry.
Removed section on custom grids.

desc/compute/__init__.py

@@ -26,8 +26,6 @@
 # just need to import all the submodules here to register everything in the
 # data_index
 
-from desc.utils import flatten_list
-
 from . import (
     _basis_vectors,
     _bootstrap,

desc/compute/_bootstrap.py

@@ -13,8 +13,8 @@
 from scipy.special import roots_legendre
 
 from ..backend import fori_loop, jnp
+from ..integrals import surface_averages_map
 from .data_index import register_compute_fun
-from .utils import surface_averages_map
 
 
 @register_compute_fun(

desc/compute/_equil.py

@@ -13,8 +13,9 @@
 
 from desc.backend import jnp
 
+from ..integrals import surface_averages
 from .data_index import register_compute_fun
-from .utils import cross, dot, safediv, safenorm, surface_averages
+from .utils import cross, dot, safediv, safenorm
 
 
 @register_compute_fun(

desc/compute/_field.py

@@ -13,17 +13,14 @@
 
 from desc.backend import jnp
 
-from .data_index import register_compute_fun
-from .utils import (
-    cross,
-    dot,
-    safediv,
-    safenorm,
+from ..integrals import (
     surface_averages,
     surface_integrals_map,
     surface_max,
     surface_min,
 )
+from .data_index import register_compute_fun
+from .utils import cross, dot, safediv, safenorm
 
 
 @register_compute_fun(

desc/compute/_geometry.py

@@ -11,8 +11,9 @@
 
 from desc.backend import jnp
 
+from ..integrals.surface_integral import line_integrals, surface_integrals
 from .data_index import register_compute_fun
-from .utils import cross, dot, line_integrals, safenorm, surface_integrals
+from .utils import cross, dot, safenorm
 
 
 @register_compute_fun(

desc/compute/_metric.py

@@ -13,8 +13,9 @@
 
 from desc.backend import jnp
 
+from ..integrals import surface_averages
 from .data_index import register_compute_fun
-from .utils import cross, dot, safediv, safenorm, surface_averages
+from .utils import cross, dot, safediv, safenorm
 
 
 @register_compute_fun(

desc/compute/_profiles.py

@@ -13,8 +13,9 @@
 
 from desc.backend import cond, jnp
 
+from ..integrals import surface_averages, surface_integrals
 from .data_index import register_compute_fun
-from .utils import cumtrapz, dot, safediv, surface_averages, surface_integrals
+from .utils import cumtrapz, dot, safediv
 
 
 @register_compute_fun(

desc/compute/_stability.py

@@ -13,8 +13,9 @@
 
 from desc.backend import jnp
 
+from ..integrals import surface_integrals_map
 from .data_index import register_compute_fun
-from .utils import dot, surface_integrals_map
+from .utils import dot
 
 
 @register_compute_fun(