Updated documentation, descriptions for v1.0 release.

scripts/ADC_instruction.ipynb

@@ -0,0 +1,156 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Atmospheric Dispersion Corrector model\n",
+    "\n",
+    "This notebook explains how you can use the ADC.py analytic ADC model for some quick simulations. For the model to be representative, the following assumptions must apply:\n",
+    "* The ADC consists of two amici prisms, totaling 4 glass prisms in total\n",
+    "* The ADC is located in the pupil plane of the instrument (or very close to it)\n",
+    "* The rotation of the prisms is defined as follows: for $\\theta=0$ the ADC is in it's maximum dispersive configuration. For any other rotation angle, the top prism set rotates by $\\theta$ degrees and the bottom prism set also rotates by $\\theta$ degrees in opposite direction. The total relative angle is thus $2\\theta$. From this also follows that the minimum dispersion magnitude is reached at $\\theta=90$ degrees.\n",
+    "\n",
+    "The ADC.py model is really not made for very general use, so it will likely require some editing in the source code by the user to make it work for a different instrument than MICADO.\n",
+    "\n",
+    "\n",
+    "We first start by importing the necessary files. Here we'll use the `AstroAtmosphere` package to calculate the atmospheric dispersion, but a manual input is also possible."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import ADC\n",
+    "import AstroAtmosphere"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then we calculate the atmospheric dispersion for a given set of conditions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Atmospheric conditions\n",
+    "T   = 288.15 \t# k\n",
+    "P   = 101325  \t# Pa\n",
+    "H   = 0.3\n",
+    "xc  = 400   \t# ppm\n",
+    "lat = -25 \t\t# degrees\n",
+    "h   = 2500  \t# m\n",
+    "l1  = 1.49 \t\t# micron, start H-band\n",
+    "l2  = 1.78 \t\t# micron, end H-band\n",
+    "zenith = 30 \t# degrees\n",
+    "\n",
+    "# Initializing dispersion model\n",
+    "at  = AstroAtmosphere.Observatory()\n",
+    "rho = at.rho(p=P, T=T, RH=H, xc=xc)\n",
+    "disp = AstroAtmosphere.dispersion(lat, h)\n",
+    "disp.setReducedHeight(P, rho)\n",
+    "\n",
+    "# Calculation of indices of refraction at l1 and l2\n",
+    "n1 = at.n_tph(l=l1, T=T, p=P, RH=H, xc=xc)\n",
+    "n2 = at.n_tph(l=l2, T=T, p=P, RH=H, xc=xc)\n",
+    "\n",
+    "# Calculation of atmospheric dispersion in milli arc sec\n",
+    "dispersion = disp.cassini(n1, n2, zenith)*3.6e6"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, we initialize the ADC class. We can calculate the dispersion in sky angles, i.e. in terms of the Field of View of the telescope, for a given rotation of the ADC prisms. In this case, if we set $\\theta=30$ degrees, we find that the ADC produces 58 milli arc seconds of dispersion in H-band."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The dispersion of the ADC for 30 degrees of rotation: 58.011 mas\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Initialize ADC object\n",
+    "adc = ADC.ADC()\n",
+    "\n",
+    "# Calculate the dispersion for a given rotation\n",
+    "theta = 30 # degrees\n",
+    "adc.setOrientation(theta)\n",
+    "adcDispersion = adc.calculateDispersion(l1,l2)[1]\n",
+    "print(\n",
+    "    'The dispersion of the ADC for {:.0f} degrees of rotation: {:.3f} mas'\\\n",
+    "    .format(theta, adcDispersion))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Of course, we're often much more interested in the optimum positioning of the ADC given an amount of atmospheric dispersion. This is done as follows."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The atmospheric dispersion: 24.771 mas\n",
+      "The optimum ADC angle in this case: 68.1 degrees\n",
+      "The residual dispersion: 0.000 mas\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Optimize for atmospheric dispersion, given wavelength range {l1,l2}\n",
+    "adcOptimumAngle = adc.optimize(dispersion, l1, l2) \n",
+    "adcDispersionOptimized = adc.calculateDispersion(l1,l2)[1]\n",
+    "\n",
+    "print('The atmospheric dispersion: {:.3f} mas'.format(dispersion) )\n",
+    "print('The optimum ADC angle in this case: {:.1f} degrees'.format(adcOptimumAngle))\n",
+    "print('The residual dispersion: {:.3f} mas'.format(dispersion - adcDispersionOptimized))\n"
+   ]
+  }
+ ],
+ "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.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}