synim 1.2.4__tar.gz → 2.0.0__tar.gz

{synim-1.2.4 → synim-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synim
-Version: 1.2.4
+Version: 2.0.0
 Summary: Synthetic interaction matrix generator for adaptive optics systems
 Author-email: Guido Agapito <guido.agapito@inaf.it>
 License-Expression: MIT
@@ -53,6 +53,7 @@ It also supports GPU acceleration. Some of its functionalities are provided by [
 - 💾 **SPECULA-compatible** FITS format for data exchange
 - 🎯 **Smart caching** to minimize redundant computations
 - 🚀 **GPU acceleration** via CuPy for high-performance computation
+- 🧭 **Mis-registration geometry** (`synim.registration`): a geometric (not pixel-based) model of the relation between global (WFS/DM/guide-star) and local (per-pair) mis-registration in MCAO/GLAO systems, its inversion, and sensitivity/noise analysis - see the [documentation](https://synim.readthedocs.io/en/latest/registration.html)
 
 ## Documentation
 

{synim-1.2.4 → synim-2.0.0}/README.md

@@ -19,6 +19,7 @@ It also supports GPU acceleration. Some of its functionalities are provided by [
 - 💾 **SPECULA-compatible** FITS format for data exchange
 - 🎯 **Smart caching** to minimize redundant computations
 - 🚀 **GPU acceleration** via CuPy for high-performance computation
+- 🧭 **Mis-registration geometry** (`synim.registration`): a geometric (not pixel-based) model of the relation between global (WFS/DM/guide-star) and local (per-pair) mis-registration in MCAO/GLAO systems, its inversion, and sensitivity/noise analysis - see the [documentation](https://synim.readthedocs.io/en/latest/registration.html)
 
 ## Documentation
 

{synim-1.2.4 → synim-2.0.0}/docs/api/index.rst

@@ -9,4 +9,5 @@ API Reference
    params_manager
    params_utils
    utils
+   registration
 

synim-2.0.0/docs/api/registration.rst

@@ -0,0 +1,42 @@
+Mis-registration Geometry (registration)
+========================================
+
+Affine geometry primitives
+--------------------------
+
+.. automodule:: synim.registration.geometry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Global mis-registration model (GuideStar, DM, WFS, System)
+----------------------------------------------------------
+
+.. automodule:: synim.registration.model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Global-from-local reconstruction
+--------------------------------
+
+.. automodule:: synim.registration.reconstruction
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Sensitivity and noise-propagation analysis
+------------------------------------------
+
+.. automodule:: synim.registration.analysis
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Visualization
+-------------
+
+.. automodule:: synim.registration.viz
+   :members:
+   :undoc-members:
+   :show-inheritance:

{synim-1.2.4 → synim-2.0.0}/docs/conf.py

@@ -11,6 +11,10 @@ import sys
 import re
 sys.path.insert(0, os.path.abspath('..'))
 
+# autodoc imports the SynIM submodules, which require synim.init() first
+import synim  # noqa: E402
+synim.init(device_idx=-1, precision=1)
+
 project = 'SynIM'
 copyright = '2025, Guido Agapito'
 author = 'Guido Agapito'

{synim-1.2.4 → synim-2.0.0}/docs/general.rst

@@ -74,55 +74,70 @@ SynIM is organized into several main modules:
 
 **utils.py**
    General utility functions:
-   
+
    - Array rebinning and masking
    - Geometric transformations
    - Zernike polynomials
    - FITS I/O helpers
 
-.. _computation_workflows:
+**registration/**
+   Unlike every module above, this does not compute a pixel/influence-
+   function interaction or projection matrix. It is a purely geometric
+   (2D affine) model of how a DM actuator grid lines up with a WFS
+   sub-aperture grid in a system with several DMs and WFSs at different
+   conjugation altitudes (MCAO/GLAO), following
+   `Agapito, Plantet & Heritier (2024) <https://doi.org/10.48550/arXiv.2406.15336>`_:
 
-Computation Workflows
-~~~~~~~~~~~~~~~~~~~~~
+   - ``geometry.py``: affine transforms (shift, rotation, magnification, anamorphosis)
+   - ``model.py``: ``GuideStar``, ``DM``, ``WFS`` and ``System`` - the global mis-registration model
+   - ``reconstruction.py``: global parameters from local measurements, by Gauss-Newton inversion
+   - ``analysis.py``: sensitivity, degeneracy and noise-propagation analysis
+   - ``viz.py``: altitude schematic, mis-registration table, top-down footprint views
 
-SynIM implements two main workflows for interaction matrix computation, automatically selected based on system geometry to optimize accuracy and performance.
-
-**SEPARATED Workflow**
-   Used when transformations exist only in DM or WFS (not both):
-   
-   **Process:**
-   
-   1. Apply DM transformations to influence functions (rotation, magnification, source altitude projection)
-   2. Compute numerical derivatives or G-tilts with edge extrapolation
-   3. Apply WFS transformations to derivatives or G-tilts (rotation, translation, magnification)
-   4. Bin derivatives or G-tilts to subaperture resolution
-   5. Extract slopes for valid subapertures
-   
-   **Advantages:**
-   
-   - Single interpolation step per transformation type
-   - Maximum accuracy (no cumulative interpolation errors)
-   - Can reuse derivatives or G-tilts for multiple WFS with same geometry
+   See :doc:`registration` for a full introduction and
+   :doc:`tutorials/registration_morfeo_tutorial` for a worked example.
 
-**COMBINED Workflow**
-   Used when both DM and WFS have transformations:
-   
-   **Process:**
-   
-   1. Combine all DM and WFS transformations into single composite operation
-   2. Apply combined transformation to influence functions in one interpolation step
-   3. Compute derivatives or G-tilts on final transformed grid
-   4. Bin and extract slopes
-   
-   **Advantages:**
-   
-   - Avoids double interpolation artifacts that occur when transformations are coupled
-   - Single interpolation step when both DM and WFS rotate/translate
-   - Consistent handling of complex geometric configurations
+.. _computation_workflows:
 
-**Automatic Workflow Selection**
+Computation Workflows
+~~~~~~~~~~~~~~~~~~~~~
 
-The workflow is automatically selected based on system geometry analyzing transformation parameters.
+**Interaction matrices**
+   All the geometric transformations (DM shift, rotation and magnification from
+   the guide star direction and height, WFS shift, rotation, magnification and
+   anamorphosis) are combined into a single affine transformation, applied to
+   the influence functions in one interpolation step:
+
+   1. Combine all DM and WFS transformations into a single composite operation
+   2. Apply it to the influence functions (the phase) in one interpolation step
+   3. Compute derivatives or G-tilts (telescoping sum) with edge repair on the
+      transformed grid
+   4. Bin to subaperture resolution and extract the slopes of the valid subapertures
+
+   The slope of a subaperture is the mean over its pupil pixels (derivatives)
+   or over its pairs of adjacent pupil pixels (telescoping sum), so partially
+   illuminated subapertures are averaged over their illuminated area. When the
+   number of pixels is not a multiple of the number of subapertures (e.g. 480
+   pixels and 68 subapertures), a pixel shared by two subapertures contributes
+   to each with the fraction of its area inside it (``utils.rebin_matrix``):
+   no interpolation of the phase or of the derivatives is needed.
+
+   WFS transformations are never applied to derivative maps: the gradient of
+   the transformed phase includes the Jacobian of the transformation (rotation
+   and 45° anamorphosis mix the x and y components, magnification and 90°
+   anamorphosis scale them), which a resampling of the derivative maps does not
+   account for.
+
+   With several WFS (``interaction_matrices_multi_wfs``), the WFS with the same
+   guide star, WFS transformations, number of subapertures and slope method
+   share the transformed influence functions and the derivatives, which are
+   computed once for the group (see ``derivatives_info['groups']``).
+
+**Projection matrices**
+   Projection matrices transform scalar fields (DM modes and the projection
+   basis), so the DM and basis transformations can be applied separately
+   (SEPARATED workflow) or combined in one interpolation step (COMBINED workflow,
+   used when both the DM and the basis are transformed).
 
 GPU Architecture
 ~~~~~~~~~~~~~~~~
@@ -140,6 +155,13 @@ GPU support is implemented through a flexible backend system:
       # GPU backend (cupy + cupyx.scipy)
       synim.init(device_idx=0, precision=1)
 
+   ``synim.init()`` must be called once, before importing the SynIM submodules
+   (``synim.synim``, ``synim.synpm``, ``synim.utils``, ``synim.params_utils``,
+   ``synim.params_manager``): they bind the array library and the data types
+   when they are imported. Importing them before ``synim.init()`` raises a
+   ``RuntimeError``, as does calling ``synim.init()`` again with a different
+   configuration after they have been imported.
+
 **Memory Management**
    - Automatic data transfer between CPU and GPU
    - Graceful fallback to CPU on memory errors
@@ -217,7 +239,7 @@ Common validation checks:
 File Organization
 -----------------
 
-SynIM follows SPECULA's directory structure for seamless integration. The ``ParamsManager`` automatically creates and manages these directories based on the ``root_dir`` parameter in your configuration:
+SynIM follows SPECULA directory structure for seamless integration. The ``ParamsManager`` automatically creates and manages these directories based on the ``root_dir`` parameter in your configuration:
 
 .. code-block:: python
 
@@ -259,7 +281,7 @@ SynIM follows SPECULA's directory structure for seamless integration. The ``Para
        └── rec/         # Reconstructors and Projection matrices (SPECULA format)
 
 
-**Note:** When using SynIM with SPECULA, both tools can share the same ``root_dir`` and ``ifunc/`` directory. SPECULA uses additional directories (``im/``, ``rec/``) which can coexist alongside SynIM's directories.
+**Note:** When using SynIM with SPECULA, both tools can share the same ``root_dir`` and ``ifunc/`` directory. SPECULA uses additional directories (``im/``, ``rec/``) which can coexist alongside SynIM directories.
 
 Filename Conventions
 ~~~~~~~~~~~~~~~~~~~~

{synim-1.2.4 → synim-2.0.0}/docs/index.rst

@@ -23,6 +23,7 @@ Key Features
 - 🎯 **Smart caching** to minimize redundant computations
 - 🔀 **Multi-WFS optimization** for faster batch computation
 - 🚀 **GPU acceleration** via CuPy for high-performance computation
+- 🧭 **Mis-registration geometry**: a geometric (not pixel-based) model linking global (WFS/DM/guide-star) and local (per-pair) registration in MCAO/GLAO systems, with inversion and sensitivity analysis
 
 
 User Guide
@@ -34,6 +35,7 @@ User Guide
    Installation <installation>
    Basics <general>
    Configuration & Legacy Migration <configuration>
+   Mis-registration Geometry <registration>
 
 Tutorials
 ---------
@@ -42,6 +44,7 @@ Tutorials
 
    SCAO calibration tutorial <tutorials/scao_calibration_tutorial>
    MCAO calibration tutorial (MORFEO) <tutorials/mcao_calibration_tutorial>
+   Mis-registration geometry tutorial (MORFEO LGS) <tutorials/registration_morfeo_tutorial>
 
 API Reference
 -------------

synim-2.0.0/docs/registration.rst

@@ -0,0 +1,212 @@
+.. _registration:
+
+Mis-registration Geometry
+==========================
+
+The ``synim.registration`` subpackage models the geometric relation
+between the **global** mis-registration of a wide-field AO (WFAO)
+system - the position of each wavefront sensor (WFS) and each
+deformable mirror (DM) relative to the pupil, and of each guide star
+relative to its assumed position - and the **local** mis-registration
+of each WFS-DM pair - the shift, rotation, magnification and
+anamorphosis a local estimator measures between one sub-aperture grid
+and one actuator grid.
+
+It follows the geometry of Agapito, Plantet & Heritier (2024),
+*SPRINT for WFAO systems*, Proc. SPIE 13097
+(`arXiv:2406.15336 <https://doi.org/10.48550/arXiv.2406.15336>`_),
+generalizing the SCAO registration method of Heritier et al. (2021) to
+systems with several WFSs and DMs (MCAO/GLAO).
+
+.. important::
+   Despite living in SynIM, this is **not** the pixel/influence-function
+   interaction matrix computed by :func:`synim.synim.interaction_matrix`
+   (or the projection matrices in ``synpm.py``): it never touches a
+   phase screen, a WFS signal or an influence function. It works
+   entirely on 2D affine geometry - the shift, rotation, magnification
+   and anamorphosis relating one coordinate grid to another - which is
+   what "interaction" means here: how the actuator grid of a DM lines up
+   with the sub-aperture grid of a WFS in a system where several DMs and
+   WFSs, conjugated at different altitudes, do not share one simple
+   pairing (an MCAO/GLAO system, unlike SCAO).
+
+   This subpackage also does **not** estimate local mis-registration
+   itself. It takes local measurements as given - produced elsewhere,
+   for example by SPRINT (already implemented in `SPECULA
+   <https://github.com/ArcetriAdaptiveOptics/SPECULA>`_) - and provides
+   the forward map from global parameters to local measurements, its
+   inversion, and tools to study its conditioning and noise sensitivity.
+   It does not touch on-sky calibration either.
+
+Local and global parameters
+----------------------------
+
+Local mis-registration, per WFS-DM pair:
+
+- X and Y shift between sub-apertures and actuators
+- rotation between sub-apertures and actuators
+- magnification and anamorphosis between sub-apertures and actuators
+
+Global mis-registration, one set per element:
+
+- shift, rotation and magnification of a WFS relative to the pupil
+- shift, rotation, magnification and anamorphosis of a DM relative to
+  the pupil
+- shift and altitude error of a guide star relative to its assumed
+  position (altitude error applies to laser guide stars only)
+
+A single DM at the pupil (for example an adaptive secondary mirror)
+makes the two levels coincide for that DM: see `System.local_transform`
+below.
+
+Building a system
+------------------
+
+A system is a set of ``WFS`` objects (each with its own ``GuideStar``)
+and a set of ``DM`` objects, collected in a ``System``:
+
+.. code-block:: python
+
+   from synim.registration.model import GuideStar, DM, WFS, System
+
+   system = System(pixel_pitch=0.0802)  # meters per shift unit
+
+   gs = GuideStar(name="lgs1", position=(45.0, 22.5), height=90000.0)
+   system.add_wfs(WFS(name="wfs1", guide_star=gs, rotation=6.2))
+
+   system.add_dm(DM(name="dm1", height=600.0))
+   system.add_dm(DM(name="dm2", height=6500.0))
+
+Every shift is expressed in the same unit as ``pixel_pitch`` (matching
+the ``xShiftPhInPixel``/``yShiftPhInPixel`` convention of a SPECULA
+YAML file); angles are in degrees, guide star positions in arcsec.
+Nominal (zero mis-registration) values are the default, so a freshly
+built system already represents a perfectly aligned instrument.
+
+The forward model: from global to local
+------------------------------------------
+
+``System.local_params`` composes a WFS own mis-registration, the
+guide-star parallax at a DM altitude, and that DM own
+mis-registration into the local shift/rotation/magnification/
+anamorphosis of one pair:
+
+.. code-block:: python
+
+   shift, rotation, magnification, anamorphosis = system.local_params("wfs1", "dm1")
+
+``System.pairs()`` lists every WFS-DM pair; restrict it to a subset
+(for example the LGS WFSs only) when some sensors carry no useful
+shape information - see the :ref:`MORFEO tutorial
+<registration_morfeo_tutorial>`.
+
+Loading a system from a configuration file
+---------------------------------------------
+
+``System.from_params_manager`` builds a system directly from an already
+parsed SPECULA/SynIM YAML configuration, reusing
+:func:`synim.params_utils.extract_wfs_list` and related helpers:
+
+.. code-block:: python
+
+   import synim
+   synim.init(device_idx=-1, precision=1)
+   from synim.params_utils import parse_params_file
+   from synim.registration.model import System
+
+   config = parse_params_file("params_mcao.yml")
+   system = System.from_params_manager(config)
+
+Only the WFS fields already used elsewhere in SynIM (``rotation``,
+``xShiftPhInPixel``/``yShiftPhInPixel``, ``magnification``,
+``anamorph45``) are read this way; a DM own shift/magnification and a
+guide star position/altitude error have no dedicated key in that
+format and default to zero - set them directly on the returned objects,
+or through the reconstruction tools below.
+
+Inverting: global parameters from local measurements
+--------------------------------------------------------
+
+Given a set of local measurements (from SPRINT, or - as in the example
+above - injected for testing), :mod:`synim.registration.reconstruction`
+recovers the global parameters behind them by Gauss-Newton iteration:
+
+.. code-block:: python
+
+   from synim.registration.reconstruction import ParameterSpec, gauss_newton_invert
+
+   specs = [
+       ParameterSpec("dm", "dm2", "shift", 0),
+       ParameterSpec("dm", "dm2", "rotation"),
+       ParameterSpec("wfs", "wfs1", "shift", 0),
+   ]
+   alpha_hat, system_hat, history = gauss_newton_invert(
+       system, specs, system.pairs(), local_measurements)
+
+A ``ParameterSpec`` names one scalar unknown (an object, a field, and -
+for a shift - which component); ``history`` is the residual norm at
+each iteration, for a convergence check. At each step, a sensitivity
+matrix (the same role as an interaction matrix, mapping global
+parameters to local measurements) is built by finite differences and
+inverted by pseudo-inverse.
+
+Sensitivity and degeneracy
+----------------------------
+
+Not every choice of unknowns is well posed. Two cases the paper points
+out, and that :mod:`synim.registration.analysis` can detect directly
+from the sensitivity matrix built above:
+
+- a common shift applied to every WFS together with every DM
+  (each scaled by its own parallax factor) leaves every local
+  measurement unchanged - an exact gauge freedom, since only the
+  *relative* WFS-DM alignment is observable;
+- a guide star position error and the shift of the WFS affect a
+  single WFS-DM pair identically, and can only be told apart using
+  several DMs at different altitudes.
+
+.. code-block:: python
+
+   from synim.registration.analysis import analyze
+
+   report = analyze(system, specs, system.pairs(), sigma=0.02)
+   print(report["condition_number"], report["modes"][-1])
+
+``report["modes"]`` lists, from best to worst determined, which
+``ParameterSpec`` entries dominate each direction; passing ``sigma``
+(the local-measurement noise, one value or one per degree of freedom)
+also returns the resulting global-parameter uncertainty, both from the
+pseudo-inverse directly (``analytic_std``) and from a Monte Carlo
+cross-check (``montecarlo_std``, via `monte_carlo_noise_propagation`).
+
+.. important::
+   That Monte Carlo check reconstructs with a single linear step,
+   linearized exactly at the true values used to generate ``report``
+   sensitivity matrix - the same linear model behind ``analytic_std``.
+   Its expectation therefore equals those true values by construction,
+   so it can validate the analytic UNCERTAINTY, but it is unbiased by
+   construction and cannot reveal an estimation BIAS. To check for a
+   real bias, run `monte_carlo_gauss_newton` instead: it repeats the
+   actual iterative estimator (`gauss_newton_invert`) from a given
+   starting system - typically the nominal one, as an operational
+   estimator would, not knowing the true values in advance. Compare its
+   returned mean to the true values, in units of ``std / sqrt(n_trials)``
+   (the standard error of that mean), to tell a real bias from Monte
+   Carlo sampling noise.
+
+Visualization
+--------------
+
+:mod:`synim.registration.viz` provides an altitude schematic, a
+mis-registration table, and a top-down footprint view per DM, all
+colour-matched and combinable through ``plot_system_overview``. See the
+:ref:`MORFEO tutorial <registration_morfeo_tutorial>` for example
+output.
+
+See Also
+--------
+
+- :ref:`registration_morfeo_tutorial` - a worked example on a MORFEO-like geometry
+- :doc:`api/registration` - full API reference
+- Agapito, Plantet & Heritier (2024), *SPRINT for WFAO systems*,
+  `arXiv:2406.15336 <https://doi.org/10.48550/arXiv.2406.15336>`_

{synim-1.2.4 → synim-2.0.0}/docs/scripts/generate_api_docs.py

@@ -16,6 +16,32 @@ def generate_module_doc(module_name, title=None):
 """
     return content
 
+def generate_registration_doc():
+    """
+    Generate the RST page for the `synim.registration` subpackage: one
+    `automodule` block per submodule, since it is a subpackage (not a
+    single flat module like the others), so `generate_module_doc`'s
+    single-module template does not apply.
+    """
+    title = "Mis-registration Geometry (registration)"
+    submodules = [
+        ("geometry", "Affine geometry primitives"),
+        ("model", "Global mis-registration model (GuideStar, DM, WFS, System)"),
+        ("reconstruction", "Global-from-local reconstruction"),
+        ("analysis", "Sensitivity and noise-propagation analysis"),
+        ("viz", "Visualization"),
+    ]
+    sections = "\n".join(
+        f"{heading}\n{'-' * len(heading)}\n\n"
+        f".. automodule:: synim.registration.{name}\n"
+        "   :members:\n"
+        "   :undoc-members:\n"
+        "   :show-inheritance:\n"
+        for name, heading in submodules
+    )
+    return f"{title}\n{'=' * len(title)}\n\n{sections}"
+
+
 def generate_api_index():
     """Generate API index page"""
     content = """API Reference
@@ -29,6 +55,7 @@ def generate_api_index():
    params_manager
    params_utils
    utils
+   registration
 
 """
     return content
@@ -64,6 +91,13 @@ def main():
             f.write(content)
         print("  ✓ Generated")
 
+    # The registration subpackage has several submodules, so it gets its
+    # own page with one automodule block each (see generate_registration_doc).
+    print("Generating api/registration.rst...")
+    with open(api_docs_path / "registration.rst", 'w') as f:
+        f.write(generate_registration_doc())
+    print("  ✓ Generated")
+
     print("\n" + "="*50)
     print("Done! Generated files:")
     for rst_file in sorted(api_docs_path.glob("*.rst")):

{synim-1.2.4 → synim-2.0.0}/docs/tutorials/mcao_calibration_tutorial.rst

@@ -20,7 +20,7 @@ This tutorial explains the calibration logic and the sequence of mathematical pr
    
    While SynIM supports dual slope-computation engines, they model the sensor physics differently:
    
-   * **'derivatives' (Default & Recommended)**: Computes local gradients using finite differences and averages them over the subaperture. Thanks to SynIM's strict sub-pixel geometric alignment during spatial resampling, this method natively absorbs the diffractive effects and cross-talk of real Shack-Hartmann sensors. It provides superior physical fidelity and resilience, especially for high-spatial-frequency modes.
+   * **'derivatives' (Default & Recommended)**: Computes local gradients using finite differences and averages them over the subaperture. Thanks to SynIM strict sub-pixel geometric alignment during spatial resampling, this method natively absorbs the diffractive effects and cross-talk of real Shack-Hartmann sensors. It provides superior physical fidelity and resilience, especially for high-spatial-frequency modes.
    * **'telsum'**: Uses a boundary-driven telescoping sum to evaluate the exact phase difference strictly at the subaperture edges. While mathematically exact for purely geometric boundaries, it struggles to map the continuous diffractive reality of the physical wavefront sensor compared to the aligned numerical derivatives.
    
    Because of this, the 'derivatives' engine guarantees both a significantly more accurate slope estimation and a substantial computational speed-up on GPU.