htpolynet 2.5.0__tar.gz → 2.6.0__tar.gz

{htpolynet-2.5.0 → htpolynet-2.6.0}/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-08-26
+
+### Fixed
+
+- **Transferred `-C#N` caps are no longer placed blind, which is what has been
+  killing low-conversion builds.**  The repair stage relocates a cap by
+  putting it along the bridge oxygen's old O-H vector, with no regard for
+  what is already there.  In a box at polymer density that direction is
+  usually occupied: in a synthetic 13000-atom box at 93 atoms/nm³, blind
+  placement put 91 of 158 caps within 0.10 nm of a neighbour and the worst at
+  0.008 nm -- effectively superimposed, which is the step-0 Lennard-Jones
+  term of order 1e15 that no minimization recovers from.
+
+  The cap is now still tried along the O-H vector first, so a cap in open
+  space lands exactly where it always did; only when that direction is
+  occupied does the driver search the sphere for the clearest one, holding
+  both bond lengths fixed so only the orientation moves.  Caps already placed
+  are part of the neighbourhood the next one sees.  On the same synthetic box
+  no cap lands closer than 0.128 nm, at either 158 or 378 transfers.
+
+  This matters more the lower the conversion, because the number of caps to
+  place is an identity -- `total reactive sites - bonds formed` -- so it rises
+  as conversion falls.  `completion_bias` does not reduce it.
+
+- **The stage now says how many fragments it transferred, and complains about
+  the ones it could not place well.**  The transfer count is the quantity that
+  predicts whether repair survives and it was buried in one mid-log INFO line;
+  it is now reported next to the conversion, along with the tightest placement
+  achieved.  A cap that could not reach `cap_min_clearance` (new, default
+  0.15 nm) in any direction is named, with its oxygen, while that is still
+  cheap to act on -- the alternative was working back to cap placement from a
+  GROMACS internal error at step 0.
+
+### Added
+
+- **`completion_bias` now says so when it is ranking the wrong side of the
+  reaction.**  The bias ranks on the `B` reactant, because htpolynet's A2+B3
+  idiom puts the crosslinker there.  Declare the crosslinker as `A` instead
+  and the bias quietly starts completing the *bridges* -- a different claim
+  about which partly-reacted species is a reactive intermediate, and almost
+  certainly not the one that was wanted.  The first cure iteration now
+  compares the initial functionality of the two sides and warns if the `A`
+  side is the more functional one.
+
+  Worth recording why the obvious detector does not work: looking for an
+  all-zero bias key catches nothing, because a difunctional bridge
+  accumulates reactions perfectly well and the key is non-zero.  What
+  separates the two cases is which side carries more reactive sites, and that
+  is readable straight off the atom dataframe -- forming a bond decrements an
+  atom's `z` and increments its `nreactions` in the same operation, so their
+  sum is conserved and reads the same at iteration 0 as at the end.
+
 ## [2.5.0] - 2026-08-26
 
 ### Added
@@ -48,12 +100,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   either side of the setting must be compared at matched crosslinker
   conversion, not matched `desired_conversion`.
 
-  It also nearly empties the repair stage, which is worth having on its own
-  terms: repair has been seen to blow up at low conversion, where it places
-  hundreds of caps and transfers hundreds of fragments and the cap-placement
-  geometry produces atom overlaps that a step-0 minimization cannot recover
-  from.  Completing crosslinkers instead of decorating them leaves it almost
-  nothing to do.
+  It also reduces the repair stage's dismantling work: at a bond conversion
+  of 0.90 the driver dismantles roughly 24 crosslinkers instead of 58, and
+  places 72 caps instead of 174.
+
+  **Corrected 2026-08-26, after this section was published:** the original
+  text here claimed the bias also relieves the cap-placement blowup that has
+  killed builds at low conversion.  It does not.  Only *transferred* caps are
+  placed geometrically -- `_place_cyn_along` runs solely where
+  `bonded_o is None` -- and the number of those is an identity,
+  `total_sites - bonds`, with no term for how the bonds are distributed.  So
+  the bias cannot change it at a matched bond conversion, and at a matched
+  crosslinker conversion it makes it *worse*, because it reaches that
+  conversion by forming fewer bonds and every bond not formed is a fragment
+  that must be transferred.  The blowup is a separate defect in
+  `repair/cyanate_cap.py`; see `ROADMAP.md`.
 
 - **A CUDA image, published as `ghcr.io/cameronabrams/htpolynet:cuda`.**  The
   only image until now installed conda-forge's default linux-64 Gromacs,

