htpolynet 2.8.0__tar.gz → 2.10.0__tar.gz

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

@@ -7,6 +7,138 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.10.0] - 2026-09-15
+
+### Added
+
+- **A constituent can carry its own frcmod.**  `frcmod: file.frcmod` on a
+  constituent loads that Amber parameter file into `tleap` after GAFF and
+  `parmchk2`, so its parameters override theirs.  It is loaded for the
+  molecule and for every template containing it, including cure, capping,
+  repair and multiply-substituted templates.  The file's contents are part of
+  the parameter cache record, so an edited frcmod re-parameterizes instead of
+  reusing stale numbers.  A system has one table per bonded type, so setup
+  stops with the type's name if an overridden type also appears, with other
+  parameters, in a molecule built without the file.
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.8.0
+Version: 2.10.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.8.0 → htpolynet-2.10.0}/ROADMAP.md

@@ -199,6 +199,20 @@ Coverage as of the last measurement: **38.8%** overall.
 
 ## Cure and repair
 
+- **Cure still settles template overcharge system-wide.**
+  `map_from_templates` ends each batch of bonds with one `adjust_charges`
+  over every mapped atom in the system.  When the templates are consistent
+  with each other this does nothing: since the second-shell templates, all 13
+  of example 6's molecules after cure are neutral (before them, the
+  range was -0.37 to +0.29 e).  But any template that does not describe
+  its instance exactly (a mapped atom whose context the template lacks, or
+  charges from a different conformer) leaks charge between molecules without
+  a trace.  A per-molecule settle, like
+  `topology_surgery.neutralize_touched_fragments` in repair, would contain
+  it.  Two cases the second-shell rule leaves out: reacted atoms *directly*
+  bonded to the bonding atom (it leaves those to the C=C chain machinery), and
+  atoms that aren't declared symmetry-equivalent.
+
 - **`cap_min_clearance` has never been calibrated against a working metric.**
   The 0.150 nm default was chosen in 2.6.0 against a clearance that was pinned
   at 0.136 nm by a bug, so it fired on 100 % of caps for a reason that had
@@ -905,6 +919,36 @@ Coverage as of the last measurement: **38.8%** overall.
   docs describe only the GAFF-scoped form. base.yaml declares both, marking the
   top-level spelling deprecated; pick one before the schema goes live.
 
