htpolynet 2.7.0__tar.gz → 2.8.0__tar.gz

htpolynet-2.8.0/.github/workflows/docs.yml

@@ -0,0 +1,90 @@
+name: Docs
+
+# ReadTheDocs has no webhook on this repository.  Its only trigger was the
+# "Trigger ReadTheDocs build" step in release.yaml, which fires on v* tags, so
+# the published docs tracked *releases* rather than main: a docs-only commit
+# did not appear on RTD until the next release.  This workflow closes that gap
+# for the `latest` version.  `stable` follows tags and stays release.yaml's job.
+#
+# The build job also enforces the repo invariant that the docs build with zero
+# warnings (-W).  RTD builds without -W, so a warning introduced on main would
+# otherwise publish green and be caught only by whoever next built locally.
+# Gating the trigger on that build means a broken docs commit is never pushed
+# to RTD.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      # autodoc reads docstrings and the tutorials literalinclude the example
+      # configs, so src/ is a docs input; changelog.rst includes CHANGELOG.md;
+      # RTD pip-installs the package, so pyproject.toml matters too.
+      - 'docs/**'
+      - 'src/**'
+      - 'CHANGELOG.md'
+      - '.readthedocs.yaml'
+      - 'pyproject.toml'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'src/**'
+      - 'CHANGELOG.md'
+      - '.readthedocs.yaml'
+      - 'pyproject.toml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: build (zero warnings)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      # Same invocation as CLAUDE.md documents for local use.  -W turns
+      # warnings into errors; -a rebuilds everything so a warning cannot be
+      # skipped by an up-to-date doctree.
+      - name: Build docs
+        run: >
+          uv run --with-requirements docs/requirements.txt --with sphinx
+          python -m sphinx -b html -W -a docs/source _docbuild
+
+  trigger-rtd:
+    name: trigger ReadTheDocs
+    needs: build
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger ReadTheDocs build of latest
+        env:
+          RTD_SECRET: ${{ secrets.RTD_SECRET }}
+        run: |
+          set -euo pipefail
+          if [ -z "${RTD_SECRET:-}" ]; then
+            echo "::error::RTD_SECRET is not set; cannot trigger a ReadTheDocs build."
+            exit 1
+          fi
+          # curl exits 0 on a 4xx unless told otherwise, so check the status
+          # explicitly.  A trigger that fails silently is worse than none: the
+          # job goes green and the docs quietly stop updating.
+          code=$(curl -sS --max-time 60 -o rtd-response.json -w '%{http_code}' \
+            -X POST \
+            -H "Authorization: Token ${RTD_SECRET}" \
+            https://readthedocs.org/api/v3/projects/htpolynet/versions/latest/builds/)
+          echo "ReadTheDocs returned HTTP ${code}"
+          cat rtd-response.json || true
+          echo
+          case "${code}" in
+            2*) echo "Build of 'latest' queued." ;;
+            401|403) echo "::error::RTD rejected the token (HTTP ${code}); RTD_SECRET is missing, wrong or expired."; exit 1 ;;
+            404) echo "::error::RTD has no project 'htpolynet' or no version 'latest' (HTTP 404)."; exit 1 ;;
+            *) echo "::error::RTD returned HTTP ${code}."; exit 1 ;;
+          esac

{htpolynet-2.7.0 → htpolynet-2.8.0}/.github/workflows/release.yaml

@@ -79,13 +79,37 @@ jobs:
           path: dist/
 
       - name: Trigger ReadTheDocs build
+        env:
+          RTD_SECRET: ${{ secrets.RTD_SECRET }}
+          RTD_VERSION: ${{ github.ref_name }}
         run: |
