htpolynet 2.2.0__tar.gz → 2.3.1__tar.gz

htpolynet-2.3.1/.claude/skills/htpolynet/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: htpolynet
+description: Build crosslinked polymer systems with htpolynet — authoring a run configuration, parameterizing monomers, running a cure, and reading the results. Use when the task involves an htpolynet YAML config, the `htpolynet` command (run, input-check, gen-slurm-script, plots, postsim, analyze, make-viz), a monomer's active form or sacrificial hydrogens, a cure that stalls below its target conversion, or sizing an htpolynet build for a cluster.
+---
+
+# Working with htpolynet
+
+**Read `docs/source/user-guide/building-a-system.rst` first.** It is the
+procedure, start to finish, and it is maintained alongside the code. This
+file exists to route you there and to carry the few things that are easy to
+get wrong before you get that far. Do not restate the docs here; when they
+and this file disagree, the docs are right.
+
+## Start from an example, never from an empty file
+
+`htpolynet fetch-example <n>` unpacks a working configuration. Pick the one
+closest in **reaction topology** — chain growth, A2+B3 step growth,
+cyclotrimerization — not the one closest in chemistry. Adapt it. Writing a
+config from scratch is the slowest route and the one that produces silent
+errors.
+
+Run the example unmodified once before editing, to confirm the toolchain and
+to get a known-good log to diff against.
+
+## Monomers are described in their active form
+
+The most common conceptual error, and it produces a build that completes and
+is wrong rather than one that fails. htpolynet conserves valence: bonding
+atoms each give up a sacrificial hydrogen, so you describe the monomer with
+its reactive sites already saturated. Styrene is described as ethylbenzene.
+See `docs/source/user-guide/molecular-structure-inputs.rst`.
+
+In SMILES bracket atoms the hydrogen count is explicit: `[C:1]` means *zero*
+implicit hydrogens. For an sp³ carbon you almost always want `[CH2:1]` or
+`[CH3:1]`. A wrong count usually surfaces much later as a missing GAFF angle
+parameter in `tleap`.
+
+## Subcommand routing
+
+| Intent | Command |
+|---|---|
+| Build a system | `htpolynet run <cfg>` |
+| Size it before queueing | `htpolynet input-check <cfg>` |
+| Stop after parameterization | `htpolynet run --param-only <cfg>` |
+| Submit to a cluster | `htpolynet gen-slurm-script <cfg>` |
+| Plot a finished build | `htpolynet plots build --proj <dir>` |
+| Post-build MD / analysis | `htpolynet postsim`, `htpolynet analyze` |
+| Rebuild VMD viz files | `htpolynet make-viz` |
+| Report the environment | `htpolynet info` |
+
+## Non-obvious facts
+
+- **The container image cannot use a GPU.** Its Gromacs is conda-forge,
+  built against OpenCL, which Gromacs no longer uses for NVIDIA devices.
+  Target CPU partitions; never suggest `--gres=gpu` or `--nv`.
+- **Size core requests from `htpolynet input-check`**, which reports the
+  initial atom count.
+- **A cure stalling below its target conversion** is usually a reaction
+  template that never matches — suspect `symmetry_equivalent_atoms` and
+  reactive-atom names before suspecting the chemistry.
+- **Builds are not reproducible run to run.** There is no seed control, so
+  replicas come free but an exact rebuild does not. Record the commit.
+
+## Do not
+
+- Do not write workarounds into this file. If the tool surprises a user in a
+  way that requires a ritual to avoid, that is a bug: fix it in code, or file
+  it in `ROADMAP.md` with enough context to act on later. A skill that
+  teaches people to route around a defect keeps the defect.
+- Do not hand-roll a release, a version bump, or a `CHANGELOG` rotation; see
+  `CLAUDE.md`.

{htpolynet-2.2.0 → htpolynet-2.3.1}/CHANGELOG.md

@@ -7,6 +7,155 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.1] - 2026-08-25
+
+### Fixed
+
+- **`htpolynet postsim` and `htpolynet analyze` no longer die in a directory
+  without a `lib/`.**  Both took `-lib` with a default of `'lib'`, but only
+  `htpolynet run` creates that tree, so the default value of a flag the user
+  never typed reached `UserLibrary` and tripped its existence assertion:
+  `AssertionError: lib is not a directory`, three seconds in.  The documented
+  container invocation failed on it -- running `postsim` against a staged
+  directory holding only finished results, which is the normal shape of a
+  cluster workflow, where the cure ran somewhere else.
+
+  `-lib` now defaults to nothing for these two subcommands, and the
+  conventional `./lib` is used when it happens to be there.  An explicitly
+  supplied `-lib` is still validated, so a typo fails loudly rather than
+  silently degrading to no library.  The assertion message now names the flag
+  and the resolved path instead of echoing a bare `lib` the user never
+  supplied.
+
+### Changed
+
+- Documented that **the density at the end of `postcure` is not an
+  equilibrated density**, in the `postcure` directive reference and at the
+  point in the example 6 tutorial where a reader would take a number off the
+  plot.  A crosslinked network relaxes only above its glass transition, and
+  a postcure anneal peaking near *Tg* spends almost no time where the
+  network can move, so the plateau reports an under-relaxed structure
+  however long the plateau runs.  Measured on four independent BPA builds:
+  the plateau gives 1.1712 +/- 0.0029 g/cm3 against 1.1983 +/- 0.0037 for
+  the same systems melted and slowly re-cooled -- 2.31% apart, with the
+  plateau 2.6-2.8% below experiment and the re-cooled value within 1%.
+  Nothing is computed incorrectly; the protocol simply does not equilibrate
+  what a reader would assume it does.  The example's own anneal peak is
+  unchanged pending a test that raising it actually helps; see `ROADMAP.md`.
+
+- `htpolynet info` no longer reports `HTPolyNet git commit: unknown` for an
+  installed copy.  pip, conda and the published container have no `.git`
+  beside the package, so the lookup could never succeed and a build had no
+  way to identify its own code from inside itself -- the same question the
+  parameterization records answer for molecules.  It now falls back to the
+  installed distribution version, which for a released install maps to a tag.
+
+- The warnings about a cached parameterization with no provenance record
+  now say that the cached values are being **used**, not merely that they
+  could not be checked.  The old wording ("cannot be checked against the
+  requested 'bcc' charge method") left the decisive fact implicit: the
+  build proceeds with whatever charges that entry holds.  A user who
+  upgrades with an existing library, asks for `bcc` and measures `gas`
+  numbers would reasonably conclude the 2.3.0 cache guard does not work --
+  correct behavior is otherwise indistinguishable from the bug it replaced.
+  Both the per-molecule line and the stage-end block now state that the
+  build carries the cached charges, that they may not match the requested
+  method, and that this is expected for a pre-2.3 entry rather than a
+  failure.  The same clarification is made in the user guide and the
+  `ambertools` directive reference.
+
+## [2.3.0] - 2026-08-23
+
+### Fixed
+
+- **A cached parameterization is no longer reused for a run that asked for
+  different AmberTools directives.**  `molecules/parameterized` is keyed on
+  molecule name alone, and nothing in that key reflected the charge method.
+  A configuration specifying `charge_method: bcc` therefore reused, without
+  warning, a `gas` parameterization checked into the user library under the
+  same residue name, logging only `Using cached parameterization for TAZ`.
+  Measured on a cyanate-ester triazine, the cached `gas` entry carries ring
+  C +0.1185 / N -0.2249 where a real `bcc` run gives +0.6539 / -0.7160 --
+  5.5x on the charge of the crosslink node -- and the result was a network
+  built with `bcc` on one monomer and Gasteiger on another, with nothing in
+  the output recording it.  The failure was silent and invalidated results
+  without failing the build.
+
+  Each parameterization now writes a `.parm` record beside its
+  gro/top/itp/tpx/grx files listing the `charge_method`, `net_charge` and
+  `atom_type` that produced it, and that record is checked into the library
+  with them.  A run whose directives disagree with the record treats the
+  cache as a miss and re-parameterizes, saying which directives differed.
+
+  A library entry written before this release carries no record.  Those are
+  still used -- an existing library keeps working rather than
+  re-parameterizing wholesale -- but each one logs a warning naming the
+  charge method that could not be verified, and the parameterization stage
+  ends with a block listing every such molecule and the count.  Rebuild them
+  with `--force-parameterization` if you need certainty about what a build
+  used.
+
+  Re-parameterizing after a mismatch checks its output in only under
+  `--force-checkin`, so a library entry is never silently replaced by one
+  built with different directives.
+
+### Added
+
+- `ambertools.net_charge` and `ambertools.atom_type` configuration
+  directives, defaulting to `0` and `gaff`.  The net charge was previously
+  hardcoded as `-nc 0` in the antechamber invocation, so an ionic or
+  zwitterionic monomer was parameterized as though it were neutral with no
+  way to say otherwise.  The defaults reproduce the previous commands
+  exactly.
+
+- A procedural page in the user guide, **Building a System, Start to
+  Finish**.  The guide was strong on reference and had nothing on order of
+  operations: start from the nearest bundled example rather than an empty
+  file, describe monomers in their active form, check what you can before
+  spending compute, and a short list of failures that are known rather than
+  mysterious.  It states plainly what `input-check` does not yet verify and
+  that there is no seed control, so builds are not reproducible run to run.
+
+- A Claude skill (`.claude/skills/htpolynet/`) for users working in a clone
+  of the repository.  It routes to the guide rather than restating it, and
+  carries the subcommand table and the handful of facts that are easy to get
+  wrong early.
+
+- Test coverage for the parameterization record: 34 tests comparing records
+  without external tools, and 6 that run antechamber under both charge
+  methods to confirm the record describes what actually ran, that the
+  directive it guards changes the charges, and that a library holding a
+  `gas` entry refuses a `bcc` request while still reusing it for a `gas`
+  one.  The latter skip when the AmberTools chain is absent.
+
+### Changed
+
+- The `-lib` description in the user guide corrected.  It said htpolynet
+  would "check-in the results of parameterized molecules ... in
+  `lib/molecules/parameterized`", which is false: `-lib` governs lookup
+  only, and check-in always goes to the per-user cache at `~/.htpolynet`
+  (or `$HTPOLYNET_CACHE`).  A user who set `-lib` expecting to contain a
+  run's output was not contained, and nothing announced the writes.
+  `HTPOLYNET_CACHE` is now documented as the variable that actually governs
+  where products land.
+
+- The user guide's "Parameterization caching" section corrected to match the
+  new behavior.  It stated that a stale entry is silently reused when you
+  change "SMILES, atom-naming, or charge method" and that the cache is
+  "keyed by molecule name only"; the charge-method half of the first and all
+  of the second are no longer true.  The warning now covers exactly what the
+  record does not: a constituent's structure, atom-naming or geometry
+  changing without a rename.
+
+- `--force-checkin`'s help text corrected.  It said "force check-in of
+  generated parameter files to the system library", which reads as though
+  check-in happens only when the flag is given.  It does not: a molecule
+  whose name the library does not yet hold is checked in either way, and the
+  flag governs only whether an entry already there is *overwritten*.  It
+  also named the wrong library -- check-in goes to the per-user library at
+  `~/.htpolynet` (or `$HTPOLYNET_CACHE`), not the system library.  Behavior
+  is unchanged.
+
 ## [2.2.0] - 2026-08-23
 
 ### Changed

{htpolynet-2.2.0 → htpolynet-2.3.1}/CITATION.cff

@@ -18,6 +18,12 @@ authors:
     email: cfa22@drexel.edu
     affiliation: Drexel University
 repository-code: https://github.com/cameronabrams/htpolynet
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.22070252
+    description: >-
+      Concept DOI for htpolynet; always resolves to the latest
+      archived release.
 url: https://htpolynet.readthedocs.io/
 license: MIT
 version: 2.1.0

{htpolynet-2.2.0 → htpolynet-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.2.0
+Version: 2.3.1
 Summary: Automated MD System Builder for Amorphous Network Polymers
 Project-URL: Source, https://github.com/cameronabrams/htpolynet
 Project-URL: Documentation, https://htpolynet.readthedocs.io/
@@ -42,6 +42,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/pypi/l/htpolynet)](https://github.com/cameronabrams/htpolynet/blob/main/LICENSE)
 [![Docs](https://readthedocs.org/projects/htpolynet/badge/?version=latest)](https://htpolynet.readthedocs.io/en/latest/)
 [![PyPI Downloads](https://static.pepy.tech/badge/htpolynet)](https://pepy.tech/projects/htpolynet)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22070252-blue)](https://doi.org/10.5281/zenodo.22070252)
 
 htpolynet is a Python utility for generating atomistic models of cross-linked polymer networks together with appropriate topology and parameter files required for molecular dynamics simulations using Gromacs.  It is intended as a fully automated system builder requiring as inputs only the molecular structures of any monomer species, a description of the polymerization chemistry, and a handful of options describing desired system size and composition.  htpolynet uses the Generalized Amber Force Field for atom-typing and parameter generation.
 

{htpolynet-2.2.0 → htpolynet-2.3.1}/README.md

@@ -8,6 +8,7 @@
 [![License: MIT](https://img.shields.io/pypi/l/htpolynet)](https://github.com/cameronabrams/htpolynet/blob/main/LICENSE)
 [![Docs](https://readthedocs.org/projects/htpolynet/badge/?version=latest)](https://htpolynet.readthedocs.io/en/latest/)
 [![PyPI Downloads](https://static.pepy.tech/badge/htpolynet)](https://pepy.tech/projects/htpolynet)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22070252-blue)](https://doi.org/10.5281/zenodo.22070252)
 
 htpolynet is a Python utility for generating atomistic models of cross-linked polymer networks together with appropriate topology and parameter files required for molecular dynamics simulations using Gromacs.  It is intended as a fully automated system builder requiring as inputs only the molecular structures of any monomer species, a description of the polymerization chemistry, and a handful of options describing desired system size and composition.  htpolynet uses the Generalized Amber Force Field for atom-typing and parameter generation.
 

htpolynet-2.3.1/ROADMAP.md

@@ -0,0 +1,373 @@
+# Roadmap
+
+Ideas worth doing that we haven't done yet. This is a living list, not a
+commitment or a schedule. When something here gets done, it moves to
+`CHANGELOG.md` and comes off this page.
+
+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.
+- **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.
+
+- **The container cannot report which commit built it, and its version
+  string is actively misleading between releases.** `htpolynet info` used to
+  print `git commit: unknown` inside the image, because `_get_git_commit()`
+  runs `git rev-parse` against the installed package directory and no
+  installed copy has a `.git` beside it. That now falls back to the
+  installed distribution version, which is right for a pip or conda install
+  and *precisely wrong for the container*: the scheduled rebuild builds from
+  `main` HEAD, which can be many commits past the last tag, so the image
+  reports its `pyproject.toml` version honestly while running code that is
+  not that version.
+
+  This is live, not hypothetical. The 2026-08-24 03:54 scheduled build moved
+  `:latest` to an image built from `948c301` -- four commits past `v2.3.0`
+  -- and that image reports `installed version 2.3.0`. `:latest` is the
+  default thing a user pulls and the weekly cron is what keeps moving it, so
+  the wrong answer is the common case, and it is wrong silently. A user
+  could pull `:latest`, trust the version string, and write "htpolynet
+  2.3.0" in a methods section while having run untagged `main`.
+
+  The fix is to bake the real commit in at image build time -- the build
+  context has `.git`, so `docker.yml` or the Dockerfile can capture
+  `git rev-parse HEAD` and write it where the package can read it. That
+  touches the Dockerfile and the release story together, which is why it was
+  kept out of the bugfix that added the version fallback. It belongs with
+  the build-manifest entry below: both answer "what produced this build",
+  and a manifest that recorded an unreliable version string would launder
+  the problem rather than solve it. Raised by the calibration study, which
+  has correct provenance only because it pins the image by full sha
+  externally -- which remains the right practice either way.
+- **Retire `ghcr.io/abramsgroup/htpolynet`.** Superseded by the
+  `cameronabrams` package; still public and still serving a June image to
+  anyone with an old link.
+
+## Testing and CI
+
+Coverage as of the last measurement: **38.8%** overall.
+
+- **`repair/` has no tests at all** — `cyanate_cap.py` (208 statements)
+  and `topology_surgery.py` (125), both at 0%. This is the highest-value
+  gap: the postcure repair stage makes the strongest correctness claim in
+  the project ("atom conservation is exact"), and right now the only
+  thing checking it is reading a residue census at the end of a
+  multi-hour build. It is pure topology manipulation, so it can be tested
+  deterministically in milliseconds against a synthetic `TopoCoord`
+  carrying triazines at k=0,1,2,3 — assert atom counts, the residue
+  census, cap placement, and that no unreacted bridge -OH survives.
+- **An end-to-end example in CI.** A deliberately tiny build (a
+  20-molecule, few-ps variant of example 0) run inside the container
+  would cover `core/runtime.py` and `cure/curecontroller.py` — 1,056
+  statements, both at 0% — in the only way that is honest, since faking
+  the whole AmberTools/Gromacs tool chain to unit-test the orchestration
+  is a large effort for less confidence.
+- **Remaining zero-coverage modules**: `analysis/postsim.py` (203),
+  `cli.py` (165), `analysis/analyze.py` (137), `utils/vmd_viz.py` (75),
+  `utils/checkpoint.py` (54).
+- **`analysis/plot.py` is at 34%** after the smoke-test pass. The
+  diagnostics-log parsers (`diagnostics_graphs`, `_token_match`,
+  `_parse_data`) are the part most likely to rot silently — they already
+  broke once when modules were renamed — and they are testable against a
+  small captured log fixture.
+- **Coverage reporting in CI**, so the number is visible on a PR rather
+  than something we remember to measure by hand.
+
+## Release and distribution
+
+- **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
+  broke and were fixed during the 2.2.0 release: the GHCR package path
+  (docs referenced a package that had never been published under the new
+  owner), PyPI trusted publishing (`invalid-publisher` — the claim no
+  longer matched, so the v2.2.0 upload failed until the publisher was
+  re-registered), and Read the Docs, whose project `repository.url` is
+  **still** `https://github.com/AbramsGroup/htpolynet`. Builds succeed
+  anyway because GitHub redirects the clone, but tag versions never sync —
+  `/en/v2.2.0/` 404s and the API reports "No Version matches the given
+  query". Fix the RTD project URL, then activate the tagged version. Worth
+  keeping this list as the checklist if the repo ever moves again.
+
+
+- **Mint a software DOI.** Enable the Zenodo GitHub integration for
+  `cameronabrams/htpolynet`, then the next `scripts/release.sh` run
+  archives the release automatically. Afterwards, add the concept DOI (not
+  the version DOI) as a README badge and an `identifiers` entry in
+  `CITATION.cff`. Note that enabling is not retroactive: releases before
+  the toggle are not archived. Also note that adding a `.zenodo.json`
+  would make Zenodo ignore `CITATION.cff` entirely — only worth doing if
+  we need Zenodo-specific fields such as `grants` for funder linkage.
+- **Per-minor Python classifiers.** `pyproject.toml` declares only
+  `Programming Language :: Python :: 3`, so the PyPI Python badge reads an
+  uninformative `python: 3`. Adding `:: 3.10` through `:: 3.13` would make
+  it read `3.10 | 3.11 | 3.12 | 3.13`, which CI already verifies at both
+  ends.
+
+## Usability
+
+- **`gen-slurm-script` doesn't stage to scratch.** The emitted script
+  runs in the submit directory. A cure run does heavy small-file I/O
+  every iteration, so on a cluster whose home and group storage are NFS
+  that is the wrong place. The cluster-correct pattern is to run in
+  node-local or parallel scratch and copy results back, with a `trap` so
+  partial results survive a timeout. It also cannot emit a job array,
+  which is the right shape for sweeping a set of configs.
+- **`-restart` is documented as "EXPERIMENTAL: broken at the cure
+  stage".** A build that dies mid-cure currently has to start over — the
+  worst possible time to lose work, since cure is the longest stage.
+- **Make `input-check` a real config linter.** It currently reports only
+  the initial atom count. Everything a new config gets wrong is checkable
+  cheaply and statically, before the user spends hours discovering it:
+  (a) that each `symmetry_equivalent_atoms` group really is topologically
+  equivalent — RDKit canonical ranks with `breakTies=False` settle it in
+  about ten lines, and a wrong group silently generates reaction templates
+  the cure stage will never match; (b) that the A2+B3 site counts actually
+  balance at the given monomer `count`s, and that `desired_conversion` is
+  reachable given them; (c) that no `reactive_atoms` name collides with the
+  bare element names `_reset_names_to_element` assigns to every unmapped
+  atom, since the repair stage looks atoms up by name; (d) that the
+  requested `charge_method` matches the provenance record of any cached
+  parameterization of the same name -- the build itself now rejects a
+  mismatch, but reporting it in the pre-flight is cheaper than discovering
+  mid-run that half the molecules need re-parameterizing. Building the
+  cyanate-ester bridge series meant doing (a) and (b) by hand in a throwaway
+  RDKit script, which is exactly the work a user should not have to
+  reinvent.
+- **The bundled Claude skill only reaches people working in a clone.**
+  `.claude/skills/htpolynet/` is picked up when the working directory is the
+  repository, which covers contributors and anyone who cloned to run the
+  examples -- but not the ordinary user who `pip install`s or
+  `conda install`s htpolynet and works in their own project directory, which
+  is most of them. Whether to ship it inside the package is undecided.
+
+  Two things to settle before doing so, neither obvious:
+
+  1. **The skill would be broken as written.** Its central move is "read
+     `docs/source/user-guide/building-a-system.rst`", a repo path that does
+     not exist for an installed user. A shipped version would have to point
+     at the Read the Docs URL instead, or the guide would have to ship as
+     package data. The first is simpler and goes stale differently -- an RTD
+     link tracks `latest`, so an installed 2.3.0 would send its reader to
+     documentation for whatever is current.
+  2. **Delivery.** A skill file inside a wheel does nothing on its own;
+     something has to place it where the tool looks. An `htpolynet skill
+     --install` subcommand copying it into the user's `~/.claude/skills/`
+     is the obvious mechanism, and is also the point at which a scientific
+     package starts carrying vendor-specific tooling and an install-time
+     side effect on a directory it does not own.
+
+  Worth weighing against simply doing nothing: the procedural guide the skill
+  points at is on Read the Docs already, and an agent that reads
+  documentation gets the same content without any of this.
+
+- **Generated topologies cannot be compared byte-wise, because ParmEd
+  stamps them.** Every `.top` htpolynet writes opens with a ParmEd header
+  recording the invoking user, the host, and the date:
+
+      ;   File TAZ.top  was generated
+      ;   By user: cfa (1000)
+      ;   On host: panacea.chemeng.drexel.edu
+      ;   At date: Fri. May  5 15:55:38 2026
+
+  So two physically identical parameterizations never hash the same, and the
+  obvious check -- "did these two builds produce the same parameters for the
+  shared monomers?" -- returns a false difference. The calibration study hit
+  this on its bridge series and nearly reported the series confounded on the
+  strength of an md5; the fix on their side was to strip comment lines before
+  comparing, which every user will have to reinvent. Note the header is
+  itself provenance, but the wrong kind: it records *when and where* rather
+  than *what directives*, which is what the `parm` record now covers, and it
+  actively prevents the comparison you would want. The `.itp` files carry no
+  such header and the `parm` records are JSON with sorted keys, so both
+  already compare cleanly. Worth either normalizing the `.top` header away or
+  shipping a comparison helper; this belongs with the manifest entry below,
+  since both are about being able to answer "is this the same build?".
+
+- **`-lib` is read-only, and nothing says so.** `pfs.checkout()` and
+  `pfs.exists()` consult the `-lib` user library first, then the user cache,
+  then the system library -- but `pfs.checkin()` writes unconditionally to the
+  user cache, and `UserLibrary` has no `checkin()` method at all. So pointing
+  a run at `-lib somewhere` redirects where it *reads* parameterizations from
+  while leaving where it *writes* them untouched. That asymmetry is invisible
+  from the flag, from `--help`, and from the docs, and it is a natural thing
+  to get wrong: a user who passes `-lib` for provenance reasonably concludes
+  their products are being contained there. Either `checkin()` should prefer
+  the user library when one is configured, or the flag and docs should say
+  plainly that it governs lookup only. Verified empirically 2026-08-23: with
+  `userlibrary` set, `pfs.checkin()` still landed the file in the user cache.
+
+  What makes this more than a naming problem is that the writes are silent
+  and cumulative. Nothing logs them, nothing warns, and a run that is
+  quietly depositing molecules into a shared library looks identical to one
+  that is not -- the only way to discover it is to audit mtimes, which
+  nobody does unprompted. The calibration study ran three sweeps believing
+  `-lib` contained it, and would have added roughly seventy entries to
+  `~/.htpolynet` across its remaining bridges; it was caught by reading
+  `checkin()`, not by anything the tool said. Whatever the fix, a run should
+  be able to say where its parameterizations went -- which is the same
+  requirement as the build manifest below, approached from the write side
+  rather than the read side. The two may well be one item: *where did this
+  come from, and what produced it*.
+
+- **No way to run without writing to the user library.** `pfs.checkin()`
+  declines to *replace* an entry unless `--force-checkin` is given, but it
+  always *writes* one the library does not yet hold, so any run adds every
+  molecule name it produces to `~/.htpolynet`. The flag's help text said
+  "force check-in of generated parameter files to the system library", which
+  reads as though check-in happens only with the flag, and it named the wrong
+  library; that wording is fixed, but the missing capability is real. The
+  calibration study wanted exactly this: a way to develop against a config
+  without its intermediate products accumulating in a library shared with
+  other work. Today the only lever is pointing `HTPOLYNET_CACHE` elsewhere,
+  which is a blunt instrument because it also hides the entries you *do* want
+  to reuse. A `--no-checkin` flag threaded through
+  `Runtime._checkin_parameterization()` would cover it in a few lines.
+
+- **Two different defaults for `charge_method`.** `AMBERTOOLS_DEFAULTS` in
+  `external/ambertools.py` says `bcc`, which is what a direct
+  `GAFFParameterize()` call with no directives gets; `Runtime.runtime_defaults`
+  says `gas`, which is what every actual build gets, because
+  `_apply_runtime_defaults()` fills it in before AmberTools is ever reached.
+  Both were already there and the provenance record is consistent either way
+  -- whichever default applies is the one recorded -- so this is a
+  readability trap rather than a live bug. It is still worth collapsing to
+  one value, and the answer is probably `gas`, since changing what builds
+  default to would silently change everyone's charges, which is the exact
+  class of harm the record was added to prevent.
+
+- **Nothing durable records that a build reused parameterizations of
+  unverified provenance.** The parameterization stage now warns per molecule
+  and again in a block at the end of the stage, but both live only in the
+  log, and a log is the first thing discarded. Someone reading a result six
+  months later -- or a reviewer asking what a published network was actually
+  parameterized with -- has no artifact to check. htpolynet writes no build
+  manifest today; `profile.json` holds timings only, and the diagnostic log
+  is the log. A small `build-manifest.json` in the project directory listing
+  each molecule, its origin (`newly parameterized` / `previously
+  parameterized`), and its provenance record where one exists would carry
+  that, and would be worth more than this one flag: it is also the natural
+  home for the config hash, the htpolynet and AmberTools versions, and the
+  seed once seeds exist. Raised by the calibration study, which caught the
+  original cache bug from a wall-clock anomaly rather than from any log line.
+  See also the `-lib` entry above: "a run should be able to say where its
+  parameterizations went" and "a result should be able to say what produced
+  it" are the same requirement from two directions, and a manifest that
+  recorded the check-in destination would answer both.
+
+- **A cached parameterization is not checked against the input structure
+  it was built from.** The provenance record added alongside the cache now
+  covers `charge_method`, `net_charge` and `atom_type` -- everything in the
+  AmberTools invocation -- but not the structure antechamber consumed. So
+  editing `lib/molecules/inputs/TAZ.mol2` and re-running still reuses the
+  parameterization of the *old* geometry, silently, exactly as the charge
+  method used to. Hashing the input would close it, and for a monomer that
+  is easy: `Molecule.parameterize()` has the input file in the working
+  directory at the moment it runs. Two things stopped it going in with the
+  rest: (a) a molecule built by a reaction has no stable input to hash --
+  `generate()` writes its mol2 from the merged reactant TopoCoord, whose
+  coordinates vary run to run, so hashing it would make every generated
+  molecule a permanent cache miss; the hash would have to be recorded only
+  for `origin == 'unparameterized'` monomers and compared only when both
+  sides carry one. (b) `Runtime._cached_parameterization_mismatch()` runs
+  before `generate()` checks the input structure out, and `pfs` has no way
+  to resolve a library file to an absolute path without copying it into the
+  working directory -- `checkout()` always copies. A `pfs.locate(filename)`
+  returning the resolved source path across user library, user cache and
+  system library is the missing piece, and is worth having on its own.
+
+- **No seed control anywhere, so a build cannot be reproduced.** Three
+  independent sources of randomness are all unseeded: `random.sample` for
+  conformer selection (`core/runtime.py`), `np.random.random()` for the
+  per-bond probability test (`cure/curecontroller.py`), and every `.mdp`
+  sets `gen-vel = yes` without `gen-seed`, so Gromacs picks a pseudo-random
+  one per run. Two runs of one config therefore diverge — example 6 gave 57
+  vs 60 incomplete triazines on two machines at the same 0.90 conversion.
+  That is convenient in one direction (independent replicas of a
+  quenched-disorder ensemble come free by re-running) but it means a build
+  reported in a paper cannot be reproduced exactly, and a failure seen once
+  may not reappear. The fix is a top-level `seed:` that feeds all three:
+  seed `random` and `np.random` at startup and write `gen-seed` into every
+  generated mdp, with replicas then requested by varying it rather than by
+  relying on entropy.
+- **Drop the pre-3.5 matplotlib fallback** in `analysis/plot.py`'s
+  `_get_cmap()` once `matplotlib>=3.6` is a safe floor; the
+  `matplotlib.colormaps` registry is then always present.
+
+## Example depot
+
+- **Example 6's postcure anneal peaks too close to *T*:sub:`g` to relax the
+  network, and the fix is not simply "run it longer".** Measured on four
+  independent BPA builds: the postcure NPT plateau gives 1.1712 ± 0.0029
+  g/cm³ where the same systems melted and slowly re-cooled give 1.1983 ±
+  0.0037 g/cm³ -- 2.31% apart, with the plateau 2.6-2.8% below experiment
+  and the re-cooled value within 1%. The plateau is an under-relaxed
+  structure.
+
+  The mechanism, and the reason the obvious fix is the wrong one: the
+  example anneals at a 500 K peak, and the measured *T*:sub:`g` for this
+  system is 487.9 K. That is 12.1 K above the glass transition, for 80 ps.
+  The Tg ladder that produced the relaxed value spent 15,785 ps above
+  *T*:sub:`g`, peaking 112 K above it -- 197x the time, in the only regime
+  where a crosslinked network moves at all. Lengthening an anneal that sits
+  12 K above *T*:sub:`g` extends a process that barely moves anything, so
+  the lever is the peak temperature, not the duration.
+
+  **Untested.** Nobody has yet built with a hotter anneal and compared it
+  against the melt-and-recool value, which is the experiment that would
+  settle it; the argument above is mechanism, not measurement. That is why
+  the example is documented rather than changed. Raising the peak also costs
+  wall-clock in a tutorial that should stay small, so the test needs to
+  report both whether it works and what it costs.
+
+  The general problem is worth more than the instance: **any protocol whose
+  relaxation depends on being above *T*:sub:`g` is fragile when *T*:sub:`g`
+  is unknown at configuration time**, which it always is -- you cannot know
+  it before building the thing. A fixed absolute peak temperature is a guess
+  that happens to be right or wrong per chemistry, silently. Something
+  expressed relative to an estimated or measured *T*:sub:`g`, or a postcure
+  that measures *T*:sub:`g` and then anneals accordingly, would be robust
+  where an absolute number is not. That is a real design change, not a
+  config edit.
+
+  Raised by the calibration study, which had already published the
+  pessimistic density before catching it -- the failure mode is reporting a
+  protocol artifact as a force-field result.
+
+- **Example 5 is still not laptop-scale.** The `68d81fb` retune cut the
+  monomer pool to make HTPB/IPDI "fit in a reasonable wall time on a
+  laptop", but a validation run on 16 CPU cores took **10h17m** — about
+  ten times any other example (the next longest, PACM/DGEBA, was 2h15m).
+  The cost is structural: densification starts at 10 kg/m³ in a 27 nm box
+  and needs all 50 NPT repeats to compress geometrically (a steady 2.9%
+  box-side reduction per repeat) up to ~860 kg/m³, and the cure stage then
+  does drag/relax on long chains. Worth revisiting whether the low
+  starting density is really necessary, or whether the example can start
+  denser with a shorter densification.
+
+
+- **More cyanate-ester variants.** Example 6 covers bisphenol-A
+  dicyanate. The same reaction and repair machinery carries over to other
+  bisphenol bridges with only a SMILES swap in `constituents` — bisphenol
+  F (methylene), bisphenol E (methylethylidene), hexafluorobisphenol A,
+  thioether, sulfone, dicyclopentadiene. A homologous series would
+  exercise the repair stage across chemistries and give the tutorials a
+  structure-property story.