htpolynet 2.6.2__tar.gz → 2.7.0__tar.gz

{htpolynet-2.6.2 → htpolynet-2.7.0}/CHANGELOG.md

@@ -7,6 +7,114 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.7.0] - 2026-09-08
+
+### Changed
+
+- **The per-iteration equilibration now constrains hydrogen bonds only, not
+  all bonds.**  The packaged `npt.mdp` and `nvt.mdp` paired `dt = 0.002` with
+  `constraints = all-bonds` and set no `lincs_order`, so GROMACS used its
+  default LINCS accuracy (order 4).  That is marginal whenever heavy-atom
+  bonds are constrained, and for a halogenated monomer it was fatal: a
+  fluorinated bisphenol died at `4-cure_equilibrate-npt` in **7 of 7** build
+  attempts, at cure iteration 5-7 of ~10, with exit codes 1 and 139.  `LINCS`
+  appeared 14 times in that bridge's `diagnostics.log` and **zero** times in
+  each of seven other bridges built identically -- a perfect discriminator
+  across eight chemistries.  In a melt of pristine, uncrosslinked monomers at
+  production density, with no cure at all, step-0 pressure was -1.34e5 bar;
+  `h-bonds` took it to -495 bar and the LINCS constraint rmsd from 4.5e-4 to
+  7.3e-7.  With the new settings the whole eight-bridge series rebuilt **32 of
+  32**, the fluorinated one reaching a bond conversion of 0.900 in all four
+  replicates.  `h-bonds` is also the conventional pairing with a 2 fs
+  timestep.
+
+  **This changes the sampled ensemble**, so structures and densities from
+  earlier versions are not strictly comparable with new ones, and because
+  `postsim` inherits `npt.mdp` it changes the production measurement too, not
+  just the cure.  The drag and relax ladders are unaffected -- they always ran
+  unconstrained at 1 fs.
+
+- **`lincs_order = 8` in the packaged `npt.mdp` and `nvt.mdp`.**  Independent
+  of the constraint change: it improves the accuracy of the constraint solve
+  without changing which bonds are constrained, so it does not itself alter
+  the ensemble.  On the diagnostic melt above, order 8 alone reduced the
+  pressure artifact 4.8-fold.
+
+### Added
+
+- **The CURE relax stages now report the density they produce.**  The relax
+  ladder is the only above-`Tg` constant-pressure time in a cure -- roughly
+  120 ps of it, at the defaults -- and nothing looked at the density it
+  produced: `_do_relax` delegates to `_distance_attenuation`, which never
+  calls `TopoCoord.equilibrate()`, the only method that traced Density.  The
+  per-stage relax table gains a `Density (kg/m3)` column, read from the NPT
+  `.edr` each stage already wrote.  Drag is deliberately excluded, since it
+  runs under restraints and its density is not comparable.
+
+- **The CURE relax stages now report reactive-species mobility (Varshney's
+  criterion).**  After each relax ladder, htpolynet reports the rmsd
+  displacement of atoms that still carry an unused reactive site, and what
+  fraction of them moved at least one `CURE.controls.search_radius` during
+  the window.  Varshney sized the original 40 ps relaxation window on exactly
+  this requirement -- that unreacted species diffuse far enough between
+  reactions to find new partners -- but the requirement decays over a cure as
+  those species are bonded into the growing network, and until now nothing
+  reported when a window had stopped satisfying it.  A build where fewer than
+  25 % of still-reactive atoms cross a search radius now says so, because its
+  later bonds are being chosen from a nearly frozen neighborhood.
+
+  Both reports are pure observation: they change no simulation input and
+  gate nothing.  Every failure path is swallowed and logged at debug level,
+  so instrumentation cannot fail a build.  A run resuming mid-ladder skips
+  the mobility report rather than measuring only the tail of its window.
+
+- **`repair-summary.yaml` now reports the pre-repair bond histogram.**  A new
+  `prerepair_bond_counts` key gives how many crosslinkers carried 0, 1, ... up
+  to `full_bond_count` bonds *before* repair dismantled any of them.  Repair
+  rewrites the topology and the final structure does not record which cap came
+  from which ring, so this distribution was previously unrecoverable after the
+  fact -- only `n_complete`, its top bin, survived.  It is the statistic that
+  makes the independence assumption behind "crosslinker conversion = bond
+  conversion cubed" directly testable, and that relationship is now known to
+  be wrong in a way that matters: audited against 54 builds, the effective
+  exponent runs about 3.5 near a bond conversion of 0.55, 3.0 near 0.73 and
+  2.6-2.7 near 0.90, so the deviation from the cube changes sign and no single
+  power law fits.  The histogram is zero-filled, so the shape of the summary
+  does not depend on the box, and it is cross-checked against the completion
+  count on every build -- the two are computed independently, and a
+  disagreement now warns.
+
+### Documentation
+
+- **The constraint trap is documented where someone hitting it will look.**
+  The failure above surfaces at the equilibration step immediately after the
+  relax ladder, so the natural diagnosis is that the relax schedule is too
+  coarse.  It is not: the drag and relax ladders run unconstrained at a 1 fs
+  timestep and cannot be responsible, and refining them makes matters worse --
+  a three-variant array (increment 0.08 to 0.04 to 0.02, plus a double-MD arm)
+  confirmed that, with quadrupling the stage count degrading the result.  The
+  CURE section of the program-flow page now says which stages are constrained
+  and which are not, and says to look at the constraints rather than the
+  ladder when LINCS warnings appear at `cure_equilibrate`.
+
+- **Four defaults in the `CURE.controls` table were wrong.**  The table and
+  `curedict_defaults` had drifted apart: `radial_increment` is 0.05 and was
+  documented as 0.25, `max_iterations` is 100 and was documented as 150,
+  `desired_conversion` is 0.5 and was documented as 0.95, and
+  `min_allowable_bondcycle_length` is -1 rather than 0 (any value <= 0
+  disallows all cycles, so the documented *behavior* was right and only the
+  literal was wrong).  `desired_conversion` is the costly one: a user who
+  read "default 0.95" and omitted the key got a half-cure.  Every shipped
+  example that cures sets it explicitly, which is why nothing caught this.
+
+- **`desired_conversion` now says which conversion it means.**  The
+  `CURE.controls` table described it as "target conversion", which every
+  reader takes to be the crosslinker conversion an experiment measures.  It
+  is the *bond* conversion -- bonds formed over bonds possible -- and the
+  crosslinker conversion is lower: at a nominal 90 % cure, an audit of 30
+  builds found 75.2 triazines complete per 100, not 90.  The row now says
+  so and links to the fuller explanation under postcure repair.
+
 ## [2.6.2] - 2026-08-31
 
 ### Fixed

{htpolynet-2.6.2 → htpolynet-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.6.2
+Version: 2.7.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.6.2 → htpolynet-2.7.0}/ROADMAP.md

@@ -74,15 +74,23 @@ Rough ordering within each section is by value, not by effort.
 
 Coverage as of the last measurement: **38.8%** overall.
 
-- **`repair/` has no tests at all** — `cyanate_cap.py` (208 statements)
-  and `topology_surgery.py` (125), both at 0%. This is the highest-value
-  gap: the postcure repair stage makes the strongest correctness claim in
-  the project ("atom conservation is exact"), and right now the only
-  thing checking it is reading a residue census at the end of a
-  multi-hour build. It is pure topology manipulation, so it can be tested
-  deterministically in milliseconds against a synthetic `TopoCoord`
-  carrying triazines at k=0,1,2,3 — assert atom counts, the residue
-  census, cap placement, and that no unreacted bridge -OH survives.
+- **`repair/`'s driver has no test.** `test_cap_placement.py` and
+  `test_repair_conversion.py` now cover the placement search and the
+  reported statistics, but `triazine_to_cyanate_cap` itself and all of
+  `topology_surgery.py` (125 statements) are still untouched. This is the
+  highest-value gap: the postcure repair stage makes the strongest
+  correctness claim in the project ("atom conservation is exact"), and
+  right now the only thing checking it in-tree is reading a residue census
+  at the end of a multi-hour build. (An external audit of 54 builds at
+  v2.6.2 found the accounting exact everywhere -- `3*TAZ_final + CYN ==
+  720` in all 54, every surviving triazine with exactly 3 aryl-ether bonds
+  across 7,501 examined, zero bare -OH -- and a six-defect negative control
+  was caught by 2-10 checks each. That is real evidence, but it is not a
+  test and it does not run on a PR.) It is pure topology manipulation, so
+  it can be tested deterministically in milliseconds against a synthetic
+  `TopoCoord` carrying triazines at k=0,1,2,3 — assert atom counts, the
+  residue census, cap placement, and that no unreacted bridge -OH
+  survives.
 - **An end-to-end example in CI.** A deliberately tiny build (a
   20-molecule, few-ps variant of example 0) run inside the container
   would cover `core/runtime.py` and `cure/curecontroller.py` — 1,056
