htpolynet 2.6.1__tar.gz → 2.6.2__tar.gz

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

@@ -7,6 +7,106 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.6.2}/PKG-INFO

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

{htpolynet-2.6.1 → htpolynet-2.6.2}/ROADMAP.md

@@ -186,13 +186,15 @@ Coverage as of the last measurement: **38.8%** overall.
   degree placement at 0.236 nm -- but the aryl carbon has since been excluded
   from the metric precisely so it does not saturate, so that bound no longer
   applies and there is no analytic ceiling to reason from at all. What is
-  unknown is the fire rate in a box at polymer density. Next time a full
-  cyanate-ester build runs, read `min_clearance_nm`, `median_clearance_nm`,
-  `n_below_target` and `n_preferred_out_of_angle` out of `repair-summary.yaml`
-  and set the default so it flags the tail rather than the bulk. A threshold
-  that fires on everything is not a threshold. If `n_preferred_out_of_angle`
-  comes back large, the 90--150 degree window is biting real O-H vectors and
-  is the thing to change, not the clearance.
+  unknown was the fire rate in a box at polymer density, and that has now been
+  measured (see the real-box block at the end of this entry). What is left is
+  the recalibration itself: set the default so it flags the tail rather than
+  the bulk, using `blind_min_clearance_nm`, `blind_median_clearance_nm` and
+  `n_below_target`. Do **not** calibrate against `min_clearance_nm` -- it
+  saturates at whatever target is set. A threshold that fires on everything is
+  not a threshold. The `n_preferred_out_of_angle` escape hatch is closed: it
+  came back at 6 %, so the 90--150 degree window is not biting real O-H
+  vectors and is not the thing to change.
 
   One thing the synthetic sweep did settle, so nobody re-derives it: the
   clipping the aryl-carbon exclusion removes is density-dependent, and at melt
@@ -273,6 +275,49 @@ Coverage as of the last measurement: **38.8%** overall.
   accordingly rather than assuming the high-conversion points are as tight as
   the low ones.
 
+  **Measured on real boxes, 2026-08-27** (study session, job 22107390): 14
+  independent cured BPA-cyanate-ester boxes at v2.6.1, chi_bond 0.740--0.901,
+  1955 caps, ~53 heavy atoms/nm^3 -- the first placement numbers taken without
+  the clearance bug present. `blind_median_clearance_nm` 0.1198 +/- 0.0061
+  against the synthetic sweep's 0.143: real boxes are ~16 % *tighter*, in the
+  direction the sweep's own caveat predicted, so the sweep's absolute values
+  should not be used to set the default. `blind_min_clearance_nm` 0.006--0.048.
+  722 of 1955 caps (37 %) would have been placed inside 0.10 nm blind.
+  `n_preferred_out_of_angle` 109 (6 %). `n_below_target` 1 of 1955, against
+  the sweep's 0 that was flagged "certainly optimistic".
+
+  And a correction to this entry's own advice, which the numbers force:
+  `min_clearance_nm` is **not** a tail statistic and must not be calibrated
+  against. Across all 14 boxes it came in at 0.1503 +/- 0.0006 against a 0.150
+  target -- the target seen from above, not a measurement. The search exits at
+  the first direction reaching target, so whenever it succeeds for every cap
+  the worst-placed cap is one that only just cleared, and the minimum is
+  pinned to the threshold by construction. The one box below it (cb0773,
+  0.1488) is the one box with `n_below_target` = 1. This is the searched-median
+  defect one statistic further along; it was missed because the median's
+  version of it was the one being written up. Docs corrected.
+
+  So the recalibration is unblocked and wants the `blind_*` columns. Note that
+  0.150 sits well above the measured blind median of 0.120, not marginally
+  above 0.143 as the sweep suggested -- so the search runs for well over half
+  of all caps -- yet it succeeds for 1954 of 1955. Demanding and reachable at
+  once, which is a different situation from the one this entry was written
+  against, and it weakens the earlier guess that recalibration would move the
+  default down.
+
+  **The placement change is density-neutral at high conversion, 2026-08-28**
+  (study session; picotte 22107390 complete, 14/14, exit 0:0). v2.6.1 anchors
+  at chi_OCN 0.7438 give 1197.59 kg/m^3 (n = 2) against v2.3.0's 1197.94 +/-
+  3.25 at 0.7458 (n = 8): offset -0.34 on a combined SE of 2.38, i.e. 0.1
+  sigma, bounding |offset| < 4.7 kg/m^3 at 2 sigma. So the net of 5a58d3d and
+  82ddd3e does not move bulk density where it has been checked. Two limits.
+  The bound is small against the 21 kg/m^3 rise across the series, so the two
+  versions pool for curve shape -- but it is *not* small against the 3.0 kg/m^3
+  basin depth, so it licenses nothing about the basin. And it does not
+  calibrate `cap_min_clearance`: a placement change being invisible in bulk
+  density is a much weaker statement than the threshold being right, and this
+  item stays open exactly as written above.
+
 - **The cap direction search stops at the first adequate direction, not the
   best one.** `_choose_cap_placement` breaks out as soon as a direction
   reaches `cap_min_clearance`, so a cap that could have had 0.25 nm of room
