Explain realized 2D unwrapping algorithm in docstring

Author: AlexeyPechnikov

insardev/insardev/Batch.py

@@ -1332,6 +1332,12 @@ def unwrap2d_irls(self, weight: 'BatchUnit | None' = None, device: str = 'auto',
             - unwrapped: Batch of unwrapped phase (float32)
             - conncomp: BatchUnit of component labels (uint16, 0=invalid, 1=largest, ...)
 
+        Notes
+        -----
+        Uses a novel DCT+IRLS algorithm that combines DCT efficiency with IRLS
+        robustness. See `utils_unwrap2d.irls_unwrap_2d` for algorithm details
+        and references.
+
         Examples
         --------
         >>> phase, corr = stack.pairs(baseline.tolist()).phasediff(wavelength=30).angle()

insardev/insardev/Stack_unwrap2d.py

@@ -758,11 +758,12 @@ def unwrap2d_irls(self, phase, weight=None, device='auto',
         Notes
         -----
         - GPU/TPU-accelerated using PyTorch (TPU via XLA, CUDA/ROCm, MPS, or CPU)
-        - Uses accelerated DCT for fast initialization
-        - L¹ norm preserves discontinuities better than L² (DCT)
+        - L¹ norm preserves discontinuities better than L² (DCT alone)
         - Correlation weighting handles phase residues properly
         - Provides consistent results across multi-burst data
-        - Based on arXiv:2401.09961
+
+        **Algorithm**: Uses a novel DCT+IRLS combination. See
+        `utils_unwrap2d.irls_unwrap_2d` for algorithm details and references.
         """
         import dask
         import dask.array as da

insardev/insardev/utils_unwrap2d.py

@@ -1125,14 +1125,30 @@ def irls_unwrap_2d(phase, weight=None, device='auto', max_iter=50, tol=1e-3,
 
     Notes
     -----
-    The algorithm uses GPU-accelerated DCT as initial solution (same as
-    standalone DCT method), then refines it through weighted iterations.
-    The DCT initialization provides a good starting point, and the IRLS
-    iterations correct for residue-induced errors using correlation weights.
-
-    Based on: Dubois-Taine et al., "Iteratively Reweighted Least Squares
-    for Phase Unwrapping", arXiv:2401.09961 (2024).
+    **Algorithm novelty**: This implementation uses DCT to solve the weighted
+    least squares subproblem within each IRLS iteration. This specific combination
+    does not appear in the literature:
+
+    - **DCT for phase unwrapping** (Ghiglia & Romero): Uses DCT to solve least
+      squares, but with static weights only (not iteratively reweighted).
+    - **IRLS for phase unwrapping** (arXiv:2401.09961): Uses IRLS iterations,
+      but with preconditioned conjugate gradient as the inner solver, not DCT.
+    - **Weighted DCT (WDCT)**: Uses weights but they are fixed, not iteratively
+      updated based on residuals.
+
+    This implementation combines DCT's efficiency with IRLS's robustness by
+    using DCT as the fast solver within each IRLS iteration, updating weights
+    based on residuals after each step.
+
+    References
+    ----------
+    - Ghiglia & Romero, "Robust two-dimensional weighted and unweighted phase
+      unwrapping that uses fast transforms and iterative methods", JOSA A (1994)
+    - Dubois-Taine et al., "Iteratively Reweighted Least Squares for Phase
+      Unwrapping", arXiv:2401.09961 (2024), https://arxiv.org/abs/2401.09961
 
+    Performance
+    -----------
     Achieves 10-20x speedup over SNAPHU on GPU/TPU.
 
     Default parameters ensure robust convergence for InSAR processing: