htpolynet 2.11.1__tar.gz → 2.11.2__tar.gz

{htpolynet-2.11.1 → htpolynet-2.11.2}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.11.2] - 2026-09-23
+
+### Fixed
+
+- **A ring cure near its target kept re-proposing the triples it had just declined.**
+  Declining a ring that the closure ladder could not pull shut leaves its three groups
+  unreacted, which is the point -- but the next search then offered the same groups,
+  ran the same eight-stage ladder, and declined them again.  htpolynet-study measured
+  the cost on a 2.11.1 build: at conversion 0.97 with 24 groups left, nine iterations
+  running produced 77 declines and not one ring, at about 67 s each.
+
+  A declined combination is now passed over while any untried ring is within the search
+  radius.  It is a preference and not a prohibition: that cure escaped on iteration 41
+  and finished at 0.971, because the relaxation between iterations moves the groups, so
+  a triple that failed once can still close later.  When the memory is the only thing
+  left keeping an iteration idle, the search lifts it and offers those rings again
+  rather than stand still.
+
 ## [2.11.1] - 2026-09-22
 
 ### Fixed

{htpolynet-2.11.1 → htpolynet-2.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.11.1
+Version: 2.11.2
 Summary: Automated MD System Builder for Amorphous Network Polymers
 Project-URL: Source, https://github.com/cameronabrams/htpolynet
 Project-URL: Documentation, https://htpolynet.readthedocs.io/

{htpolynet-2.11.1 → htpolynet-2.11.2}/ROADMAP.md

@@ -199,6 +199,24 @@ Coverage as of the last measurement: **38.8%** overall.
 
 ## Cure and repair
 
+- **A ring cure that stalls near its target has no exit but `max_iterations`.**
+  Reported by htpolynet-study 2026-09-23 from a 2.11.1 build: at conversion 0.97
+  with 24 groups left, nine iterations running (32-40) produced 77 declines and no
+  ring, about 67 s apiece.  2.11.1 now skips a triple it has already failed to
+  close, which removes most of that cost, but a cure with nothing closable left
+  still runs to `max_iterations` rather than stopping.
+
+  The obvious fix -- stop after N consecutive iterations that close nothing -- was
+  deliberately not taken, and the reason is worth keeping.  That build escaped on
+  iteration 41 and finished at 0.971, and it was the one of four that survived the
+  study's postcure anneal.  Any N below 9 would have ended it early.  A stall is
+  not evidence that a cure is finished: the inter-iteration relaxation keeps moving
+  the groups, so the escape is real and can be a long time coming.
+
+  If this is revisited, the test should be something that distinguishes "nothing is
+  closable" from "nothing closed this time" -- the trend in the ladder's final
+  distances across the stalled run, say, rather than a count of iterations.
+
 - **Filtering candidate crosslinks against disallowed topologies, and what that means
   for cyanate esters.**  Raised by Cameron 2026-09-21, who asked the right question:
   can "physically disallowable" even be defined for these systems?  Partly.  Three

{htpolynet-2.11.1 → htpolynet-2.11.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "htpolynet"
-version = "2.11.1"
+version = "2.11.2"
 authors = [
   { name="Cameron F Abrams", email="cfa22@drexel.edu" },
 ]

{htpolynet-2.11.1 → htpolynet-2.11.2}/src/htpolynet/cure/ringcontroller.py

@@ -33,6 +33,21 @@ from ..repair.topology_surgery import neutralize_touched_fragments
 logger = logging.getLogger(__name__)
 
 
+def _triple_key(donors):
+    """A ring's identity, in terms that survive from one iteration to the next.
+
+    A triple is held as row numbers into the site table, and that table is rebuilt
+    every iteration and shrinks as groups react, so those numbers name a different
+    ring next time.  The three donor atoms do not move: one per group, unique to it,
+    and fixed for the life of the system.
+
+    The two ring orientations deliberately share a key.  :func:`candidate_triples`
+    scores both and keeps the better one, so the orientation that was declined is the
+    better one, and the other would have farther to go.
+    """
+    return frozenset(int(d) for d in donors)
+
+
 class RingCureState:
     """How far a ring cure has got, and enough to resume it."""
 
@@ -93,6 +108,7 @@ class RingController:
         self.dicts = d
         self.state = state or RingCureState()
         self.rings_df = None
+        self.declined = set()
 
     # ---- what the loop decides, all of it testable without MD ----
 
@@ -172,16 +188,49 @@ class RingController:
             cands = candidate_triples(sites, positions, self.radius, box,
                                       same_molecule=self.dicts['same_molecule'],
                                       same_residue=self.dicts['same_residue'])
-            chosen = select_disjoint(cands, max_triples=self.dicts['max_rings_per_iteration'])
+            allowed = self._drop_declined(cands, sites)
+            chosen = select_disjoint(allowed, max_triples=self.dicts['max_rings_per_iteration'])
+            passed = len(cands) - len(allowed)
             logger.info(f'Iteration {self.state.iter}: {len(sites)} unreacted group(s), '
-                        f'{len(cands)} candidate ring(s) within {self.radius:.3f} nm, '
-                        f'{len(chosen)} accepted')
+                        f'{len(cands)} candidate ring(s) within {self.radius:.3f} nm'
+                        + (f' ({passed} passed over as already failed)' if passed else '')
+                        + f', {len(chosen)} accepted')
             if len(chosen) >= floor or self.radius >= self.dicts['max_radius']:
+                if not chosen and cands and self.declined:
+                    # the memory is now the only thing keeping this iteration idle, and
+                    # the groups have moved since they were declined; try them again
+                    logger.info(f'Iteration {self.state.iter}: every ring in reach has '
+                                f'failed before; forgetting {len(self.declined)} of them '
+                                f'and offering them again')
+                    self.declined.clear()
+                    chosen = select_disjoint(cands,
+                                             max_triples=self.dicts['max_rings_per_iteration'])
                 return sites, chosen
             self.state.radius_index += 1
             logger.info(f'Radius increased to {self.radius:.3f} nm '
                         f'({len(chosen)}/{floor} ring(s) so far)')
 
+    def _drop_declined(self, cands, sites):
+        """Passes over the triples this cure has already failed to pull shut.
+
+        A declined ring leaves its three groups unreacted by design, and the next search
+        offers them again -- so a rigid endgame proposes the same triples, runs the same
+        closure ladder, and declines them again.  Measured at conversion 0.97 with 24
+        groups left: nine iterations running, 77 declines, about 67 s apiece, before one
+        triple finally closed and the cure finished at 0.971.
+
+        A preference, not a prohibition, because the geometry between one decline and the
+        next search is not identical -- the inter-iteration relaxation moves the groups,
+        which is how that cure escaped.  Skipping a triple saves a ladder that would
+        almost certainly fail; refusing it outright would have ended that cure three
+        iterations early.  :meth:`search` therefore lifts the whole memory rather than
+        come back empty-handed.
+        """
+        if not self.declined:
+            return cands
+        return [c for c in cands
+                if _triple_key(sites.at[a, 'donor'] for a in c[1]) not in self.declined]
+
     def record(self, chosen):
         """Counts the rings formed and the groups they consumed."""
         self.state.rings += len(chosen)
@@ -244,6 +293,11 @@ class RingController:
         next iteration, by which time the neighbourhood has moved; only if they can never
         close does the cure lose them, which is the right outcome.
 
+        The combination itself is recorded for :meth:`_drop_declined`, which prefers not
+        to spend another ladder on it while any untried ring is in reach.  That is what
+        a rigid endgame otherwise does: nine iterations running, 77 declines, the same
+        few triples every time.
+
         Args:
             bdf (pandas.DataFrame): this iteration's bonds, three rows per ring
             work (pandas.DataFrame): the same pairs with their final distances
@@ -261,9 +315,11 @@ class RingController:
             return bdf, chosen
         for n in range(len(chosen)):
             if n not in keep:
+                self.declined.add(_triple_key(bdf[bdf['triple'] == n]['ai']))
                 logger.info(f'Iteration {self.state.iter}: declining a ring still '
                             f'{worst[n]:.3f} nm from closing (limit {limit:.3f} nm); its '
-                            f'groups stay unreacted and will be offered again')
+                            f'groups stay unreacted, and this combination waits until '
+                            f'nothing untried is in reach')
         renumber = {old: new for new, old in enumerate(keep)}
         bdf = bdf[bdf['triple'].isin(keep)].copy()
         bdf['triple'] = [renumber[t] for t in bdf['triple']]

