Improve documentation

docs/adding_compute_funs.rst

@@ -161,3 +161,61 @@ 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 which cannot be get from other input arguments or dependencies in ``data``. One example of this kind of compute function is ``P_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,
+::
+
+  # 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"]

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 DESC on Windows and there have been some instances that numerical discrepancies on Windows cause failures or wrong results. For 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,