{htpolynet-2.5.0 → htpolynet-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.5.0
+Version: 2.6.0
 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.5.0 → htpolynet-2.6.0}/ROADMAP.md

@@ -171,12 +171,16 @@ Coverage as of the last measurement: **38.8%** overall.
   by how many bonds their `B`-side residue already carries, because
   htpolynet's A2+B3 idiom puts the multifunctional crosslinker in the `B`
   position -- as example 6 does. A user who declares the crosslinker as `A`
-  gets no bias at all, silently, because every candidate scores zero on a
-  difunctional bridge and the ordering collapses back to distance. The
-  generalization is small (rank on the `A` side, or on the sum of both) but
-  each variant is a different physical claim about which partly-reacted
-  species is an intermediate, and none of them has been run. Do it when
-  someone has a chemistry that needs it, and make them say which side.
+  gets the bias pointed at their *bridges* instead: not a no-op, a different
+  claim about which partly-reacted species is a reactive intermediate. That
+  case is now warned about at the first cure iteration, by comparing the
+  initial functionality of the two sides, so it is visible rather than silent
+  -- but it is still not *served*. The generalization is small (rank on the
+  `A` side, or on the sum of both) and each variant is a different physical
+  claim, none of them run. Do it when someone has a chemistry that needs it,
+  and make them say which side rather than inferring it from functionality:
+  the warning's heuristic is good enough to flag a probable mistake and not
+  good enough to silently redirect the ranking on.
 
 - **Nobody has run example 6 with `completion_bias` on.** The ranking is
   unit-tested -- ordering, tie-breaks, missing residues, the fallback when a
@@ -190,18 +194,20 @@ Coverage as of the last measurement: **38.8%** overall.
   truncation and that is where to look. Until someone runs it, the directive
   is documented as untested at scale.
 
-- **The repair stage's cap placement does not scale to low conversion.**
-  At a bond conversion of 0.90 the triazine-to-cyanate driver places on the
-  order of a hundred caps; at 0.30 it places hundreds and transfers hundreds
-  of fragments, and runs have died at the repair NVT with a step-0 potential
-  energy around 7e15 dominated by Lennard-Jones -- atom overlap from cap
-  placement. It is packing-dependent rather than systematic: siblings at the
-  same conversion survive. `completion_bias` makes the stage nearly empty
-  and so hides this, but the geometry is still wrong for a crowded box, and
-  a sub-gel-point study that wants the unbiased ranking will hit it again.
-  The fix is in `repair/cyanate_cap.py::_place_cyn_along` and the greedy
-  matcher around it: place against the local neighbourhood rather than along
-  the old O-H vector alone, or minimize incrementally as caps are placed.
+- **Cap placement is greedy and never backtracks.** Transferred `-C#N`
+  fragments are now placed against the local neighbourhood rather than blindly
+  along the old O-H vector, which removes the catastrophic overlaps: in a
+  synthetic box at polymer density, blind placement put 91 of 158 caps within
+  0.10 nm of a neighbour and the worst at 0.008 nm, while the neighbourhood
+  search puts none below 0.128 nm. What it does not do is relax. Each cap is
+  placed once, in the clearest direction available *at that moment*, and later
+  caps must work around it; in a genuinely over-packed box a residue of
+  sub-target placements remains (17 of 158, 33 of 378 in the same synthetic
+  test) and is reported rather than fixed. The next lever is minimizing
+  incrementally as caps land, or placing in order of how constrained each site
+  is rather than in match order. Do it if the reported clearance warnings turn
+  out to correlate with builds that still die -- the instrumentation to decide
+  that now exists, and did not before.
 
 - **`bdf.loc[:abs_max]` takes one bond more than the limit.** In
   `curecontroller.py::_searchbonds`, the truncation that applies

{htpolynet-2.5.0 → htpolynet-2.6.0}/docs/source/user-guide/configs/configs-for-run.rst

