Orientation Estimation Base Class Name Change

docs/source/orientation_estimation.rst

@@ -15,7 +15,7 @@ The reference-free workflow below illustrates how orientation solvers integrate
 denoising and reconstruction utilities.
 
 #. Starting from an ``ImageSource`` (often the output of the class averaging stack
-   described in :doc:`class_source`), instantiate one of the ``CLOrient3D`` subclasses
+   described in :doc:`class_source`), instantiate one of the ``Orient3D`` subclasses
    with the source plus any tuning parameters (angular resolution, shift search ranges,
    histogram settings).
 
@@ -60,14 +60,14 @@ Layout of the Class Hierarchy
 -----------------------------
 
 All common-line estimators live under :mod:`aspire.abinitio` and share the base class
-``CLOrient3D``. Algorithms that rely on a pairwise common-line matrix inherit from the
-intermediary base class ``CLMatrixOrient3D``. Together they codify the data preparation
+``Orient3D``. Algorithms that rely on a pairwise common-line matrix inherit from the
+intermediary base class ``CLOrient3D``. Together they codify the data preparation
 steps, caching strategy, and the minimal interface each subclass must expose.
 
-CLOrient3D
-^^^^^^^^^^
+Orient3D
+^^^^^^^^
 
-``CLOrient3D`` manages dataset-wide configuration such as polar grid resolution, masking
+``Orient3D`` manages dataset-wide configuration such as polar grid resolution, masking
 strategies, and the shift solving backend. It exposes:
 
 - ``src``: the ``ImageSource`` supplying masked projection stacks.
@@ -83,7 +83,7 @@ strategies, and the shift solving backend. It exposes:
 .. mermaid::
 
    classDiagram
