htpolynet 2.4.0__tar.gz → 2.6.0__tar.gz

htpolynet-2.6.0/.github/workflows/docker.yml

@@ -0,0 +1,72 @@
+name: Build and push Docker image
+
+on:
+  push:
+    tags:
+      - "v*"
+      - "d*"
+  schedule:
+    # Rebuild weekly (Monday 03:00 UTC) to pick up latest Gromacs/AmberTools
+    - cron: '0 3 * * 1'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # The default image.  conda-forge's preferred linux-64 Gromacs is the
+          # OpenCL build, which cannot drive NVIDIA devices; this image is
+          # CPU-only by design and stays the default so `docker run` on a
+          # laptop keeps working without pulling the CUDA toolkit.
+          - variant: cpu
+            gromacs_build: ""
+            cuda_override: ""
+            tag_prefix: ""
+          # The CUDA image.  gromacs=*=nompi_cuda* depends on the __cuda
+          # virtual package, which conda synthesizes only where an NVIDIA
+          # driver is present -- so the solve fails on this runner unless
+          # CONDA_OVERRIDE_CUDA declares one.  That makes the image buildable
+          # here; it does NOT make it verifiable here.  Nothing in CI can
+          # confirm that mdrun actually offloads, so smoke-test a new CUDA
+          # image on real hardware before recommending it.
+          - variant: cuda
+            gromacs_build: "nompi_cuda"
+            cuda_override: "12.9"
+            tag_prefix: "cuda-"
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Log in to GitHub Container Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Compute tags
+      id: tags
+      run: |
+        if [ "${{ matrix.variant }}" = "cuda" ]; then
+          moving="ghcr.io/cameronabrams/htpolynet:cuda"
+        else
+          moving="ghcr.io/cameronabrams/htpolynet:latest"
+        fi
+        printf 'tags<<EOF\n%s\nghcr.io/cameronabrams/htpolynet:%s%s\nEOF\n' \
+          "$moving" "${{ matrix.tag_prefix }}" "${{ github.sha }}" >> "$GITHUB_OUTPUT"
+
+    - name: Build and push
+      uses: docker/build-push-action@v6
+      with:
+        context: .
+        file: docker/Dockerfile
+        push: true
+        build-args: |
+          HTPOLYNET_COMMIT=${{ github.sha }}
+          GROMACS_BUILD=${{ matrix.gromacs_build }}
+          CONDA_OVERRIDE_CUDA=${{ matrix.cuda_override }}
+        tags: ${{ steps.tags.outputs.tags }}

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