@@ -228,7 +228,7 @@ In this section we show all subdirectives for each of the five main directives i
 
       The ``min_bonds_per_iteration`` knob batches small late-stage finds together: instead of accepting whichever 1-2 bonds happen to lie within the initial 0.5 nm radius and immediately moving on to relax + equilibrate, the search grows the radius until at least 10 (the default) eligible bonds have been gathered.  On the DGEBA/PACM example, raising it from 1 to 10 cuts the cure iteration count from 41 to 15; raising further to 20 only buys one more iteration.  The default of 10 is roughly the diminishing-returns sweet spot.
 
-      ``completion_bias`` changes which bonds a CURE iteration chooses, and with it what ``desired_conversion`` means physically, so it is off by default and every shipped example runs without it.  Candidates are ranked by separation alone by default.  Separation is uncorrelated with how many bonds a crosslinker already carries, so in an A2+B3 system the bonds spread evenly across every ``B`` in the box rather than finishing any of them: at a bond conversion of 0.90, a trifunctional crosslinker placed at random is complete with probability 0.90\ :sup:`3`, about 0.73.  Turning ``completion_bias`` on makes the number of bonds already on the candidate's ``B``-side residue the primary sort key, with separation as the tie-break inside each group, so a crosslinker with two of three sites filled is finished before an untouched one is started.  Nothing else about the search changes -- same radius growth, same dragging and relaxation, same probabilities, same cycle handling.
+      ``completion_bias`` changes which bonds a CURE iteration chooses, and with it what ``desired_conversion`` means physically, so it is off by default and every shipped example runs without it.  Candidates are ranked by separation alone by default.  Separation is uncorrelated with how many bonds a crosslinker already carries, so in an A2+B3 system the bonds spread evenly across every ``B`` in the box rather than finishing any of them: at a bond conversion of 0.90, a trifunctional crosslinker placed at random is complete with probability 0.90\ :sup:`3`, about 0.73.  Turning ``completion_bias`` on makes the number of bonds already on the candidate's ``B``-side residue the primary sort key, with separation as the tie-break inside each group, so a crosslinker with two of three sites filled is finished before an untouched one is started.  The ``B`` side is where htpolynet's A2+B3 idiom puts the crosslinker; declare it as ``A`` instead and the bias completes your *bridges*, so the first cure iteration compares the two sides' functionality and warns if the more functional one is on ``A``.  Nothing else about the search changes -- same radius growth, same dragging and relaxation, same probabilities, same cycle handling.
 
       Which conversion this matters for depends on the chemistry.  Where a partly-reacted crosslinker is a real, stable species, the unbiased ranking is the more faithful one.  Where it is a reactive intermediate -- a cyclotrimerizing cyanate ester, whose triazine ring either closes or does not -- the biased ranking is, and the difference shows up directly in what :ref:`postcure repair <postcure_repair>` has to dismantle.  Note that the two settings reach different structures at the same ``desired_conversion``: a config that yields a crosslinker conversion of 0.76 at ``desired_conversion: 0.90`` unbiased will yield about 0.90 biased.  Comparisons across the setting have to be made at matched crosslinker conversion, not matched ``desired_conversion``.
 

{htpolynet-2.5.0 → htpolynet-2.6.0}/docs/source/user-guide/postcure-repair.rst

@@ -153,6 +153,7 @@ Spec fields
        cap_residue: CYN
        cap_template: BPA~O1-C1~CYN
        cap_search_radius: 0.6   # nm
+       cap_min_clearance: 0.15  # nm
 
 * ``crosslinker`` — names the trifunctional residue to be inspected.
   ``ring_carbon_atoms`` / ``ring_nitrogen_atoms`` give the
@@ -169,6 +170,17 @@ Spec fields
   types / charges / bonded interactions get spliced in for each
   bridge-O-to-cap-C bond.  ``cap_template`` is the ``product:`` field
   of a ``stage: repair`` reaction declared elsewhere in the YAML.