-          curl -X POST \
-            -H "Authorization: Token ${{ secrets.RTD_SECRET }}" \
-            https://readthedocs.org/api/v3/projects/htpolynet/versions/latest/builds/
-          curl -X POST \
-            -H "Authorization: Token ${{ secrets.RTD_SECRET }}" \
-            https://readthedocs.org/api/v3/projects/htpolynet/versions/${{ github.ref_name }}/builds/
+          set -euo pipefail
+          if [ -z "${RTD_SECRET:-}" ]; then
+            echo "::error::RTD_SECRET is not set; cannot trigger a ReadTheDocs build."
+            exit 1
+          fi
+          # curl exits 0 on a 4xx unless told otherwise.  These calls used to
+          # go unchecked, so an expired token would print a 401 body and the
+          # step would still pass -- the docs would just stop updating.
+          trigger() {
+            local version="$1"
+            local code
+            code=$(curl -sS --max-time 60 -o rtd-response.json -w '%{http_code}' \
+              -X POST \
+              -H "Authorization: Token ${RTD_SECRET}" \
+              "https://readthedocs.org/api/v3/projects/htpolynet/versions/${version}/builds/")
+            echo "ReadTheDocs (${version}) returned HTTP ${code}"
+            cat rtd-response.json || true
+            echo
+            case "${code}" in
+              2*) return 0 ;;
+              *)  echo "::error::RTD returned HTTP ${code} for version '${version}'."; return 1 ;;
+            esac
+          }
+          trigger latest
+          # The tag's own version may not exist yet if RTD has not synced it;
+          # that is not a release failure, so report it without failing the job.
+          trigger "${RTD_VERSION}" || echo "::warning::Could not trigger the '${RTD_VERSION}' version build; trigger it from the RTD dashboard if that version is expected."
 
   publish:
     needs: release

{htpolynet-2.7.0 → htpolynet-2.8.0}/.gitignore

@@ -145,3 +145,6 @@ dmypy.json
 .pyre/
 .vscode/settings.json
 
+
+# sphinx output from the docs CI job (and local runs that mirror it)
+_docbuild/

{htpolynet-2.7.0 → htpolynet-2.8.0}/CHANGELOG.md

