{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "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",
    "\n",
    "Zernike notations are a subclass of [Pupil](./Pupils.ipynb), so they support the same arguments to `__init__`,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "from prysm import FringeZernike, NollZernike\n",
    "p = FringeZernike(samples=123, dia=456.7, wavelength=1.0, opd_unit='nm', 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,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "p2 = FringeZernike(Z4=1, Z9=1, Z48=1, base=0, norm=True)\n",
    "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",
    "\n",
    "A Zernike pupil can also be initalized with an iterable (list, tuple...) of coefficients,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "terms = np.random.rand(49)  # 49 zernike coefficients, e.g. from a wavefront sensor\n",
    "fz3 = FringeZernike(terms)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Zernike instances have a `truncate` method which discards terms with indices higher than n. For example,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fz3.truncate(16)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "this is less efficient, however, than simply slicing the coefficient vector,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fz4 = FringeZernike(terms[:16])"
   ]
  },
  {
   "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,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fz4.top_n(5)"
   ]
  },
  {
   "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"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These things may be (bar) plotted;"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "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)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from prysm._zernike import defocus"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "each of these takes arguments of (rho, phi). They have names which end with _x, or _00 and _45 for the terms which have that naming convention."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Zernike functions are cached by prysm's internal routines,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from prysm.zernike import zcache\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"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This cache instance is used internally by prysm, if you modify the returned arrays in-place, you probably won’t like the result. You can create your own independent instance,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from prysm.zernike import ZCache\n",
    "my_zcache = ZCache()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See [Pupils](./Pupils.ipynb) for information about general pupil functions."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}