+* ``cap_min_clearance`` — how much room (nm) a transferred cap tries
+  to leave itself.  The cap is first placed along the bridge-O's old
+  O-H vector, as it always was; if that direction is already occupied
+  the driver searches the sphere for the clearest direction, holding
+  both bond lengths fixed so only the orientation moves, and stops as
+  soon as it reaches this clearance.  Default 0.15 nm, which is about
+  what a steepest-descent minimization absorbs and which is actually
+  achievable in a box at polymer density — 0.22 nm is not, and asking
+  for it would flag every cap.  When no direction reaches the target,
+  the driver says so and names the worst offenders; see
+  :ref:`what repair reports <postcure_repair_reporting>`.
 * ``cap_search_radius`` — radius (nm) within which a free-cap
   fragment looks for an unreacted bridge-O.  Expanded up to 10× on
   miss; falls back to globally nearest as a last resort.  Atom
@@ -322,6 +334,30 @@ directory, for reading across a series of runs:
      n_dismantled: 64
      crosslinker_conversion: 0.7333333333333333
 
+The stage also reports how many **cap fragments it transferred**, and
+how tightly they landed::
+
+    Repair transferred 158 cap fragments; tightest placement 0.128 nm
+
+That count is worth watching, because it is the quantity that predicts
+whether this stage survives.  It is an identity — every bond the cure
+did not form leaves a bridge site unreacted, and every unreacted
+bridge site receives one transferred fragment::
+
+    transferred fragments = total reactive sites - bonds formed
+
+so it *rises as conversion falls*, and a low-conversion build can be
+placing several hundred.  Each one is a two-atom group being dropped
+into an already-dense box.  If the following minimization dies with a
+Lennard-Jones term of order 1e15, this is where to look, and the
+warning about caps that could not reach ``cap_min_clearance`` names
+the specific oxygens involved.
+
+Note that this count depends only on the bond conversion, not on how
+the bonds are distributed, so ``completion_bias`` does not reduce it.
+At a *matched crosslinker conversion* the bias in fact increases it,
+because it reaches that conversion by forming fewer bonds.
+
 To *raise* the crosslinker conversion rather than merely report it,
 see the ``CURE.controls.completion_bias`` directive in
 :ref:`the run-configuration reference <cure.controls>`: it makes the

{htpolynet-2.5.0 → htpolynet-2.6.0}/pyproject.toml

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

{htpolynet-2.5.0 → htpolynet-2.6.0}/src/htpolynet/core/runtime.py

@@ -523,6 +523,15 @@ class Runtime:
             if bond_conversion is not None:
                 msg += f'; the cure reported a bond conversion of {bond_conversion:.3f}'
             my_logger(msg, logger.info)
+            # the transfer count is what predicts whether this stage survives,
+            # so it belongs next to the conversion rather than mid-log
+            if st.get('n_transferred'):
+                tmsg = f'Repair transferred {st["n_transferred"]} cap fragments'
+                if st.get('min_clearance_nm') is not None:
+                    tmsg += f'; tightest placement {st["min_clearance_nm"]:.3f} nm'
+                if st.get('n_below_target'):
+                    tmsg += f'; {st["n_below_target"]} below the clearance target'
+                my_logger(tmsg, logger.info)
         try:
             with open('repair-summary.yaml', 'w') as f:
                 yaml.dump(record, f, default_flow_style=False)

{htpolynet-2.5.0 → htpolynet-2.6.0}/src/htpolynet/cure/curecontroller.py

@@ -38,6 +38,22 @@ def residue_reaction_counts(adf):
     """
     return adf.groupby('resNum')['nreactions'].sum()
 
+def residue_functionality(adf):
+    """Counts, per residue, how many reactive sites it started with.
+
+    Forming a bond decrements an atom's 'z' and increments its 'nreactions' in
+    the same operation, so their sum is conserved per atom for the whole cure.
+    Summed over a residue it is that residue's initial functionality, and it
+    reads the same at iteration 0 as at the end.
+
+    Args:
+        adf (pandas.DataFrame): the global atom dataframe; must carry the 'resNum', 'z' and 'nreactions' attributes
+
+    Returns:
+        pandas.Series: initial reactive sites, indexed by residue number
+    """
+    return adf.groupby('resNum')[['z','nreactions']].sum().sum(axis=1)
+
 def rank_bond_candidates(bdf,reaction_counts=None):
     """Orders bond candidates ahead of the greedy one-bond-per-residue downselection.
 
@@ -212,6 +228,9 @@ class CureController:
                         self.dicts[k][kk]=vv
 
         self.chain_manager=None