@@ -281,32 +326,157 @@ Coverage as of the last measurement: **38.8%** overall.
   admits about 43 % of a 48-direction Fibonacci spiral, so a full scan is
   ~21 vectorized distance evaluations against a neighbour list of order 100.
   And `median_clearance_nm` is partly a readout of the threshold rather than
-  of the box, since the distribution is truncated from below at the target.
+  of the box, since the distribution is truncated from below at the target --
+  as is `min_clearance_nm`, which is pinned *at* the target rather than merely
+  pulled toward it, measured at 0.1503 +/- 0.0006 across 14 real boxes.
+  Removing the early exit would give both fields their meaning back.
 
   Deliberately not changed for 2.6.1: taking the best direction moves every
   cap that needed a search, and doing that on the same release as the
   clearance fix means the next real build cannot attribute a change in the
-  numbers to either one. Do it after there is one clean real-box measurement
-  to compare against. Until then the docs say which fields are placement
-  outcomes and which are crowding measurements, and
-  `blind_median_clearance_nm` -- one fixed direction, no search, no early
-  exit -- is the statistic to correlate on.
+  numbers to either one. That precondition is now satisfied -- the 14-box
+  measurement of 2026-08-27 recorded above is the clean pre-change baseline,
+  so this is ready to do. Note that changing it invalidates the achieved
+  columns of anything built before it while leaving the `blind_*` columns
+  comparable, which is another reason those are the ones to correlate on.
 
 - **The shortfall from the cube law between `f` and many iterations is
-  unexplained.** Below `f` iterations crosslinker conversion is exactly zero,
-  a counting constraint; at nine iterations real runs land 1--3 % above the
-  cube. In between, measured ratios to the cube law are 0.06 and 0.46--0.50 at
-  three iterations and 0.86 at four -- an eightfold spread at an *identical*
-  iteration count, so the iteration count does not determine it. The
-  one-bond-per-residue-per-iteration rule was simulated against this and moves
-  the n=3 prediction only from 30.0 to 25.9 against 15 observed: about a fifth
+  unexplained, and is now known to be narrow.** Below `f` iterations
+  crosslinker conversion is exactly zero, a counting constraint; the four runs
+  of the nine-iteration cohort land +0.6 to +3.5 % above the cube (attested at
+  nine for two of the four; the other two are the same cohort at the same
+  target with the count unrecorded). In between, measured ratios
+  to the cube law are 0.06 and 0.46--0.50 at three iterations and 0.86 at
+  four -- an eightfold spread at an *identical* iteration count, so the
+  iteration count does not determine it. The band above that is now measured
+  and shows no shortfall at all: 14 runs at `n`/`f` 1.67--2.67 sit at
+  1.020 +/- 0.029 of the cube, with 3 of the 14 *below* it to -3.7 % against
+  replicate scatter of 0.8--1.8 %. So the unexplained region is only
+  `f` to about 1.7`f`, and across 1.7--2.7`f` the cube is a two-sided estimate
+  rather than the floor the docs used to call it -- corrected there.
+
+  What that does **not** settle is 3`f`, and the temptation to settle it by
+  arithmetic should be resisted: applying the 1.7--2.7`f` scatter to the
+  nine-iteration cohort gives P(below cube) = 0.245 and makes four-of-four
+  above a one-in-three outcome, but that presupposes the deviation is
+  regime-independent, which is the claim in question. The cohort on its own is
+  +2.64 % sd 1.39 % (n = 4), giving P = 0.03 -- an order of magnitude apart --
+  and at n = 4 the sd's 95 % CI is [0.79, 5.18], so the two cannot be
+  distinguished. 3`f` is untested, not disproved. Settling it wants more runs
+  at 3`f`, not a wider distribution borrowed from a lower one. Whatever
+  mechanism explains the shortfall has to switch off within a factor of two
+  of `f`.
+
+  The one-bond-per-residue-per-iteration rule was simulated against this and
+  moves the n=3 prediction only from 30.0 to 25.9 against 15 observed: a fifth
   of the gap. The leading untested guess is spatial anti-correlation --
   bonds forming preferentially on crosslinkers that already have room, leaving
   the rest to compete. This matters because it is the regime where a user's
   reported conversion is most wrong, and because a warning better than the
   current `iterations < f` one needs a mechanism to threshold on. Widening
