{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# PSFs\n",
    "\n",
    "PSFs in prysm have a very simple constructor,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from prysm import PSF\n",
    "x = y = np.linspace(-1,1,128)\n",
    "z = np.random.random((128,128))\n",
    "ps = PSF(data=z, x=x, y=y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "PSFs are usually created from a [Pupil](./Pupils.ipynb) instance in a model, but the constructor can be used with e.g. experimental data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from prysm import Pupil\n",
    "ps = PSF.from_pupil(Pupil(dia=10), efl=20) # F/2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The encircled energy can be computed, for either a single point or an iterable (tuple, list, numpy array, …) of points,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ps.encircled_energy(0.1), ps.encircled_energy([0.1, 0.2, 0.3])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "encircled energy is computed via the method described in V Baliga, B D Cohn, “Simplified Method For Calculating Encircled Energy,” Proc. SPIE 0892, Simulation and Modeling of Optical Systems, (9 June 1988)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The inverse can also be computed using the a nonlinear optimization routine, provided the wavelength and F/# are known to support the initial guess."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ps.ee_radius(0.838)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Baliga’s method is relatively slow for large arrays, so a dictionary is kept of all computed encircled energies at `ps._ee`.\n",
    "\n",
    "The encircled energy can be plotted. An axis limit must be provided if no encircled energy values have been computed. If some have, by default prysm will plot the computed values if no axis limit is given"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ps.plot_encircled_energy()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ps.plot_encircled_energy(axlim=3, npts=50)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The PSF can be plotted in 2D,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ~0.838, exact value of energy contained in first airy zero\n",
    "from prysm.psf import FIRST_AIRY_ENCIRCLED\n",
    "ps.plot2d(axlim=5*1.22*ps.wavelength*FIRST_AIRY_ENCIRCLED,\n",
    "          power=2,\n",
    "          interp_method='lanczos',\n",
    "          pix_grid=1.12,\n",
    "          show_axlabels=True,\n",
    "          show_colorbar=True,\n",
    "          circle_ee=FIRST_AIRY_ENCIRCLED)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Both `plot_encircled_energy` and `plot2d` take the usual `fig` and `ax` kwargs as well. For `plot2d`, the `axlim` arg sets the x and y axis limits to symmetrical values of axlim, i.e. the limits above will be `[0.8, 0.8]`, `[0.8, 0.8]`. `power` controls the stretch of the color scale. The image will be stretched by the 1/power power, e.g. 2 plots psf^(1/2). `interp_method` is passed to matplotlib. `pix_grid` will use the minor axis ticks to draw a light grid over the PSF, intended to show the size of a PSF relative to the pixels of a detector. Units of microns. `show_axlabels` and `show_colorbar` both default to True, and control whether the axis labels are set and if the colorbar is drawn. `circle_ee` will draw a dashed circle at the radius containing the specified portion of the energy, and another at the diffraction limited radius for a circular aperture.\n",
    "\n",
    "PSFs are a subclass of Convolvable and inherit all methods and attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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
}