@@ -431,6 +439,17 @@ Coverage as of the last measurement: **38.8%** overall.
   r(chi_bond, n/f) = +0.905; counts run 3 to 8, n/f 1.00 to 2.67. Docs cite
   the four-run evidence now.
 
+  **The deviation changes sign, 2026-09-03** (study session, 54 builds
+  audited at v2.6.2): near `chi_bond` 0.900 the observed crosslinker count
+  runs *above* the cube -- 180.60 against 175.39 predicted over 30 builds,
+  +2.17 pp at t = +10.8 against a replicate sd of 2.63 triazines -- while at
+  `chi_bond` <= 0.64 it runs below, 32.17 against 41.28 over 6 builds, -3.80
+  pp. The compact way to say it is that the effective exponent
+  `ln(chi_OCN)/ln(chi_bond)` is not 3 and is not constant: ~3.5 near
+  `chi_bond` 0.55, ~3.0 near 0.73, ~2.6--2.7 near 0.90. No single power law
+  fits, so the cube is a local estimate around 0.9 and nothing more. This is
+  consistent with the 1.020 +/- 0.029 above, and puts a significance on it.
+
 - **A config-time version of that warning, before any compute is spent.**
   Largely superseded by the completed-crosslinker check that shipped -- nothing
   needs a proxy for a quantity that is exactly known by the time the cure
@@ -519,7 +538,13 @@ Coverage as of the last measurement: **38.8%** overall.
   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.
+  that now exists, and did not before. One thing the instrumentation still
+  does not report is how far a transferred cap actually travelled:
+  `_greedy_match` can reach the globally nearest free oxygen after ten radius
+  doublings, and one audited build transferred 72 of 177 caps, but
+  `repair-summary.yaml` carries clearance statistics only, so an external
+  audit could not bound the transfer distance. Report it alongside the
+  clearances.
 
 - **`bdf.loc[:abs_max]` takes one bond more than the limit.** In
   `curecontroller.py::_searchbonds`, the truncation that applies
@@ -531,8 +556,240 @@ Coverage as of the last measurement: **38.8%** overall.
   Worth doing at a version boundary where a small reproducibility break is
   already expected, not before.
 
+- **An algebraic self-check that no build currently runs.** For an A2 monomer
+  of `A` atoms in the 360-bisphenol/240-triazine example, the total atom count
+  is `360*A + 2160 - 1440` regardless of conversion -- verified at 12600
+  (bpa, A = 33), 9720 (bpo, A = 25) and 14760 (tmb, A = 39). It is
+  conversion-independent and closed-form, so any atom dropped or duplicated
+  anywhere in cure or repair breaks it. Cheap to assert at the end of repair.
+
+- **`_distance_attenuation` runs an open-loop stage ladder.** In
+  `cure/curecontroller.py:606`, `this_nstages = int(maxL/d['increment'])` is
+  computed once from the initial maximum bond length, and the loop then runs
+  that many stages whatever happens. `maxL` *is* recomputed inside the loop,
+  but only to log it -- it never extends, shortens or aborts the ladder -- and
+  `restore_bond_parameters(saveT)` runs each stage whether or not the bonds
+  actually closed. So a stage schedule that fails to bring a bond in has no
+  way to say so. Robustness only; it was ruled out as the cause of the
+  halogen failure below (quadrupling the stage count made that *worse*).
+  The densification entry below is the same shape of problem -- a number
+  computed once and trusted thereafter.
+
+- **If anything gates on density convergence, it should be densification,
+  not cure.** The initial 200 -> ~1100 kg/m3 compaction is one-shot,
+  involves a large volume change, and currently runs on fixed `nsteps`
+  (`runtime_defaults['densification']['equilibration']`,
+  `core/runtime.py:78-86`). That is the direct analogue of pestifer's use of
+  `density_equilibrate` -- a terminal, run-until-converged replacement for a
+  hand-written NPT ladder -- and it is cheap, because it happens once per
+  build rather than ~10 times.
+
+  What to port from `pestifer/util/density_convergence.py` is only the
+  criterion: an **autocorrelation-corrected SEM**, `sigma/sqrt(N/tau_int)`,
+  because NPT cell density is autocorrelated over hundreds of steps and a
+  naive block-means SEM is optimistic by ~1.5x. That also makes the test
+  size-aware for free, since `sigma/mean ~ 1/sqrt(N_atoms)` while tau is
+  roughly size-independent. Port the explicit **ceiling outcome** too, so a
+  build that never settled says so instead of silently reporting a density.
+  Do **not** port the chunking (`next_chunk_steps`, `is_patch_grid_crash`):
+  that exists because NAMD fixes its patch/PME grid at the start of each
+  `run`, and GROMACS rescales the box within one `mdrun` without that
+  failure mode. The chunking is most of pestifer's complexity and none of
+  its value here.
+
+- **Decided against: gating and extending `CURE.relax` on density
+  convergence.** Raised by Cameron 2026-09-05 from the observation that
+  pestifer has a gate system htpolynet does not; recommended by the study
+  session, twice revised, then withdrawn 2026-09-07 once the experiment that
+  tested it had run. Recorded here so it is not re-proposed from the same
+  premises. **The verdict is "not now, on these grounds", not "never"** --
+  both legs of it have stated limits, recorded below with the evidence.
+
+  **The experiment.** Arm R16 raised `CURE.relax` NPT `nsteps` 2000 ->
+  32000, i.e. above-`Tg` relaxation during cure from ~120 ps to ~1.9 ns, on
+  two chemistries at matched conversion, n = 4:
+
+      bpa   1187.52 -> 1192.19 kg/m3   +4.67 +/- 2.61   (+1.8 sigma)
+      bpf   1257.65 -> 1255.44         -2.21 +/- 2.15   (-1.0 sigma)
+
+  Sixteen times the relaxation closes **17 % of the density deficit, and not
+  significantly**; bpf, the control that should not move, did not. The
+  premise -- that the fixed relaxation window generates the deficit and a
+  gate would recover it -- survives only as a minor contributor.
+
+  **R16 is underpowered for the effect it found, and must not be recorded as
+  settled beyond its power.** Resolving +4.7 kg/m3 at 3 sigma needs n ~ 11 at
+  the observed scatter; this is n = 4. "17 % of the deficit at +1.8 sigma" is
+  a point estimate, not a tight upper bound, and better statistics could move
+  it. What it does rule out is a *large* effect of relaxation duration --
+  which is what the gate would have had to deliver to be worth its cost.
+
+  **The stronger reason, which does not depend on that result.** R16 ran a
+  fixed multiple, never to convergence, so ask what convergence would cost.
+  Restoring the start-of-cure crossing fraction needs ~4.4x the displacement
+  of unreacted species, which under `sqrt(t)` is ~19x the time: ~37 ns of
+  relax per build against a 39.2 ns production ladder, roughly doubling
+  build cost. **And `sqrt(t)` does not hold.** Past the gel point the
+  unreacted species are bonded into the network -- topologically
+  constrained, not merely slow -- and no amount of NPT time restores a
+  capture-radius displacement to a covalently tethered fragment. So an
+  honestly implemented gate would hit its ceiling on every late-cure
+  iteration and report "may not have settled", correctly, with nothing to be
+  done about it. It detects a condition it cannot cure.
+
+  **The limit on that argument:** arrest is inferred partly from gelation
+  physics, not purely measured. The study's displacement trace is still
+  falling at the last cure iteration, 4.63 -> 4.08 -> 3.72 A -- consistent
+  with approaching arrest, but not a demonstrated plateau. Measuring the
+  plateau directly would settle it either way, and is a smaller experiment
+  than powering R16 up.
+
+  **And a structural mismatch.** Pestifer uses `density_equilibrate` as a
+  terminal, one-shot replacement for a hand-written NPT ladder at the end of
+  a build -- somewhere you can afford to run until converged. The proposal
+  put the same machinery in an inner loop that executes ~10 times per build.
+  The economics are entirely different.
+
+  What does *not* change is the mechanism the proposal was built to explain,
+  which is still unexplained. If the box is under-relaxed while bonds are
+  forming, bonds form between whichever atoms happen to be adjacent in a
+  too-open configuration, and **the topology is then permanent** -- a later
+  remelt relaxes coordinates but cannot rewire bonds. That still ties
+  together three otherwise-awkward results from the study's 64-build series:
+  post-cure annealing is refuted as a cause of the density deficit (the
+  ladder opens 2 ns at `Tg`+112 K, erasing pre-ladder history), the uncured
+  monomer melt matches experimental dilatometry to 0.19 % while the cured
+  network is 2.25 % low, and cure shrinkage is strongly bridge-dependent
+  (+0.033 to -0.004 ml/g) and anti-correlates with monomer van der Waals
+  volume. R16 says more relax time is not the fix; it does not say the
+  mechanism is wrong.
+
+  **The production ladder does not need a gate either.** Two structures with
+  opposite histories held 5 ns at 480 K converge from opposite sides and
+  stall 4.25 kg/m3 apart with the ladder's own hold inside that bracket;
+  within-hold drift on the glassy branch is -0.35 to +0.53 kg/m3 per 667 ps
+  across four replicates; and replicate scatter is topological rather than
+  equilibrative (sd 3.2 kg/m3 at high conversion against 0.7 at `chi_OCN` 0).
+
+  **Reference values for the instrumentation that did ship in v2.7.0.** The
+  relax and mobility numbers a user now sees in their own log mean nothing
+  without something to compare them against, and these are the only measured
+  ones we have. Window size: the default relax sequence ends in an NPT
+  segment of 2000 steps and `relax-npt.mdp` runs `dt = 0.001`, so 2 ps per
+  stage; at the default `nstages: 6` over ~10 iterations that is roughly
+  **120 ps of above-`Tg` constant-pressure time across an entire cure**,
+  against a 39.2 ns production ladder. Density at cure termination is still
+  climbing, bpa +1.29 +/- 0.62 and bpf +1.48 +/- 0.28 kg/m3 per iteration
+  over the second half of cure (2.1 and 5.3 sigma, n = 4 per chemistry) --
+  though a rising density is *partly* expected, since crosslinking genuinely
+  densifies, and that slope cannot separate real densification from
+  incomplete relaxation. Reactive-species mobility over cure: bpa 18.1 ->
+  3.7 A with crossing fraction 97 % -> 13 %, bpf 17.4 -> 4.4 A and
+  97 % -> 22 %. All measured by the study session.
+
+- **Published gating designs we have not evaluated.** Audited by the study
+  session 2026-09-05. These gate *bond acceptance*, not density, so R16's
+  refutation of the density gate leaves them untouched.
+
+  - **Rejection on relaxation failure -- Moore et al. 2021**
+    (*Macromolecules* 54:6275), on di(cyanate ester)s, which is *our*
+    chemistry. Verbatim: "If a failure occurred during relaxation following
+    bond formation, the bond was removed and the crosslink cycle was
+    repeated with different bonds selected for crosslinking." That is bond
+    *acceptance* conditioned on a measured relaxation outcome. The same
+    paper caps bonds at **1 % of total per iteration** and terminates on
+    **stall** -- no new bonds in 20 iterations -- rather than on a step
+    count. Both are directly comparable to knobs we have:
+    `max_conversion_per_iteration` defaults to 1.0, i.e. no cap at all, and
+    we terminate on conversion or `max_iterations`.
+  - **Arrhenius kinetics gating -- Schichtel & Chattopadhyay 2020**
+    (*Comput. Mater. Sci.*): bonding probability from cure temperature,
+    cutoff distance and an activation energy. Their sec 2.4 *demonstrates*
+    the failure mode rather than merely flagging it -- a density trajectory
+    they call "not physical", ending in a metastable configuration, from
+    "accelerated reaction kinetics caused by the usage of higher
+    probabilities."
+
+  Rejection catches a bond that will not relax at all; Arrhenius sets the
+  rate. Neither sees gradual under-relaxation, but neither costs what the
+  density gate would have, and both act where R16 says the leverage is not
+  -- on which bonds form, rather than on how long the box is given
+  afterwards.
+
+  **A calibration number worth having before anyone panics about our
+  deficit.** Moore uses a fixed 40 ps NPT relaxation window at 800 K -- the
+  same number Varshney chose in 2008, with the same stated rationale, to let
+  unreacted species diffuse between reactions -- and reports a **4.77 %**
+  density deficit in BADCy after 100 ns of post-cure equilibration at 293 K.
+  Ours is 2.25 %. So the fixed-window architecture is universal from 2008 to
+  a 2021 GPU workflow, the resulting deficit does not equilibrate away, and
+  htpolynet is not an outlier. That makes this a field-wide design question
+  rather than a bug, which raises the value of getting it right and lowers
+  the urgency.
+
+  Nobody here has read either paper; the quotations above are the study
+  session's, and both citations should be checked against the originals
+  before being repeated anywhere public. The same applies to Varshney 2008,
+  which the v2.7.0 docs now name as the origin of the 40 ps relaxation
+  window and its mobility criterion -- that attribution is the study
+  session's too, and it is the one of the three that has already been
+  published in our documentation. Verify it first if any of them.
+
+## Simulation defaults
+
+- **The halogen constraint failure is fixed but not explained.** v2.7.0
+  switched the per-iteration equilibration to `constraints = h-bonds` with
+  `lincs_order = 8`, which took a fluorinated bisphenol from 0 of 7 builds to
+  4 of 4, and the eight-bridge series from 7 failures to 32 of 32. What is
+  still not understood is the *timing*. The constraint artifact is present
+  from the very first NPT step -- a melt of pristine, uncrosslinked BAF
+  monomers at production density shows step-0 pressure of -1.34e5 bar, with
+  no cure involved at all -- yet the old builds survived densification,
+  precure and 4-6 cure iterations before dying. So it was a predisposing
+  cause plus a threshold in the network's tolerance for it, not a single
+  trigger, and nobody knows what sets the threshold. The failing structures
+  were not preserved, so the LINCS atom indices were never mapped to
+  residues; anyone chasing this should trap and keep them first. The
+  diagnostic that identified it is worth reusing: halving `dt` made the
+  artifact ~4x *worse*, and 1/dt^2 scaling is the signature of a one-shot
+  constraint start-up projection rather than a physical clash.
+
+- **`mdp_to_dict` crashes on any mdp line containing two `=` signs.** In
+  `external/gromacs.py:239` it does `k,v = l.split('=')`, which raises
+  `ValueError: too many values to unpack` rather than reporting anything
+  useful. No packaged template trips it today -- checked across all eleven --
+  but any comment containing an equals sign does, including the obvious one
+  someone would write next to a timestep. It also does not strip `;`
+  comments, so the comment text becomes part of the value and is re-emitted
+  attached to it; GROMACS tolerates that, but `mdp_get` on a commented
+  numeric key would not survive a `float()`. Split on the first `=` only,
+  and strip comments.
+
+- **`postsim` inherits `npt.mdp` wholesale, so cure defaults govern the
+  production measurement.** `analysis/postsim.py:81` checks out `npt` and
+  renames it; `build_mdp()` overrides `ref_t`, `ref_p`, `nsteps`, velocity
+  generation and `tcoupl` (to `v-rescale`) but never touches `dt`,
+  `constraints`, `lincs_*` or `pcoupl`. So whatever is chosen above also sets
+  the timestep and constraint scheme of every postsim run, and the barostat
+  there is still **Berendsen**, which does not sample a correct NPT ensemble
+  and is deprecated in modern GROMACS. Changing the barostat is a physics
+  change to published numbers; changing it silently would be worse than
+  leaving it, so it wants a release note and probably a config knob.
+
 ## Usability
 
