htpolynet 2.1.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.3.0/.github/workflows/conda-forge-sync.yml

@@ -0,0 +1,56 @@
+# Check that pyproject.toml's runtime dependencies are in sync with
+# the conda-forge feedstock's `requirements.run` block.
+#
+# Two modes:
+#   - Push/PR to main: warn-only.  Drift adds a job-summary line so a
+#     reviewer notices but the workflow doesn't fail.
+#   - Tag push (v*): strict.  Drift fails the job, so a release tag
+#     can't ship with a recipe known to be broken.
+#
+# The script that does the work is scripts/check-conda-sync.py; see
+# its header for what gets compared and the PyPI→conda-forge name
+# remap.
+
+name: conda-forge sync check
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Run sync check
+        id: check
+        run: |
+          set +e
+          out="$(./scripts/check-conda-sync.py 2>&1)"
+          rc=$?
+          echo "$out"
+          {
+            echo '## conda-forge sync check'
+            echo ''
+            echo '```'
+            echo "$out"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+          echo "rc=$rc" >> "$GITHUB_OUTPUT"
+
+      - name: Strict mode on tag push
+        if: startsWith(github.ref, 'refs/tags/v') && steps.check.outputs.rc != '0'
+        run: |
+          echo "::error::pyproject.toml deps drift from conda-forge recipe; release blocked."
+          echo "Either prepare the recipe update on the feedstock before tagging,"
+          echo "or plan to supersede the autotick-bot PR with a manual update."
+          exit 1

{htpolynet-2.1.0 → htpolynet-2.3.0}/.github/workflows/docker.yml

@@ -32,5 +32,5 @@ jobs:
         file: docker/Dockerfile
         push: true
         tags: |
-          ghcr.io/abramsgroup/htpolynet:latest
-          ghcr.io/abramsgroup/htpolynet:${{ github.sha }}
+          ghcr.io/cameronabrams/htpolynet:latest
+          ghcr.io/cameronabrams/htpolynet:${{ github.sha }}

htpolynet-2.3.0/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  unit:
+    name: unit (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # floor and current; pyproject requires-python is >=3.10
+        python-version: ['3.10', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      # Tests needing antechamber/tleap/parmchk2/gmx skip themselves when those
+      # binaries are absent, so this runner needs no MD toolchain.  Everything
+      # that does not shell out still runs -- ~250 tests in a few seconds.
+      - name: Run unit tests
+        run: >
+          uv run --python ${{ matrix.python-version }} --extra test
+          pytest tests/unit -q

{htpolynet-2.1.0 → htpolynet-2.3.0}/.gitignore

@@ -17,8 +17,6 @@ __pycache__/
 # C extensions
 *.so
 
-CLAUDE.md
-
 # Distribution / packaging
 .Python
 build/
@@ -105,6 +103,10 @@ ipython_config.py
 #   install all needed dependencies.
 #Pipfile.lock
 
+# uv lockfile — regenerated locally; not committed (htpolynet is a
+# library, not a leaf application that needs a pinned dependency tree).
+uv.lock
+
 # PEP 582; used by e.g. github.com/David-OConnor/pyflow
 __pypackages__/
 

{htpolynet-2.1.0 → htpolynet-2.3.0}/CHANGELOG.md

@@ -7,6 +7,275 @@ 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
+
+- Container docs' HPC section now leads with `htpolynet gen-slurm-script`
+  instead of a hand-written batch script -- the subcommand is already
+  Apptainer-aware (`--sif`), but was documented only in `usage.rst`,
+  so container users had no reason to find it.  The old example
+  defaulted to `--gres=gpu:1` and `--nv`, which is actively wrong for
+  this image (see the GPU entry under Fixed); replaced with a warning
+  explaining why CPU partitions are the right target, plus guidance on
+  sizing cores against system size and keeping the submit directory off
+  NFS.
+- `rdkit` promoted from the `[smiles]` optional extra to a core
+  runtime dependency.  Every depot example uses atom-mapped SMILES
+  (`[CH:1]`, `[NH2:2]`, etc.), so RDKit is required for any normal
+  user workflow; the obabel-only fallback that the extra was
+  guarding remains supported but isn't exercised by anything we
+  ship.  `pip install htpolynet` (or `uv pip install -e .` from the
+  repo) now installs RDKit automatically; `'htpolynet[smiles]'` is
+  no longer needed (and is gone from `install.rst`).
+- Example 5 (`5-htpb-ipdi.yaml`) retuned for shorter wall-clock.
+  The saving comes from a smaller system: the monomer pool drops
+  from 125/50/50 to 50/20/20 (IPD/DHT/THT), keeping IPD at
+  (2·DHT + 3·THT)/2 so every crosslinker still has both NCO groups
+  spoken for at full conversion.  Precure anneal segments go 500 →
+  200 ps and postcure postequilibration 1000 → 200 ps.
+  Densification was re-balanced for the smaller box in the other
+  direction — `initial_density` 50 → 10 kg/m³ to give the long HTPB
+  chains room to relax without overlap, and NPT `repeat` 20 → 50 so
+  the looser start still reaches target density — so densification
+  itself does more work, on a much smaller system.  The build still
+  converges.
+
+### Added
+
+- **CI now runs the unit suite** (`.github/workflows/test.yml`), on pushes
+  to `main` and on every pull request, across Python 3.10 and 3.13.  Nothing
+  ran the tests automatically before, which is how a broken import sat in
+  `test_resources.py` aborting collection indefinitely.
+- Tests that shell out to `gmx` / `antechamber` / `tleap` / `parmchk2` now
+  skip when those binaries are absent instead of failing, so a runner with
+  no MD toolchain still reports the ~250 tests that do not need one (in
+  under 4 seconds).
+- Test coverage for `external/slurm.py` (0% -> 98%),
+  `external/smiles_input.py` (0% -> 84%), `utils/inputcheck.py`
+  (0% -> 70%), and `analysis/plot.py` (6.7% -> 34%), none of which had
+  any.  Overall coverage 34.4% -> 38.8%.  The plot smoke tests were
+  checked against the pre-fix module under matplotlib 3.11 and do fail
+  there, so they would have caught the `cm.get_cmap` removal.
+- Docker image now carries an `org.opencontainers.image.source` label,
+  linking the published GHCR package back to the repository.  Without
+  it the package is orphaned: it doesn't appear on the repo page and
+  doesn't inherit repository-based access permissions.
+- `test` optional-dependency extra (`uv run --extra test pytest tests/unit`),
+  with `dev` kept as an alias so both spellings work.
+- `scripts/run_all_examples.sh`: fail-fast preflight that checks
+  every required native tool (`htpolynet`, `antechamber`,
+  `parmchk2`, `tleap`, `gmx`, `obabel`, `dot`) is on `PATH` before
+  starting any build.  Better than hitting the first missing
+  binary hours into a partial run.  Header docstring also gains a
+  Prerequisites block pointing at `install.rst` for setup.
+- Docker image now built on `condaforge/miniforge3:latest` (was
+  `continuumio/miniconda3:latest`).  Miniforge is community-
+  maintained, conda-forge only, no Anaconda Inc. terms-of-service
+  exposure.  Package installs switched from `conda` to `mamba` for
+  faster solves.  Verified end-to-end: built container's
+  `antechamber`, `gmx 2025.4-conda_forge`, `obabel`, `parmed`,
+  `rdkit`, and `htpolynet 2.1.0` all callable; `htpolynet
+  fetch-example 6 && htpolynet input-check` round-trips.
+- `install.rst` rewritten around the uv + Miniforge workflow: per-
+  repo `uv venv` + `uv pip install -e .` for the Python side,
+  separate `mamba create -n gromacs` / `mamba create -n ambertools`
+  envs for the native MD binaries (both env bins appended to PATH
+  in `.bashrc`).  Documents `uv tool install --editable .` as the
+  way to get a global `htpolynet` command callable from any shell.
+  Legacy conda-only one-stop install demoted to a subsection.
+- `htpolynet.utils.profiling` (moved from `htpolynet.profiling`).
+  Small utility module — fits utils/ scope; keeps the package root
+  focused on actual subpackages.  Three internal call sites
+  updated.
+
+### Fixed
+
+- **API reference documented a module that no longer exists.**
+  `docs/source/htpolynetpackage.rst` autodoc'd `htpolynet.driver`,
+  removed in the 2.0 refactor, so the package's top-level API section
+  rendered empty; it now documents `htpolynet.cli`.  The same page was
+  missing nine modules that do exist -- most notably the entire
+  `repair` subpackage (`repair.cyanate_cap`, `repair.topology_surgery`,
+  i.e. the postcure-repair machinery), plus `external.slurm`,
+  `external.smiles_input`, `geometry.lattice`, `utils.profiling`, and
+  `utils.vmd_viz`.  A duplicated `htpolynet.core` heading was merged.
+- `release-history.rst` appeared in no toctree, so the pre-2.0 release
+  history (1.0.7.2 back to 0.0.1, which `CHANGELOG.md` does not cover)
+  was unreachable from the docs.  Linked from `index.rst`; its 2.0.0
+  date corrected from 2026-04-15 to 2026-05-07 to match the tag.
+- Two docstrings (`BondTemplate.matches`,
+  `utils.profiling.classify_command`) opened bullet lists with no
+  preceding blank line, which docutils rejects; both rendered as
+  errors.  `conf.py` also pointed `html_static_path` at a
+  `docs/source/_static` that did not exist.  The docs now build with
+  zero warnings.
+- **The unit suite could not run at all.**  `tests/unit/test_resources.py`
+  imported `RuntimeLibrary` from `htpolynet.utils.projectfilesystem` and
+  `Software` from `htpolynet.external.software`; neither symbol nor that
+  module path survived the 2.0 refactor.  Because the imports were at
+  module scope, collection aborted for the *entire* `tests/unit` tree, so
+  `pytest tests/unit` had been failing outright rather than reporting
+  results.  Rewritten against the current `SystemLibrary` API (15 tests).
+- Two `test_chain.py` tests asserted exceptions (`'This is a bug - no
+  i-chain!'` / `'no j-chain!'`) that no longer exist anywhere in the
+  source: `cure/chain.py` deliberately replaced them with graceful chain
+  extension, since bonding to a chain-less atom is legitimate for
+  non-vinyl chemistry such as HTPB assembly.  Rewritten to assert the
+  current semantics, plus a new test for the `create_if_missing=False`
+  branch.  These had been invisible behind the collection failure above.
+- `test_write_top` wrote its scratch file into the repository.  The
+  autouse `change_test_dir` fixture chdirs each test into a directory
+  inside the source tree, and cleanup only ran on the success path, so
+  any failure or interrupt left `tests/unit/test_topology/write_test.top`
+  behind.  Now uses `tempfile.TemporaryDirectory`.
+- **Every plot call crashed on matplotlib 3.11.**  `analysis/plot.py`
+  called `matplotlib.cm.get_cmap`, deprecated in 3.7 and removed in
+  3.11, at five sites.  Since `pyproject.toml` floors matplotlib at
+  `>=3.5` with no ceiling, any reasonably fresh install -- including
+  the container image, which tracks latest conda-forge -- died with
+  `AttributeError: module 'matplotlib.cm' has no attribute
+  'get_cmap'` at the first density trace, i.e. *after* densification
+  had already burned its compute.  Replaced with a `_get_cmap()`
+  helper that prefers the `matplotlib.colormaps` registry and falls
+  back to the legacy call only below 3.5.  Caught by running example 6
+  on Picotte through the container.
+- GPU usability is now judged on whether the gmx build can actually
+  drive the detected devices, not merely on whether its GPU support is
+  non-`disabled`.  conda-forge (and hence our container) ships an
+  OpenCL Gromacs build; `gpu_ids` is populated from nvidia-smi and so
+  only ever lists NVIDIA devices, which Gromacs no longer drives via
+  OpenCL.  The previous check passed that combination through, so a
+  `gpu_id` from the config reached an `mdrun` that could not honor it.
+  New `software.gpu_unusable_reasons()` centralizes the predicate and
+  is used by `_mdrun_cmd`, `_enforce_gpu_consistency`, the startup
+  banner, and the `grompp_and_mdrun` backstop, which previously
+  duplicated a weaker hardware-only version of the test.
+- Container image was missing the `graphviz` system package, so the
+  `dot` binary `htpolynet.analysis.plot.draw_reaction_dag` shells out
+  to was absent.  `pyproject.toml` declares the `graphviz` Python
+  binding but the Dockerfile only apt-installed `openbabel` and
+  `gosu`.  Failure was silent-ish -- `cure/reaction.py` catches the
+  exception and logs `reaction_network.png render failed` -- so
+  container builds simply came out with no reaction-network figure.
+  Found while porting example 6 to Picotte via Apptainer.
+- `htpolynet plots diag` parser templates: the module-path token
+  the matcher keyed on was `HTPolyNet.runtime.my_logger` /
+  `HTPolyNet.curecontroller.do_iter` from the pre-2.0 namespace.
+  After the module reorganization into `htpolynet.core.runtime` /
+  `htpolynet.cure.curecontroller`, both lines silently stopped
+  matching and the diag parser produced an empty dataframe →
+  `IndexError` at first row access.  Templates refreshed to the
+  current module paths, and the module-name token dropped from
+  `pat_idx` so future renames don't break it again.
+- Reaction-network plot (`plots/reaction_network.png`) replaced
+  with a bipartite DAG rendered via graphviz `dot` (was a
+  spring-layout networkx render that produced tangled, label-
+  overlapping diagrams; example 5 was a 30+ node hairball).  Each
+  molecule is a rounded box; each reaction is a diamond with edges
+  from its reactants and an outgoing edge to its product; nodes are
+  colored by role (constituent / intermediate / final) and reaction
+  stage (param / build / cure / cap / repair).  Procession-
+  expanded reactions (e.g. example 5's `polymerization` with
+  `procession.count: 15`, which `parse_reaction_list` explodes
+  into 16 sequential reactions + 15 `A18_I*` intermediates) are
+  collapsed back into one node labeled `(×N)` so the diagram
+  matches what the user wrote.  New runtime dep: `graphviz` (the
+  Python wrapper; also needs the system `dot` binary, a separate
+  install).
+
 ## [2.1.0] - 2026-06-01
 
 ### Added

htpolynet-2.3.0/CITATION.cff

@@ -0,0 +1,56 @@
+cff-version: 1.2.0
+message: >-
+  If you use htpolynet in published work, please cite the SoftwareX article
+  under `preferred-citation`, along with the GAFF and Gromacs papers listed
+  in the documentation.
+title: htpolynet
+abstract: >-
+  Automated molecular-dynamics system builder for amorphous network polymers.
+  Generates atomistic models of cross-linked polymer networks, together with
+  the Gromacs topology and parameter files needed to simulate them, from only
+  the monomer structures, a description of the polymerization chemistry, and a
+  handful of system-size and composition options. Atom typing and parameter
+  generation use the General Amber Force Field.
+type: software
+authors:
+  - family-names: Abrams
+    given-names: Cameron F.
+    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
+date-released: '2026-06-01'
+keywords:
+  - molecular dynamics
+  - crosslinked polymers
+  - thermosets
+  - polymer networks
+  - Gromacs
+  - GAFF
+preferred-citation:
+  type: article
+  title: >-
+    HTPolyNet: A general system generator for all-atom molecular simulations of
+    amorphous crosslinked polymers
+  authors:
+    - family-names: Huang
+      given-names: Ming
+    - family-names: Abrams
+      given-names: Cameron F.
+      email: cfa22@drexel.edu
+      affiliation: Drexel University
+  journal: SoftwareX
+  volume: 21
+  start: 101303
+  year: 2023
+  month: 2
+  issn: 2352-7110
+  doi: 10.1016/j.softx.2022.101303

htpolynet-2.3.0/CLAUDE.md

@@ -0,0 +1,103 @@
+# Working on htpolynet
+
+## Roadmap and changelog
+
+`ROADMAP.md` holds upgrades we have identified but not done. `CHANGELOG.md`
+holds what shipped, in Keep-a-Changelog form with a live `[Unreleased]`
+section.
+
+Keep both current as a matter of course, without being asked:
+
+- When we decide *not* to do something now — a deferred fix, an idea worth
+  keeping, a limitation we chose to live with — add it to `ROADMAP.md` with
+  enough context to act on it months later. An entry that just says "make
+  Gromacs faster" is worthless; say which build, why it is slow, and what
+  the tradeoff is.
+- When a roadmap item ships, delete it from `ROADMAP.md` and describe it in
+  `CHANGELOG.md` under `[Unreleased]`.
+- Surface relevant roadmap items unprompted when we touch related code.
+
+## Running the tests
+
+```
+uv run --extra test pytest tests/unit -q
+```
+
+`dev` is an alias for the `test` extra; both work.
+
+Three test modules shell out to external binaries — `test_parameterize_react`
+needs antechamber/parmchk2/tleap/gmx, and the two `test_gromacs_*` modules
+need gmx. They skip when those are absent rather than failing, which is what
+lets CI run on a plain runner. With the tool chain present the suite takes a
+couple of minutes; without it, about four seconds.
+
+## The test suite runs inside the source tree
+
+`tests/conftest.py` has an autouse `change_test_dir` fixture that chdirs each
+test into `tests/unit/<module_name>/` if that directory exists, otherwise
+`tests/unit/`. Both are inside the repo. So a test that writes a file to the
+working directory litters the source tree, and cleanup that runs only on the
+success path leaves the file behind whenever the test fails or is
+interrupted. Write scratch files to `tmp_path` or a
+`tempfile.TemporaryDirectory` instead.
+
+## Docs must build with zero warnings
+
+```
+uv run --with-requirements docs/requirements.txt --with sphinx \
+    python -m sphinx -b html docs/source /tmp/docbuild
+```
+
+It currently builds clean; keep it that way. Two things that historically
+broke it:
+
+- `docs/source/htpolynetpackage.rst` is a hand-maintained list of
+  `automodule` directives, so it drifts silently as modules are added,
+  moved, or deleted. It once autodoc'd `htpolynet.driver` for months after
+  that module ceased to exist. When you add or move a module, add it here.
+- Adding a module to that page renders its docstrings for the first time,
+  which surfaces latent RST errors. The usual one is a bullet list with no
+  blank line before it, which docutils rejects.
+
+## Releases
+
+Use `scripts/release.sh <version>`. It rotates `[Unreleased]` into a dated
+section, bumps the version in `pyproject.toml`, commits, tags, and pushes.
+Pushing the tag is what triggers publication: `release.yaml` builds and
+publishes to PyPI, creates a GitHub Release from the changelog notes, and
+kicks a Read the Docs build. The conda-forge autotick bot then opens a
+feedstock PR.
+
+Do not hand-roll any of that. The script's preflight also checks that
+`pyproject.toml`'s runtime dependencies still match the conda-forge feedstock
+recipe — the autotick bot only bumps version and sha, so a dependency change
+we forget to mirror ships a broken conda package.
+
+Because the changelog notes become the public release body, keep
+`[Unreleased]` free of internal bookkeeping ("got bundled into commit
+abc1234") and file entries under the right heading.
+
+## The container
+
+The image is `ghcr.io/cameronabrams/htpolynet`, built by `docker.yml` from
+`docker/Dockerfile`. It rebuilds weekly on a schedule and on any tag matching
+`v*` or `d*`. A `d*` tag is the way to rebuild the image without cutting a
+release — useful when only the Dockerfile changed.
+
+Its Gromacs comes from conda-forge, which means **OpenCL, not CUDA**, and
+generic `AVX2_256` SIMD. Gromacs no longer drives NVIDIA devices through
+OpenCL, so the image cannot use a GPU: on a cluster, target CPU partitions
+and do not request `--gres=gpu` or pass `--nv`. See `ROADMAP.md`.
+
+## Two invariants worth not breaking
+
+- **Colormaps go through `analysis.plot._get_cmap()`**, never
+  `matplotlib.cm.get_cmap` directly. The latter was removed in matplotlib
+  3.11, and since `pyproject.toml` floors matplotlib without a ceiling, a
+  direct call breaks every plot on a fresh install — after densification has
+  already spent its compute.
+- **GPU usability is decided by `external.software.gpu_unusable_reasons()`**,
+  which is the single place that reconciles detected hardware against what
+  the gmx build can actually drive. Do not add ad-hoc `if gpu_ids:` checks
+  elsewhere; a weaker hardware-only duplicate of this test used to live in
+  `grompp_and_mdrun` and disagreed with it.