-  that warning to `n < 2f` was considered and rejected: the eightfold spread
-  at fixed `n` shows no threshold on `n` can work.
+  that warning to `n < 2f` was considered and rejected: no threshold on `n`
+  alone can work.
+
+  That conclusion survives a correction to its own evidence, and comes out
+  stronger. The 8x pair was **confounded**: conv40 r3 and conv50 r1 are both
+  n = 3 but sit at chi_bond 0.40 and 0.50, so they never isolated `n` either.
+  The new low-conversion builds split it -- at fixed chi_bond the residual
+  spread is 1.36x, not 8x, and the chi_bond 0.40 ratio-to-cube reproduces to
+  three digits across v2.3.0 and v2.6.1 five months apart. So at fixed `n` the
+  ratio moves 7--10x purely with chi_bond, which is a sharper refutation of an
+  `n` threshold than the confounded pair was. What does *not* survive is the
+  explanation: the "product of per-iteration bond fractions" account is
+  superseded by plain chi_bond, which is simpler and reproduces across
+  versions. Docs corrected.
+
+  **Reinstated 2026-08-29**, and worth recording because it was withdrawn and
+  reinstated inside two days. The "product of per-iteration bond fractions"
+  account was not superseded -- it was under-evidenced, and the iteration logs
+  now make it the best-evidenced thing in this entry. Bonds per iteration decay
+  steeply (bpa-fl0500: 156, 145, 59; bpa-cb0900: 162, 148, 128, 92, 46, 29, 17,
+  26), so `720 x chi_bond / n` is an average no build actually realises. What
+  matters is the LAST iteration, the one that has to supply a triazine's third
+  bond: bpa-fl0400 spent 9 bonds there against an average of 96 and came in at
+  ratio 0.064, and conv40 r3 -- same conversion, v2.3.0, five months earlier --
+  spent 10 on its own last iteration and also came in at 0.064.
+
+  So chi_bond is a **proxy for the distribution, not a replacement for it**.
+  The algebra above still holds for *average* bonds-per-iteration, which is
+  exactly collinear with chi_bond at fixed n (r = 1.0000). The *last-iteration*
+  count is a third variable at r = 0.980 with chi_bond -- separable in
+  principle, not on four points. The withdrawal on 08-28 was made on the
+  strength of a correlation, which is the move this entry already warns about
+  one paragraph earlier.
+
+  **Measured below the band, 2026-08-28** (study session; picotte 22132281,
+  12 BPA builds at v2.6.1, cures final, ladders still running): at bond
+  conversions of 0.40--0.73 the deviation from the cube is one-sided and
+  large -- 11 of 12 below, mean -19.9 %, worsening monotonically as bond
+  conversion falls, -93.6 % at 0.40. The single build inside the documented
+  band (0.7306, +1.5 %) agrees with it, so nothing here disturbs the
+  1.7--2.7`f` scoping.
+
+  The open question this creates is which variable is doing the work. The
+  documented band is *both* 1.7--2.7`f` and bond conversion 0.74--0.90; this
+  array varies bond conversion and its iteration counts are not yet in hand
+  (they live in `diagnostics.log`, returned only when a task ends -- expected
+  early 2026-08-29). So the docs state the degradation against bond
+  conversion, which is what was measured, and do not attribute it to `n`/`f`.
+  **Resolved 2026-08-29**, counts returned with the array. Four builds sit at
+  exactly n = 3 spanning 15x in ratio-to-cube (0.064 / 0.633 / 0.795 / 0.937 at
+  chi_bond 0.40 / 0.50 / 0.55 / 0.58), monotone in chi_bond. So "iteration
+  count does not determine the shortfall" is established directly, on four
+  same-n runs, rather than inferred from the confounded pair. Over all 26
+  builds r(ratio, chi_bond) = +0.813 against r(ratio, n/f) = +0.567, with
+  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.
+
+- **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
+  ends -- and worth keeping only for
+  what the post-hoc check cannot do: warn *before* a multi-hour build rather
+  than after it. That is a weaker claim on much worse evidence, so it is a
+  separate feature and not a substitute. The reasoning that motivated it:
+  chi_bond predicts the ratio-to-cube to within 1.36x, and unlike a bond
+  distribution -- which does not exist until the cure runs -- it is knowable
+  before the cure starts. So
+  htpolynet could warn at config time that a run will yield far less
+  crosslinker conversion than the cube law implies, which is the number a user
+  is actually reasoning with. The existing `iterations < f` warning fires only
+  after the fact and only in the exactly zero regime.
+
+  **Do not key it on `desired_conversion`, and do not key it on chi_bond
+  either.** chi_bond is a config-time proxy, not the governing quantity, and
+  the collinearity is not an accident of sampling that more builds would fix.
+  Within a fixed iteration count `bonds = 720 x chi_bond` for this system, so
+  bonds-per-iteration `= 720 x chi_bond / n` is *exactly* proportional to
+  chi_bond. No dataset at fixed `n` can separate them, however large. Breaking
+  the proportionality needs `max_conversion_per_iteration` or
+  `min_bonds_per_iteration` varied AT FIXED `desired_conversion` -- which is
+  a deliberate experiment nobody has run, not something a wider sweep of
+  conversions will deliver.
+
+  There is a further reason to keep it qualitative: the quantity that appears
+  to govern the shortfall is the number of bonds formed in the *last*
+  iteration, and that is not knowable at config time at all -- it is an
+  outcome of the cure, not a setting. Any config-time warning is necessarily
+  keyed on a proxy for it.
+
+  Those same two directives are also why `desired_conversion` is the wrong
+  key in ordinary use: they set bonds-per-iteration independently of it, which
+  is exactly what the warning at `cure/curecontroller.py:674` already tells a
+  user to do to spend more iterations at the same conversion, and what this
+  project plans in order to reach 9+ iterations. A threshold keyed on
+  `desired_conversion` alone would misfire on precisely the runs that took
+  htpolynet's own advice.
+
+  So keep it qualitative until something separates the two. A warning saying
+  "below about 0.7 the cube law overstates badly, and worsens as you go lower"
+  needs no attribution and could ship soon. One that quotes a number needs both
+  the separation and a sense of how much of the curve is BADCy-specific -- it
+  is one chemistry, one force field, one cure protocol, n = 1 per target apart
+  from a single duplicate.
 
 - **`completion_bias` biases the `B` side only, and that is a convention,
   not a law.** The new `CURE.controls.completion_bias` ranks bond candidates