+        # once-per-run: has the completion bias been checked against which side
+        # of the reaction actually carries the more functional residue?
+        self.bias_side_checked=False
         self.dragging_enabled=False
         d=self.dicts['drag']
         if (d['nstages']>0 or d['increment']>0.0) and d['limit']>0.0:
@@ -636,6 +655,33 @@ class CureController:
             return None
         return residue_reaction_counts(adf)
 
+    def _check_bias_side(self,adf,bdf):
+        """Warns, once per run, if the completion bias is ranking the less functional side.
+
+        The bias ranks on the ``B`` reactant because htpolynet's A2+B3 idiom
+        puts the crosslinker there.  Declare the crosslinker as ``A`` instead
+        and the bias silently starts completing the *bridges*, which is a
+        different claim about which species is a reactive intermediate and
+        almost certainly not the one that was wanted.  It cannot be caught by
+        looking for an all-zero bias key -- a difunctional bridge accumulates
+        reactions perfectly well, so the key is non-zero and the ranking looks
+        healthy.  What distinguishes the two cases is which side is the more
+        functional one, and that is fixed at setup.
+
+        Args:
+            adf (pandas.DataFrame): the global atom dataframe
+            bdf (pandas.DataFrame): the bond candidates for this iteration
+        """
+        if self.bias_side_checked: return
+        if not all(c in adf.columns for c in ('z','nreactions')): return
+        self.bias_side_checked=True
+        func=residue_functionality(adf)
+        a=bdf['ri'].map(func).dropna()
+        b=bdf['rj'].map(func).dropna()
+        if a.empty or b.empty: return
+        if a.max()>b.max():
+            logger.warning(f'completion_bias ranks candidates on the B-side residue, but the A side is the more functional one here ({int(a.max())} reactive sites vs {int(b.max())}). The bias will complete B-side residues, which is probably not what was intended; declare the crosslinker as the second reactant to bias toward it.')
+
     # TODO: move to searchbonds.by; split into make_candidates() and apply_filters()
     def _searchbonds(self,TC:TopoCoord,RL:ReactionList,MD:MoleculeDict,stage=reaction_stage.cure,abs_max=0,apply_probabilities=False,reentry=False):
         """Manages the search for bonds.
@@ -749,6 +795,7 @@ class CureController:
             reaction_counts=self._completion_bias_counts(adf)
             bdf=rank_bond_candidates(bdf,reaction_counts)
             if reaction_counts is not None:
+                self._check_bias_side(adf,bdf)
                 nrx=bdf['rj'].map(reaction_counts).fillna(0).astype(int)
                 logger.debug(f'Completion bias: {int((nrx>0).sum())} of {bdf.shape[0]} candidates extend an already-reacted B-side residue (most bonds already carried: {int(nrx.max())})')
             bdf['allowed']=[True for x in range(bdf.shape[0])]

{htpolynet-2.5.0 → htpolynet-2.6.0}/src/htpolynet/repair/cyanate_cap.py

@@ -106,6 +106,10 @@ def _place_cyn_along(bpa_o_xyz, bpa_o_h_xyz, oc_len=0.136, cn_len=0.116):
     direction from BPA-O toward the (about-to-be-deleted) H, so the new
     cap sticks out along the original O-H bond.
 
+    This is the unconditioned placement: it is where the cap goes if that
+    direction happens to be empty, and it is blind to whether it is.  See
+    :func:`_choose_cap_placement`, which uses it as its first candidate.
+
     Lengths in nm: standard -O-C ester ~1.36 A, -C#N ~1.16 A.
     Returns (C_xyz, N_xyz).
     """
@@ -122,12 +126,140 @@ def _place_cyn_along(bpa_o_xyz, bpa_o_h_xyz, oc_len=0.136, cn_len=0.116):
     return c_xyz, n_xyz
 
 