@@ -7,6 +7,127 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.8.0] - 2026-09-12
+
+### Added
+
+- **Configuration files are now validated.**  `htpolynet run` checks every
+  configuration against a schema before doing anything else, and fills in
+  every documented default from that same schema.  Previously a configuration
+  was read by picking out the keys htpolynet recognized and silently discarding
+  the rest, so a misspelled key did nothing and said nothing: a
+  `desired_converson: 0.9` typo produced a default-value build -- a half-cure --
+  with no message.  Errors now name the offending location, for example
+  `Attribute 'smilse' invalid ... under 'constituents[STY]'` or
+  `Attribute 'stage' of 'reactions[1]' must be one of build, param, cure, cap,
+  repair`.  Validation covers every section, including molecule records,
+  reactions and postcure repair specs; only `gromacs.mdrun_options` is left
+  open on purpose.  This adds a runtime dependency on
+  [ycleptic](https://pypi.org/project/ycleptic/) 2.4.1 or later.
+
+- **Densification can gate on measured density convergence instead of a fixed
+  step count.**  An NPT record in `densification.equilibration` may carry a
+  `converge` block; the stage then repeats until the density settles or a
+  ceiling is hit.  It is off unless configured, so existing configurations
+  reproduce exactly.  The criterion is an autocorrelation-corrected standard
+  error, `sigma/sqrt(N/tau_int)` -- an NPT cell density is correlated over
+  hundreds of steps, so successive frames are not independent samples and a
+  naive standard error is optimistic by roughly 1.5x, which would stop the
+  gate early.  It also makes the tolerance size-aware for free.  A small
+  standard error alone is not accepted as convergence, because a trace that is
+  still climbing looks tight in every short window; the window's two halves
+  are compared as well.  **Reaching the ceiling is reported as a failure**,
+  with a warning saying the number is an unsettled box rather than the
+  system's density.
+
+  Densification is the one place this belongs: the 200 to ~1100 kg/m^3
+  compaction happens once and involves a large volume change.  Gating the CURE
+  relaxation loop was measured and rejected -- past the gel point the
+  unreacted species are bonded into the network and topologically constrained,
+  the effective diffusion exponent falls to about 0.14, and restoring the
+  mobility a gate would wait for takes of order 10^4 times the relaxation
+  time.  Note also that the gate certifies convergence of the Berendsen
+  barostat `npt.mdp` currently uses, which does not sample a correct NPT
+  ensemble; treat it as a reproducibility criterion, not a physical one.
+
+### Changed
+
+- **A configuration that 2.7.0 accepted may now be rejected.**  This is the
+  point of the validation above, but it is a change in behavior: a key
+  htpolynet does not know, a value of the wrong type, a value outside its
+  allowed choices, or a missing required field now stops the run with a
+  message instead of being ignored.  Every shipped example validates.  If an
+  existing configuration of yours is rejected, the message says where; the fix
+  is almost always a misspelled or obsolete key that was already having no
+  effect.
+
+- **Every shipped example now gates its densification on density
+  convergence**, using the `converge` block described under Added, so their
+  densification stages run until the box settles rather than for a fixed
+  duration.
+
+- **The conda-forge package for this release will follow later.**  ycleptic,
+  the new dependency, is not yet available on conda-forge, so the conda-forge
+  build of this version cannot be published until it is.  In the meantime the
+  release is available from PyPI (`pip install htpolynet`) and in the container
+  image (`ghcr.io/cameronabrams/htpolynet`); conda-forge users will stay on
+  2.7.0 until then.
+
+- **The single moleculetype htpolynet writes is now named `whole_system`, not
+  `None`.**  An entire build is written as one moleculetype on purpose -- a
+  cured network is one covalently connected molecule -- but the default name
+  was the literal string `None`, which reads like an unset field or a bug.  It
+  sits on exactly the line users inspect after GROMACS warns about
+  "inconsistent shifts", so it was sending them looking for a topology error
+  that is not there.  Purely cosmetic: GROMACS accepts either, and existing
+  topologies that say `None` still read back unchanged.
+
+### Fixed
+
+- **A config that omitted `CURE.relax.increment` crashed at the first
+  relax.**  The default was `0.0`, and `_distance_attenuation` derives its
+  stage count as `int(maxL/increment)` with no guard, so the build died with
+  `ZeroDivisionError` rather than any message about the config.  The
+  documented default -- 0.08 -- is now the actual one.  Dragging's `increment`
+  stays 0.0, which is a sentinel rather than the same bug: its own 0.0 `limit`
+  disables dragging before anything divides.  Every shipped example sets
+  `relax.increment` explicitly, which is why this went unnoticed.
+
+### Documentation
+
+- **New page: analyzing trajectories of periodic networks.**  Explains why
+  `gmx trjconv -pbc whole` reports "There were N inconsistent shifts" on a
+  cured network (the bond graph wraps through the periodic boundaries, so no
+  consistent unwrapped image exists), and that this is expected rather than a
+  topology error -- on example 3 the count is zero until the network
+  percolates, then 2 at 69% conversion and 140 at 95%.  It gives tested recipes
+  for visualization, MSD and free volume.  The MSD one carries a real
+  warning: `gmx msd`'s default `-rmpbc` tries to make the network whole every
+  frame and silently inflates the MSD, by about 2.4x at 100 ps on example 3,
+  while still exiting normally; use `-pbc nojump` and then `-normpbc`.  Prompted
+  by a user report.
+
+- The `htpolynet analyze` free-volume docs now say that the per-molecule lines
+  in `gmx freevolume`'s output describe the whole box as one molecule, and two
+  instances of `poststim` now read `postsim`.
+
+- **The docs landing page carries the standard badge row, and the release
+  history is gone from the table of contents.**  `release-history.rst`
+  duplicated what this file already records from 1.0.8 forward, so it is
+  deleted and `changelog` moves to the *end* of the contents tree rather than
+  sitting second.  The seven pre-1.0.8 entries it held -- 1.0.7.2 back to
+  0.0.1, which this file did not cover -- were migrated here first, so nothing
+  is lost by the deletion.  The landing page now shows the same eight badges
+  as the README: tests, PyPI, conda-forge, Python versions, license, docs,
+  downloads and DOI.
+
+- **Two more `CURE`/`densification` defaults in the config tables were
+  wrong.**  `densification.initial_density` is 200.0 kg/m^3, not the 300.0 the
+  table gave; and the prose under `min_allowable_bondcycle_length` still said
+  "setting it to zero (the default)" after the table had been corrected to -1.
+  Found while transcribing the defaults into a machine-readable schema, which
+  is the point of doing so.
+
 ## [2.7.0] - 2026-09-08
 
 ### Changed
@@ -1018,3 +1139,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Uses `chordless_cycles` to find rings; `ringidx` is no longer a unique atom attribute; improved ring-pierce detection.
+
+## [1.0.7.2] - untagged
+
+### Changed
+
+- Moved the Library package to the `resources` subpackage of `htpolynet`.
+
+## [1.0.6] - 2023-06-21
+
+### Added
+
+- `gmx`-style `analyze` subcommand.
+
+## [1.0.5] - 2022-09-29
+
+### Added
+
+- Post-build MD simulations and plotting functionality.
+
+## [1.0.2] - 2022-09-16
+
+### Changed
+
+- Enhanced molecule-network graph drawing in the `plot` subcommand.
+
+## [1.0.1] - 2022-09-07
+
+### Fixed
+
+- Atom index assignment for systems with more than 100,000 atoms.
+
+## [1.0.0] - 2022-09-03
+
+- First release.
+
+## [0.0.1] - 2022-08-29
+
+- Initial beta version.

{htpolynet-2.7.0 → htpolynet-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.7.0
+Version: 2.8.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/
@@ -26,6 +26,7 @@ Requires-Dist: rdkit>=2024.3
 Requires-Dist: requests>=2.28
 Requires-Dist: scipy>=1.10
 Requires-Dist: setuptools
+Requires-Dist: ycleptic>=2.4.1
 Provides-Extra: dev
 Requires-Dist: pytest; extra == 'dev'
 Provides-Extra: test

{htpolynet-2.7.0 → htpolynet-2.8.0}/ROADMAP.md

@@ -110,6 +110,24 @@ Coverage as of the last measurement: **38.8%** overall.
 
 ## Release and distribution
 
+- **The conda recipe drops `matplotlib`'s version floor.** `pyproject.toml`
+  requires `matplotlib>=3.5`; the feedstock recipe lists a bare
+  `matplotlib-base` with no lower bound, so conda can solve an environment
+  pip would refuse. Found by grayskull's dependency analysis on feedstock
+  PR #21, not by us -- `check-conda-sync.py` compared names with the version
+  specifiers stripped and so could not see a floor at all (fixed 2026-09-09;
+  it now compares floors, and reports this one). Practical risk is low
+  because `analysis/plot.py`'s `_get_cmap` carries a pre-3.5 fallback, but
+  the declaration should match. **Fold it into the hand-written feedstock PR
+  that has to add `ycleptic >=2.4.1` anyway** rather than opening a separate
+  one -- same file, two lines.
+
+  Three other items in that same grayskull report are noise and should not be
+  "fixed": `python {{ python_min }}` vs `python 3.10` is a Jinja rendering
+  artifact, `rdkit >=2024.03` vs `>=2024.3` are the same version to both
+  conda and pip, and `ambertools`/`graphviz` are deliberate conda-only
+  additions with no PyPI equivalent.
+
 - **The release preflight cannot tell whether the *previous* release
   actually shipped to conda-forge.** `scripts/check-conda-sync.py` compares
   `pyproject.toml`'s runtime deps against the feedstock recipe, which
@@ -575,28 +593,6 @@ Coverage as of the last measurement: **38.8%** overall.
   The densification entry below is the same shape of problem -- a number
   computed once and trusted thereafter.
 
-- **If anything gates on density convergence, it should be densification,
-  not cure.** The initial 200 -> ~1100 kg/m3 compaction is one-shot,
-  involves a large volume change, and currently runs on fixed `nsteps`
-  (`runtime_defaults['densification']['equilibration']`,
-  `core/runtime.py:78-86`). That is the direct analogue of pestifer's use of
-  `density_equilibrate` -- a terminal, run-until-converged replacement for a
-  hand-written NPT ladder -- and it is cheap, because it happens once per
-  build rather than ~10 times.
-
-  What to port from `pestifer/util/density_convergence.py` is only the
-  criterion: an **autocorrelation-corrected SEM**, `sigma/sqrt(N/tau_int)`,
-  because NPT cell density is autocorrelated over hundreds of steps and a
-  naive block-means SEM is optimistic by ~1.5x. That also makes the test
-  size-aware for free, since `sigma/mean ~ 1/sqrt(N_atoms)` while tau is
-  roughly size-independent. Port the explicit **ceiling outcome** too, so a
-  build that never settled says so instead of silently reporting a density.
-  Do **not** port the chunking (`next_chunk_steps`, `is_patch_grid_crash`):
-  that exists because NAMD fixes its patch/PME grid at the start of each
-  `run`, and GROMACS rescales the box within one `mdrun` without that
-  failure mode. The chunking is most of pestifer's complexity and none of
-  its value here.
-
 - **Decided against: gating and extending `CURE.relax` on density
   convergence.** Raised by Cameron 2026-09-05 from the observation that
   pestifer has a gate system htpolynet does not; recommended by the study
@@ -637,12 +633,27 @@ Coverage as of the last measurement: **38.8%** overall.
   iteration and report "may not have settled", correctly, with nothing to be
   done about it. It detects a condition it cannot cure.
 
-  **The limit on that argument:** arrest is inferred partly from gelation
-  physics, not purely measured. The study's displacement trace is still
-  falling at the last cure iteration, 4.63 -> 4.08 -> 3.72 A -- consistent
-  with approaching arrest, but not a demonstrated plateau. Measuring the
-  plateau directly would settle it either way, and is a smaller experiment
-  than powering R16 up.
+  **That limit is now closed, and the conclusion is stronger than it was.**
+  The argument used to lean partly on gelation physics rather than
+  measurement. 32 cure-only builds at the production window (study session,
+  2026-09-08) measure the effective diffusion exponent directly:
+  displacement ~ t^alpha, with alpha **0.32** at the start of cure -- already
+  sub-Fickian, which is 0.50 -- falling to **0.14** at the end. At alpha 0.14,
+  restoring the displacement a gate would need takes **3.6e4 times** the
+  relaxation time. That is not expensive, it is impossible, and it does not
+  depend on the earlier n = 4 result at all.
+
+  **And the shipped window never satisfies Varshney's criterion, not even at
+  the start.** Mean crossing fraction is **0.61 at iteration 1** and **0.036
+  at the last** -- so the window is outside the criterion it was sized against
+  for the whole cure, not merely late in it. This is the calibration for the
+  mobility report that shipped in v2.7.0: its 25 % warning threshold sits
+  between those two numbers, so a default build stays quiet early and warns
+  through the second half. Whether 25 % is the right line is not yet
+  established -- nothing measures what crossing fraction a *trustworthy* build
+  needs, only what the current one delivers -- so the threshold is a placeholder
+  chosen to be quiet at iteration 1, and should be revisited against a build
+  whose bonds are known to be well sampled.
 
   **And a structural mismatch.** Pestifer uses `density_equilibrate` as a
   terminal, one-shot replacement for a hand-written NPT ladder at the end of
@@ -735,6 +746,165 @@ Coverage as of the last measurement: **38.8%** overall.
   session's too, and it is the one of the three that has already been
   published in our documentation. Verify it first if any of them.
 
+## Configuration
+
+- **Move config handling onto ycleptic.** Approved by Cameron 2026-09-08.
+  `core/configuration.py` (85 lines) reads YAML/JSON and `.get()`s eleven
+  known top-level sections into attributes with **no validation at all**: an
+  unrecognized section or a misspelled key is silently discarded. Defaults
+  live in three separate Python dicts applied by three hand-rolled mechanisms
+  at three different depths -- `Runtime.runtime_defaults` (shallow, one level,
+  `core/runtime.py:177`), `CureController.curedict_defaults` (two levels,
+  `cure/curecontroller.py:299-304`), and `Runtime.default_edict` (ad hoc). And
+  937 lines of hand-maintained RST document those defaults, which is why six
+  of them had drifted from the code by the time anyone checked.
+
+  `src/htpolynet/schema/base.yaml` now holds the schema for the sections
+  ycleptic 2.3.0 can express. It is **inert**: nothing reads it, and
+  `pyproject.toml` does not declare a ycleptic dependency. All seven shipped
+  example configs validate against it, and a `desired_converson` typo that
+  htpolynet accepts silently today is rejected with the list of valid keys.
+
+  Staging, agreed with the ycleptic session:
+
+  1. **ycleptic to conda-forge** -- gates shipping and nothing else, and is
+     now the ONLY thing gating it.
+     `api.anaconda.org/package/conda-forge/ycleptic` was 404 while htpolynet
+     is 200, and a conda package's run-deps must exist in the channel, so
+     declaring the dependency would make htpolynet's feedstock unbuildable and
+     trip `scripts/release.sh`'s `check-conda-sync.py --strict` preflight.
+     Submitted 2026-09-08 with Cameron's direct approval as
+     conda-forge/staged-recipes#34763, "Adding ycleptic"; still open, not
+     merged, and `api.anaconda.org/package/conda-forge/ycleptic` is still 404.
+
+     **That PR pins 2.3.0, and 2.4.0 is now out on PyPI.** As written, merging
+     it creates a feedstock one version behind, and 2.4.0 then arrives only
+     through an autotick-bot PR -- the exact cycle whose stalling is the
+     central OBSERVED failure in Cameron's conda-forge skill. Updating the
+     staged recipe to 2.4.0 before it merges would skip that cycle entirely.
+     It is ycleptic's PR, not ours, and this is recorded as an observation
+     rather than an action.
+  2. **Three ycleptic grammar additions**: `value_attributes:` + `key_text:`
+     for free-key mappings, `value_type:` for scalar-valued ones, and
+     `list_defaults: replace|append` per attribute. **Released as ycleptic
+     2.4.0 on PyPI**, and base.yaml uses all three.
+  3. Port the flat sections and generate their reference docs -- done in
+     base.yaml, awaiting 1 to go live.
+
+     **The first release carrying ycleptic (2.8.0) was cut ahead of
+     conda-forge, deliberately.** An earlier version of this entry said a bot
+     PR without `ycleptic` in the recipe would be green and would ship a conda
+     package that fails at import, and so forbade `--skip-conda-check`. That
+     premise was wrong, and checked 2026-09-12: the feedstock's test runs
+     `htpolynet --help`, and importing `htpolynet.cli` loads ycleptic. So the
+     bot's PR for a ycleptic-carrying release **fails its own test**, sits red,
+     and cannot auto-merge. No broken conda package ships; conda-forge users
+     simply stay on the last good version.
+
+     What that leaves to do once ycleptic is on the channel:
+
+     a. Edit the recipe on the autotick bot's open PR for the current version
+        (push to the bot's fork, not to `origin` -- see the conda-forge skill)
+        adding `ycleptic >=2.4.1` to `run:`, and `>=3.5` to the bare
+        `matplotlib-base`. Its test then passes and automerge takes it.
+     b. If the bot has not opened one, open that recipe PR by hand.
+
+     Two cautions that still stand. The protection is the recipe's
+     `htpolynet --help` test; if that test is ever removed, this reasoning
+     stops holding and `--skip-conda-check` becomes dangerous again. And a red
+     bot PR must not be merged by hand -- red is the thing keeping the broken
+     package off the channel.
+  4. Port `constituents` and `reactions`. **`constituents` is done**: it is a
+     `value_attributes` free-key mapping, so a typo inside a molecule record
+     is now rejected naming the molecule (`Attribute 'smilse' invalid ...
+     under 'constituents[STY]'`), `count` defaults per value, a required
+     `conformers.count` is enforced, and `conformers.generator.name` is
+     constrained to obabel/gromacs. Every list with a non-empty default
+     carries `list_defaults: replace`, verified to use a user's ladder
+     verbatim rather than appending it to the default one.
+
+     **`reactions` and `postcure_repair` are now ported too.** ycleptic 2.4.0
+     added `value_attributes` on a *list*, which describes multi-key records
+     and closed the `lwalk` gap, plus `value_type:` for scalar-valued free-key
+     mappings. Every config section is now validated except
+     `gromacs.mdrun_options`, which is deliberately open. Errors name the
+     offending item -- `under 'reactions[2]'`, `of 'postcure_repair[0]'`.
+     Today an unknown reaction key is discarded by `Reaction.__init__` with a
+     debug-level message, so this replaces a silent failure with a loud one.
+
+     Superseded, kept for the record -- these were the two blockers:
+
+     - ycleptic describes list items with the tagged-task idiom -- `lwalk`
+       takes `itemname = list(item.keys())[0]` -- and htpolynet's reaction
+       records are multi-key. With no schema node for the item there is
+       nowhere to hang `value_attributes` for `reactions[].atoms`, which
+       would otherwise qualify. The ycleptic session has deliberately not
+       changed `lwalk`; it is a real feature request.
+     - `value_attributes` requires every value to be a **mapping**, which
+       ruled out scalar-valued free-key mappings. **Closed**: `value_type:`
+       was bundled into ycleptic 2.4.0, and `constituents[].reactive_atoms`
+       and `constituents[].rename_atoms` now declare `value_type: str` and
+       are validated. `reactions[].reactants` (`{1: BPA, 2: HIE}`) is the
+       same shape and would work too, but it lives inside a `reactions` list
+       item, so the `lwalk` limitation above blocks it regardless.
+
+- **`required: true` on a list attribute is silently ineffective in ycleptic
+  2.4.0.** An absent required list is filled with `[]` and no error is raised
+  (`walkers.py:389-397`); scalars raise, and dicts raise via their required
+  children. Verified with a minimal spec, and it is the exact class of
+  do-nothing declaration `speccheck` exists to catch, which does not catch
+  this one. In base.yaml it means `reactions[].bonds`, `bonds[].atoms` and the
+  repair spec's `ring_carbon_atoms`, `ring_nitrogen_atoms` and
+  `reactive_oxygen_atoms` are declared required and are not enforced: omitting
+  one validates, then fails deeper in htpolynet. The declarations are kept
+  because they state the intent correctly and will start working when ycleptic
+  fixes it. Reported to the ycleptic session; not worked around here.
+
+  **The version floor is a trap; read this before pinning anything.** The
+  staged-recipes submission is necessarily at ycleptic **2.3.0**, because
+  staged-recipes needs a tarball that already exists. Step 3's base.yaml is
+  written against 2.3.0 and works there. But the free-key node step 4 needs
+  will land in **2.4.0**, and 2.4.0 reaches conda-forge only via an
+  autotick-bot PR *after* that release -- and the central OBSERVED failure in
+  Cameron's conda-forge skill is exactly those bot PRs sitting red for months
+  while conda-forge serves the stale version. So: pin `ycleptic>=2.3.0` when
+  step 3 goes live, and **do not raise the floor to 2.4.0 until the anaconda
+  API confirms 2.4.0 is actually on the channel** -- not when it is released,
+  not when the bot PR opens. Raising it early recreates precisely the
+  unbuildable-feedstock problem step 1 exists to avoid. The ycleptic session
+  will report when the API says so.
+
+  Two hazards are recorded in the base.yaml header rather than here, because
+  that is where someone editing it will look: ycleptic's `dwalk` rejects any
+  key not declared, so user-keyed sections must currently be bare `dict` and
+  are unvalidated; and a bare list's default *concatenates* rather than
+  replaces, so a base default of `[min, nvt, npt]` plus a user's `[nvt]`
+  yields `['min','nvt','npt','nvt']` silently. Every list in base.yaml
+  therefore declares no default, which gives correct replace semantics, with
+  the real default left in Python and marked.
+
+- **Documented `CURE.drag`/`CURE.relax` defaults do not match the code, and
+  several keys are undocumented.** The tables give `drag.increment` 0.08 and
+  `drag.limit` 0.3 where `curedict_defaults` has 0.0 for both -- sentinels
+  that disable dragging via the `:316` guard, so the documented defaults would
+  turn on a stage ladder the code turns off. (`relax.increment` was the same
+  kind of mismatch and is now fixed in the code's favor: it defaults to the
+  documented 0.08. `relax.nstages: 6` is still declared and never read.)
+  Undocumented entirely:
+  `drag.trigger_distance`, `drag.kb`, `drag.nstages`, `drag.cutoff_pad`,
+  `relax.nstages`, `relax.cutoff_pad`, the whole `CURE.output` block,
+  `densification.scale`, `densification.aspect_ratio` and
+  `densification.initial_boxsize`. Generating the reference from base.yaml is
+  what makes this class of error impossible; until then the tables need a pass.
+
+- **`resolve_type_discrepancies` is accepted in two places and documented in
+  one.** `core/runtime.py:326` falls back from
+  `cfg.gaff.get('resolve_type_discrepancies',[])` to
+  `cfg.resolve_type_discrepancies`, so both a top-level key and a
+  `GAFF`-scoped one work, with GAFF winning. The
+  docs describe only the GAFF-scoped form. base.yaml declares both, marking the
+  top-level spelling deprecated; pick one before the schema goes live.
+
 ## Simulation defaults
 
 - **The halogen constraint failure is fixed but not explained.** v2.7.0
@@ -951,6 +1121,44 @@ Coverage as of the last measurement: **38.8%** overall.
   `_get_cmap()` once `matplotlib>=3.6` is a safe floor; the
   `matplotlib.colormaps` registry is then always present.
 
+- **The 18 postsim TODO placeholders are the last unfinished tutorial work.**
+  Every one of the seven `postsim.rst` pages carries `**TODO:** insert the
+  rho_v_ns.png plots`, `**TODO:** insert tg.png` and `**TODO:** report the
+  fractional free volume`, and `6-cyanate-ester/monomers.rst` still wants a
+  `pics/TAZ.png`. These are unfinished rather than stale: nothing in them is
+  wrong, the numbers and figures were simply never produced. Filling them
+  needs real compute -- `htpolynet postsim` runs, which the 2026-09-08 example
+  sweep did not do, since it ran `htpolynet run` only.
+
+- **Tutorial timings are hardware-dependent and nothing said so until now.**
+  The stage tables in examples 4, 5 and 6 were rewritten on 2026-09-09 from
+  measured 24-core runs and now say "on 24 cores". Before that, example 5's
+  table quoted ~12 hours from a 16-core run of an earlier configuration of
+  that example, against 3h45m measured now -- and its iteration count was 15
+  against 9 measured, which is a real behavior change rather than hardware.
+  Whatever replaces this should either state the machine or stop quoting
+  absolute times.
+
+- **`htpolynet analyze` has no MSD stage, and one would have to be written
+  carefully.** A user asked for an MSD workflow on a DGEBA/PACM network
+  (2026-09-12), and the only thing to point them at was `gmx msd` directly.
+  The trap for whoever adds one: `gmx msd` defaults to `-rmpbc`, which tries to
+  make each molecule whole every frame, and for a periodic network that is
+  impossible. It does not fail -- it prints "inconsistent shifts" and silently
+  inflates the MSD, by about 2.4x at 100 ps on example 3 (0.379 against 0.154
+  nm^2). The correct recipe is `trjconv -pbc nojump` and then
+  `gmx msd -normpbc`. Avoid `-nopbc`, which segfaulted `gmx msd` in GROMACS
+  2025.4. `-mol` is meaningless, since the whole network is one molecule. The
+  documented recipe is on the "Analyzing Trajectories of Periodic Networks"
+  page.
+
+  Relatedly, the existing `freevolume` stage passes no `-normpbc`, so it also
+  prints the warnings. For free volume they are harmless -- 0.211 +/- 0.007
+  with default settings against 0.210 +/- 0.006 with `-normpbc` -- but they are
+  noise a user will reasonably worry about. Adding `-normpbc` to its defaults
+  would silence them; it is not done yet because `Analyze`'s option dict
+  expects key/value pairs, and a bare boolean flag needs checking there.
+
 ## Example depot
 
 - **Example 6's postcure anneal peaks too close to *T*:sub:`g` to relax the

{htpolynet-2.7.0 → htpolynet-2.8.0}/docs/source/example-tutorials/0-liquid-styrene/run.rst

@@ -18,7 +18,10 @@ This kicks off the full workflow:
 2. **Initial pack.**  1000 copies of styrene are placed into a box sized
    for ``initial_density: 300 kg/m³``.
 3. **Densification.**  The cascade under ``densification`` runs:
-   minimization, 10 ps NVT, 200 ps NPT at 10 bar.
+   minimization, 10 ps NVT, then 200 ps NPT at 10 bar *repeated until the
+   density settles*.  On a 24-core run that took two extra segments, so
+   600 ps of NPT rather than 200, and densification as a whole took about
+   5.5 minutes.
 4. **Anneal cascade.**  The cascade under ``precure`` runs:
    pre-equilibration, two 300/600 K cycles, post-equilibration.
 

{htpolynet-2.7.0 → htpolynet-2.8.0}/docs/source/example-tutorials/1-polystyrene/run.rst

@@ -31,7 +31,8 @@ same as in :ref:`example 0 <liquid_styrene_run>`; the new ones are
    sized for ``initial_density: 300 kg/m³``.
 
 3. **densification.**  Minimization → 10 ps NVT @ 300 K → 200 ps NPT
-   @ 300 K, 10 bar.
+   @ 300 K, 10 bar, the NPT stage repeating until the density settles
+   (one extra segment on a 24-core run; ~4 minutes in total).
 
 4. **precure.**  Pre-equilibration, two 300/600 K annealing cycles,
    post-equilibration.

{htpolynet-2.7.0 → htpolynet-2.8.0}/docs/source/example-tutorials/2-bisgma-styrene-thermoset/run.rst

@@ -88,7 +88,7 @@ With ``desired_conversion: 0.95`` and a max of 300 bonds, the target is
 default 0.5 nm search radius; as conversion approaches the target, the
 remaining reactive pairs get sparser and ``htpolynet`` has to grow the
 radius (and sometimes drag pairs in) to find anything.  A typical run
-needs ~12–15 iterations at the default ``min_bonds_per_iteration: 10``.
+needs ~10–15 iterations at the default ``min_bonds_per_iteration: 10``.
 Excerpted from a representative log:
 
 .. code-block:: text