{htpolynet-2.6.1 → htpolynet-2.6.2}/docs/source/example-tutorials/6-cyanate-ester/results.rst

@@ -51,7 +51,10 @@ Diagnostic-log plots:
    0.90 leaves a cyanate conversion near 0.73 -- a little above it
    here, since this cure takes nine iterations and the distance-ranked
    search keeps re-finding crosslinkers that are partly bonded.  The
-   cube is only a floor in that many-iteration limit; a cure that
+   cube is an estimate rather than a bound, and only near this run's
+   own bond conversion: at 0.74–0.90 real runs scatter a few percent
+   either side of it, but by 0.5 they fall short of it by tens of
+   percent, always on the same side.  A cure that
    reaches its target in two or three iterations lands far below it,
    and in fewer than three it lands at exactly zero, because at most
    one bond per residue forms per iteration.  htpolynet reports

{htpolynet-2.6.1 → htpolynet-2.6.2}/docs/source/user-guide/postcure-repair.rst

@@ -176,13 +176,22 @@ Spec fields
   the driver searches 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.  It is a demanding default:
-  at the heavy-atom density of a cured thermoset it sits a little
-  above the room a typical site has along the O-H vector, so the
-  direction search runs for roughly half of all caps rather than
-  rubber-stamping them.  That is the intent — the search exists for
-  the crowded half — but it means a run reporting that most caps
-  needed a search is behaving normally, not signalling a bad box.
+  steepest-descent minimization absorbs.  It is a demanding default,
+  and deliberately so: at the heavy-atom density of a cured thermoset
+  it sits well above the room a typical site has along the O-H vector,
+  so the direction search runs for most caps rather than
+  rubber-stamping them.  Measured on 14 independent cured
+  bisphenol-A-cyanate-ester boxes at about 53 heavy atoms per
+  nm\ :sup:`3` (1955 caps in total), the median clearance along the
+  O-H vector was 0.120 nm — below the target — and 37 % of caps would
+  have been placed within 0.10 nm of a neighbour had that direction
+  been taken blind.  That is the intent, and it is not a symptom: a
+  run reporting that most caps needed a search is the default working.
+
+  Demanding is not the same as unreachable.  In those same 14 boxes
+  the search found the target for all but 1 cap of 1955, so a run
+  reporting more than an occasional ``n_below_target`` is saying
+  something about the box, not about the threshold.
 
   The clearance is measured only against atoms the cap is *not* bonded
   through — the bridge oxygen itself and its aryl carbon are excluded,
