htpolynet 2.2.0__tar.gz → 2.3.0__tar.gz

htpolynet-2.3.0/.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.0}/CHANGELOG.md

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

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

@@ -0,0 +1,255 @@
+# 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.
+- **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.
+- **`-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 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.

{htpolynet-2.2.0 → htpolynet-2.3.0}/docs/source/htpolynetpackage.rst

@@ -55,6 +55,11 @@ htpolynet.core
    :undoc-members:
    :show-inheritance:
 
+.. automodule:: htpolynet.core.paramcache
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 .. automodule:: htpolynet.core.projectfilesystem
    :members:
    :undoc-members:

htpolynet-2.3.0/docs/source/user-guide/building-a-system.rst

@@ -0,0 +1,172 @@
+.. _building_a_system:
+
+Building a System, Start to Finish
+----------------------------------
+
+The other pages in this guide are reference: what each subcommand accepts,
+what each configuration directive means, what the program does internally.
+This page is the procedure — the order to do things in, and where each step
+can go wrong.  It assumes ``htpolynet`` is installed (see :doc:`/install`)
+and that ``htpolynet info`` reports AmberTools and Gromacs on your ``PATH``.
+
+Start from the nearest example, not from an empty file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A working configuration is a few hundred lines and most of it is not
+chemistry-specific.  Writing one from scratch is the slowest possible route.
+Pick whichever bundled example is closest in *reaction topology* to what you
+want and edit it:
+
+.. code-block:: console
+
+    $ htpolynet fetch-example 1     # linear chain growth (polystyrene)
+    $ htpolynet fetch-example 2     # A2 + B4 thermoset (bisGMA/styrene)
+    $ htpolynet fetch-example 3     # amine + epoxy (PACM/DGEBA)
+    $ htpolynet fetch-example 6     # cyclotrimerization (cyanate ester)
+
+Closeness in topology matters more than closeness in chemistry.  If you are
+building a step-growth thermoset from a difunctional and a tetrafunctional
+monomer, example 2 is a better starting point than an example that happens
+to share a functional group but polymerizes by chain growth.
+
+Run the example unmodified once before editing it.  It confirms your
+toolchain works, and it gives you a known-good log to compare against when
+your own configuration misbehaves.
+
+Describe monomers in their *active* form
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the single most common conceptual error, and it produces a build
+that runs to completion and is wrong rather than one that fails.
+
+``htpolynet`` conserves valence: when two atoms bond, each gives up a
+**sacrificial hydrogen**.  So the structure you describe is not the textbook
+monomer — it is the monomer with its reactive sites already saturated.
+Styrene is described as ethylbenzene.  See
+:ref:`molecular_structure_inputs` for the full explanation and pictures;
+do not skip it.
+
+Prefer writing SMILES directly into the ``constituents`` block with
+RDKit atom-map labels, which names reactive atoms by chemical identity
+rather than by file index:
+
+.. code-block:: yaml
+
+    constituents:
+      STY:
+        smiles: "c1ccccc1[CH2:1][CH3:2]"
+        reactive_atoms: {1: C1, 2: C2}
+
+Watch the hydrogen counts inside brackets.  ``[C:1]`` means *zero* implicit
+hydrogens; for an sp³ carbon you nearly always want ``[CH2:1]`` or
+``[CH3:1]``.  A wrong count typically surfaces much later as a missing GAFF
+angle parameter in ``tleap``, which is a long way from its cause.
+
+Check what you can before spending compute
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    $ htpolynet input-check my-system.yaml
+
+This reports the atom count of the initial system, which is what you size a
+core request against.  It is fast and worth running every time you change
+monomer counts.
+
+Be aware of what it does **not** yet check.  It does not verify that
+``symmetry_equivalent_atoms`` groups really are topologically equivalent,
+that your A2 + B3 site counts balance, or that ``desired_conversion`` is
+reachable given the monomer counts you supplied.  Those are all silent
+failure modes today: a wrong symmetry group generates reaction templates
+the cure stage will simply never match, and the build spends its full
+wall-clock reaching a conversion it could never have reached.  If a cure
+stalls well below the conversion you asked for, suspect these first.
+
+Run it
+^^^^^^
+
+.. code-block:: console
+
+    $ htpolynet run my-system.yaml
+
+Locally this is fine for the bundled examples.  For anything production-sized,
+generate a batch script rather than writing one:
+
+.. code-block:: console
+
+    $ htpolynet gen-slurm-script my-system.yaml
+
+Size the core request from the ``input-check`` atom count.  If you are using
+the container image, target **CPU partitions**: its Gromacs comes from
+conda-forge and is built against OpenCL, which Gromacs no longer uses to
+drive NVIDIA devices, so the image cannot use a GPU.  Requesting
+``--gres=gpu`` or passing ``--nv`` buys nothing and may cost you queue time.
+See :doc:`container-usage`.
+
+Parameterization runs first and is cached across projects and across
+directories.  The first run of a new chemistry pays several minutes per
+species; later runs reuse that work.  Read
+:ref:`parameterization_caching` before you rely on it — in particular,
+editing a monomer's structure without renaming it will silently reuse the
+old parameterization.
+
+Replicas, and what "the same" means
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each ``htpolynet run`` in the same base directory creates its own project
+directory, so replicas are just repeated invocations of the same
+configuration.
+
+There is currently **no seed control**.  Conformer selection, the per-bond
+probability test, and Gromacs velocity generation are all unseeded, so two
+runs of one configuration diverge.  This is convenient in one direction —
+independent replicas of a quenched-disorder ensemble come free — but it
+means a specific build cannot be reproduced exactly, and a failure seen
+once may not reappear.  Record the commit you built with if the result
+matters.
+
+Look at what you built
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    $ htpolynet plots build --proj proj-0
+    $ htpolynet make-viz -top final.top -gro final.gro
+
+``plots build`` gives traces, the reaction graph, and cluster-size
+distributions; ``make-viz`` regenerates VMD visualization files from an
+existing topology/coordinate pair.  For thermomechanical properties, run
+post-build simulations and analyses:
+
+.. code-block:: console
+
+    $ htpolynet postsim postsim.yaml --proj proj-0
+    $ htpolynet plots post --proj proj-0
+    $ htpolynet analyze analyze.yaml --proj proj-0
+
+See :doc:`configs/configs-for-postsim` and :doc:`configs/configs-for-analyze`.
+
+When something goes wrong
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A short list of traps that are known rather than mysterious:
+
+* **The cure stalls below your target conversion.**  Usually a reaction
+  template that never matches: check ``symmetry_equivalent_atoms`` and your
+  reactive-atom names before suspecting the chemistry.
+
+* **A ``tleap`` error about a missing parameter.**  Usually an atom typed
+  wrongly because of a hydrogen-count error in a SMILES bracket atom.
+
+* **Results that do not match the configuration you are reading.**  Suspect
+  a stale cache entry: a structure edit without a rename reuses the old
+  parameterization.  ``--force-parameterization`` rebuilds.
+
+* **A build that dies during cure.**  ``-restart`` is documented as
+  experimental and is currently broken at the cure stage, which is the worst
+  place to lose work since cure is the longest phase.  Treat a dead cure as
+  a restart from the beginning.
+
+* **Anything else.**  Run ``htpolynet info`` and include its output when
+  reporting a problem; it reports the versions of every external tool the
+  build depends on.