{htpolynet-2.11.1 → htpolynet-2.11.2}/tests/unit/test_ringcontroller.py

@@ -12,7 +12,7 @@ import unittest
 import numpy as np
 import pandas as pd
 
-from htpolynet.cure.ringcontroller import RingController, RingCureState
+from htpolynet.cure.ringcontroller import RingController, RingCureState, _triple_key
 
 from .test_triplesearch import BOX, triangle
 
@@ -270,3 +270,90 @@ class TestDecliningRingsThatDidNotClose(unittest.TestCase):
         bdf, work, chosen = self.bonds_and_work([0.9])
         out_b, out_c = c.accept(bdf, work, chosen)
         self.assertEqual(len(out_c), 1)
+
+
+class TestATripleThatFailedIsNotTriedAgainWhileAnythingElseIsLeft(unittest.TestCase):
+    """A declined ring leaves its groups unreacted, so the next search offered the same
+    triples, ran the same ladder and declined them again: nine iterations running at
+    conversion 0.97, 77 declines, before one finally closed and the cure finished at
+    0.971.  The memory skips them; it does not forbid them, because that cure escaped
+    only because the geometry between iterations had moved."""
+
+    def bonds_and_work(self, worsts, donors=None):
+        """One ring per entry in `worsts`; `donors` gives each ring's three donor atoms."""
+        rows, final = [], []
+        for n, w in enumerate(worsts):
+            d = donors[n] if donors else [10 * n + k for k in range(3)]
+            for k in range(3):
+                rows.append({'ai': d[k], 'aj': 10 * n + k + 5, 'triple': n})
+                final.append(0.15 if k < 2 else w)
+        return (pd.DataFrame(rows),
+                pd.DataFrame({'final_distance': final}),
+                [object() for _ in worsts])
+
+    def two_triangles(self):
+        """Two rings far enough apart to be independent, and a controller that sees both."""
+        a1, p1 = triangle(side=0.2, resnums=(1, 2, 3), molecules=(1, 2, 3))
+        a2, p2 = triangle(side=0.2, resnums=(4, 5, 6), molecules=(4, 5, 6))
+        a2 = a2.copy()
+        a2['globalIdx'] += 100
+        p2 = {k + 100: v + np.array([2.0, 0.0, 0.0]) for k, v in p2.items()}
+        c = RingController({'search_radius': 0.6})
+        c.setup(total_groups=6, max_radius=1.0)
+        return c, pd.concat([a1, a2], ignore_index=True), {**p1, **p2}
+
+    def test_a_declined_ring_is_remembered_by_its_donor_atoms(self):
+        # row numbers into the site table name a different ring next iteration; the
+        # donors do not move
+        c = RingController({})
+        bdf, work, chosen = self.bonds_and_work([0.40], donors=[[7, 21, 34]])
+        with self.assertLogs(LOG, level='INFO'):
+            c.accept(bdf, work, chosen)
+        self.assertEqual(c.declined, {_triple_key([34, 7, 21])})
+
+    def test_a_ring_that_closed_is_not_remembered(self):
+        c = RingController({})
+        bdf, work, chosen = self.bonds_and_work([0.22])
+        c.accept(bdf, work, chosen)
+        self.assertEqual(c.declined, set())
+
+    def test_the_search_takes_the_other_ring_instead(self):
+        c, adf, pos = self.two_triangles()
+        with self.assertLogs(LOG, level='INFO'):
+            sites, chosen = c.search(adf, pos, BOX, 'BCY', (('N1', 'C1'),))
+        self.assertEqual(len(chosen), 2)
+        first = _triple_key(sites.at[a, 'donor'] for a in chosen[0][1])
+        c.declined.add(first)
+        with self.assertLogs(LOG, level='INFO') as cm:
+            sites, chosen = c.search(adf, pos, BOX, 'BCY', (('N1', 'C1'),))
+        self.assertEqual(len(chosen), 1)
+        self.assertNotEqual(_triple_key(sites.at[a, 'donor'] for a in chosen[0][1]), first)
+        self.assertIn('1 passed over as already failed', '\n'.join(cm.output))
+
+    def test_it_is_lifted_rather_than_leave_the_iteration_idle(self):
+        # the relaxation between iterations moves the groups, so a triple that failed
+        # can still close later -- one did, at iteration 41, and it finished that cure
+        adf, pos = triangle(side=0.25)
+        c = RingController({'search_radius': 0.6})
+        c.setup(total_groups=3, max_radius=1.0)
+        with self.assertLogs(LOG, level='INFO'):
+            sites, chosen = c.search(adf, pos, BOX, 'BCY', (('N1', 'C1'),))
+        c.declined.add(_triple_key(sites['donor']))
+        with self.assertLogs(LOG, level='INFO') as cm:
+            _, chosen = c.search(adf, pos, BOX, 'BCY', (('N1', 'C1'),))
+        self.assertEqual(len(chosen), 1)
+        self.assertEqual(c.declined, set())
+        self.assertIn('offering them again', '\n'.join(cm.output))
+
+    def test_both_orientations_share_one_key(self):
+        # candidate_triples scores both and keeps the better, so the declined one is
+        # the better one and the other has farther to go
+        self.assertEqual(_triple_key([3, 1, 2]), _triple_key([1, 2, 3]))
+
+    def test_a_ring_exactly_at_the_limit_is_kept(self):
+        # the log rounds to three decimals, so a decline reported at the limit was over it
+        c = RingController({'closure': {'max_accept': 0.30}})
+        bdf, work, chosen = self.bonds_and_work([0.30])
+        _, out_c = c.accept(bdf, work, chosen)
+        self.assertEqual(len(out_c), 1)
+        self.assertEqual(c.declined, set())