@@ -334,9 +343,9 @@ bond conversion: a run at a bond conversion of 0.90 lands near 0.73.
 A run reported as "90 % cured" on the strength of the cure log is, as
 a cured structure, closer to three-quarters converted.
 
-**The cube law holds only when the cure took many iterations.**  Below
-that it overstates the result, and there are two regimes with a hard
-boundary between them.
+**The cube law holds only once the cure has taken enough iterations.**
+Below that it overstates the result, and there are two regimes with a
+hard boundary between them.
 
 * **Fewer than** ``f`` **iterations: the crosslinker conversion is
   exactly zero.**  The bond downselection admits at most one bond per
@@ -345,28 +354,97 @@ boundary between them.
   constraint rather than a tendency: it holds whatever the bond
   conversion reached.  A cure that hits its target in two iterations
   builds a monomer melt with no junctions at all, however healthy its
-  reported bond conversion looks, and htpolynet warns when a run ends
-  this way since nothing else in the output would tell you.
-* **At or above** ``f`` **iterations: the shortfall depends on how the
-  bonds were distributed across those iterations, not on how many
-  there were.**  Two trifunctional runs that both took three
-  iterations came out at 6 % and 50 % of the cube-law figure — an
-  eightfold spread at an identical iteration count.  Measured ratios
-  to the cube law across a series of runs: 0.00 at two iterations,
-  0.06–0.50 at three, 0.86 at four, 1.01–1.04 at nine.  The mechanism
-  behind the residual is not identified; the one-bond-per-residue rule
-  accounts for only about a fifth of it.
-
-Given many iterations, proximity works the other way.  The search is
-distance-ranked and a partly-bonded crosslinker already sits in a
-bridge-rich neighbourhood, so it keeps getting re-found: a weak
-version of ``completion_bias`` for free.  That is what puts long runs
-a couple of percent *above* the cube, and it is expected behaviour
-rather than a sign anything is wrong.
-
-So the cube is a floor only in the many-iteration limit.  Anywhere
-below it the iteration count will not tell you how far short you fell,
-and the only trustworthy number is the measured one that repair
+  reported bond conversion looks.
+* **At or above** ``f`` **iterations: the iteration count does not
+  determine the shortfall.**  Four trifunctional runs that each took
+  exactly three iterations came out at 0.06, 0.63, 0.80 and 0.94 of
+  the cube-law figure — a fifteenfold spread at an identical iteration
+  count, ordered by their bond conversions of 0.40, 0.50, 0.55 and
+  0.58.  Measured ratios to the cube law across a series of runs: 0.00
+  at two iterations, 0.06–0.94 at three, 0.86 at four, 1.02 ± 0.03
+  over 14 runs at five to eight, 1.01–1.04 across the four-run
+  nine-iteration cohort — where the spread at three iterations is the
+  bond-conversion spread just described, not an iteration effect.
+  What sets the *size* of the shortfall looks like the distribution of
+  the bonds across those iterations, and specifically how many the
+  last iteration formed — it is the one that has to supply a
+  crosslinker's final bond, and the per-iteration bond count decays
+  steeply, so the average is not what matters.  The run at 0.06 above
+  spent its last iteration on 9 bonds against an average of 96, so
+  almost no crosslinker could complete; a run at the same bond
+  conversion built five months earlier under an older htpolynet spent
+  its own last iteration on 10 and landed at the same ratio to three
+  digits.  That is the best account available and it rests on few
+  runs.  The one-bond-per-residue rule alone accounts for about a
+  fifth of the shortfall.
+
+htpolynet warns about both of these at the end of the cure, because
+nothing else in the output would tell you.  Below ``f`` iterations it
+says so by name, since the cause is then known exactly.  At or above
+``f`` it counts how many crosslinkers actually ended up reacted at all
+of their sites — an exact number by that point, not an estimate — and
+warns when that is a small enough fraction that a percolating network
+should not be assumed.  The count is logged either way.  The second
+case is the one that matters in practice: a cure can run exactly ``f``
+iterations, reach its target bond conversion, and still finish with
+almost no complete crosslinkers if its last iteration formed few
+bonds.
+
+Proximity works the other way, and it is what closes the gap.  The
+search is distance-ranked and a partly-bonded crosslinker already sits
+in a bridge-rich neighbourhood, so it keeps getting re-found: a weak
+version of ``completion_bias`` for free.  That is a bias of a couple
+of percent, not a bound, and runs land on both sides of the cube.
+
+The recovery is complete well before the many-iteration limit, but it
+arrives as a two-sided estimate rather than as a floor.  Across 14
+independent trifunctional runs at 1.7–2.7 ``f`` iterations and bond
+conversions of 0.74–0.90, the crosslinker conversion sat **+2.0 %**
+from the cube on average, with a standard deviation of 2.9 % and a
+range of −3.7 % to +6.3 %; 3 of the 14 landed *below* the cube,
+against a replicate scatter of 0.8–1.8 %, so those excursions are real
+and not measurement noise.
+
+That band is bounded from below, and the bound is sharp.  A separate
+array of 12 runs at bond conversions of 0.40–0.73 does not behave like
+a two-sided estimate at all: 11 of the 12 landed *below* the cube, by
+−19.9 % on average, worsening monotonically as the bond conversion
+falls and reaching −93.6 % at a bond conversion of 0.40 — an
+overstatement by a factor of 15.  So ± 3 % is not the cube law's
+general accuracy.  Carried down to a bond conversion of 0.5 it
+understates the error by an order of magnitude, and in a predictable
+direction: the cube is always the optimistic side down there.
+
+The accuracy is stated against bond conversion because that is what it
+tracks — over 26 runs the correlation with bond conversion is +0.81
+against +0.57 for the iteration count, and the fifteenfold spread at a
+fixed iteration count above rules the iteration count out as the sole
+determinant.  It does not follow that the bond conversion is the
+governing quantity.  Within a fixed iteration count the *average*
+number of bonds formed per iteration is exactly proportional to the
+bond conversion, so no set of runs sharing an iteration count can tell
+those two apart, and every run here shares one with several others.
+Treat the bond conversion as the variable to *read* the accuracy
+against; the mechanism, as far as it is understood, is the one
+described above, and the bond conversion stands in for how the bonds
+were distributed rather than replacing it.
+
+Further out than that it is not settled.  The four runs of the
+nine-iteration cohort all landed above the cube, by +0.6 % to +3.5 %,
+which reads like a bound — but 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 simply be carried to 3 ``f``, since
+whether the deviation depends on the regime is the very thing at issue
+here.  So the correction below applies where it was measured: at
+1.7–2.7 ``f`` the cube is demonstrably not a floor.  At 3 ``f`` it is
+untested, not disproved.
+
+So the cube is a useful estimate over a specific band — good to about
+3 % at bond conversions of 0.74–0.90 and 1.7–2.7 ``f`` iterations, and
+across that band not a floor.  Outside it, in either direction, it
+overstates the result: by an amount the iteration count will not tell
+you below ``f``, and by up to a factor of 15 at low bond conversion.
+The only trustworthy number anywhere is the measured one that repair
 reports.
 
 ``completion_bias`` does not lift the iteration floor — it changes
@@ -418,26 +496,39 @@ with the full placement record in the same YAML file:
 These do not all mean the same kind of thing, and reading them as if
 they did is the mistake to avoid:
 
-* ``min_clearance_nm`` and ``n_below_target`` describe the **tail**,
-  which is where a placement failure actually lives, and they are what
-  ``cap_min_clearance`` should be calibrated against.
-* ``median_clearance_nm`` is a **placement outcome, not a measurement
-  of the site**.  The search stops at the first direction that reaches
-  the target, so this number is pulled toward ``cap_min_clearance`` by
-  construction and partly reports the threshold you set rather than
-  how crowded the box is.  It answers "how did the caps end up", which
-  is a fair question, but it is not a crowding statistic.
+* ``n_below_target`` is the one **achieved** number that describes the
+  tail, which is where a placement failure actually lives.
+* ``min_clearance_nm`` and ``median_clearance_nm`` are **placement
+  outcomes, not measurements of the site**.  The search stops at the
+  first direction that reaches the target, so both are pulled toward
+  ``cap_min_clearance`` by construction and partly report the
+  threshold you set rather than how crowded the box is.  The median is
+  pulled; the minimum is pinned.  Whenever the search succeeds for
+  every cap, the worst-placed cap is by construction one that only
+  just cleared the target, so ``min_clearance_nm`` lands just above it
+  — measured at 0.1503 ± 0.0006 nm against a 0.150 nm target across 14
+  independent boxes, and the single box that came in below (0.1488)
+  was the single box with a non-zero ``n_below_target``.  So
+  ``min_clearance_nm`` carries nothing that ``n_below_target`` has not
+  already said, and in particular it is not something to calibrate
+  ``cap_min_clearance`` against: it is the threshold seen from above.
 * ``blind_min_clearance_nm`` and ``blind_median_clearance_nm`` are the
