Docs and small fix

Author: SimonHeybrock

docs/user-guide/workflow.ipynb

@@ -4,7 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# He3 Cell Workflow\n",
+    "# Workflows\n",
+    "\n",
+    "## He3 Cell Workflow\n",
     "\n",
     "The `he3` submodule provides a helper `He3CellWorkflow`:"
    ]
@@ -24,7 +26,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Opacity\n",
+    "### Opacity\n",
     "\n",
     "There are two ways of computing the opacity, from cell parameters and from direct-beam measurements."
    ]
@@ -53,7 +55,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Transmission function\n",
+    "### Transmission function\n",
     "\n",
     "The opacity can be used to obtain the transmission function of the cells.\n",
     "We show the in-situ case, but it works equivalently for the more precise definition of opacity:"
@@ -71,6 +73,56 @@
     ")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "There is a variant of the workflow using an incoming polarized beam for computing the transmission function of the analyzer:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "workflow = pol.he3.He3CellWorkflow(in_situ=False, incoming_polarized=True)\n",
+    "workflow.visualize(\n",
+    "    (pol.TransmissionFunction[pol.Polarizer], pol.TransmissionFunction[pol.Analyzer]),\n",
+    "    graph_attr={\"rankdir\": \"LR\"},\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Supermirror Workflow\n",
+    "\n",
+    "The `supermirror` submodule provides a helper `SupermirrorWorkflow`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ess import polarization as pol\n",
+    "\n",
+    "workflow = pol.supermirror.SupermirrorWorkflow()\n",
+    "print(workflow.__doc__)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "workflow.visualize(pol.TransmissionFunction[pol.Polarizer])"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

src/ess/polarization/he3.py

@@ -236,7 +236,7 @@ def compute_transmission_fraction_from_direct_beam(
     )
 
 
-def get_he3_transmission_from_fit_to_direct_beam(
+def get_he3_transmission_incoming_unpolarized_from_fit_to_direct_beam(
     transmission_fraction: He3CellTransmissionFraction[PolarizingElement, Polarized],
     opacity_function: He3OpacityFunction[PolarizingElement],
     transmission_empty_glass: He3TransmissionEmptyGlass[PolarizingElement],
@@ -283,7 +283,7 @@ def expected_transmission(
 def get_he3_transmission_incoming_polarized_from_fit_to_direct_beam(
     transmission_fraction_up: He3AnalyzerTransmissionFraction[Up, Polarized],
     transmission_fraction_down: He3AnalyzerTransmissionFraction[Down, Polarized],
-    opacity_function: He3OpacityFunction[PolarizingElement],
+    opacity_function: He3OpacityFunction[Analyzer],
     transmission_empty_glass: He3TransmissionEmptyGlass[Analyzer],
 ) -> TransmissionFunction[Analyzer]:
     """
@@ -430,7 +430,9 @@ def He3CellWorkflow(
     *, in_situ: bool = True, incoming_polarized: bool = False
 ) -> sl.Pipeline:
     """
-    Workflow performing polarization correction for beam lines with two He3 cells.
+    Workflow for computing transmission functions for He3 cells.
+
+    This can handle polarizers as well as analyzers.
 
     Parameters
     ----------
@@ -439,20 +441,20 @@ def He3CellWorkflow(
         parameters, or an ex-situ definition based on direct beam data. The latter
         requires a direct-beam measurement with depolarized cells.
     incoming_polarized :
-        Whether the incoming beam for computing the cell transmission is polarized.
-        This is the case in beamlines with a supermirror polarizer.
+        Whether the incoming beam for computing the analyzer transmission is polarized.
+        This is the case in beamlines with a supermirror polarizer, but also if the
+        polarizer is not removed from the beam during the analyzer transmission
+        measurement.
     """
     workflow = sl.Pipeline(providers)
     if in_situ:
         workflow.insert(he3_opacity_function_from_cell_opacity)
     else:
         workflow.insert(he3_opacity_function_from_beam_data)
-    # TODO It is error-prone to rely on setting the correct workflow parameter here.
-    # Can PolarizationAnalysisWorkflow do this automatically if the polarizer workflow
-    # is a supermirror workflow? Or are there cases whether the polarizer is a He3 cell
-    # but the incoming beam is nevertheless polarized?
+    # Note that the incoming-unpolarized function is inserted even if
+    # incoming_polarized=True, since the incoming-unpolarized function is still
+    # required for computing the *polarizer* transmission calculation.
+    workflow.insert(get_he3_transmission_incoming_unpolarized_from_fit_to_direct_beam)
     if incoming_polarized:
         workflow.insert(get_he3_transmission_incoming_polarized_from_fit_to_direct_beam)
-    else:
-        workflow.insert(get_he3_transmission_from_fit_to_direct_beam)
     return workflow

src/ess/polarization/supermirror.py

@@ -59,4 +59,7 @@ def get_supermirror_transmission_function(
 
 
 def SupermirrorWorkflow() -> sciline.Pipeline:
+    """
+    Workflow for computing transmission functions for supermirror polarizing elements.
+    """
     return sciline.Pipeline(supermirror_providers)

tests/he3/polarization_test.py

@@ -23,7 +23,7 @@ def test_incoming_unpolarized_reproduces_input_params_within_errors() -> None:
         polarization=polarization,
     )
 
-    result = he3.get_he3_transmission_from_fit_to_direct_beam(
+    result = he3.get_he3_transmission_incoming_unpolarized_from_fit_to_direct_beam(
         transmission_fraction=transmission,
         opacity_function=opacity_function,
         transmission_empty_glass=transmission_empty_glass,
@@ -39,7 +39,7 @@ def test_incoming_unpolarized_reproduces_input_params_within_errors() -> None:
     transmission_noisy = transmission.copy()
     transmission_noisy.values += rng.normal(0.0, 0.01, transmission_noisy.shape)
 
-    result = he3.get_he3_transmission_from_fit_to_direct_beam(
+    result = he3.get_he3_transmission_incoming_unpolarized_from_fit_to_direct_beam(
         transmission_fraction=transmission_noisy,
         opacity_function=opacity_function,
         transmission_empty_glass=transmission_empty_glass,