htpolynet 2.6.0__tar.gz → 2.6.2__tar.gz

{htpolynet-2.6.0 → htpolynet-2.6.2}/.github/workflows/docker.yml

@@ -50,14 +50,38 @@ jobs:
 
     - name: Compute tags
       id: tags
+      env:
+        REF_NAME: ${{ github.ref_name }}
+        REF_TYPE: ${{ github.ref_type }}
       run: |
+        repo="ghcr.io/cameronabrams/htpolynet"
+        prefix="${{ matrix.tag_prefix }}"
         if [ "${{ matrix.variant }}" = "cuda" ]; then
-          moving="ghcr.io/cameronabrams/htpolynet:cuda"
+          moving="$repo:cuda"
         else
-          moving="ghcr.io/cameronabrams/htpolynet:latest"
+          moving="$repo:latest"
         fi
-        printf 'tags<<EOF\n%s\nghcr.io/cameronabrams/htpolynet:%s%s\nEOF\n' \
-          "$moving" "${{ matrix.tag_prefix }}" "${{ github.sha }}" >> "$GITHUB_OUTPUT"
+        {
+          echo "tags<<EOF"
+          echo "$moving"
+          echo "$repo:${prefix}${{ github.sha }}"
+          # A release also gets a tag people can *guess*.  Until now the only
+          # stable name was the commit sha, so `pull ...:v2.6.0` failed with
+          # `manifest unknown` -- which reads like the build failed rather than
+          # like the tag is named something else.  Emit both spellings, the git
+          # tag as written and the bare version, because there is no way for a
+          # user to know which convention this registry chose.  A `d*` tag is a
+          # Dockerfile-only rebuild, not a release, so it gets neither.
+          if [ "$REF_TYPE" = "tag" ]; then
+            case "$REF_NAME" in
+              v*)
+                echo "$repo:${prefix}${REF_NAME}"
+                echo "$repo:${prefix}${REF_NAME#v}"
+                ;;
+            esac
+          fi
+          echo "EOF"
+        } >> "$GITHUB_OUTPUT"
 
     - name: Build and push
       uses: docker/build-push-action@v6

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

@@ -7,6 +7,246 @@ 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
+
+- **Cap-placement clearance was pinned at the O-C bond length and measured
+  nothing** (regression in 2.6.0).  The neighbour set a transferred `-C#N` cap
+  was scored against excluded the cap atoms being moved and the hydrogens
+  about to be deleted, but not the bridge oxygen the cap bonds *to*.  The cap
+  carbon sits at exactly `oc_len` = 0.136 nm from that oxygen in every
+  candidate direction, so the reported clearance was 0.136 nm whichever
+  direction was scored.  Two independent acceptance builds on different
+  topologies both reported `min_clearance_nm` 0.136, median 0.136, and 71 of
+  71 caps below the 0.150 nm target -- identical to three decimals, which is
+  what a constant looks like when it is being read as a distribution.
+
+  Consequences: the reported clearance carried no information about crowding;
+  the default target was unreachable by construction, so the "could not reach
+  clearance" warning fired on every cap in every run and
+  `n_direction_searched` was always 100 %; and the search, while not dead,
+  could only reject directions worse than 0.136 nm rather than pick the
+  clearest one.  Placement was degraded, not disabled, and the repair
+  chemistry was never affected -- every conservation identity held through
+  2.6.0.
+
+  Each cap now drops the atoms it is bonded *through* -- its attachment oxygen
+  and that oxygen's aryl carbon -- and nothing else.  Every *other* cap's
+  oxygen is a real atom in the way, as is every cap already placed.  Both
+  exclusions are for the same reason: a distance fixed by bond geometry is not
+  a measurement of how crowded the site is.  The oxygen is the hard case, at
+  exactly 0.136 nm in every direction.  The aryl carbon is the soft one, and
+  keeping it would have left `median_clearance_nm` saturated at the C-O-C
+  geometry -- so a healthy run would still have reported a constant, just a
+  larger one, which is the same defect one bond further out.
+
+  Keeping the cap off the ring it hangs from is now an explicit constraint
+  rather than a side effect of the metric: the direction search is restricted
+  to C-O-C angles between 90 and 150 degrees.  That guards an end the aryl
+  carbon never did -- clearance alone is *maximized* by a linear ether, since
+  antiparallel puts the cap as far as possible from the rest of the molecule,
+  so a pure clearance search drifts toward a geometry no aryl ether adopts.
+  Bond lengths are still held fixed and open-space caps still land on the O-H
+  vector, so nothing moves for a cap that was already comfortable.
+
+  Because a systematically rejected preferred direction would reproduce the
+  exact symptom being fixed here -- everything searched, everything flagged,
+  for a reason unrelated to crowding -- repair now reports
+  `n_preferred_out_of_angle` separately from `n_direction_searched`.
+
+  The 2.6.0 calibration missed the original bug because it was done on a
+  jittered cubic lattice with no bonded attachment oxygen -- the fixture
+  lacked the one feature that defeats the fix.  The regression test added here
+  supplies it, and asserts the pinning at 0.136 nm that the released code
+  produces.
+
+- **Container releases now carry a version tag.**  `docker.yml` pushed only
+  the moving tag (`:latest` / `:cuda`) and the commit sha, so
+  `docker pull ...:v2.6.0` -- the obvious thing to type, and what the release
+  notes imply -- failed with `manifest unknown`.  That error reads like the
+  image failed to build rather than like the tag is named something else, and
+  it sent a user off to resolve the release through the GitHub tag API by
+  hand.  A `v*` push now also tags `:v<version>` and `:<version>`, in both
+  spellings because nothing tells a user which convention a registry chose,
+  with the `cuda-` prefix for the CUDA variant.  A `d*` tag is a
+  Dockerfile-only rebuild rather than a release and gets neither.
+
+  Releases before this one are unaffected and still have no version tag; the
+  container docs now say so and say how to resolve one to its commit sha.
+
+### Changed
+
+- **The docs now say which placement fields measure the box and which measure
+  the search.**  `repair-summary.yaml` carries nine numbers about cap
+  placement and they are not the same kind of thing, which is worth knowing
+  before treating any of them as physics.  `min_clearance_nm` and
+  `n_below_target` describe the tail, and are what `cap_min_clearance` should
+  be calibrated against.  `median_clearance_nm` is a placement *outcome*: the
+  direction search stops at the first direction that reaches the target, so
+  the number is pulled toward the threshold you set and partly reports it back
+  to you.  `blind_min_clearance_nm` and `blind_median_clearance_nm` are the
+  crowding statistics -- one fixed direction, no search, no early exit -- and
+  are the ones to correlate across a series of runs.
+
+  `cap_min_clearance` is also now described honestly as a demanding default.
+  At the heavy-atom density of a cured thermoset it sits slightly above the
+  room a typical site has along the O-H vector, so the direction search runs
+  for roughly half of all caps.  That is the intent -- the search exists for
+  the crowded half -- but a run reporting that most caps needed a search is
+  the default working, not a symptom.
+
+- **The docs now bound the cube law by what has actually been measured.**
+  Crosslinker conversion goes as roughly the cube of bond conversion, but only
+  in the many-iteration limit, where proximity lifts real runs a couple of
+  percent *above* it -- the search is distance-ranked and a partly-bonded
+  crosslinker sits in a bridge-rich neighbourhood, so `completion_bias` gets a
+  weak version of itself for free.  Below that limit the page now says two
+  things and no more than two.  Under `f` iterations the crosslinker
+  conversion is *exactly zero*, which is a counting constraint and holds
+  unconditionally.  At or above `f` it falls short of the cube by an amount
+  set by how the bonds were distributed across the iterations, not by how many
+  there were: two trifunctional runs at three iterations apiece came out at
+  6 % and 50 % of the cube-law figure.  An earlier draft of this page claimed
+  the iteration count decides where a run lands and that the
+  one-bond-per-residue rule accounts for the shortfall; the eightfold spread
+  refutes the first, and the rule is worth only about a fifth of the second.
+  The remaining mechanism is unidentified and the page now says so rather than
+  guessing.
+
+### Added
+
+- **htpolynet warns when a cure ran too few iterations for its crosslinkers to
+  complete.**  The bond downselection admits at most one bond per residue per
+  iteration, so a residue with `f` reactive sites cannot be fully reacted in
+  fewer than `f` iterations -- whatever bond conversion was reached.  A cure
+  that hits its target in two iterations therefore leaves *every*
+  trifunctional crosslinker incomplete, and a system with no complete
+  crosslinker has no junctions: it is a monomer melt that equilibrates,
+  reports a sensible density, and looks in every other respect like a cured
+  network.
+
+  Nothing else surfaces this.  The conversion the cure reports is a bond
+  conversion and is perfectly happy with it; only a `postcure_repair` stage
+  would notice, and only if one is configured.  The warning also says that
+  `completion_bias` is not the fix -- it changes which residues react, not the
+  one-per-residue-per-iteration rule -- because it is the first thing a user
+  would reach for on seeing a low crosslinker conversion.
+
+- **Repair now records what blind cap placement *would* have given, on the
+  real box.**  The O-H direction is tried first anyway, so its clearance is
+  free to compute; logging it turns "blind placement was putting caps in
+  overlap" from a claim measured on a synthetic lattice into a number measured
+  on the system actually being built.  Reported alongside the achieved
+  clearance and carried in `repair-summary.yaml` as `blind_min_clearance_nm`
+  `blind_median_clearance_nm`, and `n_blind_would_overlap`, with
+  `median_clearance_nm` alongside them -- a minimum says whether one build is
+  in danger, but correlating placement quality against outcomes across a
+  series of runs needs a statistic that is not an extreme value.  This is what tells someone whether structures
+  built before v2.6.0 were shaped by overlap resolution rather than by
+  placement -- a question that could not be answered from those runs' own
+  output.
+
 ## [2.6.0] - 2026-08-26
 
 ### Fixed

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

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

@@ -27,10 +27,17 @@ Rough ordering within each section is by value, not by effort.
   choice for runs that offload to a GPU anyway, so the penalty may be small
   for exactly the case the `:cuda` image serves.
 
-- **Publish a digest or version tag people can pin.** `:latest` moves
-  every week via the scheduled rebuild, so a run recorded as "built with
-  the container" is not reproducible. Per-commit tags already exist;
-  what's missing is documenting that users should pin one.
+- **Releases before v2.6.1 have no version tag in the registry.** From
+  v2.6.1 on, `docker.yml` pushes `:v<version>` and `:<version>` (and the
+  `cuda-` variants) alongside the commit sha, but the earlier releases were
+  pushed as `:latest` and a sha only. So `pull ...:v2.5.0` returns `manifest
+  unknown`, which reads like a failed build rather than a differently-named
+  tag. The docs now say how to resolve an old release to its sha, which is
+  the cheap half. Retagging the existing images would be better and is a
+  registry operation, not a code change: `docker buildx imagetools create -t
+  ghcr.io/cameronabrams/htpolynet:v2.5.0 ghcr.io/cameronabrams/htpolynet:<sha>`
+  for each past release, which needs a token with `write:packages`. Worth
+  doing if anyone reports hitting it a second time.
 
 - **The image's Gromacs and AmberTools are unpinned, so two images with
   identical htpolynet code can compute different numbers.** `docker/Dockerfile`
@@ -166,6 +173,311 @@ Coverage as of the last measurement: **38.8%** overall.
 
 ## Cure and repair
 
+- **`cap_min_clearance` has never been calibrated against a working metric.**
+  The 0.150 nm default was chosen in 2.6.0 against a clearance that was pinned
+  at 0.136 nm by a bug, so it fired on 100 % of caps for a reason that had
+  nothing to do with crowding, and the 0.22 nm value rejected before it was
+  rejected on the same broken measurement. The metric is real as of the fix,
+  but the only two data points on a real box -- the accept260 builds on
+  picotte, `/ifs/groups/abramsGrp/cfa22/htpolynet/cyanate-bridge-series/accept260/{unbiased,biased}/`
+  -- were taken with the bug present and are uninformative. The geometry now
+  bounds the achievable clearance at 0.272 nm (cap carbon to the attachment
+  oxygen's aryl carbon, antiparallel), with the chemically sensible ~120
+  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 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
+  density it was mild. Median clearance against random neighbourhoods at 5,
+  15, 33 and 60 heavy atoms per nm^3 ran 0.316 / 0.230 / 0.193 / 0.177 nm with
+  the aryl carbon excluded and 0.233 / 0.222 / 0.191 / 0.174 nm with it in.
+  It pins hard at 0.233 nm -- the C-O-C geometry at 118 degrees -- only in
+  sparse surroundings, where the caps are comfortable anyway; by 33/nm^3 real
+  neighbours are usually closer than the geometric bound and the two agree to
+  about 2 %. So the median was censored from above rather than constant, and
+  the exclusion buys an uncensored statistic rather than rescuing a dead one.
+  Worth knowing before treating a change in that median as physics.
+
+  For the cyanate-ester system specifically, the study session measured the
+  box: heavy-atom count is conversion-independent at 7560 (14,040 atoms less
+  6,480 H, and the cure removes only hydrogen), post-repair mass 100,192
+  g/mol, and measured densities of 1.171--1.198 g/cm^3 across the as-cured,
+  ladder-cold-end and monomer-melt states bracket **~53 heavy atoms per
+  nm^3**. Repair runs before the postcure anneal so the placement-time value
+  is not directly measured, but the spread between those three is smaller than
+  the uncertainty over which stage to attribute. That is inside the swept
+  range, so nothing here extrapolates. Rerunning the sweep at 53/nm^3 gives
+  median blind clearance 0.143 nm (p10 0.075, p90 0.212), median searched
+  clearance 0.179 nm, and about 45 % of caps keeping the O-H direction, with
+  the censored and uncensored medians differing by under 1 %. Three things
+  follow.
+
+  First, and this needs stating at commit granularity rather than as "the
+  clearance fix", because the two commits move the numbers by wildly different
+  amounts in the same release: 5a58d3d, dropping the attachment oxygen, turns
+  `median_clearance_nm` from the constant 0.136 into a distribution, so every
+  placement field moves enormously between the accept260 runs and whatever
+  comes next. That is the released bug being fixed and is expected. 82ddd3e,
+  dropping the aryl carbon, is the <1 % above. Read as one change, the large
+  shift becomes evidence about the aryl-carbon exclusion, which it is not.
+
+  Second, a `blind_median_clearance_nm` anywhere near 0.233 in a box believed
+  to be at this density is unambiguous evidence the box is wrong, since that
+  value is only legitimate in the sparse regime.
+
+  Third, the default sits *above* the blind median: 0.150 against 0.143, which
+  is the same fact as only ~45 % of caps keeping the O-H vector. So at melt
+  density roughly half of all cap sites cannot reach `cap_min_clearance` along
+  the preferred direction and the search is doing real work rather than
+  rubber-stamping. That makes 0.150 demanding but not absurd -- which is more
+  than it was when it was unreachable by construction -- and it suggests the
+  recalibration may move it *down* rather than up. Not the direction either
+  session guessed, and worth not being surprised by.
+
+  Independent check on the scale, by the study session: uncorrelated Poisson
+  at 53/nm^3 has a median nearest-neighbour distance of 0.1462 nm from a probe
+  point, dropping to 0.1236 when minimized over both atoms of a -C#N group at
+  0.116 nm separation. The swept 0.143 sits inside [0.124, 0.146], near the
+  top, which is where the excluded hole around the attachment oxygen should
+  put it. Script at
+  `~/devtests/htpolynet/bridge-series/verify_blind_clearance_scale.py`.
+
+  A trap in that check, flagged by the study session and worth disarming
+  before someone rederives it: the disjoint-sphere floor,
+  `(ln 2 / (8/3 pi rho))^(1/3)`, evaluates to 0.116 nm at rho = 53, which is
+  also `cn_len`, the C-N bond length. That is arithmetic coincidence at this
+  one density and nothing else. The floor tracks number density -- 0.127 at
+  40/nm^3, 0.116 at 53, 0.111 at 60, 0.101 at 80 -- while the bond length is
+  fixed. Anyone who writes down "the floor is the C-N bond length" has made a
+  claim that is invisible here and wrong everywhere else, and has attributed a
+  number-density result to cap geometry.
+
+  Two caveats on those figures. The sweep places uncorrelated Poisson points
+  with a hole around the oxygen, which is not a melt -- real packing is
+  correlated and has excluded volume between the neighbours too -- so it gives
+  a scale, not a prediction, and in particular its `n_below_target` of zero is
+  certainly optimistic. And replicate scatter in this system is topological
+  rather than numerical: the study session measures density sd rising from
+  0.71 kg/m^3 at chi_OCN 0 to 3.25 at 0.746, a factor of 4.6, because at zero
+  conversion every build is the same molecular liquid. Cap sites are network
+  sites, so expect the scatter in `blind_median_clearance_nm` to grow with
+  conversion the same way, and size any series meant to calibrate the default
+  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
+  may be left with 0.15. Two consequences. The placement is worse than it
+  needs to be, for compute that is genuinely negligible -- the angle window
+  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 --
+  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. 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, 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: 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
   by how many bonds their `B`-side residue already carries, because

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

@@ -48,7 +48,16 @@ Diagnostic-log plots:
    cyanate — and the fraction of triazines that survive is what FTIR
    measures at 2270 cm\ :sup:`-1`.  Under random placement that
    fraction is about the cube of the bond conversion, so a run at
-   0.90 leaves a cyanate conversion near 0.73.  htpolynet reports
+   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 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
    both figures at the end of the repair stage and writes them to
    ``repair-summary.yaml``; see :ref:`what repair reports
    <postcure_repair_reporting>`.  If what you want is a structure