Merge remote-tracking branch 'origin/master'

.github/workflows/pytest.yml

@@ -26,7 +26,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          poetry install --with dev
+          poetry install --with dev --extras all
 
       - name: Run tests
         run: |

.github/workflows/testpypi.yml

@@ -9,11 +9,11 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+
     environment:
       name: testpypi
       url: https://test.pypi.org/p/openwfs
-
-    # enable openid authentication for PyPi
+
     permissions:
       id-token: write  # Required for OIDC
 
@@ -50,4 +50,5 @@ jobs:
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
         repository-url: https://test.pypi.org/legacy/
+        verbose: true
 

.gitignore

@@ -7,6 +7,7 @@ __pycache__
 auto_examples
 build
 _build
+requirements.txt
 .vs
 .bak
 PyDevice.sln

.readthedocs.yaml

@@ -1,4 +1,4 @@
-version: "2"
+version: 2
 
 build:
   os: "ubuntu-22.04"
@@ -7,9 +7,11 @@ build:
 
   jobs:
     post_create_environment:
+      - pip install --upgrade pip
       - pip install poetry
       - pip install poetry-plugin-export
-      - poetry export -f requirements.txt -o requirements.txt --with docs --without opengl
+      - poetry config warnings.export false
+      - poetry export -f requirements.txt -o requirements.txt --with docs --extras "all"
       - cat requirements.txt
 
 python:

STYLEGUIDE.md

@@ -6,8 +6,45 @@
 
 # General
 
-- The package `black` is used to ensure correct formatting. Install with `pip install black` and run in the terminal using `black .` when located at the root of the repository. 
+- The package `black` is used to ensure correct formatting.
+  When using PyCharm, just install black through the settings dialog.
+- PyCharm warnings and errors should be fixed. Exceptions:
+    - PEP 8: E501 line too long. May be disabled. This is already checked by black. For docstrings, keeping a string
+      line limit can be very cumbersome.
+    - PEP 8:E203 whitespace before ':'. May be disabled. This is already checked by (and conflicts with) black.
+
+# Layout
+
+- Line length of code is limited to 120 characters by `black`.
+- Use soft wrapping for Markdown (`.md`) and reStructuredTest (`.rst`) files.
 
 # Tests
 
-- Tests must *not* plot figures.
+- Tests must *not* plot figures.
+
+# Sphinx
+
+Common warnings:
+
+- All line numbers are relative to the start of the docstring.
+- 'WARNING: Block quote ends without a blank line; unexpected unindent'. This happens if a block of text is not properly
+  wrapped and one of the lines starts with a space. To fox, remove the space at the beginning of the line.
+- 'ERROR: Unexpected indentation' can be caused if a line ends with ':' and the next line is not indented or empty.
+
+# Indexing
+
+- For 2-D data, the first index is the row, the second index is the column.
+- Multi-dimensional data sets should be indexed such that the first index corresponds
+  to the slowest changing dimension, and the last index corresponds to the fastest changing dimension. For example, a
+  sequence of camera frames should be indexed as `frames[frame_index, row, column]`.
+- If you find yourself needing to index a 3D array with `array[:, :, 0]`, using a lot of `expand_dims` or `reshape`
+  commands, this is an indication that the indexing is not optimal, both in terms of performance and readability.
+- Don't use ``[i,...]`` for indexing, use ``[i]`` instead.
+- Prefer ``len(x)`` over ``x.shape(0)`` if the leading dimension represents a different 'type'. So, for a list of
+  images, use ``len(images)`` instead of ``images.shape(0)``. But to access the number of rows in an image, use
+  ``image.shape(0)``.
+
+  # Properties
+- Document properties in the getter method only, not in the setter method. Also describe what happens if the property is
+  set.
+- 

docs/source/conclusion.rst

@@ -5,7 +5,7 @@ In this work we presented an open-source Python package for conducting and simul
 
 OpenWFS incorporates features to reduce the chances of errors in the design of wavefront shaping code. Notably, the use of units of measure prevents the accidental mixing of units, and the automatic synchronization mechanism ensures that hardware is properly synchronized without the need to write any synchronization code. Finally, the ability to simulate full experiments, and to mock individual components, allows the user to test wavefront shaping algorithms without the need for physical hardware. We find this feature particularly useful since there is a lot that can go wrong in an experiment, (also see :cite:`Mastiani2024PracticalConsiderations`), and experimental issues and software issues are not always easy to distinguish. With OpenWFS, it is now possible to fully test the algorithms before entering the lab, which can save a lot of time and frustration.
 