+_PLACEMENT_LOCALITY = 0.8
+"""nm: an atom farther than this from the target oxygen cannot constrain a cap
+that reaches only ~0.25 nm from it, so it is not scored against."""
+
+
+def _report_placements(placements, target):
+    """Say how well the transferred caps landed, and complain about the tight ones.
+
+    The transfer count is the quantity that predicts whether this stage will
+    survive, so it is stated plainly rather than left to be inferred, and a
+    placement that could not reach the target clearance is named while it is
+    still cheap to act on -- the alternative is reading it back out of a
+    Lennard-Jones term at step 0.
+
+    Args:
+        placements (list): one dict per transferred cap, with 'o' and 'clearance'
+        target (float): the clearance in nm that was being aimed for
+
+    Returns:
+        dict: n_transferred, n_direction_searched, n_below_target, min_clearance_nm
+    """
+    if not placements:
+        return {'n_transferred': 0, 'n_direction_searched': 0,
+                'n_below_target': 0, 'min_clearance_nm': None}
+    gaps = np.array([p['clearance'] for p in placements], dtype=float)
+    searched = sum(1 for p in placements if not p['kept_o_h_direction'])
+    below = [p for p in placements if p['clearance'] < target]
+    logger.info(
+        f'triazine_to_cyanate_cap: placed {len(placements)} transferred caps '
+        f'({searched} needed a direction search); clearance min/median '
+        f'{gaps.min():.3f}/{float(np.median(gaps)):.3f} nm against a target of {target:.3f}'
+    )
+    if below:
+        worst = sorted(below, key=lambda p: p['clearance'])[:5]
+        detail = ', '.join(f'O {int(p["o"])} at {p["clearance"]:.3f} nm' for p in worst)
+        logger.warning(
+            f'triazine_to_cyanate_cap: {len(below)} of {len(placements)} transferred '
+            f'caps could not reach {target:.3f} nm of clearance in any direction '
+            f'(worst: {detail}). The box is too crowded here for this many caps; '
+            f'if the following minimization fails with a huge Lennard-Jones term, '
+            f'this is why.'
+        )
+    return {
+        'n_transferred': len(placements),
+        'n_direction_searched': searched,
+        'n_below_target': len(below),
+        'min_clearance_nm': float(gaps.min()),
+    }
+
+
+def _sphere_directions(n=48):
+    """``n`` roughly uniform unit vectors on the sphere, deterministically.
+
+    A Fibonacci spiral: no randomness, so a rebuild of the same system places
+    its caps identically.
+
+    Args:
+        n (int): how many directions to generate
+
+    Returns:
+        numpy.ndarray: (n, 3) array of unit vectors
+    """
+    k = np.arange(n) + 0.5
+    phi = np.arccos(1.0 - 2.0 * k / n)
+    theta = np.pi * (1.0 + 5.0 ** 0.5) * k
+    return np.stack([np.cos(theta) * np.sin(phi),
+                     np.sin(theta) * np.sin(phi),
+                     np.cos(phi)], axis=1)
+
+
+def _clearance(c_xyz, n_xyz, neighbors, box):
+    """Smallest distance from either cap atom to any neighbouring atom.
+
+    Args:
+        c_xyz (numpy.ndarray): position of the cap carbon
+        n_xyz (numpy.ndarray): position of the cap nitrogen
+        neighbors (numpy.ndarray): (m, 3) positions to stay clear of
+        box (numpy.ndarray): orthorhombic box lengths, for minimum image
+
+    Returns:
+        float: the smallest such distance in nm, or inf if there are no neighbours
+    """
+    if neighbors is None or len(neighbors) == 0:
+        return float('inf')
+    return float(min(_min_image_dist(c_xyz, neighbors, box).min(),
+                     _min_image_dist(n_xyz, neighbors, box).min()))
+
+
+def _choose_cap_placement(o_xyz, ref_xyz, neighbors, box, oc_len=0.136,
+                          cn_len=0.116, target=0.15, n_directions=48):
+    """Place a transferred -C#N group in the clearest direction available.
+
+    The old O-H vector is tried first and kept if it is clear enough, so a
+    cap in open space lands exactly where it always did.  Only when that
+    direction is occupied does this search the sphere -- which is the case
+    that used to produce a step-0 Lennard-Jones term around 1e15 and a
+    minimization that could not recover.  Bond lengths are held fixed; only
+    the direction moves, so the chemistry is unchanged.
+
+    Args:
+        o_xyz (numpy.ndarray): position of the bridge oxygen the cap attaches to
+        ref_xyz (numpy.ndarray): position defining the preferred direction, normally the O's about-to-be-deleted H
+        neighbors (numpy.ndarray): (m, 3) positions the cap must avoid
+        box (numpy.ndarray): orthorhombic box lengths, for minimum image
+        oc_len (float): O-C bond length in nm
+        cn_len (float): C#N bond length in nm
+        target (float): clearance in nm that counts as good enough to stop searching; the default 0.15 is about what a steepest-descent minimization absorbs without trouble, and is achievable in a box at polymer density -- 0.22 is not, and asking for it would flag every cap
+        n_directions (int): how many directions to try when the preferred one is occupied
+
+    Returns:
+        tuple: (C position, N position, achieved clearance in nm, whether the preferred direction was kept)
+    """
+    o = np.asarray(o_xyz, dtype=float)
+    c_xyz, n_xyz = _place_cyn_along(o, ref_xyz, oc_len=oc_len, cn_len=cn_len)
+    best = _clearance(c_xyz, n_xyz, neighbors, box)
+    if best >= target:
+        return c_xyz, n_xyz, best, True
+    for u in _sphere_directions(n_directions):
+        cc = o + u * oc_len
+        nn = cc + u * cn_len
+        gap = _clearance(cc, nn, neighbors, box)
+        if gap > best:
+            best, c_xyz, n_xyz = gap, cc, nn
+            if best >= target:
+                break
+    return c_xyz, n_xyz, best, False
+
+
 # ---------------------------------------------------------------------------
 # Main driver
 # ---------------------------------------------------------------------------
 
 
