htpolynet 2.3.0__tar.gz → 2.4.0__tar.gz

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

@@ -0,0 +1 @@
+../../../src/htpolynet/resources/claude/SKILL.md

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

@@ -31,6 +31,8 @@ jobs:
         context: .
         file: docker/Dockerfile
         push: true
+        build-args: |
+          HTPOLYNET_COMMIT=${{ github.sha }}
         tags: |
           ghcr.io/cameronabrams/htpolynet:latest
           ghcr.io/cameronabrams/htpolynet:${{ github.sha }}

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

@@ -7,6 +7,117 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-08-25
+
+### Added
+
+- **`htpolynet setup-claude` installs the bundled Claude Code skill**, so it
+  reaches users who `pip install` or `conda install` htpolynet rather than
+  only those working inside a clone.  The skill previously lived at
+  `.claude/skills/htpolynet/`, which the tool finds only when the working
+  directory is the repository -- that is contributors, and not most users.
+  It now ships as package data and is copied to
+  `~/.claude/skills/htpolynet/SKILL.md` on request; `--skills-dir
+  ./.claude/skills` scopes it to one project instead, and `--force`
+  overwrites an existing copy after an upgrade.
+
+  Nothing happens at install time: installing the package never writes to
+  `~/.claude/`.  The repository's `.claude/skills/htpolynet/SKILL.md` is now
+  a symbolic link to the packaged file, so a clone and an install get the
+  same skill and the two cannot drift apart.
+
+  The skill itself was rewritten to stand alone.  It used to be a router --
+  its first instruction was to read
+  `docs/source/user-guide/building-a-system.rst`, a path that does not exist
+  for an installed user -- so it now carries the procedure inline and cites
+  Read the Docs once as the full reference.
+
+### Fixed
+
+- **The container image now reports the commit it was built from.**  A
+  published image had no way to say what code it contained: there is no git
+  in the image and no `.git` beside the installed package, so
+  `htpolynet info` fell back to the installed version -- which is right for
+  pip and conda and *misleading for the container*, because the weekly
+  scheduled rebuild builds from `main` HEAD and reports whatever
+  `pyproject.toml` last said.  An image built four commits past a release
+  claimed to be that release, and `:latest` is the default thing people
+  pull.  A user could pull `:latest`, trust the version string, and record
+  the wrong version in a methods section.
+
+  The build now passes the commit as a `HTPOLYNET_COMMIT` build argument,
+  the image carries it in its environment, and `htpolynet info` reports it
+  in preference to the version fallback.  A real git checkout still wins
+  over both, since it reflects the working tree including uncommitted
+  changes.  The container-usage guide explains why `:latest` moves and how
+  to pull by digest or per-commit tag when provenance has to be stateable
+  later.
+
+- The container-usage guide now distinguishes two habits that are easy to
+  conflate: **pulling once** gives a campaign a constant tool chain, while
+  **recording the digest** is what lets you state afterwards what that tool
+  chain was.  The image pins more than the htpolynet code -- Gromacs and
+  AmberTools come unpinned from conda-forge at build time, so two images
+  built days apart can carry different versions of either while running
+  identical htpolynet code.
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.3.0
+Version: 2.4.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/

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

@@ -27,6 +27,34 @@ Rough ordering within each section is by value, not by effort.
   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 image's Gromacs and AmberTools are unpinned, so two images with
+  identical htpolynet code can compute different numbers.** `docker/Dockerfile`
+  installs `ambertools`, `gromacs`, `parmed` and `rdkit` from conda-forge with
+  no version constraints, and the weekly rebuild exists precisely to pick up
+  whatever is newest. So the commit stamp now tells you which htpolynet
+  produced a build, and still does not tell you which force-field tool chain
+  did. Observed live: the image built 2026-08-25 carries AmberTools 26.0 and
+  Gromacs 2026.3, while panacea's native environment is on Gromacs
+  2025.4 -- a different major version against the same htpolynet.
+
+  Unpinning is deliberate and mostly right: pinning would freeze the image on
+  old Gromacs and defeat the point of a weekly rebuild. The gap is that
+  nothing *records* what a given image resolved to, so the versions are
+  discoverable only by running `htpolynet info` inside it and writing the
+  answer down by hand. The better of two candidates is an image
+  **label** carrying a `conda list` export, written at build time: `docker
+  inspect` then answers the question without running the image, so the record
+  survives reaching someone who cannot run the container at all -- a reviewer,
+  an archive, a future reader holding only the digest. The alternative, making
+  `htpolynet info` machine-readable so a build can capture it, requires the
+  image to still be runnable, which is the weaker guarantee. This is the same
+  requirement as the build manifest below, one layer further down -- what
+  produced this build, all the way to the compilers.
+
+  Raised by the calibration study, which found the 2025.4/2026.3 split only
+  because it went looking after an unrelated prompt.
+
 - **Retire `ghcr.io/abramsgroup/htpolynet`.** Superseded by the
   `cameronabrams` package; still public and still serving a June image to
   anyone with an old link.
