htpolynet 2.7.0__tar.gz → 2.9.0__tar.gz

htpolynet-2.9.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.9.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.9.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.9.0}/CHANGELOG.md

@@ -7,6 +7,245 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.9.0] - 2026-09-15
+
+### Added
+
+- **The build log reports molecules that carry net charge.**  After cure,
+  after postcure repair, and when the final results are written, htpolynet
+  checks every covalently bonded molecule.  It logs one line when all are
+  neutral to within 0.01 e, and a warning naming the count and the largest
+  charge when some are not.  The system total is zero by construction, so
+  until now a template or repair step that moved charge from one molecule to
+  another left no trace.  The check can't see charge misplaced *inside* a
+  percolated network, because the whole network is a single molecule.
+
+### Fixed
+
+- **Later bonds on a triazine reset the charges of its earlier ones.**
+  Each cure template shows a single BPA on the ring, and splicing it in
+  rewrites the charges of atoms up to two bonds from the new bond, which
+  includes the other ring carbons.  So every ring carbon that reacted before
+  the last one got its *unreacted* charge back.  Example 6's fully reacted
+  rings had carbons anywhere from 0.14 to 0.31 e, where the template value is
+  0.28.  A cured bisphenol-A dicyanate network showed a clean 2:1 split,
+  +0.70 against +0.90 e.  htpolynet now builds extra templates at setup for
+  rings that already carry one or two BPAs; example 6 gets 18 of them.  Each
+  cure bond picks the one that matches the ring as it stands: templates
+  record which atoms two bonds from the bonding atom have already reacted,
+  and matching prefers the one that records the most.  This applies to any
+  reactive atom whose `symmetry_equivalent_atoms` partners sit two bonds
+  away.  None of the other shipped examples has one, and example 5's
+  build-stage molecules are unchanged, charge for charge.
+
+  Replaying example 6's recorded cure bonds offline puts every bonded ring
+  carbon at its template value: 0.275, 0.277 or 0.279 e for one, two or
+  three BPAs.  All 13 molecules after cure are now neutral, where before
+  they ranged from -0.37 to +0.29 e.  Cyanate-ester builds should be
+  rebuilt.
+
+- **A template that matched a bond only in reverse crashed the cure** with
+  `mapping mismatch -- bug`.  After reversing the bond to line up with the
+  template, the mapping check still compared it the original way round.  No
+  shipped example had reached this path.
+
+- **Cyanate-cap repair left molecules charged.**  `triazine_to_cyanate_cap`
+  kept the system neutral, but not each molecule.  It settled charge twice,
+  both times system-wide:
+  - once while splicing the cap template, when the sacrificial H's still
+    existed;
+  - once after deleting them, onto only the atoms those H's had been bonded
+    to.
+
+  Caps formed in place and caps transferred to a free BPA-OH therefore ended
+  with charges 0.24 e apart on the phenolic O and the cap C.  In a
+  zero-conversion bisphenol-A dicyanate melt, every molecule came out at
+  either +0.21 or -0.27 e.  In example 6, the 27 molecules left after repair
+  ranged from -3.59 to +0.62 e.  Repair now brings each molecule it touched
+  back to neutral, and makes the correction only on the atoms it changed.
+  Example 6's molecules are all neutral, and its cap residues sit at
+  0.05-0.09 e, near the template's 0.069, instead of splitting between 0.04
+  and 0.20.  Builds that used `postcure_repair` should be rebuilt.
+
+- **A false percolation warning on linear polymers.**  The end-of-cure check
+  warned that too few residues had reacted at every site to assume the system
+  percolates, and it fired on chain-growth systems like example 1's
+  polystyrene -- "only 902 of 1000 STY (90.2%) ... below the 100.0% ... at its
+  gel point".  For a difunctional monomer that threshold, `(1/(f-1))^f`, is
+  exactly 100%, and a fully reacted difunctional unit is a chain interior
+  rather than a crosslink junction, so neither the warning nor its premise
+  applied.  The check now runs only when some residue has at least three
+  reactive sites.
+
+- **The percolation check counted sites the cure never uses.**  It summed
+  every reactive site a residue was built with, including bonds made while
+  assembling molecules and valences no cure reaction can consume.  Example 2
+  warned that "0 of 150 HIE" had reacted at all four sites, which was
+  impossible: two of those sites sit on an atom only the molecule-building
+  reactions touch.  Example 5's warning about TB was the same mistake, since
+  every TB site is a chain bond made before the cure.  In examples 3 and 4 the
+  diepoxide and the diamine tied at four sites, so the reported fraction
+  mixed both residue types ("83 of 300 DGE").  Functionality and completion are
+  now counted only on atoms a cure reaction can bond, taken from the
+  symmetry-expanded reaction list the bond search itself uses.  Example 3 now
+  reports "83 of 100 PAC", and example 6's check is unchanged.  When no
+  residue has three or more cure sites, the check says crosslink percolation
+  was not assessed, rather than staying silent: systems that crosslink through
+  a multi-residue molecule, such as a dimethacrylate, are outside what a
+  residue-level count can see.
+
+- **Bondless MOL2 files for symmetry-sibling molecules.**  A molecule built by
+  copying a parent's topology (for example `GMAS-4`, from `GMA`) has its bonds
+  in the topology but no MOL2 bond table, so writing it as MOL2 produced a file
+  with no bonds and a "Cannot write any bonds to MOL2 file" warning -- twelve
+  times in example 2 on a fresh parameterization.  Those writes are now filled
+  from the topology's bonds, as single bonds.  In every shipped example the
+  affected files were diagnostic `*-prebonding.mol2` outputs that nothing reads,
+  so no parameterization input was ever affected.
+
+- **The CPU container image failed to build for 2.8.0**, so
+  `ghcr.io/cameronabrams/htpolynet:v2.8.0` was never published (the CUDA image
+  was).  The base image `condaforge/miniforge3:latest` moved to mamba 2.9.0,
+  whose `mamba clean -afy` fails on a symlink inside the CPU AmberTools
+  package.  The install was succeeding; only the cleanup step failed.  The
+  Dockerfile now cleans with `conda clean`.
+
+### Documentation
+
+- **The installation page now recommends the container as the default way to
+  run htpolynet**, in a callout at the top with the two commands you need on a
+  desktop (Docker Compose) or on a cluster (Singularity/Apptainer), plus the
+  note that the default image is CPU-only and GPU users want the `:cuda` tag.
+  Installing htpolynet and its tools natively is still documented below it,
+  for development and for systems without containers.
+
+- **The documentation has a logo and a landing-page illustration.**  The
+  logo appears in every page's sidebar, in black-on-transparent for the light
+  theme and white-on-transparent for the dark one, so it never shows as a white
+  box in dark mode.  The browser tab shows it too, as a favicon on a white disc
+  so it stays visible whether the tab bar is light or dark.
+
+## [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 +1257,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.9.0}/PKG-INFO

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