rewrite Zernike user guide

docs/source/user_guide/Zernikes.ipynb

@@ -6,7 +6,13 @@
    "source": [
     "# Zernikes\n",
     "\n",
-    "Prysm supports two flavors of Zernike polynomials; the Fringe set up to the 49th term, and the Noll set up to the 36th term. They have identical interfaces, so only one will be shown here.\n",
+    "Prysm supports several flavors of Zernike polynomial:\n",
+    "- Fringe\n",
+    "- Noll\n",
+    "- ANSI \"j\"\n",
+    "- ANSI \"n,m\"\n",
+    "\n",
+    "The single index notations have identical interfaces, while the (n,m) notation is slightly different.\n",
     "\n",
     "Zernike notations are a subclass of [Pupil](./Pupils.ipynb), so they support the same arguments to `__init__`,"
    ]
@@ -18,15 +24,15 @@
    "outputs": [],
    "source": [
     "%matplotlib inline\n",
-    "from prysm import FringeZernike, NollZernike\n",
+    "from prysm import FringeZernike, NollZernike, ANSI1TermZernike, ANSI2TermZernike\n",
     "p = FringeZernike(samples=123, dia=456.7, wavelength=1.0, z_unit='nm', phase_mask='dodecagon')"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "There are additional keyword arguments for each term, and the base (0 or 1) can be supplied. With base 0, the terms start at Z0 and range to Z48. With base 1, they start at Z1 and range to Z49 (or Z48, for Standard Zernikes). The Fringe set can also be used with unit variance via the `norm` keyword argument. Both notations also have nice print statements,"
+    "There are additional keyword arguments for each term.  The polynomials are orthogonal, having unit amplitude (zero-to-peak).  They can also be used with unit variance via the `norm` keyword argument, in which case they are orthonormal.  The polynomial classes have friendly print statements:"
    ]
   },
   {
@@ -35,15 +41,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "p2 = FringeZernike(Z4=1, Z9=1, Z48=1, base=0, norm=True)\n",
+    "p2 = FringeZernike(Z4=1, Z9=1, Z98=1, norm=True)\n",
     "print(p2)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Notice that the RMS value is equal to sqrt(1^2 + 1^2 + 1^2) = sqrt(3) = 1.732 ~= 1.722. The difference of ~1% is due to the array sizes used by prysm by default, if increased, e.g. by adding `samples=1204` to the constructor, the value would converge to the analytical one.\n",
+    "Notice that we include a 98th term which you likely will not find in most other programs, and that the RMS value is equal to sqrt(1^2 + 1^2 + 1^2) = sqrt(3) = 1.718 ~= 1.722. The difference is due to the array sizes used by prysm by default, if increased, e.g. by adding `samples=1204` to the constructor, the value would converge to the analytical one.\n",
     "\n",
     "A Zernike pupil can also be initalized with an iterable (list, tuple...) of coefficients,"
    ]
@@ -72,14 +78,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fz3.truncate(16)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "this is less efficient, however, than simply slicing the coefficient vector,"
+    "fz3.truncate(16)\n",
+    "print(fz3)"
    ]
   },
   {
@@ -88,16 +88,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fz4 = FringeZernike(terms[:16])"
+    "fz3.top_n(5)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "and this slicing alternative should be used when one is sensitive to performance.\n",
-    "\n",
-    "The top few terms may be extracted,"
+    "or the terms listed by their pairwise magnitudes and clocking angles,"
    ]
   },
   {
@@ -106,23 +104,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fz4.top_n(5)"
+    "fz3.magnitudes"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "or the terms listed by their pairwise magnitudes and clocking angles,"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "fz4.magnitudes"
+    "Magnitudes is a dict keyed by the name with values of `(mag, ang)`.  The angle is always zero if the term is rotationally invariant."
    ]
   },
   {
@@ -138,9 +127,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fz4.barplot(orientation='h', buffer=1, zorder=3)\n",
-    "fz4.barplot_magnitudes(orientation='h', buffer=1, zorder=3)\n",
-    "fz4.barplot_topn(n=5, orientation='h', buffer=1, zorder=3)"
+    "fz3.barplot(orientation='h', buffer=1, zorder=3)\n",
+    "fz3.barplot_magnitudes(orientation='h', buffer=1, zorder=3)\n",
+    "fz3.barplot_topn(n=5, orientation='h', buffer=1, zorder=3)"
    ]
   },
   {
@@ -149,7 +138,7 @@
    "source": [
     "`orientation` controls the axis on which the terms are enumerated. `h` results in vertical bars, `v` is also accepted, as are horizontal and vertical. `buffer` is the number of terms’ worth of spaces left on each side. The default of 1 leaves a one bar margin. `zorder` is passed to matplotlib – the default of 3 places the bars above any gridlines, which is an aesthetic choice. Matplotlib has a general default of 1.\n",
     "\n",
-    "If you would like direct access to the underlying functions, there are two paths. `prysm._zernike` contains functions for the first 49 (Fringe ordered) Zernike polynomials, for example"
+    "If you would like direct access to the underlying functions, the first few polynomials are provided as explicit functions and can be imported:"
    ]
   },
   {
@@ -181,10 +170,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from prysm.zernike import zcache\n",
+    "from prysm.zernike import zcachemn\n",
     "# 8 is the index into prysm.zernike.zernikes, which loosely follows the Fringe ordering\n",
-    "zcache(8, norm=True, samples=128)\n",
-    "zcache.clear()  # you should never have to do this unless you want to release memory"
+    "zcachemn(7, 7, norm=True, samples=128)\n",
+    "zcachemn.clear()  # you should never have to do this unless you want to release memory"
    ]
   },
   {
@@ -200,8 +189,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from prysm.zernike import ZCache\n",
-    "my_zcache = ZCache()"
+    "from prysm.zernike import ZCacheMN\n",
+    "my_zcache = ZCacheMN()"
    ]
   },
   {
@@ -228,7 +217,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.4"
+   "version": "3.7.6"
   }
  },
  "nbformat": 4,