-  crowding statistics.  They are measured along the single fixed O-H
-  direction with no search and no early exit, so they describe the
-  site rather than the algorithm, and they are the ones to correlate
-  across a series of runs.  ``n_blind_would_overlap`` counts the caps
-  that direction alone would have put inside 0.10 nm of a neighbour —
-  which is what placement did before the direction search existed.
+  crowding statistics, and the blind minimum is the real tail
+  statistic — it ranged 0.006–0.048 nm across those 14 boxes while the
+  achieved minimum sat on the target.  Both are measured along the
+  single fixed O-H direction with no search and no early exit, so they
+  describe the site rather than the algorithm, and they are the ones
+  to correlate across a series of runs and to calibrate the target
+  against.  ``n_blind_would_overlap`` counts the caps that direction
+  alone would have put inside 0.10 nm of a neighbour — which is what
+  placement did before the direction search existed, and which came to
+  37 % of caps on those boxes.
 * ``n_preferred_out_of_angle`` separates the two reasons a preferred
   direction gets abandoned.  A large value means the C-O-C angle
   window is rejecting real O-H vectors, which would look exactly like
-  a crowded box in every other field.
+  a crowded box in every other field.  On the 14 boxes above it was
+  6 % of caps, so the 90–150° window is not what is sending caps to
+  the search; a value several times that is the one to act on.
 
 That count is worth watching, because it is the quantity that predicts
 whether this stage survives.  It is an identity — every bond the cure

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

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