+- **The atom-serial column in `final.gro` wraps modulo 10000, and nothing
+  says so.** That is the GROMACS `.gro` format, not an htpolynet bug -- atom
+  10000 prints as `0` -- but every htpolynet system large enough to matter
+  crosses it, and the natural analysis script joins `final.gro` to `final.top`
+  on that column. In one 12,600-atom build 2,601 atoms (21%) have a `.gro`
+  serial that differs from their `.top` index, so such a script is silently
+  wrong for a fifth of the box with no error anywhere. Worth a sentence in the
+  analysis docs saying to join on line order, not on the serial. Same family
+  as the existing trap that `min_clearance_nm` is a substring of
+  `blind_min_clearance_nm` while PyYAML emits keys alphabetically, so a naive
+  grep of `repair-summary.yaml` picks the wrong one.
+
 - **`gen-slurm-script` doesn't stage to scratch.** The emitted script
   runs in the submit directory. A cure run does heavy small-file I/O
   every iteration, so on a cluster whose home and group storage are NFS

{htpolynet-2.6.2 → htpolynet-2.7.0}/docs/source/user-guide/configs/configs-for-run.rst

@@ -216,13 +216,13 @@ In this section we show all subdirectives for each of the five main directives i
         ``CURE.controls`` parameter           Type                Description (default)
         ==================================    =================   ======================
         ``search_radius``                     float               initial search radius in nm (default 0.5)