@@ -122,6 +150,29 @@ Coverage as of the last measurement: **38.8%** overall.
   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.
+- **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
@@ -234,6 +285,71 @@ Coverage as of the last measurement: **38.8%** overall.
 
 ## 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 regime where
+  a crosslinked network actually moves. 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.
+
+  **But raising the peak is unlikely to close the gap entirely.** Two
+  structures of the same network were held for 5 ns at a 480 K setpoint
+  that thermostatted to 477.1 K -- about 11 K *below* the measured
+  *T*:sub:`g`, and far longer than the 80 ps the example spends near it.
+  Relaxation there is fast at first and then stops: about 87% of an
+  initial 34.8 kg/m³ density gap -- the gap measured over the first 200 ps
+  -- closes within 3 ns, and the remaining 4.25 kg/m³ persists at
+  7.2 sigma, with a last-half trend of +0.030 kg/m³/ns, i.e. not decaying.
+  (State the baseline and the window whenever this number is quoted: the
+  same data give 83.5-87.8% across the defensible choices of each, so a
+  bare percentage is not a fact.)  So heat and time buy most of the
+  relaxation quickly and then buy nothing, and a residual difference
+  survives that a longer anneal at this scale does not appear able to
+  remove.  Whatever replaces the current anneal should
+  therefore be argued as a large improvement, not as a fix; an entry
+  promising equilibration would oversell what was measured.
+
+  Note what that hold also says about *T*:sub:`g` itself: **relaxation does
+  not switch off at the glass transition**, it slows continuously through
+  it.  A transition 20-34 K wide by experiment means 11 K below
+  *T*:sub:`g` is inside the transition, not deep in the glass, so fast
+  early relaxation there is expected rather than anomalous.  This does not
+  soften the argument above -- the 197x figure is unchanged and a peak well
+  clear of the transition is still the lever -- but it does mean *T*:sub:`g`
+  is a soft kinetic boundary for this material, which any protocol
+  expressed relative to it has to accommodate.
+
+  **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

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

@@ -51,6 +51,14 @@ COPY . /htpolynet
 WORKDIR /htpolynet
 RUN pip install --no-cache-dir .
 
+# The commit this image was built from.  There is no git in the image and no
+# .git beside the installed package, so without this an image cannot say what
+# code it contains -- and its version string is actively misleading between
+# releases, since the weekly rebuild builds from main HEAD.  Declared after the
+# expensive layers so that a changed sha does not invalidate the mamba cache.
+ARG HTPOLYNET_COMMIT=unknown
+ENV HTPOLYNET_COMMIT=${HTPOLYNET_COMMIT}
+
 # Pre-create HOME for the unprivileged user the entrypoint drops to.  When
 # compose.yml mounts a named volume here, Docker initializes the fresh volume
 # from this directory and preserves the 0777 mode.

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

@@ -87,6 +87,22 @@ Run it:
 Density during annealing and equilibration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. warning::
+
+   The density this stage settles at is **not** an equilibrated density.
+   This example's postcure anneal peaks at 500 K, and the measured
+   *T*:sub:`g` for this system is about 488 K -- so the anneal spends its
+   80 ps of peak time only ~12 K above the glass transition, where a
+   crosslinked network barely moves.  On four independent builds the
+   postcure plateau came out 2.31% below the same systems' density after a
+   melt and slow re-cool, and 2.6-2.8% below experiment, where the
+   re-cooled value agrees with experiment to under 1%.
+
+   The 500 K peak is fine for this tutorial's purpose, which is to show the
+   workflow.  It is not a basis for quoting a density.  Take densities from
+   the cooling ladder below instead.
+
+
 .. admonition:: Placeholder
    :class: caution
 

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

