opticalib 2.0.0__tar.gz → 2.2.0__tar.gz

opticalib-2.2.0/CITATION.bib

@@ -0,0 +1,10 @@
+@misc{opticalib, 
+    doi = {10.20371/INAF/SW/2026_00013}, 
+    url = {https://openscience.inaf.it/?page_id=696}, 
+    author = {{Pietro Ferraiuolo} and {Marco Xompero} and {Runa Briguglio} and {Matteo Menessini}}, 
+    language = {en}, 
+    title = {OPTICALIB: A Python Framework for Adaptive Optics Experimentation}, 
+    publisher = {O.A. Arcetri}, 
+    year = {2025}, 
+    copyright = {MIT License}
+}

{opticalib-2.0.0 → opticalib-2.2.0}/MANIFEST.in

@@ -1,7 +1,9 @@
 include README.md
-include requirements.txt
+include LICENSE
+include CITATION.bib
 include opticalib/core/_configurations/configuration.yaml
-include setup_calpy.py
-include opticalib/__init_script__/initCalpy.py
 include opticalib/simulator/_API/alpao_conf.yaml
-recursive-include labott *.py
+include opticalib/__init_script__/initCalpy.py
+recursive-include opticalib/gui/resources *.svg *.png *.ico
+graft tests
+global-exclude __pycache__ *.py[cod]

{opticalib-2.0.0/opticalib.egg-info → opticalib-2.2.0}/PKG-INFO

@@ -1,15 +1,17 @@
 Metadata-Version: 2.4
 Name: opticalib
-Version: 2.0.0
+Version: 2.2.0
 Summary: This package is a python interface for laboratory adaptive optics systems, with a focus on the calibration of deformable mirrors (DMs) and the acquisition of wavefront data using wavefront sensors.
-Home-page: https://github.com/ArcetriAdaptiveOptics/opticalib
-Author: Adaptive Optics Group - INAF - Osservatorio Astrofisico di Arcetri
-Author-email: pietro.ferraiuolo@inaf.it
-Maintainer: Pietro Ferraiuolo
-License: MIT License
+Author-email: Adaptive Optics Group - INAF - Osservatorio Astrofisico di Arcetri <pietro.ferraiuolo@inaf.it>
+Maintainer-email: Pietro Ferraiuolo <pietro.ferraiuolo@inaf.it>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ArcetriAdaptiveOptics/opticalib
+Project-URL: Repository, https://github.com/ArcetriAdaptiveOptics/opticalib
+Project-URL: Issues, https://github.com/ArcetriAdaptiveOptics/opticalib/issues
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: Unix
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -22,31 +24,43 @@ Requires-Dist: pipython
 Requires-Dist: photutils
 Requires-Dist: scipy
 Requires-Dist: ruamel.yaml
+Requires-Dist: PyYAML
 Requires-Dist: Pyro4
 Requires-Dist: h5py
 Requires-Dist: jdcal
 Requires-Dist: tqdm
 Requires-Dist: matplotlib
-Requires-Dist: xupy
 Requires-Dist: numpy
-Requires-Dist: PyQt5
-Requires-Dist: qtconsole
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
+Requires-Dist: rbfgpu
+Requires-Dist: xupy>=2.0
+Requires-Dist: ipython
+Provides-Extra: gui
+Requires-Dist: PySide6-Essentials; extra == "gui"
+Requires-Dist: QtPy; extra == "gui"
+Requires-Dist: qtconsole; extra == "gui"
+Requires-Dist: ipykernel; extra == "gui"
+Requires-Dist: jupyter_client; extra == "gui"
+Requires-Dist: pyqtgraph; extra == "gui"
+Requires-Dist: qtawesome; extra == "gui"
+Requires-Dist: psutil; extra == "gui"
+Provides-Extra: cuda12
+Requires-Dist: xupy[cuda12]>=2.0; extra == "cuda12"
+Provides-Extra: cuda13
+Requires-Dist: xupy[cuda13]>=2.0; extra == "cuda13"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: dev
+Requires-Dist: opticalib[gui,test]; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
 Dynamic: license-file
-Dynamic: maintainer
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 # OptiCalib : python framework for OPTical CALibration of deformable mirrors and AO experimentation
 
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ArcetriAdaptiveOptics/opticalib/tests.yml)
+[![PyPI version](https://img.shields.io/pypi/v/opticalib.svg)](https://pypi.org/project/opticalib/)
+[![Python versions](https://img.shields.io/pypi/pyversions/opticalib.svg)](https://pypi.org/project/opticalib/)
+[![License: MIT](https://img.shields.io/pypi/l/opticalib.svg)](LICENSE)
 
 `Adaptive Optics Group, INAF - Osservatorio Astrofisico di Arcetri`
 
@@ -78,6 +92,14 @@ The latests, stable, version can be installed from pypi:
 pip install opticalib
 ```
 
+The base install contains everything needed to talk to the hardware, run the simulators and the calibration routines, and use the `calpy` shell. Two optional extras add the rest:
+
+```bash
+pip install "opticalib[gui]"      # the graphical interface (calpy --gui / OptiCalib)
+pip install "opticalib[cuda13]"   # GPU backend (CuPy, via xupy); use cuda12 for CUDA 12.x
+pip install "opticalib[gui,cuda13]"  # extras can be combined
+```
+
 The in-development version can be installed directly from this repository:
 
 ```bash
@@ -113,7 +135,7 @@ dm = opt.AlpaoDm(820)       # set in the configuration file
 # an Influence Function by just doing
 
 tn = dmutils.iff_module.iffDataAcquisition(dm, interf) # Optional paramenters
-# are `modesList, modesAmplitude, template`, which if not specified are 
+# are `modeslist, modesAmplitude, template`, which if not specified are 
 # read from the configuration file
 ```
 

{opticalib-2.0.0 → opticalib-2.2.0}/README.md

@@ -1,6 +1,9 @@
 # OptiCalib : python framework for OPTical CALibration of deformable mirrors and AO experimentation
 
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ArcetriAdaptiveOptics/opticalib/tests.yml)
+[![PyPI version](https://img.shields.io/pypi/v/opticalib.svg)](https://pypi.org/project/opticalib/)
+[![Python versions](https://img.shields.io/pypi/pyversions/opticalib.svg)](https://pypi.org/project/opticalib/)
+[![License: MIT](https://img.shields.io/pypi/l/opticalib.svg)](LICENSE)
 
 `Adaptive Optics Group, INAF - Osservatorio Astrofisico di Arcetri`
 
@@ -32,6 +35,14 @@ The latests, stable, version can be installed from pypi:
 pip install opticalib
 ```
 
+The base install contains everything needed to talk to the hardware, run the simulators and the calibration routines, and use the `calpy` shell. Two optional extras add the rest:
+
+```bash
+pip install "opticalib[gui]"      # the graphical interface (calpy --gui / OptiCalib)
+pip install "opticalib[cuda13]"   # GPU backend (CuPy, via xupy); use cuda12 for CUDA 12.x
+pip install "opticalib[gui,cuda13]"  # extras can be combined
+```
+
 The in-development version can be installed directly from this repository:
 
 ```bash
@@ -67,7 +78,7 @@ dm = opt.AlpaoDm(820)       # set in the configuration file
 # an Influence Function by just doing
 
 tn = dmutils.iff_module.iffDataAcquisition(dm, interf) # Optional paramenters
-# are `modesList, modesAmplitude, template`, which if not specified are 
+# are `modeslist, modesAmplitude, template`, which if not specified are 
 # read from the configuration file
 ```
 

{opticalib-2.0.0 → opticalib-2.2.0}/opticalib/__init__.py

@@ -5,20 +5,15 @@ OPTICALIB: adaptive OPTIcs package for dm CALIBration
 Author(s)
 ---------
 - Pietro Ferraiuolo : pietro.ferraiuolo@inaf.it
+- Runa Briguglio: runa.briguglio@inaf.it
+- Marco Xompero: marco.xompero@inaf.it
+- Matteo Menessini: matteo.menessini@inaf.it
 
 Description
 -----------
-`opticalib` is a package for the control of laboratory instrumentations, like
+OptiCalib is a package for the control of laboratory instrumentations, like
 Interferometers and Deformable Mirrors. It also provides tools for the
 analysis of wavefronts and images.
-
-How to Use:
------------
-```python
-> import opticalib
-> interf = opticalib.PhaseCam('193.206.155.218', 8011)
-> img = interf.acquire_map()
-```
 """
 
 from __future__ import annotations
@@ -34,13 +29,6 @@ from .core.root import (
 from .core import config
 from .core import _types as typings
 from .core.fitsarray import fits_array
-from .devices import *
-from .devices.interferometer import _4DInterferometer
-
-get_camera_settings = _4DInterferometer.get_camera_settings
-get_frame_rate = _4DInterferometer.get_frame_rate
-
-del _4DInterferometer
 
 from . import (
     analyzer,
@@ -51,6 +39,14 @@ from . import (
     visualization,
 )
 
+from .devices.interferometer import _4DInterferometer
+
+get_camera_settings = _4DInterferometer.get_camera_settings
+get_frame_rate = _4DInterferometer.get_frame_rate
+del _4DInterferometer
+
+from .devices import *
+
 vis = visualization
 
 __all__ = [

{opticalib-2.0.0 → opticalib-2.2.0}/opticalib/__version__.py

@@ -9,7 +9,7 @@ Pietro Ferraiuolo
 __title__ = "opticalib"
 __long_title__ = "OPTICALIB : python framework for OPTIcal CALIBration of deformable mirrors and adaptive optics experimentation"
 __description__ = "This package is a python interface for laboratory adaptive optics systems, with a focus on the calibration of deformable mirrors (DMs) and the acquisition of wavefront data using wavefront sensors."
-__version__ = "2.0.0"
+__version__ = "2.2.0"
 __author__ = "Adaptive Optics Group - INAF - Osservatorio Astrofisico di Arcetri"
 __maintainer__ = "Pietro Ferraiuolo"
 __author_email__ = "pietro.ferraiuolo@inaf.it"

opticalib-2.2.0/opticalib/analyzer/__init__.py

@@ -0,0 +1,13 @@
+from .image_processing import *
+from .signals import *
+from .timeseries import *
+
+
+def _get_safe_interf_fullframe():
+    from ..devices.interferometer import _4DInterferometer
+
+    func = _4DInterferometer.into_full_frame
+    return func
+
+
+into_4d_full_frame = _get_safe_interf_fullframe()

{opticalib-2.0.0 → opticalib-2.2.0}/opticalib/analyzer/image_processing.py

@@ -1,21 +1,14 @@
 """
-Module: images_processing
-=========================
+Analyzer — offline image, cube and signal processing
+=====================================================
 
-Author(s)
----------
-- Pietro Ferraiuolo
+Offline analysis of acquired data: single-frame reduction, cube-level
+processing (push-pull, rebin, piston unwrap), spectral analysis (PSD,
+periodograms, Fourier filtering) and time-series diagnostics.
 
-Description
------------
+These are pure functions — they take arrays in and give arrays (or
+numbers) out, with no device access and no persisted state.
 
-This module provides utilities to process masked optical phase maps and
-image cubes, including piston unwrapping, push-pull reduction, rebinning,
-Zernike-mode removal, Fourier-domain filtering, and power spectral density
-analysis.
-
-The functions are designed to operate on Opticalib typing aliases and
-``fitsarray``-compatible masked arrays used across the analysis pipeline.
 """
 
 import xupy as _xp
@@ -27,6 +20,38 @@ from ..ground import osutils as osu, modal_decomposer as _md
 from scipy import stats as _stats, fft as _fft, ndimage as _ndimage
 
 
+def pad_image_to_shape(
+    img: _ot.ImageData,
+    shape: tuple[int, int],
+    offset: tuple[int, int],
+    fill_value: float = 0.0,
+) -> _ot.ImageData:
+    """
+    Pads an image to a specified shape with a given offset and fill value.
+
+    Parameters
+    ----------
+    img : _ot.ImageData
+        The image to be padded.
+    shape : tuple[int, int]
+        The target shape (height, width) for the padded image.
+    offset : tuple[int, int]
+        The (y, x) offset at which to place the original image in the padded image.
+    fill_value : float, optional
+        The value to fill the padded areas with. Default is 0.
+
+    Returns
+    -------
+    padded_img : _ot.ImageData
+        The padded image.
+    """
+    padded_img = _np.full(shape, fill_value)
+    y, x = offset
+    h, w = _np.shape(img)
+    padded_img[y : y + h, x : x + w] = img.data
+    return padded_img
+
+
 def frame(idx: int, mylist: list[_ot.ImageData] | _ot.CubeData) -> _ot.ImageData:
     """
     Returns a single frame from a list of files or from a cube.
@@ -213,12 +238,13 @@ def push_pull_reduction_algorithm(
     Parameters
     ----------
     imagelist : list of ImageData | CubeData
-        List of images for the PushPull acquisition, organized according to the template.
+        List of images for the PushPull acquisition, organized according to the
+        template.
     template: int | ArrayLike
         Template for the PushPull acquisition.
     normalization : float | int, optional
-        Normalization factor for the final image. If None, the normalization factor
-        is set to the template length minus one.
+        Normalization factor for the final image. If None, the normalization
+        factor is set to the template length minus one.
 
     Returns
     -------
@@ -231,7 +257,7 @@ def push_pull_reduction_algorithm(
     # Template weights computation
     w = _xp.asarray(
         template.astype(_np.result_type(template, imagelist[0].data), copy=True),
-        dtype=_xp.float,
+        dtype=_ot.compute_float(),
     )
     if n_images > 2:
         w[1:-1] *= 2.0
@@ -239,9 +265,9 @@ def push_pull_reduction_algorithm(
     master_mask = _np.logical_or.reduce([ima.mask for ima in imagelist])
     # Compute weighted sum over realizations on raw data
     stack = _xp.stack(
-        [_xp.asarray(ima.data, dtype=_xp.float) for ima in imagelist],
+        [_xp.asarray(ima.data, dtype=_ot.compute_float()) for ima in imagelist],
         axis=0,
-        dtype=_xp.float,
+        dtype=_ot.compute_float(),
     )  # (n, H, W)
     image = _xp.asnumpy(_xp.tensordot(w, stack, axes=(0, 0)))  # (H, W)
 
@@ -262,6 +288,7 @@ def create_cube(fl_or_il: list[str], register: bool = False) -> _ot.CubeData:
     ----------
     fl_or_il : list of str
         Either:
+
         - the list of image file paths;
         - a list of ImageData.
     register : int or tuple, optional
@@ -865,6 +892,8 @@ def rebin2_d_array(
 
 
 __all__ = [
+    "pad_image_to_shape",
+    # "into_4d_full_frame",
     "frame",
     "unwrap_piston",
     "unwrap_image",

{opticalib-2.0.0 → opticalib-2.2.0}/opticalib/analyzer/signals.py

@@ -1,16 +1,11 @@
 """
-Module: signals
-===============
+Signal-processing utilities — FFT, PSD, filtering and periodograms
+==================================================================
 
-Author(s)
----------
-- Pietro Ferraiuolo
+Functions for frequency-domain analysis: Fourier filtering, power spectral
+density estimation, periodogram computation and signal detrending.  All
+functions operate on plain arrays and return plain arrays.
 
-Description
------------
-
-Module containing functions for signal processing and frequency analysis within
-the Opticalib framework.
 """
 
 import numpy as _np
@@ -45,6 +40,7 @@ def extract_frequency_spectrum(
         Axis along which to compute the FFT (default: -1, last axis).
     window : str or None, optional
         Window function to apply before FFT to reduce spectral leakage:
+
         - None: No windowing (rectangular window)
         - "hann": Hann window (default, good general purpose)
         - "hamming": Hamming window
@@ -52,17 +48,20 @@ def extract_frequency_spectrum(
         - "tukey": Tukey window
     detrend : str or None, optional
         Detrending method applied before FFT:
+
         - None: No detrending
         - "constant": Remove mean (default)
         - "linear": Remove linear trend
     scaling : str, optional
         Scaling of the power spectral density:
+
         - "density": Power spectral density (default)
         - "magnitude": Magnitude spectrum
 
     Returns
     -------
     dict with keys:
+
         - "frequencies" : 1D ndarray
             Frequency axis in Hz
         - "magnitude" : ndarray

{opticalib-2.0.0 → opticalib-2.2.0}/opticalib/analyzer/timeseries.py

@@ -1,32 +1,11 @@
 """
-Module: timeseries
-==================
-
-Author(s)
----------
-- Runa Briguglio
-- Pietro Ferraiuolo
-
-Description
------------
-
-This module provides functions to handle and analyze time series data in the context of Optical Imaging.
-It includes utilities for frame extraction, averaging frames, saving and loading averaged images,
-computing running differences, calculating running means, and estimating structure functions from
-time series data.
-
-Functions:
-- frame: Retrieve a single frame from a list or cube.
-- average_frames: Average multiple frames to create an averaged image.
-- save_average: Save the averaged image to a file.
-- open_average: Load an averaged image from a file.
-- running_diff: Compute the running difference between frames with optional zernike removal.
-- timevec: Generate a time vector for a set of frames based on their timestamps.
-- running_mean: Calculate the running mean of a 1D array.
-- structfunc: Compute the structure function for a given time series.
-
-
-This module is part of the OPTICALIB library and relies on other modules within the package for data handling and processing.
+Time-series analysis — frame extraction, running statistics, structure functions
+================================================================================
+
+Utilities for handling time-ordered data: frame extraction and averaging,
+running differences and means, structure-function estimation, and
+timestamp-based time-vector generation.
+
 """
 
 import os as _os
@@ -139,6 +118,7 @@ def save_average(
         be passed on
     **kwargs : additional optional arguments
         The same arguments as `average_frames`, to specify the averaging method.
+
         - first : int, optional
             Index number of the first file to consider. If None, the first file in
             the list is considered.
@@ -210,6 +190,7 @@ def running_diff(
     ----------
     tn_or_fl : str or list[str] or list[ImageData] or CubeData
         It can either be:
+
         - a tracking number where the frames to process are;
         - a list of strings with the file list of images to process;
         - a list of ImageData objects;
@@ -408,6 +389,7 @@ def noise_pushpull(
     ----------
     tn_or_fl : str | list[ImageData] | list[str] | CubeData
         The data to be processed. Can be either:
+
         - A tracking number (str)
         - A list of file paths (str)
         - A list of ImageData objects

opticalib-2.2.0/opticalib/core/__init__.py

@@ -0,0 +1,17 @@
+"""
+Core — configuration, data folders, shared types and I/O
+========================================================
+
+The :mod:`opticalib.core` package is the foundation of the library.  It
+owns the YAML configuration file, the on-disk data folder tree, the
+exception hierarchy, shared decorators, structured data classes for
+passing calibration results between components, and the FITS-aware masked
+array wrappers.
+
+Every other area of the library depends on core.  Importing it reads
+``AOCONF``, opens the configuration file, and calls
+:func:`~opticalib.core.root.create_folder_tree` — set the environment
+variable before import (or use the ``calpy`` entry point, which handles
+it automatically).
+
+"""

{opticalib-2.0.0 → opticalib-2.2.0}/opticalib/core/_configurations/configuration.yaml

@@ -61,11 +61,14 @@ DEVICES:
   DEFORMABLE.MIRRORS:
     AlpaoXXX:
       # AlpaoDM serial number, BAX<YYY>
-      serialNumber: 
+      serial_number: 
       # Parent folder containing Lib64/ (e.g. .../Linux/Samples/Python3)
       sdk_folder_path: 
       # Folder containing the .acfg hardware config file (sets ACECFG env var)
       acfg_path: 
+      # IP and PORT needed for the plico_dm backend
+      plico_ip: 
+      plico_port: 
       diameter: 
       slave_ids: []
       border_ids: []

{opticalib-2.0.0 → opticalib-2.2.0}/opticalib/core/_types.py

@@ -1,19 +1,32 @@
 """
-TYPINGS module
-==============
-2025
-
-Author(s)
----------
-- Pietro Ferraiuolo : pietro.ferraiuolo@inaf.it
-
-Description
------------
-This module defines custom type aliases and protocols for type hinting
-within the `opticalib` package. It includes protocols for matrix-like
-objects, image data, cube data, interferometer devices, and deformable
-mirror devices. Additionally, it provides a custom `isinstance_` function
-to check if an object conforms to these protocols.
+Type System — structural type aliases and device protocols for OptiCalib
+========================================================================
+
+OptiCalib is deliberately *hardware agnostic*.  Instead of coupling
+algorithms to concrete classes, this module defines **structural type
+aliases** and **Protocol classes** that describe the *shape* and
+*capabilities* an object must have.
+
+Two complementary layers:
+
+**Data aliases** — ``MatrixLike``, ``MaskData``, ``ImageData``,
+``CubeData``, ``FitsData`` — capture what array-shaped payloads look like
+(dimensionality, presence of a mask, FITS serialisability).  Every alias
+is a :class:`~typing.TypeVar` bound to a :class:`~typing.Protocol`, so
+static type checkers verify compatibility without any inheritance
+relationship.
+
+**Device protocols** — ``InterferometerDevice``, ``WFSDevice``,
+``CameraDevice``, ``DeformableMirrorDevice`` and their ``Fake*``
+counterparts — specify the *methods* a device must expose.  Any object
+that structurally matches the protocol can be passed where the alias is
+expected, whether it is a real driver, a simulator, or a test double.
+
+The module is re-exported publicly as ``opticalib.typings``.
+
+Because the aliases are structural (not nominal), ``isinstance(x,
+ImageData)`` does **not** work.  Use :func:`isinstance_` instead — it
+dispatches to the correct runtime check for the given name.
 
 """
 
@@ -39,7 +52,10 @@ if TYPE_CHECKING:
 #################################
 ## DATA TYPES AND TYPE ALIASES ##
 #################################
+#: A reconstructor object used to convert raw interferometer frames into
+#: phase maps, or ``None`` when no reconstruction is needed.
 Reconstructor: TypeAlias = Union["ComputeReconstructor", None]
+#: Any plain Python number, i.e. an ``int``, a ``float`` or a ``complex``.
 Number: TypeAlias = Union[int, float, complex]
 
 
@@ -82,10 +98,21 @@ class _CubeProtocol(Protocol):
     def __array__(self) -> ArrayLike: ...
 
 
+#: A generic 2-D matrix, i.e. any object with a ``shape`` that can be
+#: indexed, such as a ``numpy.ndarray`` or a nested list. Used for command matrices,
+#: command histories and other plain numeric tables.
 MatrixLike = TypeVar("MatrixLike", bound=_MatrixProtocol)
+#: A 2-D boolean (or integer 0/1) mask, typically marking which pixels lie
+#: outside the pupil or region of interest.
 MaskData = TypeVar("MaskData", bound=_MatrixProtocol)
+#: A single 2-D image with a mask attached, such as a phase map returned by
+#: an interferometer. In practice this is a ``numpy.ma.MaskedArray``.
 ImageData = TypeVar("ImageData", bound=_ImageDataProtocol)
+#: A 3-D stack of masked images, with shape ``(ny, nx, n_frames)``, such as
+#: the set of influence functions measured for a deformable mirror.
 CubeData = TypeVar("CubeData", bound=_CubeProtocol)
+#: An array (masked or not) that can be saved to and loaded from a FITS file,
+#: e.g. a :class:`~opticalib.core.fitsarray.FitsArray`.
 FitsData = TypeVar("FitsData", _FitsArrayProtocol, _FitsMaskedArrayProtocol)
 
 
@@ -118,8 +145,13 @@ class _WFSProtocol(Protocol):
     def acquire_detector(self, **kwargs: dict[str, Any]) -> ImageData: ...
 
 
+#: Any interferometer, real or simulated, that can acquire phase maps and
+#: capture/produce raw frame sequences.
 InterferometerDevice = TypeVar("InterferometerDevice", bound=_InterfProtocol)
+#: Any camera that can acquire frames and get/set its exposure time.
 CameraDevice = TypeVar("CameraDevice", bound=_CameraProtocol)
+#: Any wavefront sensor that can acquire phase maps, pupil images and raw
+#: detector frames.
 WFSDevice = TypeVar("WFSDevice", bound=_WFSProtocol)
 
 
@@ -130,7 +162,7 @@ class _DMProtocol(Protocol):
     def set_shape(self, cmd: MatrixLike, differential: bool) -> None: ...
     def get_shape(self) -> ArrayLike: ...
     def upload_cmd_history(
-        self, cmdhist: MatrixLike, *, slave: bool | str = False
+        self, cmdhist: MatrixLike, *, slaving: bool | str = False
     ) -> None: ...
     def run_cmd_history(
         self,
@@ -162,14 +194,22 @@ class _FakeInterfProtocol(_InterfProtocol, Protocol):
     def toggle_shape_removal(self, modes: list[int]) -> None: ...
 
 
+#: Any deformable mirror, real or simulated, that can apply a shape, read it
+#: back, and run a timed history of commands.
 DeformableMirrorDevice = TypeVar("DeformableMirrorDevice", bound=_DMProtocol)
+#: A simulated deformable mirror. It is a ``DeformableMirrorDevice`` that
+#: also exposes its internal mask, Zernike generator and computed wavefront.
 FakeDeformableMirrorDevice = TypeVar(
     "FakeDeformableMirrorDevice", bound=_FakeDMProtocol
 )
+#: A simulated interferometer. It is an ``InterferometerDevice`` that also
+#: offers live-view controls (surface view, noise, shape removal, ...).
 FakeInterferometerDevice = TypeVar(
     "FakeInterferometerDevice", bound=_FakeInterfProtocol
 )
 
+#: Any device object, with no required methods. Used where a function works
+#: with whichever instrument it is given.
 GenericDevice = TypeVar("GenericDevice")
 
 #######################
@@ -399,3 +439,32 @@ class InstanceCheck:
 
 
 isinstance_ = InstanceCheck.isinstance_
+
+######################
+## Helper Functions ##
+######################
+
+
+def get_device_type(device: object) -> str:
+    if isinstance_(device, "InterferometerDevice"):
+        return "interf"
+    elif isinstance_(device, "WFSDevice"):
+        return "wfs"
+    elif isinstance_(device, "CameraDevice"):
+        return "camera"
+    return device._name
+
+
+def compute_float():
+    """
+    Floating dtype for numerical work on the active xupy backend.
+
+    ``float32`` on GPU (CuPy) for speed, ``float64`` on CPU (NumPy). This is
+    what the removed ``xupy.float`` alias used to resolve to; it is evaluated
+    at call time, so it follows ``xupy.use_cpu()`` / ``xupy.use_gpu()``.
+    """
+    import xupy as xp
+
+    dtype = xp.float32 if xp.on_gpu else xp.float64
+    del xp
+    return dtype