htpolynet 2.11.3__tar.gz → 2.11.4__tar.gz

{htpolynet-2.11.3 → htpolynet-2.11.4}/CHANGELOG.md

@@ -7,6 +7,173 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.11.4] - 2026-09-26
+
+### Added
+
+- **A file of your own that replaces a packaged one now says so.**  `pfs.checkout`
+  searches the user library, then the user cache, then what htpolynet ships, and took
+  the first hit silently.  Overriding a packaged file is supported and often the point;
+  the trap is that a copy taken from an older version keeps that version's settings for
+  as long as it stays on the search path, and nothing said which file a run actually
+  used.
+
+  Found the hard way.  A study's `npt.mdp`, copied from 2.6.2 and edited in one place,
+  stayed on its path across four upgrades.  From 2.7.0 the packaged file sets
+  `lincs_order = 8`, because at `dt = 0.002` GROMACS' default of 4 is marginal --- it
+  was fatal on one chemistry in 7 of 7 builds, with exit codes 1 and 139.  The stale
+  copy reverted every run to order 4, and the instability that produced was written up
+  for weeks as a property of the systems being built.
+
+  **This bears on the 2.11.3 notes below.**  "Eleven of twenty builds died in the
+  anneal" is the rate from builds carrying that stale mdp, so it overstates what the
+  unrelaxed final batch alone causes.  The defect and the remedy are unaffected: the
+  bond energies entering the anneal are single-point energies of the structure and owe
+  nothing to integration settings, and the paired seed test showed the settle helping
+  even at LINCS order 4.  Only the headline failure rate is in doubt.
+
+
+- **A ring cure now refuses a ring that would close around an existing bond.**  CURE
+  tests every candidate bond for piercing an existing ring; the ring cure has the
+  converse problem and tested nothing at all --- `ringcontroller.py` had no reference to
+  `bondtest`, `pierces_ring` or `BTRC`.  A triazine could therefore form *around* a
+  monomer that was already there and thread it permanently.
+
+  That is what the stretched monomers were.  Over ten finished builds, six carried a
+  threaded triazine, and the threading bonds are the same bonds found stretched past
+  2 A: 15 stretched, 13 threading, none threading without being stretched.  10 of 11
+  were pre-existing monomer backbone bonds.  It explains why those bonds sit on monomers
+  that took no part in the ring, why a 160 ps anneal left them unchanged to two
+  decimals, and why they hold roughly 700 kT without being thermal --- escaping a
+  topological trap needs a bond to break, not a barrier to be crossed.
+
+  The test runs after the closure ladder and before the bonds are formed, which is
+  where the question is unambiguous: the loop is down to nearly its final size, so what
+  is inside it is what the triazine will enclose.  It treats the loop as a triangle fan
+  from its centroid rather than as a plane, and images every coordinate against an
+  anchor atom, since a centroid of raw wrapped positions gives false positives across a
+  periodic boundary.
+
+  `ring_cure.prefilter_threaded_candidates` applies the same test at candidate time as
+  well, to avoid spending a ladder on a ring that is already threaded.  It is **off by
+  default**, because a candidate loop is three groups a search radius apart: a formed
+  triazine's circumscribed radius is about 1.37 A and near enough rigid across 233 of
+  them, while the candidate loop encloses roughly nine times that area at a 1.0 nm
+  search radius and over twenty at 1.6 nm, which is where late iterations run.
+  Threading would carry through the shrink if nothing moved, but the ladder runs six
+  stages of NVT at 600 K, so a bond inside the candidate loop need not still be inside
+  at closure.  Set `ring_cure.reject_threaded_rings: false` to reproduce the old
+  behavior entirely.
+
+  **Measured across three arms, same image, no mdp override.**  Filtered builds came out
+  clean 6 of 6; unfiltered builds carried a pierced triazine in 2 of 4 --- 4, 2, 0 and 0
+  piercings, a mean of 1.5 each.  There is no conversion cost: 0.971 to 0.983 in 21 to
+  23 iterations against 0.971 to 0.979 in 20 to 22 without it.
+
+  The closure-time test declined 2, 10 and 1 candidates across three builds, a mean of
+  4.3 against those 1.5 piercings.  Same order of magnitude with overlapping
+  distributions, and that is as much as the data supports: at three builds against four
+  the smallest two-sided Mann-Whitney p obtainable is 0.057, so the observed 0.47 is no
+  more evidence of agreement than of excess.  The two are not the same quantity either
+  --- a declined candidate is one that *would* have threaded, and the alternative
+  `select_disjoint` takes instead may itself thread and be declined in turn, so declines
+  bound the piercings prevented rather than counting them.
+
+  The candidate-time prefilter is a different matter: it discarded 1216 to 4385
+  candidates per build to catch what the closure test catches in single digits, and both
+  arms finished equally clean --- which is why it stays off by default.
+
+### Fixed
+
+- **A ring cure ran at constant volume from first ring to last, so it could not
+  densify.**  Every ring-cure stage was NVT — the relaxation after each iteration, the
+  closure ladder, and the settle — with no constant-pressure step anywhere.  Measured
+  over 22 iterations of a 233-triazine build, the box stayed at 5.241 nm to four
+  decimals and the density at 1155.9 kg/m3 from the first ring to the last, with the
+  entire volume change deferred to a single postcure NPT.  CURE's density climbs
+  through its cure, roughly 1085 to 1170, because its relaxation stages run NPT above
+  Tg and are deliberately "the only above-Tg constant-pressure time in a cure".
+
+  Cure shrinkage cannot be reproduced at fixed volume by construction — Snow measures
+  0.0324 ml/g for BADCy — and a network that forms in a box which cannot respond
+  accumulates internal stress with nowhere to put it, which is a plausible route to the
+  stretched bonds recorded in `ROADMAP.md`.
+
+  `ring_cure.relax` now mirrors CURE's `relax.equilibration` exactly --- minimization,
+  NVT at 600 K, then NPT at 600 K and 1 bar --- rather than CURE's much longer
+  per-iteration equilibration.  The whole sequence is above Tg, not just the
+  constant-pressure stage: relaxing at 300 K in between two 600 K closure ladders cooled
+  the network and would have put a cold, less mobile configuration under the barostat,
+  which is a good way to measure no densification and wrongly conclude the stage does
+  not work.  The closure ladder itself stays constant-volume on purpose: NPT while
+  restraints are actively pulling groups together is not a stable combination.
+
+- **A ring cure had no cold equilibration, so once it could move, its box only grew.**
+  Adding the constant-pressure relax stage above let the box respond, but `relax` ends
+  hot.  Measured with relax alone over a full build, the box expands thermally for six
+  iterations to +27.9% in volume, then comes back down as the network forms: peak to
+  minimum is -7.49% in volume and +71.9 kg/m3.  The two legs nearly cancel, so the net
+  is near zero and the path length is 0.4104 nm --- a frozen box captures none of it.
+
+  That descending leg is not a measurement of cure shrinkage: 2 ps at 600 K does not
+  equilibrate, so it mixes in residual thermal relaxation, and it spans conversion 0.55
+  to 0.971.  It costs iterations too --- `search_radius` is an absolute length and does
+  not scale with the box, so an expanded box encloses fewer groups per sphere, and the
+  hot-only arm needed 25 iterations against 22 for the same conversion.  A cure is not only shrinkage --- the hot stages enlarge
+  the box and a cold stage pulls it back, and on the pairwise route the box travels
+  three to nine times further in length than it ends up moving.
+
+  `ring_cure` now has an `equilibrate` stage identical in shape and in defaults to
+  `CURE.equilibrate` --- NPT, 300 K, 1 bar, 50000 steps of 2 fs --- run once per
+  iteration after `relax`, through the same code path the pairwise cure uses, so it
+  picks up that route's box logging and density series rather than reimplementing them.
+  The per-iteration shape of the two cures is now the same.
+
+  It is also the expensive stage, roughly 99 s against a 280 s iteration.  Whether
+  100 ps is the right number for *either* route has never been measured; `ROADMAP.md`
+  sketches the study.
+
+- **Three `ring_cure` settings could not be set at all**, because they were missing from
+  the schema, and ycleptic rejects an unknown key outright rather than ignoring it.
+  `ring_cure.relax` and `ring_cure.closure.equilibration` were never exposed, and
+  `closure.max_accept` — added in 2.11.1 — was written into `CURE`'s `drag` block by
+  mistake, where a config could set it and nothing would read it.  All three now sit
+  where they belong, and a test asserts that every key the controller honors appears in
+  the schema with a matching default.
+
+### Changed
+
+- **The installation page now says not to install `htpolynet` from conda-forge.**  The
+  package published there is several releases behind and cannot currently be updated:
+  `htpolynet` depends on `ycleptic`, which is not yet available on conda-forge, so the
+  feedstock's automatic version bumps produce a package that cannot import and none has
+  been published.  What is on conda-forge does install and run, so nothing warns a user
+  that they have an old `htpolynet`.
+
+  The conda-only recipe now installs Python and the MD binaries from conda-forge and
+  `htpolynet` itself from PyPI.  The warning is scoped to the `htpolynet` package alone
+  --- conda-forge remains the recommended source for AmberTools and Gromacs --- and it
+  gives the two commands to check the current state rather than asking the reader to
+  trust a page that may itself be stale.  The container remains the recommendation, and
+  the page now says outright that it requires no installation at all.
+
+### Added
+
+- **A build now says so when it hands on a bond that is not a bond any more.**  At the
+  end of a ring cure and again in the final data, any bond longer than 0.2 nm is
+  reported, the worst named by atom and residue.  Lengths use the minimum-image
+  convention, so a bond across a periodic boundary is not counted.
+
+  This exists because such a bond is otherwise silent: the topology is valid, every
+  molecule is neutral, and the run completes.  htpolynet-study measured a C-C at 3.20 A
+  in two of five *final* structures, unchanged to two decimals by a 160 ps anneal.  Ring
+  bonds always relaxed; these did not, because they are held by network tension rather
+  than by thermal motion — a monomer stretched between parts of the network that a ring
+  closure pulled apart, in a ring it was not itself part of.
+
+  This is detection and not a fix; `ROADMAP.md` has the mechanism and why no remedy has
+  been chosen.  Anything computed from a structure carrying such a bond inherits it.
+
 ## [2.11.3] - 2026-09-23
 
 ### Fixed

{htpolynet-2.11.3 → htpolynet-2.11.4}/PKG-INFO

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

@@ -199,6 +199,173 @@ Coverage as of the last measurement: **38.8%** overall.
 
 ## Cure and repair
 
+- **Nobody has ever checked whether the intra-cure MD stages do anything, and they are
+  most of the cost.**  Raised by Cameron 2026-09-24: the annealing and relaxation runs
+  inside a cure were chosen arbitrarily and have never been justified by a convergence
+  study.  The budget, per cure iteration, from the shipped defaults:
+
+        CURE        relax.equilibration   6 stages x (min + 1 ps NVT 600 + 2 ps NPT 600)   18 ps
+                    equilibrate           1 x NPT 300 K, 50000 steps x 2 fs               100 ps
+                    drag.equilibration    disabled by default (trigger_distance 0.0)         --
+                                                                                  total ~118 ps
+
+        ring cure   closure.equilibration 8 stages x (min + 1 ps NVT 600)                   8 ps
+                    relax                 min + 1 ps NVT 600 + 2 ps NPT 600                 3 ps
+                                                                                   total ~11 ps
+
+  **85% of CURE's intra-cure MD is the single 100 ps `equilibrate`**, and nothing
+  records what it accomplishes.  Note also the order-of-magnitude asymmetry between the
+  two routes, which nobody chose deliberately either.
+
+  **Why it cannot be answered today.**  `profiling.stage` wraps whole phases and whole
+  iterations, not individual `grompp_and_mdrun` calls, so there is no per-stage wall
+  time.  And no stage records the quantity it exists to move, so "did it converge" is
+  not answerable from any existing output.  One exception worth knowing: the ring
+  closure ladder already logs its max pair distance per stage at DEBUG
+  (`ringcontroller.py`, "ring-close stage"), so that ladder's convergence can be audited
+  from a run with debug logging and no new code at all.
+
+  **A study, in four parts.**
+
+  *0. Instrument.*  Extend profiling to wrap each `grompp_and_mdrun` so `profile.json`
+  carries per-stage wall time, and have each stage record the observable it is supposed
+  to move: box and density against time for anything NPT (from the `.edr`, so the
+  within-stage trajectory is available and not just the endpoint), new-bond length
+  against its attenuated `b0` for `relax`, max pair distance for the ring ladder.  This
+  is the only part that is repo work; it is small, and everything else depends on it.
+
+  *1. Convergence audit.*  One CURE build and one ring-cure build at stock settings.
+  One data point already exists and it cuts against the cheap end of the range: 2 ps of
+  NPT per iteration does not converge a ring cure's box at all (see the constant-volume
+  entry above), so the audit should expect the answer to be tens of ps rather than
+  single digits, and should sample within a stage rather than only at its end.
+  For each stage ask a single question: at what fraction of its length does the
+  observable stop changing?  A 100 ps equilibration whose density plateaus at 20 ps is
+  five times longer than it needs to be, and that is measurable once, cheaply, rather
+  than argued about.
+
+  *2. Truncation sweep.*  For every stage that converges early, halve and quarter it.
+
+  *3. Null arm.*  Remove the stage outright.  This is the actual test of Cameron's
+  question --- a stage whose removal changes nothing downstream is not earning its
+  keep, however well it converges.
+
+  **Fix the acceptance criteria before running anything**, because every one of these
+  arms will produce a build that looks fine.  Proposed: final density within a stated
+  tolerance of the stock build; conversion-against-iteration curves overlapping; no
+  increase in bonds beyond 0.2 nm as counted by `Runtime._report_overlong_bonds`; no
+  increase in postcure anneal failures across a fixed set of velocity seeds; and total
+  wall time, which is the point.  Deciding those numbers afterwards is how a cheaper
+  cure gets declared equivalent because it did not obviously break.
+
+  **Who runs it.**  The instrumentation is repo work.  The builds are not --- example
+  builds belong to htpolynet-sweep, and a cure-physics comparison of this kind is the
+  study's kind of work.  The ring-cure NPT A/B of 2026-09-24 is the first instance of
+  exactly this pattern and its design is worth copying: two arms differing in one stage
+  list, same pinned image, both arms written out explicitly so neither inherits a
+  default that might move underneath the comparison.
+
+- **The ring cure has no cold equilibration stage, so its box cannot breathe the way
+  CURE's does.**  As of 2.11.4 `ring_cure.relax` ends with NPT at 600 K, which is what
+  lets the box respond at all.  CURE has that *and* a separate per-iteration
+  `equilibrate` --- NPT at 300 K for 50000 steps, 100 ps --- which the ring cure has no
+  equivalent of.  So the ring cure equilibrates hot and never gets pulled back cold.
+
+  Cameron's observation is that a cure is not only shrinkage: the 600 K stages enlarge
+  the box and the 300 K equilibration pulls it back, so the box cycles every iteration.
+  htpolynet-study measured the cycle on three A2+B3 surrogates, at the cold checkpoints
+  only --- the 600 K stages log no box at all, so the real amplitude is larger:
+
+        build   iters   rises   largest rise      net   path length
+        r1         17       6        +0.0120   -0.0430        0.1450
+        r2         16       5        +0.0140   -0.0420        0.1360
+        r3         16       8        +0.0260   -0.0240        0.2100
+
+  The box travels three to nine times further than it ends up moving.  A ring cure over
+  22 iterations had a path length of exactly 0.0000 nm.
+
+  **Deliberately deferred, and by whom.**  Presented with the choice between mirroring
+  CURE's `relax.equilibration` and mirroring its full `equilibrate`, Cameron chose the
+  cheaper one.  The A/B measuring whether it suffices is what should settle this; 100 ps
+  per iteration against a 150-iteration cap is not a cost to take on speculatively.
+
+  **MEASURED 2026-09-24, and the cheap shape is not enough.**  A two-arm A/B, both arms
+  on the same pinned image, differing only in the relax stage list:
+
+        arm        box (nm), successive iterations   rho (kg/m3)     path
+        npt r1     5.5566 -> 5.6882                  970 -> 904    0.1315
+        npt r2     5.5977 -> 5.6553 -> 5.6614        949 -> 917    0.0637
+        control    5.2382 / 5.2435, unchanged x3     1157 / 1154   0.0000
+        baseline   5.2405                            1156.0        0.0000
+
+  The control arms are frozen to five decimals, which establishes that the constant
+  volume was the relax stage list alone and nothing else that changed between 2.11.1
+  and 2.11.4.
+
+  **Read the whole run, not its first quarter.**  Over a complete 25-iteration build the
+  hot-only box has two regimes, and only the first was visible early:
+
+        iter     1      6     12     18     21     24     25
+        box   5.5977 5.7223 5.6639 5.6701 5.6442 5.5757 5.5939
+        rho    948.5  887.9  915.6  912.7  925.3  959.8  950.4
+                                      path 0.4104 nm, net -0.0038 nm
+
+  Thermal expansion to iteration 6, then the box comes back **down** as the network
+  forms: peak to minimum is -7.49% in volume, +71.9 kg/m3, 0.0844 ml/g.  The net is
+  near zero only because the two legs nearly cancel, which is exactly why path length
+  rather than net is the statistic to quote.  A frozen box captures none of it.
+
+  This retires two judgements made on the first four iterations --- mine, that a
+  still-expanding box was "differently wrong", and the reading that the climb had no
+  bound.  Nor is there a conversion ceiling: the hot-only arm finished at 233 rings and
+  conversion 0.971, the same endpoint as both controls and the baseline, in 25
+  iterations against 22.  The 0.09-0.10 conversion deficit at matched iteration is real
+  but is a **rate** effect worth about 14% in iterations, not a limit.  Its mechanism is
+  worth keeping: ``search_radius`` is an absolute length and does not scale with the
+  box, so an expanded box encloses fewer groups per sphere and a triple is harder to
+  find.
+
+  **What the descending leg is not** is a measurement of cure shrinkage.  2 ps at 600 K
+  does not equilibrate, so that leg mixes in residual thermal relaxation, and it spans
+  conversion 0.55 to 0.971.  It captures shrinkage; it does not measure it.  That, and
+  Cameron's instruction to match what the binary cures already do, are what the cold
+  equilibration rests on --- not on hot-only being worse, which it is not.
+
+  What the widening actually tracks is **concentration**, which is worth knowing on its
+  own.  Both arms widened for the first time at the same iteration, on the same trigger
+  of two candidates against a floor of four, from very different states: 315 unreacted
+  groups in a 192.6 nm3 box against 237 in a 143.7 nm3 box --- 1.6352 and 1.6489 groups
+  per nm3, within 0.9% of each other, while the arms sat 0.09 apart in conversion and
+  33% apart in raw count.  A fixed `search_radius` makes `min_rings_per_iteration` an
+  implicit concentration criterion.  Since 2.11.4 the search logs that concentration,
+  because otherwise the widening looks arbitrary in any cure whose box moves.
+
+  So a *short* cold stage will not equilibrate either, and CURE's 100 ps is the relevant
+  scale rather than an arbitrary one.
+
+  **Do not score that measurement against CURE's density curve.**  CURE's 1085 -> 1170
+  is read at its *cold* checkpoints.  A ring cure whose only NPT is at 600 K will sit at
+  a larger box and a lower density than its own constant-volume baseline, and that is
+  the stage working rather than failing.  The signal is path length greater than zero,
+  and then the trend across hot checkpoints.  If a cold stage is added later, the open
+  question is whether a short one converges at all or whether the barostat needs
+  something like CURE's 100 ps --- which is the other thing the A/B will show.
+
+- **Properties measured before the threading filter may carry threaded rings.**  The
+  filter shipped in 2.11.4; every build made before it could contain a triazine closed
+  around a monomer, which happened in 2 of 4 unfiltered builds --- 4, 2, 0 and 0
+  piercings, a mean of 1.5 each.
+  A threaded monomer is a permanent topological defect carrying a bond stretched past
+  2 A, so it is not obvious that Tg, density or modulus from those builds are unbiased,
+  and it is not obvious that they are biased either --- nobody has measured it.
+
+  The comparison is cheap now that both arms exist: build a small set with
+  `reject_threaded_rings` true and false and compare the properties, rather than
+  re-running any campaign on faith.  Whoever owns a property campaign predating 2.11.4
+  should decide whether to rebuild; htpolynet-study raised this about their own and it
+  is their call, not the repo's.
+
+
 - **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

{htpolynet-2.11.3 → htpolynet-2.11.4}/docs/source/install.rst

@@ -29,6 +29,10 @@ Installation and Prerequisites
    The default image runs Gromacs on CPUs only.  To use an NVIDIA GPU, use
    the ``:cuda`` tag instead.
 
+   Nothing is installed on your system, and the image is always current ---
+   which the ``conda-forge`` package is not; see
+   :ref:`the note below <conda_forge_not_recommended>`.
+
    See :ref:`container_usage` for the details: persistent caches, GPU setup,
    and pinning a release.
 
@@ -153,14 +157,41 @@ On openSUSE / Fedora / RHEL:
 Conda-only (simpler one-stop install)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. _conda_forge_not_recommended:
+
+.. admonition:: Do not install ``htpolynet`` itself from conda-forge
+   :class: warning
+
+   The ``htpolynet`` package on ``conda-forge`` is several releases behind
+   and is **not currently recommended**.  What is published there installs
+   and runs, so nothing warns you --- you simply get an old ``htpolynet``.
+
+   It cannot be updated at the moment.  ``htpolynet`` now depends on
+   `ycleptic <https://pypi.org/project/ycleptic/>`_, which is not yet
+   available on ``conda-forge``; until it is, the feedstock's automatic
+   version bumps produce a package that cannot import, so none has been
+   published.
+
+   You do not have to take this page's word for how far behind it is ---
+   the page may itself be stale by the time you read it:
+
+   .. code-block:: console
+
+      $ conda search -c conda-forge htpolynet | tail -1   # what conda-forge has
+      $ pip index versions htpolynet                      # what is current
+
+   This applies only to the ``htpolynet`` package.  ``conda-forge`` remains
+   the recommended source for AmberTools and Gromacs, as described above.
+
 Using Miniforge (preferred) or any other ``conda``-style installer, you
-can manage everything — Python, MD binaries, and ``htpolynet`` itself —
-in a single environment:
+can manage Python and the MD binaries in a single environment, then add
+``htpolynet`` itself from PyPI:
 
 .. code-block:: console
 
-    $ mamba create -n htpolynet -c conda-forge python ambertools gromacs htpolynet
+    $ mamba create -n htpolynet -c conda-forge python ambertools gromacs
     $ mamba activate htpolynet
+    $ pip install htpolynet
 
 Then install OpenBabel from your distribution's package manager as
 described above (OpenBabel via ``conda-forge`` works too but the

{htpolynet-2.11.3 → htpolynet-2.11.4}/pyproject.toml

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

{htpolynet-2.11.3 → htpolynet-2.11.4}/src/htpolynet/core/projectfilesystem.py

@@ -472,9 +472,38 @@ def resolve_user_library(pathname, default='lib'):
     return default if os.path.isdir(default) else None
 
 
+def _note_if_shadowing(filename, source):
+    """Says so when a file of your own replaces one htpolynet ships.
+
+    Overriding a packaged file is supported and often the point.  The trap is that a
+    copy taken from an older version keeps that version's settings, silently, for as
+    long as it stays on the search path -- so a setting the packaged file has since
+    gained never reaches the run, and nothing says which file was used.
+
+    Seen 2026-09-24: an `npt.mdp` copied from 2.6.2 and edited in one place stayed on a
+    study's path across four upgrades.  From 2.7.0 the packaged file sets
+    ``lincs_order = 8``, because at ``dt = 0.002`` GROMACS' default of 4 is marginal and
+    was fatal on one chemistry in 7 of 7 builds.  The stale copy reverted every run to
+    order 4, and the resulting instability was written up for weeks as a property of the
+    systems being built.
+    """
+    try:
+        if _SYSTEM_LIBRARY_ and _SYSTEM_LIBRARY_._root.joinpath(filename).exists():
+            logger.warning(
+                f'{filename} was taken from your {source} and replaces the copy '
+                f'htpolynet ships.  That is supported -- but if it was copied from an '
+                f'older version it still carries that version\'s settings.  Compare it '
+                f'against the packaged file after any upgrade.')
+    except Exception:
+        pass
+
+
 def checkout(filename, altpath=[]):
     """Copies a file to cwd; searches user library, then user cache, then system library.
 
+    A file found in the user library or cache shadows the packaged one, and
+    :func:`_note_if_shadowing` says so, because a stale copy is otherwise invisible.
+
     Args:
         filename (str): path relative to library root
         altpath (list): extra search directories, defaults to []
@@ -484,8 +513,10 @@ def checkout(filename, altpath=[]):
     """
     if _PFS_ and _PFS_.userlibrary and _PFS_.userlibrary.checkout(
             filename, searchpath=[_PFS_.rootPath, _PFS_.projPath], altpath=altpath):
+        _note_if_shadowing(filename, 'user library')
         return True
     if _USER_CACHE_.checkout(filename):
+        _note_if_shadowing(filename, 'user cache')
         return True
     return _SYSTEM_LIBRARY_.checkout(filename)
 

{htpolynet-2.11.3 → htpolynet-2.11.4}/src/htpolynet/core/runtime.py

@@ -14,6 +14,7 @@ from copy import deepcopy
 
 import networkx as nx
 import numpy as np
+import pandas as pd
 
 from networkx.algorithms import isomorphism
 
@@ -31,7 +32,7 @@ from ..cure.reaction import (Reaction, ReactionList, parse_reaction_list, extrac
                              is_reactant, is_ring_closing, reaction_stage)
 from ..core.productsplice import nearer_site_atoms
 from ..cure.ringcontroller import RingController, RingCureState
-from ..cure.triplesearch import reactive_sites, triple_bonds_dataframe
+from ..cure.triplesearch import bonds_by_atom, reactive_sites, triple_bonds_dataframe
 from ..external import software as software
 from ..external.gromacs import insert_molecules, mdp_modify, mdp_get
 from ..external.smiles_input import materialize_smiles_inputs
@@ -694,7 +695,11 @@ class Runtime:
             adf = TC.Coordinates.A
             positions = {int(r.globalIdx): np.array([r.posX, r.posY, r.posZ])
                          for r in adf.itertuples()}
-            sites, chosen = rc.search(adf, positions, TC.Coordinates.box.diagonal(), resname, groups)
+            # a ring that closes around an existing bond threads that monomer through
+            # it for good; CURE refuses the mirror image of this and the ring cure did not
+            bonds_of = bonds_by_atom(TC.Topology.D['bonds'])
+            sites, chosen = rc.search(adf, positions, TC.Coordinates.box.diagonal(), resname,
+                                      groups, bonds_of=bonds_of)
             if not chosen:
                 if rc.widen():
                     break
@@ -704,12 +709,17 @@ class Runtime:
             work = rc.close_rings(TC, bdf, gromacs_dict=gromacs_dict)
             # a ring the ladder could not pull shut would be bonded long and stay that way
             bdf, chosen = rc.accept(bdf, work, chosen)
+            # now that the loop is nearly ring-sized, ask what it actually encloses
+            bdf, chosen = rc.reject_threaded(TC, bdf, chosen)
             if not chosen:
                 rc.state.iter += 1
                 continue
             rc.form_rings(TC, bdf, sites, chosen, template, template_resids,
                           name_translations=name_translations, atom_names=arm)
             rc.relax(TC, gromacs_dict=gromacs_dict)
+            # the cold half of the cycle: relax ends hot and expanded, and without this
+            # the box only ever grows
+            rc.equilibrate(TC, gromacs_dict=gromacs_dict)
             rc.record(chosen)
             TC.write_gro(f'ring-{rc.state.iter}.gro')
             TC.write_top(f'ring-{rc.state.iter}.top')
@@ -725,6 +735,7 @@ class Runtime:
         rc.settle(TC, gromacs_dict=gromacs_dict)
         pfs.go_proj()
         self._report_molecule_charges('after ring cure')
+        self._report_overlong_bonds('after ring cure')
         my_logger(f'Ring cure ends: {rc.state.rings} ring(s), conversion '
                   f'{rc.state.conversion:.3f}', logger.info)
         return {c: os.path.basename(x) for c, x in TC.files.items() if c != 'mol2'}
@@ -845,6 +856,7 @@ class Runtime:
         if dropped:
             logger.info(f'Pruned {dropped} stale [ pairs ] entries left over from cure-induced path shortening')
         self._report_molecule_charges(f'in {result_name}')
+        self._report_overlong_bonds(f'in {result_name}')
         TC.write_grx_attributes(f'{result_name}.grx')
         TC.write_gro(f'{result_name}.gro')
         TC.write_top(f'{result_name}.top')
@@ -883,6 +895,62 @@ class Runtime:
                        f'moved between molecules, which parameterization does not intend.')
         return charged
 
+    def _report_overlong_bonds(self, when, limit=0.2, show=5):
+        """Logs any bond too long to be a bond in the structure being handed on.
+
+        A crosslinked network can finish a build carrying a bond stretched far past what
+        chemistry allows, and nothing else reports it: the topology is valid, every
+        molecule is neutral, and the run completes.  htpolynet-study measured a C-C at
+        3.20 A in two of five *final* structures, unchanged to two decimals by a 160 ps
+        anneal -- a monomer held stretched by network tension from a ring closure it was
+        not part of.  Ring bonds themselves always relaxed; these did not.  Anything
+        computed from such a structure inherits it, so it should at least be said out
+        loud.  See ROADMAP.md for the mechanism and why there is no fix yet.
+
+        Lengths use the minimum-image convention, so a bond spanning a periodic boundary
+        is measured across the boundary rather than counted as long.
+
+        Args:
+            when (str): stage label for the message, e.g. 'in final'
+            limit (float): longest credible bond, in nm.  The longest ordinary single
+                bond between light elements is C-S at about 0.182 nm, so 0.2 is
+                generous: this is meant to catch a bond that is not a bond any more,
+                not to police a strained one.
+            show (int): how many of the worst to name individually
+
+        Returns:
+            pandas.DataFrame: the offending bonds, longest first
+        """
+        TC = self.TopoCoord
+        D = getattr(getattr(TC, 'Topology', None), 'D', None) or {}
+        bonds = D.get('bonds')
+        if bonds is None or bonds.empty:
+            return pd.DataFrame()
+        work = bonds[['ai', 'aj']].copy()
+        TC.add_length_attribute(work, attr_name='length')
+        long = work[work['length'] > limit].sort_values('length', ascending=False)
+        if long.empty:
+            logger.info(f'Bond lengths {when}: no bond among {work.shape[0]} exceeds {limit} nm')
+            return long
+        A = TC.Coordinates.A.set_index('globalIdx')
+
+        def label(i):
+            try:
+                r = A.loc[int(i)]
+                return f'{r.atomName}({int(i)}) of {r.resName}{int(r.resNum)}'
+            except Exception:
+                return str(int(i))
+
+        ess = '' if long.shape[0] == 1 else 's'
+        worst = '; '.join(f'{label(r.ai)}-{label(r.aj)} at {r.length * 10:.2f} A'
+                          for r in long.head(show).itertuples())
+        logger.warning(f'Bond lengths {when}: {long.shape[0]} bond{ess} of {work.shape[0]} exceed '
+                       f'{limit} nm, which is longer than any real bond between these elements.  '
+                       f'Worst: {worst}.  A bond this long survives minimization and annealing -- '
+                       f'it is held by the surrounding network, not by thermal motion -- and every '
+                       f'property computed from this structure carries it.  See ROADMAP.md.')
+        return long
+
     def _write_vmd_viz_files(self, result_name='final'):
         """Writes a PSF (real bond topology for VMD) and a TCL helper that
         trims bonds spanning periodic boundaries so VMD doesn't render the