@@ -61,7 +61,7 @@ In this section we show all subdirectives for each of the five main directives i
 
     These three directives determine the parameters ``antechamber`` produces, so each parameterization records them in a ``.parm`` file checked into the library alongside its ``gro``, ``top``, ``itp``, ``tpx`` and ``grx`` files.  Because the library is keyed on molecule name, that record is the only thing distinguishing a molecule parameterized one way from the same molecule parameterized another.  A run whose directives disagree with the record re-parameterizes rather than reusing the cached files, and says which directives differed.
 
-    A parameterization checked in before htpolynet 2.3 has no such record.  It is still used, but the run warns that it cannot verify what produced it; rebuild it with ``--force-parameterization`` if you need to be sure.  Note that re-parameterizing after a mismatch does **not** replace the library entry unless you also pass ``--force-checkin``, so a library holding a ``gas`` parameterization keeps it even after a ``bcc`` run.
+    A parameterization checked in before htpolynet 2.3 has no such record.  It is still used **as-is**, which means the build takes whatever charges that entry holds even if they were produced with a different ``charge_method``; the run warns, per molecule and again in a block at the end of the parameterization stage, that it could not verify what produced them.  This is deliberate -- it keeps an existing library working instead of re-parameterizing it wholesale -- but it does mean that asking for ``bcc`` against a pre-2.3 library can still yield ``gas`` numbers.  Rebuild those entries with ``--force-parameterization`` if a build's charges need to be certain.  Note that re-parameterizing after a mismatch does **not** replace the library entry unless you also pass ``--force-checkin``, so a library holding a ``gas`` parameterization keeps it even after a ``bcc`` run.
 
 * ``GAFF``
 
@@ -263,6 +263,14 @@ In this section we show all subdirectives for each of the five main directives i
 
     The ``postcure`` directive instructs ``htpolynet`` on running a series of MD simulations after cure.  Its form is identical to that of ``precure``, namely with optional ``preequilibration``, ``anneal``, and ``postequilibration`` subdirectives.
 
+    .. warning::
+
+       **The density at the end of ``postequilibration`` is not an equilibrated density, and should not be quoted as one.**  A crosslinked network only relaxes appreciably above its glass transition, and a postcure anneal whose peak sits near *T*:sub:`g` spends very little time where the network can move -- so the postcure plateau reports an under-relaxed structure no matter how long the plateau itself runs.
+
+       Measured on four independent BPA cyanate-ester builds: the postcure NPT plateau gave 1.1712 ± 0.0029 g/cm³ at 300 K, while the same systems melted and slowly re-cooled gave 1.1983 ± 0.0037 g/cm³ at 293 K -- a 2.31% difference between two extractions of the same quantity.  Against experiment (1.205 by mercury dilatometry, 1.202 by flotation, same monomer), the plateau value is 2.6-2.8% low and the re-cooled value 0.3-0.6% low.  A build reporting the plateau density would have read as a force-field failure when it was a protocol artifact.
+
+       If you need a density, extract it from a melt-and-slow-cool trajectory (an :doc:`htpolynet postsim <configs-for-postsim>` ladder does this) rather than from the postcure plateau.  The same caution applies to any property that depends on the structure having relaxed.
+
 .. _reactions:
 
 * ``reactions``

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

@@ -99,6 +99,38 @@ The ``compose.yml`` file mounts the current directory into the container as
 ``/work`` and runs the process as your host user, so all output files are
 written with your own ownership.
 
