htpolynet 2.6.2__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.6.2 → 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.6.2 → 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.6.2 → htpolynet-2.8.0}/CHANGELOG.md

@@ -7,6 +7,235 @@ 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
+
+- **The per-iteration equilibration now constrains hydrogen bonds only, not
+  all bonds.**  The packaged `npt.mdp` and `nvt.mdp` paired `dt = 0.002` with
+  `constraints = all-bonds` and set no `lincs_order`, so GROMACS used its
+  default LINCS accuracy (order 4).  That is marginal whenever heavy-atom
+  bonds are constrained, and for a halogenated monomer it was fatal: a
+  fluorinated bisphenol died at `4-cure_equilibrate-npt` in **7 of 7** build
+  attempts, at cure iteration 5-7 of ~10, with exit codes 1 and 139.  `LINCS`
+  appeared 14 times in that bridge's `diagnostics.log` and **zero** times in
+  each of seven other bridges built identically -- a perfect discriminator
+  across eight chemistries.  In a melt of pristine, uncrosslinked monomers at
+  production density, with no cure at all, step-0 pressure was -1.34e5 bar;
+  `h-bonds` took it to -495 bar and the LINCS constraint rmsd from 4.5e-4 to
+  7.3e-7.  With the new settings the whole eight-bridge series rebuilt **32 of
+  32**, the fluorinated one reaching a bond conversion of 0.900 in all four
+  replicates.  `h-bonds` is also the conventional pairing with a 2 fs
+  timestep.
+
+  **This changes the sampled ensemble**, so structures and densities from
+  earlier versions are not strictly comparable with new ones, and because
+  `postsim` inherits `npt.mdp` it changes the production measurement too, not
+  just the cure.  The drag and relax ladders are unaffected -- they always ran
+  unconstrained at 1 fs.
+
+- **`lincs_order = 8` in the packaged `npt.mdp` and `nvt.mdp`.**  Independent
+  of the constraint change: it improves the accuracy of the constraint solve
+  without changing which bonds are constrained, so it does not itself alter
+  the ensemble.  On the diagnostic melt above, order 8 alone reduced the
+  pressure artifact 4.8-fold.
+
+### Added
+
+- **The CURE relax stages now report the density they produce.**  The relax
+  ladder is the only above-`Tg` constant-pressure time in a cure -- roughly
+  120 ps of it, at the defaults -- and nothing looked at the density it
+  produced: `_do_relax` delegates to `_distance_attenuation`, which never
+  calls `TopoCoord.equilibrate()`, the only method that traced Density.  The
+  per-stage relax table gains a `Density (kg/m3)` column, read from the NPT
+  `.edr` each stage already wrote.  Drag is deliberately excluded, since it
+  runs under restraints and its density is not comparable.
+
+- **The CURE relax stages now report reactive-species mobility (Varshney's
+  criterion).**  After each relax ladder, htpolynet reports the rmsd
+  displacement of atoms that still carry an unused reactive site, and what
+  fraction of them moved at least one `CURE.controls.search_radius` during
+  the window.  Varshney sized the original 40 ps relaxation window on exactly
+  this requirement -- that unreacted species diffuse far enough between
+  reactions to find new partners -- but the requirement decays over a cure as
+  those species are bonded into the growing network, and until now nothing
+  reported when a window had stopped satisfying it.  A build where fewer than
+  25 % of still-reactive atoms cross a search radius now says so, because its
+  later bonds are being chosen from a nearly frozen neighborhood.
+
+  Both reports are pure observation: they change no simulation input and
+  gate nothing.  Every failure path is swallowed and logged at debug level,
+  so instrumentation cannot fail a build.  A run resuming mid-ladder skips
+  the mobility report rather than measuring only the tail of its window.
+
+- **`repair-summary.yaml` now reports the pre-repair bond histogram.**  A new
+  `prerepair_bond_counts` key gives how many crosslinkers carried 0, 1, ... up
+  to `full_bond_count` bonds *before* repair dismantled any of them.  Repair
+  rewrites the topology and the final structure does not record which cap came
+  from which ring, so this distribution was previously unrecoverable after the
+  fact -- only `n_complete`, its top bin, survived.  It is the statistic that
+  makes the independence assumption behind "crosslinker conversion = bond
+  conversion cubed" directly testable, and that relationship is now known to
+  be wrong in a way that matters: audited against 54 builds, the effective
+  exponent runs about 3.5 near a bond conversion of 0.55, 3.0 near 0.73 and
+  2.6-2.7 near 0.90, so the deviation from the cube changes sign and no single
+  power law fits.  The histogram is zero-filled, so the shape of the summary
+  does not depend on the box, and it is cross-checked against the completion
+  count on every build -- the two are computed independently, and a
+  disagreement now warns.
+
+### Documentation
+
+- **The constraint trap is documented where someone hitting it will look.**
+  The failure above surfaces at the equilibration step immediately after the
+  relax ladder, so the natural diagnosis is that the relax schedule is too
+  coarse.  It is not: the drag and relax ladders run unconstrained at a 1 fs
+  timestep and cannot be responsible, and refining them makes matters worse --
+  a three-variant array (increment 0.08 to 0.04 to 0.02, plus a double-MD arm)
+  confirmed that, with quadrupling the stage count degrading the result.  The
+  CURE section of the program-flow page now says which stages are constrained
+  and which are not, and says to look at the constraints rather than the
+  ladder when LINCS warnings appear at `cure_equilibrate`.
+
+- **Four defaults in the `CURE.controls` table were wrong.**  The table and
+  `curedict_defaults` had drifted apart: `radial_increment` is 0.05 and was
+  documented as 0.25, `max_iterations` is 100 and was documented as 150,
+  `desired_conversion` is 0.5 and was documented as 0.95, and
+  `min_allowable_bondcycle_length` is -1 rather than 0 (any value <= 0
+  disallows all cycles, so the documented *behavior* was right and only the
+  literal was wrong).  `desired_conversion` is the costly one: a user who
+  read "default 0.95" and omitted the key got a half-cure.  Every shipped
+  example that cures sets it explicitly, which is why nothing caught this.
+
+- **`desired_conversion` now says which conversion it means.**  The
+  `CURE.controls` table described it as "target conversion", which every
+  reader takes to be the crosslinker conversion an experiment measures.  It
+  is the *bond* conversion -- bonds formed over bonds possible -- and the
+  crosslinker conversion is lower: at a nominal 90 % cure, an audit of 30
+  builds found 75.2 triazines complete per 100, not 90.  The row now says
+  so and links to the fuller explanation under postcure repair.
+
 ## [2.6.2] - 2026-08-31
 
 ### Fixed
@@ -910,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.6.2 → htpolynet-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.6.2
+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