-def _completion_stats(residue_name, n_crosslinkers, n_incomplete, log=True):
+def _completion_stats(residue_name, n_crosslinkers, n_incomplete, log=True, placement=None):
     """Summarize crosslinker completion and log it.
 
     A crosslinker survives this repair only if every one of its sites is
@@ -142,6 +274,7 @@ def _completion_stats(residue_name, n_crosslinkers, n_incomplete, log=True):
         n_crosslinkers (int): number of crosslinker residues in the system
         n_incomplete (int): how many of them are being dismantled
         log (bool): emit the summary message; False when there is nothing to summarize
+        placement (dict): cap-placement summary from :func:`_report_placements`, merged into the result
 
     Returns:
         dict: n_crosslinkers, n_complete, n_dismantled, crosslinker_conversion
@@ -154,13 +287,16 @@ def _completion_stats(residue_name, n_crosslinkers, n_incomplete, log=True):
             f'{residue_name} residues are complete and survive repair; '
             f'crosslinker conversion {chi:.3f}'
         )
-    return {
+    out = {
         'residue': residue_name,
         'n_crosslinkers': n_crosslinkers,
         'n_complete': n_complete,
         'n_dismantled': n_incomplete,
         'crosslinker_conversion': chi,
     }
+    if placement:
+        out.update(placement)
+    return out
 
 
 def triazine_to_cyanate_cap(TC, moldict, spec, reactions):
@@ -287,34 +423,60 @@ def triazine_to_cyanate_cap(TC, moldict, spec, reactions):
             ts.reassign_residue(TC, [cap['c'], cap['n']], cap_residue_name, new_resnum)
             ts.set_atom_attributes(TC, cap['c'], atomName='C1')
             ts.set_atom_attributes(TC, cap['n'], atomName='N1')
-            cap_records.append({'c': cap['c'], 'n': cap['n'], 'o': target_o, 'resnum': new_resnum})
+            cap_records.append({'c': cap['c'], 'n': cap['n'], 'o': target_o,
+                                'resnum': new_resnum, 'free': cap['bonded_o'] is None})
             new_resnum += 1
 
     # 3d. for free-cap donations: relocate the CYN atoms next to their target O
-    for rec in cap_records:
-        cap_in_plans = next(
-            (c for p in incomplete_plans for c in p['caps']
-             if c['c'] == rec['c'] and c['n'] == rec['n']),
-            None,
-        )
-        if cap_in_plans is None or cap_in_plans['bonded_o'] is not None:
-            continue
-        o_idx = rec['o']
-        o_xyz = ts.positions(TC, [o_idx])[0]
-        # use the (about-to-be-deleted) H on the O as the direction reference
-        o_h_idx = _find_bonded_hydrogen(TC, o_idx)
-        if o_h_idx is None:
-            # no H to use as reference (shouldn't happen for a still-reactive O,
-            # but if it does, just push the cap along +x by the rest length)
-            ref_xyz = o_xyz + np.array([1.0, 0.0, 0.0])
-        else:
-            ref_xyz = ts.positions(TC, [o_h_idx])[0]
-            h_to_delete.add(int(o_h_idx))
-        c_xyz, n_xyz = _place_cyn_along(o_xyz, ref_xyz)
-        ts.set_atom_attributes(TC, rec['c'],
-                               posX=float(c_xyz[0]), posY=float(c_xyz[1]), posZ=float(c_xyz[2]))
-        ts.set_atom_attributes(TC, rec['n'],
-                               posX=float(n_xyz[0]), posY=float(n_xyz[1]), posZ=float(n_xyz[2]))
+    #
+    # This is the phase that fails catastrophically when it fails at all.  A
+    # cap dropped blindly along the old O-H vector can land on top of a
+    # neighbour, and the resulting step-0 Lennard-Jones term -- of order 1e15
+    # kJ/mol -- is not something the following minimization recovers from.
+    # The count of caps to place here is an identity, (total reactive sites -
+    # bonds formed), so it rises as conversion falls: a low-conversion build
+    # places hundreds and is where this has been seen to kill runs.
+    #
+    # So each cap is placed against its local neighbourhood, and every cap
+    # already placed is part of the neighbourhood the next one sees.
+    free_records = [rec for rec in cap_records if rec['free']]
+    placements = []
+    placement_summary = None
+    if free_records:
+        box = TC.Coordinates.box.diagonal()
+        target_clearance = float(spec.get('cap_min_clearance', 0.15))
+        # the O's H is consumed in forming the cap; collect them all up front
+        # so that a cap placed early does not dodge an atom about to vanish
+        for rec in free_records:
+            h = _find_bonded_hydrogen(TC, rec['o'])
+            rec['o_h'] = h
+            if h is not None:
+                h_to_delete.add(int(h))
+        moving = {int(rec['c']) for rec in free_records} | {int(rec['n']) for rec in free_records}
+        A = TC.Coordinates.A
+        going = moving | {int(x) for x in h_to_delete}
+        background = A.loc[~A['globalIdx'].isin(going),
+                           ['posX', 'posY', 'posZ']].to_numpy(dtype=float)
+        for rec in free_records:
+            o_xyz = ts.positions(TC, [rec['o']])[0]
+            if rec['o_h'] is None:
+                # no H to take a direction from (shouldn't happen for a
+                # still-reactive O); any direction will do as a starting guess
+                ref_xyz = o_xyz + np.array([1.0, 0.0, 0.0])
+            else:
+                ref_xyz = ts.positions(TC, [rec['o_h']])[0]
+            # only atoms near this O can constrain a group that reaches
+            # 0.25 nm from it; the rest are not worth scoring against
+            local = background[_min_image_dist(o_xyz, background, box) < _PLACEMENT_LOCALITY]
+            c_xyz, n_xyz, gap, kept = _choose_cap_placement(
+                o_xyz, ref_xyz, local, box, target=target_clearance)
+            ts.set_atom_attributes(TC, rec['c'],
+                                   posX=float(c_xyz[0]), posY=float(c_xyz[1]), posZ=float(c_xyz[2]))
+            ts.set_atom_attributes(TC, rec['n'],
+                                   posX=float(n_xyz[0]), posY=float(n_xyz[1]), posZ=float(n_xyz[2]))
+            background = np.vstack([background, c_xyz, n_xyz])
+            placements.append({'o': rec['o'], 'clearance': gap, 'kept_o_h_direction': kept})
+        placement_summary = _report_placements(placements, target_clearance)
 
     # ---- Phase 4: splice template params (forms BPA-O-C bond with full
     # angle/dihedral/pair entries from the cap_template molecule) ----
@@ -362,7 +524,8 @@ def triazine_to_cyanate_cap(TC, moldict, spec, reactions):
                 msg='triazine_to_cyanate_cap post-deletion rebalance',
             )
 
-    return _completion_stats(cl['residue'], len(cl_residues), len(incomplete_plans))
+    return _completion_stats(cl['residue'], len(cl_residues), len(incomplete_plans),
+                             placement=placement_summary)
 
 
 # ---------------------------------------------------------------------------