-       class CLOrient3D{
+       class Orient3D{
            src: ImageSource
 	   +estimate_rotations()
 	   +estimate_shifts()
@@ -92,10 +92,10 @@ strategies, and the shift solving backend. It exposes:
 	   +shifts
        }
 
-CLMatrixOrient3D
-^^^^^^^^^^^^^^^^
+CLOrient3D
+^^^^^^^^^^
 
-``CLMatrixOrient3D`` augments ``CLOrient3D`` with utilities for assembling the
+``CLOrient3D`` augments ``Orient3D`` with utilities for assembling the
 ``clmatrix`` (indices of correlated polar rays between image pairs) and any auxiliary
 scores such as ``cl_dist`` or ``shifts_1d``. Key behaviors include:
 
@@ -110,7 +110,7 @@ scores such as ``cl_dist`` or ``shifts_1d``. Key behaviors include:
 .. mermaid::
 
    classDiagram
-       class CLMatrixOrient3D{
+       class CLOrient3D{
            src: ImageSource
 	   +estimate_rotations()
 	   +estimate_shifts()
@@ -136,7 +136,7 @@ power-method based handedness synchronization to complete this task.
 - The solver supports CPU/GPU execution, configurable tolerances (``epsilon``) and
   iteration limits (``max_iters``), and logs residuals so that callers can monitor
   convergence.
-- ``CLOrient3D`` subclasses simply import the ``JSync`` module to access handedness
+- ``Orient3D`` subclasses simply import the ``JSync`` module to access handedness
   synchronization methods.
 
 Class Hierarchy Overview
@@ -148,16 +148,16 @@ utilities, synchronization helpers) before layering on algorithm-specific logic.
 .. mermaid::
 
    classDiagram
-       CLOrient3D <|-- CLMatrixOrient3D
-       CLMatrixOrient3D <|-- CLSync3N
-       CLMatrixOrient3D <|-- CLSyncVoting   
-       CLMatrixOrient3D <|-- CommonlineSDP
+       Orient3D <|-- CLOrient3D
+       CLOrient3D <|-- CLSync3N
+       CLOrient3D <|-- CLSyncVoting
+       CLOrient3D <|-- CommonlineSDP
        CommonlineSDP <|-- CommonlineLUD
        CommonlineLUD <|-- CommonlineIRLS
-       CLMatrixOrient3D <|-- CLSymmetryC2
-       CLMatrixOrient3D <|-- CLSymmetryC3C4
-       CLOrient3D <|-- CLSymmetryCn
-       CLOrient3D <|-- CLSymmetryD2
+       CLOrient3D <|-- CLSymmetryC2
+       CLOrient3D <|-- CLSymmetryC3C4
+       Orient3D <|-- CLSymmetryCn
+       Orient3D <|-- CLSymmetryD2
        class JSync
        CLSync3N o-- JSync
        CLSymmetryC2 o-- JSync
@@ -223,7 +223,7 @@ Extensibility
 
 Adding a new orientation estimator typically involves:
 
-#. Subclassing ``CLOrient3D`` (or ``CLMatrixOrient3D`` if you need common-line matrices).
+#. Subclassing ``Orient3D`` (or ``CLOrient3D`` if you need common-line matrices).
 #. Implementing ``estimate_rotations(self, **kwargs)``. This method must return an
    ``(n, 3, 3)`` array of rotations to be consumed by ``estimate_shifts`` and downstream
    reconstruction methods.
@@ -235,9 +235,9 @@ used inside :class:`aspire.source.OrientedSource`. A simplified template is show
 
 .. code-block:: python
 
-   from aspire.abinitio import CLMatrixOrient3D
+   from aspire.abinitio import CLOrient3D
 
-   class CLFancySync(CLMatrixOrient3D):
+   class CLFancySync(CLOrient3D):
        """
        Example orientation estimator built on the common-lines matrix workflow.
        """

src/aspire/abinitio/__init__.py

@@ -4,8 +4,8 @@
     build_outer_products,
     g_sync,
 )
-from .commonline_base import CLOrient3D
-from .commonline_matrix import CLMatrixOrient3D
+from .commonline_base import Orient3D
+from .commonline_matrix import CLOrient3D
 from .commonline_sdp import CommonlineSDP
 from .commonline_lud import CommonlineLUD
 from .commonline_irls import CommonlineIRLS

src/aspire/abinitio/commonline_base.py

@@ -14,7 +14,7 @@
 logger = logging.getLogger(__name__)
 
 
-class CLOrient3D:
+class Orient3D:
     """
     Define a base class for estimating 3D orientations using common lines methods
     """

src/aspire/abinitio/commonline_c2.py

@@ -3,7 +3,7 @@
 import numpy as np
 from scipy.linalg import eigh
 
-from aspire.abinitio import CLMatrixOrient3D, JSync
+from aspire.abinitio import CLOrient3D, JSync
 from aspire.abinitio.sync_voting import _syncmatrix_ij_vote_3n
 from aspire.utils import J_conjugate, Rotation, all_pairs
 
@@ -16,7 +16,7 @@
 logger = logging.getLogger(__name__)
 
 
-class CLSymmetryC2(CLMatrixOrient3D):
+class CLSymmetryC2(CLOrient3D):
     """
     Define a class to estimate 3D orientations using common lines methods for molecules with C2 cyclic symmetry.
 

src/aspire/abinitio/commonline_c3_c4.py

@@ -3,7 +3,7 @@
 import numpy as np
 from numpy.linalg import norm, svd
 
-from aspire.abinitio import CLMatrixOrient3D, JSync
+from aspire.abinitio import CLOrient3D, JSync
 from aspire.abinitio.sync_voting import _syncmatrix_ij_vote_3n
 from aspire.operators import PolarFT
 from aspire.utils import J_conjugate, Rotation, all_pairs, anorm, tqdm, trange
@@ -17,7 +17,7 @@
 logger = logging.getLogger(__name__)
 
 
-class CLSymmetryC3C4(CLMatrixOrient3D):
+class CLSymmetryC3C4(CLOrient3D):
     """
     Define a class to estimate 3D orientations using common lines methods for molecules with
     C3 and C4 cyclic symmetry.

src/aspire/abinitio/commonline_cn.py

@@ -3,7 +3,7 @@
 import numpy as np
 from numpy.linalg import norm
 
-from aspire.abinitio import CLOrient3D, JSync
+from aspire.abinitio import JSync, Orient3D
 from aspire.operators import PolarFT
 from aspire.utils import (
     J_conjugate,
@@ -28,7 +28,7 @@
 logger = logging.getLogger(__name__)
 
 
-class CLSymmetryCn(CLOrient3D):
+class CLSymmetryCn(Orient3D):
     """
     Define a class to estimate 3D orientations using common lines methods for molecules with
     Cn cyclic symmetry, with n>4.

src/aspire/abinitio/commonline_d2.py

@@ -4,7 +4,7 @@
 import scipy.sparse.linalg as la
 from numpy.linalg import norm
 
-from aspire.abinitio import CLOrient3D
+from aspire.abinitio import Orient3D
 from aspire.operators import PolarFT
 from aspire.utils import J_conjugate, Rotation, all_pairs, all_triplets, tqdm, trange
 from aspire.utils.random import randn
@@ -15,7 +15,7 @@
 logger = logging.getLogger(__name__)
 
 
-class CLSymmetryD2(CLOrient3D):
+class CLSymmetryD2(Orient3D):
     """
     Define a class to estimate 3D orientations using common lines methods for
     molecules with D2 (dihedral) symmetry.

src/aspire/abinitio/commonline_lud.py

@@ -43,7 +43,7 @@ def __init__(
         """
         Initialize a class for estimating 3D orientations using a Least Unsquared Deviations algorithm.
 
-        This class extends the `CLOrient3D` class, inheriting its initialization parameters. Additional
+        This class extends the `Orient3D` class, inheriting its initialization parameters. Additional
         parameters detailed below.
 
         :param alpha: Spectral norm constraint for ADMM algorithm. Default is None, which

src/aspire/abinitio/commonline_matrix.py

@@ -3,7 +3,7 @@
 
 import numpy as np
 
-from aspire.abinitio import CLOrient3D
+from aspire.abinitio import Orient3D
 from aspire.utils import complex_type, tqdm
 from aspire.utils.random import choice
 
@@ -12,7 +12,7 @@
 logger = logging.getLogger(__name__)
 
 
-class CLMatrixOrient3D(CLOrient3D):
+class CLOrient3D(Orient3D):
     """
     An intermediate base class to serve commonline algorithms that use
     a commonline matrix.

src/aspire/abinitio/commonline_sdp.py

@@ -4,14 +4,14 @@
 import numpy as np
 from scipy.sparse import csr_array
 
-from aspire.abinitio import CLMatrixOrient3D
+from aspire.abinitio import CLOrient3D
 from aspire.utils import nearest_rotations
 from aspire.utils.matlab_compat import stable_eigsh
 
 logger = logging.getLogger(__name__)
 
 
-class CommonlineSDP(CLMatrixOrient3D):
+class CommonlineSDP(CLOrient3D):
     """
     Class to estimate 3D orientations using semi-definite programming.
 

src/aspire/abinitio/commonline_sync.py

@@ -2,15 +2,15 @@
 
 import numpy as np
 
-from aspire.abinitio import CLMatrixOrient3D
+from aspire.abinitio import CLOrient3D
 from aspire.abinitio.sync_voting import _rotratio_eulerangle_vec, _vote_ij
 from aspire.utils import nearest_rotations
 from aspire.utils.matlab_compat import stable_eigsh
 
 logger = logging.getLogger(__name__)
 
 
-class CLSyncVoting(CLMatrixOrient3D):
+class CLSyncVoting(CLOrient3D):
     """
     Define a class to estimate 3D orientations using synchronization matrix and voting method.
 

src/aspire/abinitio/commonline_sync3n.py

@@ -5,15 +5,15 @@
 import numpy as np
 from scipy.optimize import curve_fit
 
-from aspire.abinitio import CLMatrixOrient3D, JSync
+from aspire.abinitio import CLOrient3D, JSync
 from aspire.abinitio.sync_voting import _syncmatrix_ij_vote_3n
 from aspire.utils import J_conjugate, all_pairs, nearest_rotations, tqdm, trange
 from aspire.utils.matlab_compat import stable_eigsh
 
 logger = logging.getLogger(__name__)
 
 
-class CLSync3N(CLMatrixOrient3D):
+class CLSync3N(CLOrient3D):
     """
     Define a class to estimate 3D orientations using common lines Sync3N methods (2017).
 

src/aspire/source/image.py

@@ -9,7 +9,7 @@
 import mrcfile
 import numpy as np
 
-from aspire.abinitio import CLOrient3D, CLSync3N
+from aspire.abinitio import CLSync3N, Orient3D
 from aspire.image import Image, normalize_bg
 from aspire.image.xform import (
     CropPad,
@@ -1834,7 +1834,7 @@ def __init__(self, src, orientation_estimator=None):
         performing orientation estimation using a supplied `orientation_estimator`.
 
         :param src: Source used for orientation estimation
-        :param orientation_estimator: CLOrient3D subclass used for orientation estimation.
+        :param orientation_estimator: Orient3D subclass used for orientation estimation.
             Default uses the CLSync3N method.
         """
 
@@ -1862,9 +1862,9 @@ def __init__(self, src, orientation_estimator=None):
             orientation_estimator = CLSync3N(src)
 
         self.orientation_estimator = orientation_estimator
-        if not isinstance(self.orientation_estimator, CLOrient3D):
+        if not isinstance(self.orientation_estimator, Orient3D):
             raise ValueError(
-                "`orientation_estimator` should be subclass of `CLOrient3D`,"
+                "`orientation_estimator` should be subclass of `Orient3D`,"
                 f" found {self.orientation_estimator}."
             )
 

tests/test_commonline_matrix.py

@@ -2,7 +2,7 @@
 import pytest
 
 from aspire.abinitio import (
-    CLMatrixOrient3D,
+    CLOrient3D,
     CLSymmetryC2,
     CLSymmetryC3C4,
     CLSync3N,
@@ -55,7 +55,7 @@ def src(dtype):
 
 
 def test_class_structure(subclass):
-    assert issubclass(subclass, CLMatrixOrient3D)
+    assert issubclass(subclass, CLOrient3D)
 
 
 def test_clmatrix_lazy_eval(subclass, src, caplog):

tests/test_orient_sync_voting.py

@@ -8,7 +8,6 @@
 from click.testing import CliRunner
 
 from aspire.abinitio import (
-    CLOrient3D,
     CLSymmetryC2,
     CLSymmetryC3C4,
     CLSymmetryCn,
@@ -18,6 +17,7 @@
     CommonlineIRLS,
     CommonlineLUD,
     CommonlineSDP,
+    Orient3D,
 )
 from aspire.commands.orient3d import orient3d
 from aspire.downloader import emdb_2660
@@ -231,9 +231,9 @@ def test_n_check_error():
     sim = Simulation()
 
     with pytest.raises(NotImplementedError, match=r"n_check must be in*"):
-        _ = CLOrient3D(sim, n_check=-2)
+        _ = Orient3D(sim, n_check=-2)
     with pytest.raises(NotImplementedError, match=r"n_check must be in*"):
-        _ = CLOrient3D(sim, n_check=sim.n + 1)
+        _ = Orient3D(sim, n_check=sim.n + 1)
 
 
 def test_command_line():

tests/test_oriented_source.py

@@ -98,7 +98,7 @@ def test_estimator_error(src_fixture):
     junk_estimator = 123
     with pytest.raises(
         ValueError,
-        match="`orientation_estimator` should be subclass of `CLOrient3D`,* ",
+        match="`orientation_estimator` should be subclass of `Orient3D`,* ",
     ):
         _ = OrientedSource(og_src, junk_estimator)