+- **A parameterized molecule built from a symmetry-sibling reactant would
+  hand antechamber an incomplete bond table.**  Found while fixing the
+  bondless-MOL2 writes reported by the 2026-09-13 example sweep. Symmetry
+  siblings are loaded from the parent's top+gro and carry no `mol2_bonds`.
+  When topologies merge (`Topology.merge` via `_myconcat(... 'mol2_bonds')`),
+  a reactant without that table contributes nothing to the product's, so the
+  product's `{name}.mol2`, which `Molecule.parameterize` gives to antechamber
+  for atom typing, would silently lack that reactant's internal bonds.
+  `TopoCoord.write_mol2` now falls back to topology bonds only when the table
+  is absent entirely, which does not cover this partial case. Not exercised by
+  any shipped example: the fresh-cache 2026-09-13 sweep had zero bondless
+  writes outside diagnostic `-prebonding` files, and every sibling product
+  copied its parent's topology rather than being parameterized. The fix, if
+  a case ever appears, is for `merge` to synthesize `mol2_bonds` from `bonds`
+  for any operand that lacks the table, rather than concatenating a partial
+  table. Bond orders would then need the same single-bond assumption.
+
+- **Two gaps left after the percolation check moved to cure sites
+  (2026-09-15).**  First, a system that crosslinks through a *multi-residue*
+  molecule -- example 2's GMA (two methacrylate HIE units), example 5's
+  three-armed THT -- is reported as "not assessed". A real assessment needs a
+  molecule-level count: sum cure sites per molecule and ask how many molecules
+  reacted at all of them. Second, `CureController._completion_bias_counts`
+  still ranks candidates by `residue_reaction_counts` over *all* atoms, so a
+  bond made while building a molecule (HIE's C4) counts as progress toward
+  completion. That only matters with `completion_bias` on, which no shipped
+  example uses. It was left alone because fixing it changes which bonds a
+  biased cure forms, not just a diagnostic; `cure_site_mask` is the tool when
+  that is wanted.
+
 ## Simulation defaults
 
 - **The halogen constraint failure is fixed but not explained.** v2.7.0

{htpolynet-2.8.0 → htpolynet-2.10.0}/docker/Dockerfile

@@ -60,12 +60,19 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 ARG GROMACS_BUILD=
 ARG CONDA_OVERRIDE_CUDA=
 
+# Clean with conda, not mamba.  mamba 2.9.0 (miniforge3 26.7.2-0, the image
+# :latest moved to on 2026-09-09) fails `mamba clean -afy` with "cannot get
+# file size: No such file or directory" on the CPU AmberTools 26.0 package:
+# its bin/amber.conda is a symlink that dangles inside the package cache, and
+# mamba stats everything named *.conda.  The install itself succeeds; only the
+# clean dies, taking the whole RUN with it.  conda clean handles the same cache
+# correctly.  Reproduced locally in both directions before changing this.
 RUN CONDA_OVERRIDE_CUDA="${CONDA_OVERRIDE_CUDA}" mamba install -y -n base -c conda-forge \
         ambertools \
         "gromacs${GROMACS_BUILD:+=*=${GROMACS_BUILD}*}" \
         parmed \
         rdkit \
-    && mamba clean -afy
+    && conda clean -afy
 
 # Install HTPolyNet
 COPY . /htpolynet

{htpolynet-2.8.0 → htpolynet-2.10.0}/docs/source/conf.py

@@ -58,6 +58,19 @@ language = 'en'
 #
 html_theme = 'furo'
 
+# The logo is line art, so it ships as two transparent variants rather than one
+# opaque image: black ink for the light theme, white ink for the dark one.  An
+# opaque logo would show as a white square in furo's dark mode.
+html_theme_options = {
+    'light_logo': 'htpolynet-logo-light.png',
+    'dark_logo': 'htpolynet-logo-dark.png',
+}
+
+# The favicon, unlike the sidebar logo, keeps an opaque white disc: a browser's
+# tab bar may be light or dark, and transparent line art would vanish on one of
+# them.  16, 32 and 48 px in one .ico.
+html_favicon = '_static/htpolynet-favicon.ico'
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

{htpolynet-2.8.0 → htpolynet-2.10.0}/docs/source/example-tutorials/6-cyanate-ester/reactions.rst

@@ -43,6 +43,21 @@ setup time, each as a separately parameterized linked-product
 template.  The cure machinery treats them as six distinct reactions in
 the iterative bond search, but the user only had to write one.
 
+Six templates are not enough to give the ring the right charges,
+though.  Each describes a triazine with one BPA attached, so it shows
+the other two ring carbons unreacted, and a template splice rewrites
+the charges of every atom within two bonds of the new bond, which
+includes those carbons.  Without more context, the second and third
+bonds on a ring would reset the carbons that reacted before them to
+their unreacted charge.  So htpolynet also builds, at setup time, one
+template for each bonding carbon, BPA oxygen, and set of ring carbons
+already bonded: 18 more, with names like
+``BPA~O1-C3~BPA~O1-C2~BPA~O1-C1~TAZ``.  At each bond, the cure picks
+the one that matches the ring as it stands.  Nothing in the
+configuration asks for these.  htpolynet generates them for any
+reactive atom whose ``symmetry_equivalent_atoms`` partners sit two
+bonds away, as a triazine's ring carbons do.
+
 What the cure stage produces, then, is an A2+B3 step-growth ether
 network: every formed bond is the same chemistry (an aryl O to a
 triazine ring C, replacing one H on each side with a new C-O bond),

{htpolynet-2.8.0 → htpolynet-2.10.0}/docs/source/index.rst

@@ -41,6 +41,11 @@ htpolynet
    :target: https://doi.org/10.5281/zenodo.22070252
    :alt: DOI
 
+.. image:: _static/htpolynet-landing.jpg
+   :alt: A rusty robot in a straw hat sits on a driftwood log on a tropical beach, humming as it knots a net of ball-and-stick molecules strung between posts. A hand-painted sign beside it reads "HTPOLYNET: Stranded today. Better polymers tomorrow."
+   :align: center
+   :width: 100%
+
 htpolynet is a command-line tool for building atomic configurations of amorphous network polymers suitable for molecular dynamics (MD) simulations.
 It uses the General Amber Force Field and produces output that can be simulated 
 using Gromacs.

{htpolynet-2.8.0 → htpolynet-2.10.0}/docs/source/install.rst

@@ -2,12 +2,39 @@
 Installation and Prerequisites
 ##############################
 
-A pre-built container image is available that bundles all required
-software (Gromacs, AmberTools, OpenBabel, RDKit, and ``htpolynet``).  If
-you have Docker or Singularity/Apptainer available, this is the easiest
-way to get started — see :ref:`container_usage` for instructions.  The
-remainder of this page describes how to install ``htpolynet`` and its
-prerequisites directly on your system.
+.. admonition:: Recommended: run htpolynet from the container
+   :class: tip
+
+   The easiest way to use ``htpolynet`` is the pre-built container image,
+   ``ghcr.io/cameronabrams/htpolynet``.  It bundles everything ``htpolynet``
+   needs --- Gromacs, AmberTools, OpenBabel, RDKit, and ``htpolynet`` itself
+   --- so there is nothing else to install and no versions to line up.
+
+   **On a desktop** (Docker), fetch the Compose file once, then run
+   ``htpolynet`` through it:
+
+   .. code-block:: console
+
+      $ curl -O https://raw.githubusercontent.com/cameronabrams/htpolynet/main/docker/compose.yml
+      $ docker compose run --rm htpolynet run config.yaml
+
+   **On a cluster** (Singularity/Apptainer), pull the image once, then run it
+   with your working directory bound in:
+
+   .. code-block:: console
+
+      $ singularity pull htpolynet.sif docker://ghcr.io/cameronabrams/htpolynet:latest
+      $ singularity run --bind $(pwd):/work --pwd /work htpolynet.sif run config.yaml
+
+   The default image runs Gromacs on CPUs only.  To use an NVIDIA GPU, use
+   the ``:cuda`` tag instead.
+
+   See :ref:`container_usage` for the details: persistent caches, GPU setup,
+   and pinning a release.
+
+The rest of this page covers installing ``htpolynet`` and its prerequisites
+directly on your system, which you'll want for development or wherever
+containers aren't available.
 
 Software Prerequisites
 ----------------------

{htpolynet-2.8.0 → htpolynet-2.10.0}/docs/source/user-guide/configs/configs-for-run.rst

@@ -98,8 +98,35 @@ In this section we show all subdirectives for each of the five main directives i
     ``smiles``                               string             (optional) SMILES for in-config monomer generation; htpolynet runs ``obabel`` (or RDKit) to materialize ``lib/molecules/inputs/<NAME>.mol2`` before parameterization
     ``rename_atoms``                         dict               (optional) ``{1-based-mol2-index: atom-name}`` map applied after obabel writes the mol2 (obabel path; pairs with ``smiles``)
     ``reactive_atoms``                       dict               (optional) ``{smiles-atom-map-label: atom-name}`` map (RDKit path; pairs with a ``smiles`` that uses ``[*:N]`` atom-mapping tokens).  ``rdkit`` is a required runtime dependency and is pulled in by any normal ``htpolynet`` install
+    ``frcmod``                               string             (optional) path, relative to the configuration file, to an Amber ``frcmod`` of parameter overrides for this molecule; see below
     =====================================    =================  =====================
 
+    ``frcmod`` corrects GAFF for one monomer without touching the others, for
+    example a torsion refit against quantum-chemical scans.  ``tleap`` loads
+    the file after GAFF and ``parmchk2``, so its entries win.  It is loaded
+    for the molecule itself and for every template that contains it: cure
+    products, capping and repair templates, and the multiply-substituted
+    templates htpolynet derives.  The file's contents are part of each of
+    those parameterizations' cache records, so editing it re-parameterizes
+    them on the next run rather than reusing the old numbers.
+
+    .. code-block:: yaml
+
+       constituents:
+         BAF:
+           smiles: "FC(F)(F)C(c1ccc([OH:1])cc1)(c1ccc([OH:2])cc1)C(F)(F)F"
+           reactive_atoms: {1: O1, 2: O2}
+           frcmod: baf-torsion.frcmod
+
+    One restriction follows from how GROMACS topologies work.  A system holds
+    one parameter table per bonded *type* (four atom types, for a dihedral),
+    shared by every molecule in it.  So an override cannot apply to a type in
+    one molecule and leave the same type alone in another: if a molecule
+    built without the frcmod also contains the overridden type, with
+    different parameters, setup stops and names it.  Either load the same
+    frcmod for every constituent that contains the type, or give the atoms
+    you want to treat differently their own atom type.
+
     In the example below, we are requesting a system of 100 styrene molecules.  The key ``STY`` signals to ``htpolynet`` that it should look for either ``STY.mol2`` or ``STY.pdb`` in ``./lib/molecules/inputs`` **or** it should look for ``STY.gro``, ``STY.itp``, ``STY.top``, and ``STY.grx`` in ``./lib/molecules/parameterized``.  The latter is the case if either ``htpolynet run`` or ``htpolynet parameterized`` has already been run with ``STY.mol2`` or ``STY.pdb``.  If neither set of files is found but the constituent carries a ``smiles`` key, ``htpolynet`` generates the input ``mol2`` itself.  Multiple records in ``constituents`` should all have the "key":"record" syntax and be separated by commas.
 
     Any entry in ``constituents`` for which the ``count`` is 0 or missing is treated as an intermediate for which stereocenters or symmetry-equivalent atoms are specified.

{htpolynet-2.8.0 → htpolynet-2.10.0}/pyproject.toml

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

{htpolynet-2.8.0 → htpolynet-2.10.0}/src/htpolynet/core/bondtemplate.py

@@ -15,7 +15,7 @@ logger = logging.getLogger(__name__)
 
 
 class BondTemplate:
-    def __init__(self, names, resnames, intraresidue, order, bystander_resnames, bystander_atomnames, oneaway_resnames, oneaway_atomnames):
+    def __init__(self, names, resnames, intraresidue, order, bystander_resnames, bystander_atomnames, oneaway_resnames, oneaway_atomnames, siblings=None):
         """Creates a BondTemplate object.
 
         Args:
@@ -27,6 +27,10 @@ class BondTemplate:
             bystander_atomnames (list of two list-like containers of strs): lists of names of atoms in bystander residues (parallel to bystander_resnames)
             oneaway_resnames (list-like container of strs): names of one-away residues (residues bound one bond away from the new interresidue bond; only relevant for C=C free-radical polymerization)
             oneaway_atomnames (list-like container of strs): names of atoms in one-away residues
+            siblings (list of two lists of (str, str) tuples): for each atom in names, the
+                (atomName, partner resName) of every other atom in its residue, within two
+                intraresidue bonds, that is already bonded to another residue; defaults to
+                none on either side.  See TopoCoord.get_siblings.
         """
         self.names = names
         self.resnames = resnames
@@ -36,6 +40,7 @@ class BondTemplate:
         self.oneaway_resnames = oneaway_resnames
         self.oneaway_atomnames = oneaway_atomnames
         self.order = order
+        self.siblings = [sorted(tuple(t) for t in x) for x in siblings] if siblings else [[], []]
 
     def reverse(self):
         """Reverses the order of all parallel lists in a BondTemplate object."""
@@ -45,9 +50,10 @@ class BondTemplate:
         self.bystander_atomnames = self.bystander_atomnames[::-1]
         self.oneaway_resnames = self.oneaway_resnames[::-1]
         self.oneaway_atomnames = self.oneaway_atomnames[::-1]
+        self.siblings = self.siblings[::-1]
 
     def __str__(self):
-        return f'BondTemplate {self.names} resnames {self.resnames} intraresidue? {self.intraresidue} order {self.order} bystander-resnames {self.bystander_resnames} bystander-atomnames {self.bystander_atomnames} oneaway-resnames {self.oneaway_resnames} oneaway-atomnames {self.oneaway_atomnames}'
+        return f'BondTemplate {self.names} resnames {self.resnames} intraresidue? {self.intraresidue} order {self.order} bystander-resnames {self.bystander_resnames} bystander-atomnames {self.bystander_atomnames} oneaway-resnames {self.oneaway_resnames} oneaway-atomnames {self.oneaway_atomnames} siblings {self.siblings}'
 
     def __eq__(self,other):
         check = self.names == other.names
@@ -57,6 +63,7 @@ class BondTemplate:
         check = check and self.bystander_atomnames == other.bystander_atomnames
         check = check and self.oneaway_resnames == other.oneaway_resnames
         check = check and self.oneaway_atomnames == other.oneaway_atomnames
+        check = check and self.siblings == other.siblings
         return check
 
     def is_reverse_of(self,other):
@@ -73,13 +80,15 @@ class BondTemplate:
         return self == rb
 
     def bystander_count(self):
-        """Total number of bystander (resname, atomname) pairs across both sides.
+        """Total number of bystander (resname, atomname) pairs and siblings across both sides.
 
-        Used by find_template's best-match selection: more bystanders = more
+        Used by find_template's best-match selection: more context = more
         specific template, which should win when multiple templates can match
-        an instance under subset semantics.
+        an instance under subset semantics.  Siblings count here so that a
+        triazine template with two ring carbons already bonded beats the one
+        with one, which beats the bare one.
         """
-        return sum(len(s) for s in self.bystander_resnames)
+        return sum(len(s) for s in self.bystander_resnames) + sum(len(s) for s in self.siblings)
 
     def matches(self, other):
         """Return True if `self` (a parameterization-stage template) is a
@@ -111,6 +120,13 @@ class BondTemplate:
         force the cure reactant to mirror every inter-residue partner
         the instance carries, which forecloses the small-fragment idiom.
 
+        Subset semantics on siblings, for the same reason.  A sibling is
+        another atom of a bonding residue, close enough to the bonding atom
+        that the template overwrites its charge, that is already bonded to
+        another residue.  A template declaring a sibling describes that atom
+        as reacted, so it must not be used where the atom has not; a template
+        declaring none has always been used regardless, and still is.
+
         Args:
             other (BondTemplate): the instance bond to test for compatibility
 
@@ -133,6 +149,12 @@ class BondTemplate:
                     remaining.remove(tp)
                 else:
                     return False
+            remaining = list(other.siblings[side])
+            for sib in self.siblings[side]:
+                if sib in remaining:
+                    remaining.remove(sib)
+                else:
+                    return False
         return True
 
     def matches_reverse_of(self, other):

{htpolynet-2.8.0 → htpolynet-2.10.0}/src/htpolynet/core/molecule.py

@@ -506,7 +506,7 @@ class Molecule:
             # logger.debug(f'{self.name} oneaways {oneaway_resids} {oneaway_resnames} {oneaway_atomidx} {oneaway_atomnames}')
             self.reaction_bonds.append(ReactionBond(atom_idx, in_product_resids, order, bystander_resids, bystander_atomidx, oneaway_resids, oneaway_atomidx))
             intraresidue = in_product_resids[0] == in_product_resids[1]
-            self.bond_templates.append(BondTemplate(atom_names, in_product_resnames, intraresidue, order, bystander_resnames, bystander_atomnames, oneaway_resnames, oneaway_atomnames))
+            self.bond_templates.append(BondTemplate(atom_names, in_product_resnames, intraresidue, order, bystander_resnames, bystander_atomnames, oneaway_resnames, oneaway_atomnames, siblings=TC.get_siblings(atom_idx)))
 
     def idx_mappers(self, otherTC: TopoCoord, other_bond, bystanders, oneaways, uniq_atom_idx: set):
         """Computes the mapping dictionary from molecule template index to instance index in the other TopoCoord.

{htpolynet-2.8.0 → htpolynet-2.10.0}/src/htpolynet/core/paramcache.py

@@ -17,6 +17,7 @@ libraries keep working rather than silently re-parameterizing wholesale.
 
 Author: Cameron F. Abrams <cfa22@drexel.edu>
 """
+import hashlib
 import json
 import logging
 import os
@@ -33,6 +34,30 @@ _KEY_FIELDS = (
 )
 """Fields that determine the parameters, with human-readable labels."""
 
+FRCMOD_FIELD = 'frcmod'
+"""Record field holding a digest of the user frcmod files loaded after parmchk2's.
+
+Written only when a molecule has any, so records of molecules without one are
+unchanged; its absence means "none" when compared.
+"""
+
+
+def frcmod_digest(frcmods):
+    """Returns a digest identifying a list of user frcmod files by content.
+
+    Args:
+        frcmods (list): (label, text) tuples, in load order
+
+    Returns:
+        str or None: hex digest, or None if the list is empty
+    """
+    if not frcmods:
+        return None
+    h = hashlib.sha256()
+    for label, text in frcmods:
+        h.update(label.encode('utf-8') + b'\0' + text.encode('utf-8') + b'\0')
+    return h.hexdigest()[:16]
+
 
 def build_key(ambertools=None):
     """Returns the provenance record describing a parameterization run under
@@ -49,8 +74,12 @@ def build_key(ambertools=None):
     """
     from ..external.ambertools import AMBERTOOLS_DEFAULTS
     ambertools = ambertools or {}
-    return {field: ambertools.get(field, AMBERTOOLS_DEFAULTS[field])
-            for field, _ in _KEY_FIELDS}
+    key = {field: ambertools.get(field, AMBERTOOLS_DEFAULTS[field])
+           for field, _ in _KEY_FIELDS}
+    digest = frcmod_digest(ambertools.get(FRCMOD_FIELD))
+    if digest:
+        key[FRCMOD_FIELD] = digest
+    return key
 
 
 def key_filename(prefix):
@@ -129,4 +158,8 @@ def describe_mismatch(stored, requested):
             continue
         if stored[field] != requested.get(field):
             diffs.append(f'{label} {stored[field]!r} cached, {requested.get(field)!r} requested')
+    # unlike the fields above, an absent frcmod digest is a statement: none was loaded
+    if stored.get(FRCMOD_FIELD) != requested.get(FRCMOD_FIELD):
+        diffs.append(f'user frcmod {stored.get(FRCMOD_FIELD) or "none"} cached, '
+                     f'{requested.get(FRCMOD_FIELD) or "none"} requested')
     return diffs