@@ -7,6 +7,172 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-08-26
+
+### Fixed
+
+- **Transferred `-C#N` caps are no longer placed blind, which is what has been
+  killing low-conversion builds.**  The repair stage relocates a cap by
+  putting it along the bridge oxygen's old O-H vector, with no regard for
+  what is already there.  In a box at polymer density that direction is
+  usually occupied: in a synthetic 13000-atom box at 93 atoms/nm³, blind
+  placement put 91 of 158 caps within 0.10 nm of a neighbour and the worst at
+  0.008 nm -- effectively superimposed, which is the step-0 Lennard-Jones
+  term of order 1e15 that no minimization recovers from.
+
+  The cap is now still tried along the O-H vector first, so a cap in open
+  space lands exactly where it always did; only when that direction is
+  occupied does the driver search the sphere for the clearest one, holding
+  both bond lengths fixed so only the orientation moves.  Caps already placed
+  are part of the neighbourhood the next one sees.  On the same synthetic box
+  no cap lands closer than 0.128 nm, at either 158 or 378 transfers.
+
+  This matters more the lower the conversion, because the number of caps to
+  place is an identity -- `total reactive sites - bonds formed` -- so it rises
+  as conversion falls.  `completion_bias` does not reduce it.
+
+- **The stage now says how many fragments it transferred, and complains about
+  the ones it could not place well.**  The transfer count is the quantity that
+  predicts whether repair survives and it was buried in one mid-log INFO line;
+  it is now reported next to the conversion, along with the tightest placement
+  achieved.  A cap that could not reach `cap_min_clearance` (new, default
+  0.15 nm) in any direction is named, with its oxygen, while that is still
+  cheap to act on -- the alternative was working back to cap placement from a
+  GROMACS internal error at step 0.
+
+### Added
+
+- **`completion_bias` now says so when it is ranking the wrong side of the
+  reaction.**  The bias ranks on the `B` reactant, because htpolynet's A2+B3
+  idiom puts the crosslinker there.  Declare the crosslinker as `A` instead
+  and the bias quietly starts completing the *bridges* -- a different claim
+  about which partly-reacted species is a reactive intermediate, and almost
+  certainly not the one that was wanted.  The first cure iteration now
+  compares the initial functionality of the two sides and warns if the `A`
+  side is the more functional one.
+
+  Worth recording why the obvious detector does not work: looking for an
+  all-zero bias key catches nothing, because a difunctional bridge
+  accumulates reactions perfectly well and the key is non-zero.  What
+  separates the two cases is which side carries more reactive sites, and that
+  is readable straight off the atom dataframe -- forming a bond decrements an
+  atom's `z` and increments its `nreactions` in the same operation, so their
+  sum is conserved and reads the same at iteration 0 as at the end.
+
+## [2.5.0] - 2026-08-26
+
+### Added
+
+- **The conversion a cyanate-ester run reports is now the conversion the
+  structure actually carries.**  The cure iterates on bond conversion --
+  bonds formed over bonds possible -- and that is the only number it printed.
+  But `postcure_repair` then dismantles every crosslinker that did not fill
+  all of its sites, so the structure leaving the repair stage contains only
+  *complete* crosslinkers, and the fraction of those is what an experiment
+  measures.  For a trifunctional crosslinker under random placement the
+  second number is roughly the cube of the first, so a run at a bond
+  conversion of 0.90 leaves a cyanate conversion near 0.73 -- and nothing
+  said so.  The repair stage now logs both figures side by side and writes
+  them, with the counts behind them, to `repair-summary.yaml` in the repair
+  directory.
+
+- **`CURE.controls.completion_bias`, an opt-in change to how bond candidates
+  are ranked.**  Candidates have always been ordered by pair separation
+  alone.  Separation is uncorrelated with how many bonds a crosslinker
+  already carries, and the downselection that follows admits at most one bond
+  per residue per iteration, so bonds spread evenly across every crosslinker
+  in the box instead of finishing any of them.  With `completion_bias: true`
+  the number of bonds already on the candidate's `B`-side residue becomes the
+  primary sort key and separation the tie-break within each group, so a
+  crosslinker with two of three sites filled is completed before an untouched
+  one is started.  Nothing else about the search changes: same radius growth,
+  same dragging and relaxation, same probability application, same cycle
+  handling.
+
+  This is a modelling option, not a fix, and it is **off by default** so that
+  every existing config and every shipped example behaves exactly as before.
+  Where a partly-reacted crosslinker is a stable species the old ranking is
+  the more faithful one; where it is a reactive intermediate -- a
+  cyclotrimerizing cyanate ester, whose triazine ring either closes or does
+  not -- the new one is.  Turning it on changes what `desired_conversion`
+  means physically: a config that reaches a crosslinker conversion of 0.76 at
+  `desired_conversion: 0.90` unbiased reaches about 0.90 biased, so runs
+  either side of the setting must be compared at matched crosslinker
+  conversion, not matched `desired_conversion`.
+
+  It also reduces the repair stage's dismantling work: at a bond conversion
+  of 0.90 the driver dismantles roughly 24 crosslinkers instead of 58, and
+  places 72 caps instead of 174.
+
+  **Corrected 2026-08-26, after this section was published:** the original
+  text here claimed the bias also relieves the cap-placement blowup that has
+  killed builds at low conversion.  It does not.  Only *transferred* caps are
+  placed geometrically -- `_place_cyn_along` runs solely where
+  `bonded_o is None` -- and the number of those is an identity,
+  `total_sites - bonds`, with no term for how the bonds are distributed.  So
+  the bias cannot change it at a matched bond conversion, and at a matched
+  crosslinker conversion it makes it *worse*, because it reaches that
+  conversion by forming fewer bonds and every bond not formed is a fragment
+  that must be transferred.  The blowup is a separate defect in
+  `repair/cyanate_cap.py`; see `ROADMAP.md`.
+
+- **A CUDA image, published as `ghcr.io/cameronabrams/htpolynet:cuda`.**  The
+  only image until now installed conda-forge's default linux-64 Gromacs,
+  which is an OpenCL build; Gromacs no longer drives NVIDIA devices through
+  OpenCL, so that image cannot use a GPU at all.  The new tag installs
+  `gromacs=*=nompi_cuda*` from the same Dockerfile and can.
+
+  The CPU image remains `:latest` and remains the default, because the CUDA
+  build pulls in the CUDA toolkit and inflates the image substantially --
+  `docker run` on a laptop should not download a toolkit it cannot use.
+  Both tags are built by the same workflow on the same triggers, and both
+  carry the per-commit tag scheme (`:<sha>` and `:cuda-<sha>`).
+
+  `external.software.gpu_unusable_reasons()` needed no change: it already
+  reconciled detected hardware against what the gmx build can drive, so the
+  CUDA image simply starts passing checks the CPU image fails.
+
+  Verified on hardware, since nothing in CI can check this: on a Picotte
+  V100 node the image reports `GPU support: CUDA` where `:latest` reports
+  OpenCL, `htpolynet info` detects the device instead of calling it
+  `unusable`, and a complete `fetch-example 1` build ran every one of its
+  `gmx mdrun` steps with `-gpu_id 0`, using cuFFT for PME.  The CUDA 12.9
+  runtime in the image runs against that node's 12.4-era driver (550.127.05)
+  under CUDA minor-version compatibility, so a site does not need a
+  bleeding-edge driver to use the tag.
+
+### Changed
+
+- **Repair drivers now return a statistics dict rather than an operation
+  count**, and `htpolynet.repair.run_repair` returns `(total, stats)` rather
+  than a bare total.  This is what carries the crosslinker-conversion figures
+  out to the runtime for reporting.  Only affects code that calls a repair
+  driver directly; the `postcure_repair` config surface is unchanged.
+
+### Fixed
+
+- **The container documentation told users to give the image a GPU, which it
+  cannot use.**  `container-usage.rst` carried a "GPU support" section
+  walking through the NVIDIA Container Toolkit and a `deploy.resources`
+  block reserving nvidia devices, ending "htpolynet will detect the
+  available GPU(s) automatically at startup" -- and then, sixty lines later
+  in the Singularity section, correctly warned that the image's conda-forge
+  Gromacs is an OpenCL build and cannot drive NVIDIA devices at all.  The
+  page contradicted itself, and `README.md` repeated the wrong half with a
+  `docker run --gpus all` example.
+
+  Both now say the same thing: exposing a GPU to this image starts the
+  container and changes nothing about how it computes, so target CPU
+  partitions and do not hold a device another job could use.  The reason and
+  the detection behavior are stated once, under Docker, and the HPC warning
+  points at it for the `--nv`/`--gres=gpu` specifics.
+
+### Changed
+
+- `htpolynet setup-claude` is now discoverable where a new user will meet
+  it: the installation page and the README, rather than only the subcommand
+  reference.
+
 ## [2.4.0] - 2026-08-25
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.4.0
+Version: 2.6.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/
@@ -67,21 +67,24 @@ pip install -e .
 
 Once installed, the user has access to the main ``htpolynet`` command.
 
+If you drive htpolynet with [Claude Code](https://claude.com/claude-code), install the bundled skill so the agent knows how to use it:
+```bash
+htpolynet setup-claude
+```
+This writes `~/.claude/skills/htpolynet/SKILL.md`; nothing is installed there unless you run it.
+
 IMPORTANT NOTES: The programs ``antechamber``, ``parmchk2`` and ``tleap`` from AmberTools must be in your path.  These can be installed using the ``ambertools`` package from ``conda-forge`` or compiled from source.  You also need Gromacs installed so ``gmx`` is in your path.  The examples show how to build input monomer structures using OpenBabel, so to use them you need ``obabel`` in your path as well.
 
 ## Docker
 
-As an alternative to a local installation, a prebuilt container image is published at ``ghcr.io/cameronabrams/htpolynet``.  It bundles htpolynet together with Gromacs, AmberTools, and OpenBabel, so no additional dependencies are required on the host beyond Docker (and, optionally, the NVIDIA Container Toolkit for GPU runs).
+As an alternative to a local installation, a prebuilt container image is published at ``ghcr.io/cameronabrams/htpolynet``.  It bundles htpolynet together with Gromacs, AmberTools, and OpenBabel, so no additional dependencies are required on the host beyond Docker.
 
 Run htpolynet against a configuration file in the current directory:
 ```bash
 docker run --rm -v $(pwd):/work ghcr.io/cameronabrams/htpolynet run config.yaml
 ```
 
-With GPU support:
-```bash
-docker run --rm --gpus all -v $(pwd):/work ghcr.io/cameronabrams/htpolynet run config.yaml
-```
+**The image cannot use a GPU.**  Its Gromacs comes from conda-forge, built against OpenCL rather than CUDA, and Gromacs no longer drives NVIDIA devices through OpenCL.  Passing `--gpus all` starts the container and changes nothing about how it computes; on a cluster, target CPU partitions and do not request `--gres=gpu` or pass `--nv`.  If you need GPU-accelerated Gromacs, install htpolynet natively against a CUDA-enabled Gromacs.
 
 A Docker Compose file is also provided in [docker/compose.yml](docker/compose.yml) for a shorter invocation (``docker compose run --rm htpolynet run config.yaml``).  See [docs/source/user-guide/container-usage.rst](docs/source/user-guide/container-usage.rst) for the full story, including Singularity/Apptainer use on HPC systems.
 

{htpolynet-2.4.0 → htpolynet-2.6.0}/README.md

@@ -33,21 +33,24 @@ pip install -e .
 
 Once installed, the user has access to the main ``htpolynet`` command.
 
+If you drive htpolynet with [Claude Code](https://claude.com/claude-code), install the bundled skill so the agent knows how to use it:
+```bash
+htpolynet setup-claude
+```
+This writes `~/.claude/skills/htpolynet/SKILL.md`; nothing is installed there unless you run it.
+
 IMPORTANT NOTES: The programs ``antechamber``, ``parmchk2`` and ``tleap`` from AmberTools must be in your path.  These can be installed using the ``ambertools`` package from ``conda-forge`` or compiled from source.  You also need Gromacs installed so ``gmx`` is in your path.  The examples show how to build input monomer structures using OpenBabel, so to use them you need ``obabel`` in your path as well.
 
 ## Docker
 
-As an alternative to a local installation, a prebuilt container image is published at ``ghcr.io/cameronabrams/htpolynet``.  It bundles htpolynet together with Gromacs, AmberTools, and OpenBabel, so no additional dependencies are required on the host beyond Docker (and, optionally, the NVIDIA Container Toolkit for GPU runs).
+As an alternative to a local installation, a prebuilt container image is published at ``ghcr.io/cameronabrams/htpolynet``.  It bundles htpolynet together with Gromacs, AmberTools, and OpenBabel, so no additional dependencies are required on the host beyond Docker.
 
 Run htpolynet against a configuration file in the current directory:
 ```bash
 docker run --rm -v $(pwd):/work ghcr.io/cameronabrams/htpolynet run config.yaml
 ```
 
-With GPU support:
-```bash
-docker run --rm --gpus all -v $(pwd):/work ghcr.io/cameronabrams/htpolynet run config.yaml
-```
+**The image cannot use a GPU.**  Its Gromacs comes from conda-forge, built against OpenCL rather than CUDA, and Gromacs no longer drives NVIDIA devices through OpenCL.  Passing `--gpus all` starts the container and changes nothing about how it computes; on a cluster, target CPU partitions and do not request `--gres=gpu` or pass `--nv`.  If you need GPU-accelerated Gromacs, install htpolynet natively against a CUDA-enabled Gromacs.
 
 A Docker Compose file is also provided in [docker/compose.yml](docker/compose.yml) for a shorter invocation (``docker compose run --rm htpolynet run config.yaml``).  See [docs/source/user-guide/container-usage.rst](docs/source/user-guide/container-usage.rst) for the full story, including Singularity/Apptainer use on HPC systems.
 

{htpolynet-2.4.0 → htpolynet-2.6.0}/ROADMAP.md

@@ -8,21 +8,25 @@ Rough ordering within each section is by value, not by effort.
 
 ## Container and deployment
 
-- **CUDA-enabled Gromacs in the container image.** The published image
-  installs Gromacs from conda-forge, whose default linux-64 package is
-  built with OpenCL (not CUDA) and generic `AVX2_256` SIMD. Gromacs no
-  longer drives NVIDIA devices through OpenCL, so the image cannot use a
-  GPU at all, and on an AVX-512 host it also leaves single-core
-  throughput on the table. For reference, Picotte's own module is
-  `AVX_512` + CUDA. Doing this well probably means a second image tag
-  (e.g. `:cuda`) built against `gromacs=*=nompi_cuda*` rather than
-  changing the default, since it pulls in the CUDA runtime and inflates
-  the image substantially, and it needs a GPU-equipped runner or a
-  manual build to verify. The CPU image should stay the default so that
-  `docker run` on a laptop keeps working. Note that
-  `software.gpu_unusable_reasons()` already reasons about this correctly,
-  so a CUDA image would simply start passing its checks rather than
-  needing new logic.
+- **The container's Gromacs is generic `AVX2_256`, on both tags.** The
+  `:cuda` image fixes the GPU half of this problem and not the SIMD half:
+  conda-forge builds for a portable baseline, so on an AVX-512 host both
+  images leave single-core throughput on the table relative to a natively
+  built or module-provided Gromacs. This is inherent to installing Gromacs
+  from conda-forge and cannot be fixed by choosing a different build string
+  -- it would take building Gromacs in the image, which trades the weekly
+  rebuild's freshness for a long build and a host-specific artifact.
+
+  Confirmed on hardware 2026-08-25: the `:cuda` image on Picotte's gpu001
+  reports `SIMD instructions: AVX2_256` on a node whose CPUs support
+  AVX-512, and Gromacs itself prints the hint that "AVX_512 ...
+  instructions will perform best on this hardware". Still unquantified, and
+  that is what would decide whether it matters: nobody has run the same
+  system against Picotte's own `abramsGrp-gromacs/2021.2/cpu-gpu` module on
+  the same node. Note Gromacs also observes that AVX2 is often the better
+  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;
@@ -91,6 +95,40 @@ Coverage as of the last measurement: **38.8%** overall.
 
 ## Release and distribution
 
+- **The release preflight cannot tell whether the *previous* release
+  actually shipped to conda-forge.** `scripts/check-conda-sync.py` compares
+  `pyproject.toml`'s runtime deps against the feedstock recipe, which
+  catches dependency drift the autotick bot cannot handle. It says nothing
+  about whether the bot's last PR ever merged. That gap ran for four
+  releases: `pip check` in the recipe's test section started failing when
+  `ambertools` began pulling in distributions with unsatisfiable metadata,
+  so the bot PRs for 2.2.0, 2.3.0, 2.3.1 and 2.4.0 all sat red and unmerged
+  while conda-forge served 2.1.0 from June. Every one of those releases
+  passed the preflight, because the deps genuinely did match. Nobody
+  noticed until a bot email got read.
+
+  Fixed on 2026-08-26 by dropping `pip check` from the recipe's test section
+  (it fails on `ambertools`' bundled distributions, never on ours) and
+  merging the 2.4.0 bump, which closed the other three. **The damage is
+  permanent and visible**: conda-forge's version list for this package now
+  reads 1.0.9 -> 2.1.0 -> 2.4.0, because 2.2.0, 2.3.0 and 2.3.1 were never
+  built there and never will be. That is worth knowing as a diagnostic in
+  its own right -- a published version list that skips releases the project
+  actually made is the retroactive signature of this failure, in any
+  package, without needing to have run any check at the time.
+
+  The check is cheap: query `api.anaconda.org/package/conda-forge/htpolynet`
+  for `latest_version` and compare it against the version being superseded.
+  A mismatch does not have to block the release -- the fix is usually on the
+  feedstock, not here -- but it must be loud, because the failure mode is
+  silence. Consider also listing open PRs on the feedstock, since a red bot
+  PR is the specific thing to look at.
+
+  The deeper point is that publishing to conda-forge is the one leg of the
+  release that completes *after* `release.sh` exits and on someone else's
+  infrastructure, so it is the only one that can fail without anything here
+  noticing.
+
 - **External services still keyed to the old repo identity.** The Aug 2026
   transfer from `AbramsGroup/HTPolyNet` to `cameronabrams/htpolynet` moved
   the code but left every integration pointing at the old owner. Three
@@ -105,6 +143,12 @@ Coverage as of the last measurement: **38.8%** overall.
   query". Fix the RTD project URL, then activate the tagged version. Worth
   keeping this list as the checklist if the repo ever moves again.
 
+  A fourth instance turned up on 2026-08-26 and is fixed: the conda-forge
+  recipe's `about:` block still gave `AbramsGroup/HTPolyNet` for `home` and
+  `dev_url`, and a `doc_url` of `abramsgroup.github.io/HTPolyNet` that
+  returns 404. Corrected in the same feedstock PR that unblocked the version
+  bumps.
+
 
 - **Mint a software DOI.** Enable the Zenodo GitHub integration for
   `cameronabrams/htpolynet`, then the next `scripts/release.sh` run
@@ -120,6 +164,61 @@ Coverage as of the last measurement: **38.8%** overall.
   it read `3.10 | 3.11 | 3.12 | 3.13`, which CI already verifies at both
   ends.
 
+## Cure and repair
+
+- **`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's A2+B3 idiom puts the multifunctional crosslinker in the `B`
+  position -- as example 6 does. A user who declares the crosslinker as `A`
+  gets the bias pointed at their *bridges* instead: not a no-op, a different
+  claim about which partly-reacted species is a reactive intermediate. That
+  case is now warned about at the first cure iteration, by comparing the
+  initial functionality of the two sides, so it is visible rather than silent
+  -- but it is still not *served*. The generalization is small (rank on the
+  `A` side, or on the sum of both) and each variant is a different physical
+  claim, none of them run. Do it when someone has a chemistry that needs it,
+  and make them say which side rather than inferring it from functionality:
+  the warning's heuristic is good enough to flag a probable mistake and not
+  good enough to silently redirect the ranking on.
+
+- **Nobody has run example 6 with `completion_bias` on.** The ranking is
+  unit-tested -- ordering, tie-breaks, missing residues, the fallback when a
+  `.grx` predates the `nreactions` attribute -- but the acceptance criteria
+  that matter are system-scale and need gmx and a multi-hour build:
+  incomplete triazines should collapse from tens to ~1 at
+  `desired_conversion: 0.90`, crosslinker conversion should rise from ~0.76
+  to ~0.90, `TAZ + CYN/3` must still equal the initial triazine count
+  exactly, and atom conservation must still be exact. If the incomplete
+  count does *not* collapse, the sort key is not surviving as far as the
+  truncation and that is where to look. Until someone runs it, the directive
+  is documented as untested at scale.
+
+- **Cap placement is greedy and never backtracks.** Transferred `-C#N`
+  fragments are now placed against the local neighbourhood rather than blindly
+  along the old O-H vector, which removes the catastrophic overlaps: in a
+  synthetic box at polymer density, blind placement put 91 of 158 caps within
+  0.10 nm of a neighbour and the worst at 0.008 nm, while the neighbourhood
+  search puts none below 0.128 nm. What it does not do is relax. Each cap is
+  placed once, in the clearest direction available *at that moment*, and later
+  caps must work around it; in a genuinely over-packed box a residue of
+  sub-target placements remains (17 of 158, 33 of 378 in the same synthetic
+  test) and is reported rather than fixed. The next lever is minimizing
+  incrementally as caps land, or placing in order of how constrained each site
+  is rather than in match order. Do it if the reported clearance warnings turn
+  out to correlate with builds that still die -- the instrumentation to decide
+  that now exists, and did not before.
+
+- **`bdf.loc[:abs_max]` takes one bond more than the limit.** In
+  `curecontroller.py::_searchbonds`, the truncation that applies
+  `max_conversion_per_iteration` uses `.loc` with a slice, which is
+  inclusive of its endpoint, so an iteration limited to `n` bonds forms
+  `n + 1`. Harmless in practice -- the limit is a throttle, not a
+  correctness bound -- but it is off by one, and fixing it changes the
+  trajectory of every existing config by one bond per throttled iteration.
+  Worth doing at a version boundary where a small reproducibility break is
+  already expected, not before.
+
 ## Usability
 
 - **`gen-slurm-script` doesn't stage to scratch.** The emitted script

{htpolynet-2.4.0 → htpolynet-2.6.0}/docker/Dockerfile

@@ -20,10 +20,22 @@
 #
 #   docker run --rm -v $(pwd):/work ghcr.io/cameronabrams/htpolynet run config.yaml
 #
-# GPU support (requires nvidia-container-toolkit):
+# GPUs: the DEFAULT image cannot use one.  Its Gromacs is the conda-forge
+# OpenCL build, and Gromacs no longer drives NVIDIA devices through OpenCL, so
+# --gpus all starts the container and changes nothing about how it computes.
 #
-#   docker run --rm --gpus all -v $(pwd):/work \
-#       ghcr.io/cameronabrams/htpolynet run config.yaml
+# Build the CUDA variant instead, which installs gromacs=*=nompi_cuda*:
+#
+#   CONDA_OVERRIDE_CUDA=12.9 docker build -f docker/Dockerfile \
+#       --build-arg GROMACS_BUILD=nompi_cuda \
+#       --build-arg CONDA_OVERRIDE_CUDA=12.9 \
+#       -t ghcr.io/cameronabrams/htpolynet:cuda .
+#
+# CONDA_OVERRIDE_CUDA is required to build on a machine with no NVIDIA driver:
+# the CUDA package depends on the __cuda virtual package, which conda
+# synthesizes only where a driver is present, so the solve fails on an
+# ordinary CI runner without it.  Running the resulting image does need
+# nvidia-container-toolkit and --gpus all.
 
 FROM condaforge/miniforge3:latest
 
@@ -39,9 +51,18 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
         gosu \
     && apt-get clean && rm -rf /var/lib/apt/lists/*
 
-RUN mamba install -y -n base -c conda-forge \
+# Which Gromacs build to install.  Empty (the default) takes whatever
+# conda-forge considers best, which for linux-64 is the OpenCL build -- correct
+# for a CPU image, and unable to drive an NVIDIA device.  Pass
+# GROMACS_BUILD=nompi_cuda for the CUDA image; that package depends on the
+# __cuda virtual package, so a build host without an NVIDIA driver also needs
+# CONDA_OVERRIDE_CUDA set to a version to satisfy the solve.
+ARG GROMACS_BUILD=
+ARG CONDA_OVERRIDE_CUDA=
+
+RUN CONDA_OVERRIDE_CUDA="${CONDA_OVERRIDE_CUDA}" mamba install -y -n base -c conda-forge \
         ambertools \
-        gromacs \
+        "gromacs${GROMACS_BUILD:+=*=${GROMACS_BUILD}*}" \
         parmed \
         rdkit \
     && mamba clean -afy

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

@@ -39,6 +39,23 @@ Diagnostic-log plots:
    with k<3 are the ones the postcure repair stage subsequently
    dismantled.
 
+.. warning::
+
+   The 90 % above is a **bond** conversion, and it is not the number
+   this structure would be reported as in an experiment.  Repair
+   dismantles every triazine that did not fill all three of its
+   sites, so what survives is complete triazines plus unreacted
+   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
+   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
+   that really is 90 % converted, see the
+   ``CURE.controls.completion_bias`` directive.
+
+
 For end-to-end traces:
 
 .. code-block:: console

{htpolynet-2.4.0 → htpolynet-2.6.0}/docs/source/install.rst

@@ -218,6 +218,24 @@ OpenBabel sources are in ``~/Downloads`` and the install prefix is
 Then set ``PATH``, ``LD_LIBRARY_PATH``, and ``BABEL_LIBDIR`` to point
 at ``${HOME}/opt/obabel``.
 
+Driving htpolynet with Claude Code
+----------------------------------
+
+``htpolynet`` ships a skill for `Claude Code
+<https://claude.com/claude-code>`_ that teaches the agent how to use it:
+start from the nearest example, describe monomers in their active form,
+check a configuration before spending compute, and recognize the failure
+modes that are known rather than mysterious.  Install it once, after
+installing the package:
+
+.. code-block:: console
+
+    $ htpolynet setup-claude
+
+Installing ``htpolynet`` never writes to ``~/.claude/`` on its own; the
+skill is copied only when you run this.  See :doc:`/user-guide/usage` for the options,
+including how to scope the skill to a single project.
+
 Other Prerequisites
 -------------------
 

{htpolynet-2.4.0 → htpolynet-2.6.0}/docs/source/user-guide/configs/configs-for-run.rst

@@ -208,6 +208,8 @@ In this section we show all subdirectives for each of the five main directives i
     ``gromacs``                              list                 any ``mdp`` keyword:value pairs to include in all ``mdp`` files in the ``CURE`` sequence
     =====================================    =================    =====================
 
+.. _cure.controls:
+
     * ``CURE.controls`` parameters
 
         ==================================    =================   ======================
@@ -221,10 +223,15 @@ In this section we show all subdirectives for each of the five main directives i
         ``late_threshold``                    float [0-1]         conversion above which bond probabilities are ignored (default 0.85)
         ``max_conversion_per_iteration``      float [0-1]         upper limit, as a fraction of total reactable bonds, on the new bonds formed in any single iteration (default 1.0)
         ``min_allowable_bondcycle_length``    int                 minimum number of C atoms allowed in a cycle of C-C bonds that form via polymerization (default 0, disallow all such cycles)
+        ``completion_bias``                   bool                rank bond candidates by how many bonds their ``B``-side residue already carries, and only then by distance, so that partly-reacted crosslinkers are completed before untouched ones are started (default ``False``)
         ==================================    =================   ======================
 
       The ``min_bonds_per_iteration`` knob batches small late-stage finds together: instead of accepting whichever 1-2 bonds happen to lie within the initial 0.5 nm radius and immediately moving on to relax + equilibrate, the search grows the radius until at least 10 (the default) eligible bonds have been gathered.  On the DGEBA/PACM example, raising it from 1 to 10 cuts the cure iteration count from 41 to 15; raising further to 20 only buys one more iteration.  The default of 10 is roughly the diminishing-returns sweet spot.
 
+      ``completion_bias`` changes which bonds a CURE iteration chooses, and with it what ``desired_conversion`` means physically, so it is off by default and every shipped example runs without it.  Candidates are ranked by separation alone by default.  Separation is uncorrelated with how many bonds a crosslinker already carries, so in an A2+B3 system the bonds spread evenly across every ``B`` in the box rather than finishing any of them: at a bond conversion of 0.90, a trifunctional crosslinker placed at random is complete with probability 0.90\ :sup:`3`, about 0.73.  Turning ``completion_bias`` on makes the number of bonds already on the candidate's ``B``-side residue the primary sort key, with separation as the tie-break inside each group, so a crosslinker with two of three sites filled is finished before an untouched one is started.  The ``B`` side is where htpolynet's A2+B3 idiom puts the crosslinker; declare it as ``A`` instead and the bias completes your *bridges*, so the first cure iteration compares the two sides' functionality and warns if the more functional one is on ``A``.  Nothing else about the search changes -- same radius growth, same dragging and relaxation, same probabilities, same cycle handling.
+
+      Which conversion this matters for depends on the chemistry.  Where a partly-reacted crosslinker is a real, stable species, the unbiased ranking is the more faithful one.  Where it is a reactive intermediate -- a cyclotrimerizing cyanate ester, whose triazine ring either closes or does not -- the biased ranking is, and the difference shows up directly in what :ref:`postcure repair <postcure_repair>` has to dismantle.  Note that the two settings reach different structures at the same ``desired_conversion``: a config that yields a crosslinker conversion of 0.76 at ``desired_conversion: 0.90`` unbiased will yield about 0.90 biased.  Comparisons across the setting have to be made at matched crosslinker conversion, not matched ``desired_conversion``.
+
       The ``min_allowable_bondcycle_length`` refers to the fact that in systems that polymerize via activation of carbon-carbon double bonds, it is possible in the htpolynet implementation that the "head" of a chain of C-C bonds can attack the "tail" and form a cycle, because those represent atom types that can react.  It is unclear whether such cycles actually form; if a monomer remains bound to a radical initiator it is hard to see how the head of the growing chain could attack it, but maybe it could.  Setting ``min_allowable_bondcycle_length`` to zero (the default) disallows any bonds that would form cycles involving only atoms that were once part of C=C double bonds.  (Think about the backbone of polystyrene, for example.)  In a given CURE iteration, htpolynet tests the full set of suggested bonds to see if together they result in any cycles, and for each nascent cycle longer than ``min_allowable_bondcycle_length``, htpolynet will disallow the nascent bond that has the longest initial length.
 
 .. _cure.drag: