Update pointing weights documentation to include plots from the obser…

…ver perspective and also panel plots of detector response for various HWP and fixed sky signal cases.

mkdocs/docs/pointing_weights.ipynb

@@ -39,18 +39,26 @@
   },
   {
    "cell_type": "markdown",
-   "id": "df26091f",
+   "id": "788cc93f",
    "metadata": {},
    "source": [
     "## Background\n",
     "\n",
-    "The \n",
+    "The \"Pointing Matrix\" in TOAST is represented by two types of operations.  The first is the mapping from geometric detector quaternion pointing to a pixelized representation of the sky.  The second is the model of the detector response to incoming polarized light.  This model can be expressed as the application of Mueller matrices representing optical elements in the system.  The incoming light can be expressed as a vector of Stokes parameters I, Q, U, and V.\n",
     "\n",
-    "The Stokes parameters are defined with respect to the local meridian at the detector line of sight.  In the TOAST formalism, the detector frame has the Z axis pointing along the detector line of sight and the X axis aligned with the direction of maximum polarization response.  For this exercise, we will use the COSMO convention for the Stokes parameters, since it conveniently also has the Z axis along the line of sight.  The final result is easy to swap between COSMO / IAU simply by changing the sign of the U Stokes parameter.\n",
+    "The Stokes parameters are defined with respect to the local meridian at the detector line of sight.  In the TOAST formalism, the detector frame has the Z axis pointing along the detector line of sight and the X axis aligned with the direction of maximum polarization response.  For this exercise, we will use the COSMO convention for the Stokes parameters, since it conveniently also has the Z axis along the line of sight.  The final result is easy to swap between COSMO / IAU simply by changing the sign of the U Stokes parameter.  In some scenarios, it can be convenient to look at the various angles from the perspective of the instrument \"looking out\" at the sky (with the detector Z axis going \"into the page\").  In other cases it makes more sense to visualize the situation \"looking in\" from the sky.  The figures below clearly label which case is being displayed.\n",
     "\n",
-    "![Conventions](conventions.pdf)\n",
+    "![COSMO_Conventions](pointing_weights_figs/COSMO_Pol_Conventions_v3.pdf)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "df26091f",
+   "metadata": {},
+   "source": [
+    "### Definitions\n",
     "\n",
-    "We will use alpha to represent the (counter-clockwise) angle from the meridian to the detector polarization orientation (the detector frame X axis).  We use omega to represent the (counter-clockwise) angle from the meridian to the HWP axis.  The cross-polar leakage of the detector is epsilon.  To visually simplify things, we define the polarization coefficient: \n",
+    "We will use $alpha$ to represent the angle of right-handed rotation from the meridian to the detector polarization orientation (the detector frame X axis) about the line of sight (detector Z axis).  We use $omega$ to represent the right-handed angle of rotation, about the line of sight, from the meridian to a direction parallel to the HWP fast axis.  The cross-polar leakage of the linearly polarized detector is $epsilon$.  To visually simplify things, we define the polarization coefficient: \n",
     "\n",
     "$$\n",
     "C = \\frac{1 - \\epsilon}{1 + \\epsilon}\n",
@@ -78,7 +86,7 @@
    "id": "a63eb656",
    "metadata": {},
    "source": [
-    "## Mueller Matrices\n",
+    "## Mueller Matrix Representation\n",
     "\n",
     "Assume we have an input Stokes vector:\n",
     "\n",
@@ -510,7 +518,7 @@
     "\n",
     "Our starting point is a detector quaternion at each sample that rotates the coordinate frame on the sky to the detector frame, with the Z axis along the line of sight and the X axis along the polarization sensitive direction.  In the detector frame, the vector along the meridian is offset by an angle of $-\\alpha$.  Recall that our detector coordinate frame is offset from the overall focalplane frame.  The detector frame is also rotated by an angle ${\\gamma}_{D}$.  The HWP angle (${\\gamma}_{H}(t)$) in the detector frame is time varying and measured from the same reference point:\n",
     "\n",
-    "![Detector Frame](det_frame.pdf)\n",
+    "![Detector Frame](pointing_weights_figs/det_frame.pdf)\n",
     "\n",
     "For the case with no HWP, we just need the angle $\\alpha$.  If we do have a HWP, then we can use the figure above to express $\\omega$ in terms of our known quantities.  From this we can see that $\\omega = \\alpha + {\\gamma}_{H}(t) - {\\gamma}_{D}$.  Substituting this we get (using COSMO convention, which is the default):\n",
     "\n",
@@ -544,15 +552,6 @@
     "$$\n",
     "P_{out} = \\frac{1}{2} \\left[\n",
     "I_{in} + \\frac{1 - \\epsilon}{1 + \\epsilon} \\left[ \n",
-    "Q_{in} \\cos \\left( 4 {\\gamma}_{D} - 4 {\\gamma}_{H}(t) - 2 \\alpha \\right) \n",
-    "- U_{in} \\sin \\left( 4 {\\gamma}_{D} - 4 {\\gamma}_{H}(t) - 2 \\alpha \\right)\n",
-    "\\right]\n",
-    "\\right]\n",
-    "$$\n",
-    "\n",
-    "$$\n",
-    "P_{out} = \\frac{1}{2} \\left[\n",
-    "I_{in} + \\frac{1 - \\epsilon}{1 + \\epsilon} \\left[ \n",
     "Q_{in} \\cos \\left( 2 \\left[ 2 \\left( {\\gamma}_{D} - {\\gamma}_{H}(t) \\right) - \\alpha \\right] \\right) \n",
     "- U_{in} \\sin \\left( 2 \\left[ 2 \\left( {\\gamma}_{D} - {\\gamma}_{H}(t) \\right) - \\alpha \\right] \\right)\n",
     "\\right]\n",
@@ -575,53 +574,53 @@
     "\n",
     "$$\n",
     "\\begin{aligned}\n",
-    "Q(45) = & \\;\\cos \\left( 2 \\alpha \\right) \\\\\n",
-    "Q(45) = & \\;0\n",
+    "Q_{weight}(45) = & \\;\\cos \\left( 2 \\alpha \\right) \\\\\n",
+    "Q_{weight}(45) = & \\;0\n",
     "\\end{aligned}\n",
     "$$\n",
     "\n",
     "$$\n",
     "\\begin{aligned}\n",
-    "U(45) = & \\;\\sin \\left( 2 \\alpha \\right) \\\\\n",
-    "U(45) = & \\;1\n",
+    "U_{weight}(45) = & \\;\\sin \\left( 2 \\alpha \\right) \\\\\n",
+    "U_{weight}(45) = & \\;1\n",
     "\\end{aligned}\n",
     "$$\n",
     "\n",
     "The Stokes Q weight is zero and the Stokes U weight is +1, which makes sense since the detector is aligned with the positive U axis.  In the case of a rotating HWP, our Q weight is:\n",
     "\n",
     "$$\n",
     "\\begin{aligned}\n",
-    "Q = & \\;\\cos \\left( 2 \\left[ 2 \\left( {\\gamma}_{D} - {\\gamma}_{H}(t) \\right) - \\alpha \\right] \\right) \\\\\n",
+    "Q_{weight} = & \\;\\cos \\left( 2 \\left[ 2 \\left( {\\gamma}_{D} - {\\gamma}_{H}(t) \\right) - \\alpha \\right] \\right) \\\\\n",
     "& \\;\\text{(substitute ${\\gamma}_{D}=\\alpha$)} \\\\\n",
-    "Q = & \\;\\cos \\left( 2 \\left[ 2 \\alpha - 2 {\\gamma}_{H}(t) - \\alpha \\right] \\right) \\\\\n",
-    "Q = & \\;\\cos \\left( 2 \\alpha - 4 {\\gamma}_{H}(t) \\right)\n",
+    "Q_{weight} = & \\;\\cos \\left( 2 \\left[ 2 \\alpha - 2 {\\gamma}_{H}(t) - \\alpha \\right] \\right) \\\\\n",
+    "Q_{weight} = & \\;\\cos \\left( 2 \\alpha - 4 {\\gamma}_{H}(t) \\right)\n",
     "\\end{aligned}\n",
     "$$\n",
     "\n",
     "and the U weight is:\n",
     "\n",
     "$$\n",
     "\\begin{aligned}\n",
-    "U = & \\;\\sin \\left( 2 \\left[ 2 \\left( {\\gamma}_{D} - {\\gamma}_{H}(t) \\right) - \\alpha \\right] \\right) \\\\\n",
+    "U_{weight} = & \\;\\sin \\left( 2 \\left[ 2 \\left( {\\gamma}_{D} - {\\gamma}_{H}(t) \\right) - \\alpha \\right] \\right) \\\\\n",
     "& \\;\\text{(substitute ${\\gamma}_{D}=\\alpha$)} \\\\\n",
-    "U = & \\;\\sin \\left( 2 \\left[ 2 \\alpha - 2 {\\gamma}_{H}(t) - \\alpha \\right] \\right) \\\\\n",
-    "U = & \\;\\sin \\left( 2 \\alpha - 4 {\\gamma}_{H}(t) \\right)\n",
+    "U_{weight} = & \\;\\sin \\left( 2 \\left[ 2 \\alpha - 2 {\\gamma}_{H}(t) - \\alpha \\right] \\right) \\\\\n",
+    "U_{weight} = & \\;\\sin \\left( 2 \\alpha - 4 {\\gamma}_{H}(t) \\right)\n",
     "\\end{aligned}\n",
     "$$\n",
     "\n",
     "Consider what happens when the fast axis of the HWP is aligned with the detector orientation (${\\gamma}_{H} = \\alpha = {\\gamma}_{D} = 45^{\\circ}$).  In that scenario we have:\n",
     "\n",
     "$$\n",
     "\\begin{aligned}\n",
-    "Q_{HWP}(45) = & \\;\\cos \\left( - 2 \\alpha \\right)\\\\\n",
-    "Q_{HWP}(45) = & \\;0\n",
+    "Q_{weight}(45,HWP) = & \\;\\cos \\left( - 2 \\alpha \\right)\\\\\n",
+    "Q_{weight}(45,HWP) = & \\;0\n",
     "\\end{aligned}\n",
     "$$\n",
     "\n",
     "$$\n",
     "\\begin{aligned}\n",
-    "U_{HWP}(45) = & \\;\\sin \\left( - 2 \\alpha \\right)\\\\\n",
-    "U_{HWP}(45) = & \\;-1\n",
+    "U_{weight}(45,HWP) = & \\;\\sin \\left( - 2 \\alpha \\right)\\\\\n",
+    "U_{weight}(45,HWP) = & \\;-1\n",
     "\\end{aligned}\n",
     "$$"
    ]
@@ -756,36 +755,31 @@
    "id": "d077a266",
    "metadata": {},
    "source": [
-    "## Stokes Weights Unit Test Summary\n",
+    "### Stokes Weights Unit Tests\n",
     "\n",
-    "I have implemented some plots in the unit tests that attempt to convey the different quantities at play.  For each case in the following plots:\n",
+    "The following plots are generated by the unit tests for different cases of input Stokes parameters and HWP state.  For each case in the following plots:\n",
     "\n",
     "1. The input fake sky has constant I/Q/U values at each pixel, and those are given in the plot subtitle.\n",
     "\n",
     "2. The plot is \"looking out\" from the telescope and the COSMO convention Q/U axes are drawn from this perspective.\n",
     "\n",
     "3. The focalplane frame X axis is parallel to the local coordinate system meridian and pointed \"South\".  In other words, the detector gamma angle is exactly equal to the \"alpha\" angle from the local meridian.\n",
     "\n",
-    "4. There are 4 detectors at the boresight, and their actual and expected values are given (which should be the same).  I am using a calibration factor of 0.5, so the total response is $0.5[I + q_{weight} * Q + u_{weight} * U]$.  The q/u weights are defined in this document above and in the code for the cases with / without a HWP.  The cross polar response is set to zero in this test.\n",
+    "4. There are 4 detectors at the boresight, and their actual and expected values are given (which should be the same).  I am using a calibration factor of $C = 0.5$, so the total response is $0.5[I + q_{weight} * Q + u_{weight} * U]$.  The q/u weights are defined in this document above and in the code for the cases with / without a HWP.  The cross polar response is set to zero in this test.\n",
     "\n",
-    "Each row represents a different HWP state (including no HWP at all).  Each column is different set of input map values."
+    "Each row represents a different HWP state (including no HWP at all).  Each column represents different input map values of $I = 1$, $Q = 1$, $U = 1$, and $I = Q = U = 1$"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "c5ed2097",
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "be29864d",
+   "cell_type": "markdown",
+   "id": "afff2a53",
    "metadata": {},
-   "outputs": [],
-   "source": []
+   "source": [
+    "![No HWP](pointing_weights_figs/hwp_row_none.pdf)\n",
+    "![HWP 0.0](pointing_weights_figs/hwp_row_0.0.pdf)\n",
+    "![HWP 45.0](pointing_weights_figs/hwp_row_45.0.pdf)\n",
+    "![HWP 90.0](pointing_weights_figs/hwp_row_90.0.pdf)"
+   ]
   }
  ],
  "metadata": {