htpolynet 2.4.0__tar.gz → 2.5.0__tar.gz

htpolynet-2.5.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.5.0}/CHANGELOG.md

@@ -7,6 +7,111 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 nearly empties the repair stage, which is worth having on its own
+  terms: repair has been seen to blow up at low conversion, where it places
+  hundreds of caps and transfers hundreds of fragments and the cap-placement
+  geometry produces atom overlaps that a step-0 minimization cannot recover
+  from.  Completing crosslinkers instead of decorating them leaves it almost
+  nothing to do.
+
+- **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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.4.0
+Version: 2.5.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.5.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.5.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,55 @@ 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 no bias at all, silently, because every candidate scores zero on a
+  difunctional bridge and the ordering collapses back to distance. The
+  generalization is small (rank on the `A` side, or on the sum of both) but
+  each variant is a different physical claim about which partly-reacted
+  species is an intermediate, and none of them has been run. Do it when
+  someone has a chemistry that needs it, and make them say which side.
+
+- **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.
+
+- **The repair stage's cap placement does not scale to low conversion.**
+  At a bond conversion of 0.90 the triazine-to-cyanate driver places on the
+  order of a hundred caps; at 0.30 it places hundreds and transfers hundreds
+  of fragments, and runs have died at the repair NVT with a step-0 potential
+  energy around 7e15 dominated by Lennard-Jones -- atom overlap from cap
+  placement. It is packing-dependent rather than systematic: siblings at the
+  same conversion survive. `completion_bias` makes the stage nearly empty
+  and so hides this, but the geometry is still wrong for a crowded box, and
+  a sub-gel-point study that wants the unbiased ranking will hit it again.
+  The fix is in `repair/cyanate_cap.py::_place_cyn_along` and the greedy
+  matcher around it: place against the local neighbourhood rather than along
+  the old O-H vector alone, or minimize incrementally as caps are placed.
+
+- **`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.5.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.5.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.5.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.5.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.  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:

{htpolynet-2.4.0 → htpolynet-2.5.0}/docs/source/user-guide/container-usage.rst

@@ -151,18 +151,52 @@ otherwise it is treated as an ``htpolynet`` subcommand.  So:
   Desktop on Windows always runs as the current user).  Output files will be
   owned correctly without any changes.
 
-GPU support
-"""""""""""
+GPUs: use the ``:cuda`` tag, not the default image
+""""""""""""""""""""""""""""""""""""""""""""""""""
 
-If you have an NVIDIA GPU and the
-`NVIDIA Container Toolkit <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html>`_
-installed, add a ``deploy`` block to your local copy of ``compose.yml``:
+Two images are published from the same Dockerfile, and they differ only in
+which conda-forge Gromacs they install:
+
+=============================================== ======================================
+Tag                                             Gromacs build
+=============================================== ======================================
+``ghcr.io/cameronabrams/htpolynet:latest``      OpenCL (CPU only) --- the default
+``ghcr.io/cameronabrams/htpolynet:cuda``        CUDA
+=============================================== ======================================
+
+.. warning::
+
+  **The default image cannot use a GPU.**  Its Gromacs is the conda-forge
+  OpenCL build, and Gromacs no longer supports OpenCL on NVIDIA devices, so
+  there is no code path that can drive the device.  Passing ``--gpus all`` to
+  ``docker run``, or adding a ``deploy.resources`` block reserving ``nvidia``
+  devices to ``compose.yml``, starts the container successfully and changes
+  nothing about how it computes.  On a shared machine, do not hold a GPU that
+  another job could use.
+
+  ``htpolynet`` detects this at startup rather than failing obscurely later:
+  it reports ``unusable`` in its GPU banner, drops any ``gpu_id`` from the
+  config's ``mdrun_options``, and adds ``-nb cpu`` to the ``mdrun`` command
+  line.  So the default image on a GPU host is merely wasteful, never wrong.
+
+For GPU runs, pull the ``:cuda`` tag and give the container a device.  This
+needs the `NVIDIA Container Toolkit
+<https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html>`_
+on the host:
+
+.. code-block:: console
+
+  $ docker run --rm --gpus all -v $(pwd):/work \
+        ghcr.io/cameronabrams/htpolynet:cuda run config.yaml
+
+Under Compose, point the ``image:`` at the ``:cuda`` tag and add a
+reservation:
 
 .. code-block:: yaml
 
   services:
     htpolynet:
-      image: ghcr.io/cameronabrams/htpolynet:latest
+      image: ghcr.io/cameronabrams/htpolynet:cuda
       volumes:
         - ${PWD}:/work:Z
         - htpolynet-home:/home/htpolynet
@@ -181,7 +215,17 @@ installed, add a ``deploy`` block to your local copy of ``compose.yml``:
   volumes:
     htpolynet-home:
 
-``htpolynet`` will detect the available GPU(s) automatically at startup.
+``htpolynet`` detects the available device(s) at startup and lets Gromacs use
+them.  Confirm from its GPU banner rather than assuming: if the banner still
+says ``unusable``, you are running the default image under a ``:cuda`` name,
+or the container was not given a device.
+
+.. note::
+
+  The ``:cuda`` image is substantially larger, because the CUDA build of
+  Gromacs pulls in the CUDA toolkit.  That is why the CPU image remains the
+  default: ``docker run`` on a laptop should not have to download a toolkit
+  it cannot use.
 
 HPC Users (Singularity/Apptainer)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -216,15 +260,14 @@ Then run it, binding your working directory:
 
 .. warning::
 
-  **The bundled Gromacs is not a CUDA build.**  The image installs Gromacs
-  from conda-forge, whose default package is compiled with OpenCL rather than
-  CUDA support, and Gromacs no longer supports OpenCL on NVIDIA devices.  So
-  ``--nv`` and ``--gres=gpu:...`` buy you nothing with this image: target a
-  CPU partition instead.  ``htpolynet`` detects this at startup, reports
-  ``unusable`` in its GPU banner, drops any ``gpu_id`` from the config's
-  ``mdrun_options``, and adds ``-nb cpu`` to the ``mdrun`` command line.  If
-  you need GPU-accelerated Gromacs on a cluster, run htpolynet natively
-  against a CUDA-enabled Gromacs module rather than through this container.
+  **Pull the right tag.**  For the reason given above under `GPUs: use the
+  ``:cuda`` tag, not the default image`_, ``--nv`` and ``--gres=gpu:...`` buy
+  you nothing with the default image: requesting a GPU only lengthens your
+  queue wait and idles a device another job could use.  Either target a CPU
+  partition, or pull ``docker://ghcr.io/cameronabrams/htpolynet:cuda`` and
+  pass ``--nv``.  Your cluster's own CUDA-enabled Gromacs module is still
+  worth benchmarking against the image, which is built for generic
+  ``AVX2_256`` and may lose on a newer host.
 
 Example shell scripts work the same way as under Docker — the entrypoint will
 recognize ``bash`` as an executable and exec it directly: