Improve documentation (#1304)

Resolves #1227 
Resolves #1252
Resolves #1261 
Resolves #1332 

- Make some clarifications to grid dev guide.
- Add a notebook that summarizes how we solve equilibrium problem
- Fix unavailable link in grid notebook
- Add Windows and WSL instructions
- Add an example compute function with additional kwarg

- [x] Fix the typos noticed during tutorial recording

docs/adding_compute_funs.rst

@@ -161,3 +161,70 @@ This test is a regression test to ensure that compute quantities in each new upd
 from previous versions of DESC.
 Since the new quantity did not exist in previous versions of DESC, one must run this test
 and commit the outputted ``tests/inputs/master_compute_data.pkl`` file which is updated automatically when a new quantity is detected.
+
+Compute function may take additional ``**kwargs`` arguments to provide more information to the function. One example of this kind of compute function is ``P_ISS04`` which has a keyword argument ``H_ISS04``.
+::
+
+  @register_compute_fun(
+    name="P_ISS04",
+    label="P_{ISS04}",
+    units="W",
+    units_long="Watts",
+    description="Heating power required by the ISS04 energy confinement time scaling",
+    dim=0,
+    params=[],
+    transforms={"grid": []},
+    profiles=[],
+    coordinates="",
+    data=["a", "iota", "rho", "R0", "W_p", "<ne>_vol", "<|B|>_axis"],
+    method="str: Interpolation method. Default 'cubic'.",
+    H_ISS04="float: ISS04 confinement enhancement factor. Default 1.",
+  )
+  def _P_ISS04(params, transforms, profiles, data, **kwargs):
+      rho = transforms["grid"].compress(data["rho"], surface_label="rho")
+      iota = transforms["grid"].compress(data["iota"], surface_label="rho")
+      fx = {}
+      if "iota_r" in data:
+          fx["fx"] = transforms["grid"].compress(
+              data["iota_r"]
+          )  # noqa: unused dependency
+      iota_23 = interp1d(2 / 3, rho, iota, method=kwargs.get("method", "cubic"), **fx)
+      data["P_ISS04"] = 1e6 * (  # MW -> W
+          jnp.abs(data["W_p"] / 1e6)  # J -> MJ
+          / (
+              0.134
+              * data["a"] ** 2.28  # m
+              * data["R0"] ** 0.64  # m
+              * (data["<ne>_vol"] / 1e19) ** 0.54  # 1/m^3 -> 1e19/m^3
+              * data["<|B|>_axis"] ** 0.84  # T
+              * iota_23**0.41
+              * kwargs.get("H_ISS04", 1)
+          )
+      ) ** (1 / 0.39)
+      return data
+
+
+This function can be called by following notation,
+::
+
+  from desc.compute.utils import _compute as compute_fun
+
+  # Compute P_ISS04
+  # specify gamma and H_ISS04 values as keyword arguments
+  data = compute_fun(
+            "desc.equilibrium.equilibrium.Equilibrium",
+            "P_ISS04",
+            params=params,
+            transforms=transforms,
+            profiles=profiles,
+            gamma=gamma,
+            H_ISS04=H_ISS04,
+        )
+  P_ISS04 = data["P_ISS04"]
+
+Note: Here we used `_compute` instead of `compute` to be able to call this function inside a jitted objective function. However, for normal use both functions should work. `**kwargs` can also be passed to `eq.compute`.
+
+::
+
+  data = eq.compute(names="P_ISS04", gamma=gamma, H_ISS04=H_ISS04)
+  P_ISS04 = data["P_ISS04"]

docs/index.rst

@@ -61,10 +61,11 @@
    :maxdepth: 1
    :caption: Developer guides
 
+   notebooks/dev_guide/getting-started-eq-solve.ipynb
+   notebooks/dev_guide/grid.ipynb
    adding_compute_funs
    adding_objectives
    adding_optimizers
-   notebooks/dev_guide/grid.ipynb
 
 
 

docs/installation.rst

@@ -13,6 +13,11 @@ Other package managers like venv could be used instead of conda, we have just ch
 **NOTE: DESC requires python>=3.9.**
 **If you have python2 also locally installed, replace all `pip` commands with `pip3` and all `python` commands with `python3` to ensure the correct python version is used.**
 
+**NOTE: If you are on Windows, consider using the Windows Subsystem for Linux (WSL) to install DESC.**
+
+We don't test or support DESC on Windows OS, and there have been some instances that numerical discrepancies on Windows can cause failures or wrong results. For these reasons, we recommend using WSL if you have a Windows machine. For instructions on how to install WSL see `here <https://learn.microsoft.com/en-us/windows/wsl/install>`__. For using WSL in VS Code see `here <https://code.visualstudio.com/docs/remote/wsl>`__.
+
+
 On Your Local Machine
 *********************
 

docs/notebooks/basis_grid.ipynb

@@ -425,7 +425,7 @@
     "\n",
     "The two primary attributes of any grid are `grid.nodes` and `grid.weights`.\n",
     "\n",
-    "`grid.nodes` is a $k \\times 3$ array of the node locations in straight field line coordinates $(\\rho,\\theta,\\zeta)$\n",
+    "`grid.nodes` is a $k \\times 3$ array of the node locations in flux coordinates $(\\rho,\\theta,\\zeta)$\n",
     "\n",
     "`grid.weights` is a $k \\times 1$ array giving approximate or exact quadrature weights for each node."
    ]
@@ -442,9 +442,9 @@
     "\n",
     "The simplest collocation grid is one that is linearly spaced in all coordinates $(\\rho,\\theta,\\zeta)$. It accepts 3 non-negative integer arguments in two different formats: \n",
     "\n",
-    "`L`, `M`, `N` specify the spectral resolution in each dimension. For example, `L=4` would give 5 radial grid points corresponding to a polynomial up to order $\\rho^4$. `M=2` would give 5 poloidal grid points corresponding to the 5 Fourier basis functions up to order $\\sin(2\\theta)$ and $\\cos(2\\theta)$. \n",
+    "* `L`, `M`, `N` specify the spectral resolution in each dimension. For example, `L=4` would give 5 radial grid points corresponding to a polynomial up to order $\\rho^4$. `M=2` would give 5 poloidal grid points corresponding to the 5 Fourier basis functions up to order $\\sin(2\\theta)$ and $\\cos(2\\theta)$. \n",
     "\n",
-    "`rho`, `theta`, `zeta` directly specify the number of linearly spaced grid points in each dimension, if passed as integers. Alternatively, these inputs can be used to manually specify the arrays of nodes. \n",
+    "* `rho`, `theta`, `zeta` directly specify the number of linearly spaced grid points in each dimension, if passed as integers. Alternatively, these inputs can be used to manually specify the arrays of nodes. \n",
     "\n",
     "The number of field periods is also input as a positive integer `NFP`. \n",
     "\n",
@@ -648,7 +648,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "desc-env",
    "language": "python",
    "name": "python3"
   },
@@ -662,7 +662,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,