+.. admonition:: Which code is in your image?
+   :class: note
+
+   ``htpolynet info`` reports the exact commit the image was built from, which
+   is baked in at build time.  This matters because ``:latest`` moves: besides
+   moving on every release, it is rebuilt weekly from ``main`` to pick up new
+   Gromacs and AmberTools builds, so an image tagged ``:latest`` is frequently
+   built from a commit *after* the last release and its version number alone
+   will not tell you that.
+
+   For anything whose provenance you need to be able to state later -- a
+   published result, a long campaign you want to keep consistent -- pull by
+   digest or by the per-commit tag rather than ``:latest``, and record what
+   you pulled::
+
+     $ docker pull ghcr.io/cameronabrams/htpolynet@sha256:<digest>
+
+   Every build is also pushed as ``ghcr.io/cameronabrams/htpolynet:<commit-sha>``.
+
+   Note that the image pins more than the ``htpolynet`` code.  Gromacs and
+   AmberTools are installed unpinned from conda-forge at build time, so two
+   images built days apart can carry different versions of either while
+   running identical ``htpolynet`` code -- and a charge method or an
+   integrator is not something you want silently varying across a campaign.
+   Two distinct habits protect against this and are worth keeping apart:
+   **pulling once** and reusing that image gives a campaign a constant tool
+   chain, while **recording the digest** is what lets you say afterwards what
+   that tool chain was.  Doing only the first leaves you consistent but unable
+   to state what you did; doing only the second leaves every fresh pull free
+   to move under you.  ``htpolynet info`` prints the AmberTools and Gromacs
+   versions actually present, so record its output alongside the digest.
+
 Running example shell scripts
 """""""""""""""""""""""""""""
 

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

@@ -21,6 +21,7 @@ Subcommand           Description
 ``analyze``          Perform ``gmx``-style analyses of trajectories generated by post-build MD simulations
 ``gen-slurm-script`` Emit a SLURM batch script that runs ``htpolynet run`` for a given config
 ``make-viz``         Regenerate VMD visualization files (``.viz.psf`` + ``.viz.tcl``) from an existing ``top`` + ``gro`` pair
+``setup-claude``     Install htpolynet's Claude Code skill so an agent can drive htpolynet
 ==================== ========================
 
 ``htpolynet <subcommand> -h`` provides subcommand-level help. 
@@ -222,8 +223,9 @@ checked in under the same name.
 .. note::
 
    A parameterization checked in before htpolynet 2.3 carries no record.
-   Those entries are still used, so an existing cache keeps working, but
-   each one logs a warning that its provenance could not be verified, and
+   Those entries are still used **as-is**, so an existing cache keeps
+   working — but the build takes whatever charges they hold, which may not
+   be what your ``charge_method`` asks for.  Each one logs a warning, and
    the parameterization stage ends with a block listing them all.  Rebuild
    them with ``--force-parameterization`` if you need certainty about what
    a build used.
@@ -387,7 +389,9 @@ The purpose of the ``postsim`` subcommand is to control the execution of several
     -h, --help            show this help message and exit
     -proj PROJ [PROJ ...]
                           name of project directory
-    -lib LIB              local user library of molecular structures and parameterizations
+    -lib LIB              local user library of molecular structures and
+                          parameterizations (default: ./lib if it exists,
+                          otherwise none)
     -ocfg OCFG            original htpolynet config file used to generate project(s)
     -cfg CFG              config file specifying the operations to perform
     --no-banner           suppress the startup banner
@@ -410,7 +414,9 @@ The ``analyze`` subcommand provides a shortcut interfaces to selected ``gmx``-st
     -h, --help            show this help message and exit
     -proj PROJ [PROJ ...]
                           name of project directory
-    -lib LIB              local user library of molecular structures and parameterizations
+    -lib LIB              local user library of molecular structures and
+                          parameterizations (default: ./lib if it exists,
+                          otherwise none)
     -ocfg OCFG            original htpolynet config file used to generate project(s)
     -cfg CFG              config file specifying the operations to perform
     --no-banner           suppress the startup banner
@@ -506,4 +512,28 @@ The main ``.viz.tcl`` sources this file when it exists, so the macros are availa
   # composable with the rest of VMD's selection language
   mol modselect 0 top "THT and not hydrogen"
 
-The residue-level view is untouched — selections like ``resname TBO`` or ``resname IPD`` still work — the constituent macros are an *additive* layer.
+The residue-level view is untouched — selections like ``resname TBO`` or ``resname IPD`` still work — the constituent macros are an *additive* layer.
+
+``htpolynet setup-claude``
+!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+``setup-claude`` installs the skill bundled with the package, which teaches Claude Code how to drive ``htpolynet``: start from the nearest example, describe monomers in their active form, check a config before spending compute, and recognize the failure modes that are known rather than mysterious.
+
+.. code-block:: console
+
+    $ htpolynet setup-claude -h
+
+    usage: htpolynet setup-claude [-h] [--skills-dir SKILLS_DIR] [--force]
+
+    options:
+      -h, --help            show this help message and exit
+      --skills-dir SKILLS_DIR
+                            skills directory to install into (default: ~/.claude/skills);
+                            use ./.claude/skills to scope the skill to one project
+      --force               overwrite an existing installed skill
+
+By default the skill goes to ``~/.claude/skills/htpolynet/SKILL.md``, where Claude Code finds it from any working directory.  Pass ``--skills-dir ./.claude/skills`` to scope it to a single project instead.
+
+Nothing is installed automatically: installing ``htpolynet`` never writes to ``~/.claude/``.  Re-run ``setup-claude --force`` after upgrading to pick up the current version of the skill, which otherwise stays as it was when you first installed it.
+
+Working inside a clone of the repository needs none of this --- ``.claude/skills/`` there is a symbolic link to the same file, so the skill is already in scope.

{htpolynet-2.3.0 → htpolynet-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "htpolynet"
-version = "2.3.0"
+version = "2.4.0"
 authors = [
   { name="Cameron F Abrams", email="cfa22@drexel.edu" },
 ]

{htpolynet-2.3.0 → htpolynet-2.4.0}/src/htpolynet/analysis/analyze.py

@@ -248,7 +248,7 @@ def analyze(args):
     software.sw_setup()
     logger.debug(f'ogromacs {ogromacs}')
     for d in args.proj:
-        pfs.pfs_setup(root=os.getcwd(),topdirs=pfs.Dirs.analyze_topdirs,verbose=True,projdir=d,reProject=False,userlibrary=args.lib)
+        pfs.pfs_setup(root=os.getcwd(),topdirs=pfs.Dirs.analyze_topdirs,verbose=True,projdir=d,reProject=False,userlibrary=pfs.resolve_user_library(args.lib))
         pfs.go_to(pfs.Dirs.analyze)
         for stage in cfg.stagelist:
             stage.do(**ogromacs)

{htpolynet-2.3.0 → htpolynet-2.4.0}/src/htpolynet/analysis/postsim.py

@@ -436,7 +436,7 @@ def postsim(args):
     software.sw_setup()
     logger.debug(f'ogromacs {ogromacs}')
     for d in args.proj:
-        pfs.pfs_setup(root=os.getcwd(),topdirs=pfs.Dirs.postsim_topdirs,verbose=True,projdir=d,reProject=False,userlibrary=args.lib)
+        pfs.pfs_setup(root=os.getcwd(),topdirs=pfs.Dirs.postsim_topdirs,verbose=True,projdir=d,reProject=False,userlibrary=pfs.resolve_user_library(args.lib))
         pfs.go_to(pfs.Dirs.postsim)
         for stage in cfg.stagelist:
             stage.do(mdp_pfx='local',**ogromacs)

{htpolynet-2.3.0 → htpolynet-2.4.0}/src/htpolynet/cli.py

@@ -5,11 +5,15 @@ Author: Cameron F. Abrams <cfa22@drexel.edu>
 
 import logging
 import os
+import shutil
 import textwrap
 
 import argparse as ap
 import yaml
 
+from importlib.resources import files as pkg_files
+from pathlib import Path
+
 from .analysis.analyze import analyze
 from .analysis.plot import plots
 from .analysis.postsim import postsim
@@ -119,6 +123,37 @@ def fetch_example(args):
     _fetch_one(depot, fullname)
 
 
+def setup_claude(args: ap.Namespace):
+    """Handles the setup-claude subcommand.
+
+    Copies the bundled skill into the user's skills directory.  This runs only
+    when the user asks for it; installing the package never touches
+    ``~/.claude/``.
+
+    Args:
+        args (argparse.Namespace): parsed arguments
+    """
+    # Resolve through htpolynet.resources, which is a real package; the claude/
+    # subdirectory carries no __init__.py, matching every other resource
+    # subdirectory.
+    source = pkg_files('htpolynet.resources').joinpath('claude', 'SKILL.md')
+    if not source.is_file():
+        raise FileNotFoundError(f'Bundled skill not found at {source}')
+
+    skill_dir = Path(args.skills_dir).expanduser() / 'htpolynet'
+    target = skill_dir / 'SKILL.md'
+
+    if target.exists() and not args.force:
+        print(f'{target} already exists; re-run with --force to overwrite it')
+        return
+
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    with source.open('rb') as fh, open(target, 'wb') as out:
+        shutil.copyfileobj(fh, out)
+    print(f'Written: {target}')
+    print('Claude Code picks the skill up on its next session in any directory.')
+
+
 def _add_run_options(p, loglevel='debug'):
     """Adds run options (no positional config) shared by run and gen-slurm-script."""
     p.add_argument('-lib',type=str,default='lib',help='local user library of molecular structures and parameterizations')
@@ -235,7 +270,7 @@ def _add_gen_slurm_args(p):
 def _add_analysis_args(p):
     """Adds the common arguments shared by the postsim and analyze subcommands."""
     p.add_argument('-proj',type=str,default='',nargs='+',help='name of project directory')
-    p.add_argument('-lib',type=str,default='lib',help='local user library of molecular structures and parameterizations')
+    p.add_argument('-lib',type=str,default=None,help='local user library of molecular structures and parameterizations (default: ./lib if it exists, otherwise none)')
     p.add_argument('-ocfg',type=str,default='',help='original htpolynet config file used to generate project(s)')
     p.add_argument('-cfg',type=str,default='',help='config file specifying the operations to perform')
     p.add_argument('--no-banner',default=False,action='store_true',help='suppress the startup banner')
@@ -257,6 +292,7 @@ def cli():
         ('analyze',          analyze,          "perform 'gmx <command>' style analyses specified in the config file"),
         ('gen-slurm-script', gen_slurm_script, 'generate a SLURM submission script for running htpolynet on a cluster'),
         ('make-viz',         make_viz,         'regenerate VMD viz files (.viz.psf + .viz.tcl) from an existing gromacs top + gro pair'),
+        ('setup-claude',     setup_claude,     "install htpolynet's Claude Code skill so an agent can drive htpolynet"),
     ]
 
     parser = ap.ArgumentParser(description=textwrap.dedent(banner_message),formatter_class=ap.RawDescriptionHelpFormatter)
@@ -291,6 +327,10 @@ def cli():
     cp['make-viz'].add_argument('-grx', type=str, default=None, help='input htpolynet .grx (default: auto-detect <gro-stem>.grx; needed for the constituent-selection macros)')
     cp['make-viz'].add_argument('-prefix', type=str, default=None, help='output basename; the .viz.psf, .viz.tcl, and .viz.macros.tcl are written next to the input gro (default: stem of -gro)')
 
+    cp['setup-claude'].add_argument('--skills-dir', type=str, default='~/.claude/skills',
+                                    help='skills directory to install into (default: %(default)s); use ./.claude/skills to scope the skill to one project')
+    cp['setup-claude'].add_argument('--force', default=False, action='store_true', help='overwrite an existing installed skill')
+
     _add_analysis_args(cp['postsim'])
     _add_analysis_args(cp['analyze'])
 

{htpolynet-2.3.0 → htpolynet-2.4.0}/src/htpolynet/core/projectfilesystem.py

@@ -208,7 +208,9 @@ class UserLibrary:
             pathname (str): path to the user library directory, defaults to '.'
         """
         self.root = Path(os.path.abspath(pathname))