-        ``radial_increment``                  float               increment in nm by which search radius is increased if not enough bonds are found at current radius (default 0.25)
+        ``radial_increment``                  float               increment in nm by which search radius is increased if not enough bonds are found at current radius (default 0.05)
         ``min_bonds_per_iteration``           int                 grow the radius until at least this many bonds have been identified, then proceed with whatever the count is at the current radius (default 10). Effective floor is clamped against the remaining bonds needed to reach ``desired_conversion`` and against ``max_conversion_per_iteration``, so demanding e.g. 50 near end-of-cure never stalls the build. Setting to 1 reproduces the un-batched legacy behavior.
-        ``max_iterations``                    int                 absolute maximum number of allowed iterations (default 150)
-        ``desired_conversion``                float [0-1]         target conversion between 0 and 1.0 (default 0.95)
+        ``max_iterations``                    int                 absolute maximum number of allowed iterations (default 100)
+        ``desired_conversion``                float [0-1]         target **bond** conversion -- bonds formed over bonds possible -- between 0 and 1.0 (default 0.5). This is not the crosslinker conversion an experiment measures, which is lower; see :ref:`what repair reports <postcure_repair_reporting>`.  Note the default is a half-cure, not the 0.95 the examples use; every shipped example that cures sets the value explicitly rather than relying on it.
         ``late_threshold``                    float [0-1]         conversion above which bond probabilities are ignored (default 0.85)
         ``max_conversion_per_iteration``      float [0-1]         upper limit, as a fraction of total reactable bonds, on the new bonds formed in any single iteration (default 1.0)
-        ``min_allowable_bondcycle_length``    int                 minimum number of C atoms allowed in a cycle of C-C bonds that form via polymerization (default 0, disallow all such cycles)
+        ``min_allowable_bondcycle_length``    int                 minimum number of C atoms allowed in a cycle of C-C bonds that form via polymerization (default -1; any value <= 0 disallows all such cycles)
         ``completion_bias``                   bool                rank bond candidates by how many bonds their ``B``-side residue already carries, and only then by distance, so that partly-reacted crosslinkers are completed before untouched ones are started (default ``False``)
         ==================================    =================   ======================
 

{htpolynet-2.6.2 → htpolynet-2.7.0}/docs/source/user-guide/program-flow.rst

@@ -75,6 +75,60 @@ The Connect-Update-Relax-Equilibrate (CURE) algorithm
 
 The algorithm used to create new bonds and polymerize a system is called the CURE algorithm, depicted above.  This is just a slightly modified version of a standard search-radius-type algorithm, first used by Li and Strahan to study EPON/DETDA thermosets (:cite:t:`Li2010Crosslinking`).  The CURE algorithm begins by executing a search for new bonds on a frozen system configuration.  Bonds are downselected through a series of filters to arrive at a final set of bonds to form.  If the distance between any pair of "bond-designate" atoms is greater than some threshold (the ``trigger_distance`` parameter in the :ref:`drag subdirective <cure.drag>` of the ``CURE`` directive of a configuration file), a series of MD simulations that slowly bring all to-be-bound atom closer together is performed.  Then the topology is updated, where ``htpolynet`` applies the charges, atom type, and bonded interaction templates from the oligomer template set to each bond.  After the update, a series of relaxation MD simulations bring all bonds to their equilibrium lengths.  Then a short NPT MD simulation equilibrates the overall density before initiating the next CURE iteration.  CURE iterations continue until (a) a desired conversion is reached, or (b) no new allowable bonds are identified.
 
