141 resolution tutorial (#142)

* tutorial and renaming

* cleaninG and figures

* cleaning

* documentation

* update docs

* adjustments to tutorial

* pr response

EasyReflectometry/calculators/wrapper_base.py

@@ -3,7 +3,7 @@
 
 import numpy as np
 
-from EasyReflectometry.experiment import constant_resolution_function
+from EasyReflectometry.experiment import percentage_fhwm_resolution_function
 
 DEFAULT_RESOLUTION_FWHM_PERCENTAGE = 5.0
 
@@ -17,7 +17,7 @@ def __init__(self):
             'item': {},
             'model': {},
         }
-        self._resolution_function = constant_resolution_function(DEFAULT_RESOLUTION_FWHM_PERCENTAGE)
+        self._resolution_function = percentage_fhwm_resolution_function(DEFAULT_RESOLUTION_FWHM_PERCENTAGE)
 
     def reset_storage(self):
         """Reset the storage area to blank."""

EasyReflectometry/experiment/__init__.py

@@ -1,10 +1,10 @@
 from .model import Model
 from .model_collection import ModelCollection
-from .resolution_functions import constant_resolution_function
 from .resolution_functions import linear_spline_resolution_function
+from .resolution_functions import percentage_fhwm_resolution_function
 
 __all__ = (
-    constant_resolution_function,
+    percentage_fhwm_resolution_function,
     linear_spline_resolution_function,
     Model,
     ModelCollection,

EasyReflectometry/experiment/model.py

@@ -18,7 +18,7 @@
 from EasyReflectometry.sample import LayerCollection
 from EasyReflectometry.sample import Sample
 
-from .resolution_functions import constant_resolution_function
+from .resolution_functions import percentage_fhwm_resolution_function
 
 DEFAULTS = {
     'scale': {
@@ -76,7 +76,7 @@ def __init__(
         if sample is None:
             sample = Sample(interface=interface)
         if resolution_function is None:
-            resolution_function = constant_resolution_function(DEFAULTS['resolution']['value'])
+            resolution_function = percentage_fhwm_resolution_function(DEFAULTS['resolution']['value'])
 
         scale = get_as_parameter('scale', scale, DEFAULTS)
         background = get_as_parameter('background', background, DEFAULTS)

EasyReflectometry/experiment/resolution_functions.py

@@ -11,7 +11,7 @@
 import numpy as np
 
 
-def constant_resolution_function(constant: float) -> Callable[[np.array], np.array]:
+def percentage_fhwm_resolution_function(constant: float) -> Callable[[np.array], np.array]:
     """Create a resolution function that is constant across the q range.
 
     :param constant: The constant resolution value.
@@ -27,19 +27,19 @@ def _constant(q: Union[np.array, float]) -> np.array:
     return _constant
 
 
-def linear_spline_resolution_function(q_data_points: np.array, resolution_points: np.array) -> Callable[[np.array], np.array]:
+def linear_spline_resolution_function(q_data_points: np.array, fwhm_values: np.array) -> Callable[[np.array], np.array]:
     """Create a resolution function that is linearly interpolated between given data points.
 
     :param q_data_points: The q values at which the resolution is defined.
-    :param resolution_points: The resolution values at the given q values.
+    :param fwhm_values: The resolution values at the given q values.
     """
 
     def _linear(q: np.array) -> np.array:
         """Function that calculates the resolution at a given q value.
 
         The function uses the data points from the encapsulating function and produces a linearly interpolated between them.
         """
-        return np.interp(q, q_data_points, resolution_points)
+        return np.interp(q, q_data_points, fwhm_values)
 
     return _linear
 

docs/experiment/experiment.rst

@@ -0,0 +1,80 @@
+Experiment
+==========
+
+The main component of an experiment in :py:mod:`EasyReflectometry` is the `Model`. 
+This is a description of the `sample` and the environment in which the experiment is performed. 
+The `Model` is used to calculate the reflectivity of the `Sample` at a given set of angles (Q-points).
+The `resolution_functions` are used to quantify the experimental uncertainties in wavelength and angle, allowing the `Model`` to accurately describe the data.
+
+:py:class:`Model`
+-----------------
+
+A `Model` instance contains a `Sample` and variables describing experimental settings.
+To be able to compute reflectivities it is also necessary to have a `Calculator` (interface).
+
+.. code-block:: python 
+
+   from EasyReflectometry.calculators import CalculatorFactory
+   from EasyReflectometry.experiment import Model
+   from EasyReflectometry.sample import Sample
+
+   default_sample = Sample()
+   m = Model(
+      sample=default_sample,
+      scale=1.0,
+      background=1e-6
+   )
+
+   interface = CalculatorFactory()
+   model.interface = interface
+
+This will create a :py:class:`Model` instance with the `default_sample` and the environment variables `scale` factor set to 1.0 and a `background` of 1e-6.
+Following the `interface` is set to the default calculator that is `Refnx`.
+
+
+:py:mod:`resolution_functions`
+------------------------------
+A resolution function enables the `EasyReflectometry` model to incorporate the experimental uncertainties in wavelength and incident angle into the model.
+In its essence the resolution function controls the smearing to apply when determing the reflectivtiy at a given Q-point.
+For a given Q-point the smearing to apply is given as a weighted average of the neighboring Q-point, which weigths are by a normal distribution.
+This normal distribution is then defined by a Q-point dependent Full Width at the Half Maximum (FWHM) that is given by the resolution function.
+
+:py:func:`percentage_fhwm_resolution_function`
+Often we rely on a resolution function that has a simple functional dependecy of the Q-point.
+By this is understood that the applied smearing in an Q-point has a FWHM that is simply a percentage of the value of the Q-point.
+
+.. code-block:: python 
+
+   from EasyReflectometry.experiment import Model
+   from EasyReflectometry.experiment import percentage_fhwm_resolution_function
+
+   resolution_function = percentage_fhwm_resolution_function(1.1)
+
+   m = Model(
+      resolution_function=resolution_function
+   )
+
+This will create a :py:class:`Model` instance where the resolution function is defined as 1.1% of the Q-point value, which again is the FWHM for the smearing.
+
+
+:py:func:`linear_spline_resolution_function`
+Alternatively the FWHM value might be determined and declared directly for each measured Q-point.
+When this is the case the provided Q-points and the corresponding FWHM values can be used to declare a linear spline function
+and thereby enable a determination of the reflectivity at an arbitrary point within the provided range of discrete Q-points.
+
+.. code-block:: python 
+
+   from EasyReflectometry.experiment import Model
+   from EasyReflectometry.experiment import linear_spline_resolution_function
+
+   m = Model()
+
+   resolution_function = linear_spline_resolution_function(
+      q_points=[0.01, 0.2, 0.31],
+      fwhm_values=[0.001, 0.043, 0.026]
+   )
+
+   m.resolution_function = resolution_function
+
+This will create a :py:class:`Model` instance where the resolution function defining the FWHM is determined from a linear interpolation.
+In the present case the provided data Q-points are (`[0.01, 0.2, 0.31]`) and the corresponding FWHM function values are (`[0.001, 0.043, 0.026]`).

docs/index.rst

@@ -8,6 +8,7 @@
    usage
    sample/sample
    calculators
+   experiment/experiment
    tutorials/tutorials
    contributing
    authors