Merge branch 'refs/heads/further-revisions'

# Conflicts:
#	docs/source/development.rst

docs/source/conf.py

@@ -59,17 +59,16 @@
                 Wavefront shaping (WFS) is a technique for controlling the propagation of light.
                 With applications ranging from microscopy to free-space telecommunication, 
                 this research field is expanding rapidly. 
-                It stands out that many of the important breakthroughs are made by developing better software that
-                incorporates increasingly advanced physical models and algorithms.
-                Typical control software involves individual code for scanning microscopy, image processing, 
+                As the field advances, it stands out that many breakthroughs are driven by the development of better 
+                software that incorporates increasingly advanced physical models and algorithms.
+                Typical control software involves fragmented implementations for scanning microscopy, image processing, 
                 optimization algorithms, low-level hardware control, calibration and troubleshooting, 
                 and simulations for testing new algorithms. 
 
                 The complexity of the many different aspects of wavefront shaping software, however, 
-                is becoming a bottleneck for further developments in the field, as well as for end-user adoption.
-                OpenWFS addresses these challenges by providing a Python module that coherently integrates
-                all aspects of wavefront shaping code. The module is designed to be modular and easy to expand.
-                It incorporates elements for hardware control, software simulation, and automated troubleshooting. 
+                is becoming a limiting factor for further developments in the field, as well as for end-user adoption.
+                OpenWFS addresses these challenges by providing a modular and extensible Python library that 
+                incorporates elements for hardware control, software simulation, and automated troubleshooting. 
                 Using these elements, the actual wavefront shaping algorithm and its automated tests can be written
                 in just a few lines of code.
             }

docs/source/core.rst

@@ -71,10 +71,9 @@ Processors
 ------------
 A `Processor` is a `Detector` that takes input from one or more other detectors, and combines/processes this data. We already encountered an example in :numref:`Getting started`, where the `SingleRoiProcessor` was used to average the data from a camera over a region of interest. A block diagram of the data flow of this code is shown in :numref:`hellowfsdiagram`. Since a processor, itself, is a `Detector`, multiple processors can be chained together to combine their functionality. The OpenWFS further includes various processors, such as a `CropProcessor` to crop data to a rectangular region of interest, and a `TransformProcessor` to perform affine image transformations to image produced by a source.
 
-
 Actuators
 ---------
-Actuators are devices that *move* things in the setup. This can be literal, such as moving a translation stage, or a virtual movement, like an SLM that takes time to switch to a different phase pattern. All actuators and derive from the common :class:`.Actuator` base class. Actuators have no additional methods or properties other than those in the :class:`.Device` base class.
+Actuators are devices that *move* things in the setup. This can be literal, such as moving a translation stage, or a virtual movement, like an SLM that takes time to switch to a different phase pattern. All actuators are derived from the common :class:`.Actuator` base class. Actuators have no additional methods or properties other than those in the :class:`.Device` base class.
 
 Units and metadata
 ----------------------------------
@@ -140,4 +139,74 @@ This synchronization is performed automatically. If desired, it is possible to e
 
 Finally, devices have a `timeout` attribute, which is the maximum time to wait for a device to become ready. This timeout is used in the state-switching mechanism, and when explicitly waiting for results using :meth:`~.Device.wait()` or  :meth:`~.Device.read()`.
 
-
+Currently available devices
+----------------------------
+
+The following devices are currently implemented in OpenWFS:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Device Name
+     - Device Type
+     - Description
+   * - Camera
+     - Detector
+     - Adapter for GenICam/GenTL cameras
+   * - ScanningMicroscope
+     - Detector
+     - Laser scanning microscope using galvo mirrors and NI DAQ
+   * - StaticSource
+     - Detector
+     - Returns pre-set data, simulating a static source
+   * - NoiseSource
+     - Detector
+     - Generates uniform or Gaussian noise as a source
+   * - SingleRoi
+     - Processor (Detector)
+     - Averages signal over a single ROI
+   * - MultipleRoi
+     - Processor (Detector)
+     - Averages signals over multiple regions of interest (ROIs)
+   * - CropProcessor
+     - Processor (Detector)
+     - Crops data from the source to a region of interest
+   * - TransformProcessor
+     - Processor (Detector)
+     - Performs affine transformations on the source data
+   * - ADCProcessor
+     - Processor (Detector)
+     - Simulates an analog-digital converter
+   * - SimulatedWFS
+     - Processor
+     - Simulates wavefront shaping experiment using Fourier transform-based intensity computation at the focal plane
+   * - Gain
+     - Actuator
+     - Controls PMT gain voltage using NI data acquisition card
+   * - PhaseSLM
+     - Actuator
+     - Simulates a phase-only spatial light modulator
+   * - SLM
+     - Actuator
+     - Controls and renders patterns on a Spatial Light Modulator (SLM) using OpenGL
+
+Available Algorithms
+---------------------
+
+The following algorithms are available in OpenWFS for wavefront shaping:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Algorithm Name
+     - Description
+   * - FourierDualReference
+     - A Fourier dual reference algorithm that uses plane waves from a disk in k-space for wavefront shaping :cite:`Mastiani2022`.
+   * - IterativeDualReference
+     - A generic iterative dual reference algorithm with the ability to use custom basis functions for non-linear feedback applications.
+   * - DualReference
+     - A generic dual reference algorithm with the option for optimized reference, suitable for multi-target optimization and iterative feedback.
+   * - SimpleGenetic
+     - A simple genetic algorithm that optimizes wavefronts by selecting elite individuals and introducing mutations for focusing through scattering media :cite:`Piestun2012`.
+   * - StepwiseSequential
+     - A stepwise sequential algorithm which systematically modifies the phase pattern of each SLM element :cite:`Vellekoop2007`.

