From 85c414b11a1cc1d48e28377e3284c87806dc736f Mon Sep 17 00:00:00 2001 From: Josh Carmichael Date: Mon, 27 Apr 2026 09:09:53 -0400 Subject: [PATCH 1/3] CLOrient3D -> Orient3D --- src/aspire/abinitio/__init__.py | 2 +- src/aspire/abinitio/commonline_base.py | 2 +- src/aspire/abinitio/commonline_cn.py | 4 ++-- src/aspire/abinitio/commonline_d2.py | 4 ++-- src/aspire/abinitio/commonline_lud.py | 2 +- src/aspire/abinitio/commonline_matrix.py | 4 ++-- src/aspire/source/image.py | 8 ++++---- tests/test_orient_sync_voting.py | 6 +++--- tests/test_oriented_source.py | 2 +- 9 files changed, 17 insertions(+), 17 deletions(-) diff --git a/src/aspire/abinitio/__init__.py b/src/aspire/abinitio/__init__.py index 8f309b0166..323f2f08ac 100644 --- a/src/aspire/abinitio/__init__.py +++ b/src/aspire/abinitio/__init__.py @@ -4,7 +4,7 @@ build_outer_products, g_sync, ) -from .commonline_base import CLOrient3D +from .commonline_base import Orient3D from .commonline_matrix import CLMatrixOrient3D from .commonline_sdp import CommonlineSDP from .commonline_lud import CommonlineLUD diff --git a/src/aspire/abinitio/commonline_base.py b/src/aspire/abinitio/commonline_base.py index 41f5ff109e..94c41d0e8f 100644 --- a/src/aspire/abinitio/commonline_base.py +++ b/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 """ diff --git a/src/aspire/abinitio/commonline_cn.py b/src/aspire/abinitio/commonline_cn.py index 30f3ffbca1..74703715f5 100644 --- a/src/aspire/abinitio/commonline_cn.py +++ b/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 Orient3D, JSync 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. diff --git a/src/aspire/abinitio/commonline_d2.py b/src/aspire/abinitio/commonline_d2.py index e1730bf35e..34f28ee775 100644 --- a/src/aspire/abinitio/commonline_d2.py +++ b/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. diff --git a/src/aspire/abinitio/commonline_lud.py b/src/aspire/abinitio/commonline_lud.py index f4f69181a6..40c9220fe0 100644 --- a/src/aspire/abinitio/commonline_lud.py +++ b/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 diff --git a/src/aspire/abinitio/commonline_matrix.py b/src/aspire/abinitio/commonline_matrix.py index 50623495ae..4c18fdb53a 100644 --- a/src/aspire/abinitio/commonline_matrix.py +++ b/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 CLMatrixOrient3D(Orient3D): """ An intermediate base class to serve commonline algorithms that use a commonline matrix. diff --git a/src/aspire/source/image.py b/src/aspire/source/image.py index 19d7ee311c..c349ce4c9f 100644 --- a/src/aspire/source/image.py +++ b/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 Orient3D, CLSync3N 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}." ) diff --git a/tests/test_orient_sync_voting.py b/tests/test_orient_sync_voting.py index 0cdcaa0c22..f8ead6e21b 100644 --- a/tests/test_orient_sync_voting.py +++ b/tests/test_orient_sync_voting.py @@ -8,7 +8,7 @@ from click.testing import CliRunner from aspire.abinitio import ( - CLOrient3D, + Orient3D, CLSymmetryC2, CLSymmetryC3C4, CLSymmetryCn, @@ -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(): diff --git a/tests/test_oriented_source.py b/tests/test_oriented_source.py index ebabb818d1..30bb080b9f 100644 --- a/tests/test_oriented_source.py +++ b/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) From c037ad677bbb9c5b1310981b3ba9cd9b0acb4ca8 Mon Sep 17 00:00:00 2001 From: Josh Carmichael Date: Mon, 27 Apr 2026 09:10:29 -0400 Subject: [PATCH 2/3] CLMatrixOrient3D -> CLOrient3D --- src/aspire/abinitio/__init__.py | 2 +- src/aspire/abinitio/commonline_c2.py | 4 ++-- src/aspire/abinitio/commonline_c3_c4.py | 4 ++-- src/aspire/abinitio/commonline_matrix.py | 2 +- src/aspire/abinitio/commonline_sdp.py | 4 ++-- src/aspire/abinitio/commonline_sync.py | 4 ++-- src/aspire/abinitio/commonline_sync3n.py | 4 ++-- tests/test_commonline_matrix.py | 4 ++-- 8 files changed, 14 insertions(+), 14 deletions(-) diff --git a/src/aspire/abinitio/__init__.py b/src/aspire/abinitio/__init__.py index 323f2f08ac..d8e2cfddcd 100644 --- a/src/aspire/abinitio/__init__.py +++ b/src/aspire/abinitio/__init__.py @@ -5,7 +5,7 @@ g_sync, ) from .commonline_base import Orient3D -from .commonline_matrix import CLMatrixOrient3D +from .commonline_matrix import CLOrient3D from .commonline_sdp import CommonlineSDP from .commonline_lud import CommonlineLUD from .commonline_irls import CommonlineIRLS diff --git a/src/aspire/abinitio/commonline_c2.py b/src/aspire/abinitio/commonline_c2.py index 25f4728cbd..b8e0cfc7dc 100644 --- a/src/aspire/abinitio/commonline_c2.py +++ b/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. diff --git a/src/aspire/abinitio/commonline_c3_c4.py b/src/aspire/abinitio/commonline_c3_c4.py index a404766986..b706d8efc8 100644 --- a/src/aspire/abinitio/commonline_c3_c4.py +++ b/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. diff --git a/src/aspire/abinitio/commonline_matrix.py b/src/aspire/abinitio/commonline_matrix.py index 4c18fdb53a..7bd7ea6fe9 100644 --- a/src/aspire/abinitio/commonline_matrix.py +++ b/src/aspire/abinitio/commonline_matrix.py @@ -12,7 +12,7 @@ logger = logging.getLogger(__name__) -class CLMatrixOrient3D(Orient3D): +class CLOrient3D(Orient3D): """ An intermediate base class to serve commonline algorithms that use a commonline matrix. diff --git a/src/aspire/abinitio/commonline_sdp.py b/src/aspire/abinitio/commonline_sdp.py index d2baba27c5..763ebbf56f 100644 --- a/src/aspire/abinitio/commonline_sdp.py +++ b/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. diff --git a/src/aspire/abinitio/commonline_sync.py b/src/aspire/abinitio/commonline_sync.py index 0a8aa3397d..c40751cdbb 100644 --- a/src/aspire/abinitio/commonline_sync.py +++ b/src/aspire/abinitio/commonline_sync.py @@ -2,7 +2,7 @@ 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 @@ -10,7 +10,7 @@ logger = logging.getLogger(__name__) -class CLSyncVoting(CLMatrixOrient3D): +class CLSyncVoting(CLOrient3D): """ Define a class to estimate 3D orientations using synchronization matrix and voting method. diff --git a/src/aspire/abinitio/commonline_sync3n.py b/src/aspire/abinitio/commonline_sync3n.py index fa08d5401d..0e9711405f 100644 --- a/src/aspire/abinitio/commonline_sync3n.py +++ b/src/aspire/abinitio/commonline_sync3n.py @@ -5,7 +5,7 @@ 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 @@ -13,7 +13,7 @@ logger = logging.getLogger(__name__) -class CLSync3N(CLMatrixOrient3D): +class CLSync3N(CLOrient3D): """ Define a class to estimate 3D orientations using common lines Sync3N methods (2017). diff --git a/tests/test_commonline_matrix.py b/tests/test_commonline_matrix.py index fd6a70e35f..866946a02d 100644 --- a/tests/test_commonline_matrix.py +++ b/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): From 62eaaeb689efcb7381758fc4e6564d3dec4cf4d2 Mon Sep 17 00:00:00 2001 From: Josh Carmichael Date: Mon, 27 Apr 2026 09:40:55 -0400 Subject: [PATCH 3/3] Update Docs --- docs/source/orientation_estimation.rst | 46 +++++++++++++------------- src/aspire/abinitio/commonline_cn.py | 2 +- src/aspire/source/image.py | 2 +- tests/test_orient_sync_voting.py | 2 +- 4 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/source/orientation_estimation.rst b/docs/source/orientation_estimation.rst index dca90ddcc2..afa70db73b 100644 --- a/docs/source/orientation_estimation.rst +++ b/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. """ diff --git a/src/aspire/abinitio/commonline_cn.py b/src/aspire/abinitio/commonline_cn.py index 74703715f5..cf0bc73837 100644 --- a/src/aspire/abinitio/commonline_cn.py +++ b/src/aspire/abinitio/commonline_cn.py @@ -3,7 +3,7 @@ import numpy as np from numpy.linalg import norm -from aspire.abinitio import Orient3D, JSync +from aspire.abinitio import JSync, Orient3D from aspire.operators import PolarFT from aspire.utils import ( J_conjugate, diff --git a/src/aspire/source/image.py b/src/aspire/source/image.py index c349ce4c9f..0660f402c5 100644 --- a/src/aspire/source/image.py +++ b/src/aspire/source/image.py @@ -9,7 +9,7 @@ import mrcfile import numpy as np -from aspire.abinitio import Orient3D, CLSync3N +from aspire.abinitio import CLSync3N, Orient3D from aspire.image import Image, normalize_bg from aspire.image.xform import ( CropPad, diff --git a/tests/test_orient_sync_voting.py b/tests/test_orient_sync_voting.py index f8ead6e21b..305682d8cc 100644 --- a/tests/test_orient_sync_voting.py +++ b/tests/test_orient_sync_voting.py @@ -8,7 +8,6 @@ from click.testing import CliRunner from aspire.abinitio import ( - Orient3D, CLSymmetryC2, CLSymmetryC3C4, CLSymmetryCn, @@ -18,6 +17,7 @@ CommonlineIRLS, CommonlineLUD, CommonlineSDP, + Orient3D, ) from aspire.commands.orient3d import orient3d from aspire.downloader import emdb_2660