+.. note::
+
+   The drag and relax stages run **unconstrained**, at a 1 fs timestep, because
+   the bonds they are manipulating are deliberately far from equilibrium.  Only
+   the per-iteration equilibration (and, later, ``postsim``) uses a 2 fs
+   timestep with constraints, and as of v2.7.0 it constrains **hydrogen bonds
+   only**, with ``lincs_order = 8``.
+
+   Before v2.7.0 it constrained *all* bonds at 2 fs with the GROMACS default
+   LINCS accuracy, which is marginal whenever heavy-atom bonds are constrained
+   and was fatal for halogenated monomers: a fluorinated bisphenol failed every
+   build attempt, dying at the equilibration step several cure iterations in.
+   The trap was that the failure surfaces immediately after the relax ladder,
+   so the natural diagnosis is that the relax schedule is too coarse -- and it
+   is not, since that ladder is unconstrained and cannot be responsible.
+   Refining it makes matters worse.  If you see LINCS warnings at
+   ``cure_equilibrate``, look at the constraints, not at the ladder.
+
+.. _relax_diagnostics:
+
+What the relax stages report
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As of v2.7.0 the relax ladder reports two diagnostics per CURE iteration.  Both
+are pure observation: they change no simulation input and gate nothing.
+
+The per-stage table gains a **Density** column, read from the NPT ``.edr`` each
+stage already wrote.  The relax stages are the only above-:math:`T_g`
+constant-pressure time in a cure -- roughly 120 ps of it at the defaults,
+against a production ladder measured in nanoseconds -- so this is where you can
+see whether the box is still densifying when the cure stops.  Drag stages are
+excluded, because they run under restraints and their density is not
+comparable.
+
+After each ladder, ``htpolynet`` reports **reactive-species mobility**: the rmsd
+displacement of atoms that still carry an unused reactive site, and the fraction
+of them that moved at least one ``CURE.controls.search_radius`` during the
+window.  This is the criterion the fixed-relaxation-window convention was
+originally sized against -- that unreacted species diffuse far enough between
+reactions to find new partners -- and it has been in use, at 40 ps, since
+Varshney and co-workers introduced it in 2008.
+
+That requirement decays over a cure.  Past the gel point the still-reactive
+species are bonded into the growing network, and are then topologically
+constrained rather than merely slow, so more relaxation time does not restore
+their mobility.  A build in which fewer than 25 % of still-reactive atoms cross
+a search radius emits a warning, because its later bonds are being chosen from a
+nearly frozen neighborhood.  Treat that as a statement about the *validity range
+of the protocol*, not as an error: nothing is wrong with the run, but its late
+bonds are less well sampled than its early ones.
+
+A run resuming mid-ladder from a checkpoint skips the mobility report, since the
+window it could measure is only the tail of the real one.
+
 .. _bondsearch_filters:
 
 Identifying allowable bonds:  Bondsearch filters

{htpolynet-2.6.2 → htpolynet-2.7.0}/pyproject.toml

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