docs/source/development.rst

@@ -48,6 +48,11 @@ Reporting bugs and contributing
 --------------------------------------------------
 Bugs can be reported through the GitHub issue tracking system. Better than reporting bugs, we encourage users to *contribute bug fixes, new algorithms, device drivers, and other improvements*. These contributions can be made in the form of a pull request :cite:`zandonellaMassiddaOpenScience2022`, which will be reviewed by the development team and integrated into the package when appropriate. Please contact the current development team through GitHub :cite:`openwfsgithub` to coordinate such contributions.
 
+Implementing new algorithms
+--------------------------------------------------
+To implement a new algorithm, the currently existing algorithms can be consulted for a few examples.
+Essentially, the algorithm needs to have an execute method, which needs to produce a WFSResult. With OpenWFS, all hardware interactions are abstracted away. Using `slm.set_phases` and `feedback.trigger` the algorithm can be naive to specific hardware. During the execution, different modes are measured, and a transmission matrix is calculated or approached. For most of our algorithms, the same algorithm can be used to analyze a phase stepping experiment. In order to show the versatility of this platform, we implemented the genetic algorithm described in :cite:`Piestun2012` and more recently adapted for a GUI in :cite:`Anderson2024`.
+
 
 Implementing new devices
 --------------------------------------------------
@@ -70,7 +75,7 @@ If the detector is created with the flag ``multi_threaded = True``, then `_fetch
 
 Implementing a processor
 ++++++++++++++++++++++++++++++++++
-To implement a data processing step that dynamically processes date from one or more input detectors, implement a custom processor. This is done by deriving from the `Processor` base class and implementing the `__init__` function. This function should pass a list of all upstream nodes, i.e. all detectors which provide the input signals to the processor, the base class constructor. In addition, the :meth"`~Detector._fetch()` method should be implemented to process the data. The framework will wait until the data from all sources is available, and calls `_fetch()` with this data as input. See the implementation of :class:`~.Shutter` or any other processor for an example of how to implement this function.
+To implement a data processing step that dynamically processes data from one or more input detectors, implement a custom processor. This is done by deriving from the `Processor` base class and implementing the `__init__` function. This function should pass a list of all upstream nodes, i.e. all detectors which provide the input signals to the processor, the base class constructor. In addition, the :meth"`~Detector._fetch()` method should be implemented to process the data. The framework will wait until the data from all sources is available, and calls `_fetch()` with this data as input. See the implementation of :class:`~.Shutter` or any other processor for an example of how to implement this function.
 
 Implementing an actuator
 +++++++++++++++++++++++++++++++

docs/source/index.rst

@@ -10,5 +10,6 @@ OpenWFS - a library for conducting and simulating wavefront shaping experiments
     slms
     simulations
     development
+    pydevice
     api
     auto_examples/index

docs/source/index_latex.rst

@@ -9,6 +9,7 @@ OpenWFS - a library for conducting and simulating wavefront shaping experiments
     core
     slms
     simulations
+    pydevice
     development
     conclusion
 

docs/source/pydevice.rst

@@ -0,0 +1,6 @@
+.. _section-pydevice:
+
+OpenWFS in PyDevice
+==============================================
+
+To smoothly enable end-user interaction with wavefront shaping algorithms, the Micro-Manager device adapter PyDevice was developed :cite:`PyDevice`. A more detailed description can be found in the mmCoreAndDevices source tree :cite:`mmCoreAndDevices`. In essence, PyDevice is Micro-Manager adapter that imports objects from a Python script and integrates them as devices, e.g. a camera or stage. OpenWFS was written in compliance with the templates required for PyDevice, which means OpenWFS cameras, scanners and algorithms can be loaded into Micro-Manager as devices. Examples of this are found in the example gallery :cite:`readthedocsOpenWFS`. Further developments due to this seamless connection can be a dedicated Micro-Manager based wavefront shaping GUI.