htpolynet 2.6.1__tar.gz → 2.7.0__tar.gz

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

@@ -7,6 +7,214 @@ 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
+
+- **The too-few-iterations warning was silent on the failure it exists to
+  catch.**  `check_iterations_vs_functionality` returned early whenever the
+  cure ran at least `f` iterations, so it fired only for the counting
+  impossibility `n < f`.  But `n >= f` only makes completion *possible*.  The
+  bonds a cure forms are not spread evenly across its iterations -- the
+  per-iteration count decays steeply, and it is the last iteration that has to
+  supply each crosslinker its final bond -- so a cure that runs exactly `f`
+  iterations and spends its last one on almost nothing arrives at the same
+  place as one that ran too few.  A build did exactly that: three iterations
+  against a functionality of three, target bond conversion reached, last
+  iteration spent on 9 bonds, and **one complete crosslinker out of 240**,
+  with nothing in the log about it.  The system it wrote is a monomer melt
+  that equilibrates and reports a sensible density.
+
+  The check now tests the outcome rather than the precondition, which needs no
+  new measurement: by the time it runs, how many crosslinkers reacted at all
+  of their sites is exactly known.  It logs that count on every cure and warns
+  when the fraction falls below the crosslinker conversion an ideal randomly
+  branching network of the same functionality would show at its gel point --
+  12.5 % for a trifunctional crosslinker.  That figure is an idealization and
+  is used only to decide when to raise the volume; the count itself is exact
+  and is reported either way.  The `n < f` case keeps its own message, because
+  there the cause is known exactly and worth naming.
+
+  The regression test suite had the bug written into it: a test asserted that
+  a run at exactly `f` iterations with no complete crosslinkers stays silent.
+
+### Changed
+
+- **`min_clearance_nm` is documented as a placement outcome, not a tail
+  statistic.**  2.6.1's docs said `min_clearance_nm` and `n_below_target` were
+  the tail and were what `cap_min_clearance` should be calibrated against.
+  The first half is wrong for the same reason the median was: the direction
+  search exits at the first direction reaching the target, so whenever it
+  succeeds for every cap the worst-placed cap is one that only just cleared,
+  and the reported minimum is pinned to the threshold by construction.  Across
+  14 independent real boxes it came in at 0.1503 +/- 0.0006 nm against a
+  0.150 nm target, and the single box that fell below it was the single box
+  with a non-zero `n_below_target`.  The minimum therefore carries nothing
+  `n_below_target` does not already say.  `blind_min_clearance_nm`, which
+  ranged 0.006-0.048 nm over the same boxes, is the real tail statistic, and
+  the `blind_*` fields are what to calibrate the target against.
+
+- **The cube law is documented as an estimate over a measured band, not as a
+  floor.**  The docs said crosslinker conversion sits at or above the cube of
+  bond conversion in the many-iteration limit.  It does not, and the band over
+  which the cube is even a good estimate is narrower than that claim implied.
+
+  *Where it holds*: across 14 trifunctional runs at 1.7-2.7 `f` iterations and
+  bond conversions of 0.74-0.90, the crosslinker conversion sits +2.0 % from
+  the cube with a standard deviation of 2.9 %, and 3 of the 14 land *below*
+  it, to -3.7 %, against a replicate scatter of 0.8-1.8 % -- so the excursions
+  below are real and it is a two-sided estimate, good to about 3 %.
+
+  *Below that band*: on 12 further builds at bond conversions of 0.40-0.73 it
+  is neither mild nor two-sided.  11 of the 12 fall below the cube, by -19.9 %
+  on average, worsening monotonically as the bond conversion falls and
+  reaching -93.6 % at 0.40.  Carrying +/- 3 % down to a bond conversion of 0.5
+  understates the error by an order of magnitude, in a predictable direction.
+
+  *Above it*: the four runs of the nine-iteration cohort all landed +0.6 % to
+  +3.5 % above the cube, which reads like a bound but cannot establish one --
+  four points cannot separate a bound from the upper tail of a two-sided
+  distribution, and the scatter measured at 1.7-2.7 `f` cannot be carried to
+  3 `f` when regime dependence is exactly what is at issue.  The docs say 3 `f`
+  is untested rather than either way.
+
+  *What sets the shortfall*: not the iteration count.  Four runs that each took
+  exactly three iterations span 15x in ratio-to-cube (0.06, 0.63, 0.80, 0.94).
+  It is how the bonds were distributed across those iterations, and
+  specifically how many the last one formed, since that is the iteration which
+  has to supply each crosslinker its final bond -- per-iteration bond counts
+  decay steeply, so the average is not the operative number.  The run at 0.06
+  spent its last iteration on 9 bonds against an average of 96; a run at the
+  same bond conversion five months earlier, under an older htpolynet, spent its
+  own last iteration on 10 and reached the same ratio to three digits.
+
+  *Which variable to read it against*: bond conversion, because that is what
+  the shortfall tracks -- r = +0.81, against +0.57 for the iteration count,
+  over 26 runs.  The docs are explicit that this is not the mechanism.  Within
+  a fixed iteration count the *average* bonds formed per iteration is exactly
+  proportional to the bond conversion, so no set of runs sharing an iteration
+  count can distinguish those two, and none here does.
+
+- **The placement documentation now quotes real-box numbers instead of
+  synthetic ones.**  `cap_min_clearance`'s "demanding default" was described
+  from a synthetic sweep that put the blind median at 0.143 nm and had about
+  half of caps needing a search.  On real cured boxes at the same heavy-atom
+  density the blind median is 0.120 nm -- ~16 % tighter, in the direction the
+  sweep's own caveat predicted -- so the search runs for well over half of all
+  caps and 37 % of them would have been placed inside 0.10 nm blind.  It
+  nonetheless reaches the target for all but 1 cap in 1955, so the default is
+  demanding and reachable at once.  `n_preferred_out_of_angle` came in at 6 %,
+  which the docs now give as the scale for reading that field: the 90-150
+  degree window is not what is sending caps to the search.
+
 ## [2.6.1] - 2026-08-27
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.6.1
+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/