Explain to users why variable computations may differ (#1615)

Resolves #1424
(#1424 (comment))
and resolves #1614.

desc/compute/_field.py

@@ -2488,7 +2488,8 @@ def _B_sub_zeta_rz(params, transforms, profiles, data, **kwargs):
     label="\\langle |\\mathbf{B}| \\rangle_{axis}",
     units="T",
     units_long="Tesla",
-    description="Average magnitude of magnetic field on the magnetic axis",
+    description="Average magnitude of magnetic field on the innermost flux surface "
+    "on the given grid",
     dim=0,
     params=[],
     transforms={"grid": []},

desc/integrals/singularities.py

@@ -232,8 +232,8 @@ def best_ratio(data, return_local=False):
     Parameters
     ----------
     data : dict[str, jnp.ndarray]
-        Dictionary of data evaluated on grid that ``can_fft2`` with keys
-        ``|e_theta x e_zeta|``, ``e_theta``, and ``e_zeta``.
+        Dictionary of data evaluated on single flux surface grid that
+        ``can_fft2`` with keys ``|e_theta x e_zeta|``, ``e_theta``, and ``e_zeta``.
     return_local : bool
         Whether to return the local ratio as well as the mean global ratio.
 

docs/write_variables.py

@@ -86,6 +86,13 @@ def write_csv(parameterization):
 those of the DESC :math:`\rho, \theta, \zeta` coordinate system. For example, ``|B|_z``
 is :math:`(\partial \vert B \vert / \partial\zeta)|_{\rho, \theta}`.
 
+Many quantities require special grids to compute accurately.
+To not burden users with such bookkeeping,
+when an object method such as ``eq.compute(...,override_grid=True)`` is called,
+DESC will automatically use a set of best grids for the computation.
+However, when writing objectives developers must perform the bookkeeping
+and ensure everything can be computed accurately on the chosen grid.
+
 """
 
 block = """