pymodaq_plugins_beam_shaping 5.3.1__tar.gz → 5.3.2__tar.gz

{pymodaq_plugins_beam_shaping-5.3.1 → pymodaq_plugins_beam_shaping-5.3.2}/AGENTS.md

@@ -207,4 +207,8 @@ extensions already does the job and only the conversion of the measurements or o
 - [ ] Tests added for new behaviour using a mock controller (no real hardware in CI).
 - [ ] Docstring of each plugin class states: compatible devices, what was tested, PyMoDAQ and OS versions,
       drivers to install.
-- [ ] `README.rst` updated; target PyMoDAQ version stated.
+- [ ] `README.rst` updated; target PyMoDAQ version stated. Keep its section order: a short description, then `Authors`
+      (then `Contributors` if needed), then `Instruments` (`Actuators`, `Viewer0D`...). `pymodaq_plugin_manager` reads the
+      README from `Authors` to `Instruments` (`extract_authors_from_description` in its `validate.py`), so write nothing
+      else before these sections or between them: requirements, installation, hardware notes or differences with
+      another branch come after the `Instruments` list.

{pymodaq_plugins_beam_shaping-5.3.1 → pymodaq_plugins_beam_shaping-5.3.2}/AGENTS_BEAM_SHAPING.md

@@ -30,6 +30,7 @@ close to the template so that it can be updated); this file is what is specific
 | `algorithms/factory.py` | `AlgorithmFactory`, `register_algorithms()` and the entry point group `pymodaq_plugins_beam_shaping.algorithms` for third party algorithms. |
 | `algorithms/algorithms/` | The **algorithms**, one module per family (see below). |
 | `algorithms/ini_phases/`, `stoppings/`, `loss.py` | Initial phases, stopping criteria and loss functions used by iterative algorithms. |
+| `algorithms/compensation.py`, `compensations/` | Compensation of the input beam profile (factory like the initial phases, chosen in the AlgoApp settings); an algorithm sets `INPUT_COMPENSATION` to the `Compensations` (StrEnum, add a member for a new compensation) member of its default compensation (None: none) and calls `compensate_target`. |
 | `algorithms/algorithm_app.py` | `AlgoApp`: the widget running an algorithm, owning the masks, the shaper and the fields. |
 | `algorithms/utils.py` | Enums (`AlgoStatus`, `AlgoType`, `ApplyMaskTo`, `LensSetup`). |
 | `utilities/shaper.py` | `Shaper` and `ModulatorType` (phase, amplitude, both), defined in `pymodaq_plugins_utils`; `get_default_shaper()` reads the config. |

{pymodaq_plugins_beam_shaping-5.3.1 → pymodaq_plugins_beam_shaping-5.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pymodaq_plugins_beam_shaping
-Version: 5.3.1
+Version: 5.3.2
 Summary: PyMoDAQ's extension plugin to run optical shaping from various shapers (focusing on amplitude and phase shaping) and the image propagation
 Project-URL: Homepage, https://pymodaq.cnrs.fr
 Project-URL: Documentation , https://pymodaq.cnrs.fr

{pymodaq_plugins_beam_shaping-5.3.1 → pymodaq_plugins_beam_shaping-5.3.2}/docs/scripts/binary_holograms_snapshots.py

@@ -32,7 +32,10 @@ for name in ALGORITHMS:
     pg.set_fields(algo, input_field, target_field)
     # the order to filter, as given by the algorithm, in um from the center of the intermediate plane
     y, x = np.array(algo.order_frequency()) * regions.pixel_sizes_in_um(algo.intermediate_pixel_sizes)
-    mask = ((y - MASK_HALF_SIZE, y + MASK_HALF_SIZE), (x - MASK_HALF_SIZE, x + MASK_HALF_SIZE))
+    center_y, center_x = np.array(algo.shape) * regions.pixel_sizes_in_um(algo.intermediate_pixel_sizes) / 2
+    # in the frame of the extension: the origin is the corner of the field
+    mask = ((center_y + y - MASK_HALF_SIZE, center_y + y + MASK_HALF_SIZE),
+            (center_x + x - MASK_HALF_SIZE, center_x + x + MASK_HALF_SIZE))
     pg.set_mask(app, ApplyMaskTo.INTERMEDIATE, mask, 'elliptical')
     pg.run_algorithm(algo)
     output = algo.output_field

{pymodaq_plugins_beam_shaping-5.3.1 → pymodaq_plugins_beam_shaping-5.3.2}/docs/src/user_guide/algorithm_reference.rst

@@ -8,6 +8,10 @@ Sizes of pixels in these settings follow the shaper (see :doc:`shapers`).
 Settings shared by the algorithms
 ---------------------------------
 
+The settings of the algorithm app (initial phase, masks, crosstalk, compensation of the input beam...) and the own
+settings of each algorithm are saved in the configuration file, **per algorithm**, and loaded back when the algorithm
+is selected (an algorithm never run keeps the values of the previous one).
+
 Most algorithms start from an *initial phase* of the modulator, which is also a choice in the settings:
 
 * **Random**: a random phase.
@@ -40,7 +44,7 @@ that removes the undiffracted light. Not iterative. Implements the five methods
 * ``Diffractive Models``: *Relative Amplitude* (method A), *Scattering* (B), *Davis* (C), *Bolduc* (D) or *Arrizon* (E).
 * ``Order N`` (default 10).
 
-OL2014 - Amplitude/Phase Checkerboard
+OL2014 - Amplitude-Phase Checkerboard
 -------------------------------------
 
 Creates **amplitude and phase** images with a phase-only modulator in a **4f** line with a filter in the Fourier plane,
@@ -49,6 +53,8 @@ by encoding the complex field on a checkerboard (:cite:t:`mendoza-yero_encoding_
 *Settings*:
 
 * ``Mask block size (pxls)`` (default 5): size of the blocks of the checkerboard.
+* The input beam is compensated (see *Input compensation* below): the amplitude of the target is divided by the one of
+  the beam before the angles of the checkerboard are computed.
 * ``amplitude divider`` (default 1).
 
 .. _sec-algo-amplitude-modulation:
@@ -91,10 +97,17 @@ in the review but not available.
 * ``Binarize`` (default checked): the pattern is binarized, as a DMD can only switch its pixels on or off. Unchecked,
   the grey levels of the pattern are kept (the grey off-axis hologram, an ideal modulation not feasible on a DMD, to
   see what the binarization costs).
+* The compensation of the input beam is not a setting of the algorithm: see *Input compensation* below.
 * ``Remove carrier`` (default checked), ``Carrier from`` and ``Carrier factor``: see below.
 * ``Order position``: a read-only text, updated with the periods, giving the position of the order to filter, and the
   slices of a mask around it that can be copied to the slices of the *Intermediate Masking*.
 
+What is sent to the modulator is the *SLM field* (``slm_field`` of the algorithm, ``slm`` data): the amplitude pattern
+(0 and 1 for a DMD, 1 for a phase-only modulator) and the phase (0 for an amplitude-only modulator), without the
+corrections that the extension adds when sending. It is not the *modulator field*, the field just after the modulator:
+this one is the input beam times the SLM field, and is the one used to compute the output. The fields of the
+algorithm hold ``slm/phase`` for every type of modulator and ``slm/amplitude`` when an amplitude is sent.
+
 The two first orders of the grating carry opposite phases, and this is physical: the order at ``+ν`` carries the phase
 ``-φ`` of the target, the one at ``-ν`` (the order (-1, 0) of the review) carries ``+φ``. Select the order that carries
 the phase of the target: the one the *Order position* gives.
@@ -232,3 +245,32 @@ Minimize and TorchOptim
 
 *Minimize* only: ``Method`` of the minimizer (default l-bfgs): bfgs, l-bfgs, cg, newton-cg, newton-exact, dogleg,
 trust-ncg, trust-exact or trust-krylov.
+
+
+Input compensation
+------------------
+
+The algorithms that compute the pattern of the modulator from the target (*Parallel Lee*, *Superpixel* and the
+checkerboard *OL2014*) give, without compensation, a target multiplied by the amplitude profile of the input beam. The
+group ``Input Compensation`` of the settings of the algorithm app (shown for these algorithms only, like the initial
+phase for the algorithms that have one) chooses what is done:
+
+* ``NoCompensation``: the output is the target times the profile of the beam.
+* ``DivideByInput`` (default): the amplitude to encode is the target divided by the input amplitude, scaled so that no
+  pixel has to give more than the input. ``Min input level`` (default 0.2: the transmission needed is at most 5 times
+  the one at the peak of the beam, a lower level leaves little to the centre) is the fraction of the maximum of the
+  input amplitude below which the target cannot be obtained: this *unreachable* region is off (null transmission). For
+  *Superpixel* the input is averaged over each superpixel. 4f setups: the magnification only changes the axes, the
+  arrays keep their shape.
+
+The unreachable region is outlined in red, **as soon as the compensation is chosen** and without running the algorithm,
+on the input and target loaders and on the target views; after a run also on the modulator and output views of the
+extension. It is in the ``unreachable`` data of the algorithm and its fraction of the target is
+``unreachable_fraction``. In a script, ``set_compensation(app, 'DivideByInput', {'min_input_level': 0.3})`` of
+``headless_algorithms`` chooses the compensation and ``algo.preview_unreachable()`` gives the region.
+
+A compensation is a class of the package ``algorithms/compensations``, registered with
+``CompensationFactory.register_compensation()``, with its own ``params``, like an initial phase: another type (for
+instance for a 2f setup) is added by writing one more module. An algorithm that uses it sets ``INPUT_COMPENSATION`` to the name of its
+default compensation (``'DivideByInput'`` for the algorithms above, ``None`` for an algorithm that does not use one: the
+group is then hidden) and calls ``self.compensate_target(amplitude)``.

{pymodaq_plugins_beam_shaping-5.3.1 → pymodaq_plugins_beam_shaping-5.3.2}/docs/src/user_guide/algorithms.rst

@@ -36,7 +36,7 @@ BeamShaping itself, then the ones provided by other installed packages (see :doc
      - Amplitude images with a phase-only modulator and a filter in the Fourier plane, several diffractive models
        (:cite:t:`Clark2016`).
    * - Direct diffractive modulation
-     - OL2014 - Amplitude/Phase Checkerboard
+     - OL2014 - Amplitude-Phase Checkerboard
      - 4f
      - ❌
      - ✅
@@ -257,7 +257,7 @@ shaping for the MRAF algorithm using different initial phase type and mixing par
 
 .. note::
    The metrics (NRMSE, Fidelity, Efficiency) are **automatically saved** in the ``.h5beam`` file under
-   ``/RawData/Algorithm/``. See :ref:`h5beam-structure` for details.
+   ``/RawData/Shaping/Final/``. See :ref:`h5beam-structure` for details.
 
 Algorithms provided by other packages
 -------------------------------------
@@ -283,19 +283,31 @@ cells one after the other, editing the settings on the way:
   target by default. Each field is plotted once loaded (the target with the axes of the modulator plane, the algorithm
   scales it to the target plane: ``pg.plot_field(pg.get_target_field(algo))`` shows it after the next cell);
 * *Algorithm*: ``ALGORITHM`` and ``ALGORITHM_PARAMS``, the name of the algorithm as shown in the extension and the
-  values of its parameters, given by name (``'carrier_factor'``), with dots for parameters in a group
-  (``'phase.load'``). An unknown name raises an error listing the possible ones. ``N_ITERATIONS`` completes the run, and
+  values of its parameters, given by name (``'carrier_factor'``), with ``/`` for parameters in a group
+  (``'phase/load'``). An unknown name raises an error listing the possible ones. ``N_ITERATIONS`` completes the run, and
   ``INITIAL_PHASE`` / ``INITIAL_PHASE_PARAMS`` give the initial phase as chosen in the extension, from the initial
   phases factory (``'FlatPhase'``, ``'RandomPhase'``, ``'QuadraticPhase'``...) with its parameters, or a 2D array of the
   shape of the fields;
 * *Snap*: ``pg.snap`` runs one step of the algorithm without any mask and plots the intermediate plane of 4f setups
   (intensity in log scale), to see where the mask has to be placed;
 * *Masks*: set ``APPLY_TARGET_MASK`` or ``APPLY_INTERMEDIATE_MASK`` to ``True`` to apply a mask (algorithms such as
-  *Binary Threshold*, *Parallel Lee* and *Superpixel* need the one of the intermediate plane), its region being given in um around the center of the field (``None``: the default region
+  *Binary Threshold*, *Parallel Lee* and *Superpixel* need the one of the intermediate plane), its region being given in um as the slices shown by the extension, in its frame (the origin is the corner of the field), along y then along x, that can be pasted as is (``(slice(1073, 5365, None), slice(1073, 5365, None))``, as text or not; ``((1073, 5365), (1073, 5365))`` is accepted too) (``None``: the default region
   of the extension, centered and covering 2/3 of the effective area of the SLM in the plane, printed to be edited). The cell
   draws the outline of the intermediate mask on the plot of the snap, which is updated (not created again): run it
   again until the mask is right.
 
+The *Run* cell can save the output of each iteration: ``SAVE_FIELDS`` (``True`` for all the fields, the amplitude and
+phase of the output and modulator planes and the intensity of the intermediate one, or the names of some of them such
+as ``('modulator/phase',)``) and ``SAVE_METRICS``, both off by default. ``SAVE_FINAL`` saves once, at the end of the run, all the fields and the metrics of the last iteration, as the *Save* action of the extension does, whatever is saved at each iteration. The format is the one of the continuous saving
+of the extension: a group ``/RawData/ShapingXXX`` per run, with the settings of the run, holding one sub group for each kind of data: ``Fields`` (the fields saved at each iteration) and ``Metrics`` (the metrics), each enlarged along its own ``step`` navigation axis, ``Final`` (the fields saved once at the end, without navigation axis, as in the extension's *Save*, whose main group is the same ``Shaping`` group, without index) and the ``Input`` and ``Target`` groups (the fields as used by the algorithm, with the settings of their loaders, as the *Input* and *Target* groups of the extension's *Save*, readable with the same function). The sub groups of the data per iteration and ``Final`` are only created if requested. The settings of the run are saved
+as in the extension: the name of the algorithm, the number of iterations, the initial phase
+and its parameters, the masks (applied or not, type and slices) and the parameters of the algorithm. ``SAVE_FILE`` gives the file (created if needed, the runs being added to it); with ``None``
+a file is created in the PyMoDAQ data folder at the first saved run and holds the next ones. Its path is printed (``algo.saved_h5file``).
+
+The script ``scripts/plot_convergence.py`` plots the convergence of the saved metrics (one panel per metric against the iteration) from the ``Metrics`` group of a saved run.
+
+During the run of an iterative algorithm, the index of the iteration and the metrics (fitness and efficiency) are printed after each iteration (``verbose=False`` in ``pg.run_algorithm`` to silence it).
+
 The last cells run the algorithm, plot an overview as in the extension, then the output field and the intermediate
 plane of 4f setups (its intensity in log scale), and give the results as ``Field`` objects. The overview shows the
 output, modulator and intermediate planes with their amplitude and phase, and the metrics: with ``'qt'`` a dock per field
@@ -331,3 +343,39 @@ version stays usable.
    The parameters of the algorithms are widgets, so a ``QApplication`` is needed. The helpers create it if there is none,
    no event loop is required. Matplotlib must be installed. The algorithm receives the same calls as in the extension
    through a minimal stand-in for it, but the script has not been tested on hardware.
+
+Running the same algorithm many times from a script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The cells of the script are thin wrappers around the helpers of ``headless_algorithms``, which can be called from your
+own script to run an algorithm many times with all the settings fixed but a few ones that change from one run to the
+next (a parameter, the seed of the random initial phase, the target...). The shaper and the fields are loaded once, and
+only the algorithm is created again for each run, which is cheap compared to an iteration (a few tens of ms against
+some hundreds of ms for a 1024 x 1024 shaper). Parameters are given as in the script, by name, with ``/`` for groups:
+
+.. code-block:: python
+
+   from pymodaq_plugins_beam_shaping.utilities import headless_algorithms as pg
+
+   # what stays fixed: loaded once
+   app = pg.HeadlessApp(pg.make_shaper())
+   input_field = pg.load_field('GaussianIntensity', {}, app)
+   target_field = pg.load_field('ImageFiles', {'phase/load': False}, app)
+   algo_class = pg.reload_algorithm('Gerchberg-Saxton')
+
+
+   def run(n_iterations=100, algo_params=None, ini_phase='RandomPhase', ini_phase_params=None, **saving):
+       """ One run with a new algorithm, only what is given differs from the defaults """
+       algo = pg.create_algorithm(algo_class, app, algo_params)
+       pg.set_fields(algo, input_field, target_field)
+       pg.run_algorithm(algo, n_iterations, ini_phase, ini_phase_params, **saving)
+       return algo
+
+
+   # what changes: here the seed of the random initial phase, one run per value
+   for seed in range(5):
+       algo = run(n_iterations=3, ini_phase_params=dict(fixed_seed=True, seed=seed))
+       print(f'seed {seed}: fitness = {algo.fitness:.4g}, efficiency = {algo.efficiency:.4g}')
+
+The saving options of ``pg.run_algorithm`` (``save_fields``, ``save_metrics``, ``h5file``) can be given to ``run``: with
+the same ``h5file`` all the runs are added to a single file, a group per run.

{pymodaq_plugins_beam_shaping-5.3.1 → pymodaq_plugins_beam_shaping-5.3.2}/docs/src/user_guide/corrections.rst

@@ -23,7 +23,9 @@ Phase Corrections
 =================
 
 A real setup often features optical aberrations deteriorating the calculated shaping. A correction module (and interface
-see :numref:`FIG-corrections`) is provided to add correction terms to the calculated modulator phase.
+see :numref:`FIG-corrections`) is provided to add correction terms to the calculated modulator phase. As they act on the phase, the corrections (and the :doc:`calibration <calibration>` of the
+phase) are only available, and their actions only shown, if the modulator of the shaper can modulate the phase (phase only
+or phase and amplitude), not for amplitude modulators such as DMDs.
 
 .. _sec-corrections-types:
 

{pymodaq_plugins_beam_shaping-5.3.1 → pymodaq_plugins_beam_shaping-5.3.2}/docs/src/user_guide/data_management.rst

@@ -113,6 +113,102 @@ The ``.h5field`` file has the following hierarchy:
 
 The ``.h5beam`` file has the following hierarchy:
 
+.. code-block:: text
+
+    /
+    ├── [Global Attributes]                     # Metadata (date, version, etc.)
+    │
+    └── RawData/ (GROUP)
+        ├── @settings: <binary>                # **Global configuration** (XML)
+        │                                      # Includes: wavelength, setup_type (2f/4f/no_lens),
+        │                                      # SLM settings, default loaders, etc.
+        │
+        ├── Shaping/ (GROUP)                   # **One group for the whole session** (no index)
+        │   ├── @settings: <binary>            # Algorithm name, run settings and algorithm settings (XML)
+        │   │
+        │   ├── Final/ (GROUP)                 # Algorithm results (last iteration)
+        │   │   ├── Data0D/CH00/Data00         # **NRMSE** (Normalized Root Mean Square Error)
+        │   │   │             Data01           # **Efficiency** (beam shaping efficiency)
+        │   │   └── Data2D/ (GROUP)
+        │   │       ├── CH00/                  # **Output Field Amplitude** (Axis00, Axis01: coordinates)
+        │   │       ├── CH01/                  # **Output Field Phase**
+        │   │       ├── CH02/                  # **Modulator Amplitude** (sent to SLM)
+        │   │       └── CH03/                  # **Modulator Phase** (sent to SLM)
+        │   │
+        │   ├── Input/ (GROUP)                 # **Input Field** (source beam)
+        │   │   ├── @settings: <binary>        # Loader app and loader settings (XML)
+        │   │   ├── Axis00, Axis01             # Coordinates (m)
+        │   │   ├── Data00 (CARRAY)            # Amplitude
+        │   │   └── Data01 (CARRAY)            # Phase
+        │   │
+        │   ├── Target/ (GROUP)                # **Target Field** (desired output), same content as Input
+        │   │
+        │   └── SLM/ (GROUP)                   # **SLM Phases**
+        │       └── Data2D/ (GROUP)            # Phases by channel
+        │           ├── CH00/                  # **Algorithm Phase** (to be applied to SLM), e.g. (540, 960)
+        │           ├── CH01/                  # **Quadratic Phase** (curvature correction)
+        │           ├── CH02/                  # **Linear Phase** (tilt correction)
+        │           └── CH03/                  # **Zernike Phase** (aberration correction)
+        │
+        └── Logger (VLARRAY)                   # Log messages (optional)
+
+.. list-table:: **Key Attributes in .h5field**
+   :header-rows: 1
+   :widths: 30 20 50
+   :class: longtable
+
+   * - **Location**
+     - **Attribute**
+     - **Description**
+   * - ``/``
+     - ``date``, ``time``
+     - File creation timestamp (format: ``YYYY-MM-DD``, ``HH:MM:SS.microseconds``).
+   * - ``/``
+     - ``pymodaq_version``, ``pymodaq_data_version``
+     - PyMoDAQ and pymodaq_data versions used to create the file.
+   * - ``/RawData/Field/Axis00``
+     - ``scaling``
+     - **Pixel size in meters** (e.g., ``6.494e-06`` for 6.494 µm/pixel).
+   * - ``/RawData/Field/Axis00``
+     - ``units``
+     - Physical unit for the axis (``"m"`` for meters).
+   * - ``/RawData/Field/Data00``
+     - ``label``
+     - **Data type** (``"Amplitude"`` or ``"Phase"``).
+   * - ``/RawData/Field/Data00``
+     - ``shape``
+     - Dimensions of the 2D array (e.g., ``(1024, 1024)``).
+   * - ``/RawData/Field``
+     - ``settings``
+     - **Serialized XML configuration** of the Field Loader (includes loader type, parameters, masking, etc.).
+
+.. note::
+   - The **amplitude** and **phase** are stored as **separate datasets** (``Data00`` and ``Data01``).
+   - The **physical coordinates** (in meters) are defined by ``Axis00`` (X) and ``Axis01`` (Y).
+   - The ``scaling`` attribute of each axis gives the **pixel pitch** in meters.
+
+---
+
+.. _h5beam-format:
+
+.h5beam Format
+~~~~~~~~~~~~~~
+
+**Purpose**: Store a **complete beam shaping session**, including:
+- Input and Target fields.
+- SLM phases (algorithm, quadratic, linear, Zernike).
+- Algorithm results (output field, modulator field, metrics).
+- Global configuration (wavelength, setup type, etc.).
+
+**Generated by**: Beam Shaping Extension.
+
+.. _h5beam-structure:
+
+**HDF5 Structure**
+""""""""""""""""""
+
+The ``.h5beam`` file has the following hierarchy:
+
 .. code-block:: text
 
     /
@@ -182,43 +278,45 @@ The ``.h5beam`` file has the following hierarchy:
    * - **Group**
      - **Purpose**
      - **Key Data**
-   * - ``/RawData/Input``
+   * - ``/RawData/Shaping/Input``
      - Source beam field
      - Amplitude + Phase (2D arrays)
-   * - ``/RawData/Target``
+   * - ``/RawData/Shaping/Target``
      - Desired output field
      - Amplitude + Phase (2D arrays)
-   * - ``/RawData/Algorithm/Data0D/CH00``
+   * - ``/RawData/Shaping/Final/Data0D/CH00``
      - **Performance metrics**
      - NRMSE (``Data00``), Efficiency (``Data01``)
-   * - ``/RawData/Algorithm/Data2D/CH00``
+   * - ``/RawData/Shaping/Final/Data2D/CH00``
      - **Output field amplitude**
      - 2D array (same size as Input/Target)
-   * - ``/RawData/Algorithm/Data2D/CH01``
+   * - ``/RawData/Shaping/Final/Data2D/CH01``
      - **Output field phase**
      - 2D array (radians)
-   * - ``/RawData/Algorithm/Data2D/CH02``
+   * - ``/RawData/Shaping/Final/Data2D/CH02``
      - **Modulator amplitude**
      - 2D array (sent to SLM)
-   * - ``/RawData/Algorithm/Data2D/CH03``
+   * - ``/RawData/Shaping/Final/Data2D/CH03``
      - **Modulator phase**
      - 2D array (radians)
-   * - ``/RawData/SLM/Data2D/CH00``
+   * - ``/RawData/Shaping/SLM/Data2D/CH00``
      - **Algorithm phase for SLM**
      - 2D array (shape matches SLM resolution, e.g., 540x960)
-   * - ``/RawData/SLM/Data2D/CH01``
+   * - ``/RawData/Shaping/SLM/Data2D/CH01``
      - **Quadratic phase correction**
      - 2D array
-   * - ``/RawData/SLM/Data2D/CH02``
+   * - ``/RawData/Shaping/SLM/Data2D/CH02``
      - **Linear phase correction**
      - 2D array
-   * - ``/RawData/SLM/Data2D/CH03``
+   * - ``/RawData/Shaping/SLM/Data2D/CH03``
      - **Zernike phase correction**
      - 2D array
 
 .. note::
-   - The **SLM phases** (``/RawData/SLM/Data2D/``) are **downsampled** to match the SLM resolution (e.g., 960x540 for PLUTO, 1024x768 for LC2012).
-   - The **Algorithm/Data2D** results are at the **same resolution as the Input/Target fields** (e.g., 1024x1024).
+   - The **SLM phases** (``/RawData/Shaping/SLM/Data2D/``) are **downsampled** to match the SLM resolution (e.g., 960x540 for PLUTO, 1024x768 for LC2012).
+   - The **Final/Data2D** results are at the **same resolution as the Input/Target fields** (e.g., 1024x1024).
+   - Files written before this layout (groups ``/RawData/Algorithm``, ``Input``, ``Target`` and ``SLM`` directly under ``/RawData``) are still loaded by the extension.
+   - Runs of the headless playground (``pg.run_algorithm``) use the same layout, in indexed groups ``/RawData/Shaping000``, ``Shaping001``... with in addition the ``Fields`` and ``Metrics`` groups holding the data saved at each iteration (see :ref:`sec-algorithms-playground`), the SLM group being left out.
    - The ``@settings`` attributes contain **serialized XML configurations** (can be deserialized with ``pymodaq_utils``).
 
 
@@ -235,7 +333,7 @@ You can **read `.h5beam` and `.h5field` files programmatically** using `pymodaq_
    # Load data from a .h5beam file
    with DataLoader("my_file.h5beam") as loader:
        # Access SLM phases
-       phase_data = loader.load_data("/RawData/SLM/Data2D/CH00")  # return a DataWithAxes object
+       phase_data = loader.load_data("/RawData/Shaping/SLM/Data2D/CH00")  # return a DataWithAxes object
 
        # Access metadata
        print(phase_data.extra_attributes)
@@ -333,30 +431,30 @@ HDF5 Attributes Reference
    * - **Group**
      - **Purpose**
      - **Key Data**
-   * - ``/RawData/Algorithm/Data0D/CH00``
+   * - ``/RawData/Shaping/Final/Data0D/CH00``
      - Performance metrics
      - NRMSE (``Data00``), Efficiency (``Data01``)
-   * - ``/RawData/Algorithm/Data2D/CH00``
+   * - ``/RawData/Shaping/Final/Data2D/CH00``
      - Output field amplitude
      - 2D array (same size as Input/Target)
-   * - ``/RawData/Algorithm/Data2D/CH01``
+   * - ``/RawData/Shaping/Final/Data2D/CH01``
      - Output field phase
      - 2D array (radians)
-   * - ``/RawData/Algorithm/Data2D/CH02``
+   * - ``/RawData/Shaping/Final/Data2D/CH02``
      - Modulator amplitude
      - 2D array (sent to SLM)
-   * - ``/RawData/Algorithm/Data2D/CH03``
+   * - ``/RawData/Shaping/Final/Data2D/CH03``
      - Modulator phase
      - 2D array (radians)
-   * - ``/RawData/SLM/Data2D/CH00``
+   * - ``/RawData/Shaping/SLM/Data2D/CH00``
      - Algorithm phase for SLM
      - 2D array (SLM resolution, e.g., 540x960)
-   * - ``/RawData/SLM/Data2D/CH01``
+   * - ``/RawData/Shaping/SLM/Data2D/CH01``
      - Quadratic phase
      - 2D array (curvature correction)
-   * - ``/RawData/SLM/Data2D/CH02``
+   * - ``/RawData/Shaping/SLM/Data2D/CH02``
      - Linear phase
      - 2D array (tilt correction)
-   * - ``/RawData/SLM/Data2D/CH03``
+   * - ``/RawData/Shaping/SLM/Data2D/CH03``
      - Zernike phase
      - 2D array (aberration correction)

{pymodaq_plugins_beam_shaping-5.3.1 → pymodaq_plugins_beam_shaping-5.3.2}/src/pymodaq_plugins_beam_shaping/__init__.py

@@ -11,6 +11,7 @@ config = Config()  # before field loader factory otherwise it will generate an e
 from .field import LoaderFactory, register_loaders
 from .algorithms.factory import AlgorithmFactory, register_algorithms
 from .algorithms.ini_phase import register_phases
+from .algorithms.compensation import register_compensations, CompensationFactory
 from .algorithms.stopping import register_stoppings
 
 logger = set_logger(get_module_name(__file__))
@@ -26,6 +27,12 @@ logger.info('Registering Optical Shaping ini phases')
 register_phases()
 logger.info('****************************************')
 
+logger.info('****************************************')
+logger.info('Registering Optical Shaping compensations of the input beam')
+register_compensations()
+CompensationFactory.check_enum()
+logger.info('****************************************')
+
 
 logger.info('****************************************')
 logger.info('Registering Optical Shaping stopping criteria')

{pymodaq_plugins_beam_shaping-5.3.1 → pymodaq_plugins_beam_shaping-5.3.2}/src/pymodaq_plugins_beam_shaping/algorithms/algo_base.py

@@ -16,6 +16,7 @@ from pymodaq_gui.managers.parameter_manager import ParameterManager
 from pymodaq_plugins_beam_shaping.algorithms.utils import (AlgoType, AlgoStatus, ApplyMaskTo,
                                                            LensSetup, CrossTalk, PhaseManipulation)
 from pymodaq_plugins_beam_shaping.field import Field
+from pymodaq_plugins_beam_shaping.algorithms.compensation import CompensationBase, Compensations
 from pymodaq_plugins_beam_shaping.utilities import sizing
 from pymodaq_plugins_beam_shaping.utilities.masking import MaskType
 
@@ -52,6 +53,8 @@ class AlgoBase(AlgoParameterManager, metaclass=ABCMeta):
     # the modulators the algorithm can compute a mask for (a shaper modulating both accepts any algorithm)
     MODULATOR_TYPES: tuple[ModulatorType] = (ModulatorType.PHASE, )
     INI_PHASE = True  # if True, the algorithm will init an initial phase
+    INPUT_COMPENSATION: Optional[Compensations] = None  # name of the compensation of the input beam the algorithm starts
+    # with (the app lets the user change it), None if the algorithm does not use one
     ITERATIVE = False
     MANUAL_LOOP = True
     RECOMPUTE_ON_CHANGE = False  # if True, the algorithm is run again when one of its settings changes
@@ -77,9 +80,15 @@ class AlgoBase(AlgoParameterManager, metaclass=ABCMeta):
         self._target_field = Field(amplitude=np.zeros(sizing.get_effective_needed_field_size(self.shaper)))
         self._input_field = Field(amplitude=np.zeros(sizing.get_effective_needed_field_size(self.shaper)))
         self.intermediate_field: Optional[Field] = None
+        self._unreachable_mask: Optional[np.ndarray] = None  # where the target cannot be reached, see subclasses
 
         self._modulator_field = Field(amplitude=np.zeros(sizing.get_effective_needed_field_size(self.shaper)))
         self._modulator_field.calibrate_axes(self._input_field.pixels_sizes)
+        # what has to be sent to the modulator: its phase (without any correction, added when sending) and its
+        # amplitude pattern (0 and 1 for a DMD). Not the modulator field, which contains the input beam
+        self._slm_field = Field('slm', amplitude=np.ones(self._modulator_field.shape),
+                                phase=np.zeros(self._modulator_field.shape),
+                                pixel_sizes=self._input_field.pixels_sizes)
         self._output_field = Field(amplitude=np.zeros(sizing.get_effective_needed_field_size(self.shaper)))
 
         self.update_mask = True
@@ -229,7 +238,89 @@ class AlgoBase(AlgoParameterManager, metaclass=ABCMeta):
             self.set_amplitude_in_modulator_plane(field.amplitude)
 
     def set_amplitude_in_modulator_plane(self, amplitude: np.ndarray):
-        self._modulator_field.amplitude = amplitude
+        """ Set the amplitude pattern of an amplitude modulator (0 and 1 for a DMD)
+
+        The pattern is what is sent to the modulator (see :attr:`slm_amplitude`) whereas the amplitude of the modulator
+        field, the field just after the modulator used to compute the output, is the input amplitude times the pattern
+        """
+        pattern = np.array(amplitude, dtype=float)
+        self._slm_field = Field('slm', amplitude=pattern,
+                                phase=self._slm_phase_or_zeros(pattern.shape),
+                                pixel_sizes=self._input_field.pixels_sizes)
+        self._modulator_field.amplitude = self._input_field.amplitude * pattern
+
+    def _slm_phase_or_zeros(self, shape) -> np.ndarray:
+        return self._slm_field.phase.copy() if self._slm_field.phase.shape == tuple(shape) else np.zeros(shape)
+
+    @property
+    def slm_field(self) -> Field:
+        """ The field to send to the modulator: the phase set by :meth:`set_phase_in_modulator_plane` (wrapped,
+        with crosstalk... but without any correction, added when sending) and the amplitude pattern set by
+        :meth:`set_amplitude_in_modulator_plane`, 1 everywhere if there is none. It is not the modulator field, the
+        field just after the modulator, which is the input field times the SLM field and is used to compute the
+        output"""
+        modulator_type = ModulatorType(self.shaper.modulator_type)
+        if modulator_type == ModulatorType.BOTH:
+            return self._slm_field
+        field = self._slm_field.deepcopy()
+        if modulator_type == ModulatorType.PHASE:  # nothing is shaped in amplitude
+            field.amplitude = np.ones(field.shape)
+        else:  # an amplitude modulator has no phase
+            field.phase = np.zeros(field.shape)
+        return field
+
+    @property
+    def slm_amplitude(self) -> np.ndarray:
+        """ The amplitude pattern to send to an amplitude modulator, without the input beam"""
+        return self.slm_field.amplitude
+
+    @property
+    def unreachable_mask(self) -> Optional[np.ndarray]:
+        """ Boolean array of the pixels where the target cannot be obtained (None: not computed)"""
+        return self._unreachable_mask
+
+    @property
+    def unreachable_fraction(self) -> float:
+        """ Fraction of the pixels asked by the target that cannot be obtained, see :attr:`unreachable_mask`"""
+        if self._unreachable_mask is None:
+            return 0.
+        asked = self._target_field.amplitude > 0
+        return float(np.sum(self._unreachable_mask & asked) / max(np.sum(asked), 1))
+
+    @property
+    def compensation(self) -> Optional[CompensationBase]:
+        """ The compensation of the input beam chosen in the app, None if this algorithm does not use one"""
+        if self.INPUT_COMPENSATION is None:
+            return None
+        compensation = getattr(self.parent_app, 'compensation', None)
+        if compensation is None:  # not chosen in an app: the default one of the algorithm
+            from pymodaq_plugins_beam_shaping.utilities.headless_algorithms import make_compensation
+            compensation = make_compensation(self.INPUT_COMPENSATION)
+        return compensation
+
+    @property
+    def input_block(self) -> int:
+        """ Size of the blocks of modulator pixels that see the same input amplitude (a superpixel), 1 if none"""
+        return 1
+
+    def compensate_target(self, target: np.ndarray) -> np.ndarray:
+        """ The amplitude to ask to the modulator to get the target, after the compensation of the input beam, and
+        the unreachable region it gives (:attr:`unreachable_mask`). The target itself if there is no compensation"""
+        compensation = self.compensation
+        if compensation is None:
+            self._unreachable_mask = None
+            return target
+        compensated, self._unreachable_mask = compensation.compensate(target, self._input_field.amplitude,
+                                                                      self.input_block)
+        return compensated
+
+    def preview_unreachable(self) -> Optional[np.ndarray]:
+        """ The unreachable region the next run will have, knowing the input beam and the compensation only (None:
+        no region)"""
+        compensation = self.compensation
+        if compensation is None or self._input_field is None or self._input_field.amplitude is None:
+            return None
+        return compensation.unreachable(self._input_field.amplitude, self.input_block)
 
     def set_phase_in_modulator_plane(self, phase: np.ndarray, induced_amplitude: np.ndarray = None):
         if phase.shape == self._modulator_field.shape:
@@ -243,6 +334,9 @@ class AlgoBase(AlgoParameterManager, metaclass=ABCMeta):
                 phase = gaussian_filter(phase, self.crosstalk.value)
 
             self._modulator_field.phase = phase
+            self._slm_field = Field('slm', amplitude=self._slm_field.amplitude if
+                                    self._slm_field.amplitude.shape == phase.shape else np.ones(phase.shape),
+                                    phase=phase, pixel_sizes=self._input_field.pixels_sizes)
             self._modulator_field.amplitude = (
                     self._input_field.amplitude.copy() *
                     (induced_amplitude if induced_amplitude is not None else 1))
@@ -305,12 +399,19 @@ class AlgoBase(AlgoParameterManager, metaclass=ABCMeta):
                     (self._target_field.phase[tuple(slices)]**2 - self._output_field.phase[tuple(slices)]**2) ** 2) /
                 np.sum(self._target_field.phase[tuple(slices)] ** 4)))
 