-We envision that OpenWFS will hold a growing collection of components for hardware control, advanced simulations, and wavefront shaping. The standardised interfaces for detectors, actuators and SLMs, enables the cooperative development of complex functionality. Additionally, standardized components and algorithms will greatly simplify developing reusable code that can be used across different setups and experiments. The simulation tools may additionally be used for research and education, ushering in a new phase of applications in wavefront shaping. We therefore encourage the reader to join us in developing new algorithms and components for this framework.
+We envision that OpenWFS will hold a growing collection of components for hardware control, advanced simulations, and wavefront shaping. Further expansion of the supported hardware is of high priority, especially wrapping c-based libraries and adding support for  Micro-Manager device adapters. The standardised interfaces for detectors, actuators and SLMs will greatly simplify developing reusable code that can be used across different setups and experiments. The simulation tools may additionally be used for research and education, ushering in a new phase of applications in wavefront shaping. We therefore encourage the reader to join us in developing new algorithms and components for this framework.
 
 Code availability
 ------------------------------------------------

docs/source/conf.py

@@ -43,13 +43,16 @@
 latex_elements = {
     "preamble": r"""
         \usepackage{authblk}
+        \usepackage{etoolbox}        % Reduce font size for all tables
+        \AtBeginEnvironment{tabular}{\small}
      """,
     "maketitle": r"""
         \author[1]{Daniël~W.~S.~Cox}
         \author[1]{Tom~Knop}
         \author[1,2]{Harish~Sasikumar}
         \author[1]{Ivo~M.~Vellekoop} 
-        \affil[1]{University of Twente, Biomedical Photonic Imaging, TechMed Institute, P. O. Box 217, 7500 AE Enschede, The Netherlands}
+        \affil[1]{University of Twente, Biomedical Photonic Imaging, TechMed Institute, P. O. Box 217,
+         7500 AE Enschede, The Netherlands}
         \affil[2]{Imec (Netherlands), Holst Centre (HTC-31), 5656 AE, Eindhoven, The Netherlands}
         \publishers{%
             \normalfont\normalsize%
@@ -58,19 +61,23 @@
                 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, 
-                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. 
-                Using these elements, the actual wavefront shaping algorithm and its automated tests can be written
-                in just a few lines of code.
+                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 WFS software involves a complex combination of low-level hardware control, signal processing, 
+                calibration, troubleshooting, simulation, and the wavefront shaping algorithm itself.
+                This complexity makes it hard to compare different algorithms and to extend existing software with new
+                hardware or algorithms. Moreover, the complexity of the software can be a significant barrier for end
+                users of microscopes to adopt wavefront shaping.
+
+                OpenWFS addresses these challenges by providing a modular Python library that 
+                separates hardware control from the wavefront shaping algorithm itself. 
+                Using these elements, a wavefront shaping algorithm can be written
+                in a minimal amount of code, with OpenWFS taking care of low-level hardware control, synchronization,
+                and troubleshooting. Algorithms can be used on different hardware or in a completely
+                simulated environment without changing the code. Moreover, we provide full integration with
+                the \textmu Manager microscope control software, enabling wavefront shaping experiments to be
+                executed from a user-friendly graphical user interface. 
             }
         }
         \maketitle
@@ -128,11 +135,11 @@
 autodoc_mock_imports = ["PyOpenGL", "OpenGL"]
 
 
-## Hide some classes that are not production ready yet
-def skip(app, what, name, obj, skip, options):
-    if name in ("WFSController", "Gain"):
+# Hide some classes that are not production ready yet
+def skip(_app, _what, name, _obj, do_skip, _options):
+    if name in ("Gain"):
         return True
-    return skip
+    return do_skip
 
 
 def visit_citation(self, node):
@@ -141,7 +148,7 @@ def visit_citation(self, node):
     self.add(f'<a name="{id}"></a>')
 
 
-def visit_label(self, node):
+def visit_label(_self, _node):
     """Patch-in function for markdown builder to support citations."""
     pass