-        assert self.root.exists() and self.root.is_dir(), f'{pathname} is not a directory'
+        assert self.root.exists() and self.root.is_dir(), (
+            f'user library {pathname!r} (resolved to {self.root}) is not a directory; '
+            f'pass -lib <path> to point at an existing library, or create it')
 
     def exists(self, filename):
         """Checks if filename exists in the user library.
@@ -448,6 +450,28 @@ def pfs_setup(root='.', topdirs=['molecules', 'systems', 'plots'], projdir='next
                                userlibrary=userlibrary, mock=mock)
 
 
+def resolve_user_library(pathname, default='lib'):
+    """Returns the user-library path a subcommand should use, or None for none.
+
+    An explicitly supplied path is returned unchanged, so that a typo fails
+    loudly in UserLibrary rather than silently degrading to no library.  When
+    nothing was supplied, the conventional ``lib/`` is used only if it is
+    actually there: a subcommand that merely reads finished results has no
+    reason to require a molecule library, and demanding one turns the default
+    value of a flag the user never typed into a hard error.
+
+    Args:
+        pathname (str or None): the value of the ``-lib`` flag, or None if unset
+        default (str): the conventional library directory, defaults to 'lib'
+
+    Returns:
+        str or None: path to use as the user library, or None for no user library
+    """
+    if pathname is not None:
+        return pathname
+    return default if os.path.isdir(default) else None
+
+
 def checkout(filename, altpath=[]):
     """Copies a file to cwd; searches user library, then user cache, then system library.