+    @property
+    def input_power(self) -> float:
+        """ The power incident on the modulator, the reference of the efficiency: the sum of the intensity of the input
+        field. To be subclassed if the algorithm models another illumination"""
+        return float(np.sum(self._input_field.intensity))
+
     @property
     def efficiency(self) -> float:
-        """ Compute efficiency as the ratio between output_field intensity within a given region
-        and total intensity
+        """ Compute the efficiency as the ratio between the output_field intensity within a given region (the target
+        mask if applied, else the whole field) and the power incident on the modulator, see :attr:`input_power`
 
-        Meaningfully only for algorithm using a Target defined mask
+        The losses of the setup are therefore counted: the ones of the modulator (the mirrors of a DMD that are off) and
+        the ones of the filter in the intermediate plane of a 4f setup, which the output field already went through.
 
         To be subclassed if the given implementation below is not correct for your algorithm"""
         if self.apply_mask(ApplyMaskTo.TARGET):
@@ -318,8 +419,7 @@ class AlgoBase(AlgoParameterManager, metaclass=ABCMeta):
         else:
             slices = (...,)
 
-        return (np.sum(self._output_field.intensity[tuple(slices)]) /
-                np.sum(self._output_field.intensity))
+        return float(np.sum(self._output_field.intensity[tuple(slices)]) / self.input_power)
 
     def fitness_as_dwa(self):
         return DataRaw('fitness', data=[np.array([self.fitness])],
@@ -358,6 +458,12 @@ class AlgoBase(AlgoParameterManager, metaclass=ABCMeta):
             self.modulator_field.amplitude_as_dwa('modulator'),
             self.modulator_field.phase_as_dwa('modulator'),
         ])
+        dte.append(self.slm_field.phase_as_dwa('slm'))  # what is sent to the modulator, whatever its type
+        if self.shaper.modulator_type != ModulatorType.PHASE:  # an amplitude is sent to the modulator
+            dte.append(self.slm_field.amplitude_as_dwa('slm'))
+        if self._unreachable_mask is not None:
+            dte.append(Field('unreachable', amplitude=self._unreachable_mask.astype(float),
+                             pixel_sizes=self._modulator_field.pixels_sizes).amplitude_as_dwa('unreachable'))
         if self.intermediate_field is not None:
             dte.append(self.intermediate_field.intensity_as_dwa('intermediate'))
         return dte