CodeEntropy 2.4.2__py3-none-any.whl → 2.5.0__py3-none-any.whl

CodeEntropy/__init__.py

@@ -8,4 +8,4 @@ entropy estimates, supporting a wide range of applications in molecular simulati
 and statistical mechanics.
 """
 
-__version__ = "2.4.2"
+__version__ = "2.5.0"

CodeEntropy/entropy/vibrational.py

@@ -148,7 +148,7 @@ class VibrationalEntropy:
             Eigenvalues as a NumPy array.
         """
         matrix = np.asarray(matrix, dtype=float)
-        return la.eigvals(matrix)
+        return la.eigvalsh(matrix)
 
     def _convert_lambda_units(self, lambdas: np.ndarray) -> np.ndarray:
         """Convert eigenvalues into SI units using run_manager.
@@ -185,7 +185,10 @@ class VibrationalEntropy:
         """Convert eigenvalues to frequencies with robust filtering.
 
         Filters out eigenvalues that are complex, non-positive, or near-zero to
-        avoid invalid frequencies and unstable entropies.
+        avoid invalid frequencies and unstable entropies. The near-zero
+        tolerance scales with the spectrum's own magnitude (as in
+        ``numpy.linalg.matrix_rank``) rather than using a fixed cutoff, since
+        the eigensolver noise floor around a true null mode is not constant.
 
         Args:
             lambdas: Eigenvalues (post unit conversion).
@@ -197,8 +200,11 @@ class VibrationalEntropy:
         lambdas = np.asarray(lambdas)
         lambdas = np.real_if_close(lambdas, tol=1000)
 
+        scale = float(np.max(np.abs(lambdas))) if lambdas.size else 0.0
+        atol = lambdas.size * np.finfo(float).eps * scale
+
         valid_mask = (
-            np.isreal(lambdas) & (lambdas > 0) & (~np.isclose(lambdas, 0, atol=1e-7))
+            np.isreal(lambdas) & (lambdas > 0) & (~np.isclose(lambdas, 0, atol=atol))
         )
 
         removed = int(len(lambdas) - np.count_nonzero(valid_mask))

CodeEntropy/levels/axes.py

@@ -73,17 +73,24 @@ class AxesCalculator:
           (previous/next in sequence) using MDAnalysis bonded selections.
         - If there are *no* bonds to other residues:
             * Use a custom principal axes, from a moment-of-inertia (MOI) tensor
-              that uses positions of heavy atoms only, but including masses of
+              that uses positions of heavy atoms only, but includes masses of
               heavy atom + bonded hydrogens.
             * Set translational axes equal to rotational axes (as per the original
               code convention).
-        - If bonded to other residues:
+
+        - If bonded to only one other residue:
+            * Translational axes are principal axes of data_container.
+            * Find edge heavy atom (i.e. heavy atoms bonded to neighbour residue).
+              Compute rotation centre and axes as in get_terminal_axes.
+              Compute custom MOI, using heavy atom positions and
+              heavy atom + hydrogen masses.
+
+        - If bonded to at least two other residues:
             * Translational axes are principal axes of data_container.
-            * Find edge heavy atoms (i.e. heavy atoms bonded to neighbour residues)
-              and find the shortest chain between them: the backbone. Edge
-              atoms + backbone COM are used to determine residue rotational axes.
-              (see get_residue_custom_axes).Compute a custom MOI, using heavy atom
-              positions and heavy atom + hydrogen masses.
+            * Find edge heavy atoms (i.e. heavy atoms bonded to neighbour residues).
+              Compute rotation centre and axes as in get_non_terminal_axes.
+              Compute a custom MOI, using heavy atom positions and
+              heavy atom + hydrogen masses.
 
         Args:
             data_container (MDAnalysis.Universe or AtomGroup):
@@ -137,39 +144,27 @@ class AxesCalculator:
                 masses=ua_masses,
                 dimensions=data_container.dimensions[:3],
             )
-            rot_axes, moment_of_inertia = self.get_custom_principal_axes(moi_tensor)
+            rot_axes, moment_of_inertia = self.get_principal_axes_from_tensor(
+                moi_tensor
+            )
             trans_axes = rot_axes  # per original convention
             rot_center = np.array(residue.center_of_mass())
         else:
             make_whole(data_container.atoms)
-            trans_axes = data_container.atoms.principal_axes()
-
+            trans_axes = self.get_principal_axes_from_group(data_container.atoms)
             if len(edge_atom_set) == 1:
-                if index == 0:
-                    # first residue: use first heavy atom
-                    edges = [residue.atoms[0], edge_atom_set[0]]
-                    backbone = self.get_chain(
-                        residue, residue.atoms[0], edge_atom_set[0]
-                    )
-                else:
-                    # last residue: last heavy atom
-                    last_index = len(uas) - 1
-                    last = None
-                    if last_index > 0 and last is None:
-                        heavy_atom = uas[last_index]
-                        last = heavy_atom
-                    edges = [edge_atom_set[0], last]
-
-                    backbone = self.get_chain(residue, edge_atom_set[0], last)
+                edge_atom = edge_atom_set[0]
+                rot_center, rot_axes = self.get_terminal_axes(
+                    residue=residue,
+                    edge=edge_atom,
+                    dimensions=data_container.dimensions[:3],
+                )
             else:
-                edges = [edge_atom_set[0], edge_atom_set[1]]
-                backbone = self.get_chain(residue, edge_atom_set[0], edge_atom_set[1])
-            backbone_center = np.zeros(3)
-            for heavy_atom in backbone:
-                backbone_center += heavy_atom.position
-            backbone_center = backbone_center / len(backbone)
-            rot_center, rot_axes = self.get_residue_custom_axes(edges, backbone_center)
-
+                rot_center, rot_axes = self.get_non_terminal_axes(
+                    residue=residue,
+                    edges=edge_atom_set,
+                    dimensions=data_container.dimensions[:3],
+                )
             moment_of_inertia = self.get_custom_residue_moment_of_inertia(
                 center_of_mass=rot_center,
                 positions=uas.positions,
@@ -224,14 +219,14 @@ class AxesCalculator:
                 masses=topology.residue_ua_masses,
                 dimensions=dimensions,
             )
-            rot_axes, moment_of_inertia = self.get_custom_principal_axes(
+            rot_axes, moment_of_inertia = self.get_principal_axes_from_tensor(
                 moment_of_inertia_tensor
             )
             trans_axes = rot_axes
         else:
             make_whole(mol.atoms)
-            trans_axes = mol.atoms.principal_axes()
-            rot_axes, moment_of_inertia = self.get_vanilla_axes(residue_atoms)
+            trans_axes = self.get_principal_axes_from_group(mol.atoms)
+            rot_axes, moment_of_inertia = self.get_molecule_axes(residue_atoms)
             center = residue_atoms.center_of_mass(unwrap=True)
 
         return trans_axes, rot_axes, center, moment_of_inertia
@@ -247,18 +242,17 @@ class AxesCalculator:
             Use the same approach as residue level rotational.
             Identify residue of interest and neighbours, then select
             edge heavy atoms (i.e. heavy atoms bonded to neighbour residues).
-            If there are no bonds to neighbouring residues, use residue
-            .principal axes Otherwise, find the shortest chain between edge
-            residues: the backbone. Edge atoms + backbone COM are used to
-            determine UA translational axes (see get_residue_custom_axes)
+            - If there are *no* bonds to other residues, use a custom principal axes
+            from a moment-of-inertia (MOI) tensor that uses positions of heavy atoms
+            only, but includes masses of heavy atom + bonded hydrogens.
+            - If bonded to only one other residue, see get_terminal_axes.
+            - If bonded to at least two other residues, see get_non_terminal_axes.
 
         - Rotational axes:
             Identify heavy atoms in the residue/molecule of interest and choose
             the `index`-th heavy atom (where index corresponds to the bead index).
             Use bonded topology around that heavy atom to determine UA rotational
-            axes (see :meth:`get_bonded_axes`).
-            Compute a custom MOI tensor using heavy-atom coordinates but UA masses
-            (heavy + bonded H masses), then compute the principal axes from it.
+            axes (see :meth:`get_bonded_axes`). Compute a custom MOI tensor.
 
         Args:
             data_container (MDAnalysis.Universe or AtomGroup):
@@ -289,72 +283,52 @@ class AxesCalculator:
                 # only the one residue => use principal axes
                 residue = data_container
                 trans_center = data_container.atoms.center_of_mass(unwrap=True)
-                trans_axes = data_container.atoms.principal_axes()
-                residue_heavy_atoms = heavy_atoms
+                trans_axes = self.get_principal_axes_from_group(data_container.atoms)
             else:
                 # residue of interest has at least one neighbour
-                if res_position == -1:
-                    residue = data_container.residues[0]
-                    resindex = residue.resindex
-                    resindex_next = resindex + 1
-
-                    second_edge = data_container.select_atoms(
-                        f"resindex {resindex} and bonded resindex {resindex_next}"
+                if res_position == -1 or res_position == 1:
+                    # look at a terminal residue
+                    if res_position == -1:
+                        # first residue
+                        residue = data_container.residues[0]
+                        resindex = residue.resindex
+                        resindex_next = resindex + 1
+                        edge_atom_set = data_container.select_atoms(
+                            f"resindex {resindex} and bonded resindex {resindex_next}"
+                        )
+                    else:
+                        # last residue
+                        residue = data_container.residues[1]
+                        resindex = residue.resindex
+                        resindex_prev = resindex - 1
+                        edge_atom_set = data_container.select_atoms(
+                            f"resindex {resindex} and bonded resindex {resindex_prev}"
+                        )
+                    edge_atom = edge_atom_set[0]
+                    trans_center, trans_axes = self.get_terminal_axes(
+                        residue=residue,
+                        edge=edge_atom,
+                        dimensions=data_container.dimensions[:3],
                     )
-
-                    edges = [residue.atoms[0], second_edge[0]]
-                    backbone = self.get_chain(
-                        residue, residue.atoms[0], second_edge.atoms[0]
-                    )
-
-                elif res_position == 0:
+                else:
                     # between 2 residues
                     residue = data_container.residues[1]
                     resindex = residue.resindex
                     resindex_next = resindex + 1
                     resindex_prev = resindex - 1
-
-                    edge_set = data_container.select_atoms(
+                    edge_atom_set = data_container.select_atoms(
                         f"resindex {resindex} and "
                         f"(bonded resindex {resindex_prev} or "
                         f"resindex {resindex_next})"
                     )
-
-                    edges = [edge_set[0], edge_set[1]]
-                    backbone = self.get_chain(residue, edge_set[0], edge_set[1])
-
-                else:
-                    # last resid
-                    # always resindex 1 in data_container
-                    residue = data_container.residues[1]
-                    resindex = residue.resindex
-                    resindex_prev = resindex - 1
-                    first_edge = data_container.select_atoms(
-                        f"resindex {resindex} and bonded resindex {resindex_prev}"
+                    trans_center, trans_axes = self.get_non_terminal_axes(
+                        residue=residue,
+                        edges=edge_atom_set,
+                        dimensions=data_container.dimensions[:3],
                     )
-
-                    last_index = len(heavy_atoms) - 1
-                    last = None
-                    # look for last heavy atom
-                    # with only one bond to another
-                    if last_index > 0 and last is None:
-                        heavy_atom = heavy_atoms[last_index]
-                        last = heavy_atom
-
-                    edges = [first_edge.atoms[0], last]
-                    backbone = self.get_chain(residue, first_edge.atoms[0], last)
-
-                backbone_center = np.zeros(3)
-                for heavy_atom in backbone:
-                    backbone_center += heavy_atom.position
-                backbone_center = backbone_center / len(backbone)
-
-                trans_center, trans_axes = self.get_residue_custom_axes(
-                    edges, backbone_center
-                )
-                residue_heavy_atoms = residue.atoms.select_atoms("mass 2 to 999")
-
             # look for heavy atoms in residue of interest
+            residue_heavy_atoms = residue.atoms.select_atoms("mass 2 to 999")
+
             heavy_atom_indices = []
             for atom in residue_heavy_atoms:
                 heavy_atom_indices.append(atom.index)
@@ -444,12 +418,12 @@ class AxesCalculator:
                 masses=topology.residue_ua_masses,
                 dimensions=dimensions,
             )
-            trans_axes, _moment_of_inertia = self.get_custom_principal_axes(
+            trans_axes, _moment_of_inertia = self.get_principal_axes_from_tensor(
                 moment_of_inertia_tensor
             )
         else:
             make_whole(residue_atoms)
-            trans_axes = residue_atoms.principal_axes()
+            trans_axes = self.get_principal_axes_from_group(residue_atoms)
 
         center = heavy_atom.position
         rot_axes, moment_of_inertia = self.get_bonded_axes_from_topology(
@@ -506,10 +480,10 @@ class AxesCalculator:
         ua_all = u.atoms[topology.ua_all_atom_indices]
 
         if len(heavy_bonded) == 0:
-            custom_axes, custom_moment_of_inertia = self.get_vanilla_axes(ua_all)
+            custom_axes, custom_moment_of_inertia = self.get_molecule_axes(ua_all)
 
         if len(heavy_bonded) == 1 and len(light_bonded) == 0:
-            custom_axes = self.get_custom_axes(
+            custom_axes = self.get_bonded_vector_axes(
                 a=heavy_atom.position,
                 b_list=[heavy_bonded[0].position],
                 c=np.zeros(3),
@@ -517,7 +491,7 @@ class AxesCalculator:
             )
 
         if len(heavy_bonded) == 1 and len(light_bonded) >= 1:
-            custom_axes = self.get_custom_axes(
+            custom_axes = self.get_bonded_vector_axes(
                 a=heavy_atom.position,
                 b_list=[heavy_bonded[0].position],
                 c=light_bonded[0].position,
@@ -525,7 +499,7 @@ class AxesCalculator:
             )
 
         if len(heavy_bonded) >= 2:
-            custom_axes = self.get_custom_axes(
+            custom_axes = self.get_bonded_vector_axes(
                 a=heavy_atom.position,
                 b_list=heavy_bonded.positions,
                 c=heavy_bonded[1].position,
@@ -579,10 +553,14 @@ class AxesCalculator:
             rot_center: (3,) rotation centre,
             lies on the E1-E2 vector
             rot_axes: (3,3) rotation axes of residue
+
+        Raises:
+            ValueError: If axes cannot be normalized due to degeneracy.
+
         """
-        first_edge_centre_of_geometry_vector = center - edges[0].position
+        first_edge_centre_of_geometry_vector = center - edges[0]
         # look for projection of E1-O onto E1-E2 (E1-C)
-        first_edge_second_edge_vector = edges[1].position - edges[0].position
+        first_edge_second_edge_vector = edges[1] - edges[0]
         first_edge_origin_vector = (
             np.dot(first_edge_second_edge_vector, first_edge_centre_of_geometry_vector)
             / (np.linalg.norm(first_edge_second_edge_vector) ** 2)
@@ -594,15 +572,119 @@ class AxesCalculator:
         )
         y_axis = origin_centre_of_geometry_vector
         z_axis = np.cross(x_axis, y_axis)
-        x_axis /= np.linalg.norm(x_axis)
-        y_axis /= np.linalg.norm(y_axis)
-        z_axis /= np.linalg.norm(z_axis)
-        rot_axes = np.array([x_axis, y_axis, z_axis])
-        rot_center = first_edge_origin_vector + edges[0].position
+        unscaled_rot_axes = np.array((x_axis, y_axis, z_axis), dtype=float)
+        mod = np.sqrt(np.sum(unscaled_rot_axes**2, axis=1))
+        if np.any(np.isclose(mod, 0.0)):
+            raise ValueError("Degenerate custom axes: cannot normalize (zero norm).")
+        rot_axes = unscaled_rot_axes / mod[:, np.newaxis]
+        rot_center = first_edge_origin_vector + edges[0]
+        return rot_center, rot_axes
+
+    def get_terminal_axes(self, residue, edge, dimensions):
+        """
+        Compute rotation axes at the residue level/translation axes at the UA level
+        for the terminal residues in a polymer, given the edge atom
+        (i.e. atom bonded to neighbour residue) and residue of interest.
+        Find all heavy atoms bonded to edge heavy atom and compute
+        their average position. Find all other heavy atoms in residue
+        and compute their average position. The three points are now used to
+        obtain determine residue rotational axes. (see get_residue_custom_axes)
+        If there are only two heavy atoms in the residue/all heavy atoms are bonded
+        to edge atom, x-axis is set along the vector between the
+        edge atom and average position of bonded atoms, y-axis is arbitrary
+        and z-axis is paralel to the two. This is the same as case 2 in get_bonded_axes.
+        If there no heavy atoms bonded to the edge atom (i.e. the edge atom is the only
+        heavy atom in the residue), centre is set on edge atom and axes are principal
+        axes.
+
+        Args:
+            residue: MDAnalysis AtomGroup
+            edge: MDAnalysis atom
+            dimensions: (3,) dimensions of the simulation box
+
+        Returns:
+            rot_center: (3,) rotation centre,
+            rot_axes: (3,3) rotation axes of residue
+        """
+        heavy_atoms = residue.atoms.select_atoms("mass 2 to 999")
+        bonded_atoms = residue.atoms.select_atoms(
+            f"(mass 2 to 999) and bonded index {edge.index}"
+        )
+        if len(bonded_atoms) == 0:
+            # there is only one heavy atom in the residue
+            rot_center = edge.position
+            rot_axes = self.get_principal_axes_from_group(residue.atoms)
+        else:
+            average_bonded = np.zeros(3)
+            for bonded_atom in bonded_atoms:
+                average_bonded += bonded_atom.position
+            average_bonded /= len(bonded_atoms)
+            # find the average position of all other heavy atoms in residue
+            other_atoms = []
+            for atom in heavy_atoms:
+                if atom != edge and atom not in bonded_atoms:
+                    other_atoms.append(atom)
+            if len(other_atoms) > 0:
+                average_other_atoms = np.zeros(3)
+                for atom in other_atoms:
+                    average_other_atoms += atom.position
+                average_other_atoms /= len(other_atoms)
+                rot_center, rot_axes = self.get_residue_custom_axes(
+                    [edge.position, average_other_atoms], average_bonded
+                )
+            else:
+                rot_center = edge.position
+                rot_axes = self.get_bonded_vector_axes(
+                    a=edge.position,
+                    b_list=[average_bonded],
+                    c=np.zeros(3),
+                    dimensions=dimensions,
+                )
+        return rot_center, rot_axes
+
+    def get_non_terminal_axes(self, residue, edges, dimensions):
+        """
+        Compute rotation axes at the residue level/ translation axes at
+        the UA level for the non-terminal residues in a linear polymer, given the
+        edge atoms (i.e. heavy atoms bonded to neighbour residues) and
+        residue of interest. Find the shortest chain between edge atoms: the backbone.
+        Edges + backbone average position determine the residue rotational axes.
+        (see get_residue_custom_axes). If the two edge heavy atoms
+        are bonded to each other (i.e. there is no backbone), x-axis is set
+        along the vector between the edge atom and average position of bonded
+        atoms, y-axis is arbitrary and z-axis is paralel to the two. This is the
+        same as case 2 in get_bonded_axes.
+        Args:
+            residue: MDAnalysis AtomGroup
+            edges: MDAnalysis AtomGroup
+            dimensions: (3,) dimensions of the simulation box
+
+        Returns:
+            rot_center: (3,) rotation centre,
+            rot_axes: (3,3) rotation axes of residue
+        """
+        backbone = self.get_chain(residue, edges[0], edges[1])
+        backbone_center = np.zeros(3)
+        if len(backbone) > 0:
+            for heavy_atom in backbone:
+                backbone_center += heavy_atom.position
+            backbone_center /= len(backbone)
+            rot_center, rot_axes = self.get_residue_custom_axes(
+                edges.positions, backbone_center
+            )
+        else:
+            rot_center = (edges[0].position + edges[1].position) / 2
+            rot_axes = self.get_bonded_vector_axes(
+                a=rot_center,
+                b_list=[edges[0].position],
+                c=np.zeros(3),
+                dimensions=dimensions,
+            )
         return rot_center, rot_axes
 
     def get_bonded_axes(self, system, atom, dimensions: np.ndarray):
-        r"""Compute UA rotational axes from bonded topology around a heavy atom.
+        """
+        Compute UA rotational axes from bonded topology around a heavy atom.
 
         For a given heavy atom, use its bonded atoms to get the axes for rotating
         forces around. Few cases for choosing united atom axes, which are dependent
@@ -669,11 +751,11 @@ class AxesCalculator:
 
         # case1
         if len(heavy_bonded) == 0:
-            custom_axes, custom_moment_of_inertia = self.get_vanilla_axes(ua_all)
+            custom_axes, custom_moment_of_inertia = self.get_molecule_axes(ua_all)
 
         # case2
         if len(heavy_bonded) == 1 and len(light_bonded) == 0:
-            custom_axes = self.get_custom_axes(
+            custom_axes = self.get_bonded_vector_axes(
                 a=atom.position,
                 b_list=[heavy_bonded[0].position],
                 c=np.zeros(3),
@@ -682,7 +764,7 @@ class AxesCalculator:
 
         # case3
         if len(heavy_bonded) == 1 and len(light_bonded) >= 1:
-            custom_axes = self.get_custom_axes(
+            custom_axes = self.get_bonded_vector_axes(
                 a=atom.position,
                 b_list=[heavy_bonded[0].position],
                 c=light_bonded[0].position,
@@ -692,7 +774,7 @@ class AxesCalculator:
         # case4 (not used in original 2019 code; case5 used instead)
         # case5
         if len(heavy_bonded) >= 2:
-            custom_axes = self.get_custom_axes(
+            custom_axes = self.get_bonded_vector_axes(
                 a=atom.position,
                 b_list=heavy_bonded.positions,
                 c=heavy_bonded[1].position,
@@ -732,14 +814,15 @@ class AxesCalculator:
         bonded_H_atoms = bonded_atoms.select_atoms("mass 1 to 1.1")
         return bonded_heavy_atoms, bonded_H_atoms
 
-    def get_vanilla_axes(self, molecule):
-        """Get principal axes and sorted principal moments (vanilla method).
+    def get_molecule_axes(self, molecule):
+        """Get principal axes and sorted principal moments.
 
-        Compute the principal axes and moments of inertia for a molecule using
-        MDAnalysis built-in functionality.
+        Compute the principal axes and moments of inertia for a molecule from its
+        moment of inertia tensor.
 
-        The original description is preserved:
-        - The molecule is made whole to ensure correct handling of PBC.
+        - The molecule is made whole to ensure correct handling of PBC. The tensor
+          is taken after that, so it does not depend on where the molecule sits
+          relative to the periodic boundary.
         - The moments are obtained by diagonalising the moment of inertia tensor.
         - Eigenvalues are returned sorted from largest to smallest magnitude.
 
@@ -752,17 +835,10 @@ class AxesCalculator:
                 - principal_axes: (3, 3) axes.
                 - moment_of_inertia: (3,) moments sorted descending by absolute value.
         """
-        moment_of_inertia_tensor = molecule.moment_of_inertia(unwrap=True)
         make_whole(molecule.atoms)
-        principal_axes = molecule.principal_axes()
-
-        eigenvalues, _ = np.linalg.eig(moment_of_inertia_tensor)
-        order = np.argsort(np.abs(eigenvalues))[::-1]
-        moment_of_inertia = eigenvalues[order]
+        return self.get_principal_axes_from_tensor(molecule.moment_of_inertia())
 
-        return principal_axes, moment_of_inertia
-
-    def get_custom_axes(
+    def get_bonded_vector_axes(
         self,
         a: np.ndarray,
         b_list: Sequence[np.ndarray],
@@ -994,44 +1070,72 @@ class AxesCalculator:
 
         return moment_of_inertia_tensor
 
-    def get_custom_principal_axes(
-        self, moment_of_inertia_tensor: np.ndarray
+    def get_principal_axes_from_tensor(
+        self,
+        moment_of_inertia_tensor: np.ndarray,
+        degeneracy_rtol: float = 100 * np.finfo(np.float32).eps,
+        reference_vector: Sequence[float] = (1.0, 2.0, 3.0),
     ) -> tuple[np.ndarray, np.ndarray]:
-        """Compute principal axes and moments from a custom MOI tensor.
+        """Compute the principal axes and moments of a moment of inertia tensor.
 
-        Principal axes and centre of axes from the ordered eigenvalues and
-        eigenvectors of a moment of inertia tensor. This function allows for a
-        custom moment of inertia tensor to be used, which isn't possible with the
-        built-in MDAnalysis principal_axes() function.
+        The eigenvectors of a symmetric tensor are only defined up to a sign, and,
+        for equal moments, up to a rotation within the degenerate eigenspace. The
+        axes are returned in a canonical form, so that a given tensor always
+        produces the same axes. The convention is:
 
-        Original behaviour preserved:
-
-        - Eigenvalues are sorted by descending absolute magnitude.
-        - Eigenvectors are transposed so axes are returned as rows.
-        - Z axis is flipped to enforce the same handedness convention as the
-          original implementation.
+        - Moments are sorted by descending absolute value.
+        - Within a degenerate eigenspace (moments equal to within
+          ``degeneracy_rtol`` of the largest), the basis is the eigenvectors of a
+          reference tensor built from ``reference_vector``, projected onto that
+          eigenspace.
+        - The first two axes are signed to have a positive projection onto
+          ``reference_vector``, and the third is their cross product.
 
         Args:
-            moment_of_inertia_tensor: (3, 3) custom inertia tensor.
+            moment_of_inertia_tensor: (3, 3) symmetric inertia tensor.
+            degeneracy_rtol: Relative tolerance, with respect to the largest
+                moment, for treating moments as degenerate. The default is a
+                multiple of the float32 precision of the coordinates.
+            reference_vector: Fixed direction used to choose axis signs and the
+                basis within a degenerate eigenspace. Its components must be
+                distinct, so that no symmetric or axis-aligned direction is
+                perpendicular to it or ties on its components.
 
         Returns:
             Tuple[np.ndarray, np.ndarray]:
                 - principal_axes: (3, 3) principal axes (rows).
-                - moment_of_inertia: (3,) principal moments.
+                - principal_moments: (3,) moments sorted by descending magnitude.
         """
-        eigenvalues, eigenvectors = np.linalg.eig(moment_of_inertia_tensor)
-        order = np.abs(eigenvalues).argsort()[::-1]  # descending order
-        transposed = np.transpose(eigenvectors)  # columns -> rows
-        moment_of_inertia = eigenvalues[order]
-        principal_axes = transposed[order]
-
-        # point z axis in correct direction, as per original code
-        cross_xy = np.cross(principal_axes[0], principal_axes[1])
-        dot_z = float(np.dot(cross_xy, principal_axes[2]))
-        if dot_z < 0:
-            principal_axes[2] *= -1
-
-        return principal_axes, moment_of_inertia
+        principal_moments, eigenvectors = np.linalg.eigh(moment_of_inertia_tensor)
+        order = np.argsort(np.abs(principal_moments))[::-1]
+        principal_moments = principal_moments[order]
+        eigenvectors = eigenvectors[:, order]
+
+        reference = np.asarray(reference_vector, dtype=float)
+        gaps = np.abs(np.diff(np.abs(principal_moments)))
+        boundaries = (
+            np.flatnonzero(gaps > degeneracy_rtol * np.abs(principal_moments[0])) + 1
+        )
+        for subspace in np.split(np.arange(3), boundaries):
+            if len(subspace) > 1:
+                basis = eigenvectors[:, subspace]
+                _, rotation = np.linalg.eigh(basis.T @ np.diag(reference) @ basis)
+                eigenvectors[:, subspace] = basis @ rotation
+
+        for axis in (0, 1):
+            if eigenvectors[:, axis] @ reference < 0:
+                eigenvectors[:, axis] *= -1
+
+        z_axis = np.cross(eigenvectors[:, 0], eigenvectors[:, 1])
+        principal_axes = np.array([eigenvectors[:, 0], eigenvectors[:, 1], z_axis])
+        return principal_axes, principal_moments
+
+    def get_principal_axes_from_group(self, group) -> np.ndarray:
+        """Return the canonical principal axes (rows) of an atom group."""
+        principal_axes, _ = self.get_principal_axes_from_tensor(
+            group.atoms.moment_of_inertia()
+        )
+        return principal_axes
 
     def get_UA_masses(self, molecule) -> list[float]:
         """Return united-atom (UA) masses for a molecule.

CodeEntropy/levels/nodes/covariance.py

@@ -506,8 +506,8 @@ class FrameCovarianceNode:
                 # principal axes
                 make_whole(residue.atoms)
                 make_whole(bead)
-                trans_axes = residue.atoms.principal_axes()
-                rot_axes, moi = axes_manager.get_vanilla_axes(bead)
+                trans_axes = axes_manager.get_principal_axes_from_group(residue.atoms)
+                rot_axes, moi = axes_manager.get_molecule_axes(bead)
                 center = bead.center_of_mass(unwrap=True)
 
             force_vecs.append(
@@ -658,8 +658,8 @@ class FrameCovarianceNode:
         make_whole(mol.atoms)
         make_whole(bead)
 
-        trans_axes = mol.atoms.principal_axes()
-        rot_axes, moi = axes_manager.get_vanilla_axes(bead)
+        trans_axes = axes_manager.get_principal_axes_from_group(mol.atoms)
+        rot_axes, moi = axes_manager.get_molecule_axes(bead)
         center = bead.center_of_mass(unwrap=True)
         return (
             np.asarray(trans_axes),
@@ -688,8 +688,8 @@ class FrameCovarianceNode:
         make_whole(mol.atoms)
         make_whole(bead)
 
-        trans_axes = mol.atoms.principal_axes()
-        rot_axes, moi = axes_manager.get_vanilla_axes(bead)
+        trans_axes = axes_manager.get_principal_axes_from_group(mol.atoms)
+        rot_axes, moi = axes_manager.get_molecule_axes(bead)
         center = bead.center_of_mass(unwrap=True)
 
         return (

CodeEntropy/trajectory/mda.py

@@ -354,7 +354,10 @@ class UniverseOperations:
         select_atom_force = u_force.select_atoms("all")
 
         coordinates = self._extract_timeseries(select_atom, kind="positions")
-        dimensions = self._extract_timeseries(select_atom, kind="dimensions")
+        if u.dimensions is None:
+            dimensions = self._build_non_periodic_dimensions(coordinates)
+        else:
+            dimensions = self._extract_timeseries(select_atom, kind="dimensions")
 
         forces = self._extract_force_timeseries_with_fallback(
             select_atom_force,
@@ -374,6 +377,30 @@ class UniverseOperations:
 
         return new_universe
 
+    @staticmethod
+    def _build_non_periodic_dimensions(coordinates: np.ndarray) -> np.ndarray:
+        """Build a box for a trajectory without box dimensions.
+
+        The axes and covariance code needs a box for the minimum image
+        convention and unwrapping. The box is cubic and more than twice the
+        largest interatomic distance, so neither step changes the coordinates.
+
+        Args:
+            coordinates: Positions with shape ``(n_frames, n_atoms, 3)``.
+
+        Returns:
+            Array of shape ``(n_frames, 6)`` holding the box lengths and 90
+            degree angles for every frame.
+        """
+        span = float(np.max(np.ptp(coordinates, axis=1)))
+        length = max(10.0 * span, 100.0)
+        box = np.array([length, length, length, 90.0, 90.0, 90.0], dtype=np.float32)
+        logger.warning(
+            "Trajectory has no box dimensions; treating it as non-periodic "
+            f"using a {length:.1f} A cubic box."
+        )
+        return np.tile(box, (coordinates.shape[0], 1))
+
     def _extract_timeseries(self, atomgroup, *, kind: str) -> np.ndarray:
         """Extract a time series array using explicit frame indexing.
 

{codeentropy-2.4.2.dist-info → codeentropy-2.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: CodeEntropy
-Version: 2.4.2
+Version: 2.5.0
 Summary: CodeEntropy is a Python package for computing the configurational entropy of macromolecular systems using forces sampled from molecular dynamics (MD) simulations. It implements the multiscale cell correlation method to provide accurate and efficient entropy estimates, supporting a wide range of applications in molecular simulation and statistical mechanics.
 Keywords: entropy,macromolecular systems,MD simulation
 Author-email: Arghya 'Argo' Chakravorty <arghyac@umich.edu>, Donald Chung-HK <donald.chung@stfc.ac.uk>, Sarah Fegan <sarah.fegan@stfc.ac.uk>, James Gebbie-Rayet <james.gebbie@stfc.ac.uk>, Sarah Harris <sarah.harris@sheffield.ac.uk>, Richard Henchman <rhen7213@uni.sydney.edu.au>, Jonathan Higham <j.higham4@lancaster.ac.uk>, Jas Kalayan <jas.kalayan@stfc.ac.uk>, Ioana Papa <iapapa1@sheffield.ac.uk>
@@ -16,34 +16,29 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Development Status :: 5 - Production/Stable
 License-File: LICENSE
-Requires-Dist: numpy>=2.3,<3.0
+Requires-Dist: numpy>=2.3.2,<2.5.0
 Requires-Dist: mdanalysis>=2.10,<3.0
-Requires-Dist: pandas>=3,<3.1
-Requires-Dist: psutil>=7.1,<8.0
-Requires-Dist: PyYAML>=6.0,<7.0
-Requires-Dist: python-json-logger>=4.0,<5.0
-Requires-Dist: rich>=15,<15.1
-Requires-Dist: art>=6.5,<7.0
-Requires-Dist: networkx>=3.6,<3.7
-Requires-Dist: matplotlib>=3.11,<3.12
-Requires-Dist: waterEntropy>=2,<2.3
-Requires-Dist: requests>=2.32,<3.0
-Requires-Dist: rdkit>=2025.9.5
-Requires-Dist: numba>=0.65.1,<0.70
-Requires-Dist: dask>=2026.1.2,<2026.2.0
-Requires-Dist: dask-jobqueue>=0.9.0,<0.10
-Requires-Dist: distributed>=2026.1.2,<2026.2.0
-Requires-Dist: sphinx>=9.1,<9.2 ; extra == "docs"
-Requires-Dist: nbsphinx>=0.9,<1.0 ; extra == "docs"
-Requires-Dist: sphinx_rtd_theme>=3,<3.2 ; extra == "docs"
-Requires-Dist: sphinxcontrib-contentui>=0.2,<1.0 ; extra == "docs"
-Requires-Dist: sphinxcontrib-details-directive>=0.1,<1.0 ; extra == "docs"
+Requires-Dist: pandas>=2.3.3,<4.0
+Requires-Dist: psutil>=5.9.4,<8.0
+Requires-Dist: PyYAML>=6.0.3,<7.0
+Requires-Dist: rich>=13.0.0,<16.0
+Requires-Dist: art>=5.0,<7.0
+Requires-Dist: networkx>=2.8,<4.0
+Requires-Dist: waterEntropy>=2,<3.0
+Requires-Dist: requests>=2.32.2,<3.0
+Requires-Dist: rdkit>=2025.3.4,<2026
+Requires-Dist: numba>=0.63.0,<0.70
+Requires-Dist: dask>=2025.4.0,<2027.1.0
+Requires-Dist: dask-jobqueue>=0.9.0,<1.0
+Requires-Dist: distributed>=2025.4.0,<2027.1.0
+Requires-Dist: sphinx>=8.0.0,<10.0 ; extra == "docs"
+Requires-Dist: nbsphinx>=0.9.3,<1.0 ; extra == "docs"
 Requires-Dist: sphinx_copybutton>=0.5,<1.0 ; extra == "docs"
-Requires-Dist: furo>=2025.0,<2026.0 ; extra == "docs"
+Requires-Dist: furo>=2025.12.19,<2026.0 ; extra == "docs"
 Requires-Dist: markupsafe>=3.0,<4.0 ; extra == "docs"
-Requires-Dist: pre-commit>=4.5,<5.0 ; extra == "pre-commit"
-Requires-Dist: ruff>=0.16,<0.17 ; extra == "pre-commit"
-Requires-Dist: pylint>=4.0,<5.0 ; extra == "pre-commit"
+Requires-Dist: pre-commit>=3.5.0,<5.0 ; extra == "pre-commit"
+Requires-Dist: ruff>=0.15.2,<1.0 ; extra == "pre-commit"
+Requires-Dist: pylint>=3.0.0,<5.0 ; extra == "pre-commit"
 Requires-Dist: rstcheck>=6.2,<7.0 ; extra == "pre-commit"
 Requires-Dist: pytest>=9.0,<10.0 ; extra == "testing"
 Requires-Dist: pytest-cov>=7.0,<8.0 ; extra == "testing"

{codeentropy-2.4.2.dist-info → codeentropy-2.5.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-CodeEntropy/__init__.py,sha256=ZKr8Gv-y5ra4wZypIjXV5VnpMidnqUVDAe_9f0s-zqo,404
+CodeEntropy/__init__.py,sha256=QM8PCDQ0OM8HKjPNiIHHpPFtqLhnyTcGo8Tc6-_Nh-s,404
 CodeEntropy/__main__.py,sha256=5i_ZrxQaq0q2aPllbB4SZ6BApV6oUFCgx0cGyjfMPrU,108
 CodeEntropy/cli.py,sha256=xgSgagCV6HQ3CoXUpG7p7Ef5hCExgxp7orz6dZZWA6c,960
 CodeEntropy/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -11,7 +11,7 @@ CodeEntropy/entropy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSu
 CodeEntropy/entropy/configurational.py,sha256=3erd1Ul4sGL5BMBDYq33f27aRTZqiEb6hv1bVfWo9QA,2392
 CodeEntropy/entropy/graph.py,sha256=LeDF2KxxNVgpetrIE9j0dnW64UhGywDLqoBJEf54vtc,4612
 CodeEntropy/entropy/orientational.py,sha256=gfpYqCKQjAAx22rrUdbiLvzfEIXy1nwJoub1rgYKCvY,3415
-CodeEntropy/entropy/vibrational.py,sha256=jgPWWiUW6aRCx949cFrNKuLB1MJoawD-9Uk8OB04Cs8,9366
+CodeEntropy/entropy/vibrational.py,sha256=WeQJ1bKQPSxPrREJ8CDhk9Ph2xeunrWZ0zu76y-H6Ow,9733
 CodeEntropy/entropy/water.py,sha256=Ob3V08DyQNSWDMqpQ27rqjgHeU5AlKZfjqf9EqUdgqc,8225
 CodeEntropy/entropy/workflow.py,sha256=bxg8AVXGk7uwlv4u2AZ4kTQ26PMge_Z5ubWghdLtn9U,16100
 CodeEntropy/entropy/nodes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -20,7 +20,7 @@ CodeEntropy/entropy/nodes/configurational.py,sha256=-3j2ji_p-twPjZyjQ1T3tgN0pYLS
 CodeEntropy/entropy/nodes/orientational.py,sha256=yPN_XRJ1LOxJ7hOE2cnsjIbgQlI2avM1g3mFbGhW6fM,2481
 CodeEntropy/entropy/nodes/vibrational.py,sha256=3uhRqaMpK8u7QK2SDQ6RLRcr2rS3sPh6-GlTaNdTFWw,16978
 CodeEntropy/levels/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-CodeEntropy/levels/axes.py,sha256=PzFKuac22C_JQvkQamKB7j4W6OUXBx-YMAyKHXlw_E0,44699
+CodeEntropy/levels/axes.py,sha256=wmotkCwWcc7RzicWJQzXVwYFqkyw9WqWpyeRF1NB3zU,50338
 CodeEntropy/levels/forces.py,sha256=c7XnNIBTFCHHXllr1WxTIrxEV_CkUB2b1vdFO8hUofY,11595
 CodeEntropy/levels/hierarchy.py,sha256=3cd4t6Tywg7VMgw4TboFF5VAHdhG4FaGBXsMptchisY,5158
 CodeEntropy/levels/linalg.py,sha256=PJlrKtIOYcYDycW3Tbetm6k94FKFZTq-hm28qiu_tS0,3565
@@ -47,7 +47,7 @@ CodeEntropy/levels/nodes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZ
 CodeEntropy/levels/nodes/accumulators.py,sha256=XM7phCAIo0RK9YAtx2wrdo2oinmpwXYrH9mp1_LQD7U,6259
 CodeEntropy/levels/nodes/axes_topology.py,sha256=QzrWbCL9YA8fzF4_WWpQGaIAAsOnjY6cVH7INDE40dk,11285
 CodeEntropy/levels/nodes/beads.py,sha256=9Ow065FY4jrIqPKCZJCvDNfIekJ17OBSX-bmEFsxtbc,8010
-CodeEntropy/levels/nodes/covariance.py,sha256=zwLPG_VRAH6hmCXeKkeQgqk7e_FRTBq0XXo-bNsR-U8,30210
+CodeEntropy/levels/nodes/covariance.py,sha256=EY_-Ps-e4qtI9RIhV47j7cuvP3znJovGt6kK6yC77sU,30294
 CodeEntropy/levels/nodes/detect_levels.py,sha256=YrM5SSceLiMqbOhr8Fy6SV-E_zkKRpvgHfDT8Grbin8,1864
 CodeEntropy/levels/nodes/detect_molecules.py,sha256=jILCddEicVngA7FjvQzafbG8HslaRICpT6hj2Uyi6YY,3059
 CodeEntropy/molecules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -56,10 +56,10 @@ CodeEntropy/results/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSu
 CodeEntropy/results/reporter.py,sha256=ZmCEKhh_h7-0JGumlyrpH0Y-FaG8aGv-KkzdRAamEAQ,18368
 CodeEntropy/trajectory/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 CodeEntropy/trajectory/frames.py,sha256=MSx_swzFjo4TgkZTR1y6W-1zuKNPg_C36I_uFqvOKpk,4354
-CodeEntropy/trajectory/mda.py,sha256=cWqgSgamdPnL4n3aWEKUgycjtzjpdgRgMVX6G5fln94,15803
+CodeEntropy/trajectory/mda.py,sha256=epKpAzxkNQi3rE7HJc_tsK_ZY4c575LdXmWewJoP1qE,16954
 CodeEntropy/trajectory/source.py,sha256=NfYsdm1amr29h2tmJP-RKyCp3phb1SOAtAELJmGm740,1475
-codeentropy-2.4.2.dist-info/entry_points.txt,sha256=8Oa3H9ErsrGtx5Hc6hIHOw73wK3Ylkvfgtl_4cBb_GU,52
-codeentropy-2.4.2.dist-info/licenses/LICENSE,sha256=hgMaAAVW1Q6dL586OHoz8vFO-6BYn-d2aAFBpVQylFc,1072
-codeentropy-2.4.2.dist-info/WHEEL,sha256=_yMHPaBV-s6fQMwUoo83NSdTCM3c8xXWFXRhqafN-7Y,81
-codeentropy-2.4.2.dist-info/METADATA,sha256=4OPOdf_Rgxt3pTbRbGiV0UznL2bUvKXPKlqw3X2hr48,6593
-codeentropy-2.4.2.dist-info/RECORD,,
+codeentropy-2.5.0.dist-info/entry_points.txt,sha256=8Oa3H9ErsrGtx5Hc6hIHOw73wK3Ylkvfgtl_4cBb_GU,52
+codeentropy-2.5.0.dist-info/licenses/LICENSE,sha256=hgMaAAVW1Q6dL586OHoz8vFO-6BYn-d2aAFBpVQylFc,1072
+codeentropy-2.5.0.dist-info/WHEEL,sha256=lqN8jXt_QloFOGcx9kStvWbryhfEXoI2F2z-YURm350,81
+codeentropy-2.5.0.dist-info/METADATA,sha256=OAUfGJ1rsObNQ9ftW76e4CZr3m6PFxG1ycdM6B5HdsI,6348
+codeentropy-2.5.0.dist-info/RECORD,,

{codeentropy-2.4.2.dist-info → codeentropy-2.5.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: flit 4.0.2
+Generator: flit 4.1.0
 Root-Is-Purelib: true
 Tag: py3-none-any