htpolynet 2.10.3__tar.gz → 2.11.0__tar.gz

{htpolynet-2.10.3 → htpolynet-2.11.0}/CHANGELOG.md

@@ -7,6 +7,156 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.11.0] - 2026-09-22
+
+### Added
+
+- **A three-body cure reaction: cyclotrimerization** (see `ROADMAP.md`).  A
+  `reactions` entry whose bonds close a ring among three reactants, plus a
+  `ring_cure` configuration block, now build a network by the real cyanate-ester
+  chemistry -- three -O-C#N groups closing one triazine -- instead of the
+  pre-formed-triazine surrogate that needs postcure repair.  CURE is untouched
+  and remains the default; a configuration without a ring-closing reaction
+  behaves exactly as before.
+
+  Verified end to end twice.  On 90 methyl cyanates, which can only trimerize:
+  19 triazines, 63% conversion, every ring six-membered with three aromatic
+  carbons and three aromatic nitrogens, bonds averaging 1.351 A (a triazine's
+  is 1.34) and planar to 0.065 A, the 33 unreacted groups keeping their C#N at
+  1.153 A, and all 52 molecules neutral.  Then on 100 ethylene dicyanates,
+  which gel: 50 triazines, 75% conversion, ring bonds averaging 1.347 A, 55
+  monomers reacted through both arms and 40 through one, no chemically
+  impossible bond, and the largest of the 8 remaining molecules holding 1068 of
+  1200 atoms -- a percolating network.
+
+  Then at scale, on 150 bisphenol A dicyanates -- the real monomer, 35 atoms
+  rather than 12, with a rigid aromatic backbone and its two arms about 0.9 nm
+  apart: 61 triazines at 61% conversion, every unit six-membered with three
+  aromatic nitrogens and three ring carbons still carrying their ester oxygen,
+  ring bonds averaging 1.347 A, no bond anywhere longer than 2.5 A, 54 monomers
+  reacted through both arms and 75 through one, all 150 molecules neutral, and
+  the largest of the 30 remaining components holding 1295 of 5250 atoms.
+
+  A monomer with more than one reactive site needs two things beyond the
+  single-site case, both of which the difunctional build exposed:
+  - **Only the reacting site's share of a residue is spliced.**  A dicyanate can
+    join two rings, and the trimer template shows one arm reacted, so splicing
+    the whole residue reset the other ring's arm -- 36 bonds between an aromatic
+    nitrogen and an unreacted cyanate carbon in the first attempt.  Each atom is
+    assigned to whichever site is nearer through the residue's own bonds.
+  - **The template's atom names are translated for a residue that rings through
+    its other site.**  That exchange moves every atom of the arm, hydrogens
+    included, so it is derived as an automorphism of the monomer's bond graph
+    rather than read off `symmetry_equivalent_atoms`, which names only the
+    reactive atoms.  The sets are still consulted for which sites exist.
+
+  A ring-closing reaction is also exempt from symmetry expansion, which permutes
+  each reactive atom independently: for three dicyanates that produced 64
+  reactions, most of them mixing the two arms of one site, and a template for
+  each.
+  - A reaction's residue-offset arithmetic now works for any number of
+    reactants.  It was written for exactly two, so a bond between the first and
+    third reactant of a three-reactant reaction resolved to the wrong residue.
+  - `reaction.is_ring_closing` recognizes a reaction whose bonds close a cycle
+    among its reactants, which a cyclotrimerization does (1-2, 2-3, 3-1) even
+    though its new bonds alone form no cycle -- the ring closes through bonds
+    each reactant already had.
+  - The pairwise bond search now skips such a reaction with a warning naming
+    it, rather than treating its bonds as three unrelated pairwise candidates
+    and forming them in separate iterations, which would not build a ring.
+  - A reaction bond can declare `sacrificial_h: false`, for an addition where
+    nothing is lost.  Every reaction htpolynet had before is a condensation
+    that deletes one hydrogen from each of the bond's atoms, which stays the
+    default; cyclotrimerization forms three bonds and deletes no atom.
+  - `reaction.spanning_and_closing_bonds` separates the bonds that assemble a
+    product from the bond that closes its ring.  A template build positions
+    each incoming piece as it bonds it, which a closing bond cannot do: the
+    residues it joins are already placed, so it is skipped there and its
+    geometry handled separately.
+  - `Runtime.do_ring_cure` runs it as a workflow stage, with restart state
+    beside the cure's.  `do_cure` now returns early when every cure reaction
+    closes a ring: the pairwise search skips those, so it would otherwise
+    iterate to its limit forming nothing.  (The `CURE` block is present even
+    when a configuration omits it, since the schema supplies its defaults.)
+  - `cure.ringcontroller` runs the loop: search, pull every chosen ring shut,
+    form its bonds, splice the trimer template over its three residues, settle
+    the charge, and count what was consumed.  Conversion is counted in reactive **groups**, three per
+    ring, which is what this chemistry reports -- the pre-formed-triazine route
+    has to infer it from a bond count instead.  The search widens until an
+    iteration yields `min_rings_per_iteration` rings, as the pairwise cure's
+    does for bonds.  Its state round-trips to YAML for restart, carrying the
+    widened radius with it.
+  - `cure.triplesearch` finds the triangles of reactive groups one ring-closing
+    reaction can join.  The pairwise search cannot: it asks which A atom is near
+    which B atom, while a cyclotrimerization needs three groups mutually close,
+    and two well-chosen groups can still leave the third far off.  Candidates
+    are scored as whole triangles by their total new-bond length, both ring
+    orientations are tried, each group may join only one triple, and a group is
+    identified by residue *and* atom names -- a bisphenol dicyanate carries two,
+    which is what makes it a crosslinker.  Two groups of one residue, or of one
+    molecule, are excluded by default.  On a 720-molecule box (1440 groups) at
+    a 0.5 nm radius it finds 358 candidates in half a second and packs 148
+    triples from them.
+  - A reaction bond that consumes no hydrogen is positioned by
+    `Molecule.place_for_addition` rather than `transrot`, which aligns two
+    reactants on the hydrogens they are about to lose and so cannot place an
+    addition at all: in a cyclotrimerization neither the cyanate carbon nor its
+    nitrogen carries one.  The new placement puts the incoming piece a bond
+    length away, in the direction and at the turn that leave the most room,
+    using one shared copy of that geometry in `geometry.placement`.
+  - `Molecule.close_ring_geometry` pulls a ring shut before its bonds exist,
+    by restraining every pair of the ring and stepping the restraints down to a
+    bond length under minimization.  The merged reactants' topology is already
+    valid for MD, and a type-6 restraint needs no atom types, so this needs
+    nothing parameterized.
+  - `Topology.set_restraint_parameters` prescribes a restraint's length and
+    stiffness outright.  `attenuate_bond_parameters` cannot serve here: it
+    reads each bond's reference values from the row it overwrites, which is
+    stable for a real bond, whose reference comes from its atom types, but
+    compounds on a restraint carrying explicit parameters -- an eight-stage
+    ladder ended 400 times too weak to pull anything.
+  - `core.productsplice.map_product_from_template` makes the residues of one
+    reaction event match a product template exactly -- atom types, charges, and
+    every bond, angle, dihedral and 1-4 pair among them, replacing the
+    instance's parameters where they exist and adding them where they do not.
+    This is what a ring closure needs and what the per-bond splice cannot do:
+    among the interactions a triazine closure changes are ones wholly inside a
+    residue (a cyanate C#N becoming a ring bond), which contain no new bond and
+    so are never revisited by `map_from_templates`.  It takes the residue
+    correspondence from its caller rather than inferring it from local context,
+    refuses a residue map that does not explain the bonds it was given, and
+    refuses by default to run before those bonds exist.
+
+### Fixed
+
+- **A ring cure now widens its search radius when an iteration is short of
+  rings, not only when it finds none.**  The pairwise cure has always grown its
+  radius within an iteration until it has `min_bonds_per_iteration` bonds; the
+  ring loop instead widened only after an iteration that found nothing at all.
+  A floppy monomer never noticed, but a rigid one keeps trickling one or two
+  rings at the starting radius, so the radius never grew: 150 bisphenol A
+  dicyanates stopped at conversion 0.40 after eight iterations, having asked for
+  0.60 and never once widened.  With the same rule the pairwise cure uses --
+  counted in rings, and clamped against the rings still needed to reach the
+  target -- the same system reaches 0.61 in eight iterations.  The floor is
+  `ring_cure: min_rings_per_iteration`, default 4.
+
+- **A GPU build died at its first minimization when the configuration set
+  `ntomp`.**  GROMACS refuses OpenMP threads together with a GPU unless it is
+  also told how many ranks to run: "Please specify the number of thread-MPI
+  ranks as well (option -ntmpi)."  Nothing supplied one, so every such build
+  failed about a minute in, after parameterization had already been paid for.
+  htpolynet now passes `-ntmpi 1` when a configuration asks for a GPU, sets
+  `ntomp`, and gives no rank count of its own.  A rank count in the
+  configuration (`ntmpi`, `nt` or `npme`) is left as it is, and so is an MPI
+  `mdrun`, which takes its ranks from `mpirun` or `srun` and rejects
+  `-ntmpi`.  Reported by htpolynet-study from a 9-task GPU build where every
+  task failed.
+
+- **`ntmpi` passed as a keyword argument to `grompp_and_mdrun` was dropped**,
+  because the passthrough list spelled it `ntpmi`.  Configurations were
+  unaffected: `mdrun_options` is copied whole.
+
 ## [2.10.3] - 2026-09-17
 
 ### Fixed

{htpolynet-2.10.3 → htpolynet-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.10.3
+Version: 2.11.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.10.3 → htpolynet-2.11.0}/ROADMAP.md

@@ -199,6 +199,418 @@ Coverage as of the last measurement: **38.8%** overall.
 
 ## Cure and repair
 
+- **Filtering candidate crosslinks against disallowed topologies, and what that means
+  for cyanate esters.**  Raised by Cameron 2026-09-21, who asked the right question:
+  can "physically disallowable" even be defined for these systems?  Partly.  Three
+  classes, in descending order of how firm the ground is.
+
+  **What is filtered today.**
+  - `TopoCoord.makes_shortcircuit` rejects a candidate whose two atoms sit in
+    residues that are *already* bonded to each other, so one pair of residues cannot
+    be doubly bonded.  Live for every chemistry.
+  - `TopoCoord.pierces_ring` rejects a candidate whose segment passes through an
+    existing covalent ring, and can dump a gro file of the piercing.  Live, and the
+    one genuinely topological test in the code.
+  - **The cycle-length filter is inert for cyanate esters.**
+    `min_allowable_bondcycle_length` is read into `TC.min_bondcycle_length`, but the
+    only code that consults it is the C-C bondchain pass, which exists for vinyl
+    chain growth; `makes_bondcycle` itself is commented out in `bondtest`.  For an
+    ether O-C bond, `chain_of` returns None and the whole check is skipped.  So
+    example 6 and the study's bridge series have run with **no cycle filter at all**,
+    and the config key silently does nothing there.  Worth saying out loud before
+    designing more filters.
+
+  **Class 1, firm: valence and connectivity.**  Already handled by `z` bookkeeping
+  and the short-circuit test.  One gap arrives with the three-body reaction above: two
+  -OCN groups of the *same* molecule entering the *same* triazine.  Not forbidden by
+  valence, and Lin & Khare forbade the analogous intramolecular loop by fiat.  Make it
+  a constraint of the triple search (one group per molecule per ring) with a config
+  switch, not a post-hoc rejection.
+
+  **Class 2, firm: catenation and threading.**  `pierces_ring` is one-directional: it
+  asks whether a *new bond* pierces an *existing ring*.  Cyclotrimerization creates
+  rings in situ, so the complementary test is needed -- does a *newly formed ring*
+  encircle an existing strand?  Without it, trimerization can build catenanes that no
+  chemistry would produce and no MD will undo.  This is a real, definable test and
+  should land with the three-body work.
+
+  **What the existing networks actually contain (htpolynet-study, 2026-09-21).**
+  Measured on the v5 builds, 96 cured cells, 1440 bisphenol + 960 TAZ;
+  `drops/htpolynet-study-cycle-sizes-20260921.md`, scripts and JSON in the study tree.
+  - The atom-level shortest cycle through a cure bond is **quantized at 14n, with a
+    floor of 28 in every cell, every conversion, every bridge.**  Nothing shorter
+    occurs.  14 atoms is one junction-to-junction repeat (O + 4 aryl + X + 4 aryl + O,
+    plus C-N-C through the triazine); a chemistry with a direct biphenyl link would
+    give 13, so **14 is not a constant to hardcode**.
+  - A 28-ring is two triazines joined by two *different* bisphenols.  Double-bridged
+    triazine pairs are 1.4% of bridges at chi = 0.99 (1540 instances).  **They form
+    late, and kinetically they must.**  Replaying the DEBUG bond table, which carries
+    residue numbers, dates every ring closure: over 32 c099 cells and 45,199 bridge
+    completions, the instantaneous closure rate per 100 bridges runs
+    0.21 -> 0.83 -> 1.46 -> 1.83 -> 2.55 -> 1.98 -> 1.01 across conversion, and the
+    median closure sits at chi 0.819 against 0.732 for bridges generally.  A second
+    bridge requires the triazine pair to be connected already, so the rate is first
+    connectivity-gated and then end-group-limited.  (An earlier note here called the
+    rate "flat and suspicious"; that was an artifact of comparing *cumulative* ratios
+    at 0.90/0.95/0.99, which all sit in the plateau of a saturating curve --
+    htpolynet-study, retracted 2026-09-21, `bridge-series/ring_history.py`.)
+  - Intramolecular loops, both arms of one bisphenol into one triazine, a 14-ring:
+    **zero in 96 cells, zero in ~250,000 bridges.**
+  - **And the reason is `makes_shortcircuit`, not geometry** -- which turned up
+    something worth knowing.  That test keys on the `molecule` gro attribute, which is
+    set at template build and replication and **never updated when a cure bond merges
+    two molecules**.  So it asks only "are these two monomer instances already
+    directly bonded to each other?", which forbids exactly the 14-ring and nothing
+    else.  The staleness is load-bearing: were `molecule` the current connected
+    component, the test would reject every cycle-closing bond and no system could gel
+    (ours carry a cycle rank of ~430 on ~938 junctions).  Now noted in the code at
+    both sites that read it, so it does not get "fixed".
+
+  **Class 3, soft: strained cycles, and the threshold problem.**  For cyanate esters
+  this class is where a filter does *harm* if switched on -- see the end-group
+  arithmetic below -- so what follows is a facility for other chemistries, not a
+  correction for this one.  A candidate bond
+  whose two atoms are already close *through the bond graph* closes a covalent cycle.
+  Small ones are unphysical -- a cycle threading a few rigid aromatic units cannot
+  close without absurd strain -- but "small" needs a number, and inventing one is
+  how a filter starts rejecting chemistry that is fine.  The clean generalization is
+  a **graph-distance filter**: reject a candidate when the shortest existing bond path
+  between its atoms is under N bonds, with N from config, computed by a BFS bounded at
+  N on `Topology.bondlist`, which is cheap and chemistry-agnostic.  It subsumes the
+  vinyl-only cycle logic conceptually and catches the same-molecule-twice case for
+  free.
+  - **The data says this filter is insurance, not a correction.**  The floor is a
+    28-membered macrocycle -- large and unstrained -- and the one strained candidate,
+    the 14-ring, is already excluded.  Because the spectrum is quantized, N has few
+    distinct settings in this chemistry: 15 <= N <= 28 is a no-op, N = 29 removes the
+    28-rings, N = 43 removes 28s and 42s.
+  - **Count crosslinker repeats, not atoms** (the study's ask, and it is right).
+    "Reject a bond closing a cycle spanning fewer than k junction-to-junction
+    repeats" reads off the junction graph, is chemistry-independent, and avoids a
+    per-chemistry magic number.
+  - **Off by default is the CORRECT default for cyanate esters, not a cautious one --
+    and the docs and the code comment must say why.**  htpolynet-study, 2026-09-21,
+    from the library: Fang & Shimp's end-group arithmetic caps acyclic dendritic
+    growth at **75%** cyanate conversion, a mild ring-chain model at **90%**, and only
+    severe macrocyclization reaches **98%**.  Real cure reaches 98-99%, and Guenthner
+    2014 treats the point as settled.  **A 98% polycyanurate network cannot be
+    macrocycle-free.**  Filtering short cycles out of this chemistry would therefore
+    remove the very structures that let it cure at all.
+  - **The convention we would be importing comes from a different chemistry.**  Khare
+    2018 and Lin 2009 justify prohibiting short cycles for **epoxy-amine**, where they
+    are negligible.  That justification inverts for cyanate esters.  Put this in a
+    comment where the filter is defined, because the filter will otherwise look
+    under-used and someone will helpfully turn it on.
+  - **If anything, we make too few.**  Two independent measures: cycle rank per
+    monomer **0.303 against Fang's 0.485**, and a gel-point delay of **+6.3% against
+    Lin's +21%** cyclization term.  So the interesting question for cyanate esters is
+    not how to suppress cycles but why htpolynet produces fewer than the chemistry
+    demands -- plausibly the 0.5 nm search radius and junctions seeded at t=0.  That
+    is a separate investigation, and the three-body reaction changes its terms, since
+    junctions would then emerge where ends meet.
+  - The 28-rings are near-unstrained in GAFF (span -0.07 A, C-O-C angle -0.46 deg
+    against non-ring bridges), but that only says the force field tolerates them.
+    Their absolute frequency is still set by our search radius and seeded junctions,
+    so **1.4% must never be quoted as a physical cyclization rate**; the comparison
+    against Fang above is the meaningful one.
+  - **Do not validate the filter on Tg in this system -- it is underpowered, and
+    that is bounded, not guessed.**  Between-bridge spread in ring density is 0.67
+    percentage points of bridges, and dTg/dconversion averages 5.6 K per percentage
+    point of bonds, so even if every ring bridge were completely elastically dead the
+    differential Tg across bridges is <= 3.8 K and the absolute effect <= 8.0 K --
+    against a replicate standard deviation of 12.5-25.0 K at chi 0.99 with n = 4.  A
+    null result would mean nothing.
+  - **Validate it structurally instead.**  Correctness on synthetic graphs (it rejects
+    what it should, and nothing else) plus structural observables that respond
+    directly and cheaply -- cycle rank, the count of elastically effective strands,
+    the fragment distribution -- rather than a thermal property the system cannot
+    resolve.  If a thermal effect is ever wanted, it needs a system engineered for a
+    high ring density, not this one.
+  - **Re-measure for cyclotrimerization.**  These statistics come from the A2+B3
+    route, where junctions are seeded at t=0 by random insertion rather than emerging
+    where three ends meet, and the cycle spectrum inherits that.  They are a
+    measurement of what htpolynet builds this way, not of polycyanurate.
+  - **Under the three-body reaction the same-molecule case aborts rather than
+    declines.**  `makes_shortcircuit` opens with `assert i_resNum != j_resNum`
+    (topocoord.py:1299), and two cyanate arms of one dicyanate are the *same*
+    residue, so routing that pair through `bondtest` raises instead of rejecting.
+    The triple search must exclude it **before** the pairwise test, not rely on it.
+  - **And the right criterion is a distance, not a same-residue veto** (study,
+    section 5).  Two bridge positions on one triazine sit at O...O = 4.60 +/- 0.10 A
+    (n = 2814).  Bisphenol intramolecular O...O over ~11,000 conformers of all eight
+    bridges: means 9.31-9.80 A, closest approach anywhere 5.93 A (a sulfone) -- still
+    1.3 A short, so the 14-ring is geometrically inaccessible to these monomers and a
+    blanket veto would be doing no work.  A shorter-span diol *could* reach 4.6 A, and
+    there the exclusion matters.  So gate on whether the two arms' oxygens can span
+    the junction's bridge separation, which is chemistry-independent and does real
+    work in the case where the loop is actually possible.
+
+  **Where the filters have to live.**  Not only in the pairwise search.  The
+  single-step annealer chooses a whole connectivity at once, so these become
+  constraints on its move set (reject the move, or price it in the cost), and the
+  three-body search needs them as constraints on triple selection.  A filter
+  expressed only as a post-hoc reject in `bondtest` will not transfer to either.
+  Factor them as predicates over (candidate, current topology) that all three callers
+  share.
+
+  **Reporting.**  `bondtest` outcomes are already counted per `BTRC` code and logged;
+  extend that enum rather than inventing a parallel mechanism, and log the
+  per-reason histogram at each iteration.  A filter that silently removes half the
+  candidates is worse than no filter.
+
+- **A three-body cure reaction, for the real cyanate-ester chemistry.**  Asked for by
+  Cameron 2026-09-21.  Cyanate esters cure by *cyclotrimerization*: three -O-C#N
+  groups combine into one 1,3,5-triazine ring, an addition with no atom lost.
+  htpolynet cannot express that today -- a reaction forms one bond between two
+  reactants -- so example 6 and the study's whole bridge series use a surrogate: a
+  pre-formed TAZ triazine monomer plus aryl-ether bonds (A2 + B3), with
+  `postcure_repair: triazine_to_cyanate_cap` dismantling the rings that never
+  completed back into -OCN caps.
+
+  **Why it is worth doing.**  The surrogate is wrong in ways that cost real work:
+  - Triazine rings exist before cure, so crosslink junctions are present at zero
+    conversion, and the gel point of the model is not the gel point of the chemistry.
+  - Incomplete rings are an artifact with no chemical counterpart, and the repair
+    that cleans them up is where the +/-0.24 e charge bug lived (fixed in 2.9.0).
+    With real trimerization an unreacted group simply stays -OCN, correct by
+    construction, and repair is not needed at all for new builds.
+  - Conversion becomes directly what the literature reports.  Today a bond conversion
+    has to be mapped to OCN conversion (`chi_OCN ~ chi_bond^3`, exactly zero below f
+    iterations -- see the memory note); with trimerization, one reaction event
+    consumes three OCN groups and `chi_OCN` is measured, not inferred.
+
+  **What already generalizes.**  `_yield_bonds_as_df` builds its bonds through a
+  per-reactant `resid_mapper`, so template *building* is not limited to two
+  reactants; `Molecule.generate` merges however many reactants it is given; a bond
+  record is a pair of atoms, which stays true for a ring of three bonds.
+
+  **The hard part, and the central new code.**  Per-bond template splicing cannot
+  form a ring.  `map_from_templates` matches each new bond by its local context, but
+  in the trimer template all three ring bonds exist, while the instance, partway
+  through the batch, has only some of them -- so the template's bystanders cannot
+  match the instance's, in either direction.  A ring needs a **product-wide splice**:
+  map every atom of the three participating residues from the trimer template at
+  once -- types, charges, and all angles, dihedrals and 1-4 pairs involving the new
+  ring -- rather than three independent per-bond splices.  Treat that as a new
+  function beside `map_from_templates`, not a modification of it; CURE's pairwise
+  path must keep working unchanged.
+
+  **Plan.**
+  1. *Reaction model.*  Let a cure reaction declare three reactants and three bonds.
+     Generalize `prepare_new_bonds`, whose residue-offset arithmetic is written for
+     exactly two reactants, and the `len(R.reactants) == 2` guards.  Symmetry
+     expansion needs care but is bounded: three copies of a dicyanate with two
+     equivalent sites give four distinct site combinations, not eight.
+  2. *The trimer template.*  One product per site combination, about 120 atoms for a
+     real dicyanate: a one-time AM1-BCC cost of tens of minutes, then cached.  Ring
+     closure is the question.  Preferred: build it as today by merging and placing the
+     three pieces, then close the third bond under a type-6 restraint with the
+     existing attenuation ladder before parameterizing -- the drag machinery already
+     does exactly this.  Fallback: declare the trimer from SMILES as a
+     `count: 0` constituent, which sidesteps the geometry but needs a way to name
+     residues inside one generated molecule, which htpolynet has no syntax for.
+  3. *Triple search.*  Enumerate candidate triples from the linkcell -- pairs within
+     the radius, then triangles among them -- score by the sum of the three
+     distances, and choose a disjoint set.  Greedy is the simple version; the
+     set-packing problem is close enough to the single-step annealer above that the
+     two should share code if both get built.  Forbid two groups of the same molecule
+     in one ring, as the single-step entry forbids intramolecular loops.
+  4. *Ring closure in the system.*  Three sites have to converge, which is strictly
+     harder than bringing two together.  Restrain all three pairs, walk them in with
+     the drag ladder, then form the ring in one batch and relax.
+  5. *Accounting and checks.*  Conversion counted in OCN groups consumed, three per
+     event.  `check_iterations_vs_functionality` assumes a residue carries its own
+     crosslink sites; junctions now form in situ from three molecules, so its
+     functionality model needs rework rather than a patch.  The per-molecule charge
+     check applies unchanged and is worth watching, since a ring closure changes
+     types and charges on three residues at once.
+  6. *Docs, example, validation.*  A new shipped example, or an ex6 variant, built
+     both ways: surrogate versus true trimerization at matched conversion, comparing
+     density, Tg, and the fragment and junction statistics, against the study's BADCy
+     results.  Builds belong to htpolynet-sweep.
+
+  **Risks.**  Ring closure failing in a dense box is the likely one, and the
+  three-way convergence has no precedent in the code.  Beyond that: template cost if
+  a system has several distinct cyanate monomers (one trimer template per
+  combination), and the fact that changing conversion semantics breaks comparability
+  with every existing cyanate build, which is a documentation problem as much as a
+  code one.  Out of scope: the dimer and oxazoline intermediates real cyanate cure
+  passes through.
+
+- **Single-step crosslinking (the Khare method), as an alternative to CURE, not a
+  replacement.**  Agreed with Cameron 2026-09-21.  All bonds are chosen at once by
+  combinatorial optimization on one static snapshot, before any bond exists, so
+  conversion is 100% by construction; the network is then relaxed into place by one
+  restraint-strengthening ladder applied to every bond simultaneously.  CURE stays
+  exactly as it is and remains the default.
+
+  **Sources.**  literature's spec, with every parameter attributed to the paper it
+  was read from, is
+  `~/.local/state/fleet/drops/literature-khare-crosslink-algorithm-20260921.md`.
+  The load-bearing ones: `Khare1993Generation` (origin; the open-TSP framing),
+  `Lin2009Molecular` (the only complete annealing parameter set, and the viability
+  gate), `Khare2012Directed` (the restraint ladder with all k and b0),
+  `Jang2015Comparison` (Cameron's own; the acceptance formula, and the only
+  head-to-head against multi-step).
+
+  **The method, as specified.**
+  - *Stage 1, connectivity by simulated annealing.*  Cost is the total bond length
+    over all chosen pairs; the "temperature" is a **length**, starting at 2.5 A;
+    accept if the cost drops, else with `exp(-dL/L_C)`; multiply L_C by 0.95 whenever
+    attempted moves reach 100x or accepted moves 10x the number of reactive pairs.
+    The move changes only two bonds, so a trial costs O(1) -- that is what makes it
+    cheap (under 15 min CPU in Lin 2009).  Intramolecular loops are forbidden.
+  - *The viability gate, and its loop.*  Annealing returns a sequence, not short
+    bonds: the target C-N bond is 1.364 A, van der Waals approach about 3.4 A, and
+    most chosen pairs start much further apart.  So before any bond is created, two
+    50 ps NVT runs at 300 K under harmonic distance restraints at 8 A then 3 A, then
+    a re-scan requiring every pair under 4 A, and **on failure, re-anneal**.  Lin
+    2009 needed up to three passes for their nanocomposite.  This loop is the
+    difference between a method that works and one that explodes.
+  - *Stage 2, directed diffusion.*  Ten stages of 20 ps NVT at 703 K with
+    `E = k(b-b0)^2`, k in kcal/mol/A^2 and b0 in A: (1,10) (2,9) (4,8) (8,7) (16,6)
+    (32,5) (64,4) (128,3) (256,2) (332.7,1.458).  k doubles each stage; the last is
+    the GAFF C-N bond itself.  Then the topology and charges are updated, sacrificial
+    H's deleted, and MD run for 4 ns at more than 150 K above Tg.
+
+  **Decisions taken (Cameron, 2026-09-21).**
+  1. **Objective:** sum of lengths by default, as the better-documented choice, with
+     sum of squares available as a config option.  `Lin2009Molecular` and
+     `Jang2015Comparison` use lengths, `Khare2021Atomistic` uses squares, and no
+     paper reconciles the two.
+  2. **Encoding:** a capacitated matching with a partner-swap move, rather than a
+     literal TSP path.  A path whose consecutive pairs are all bonds gives every
+     interior site two bonds -- right for a linear chain, wrong for an epoxy carbon
+     that forms one.  htpolynet already knows each site's functionality from `z`, so
+     the matching formulation handles arbitrary functionality.
+
+     **This is our design decision, not a reading of Khare.**  Lin & Khare 2009
+     (journal pp. 4320-4321) name the problem and never state the answer: they
+     extended the polystyrene approach "to incorporate the modifications required to
+     account for the complexities (e.g., **the number of connections**) of the
+     unreacted epoxy monomer, cross-linker, and POSS molecules" -- and what those
+     modifications were appears nowhere.  Their prose points both ways ("sequence of
+     bonds between randomly picked reacting site pairs" reads as a matching, "a path
+     ... that connects all of the potential reacting sites" as a Hamiltonian path),
+     but the move settles it: "only the bonds at the two end points of the selected
+     path segment get altered" is 2-opt segment reversal on a path, which on a
+     matching would change every pair in the segment.  In Khare 1993 there was no
+     tension, because polystyrene is linear and an interior monomer really is
+     bivalent.  The efficiency argument survives the change: swapping the partners of
+     two sites also alters exactly two bonds, so the O(1) delta that makes the
+     annealing schedule affordable is kept.  Credit Khare for the method and say
+     plainly that the network adaptation is ours.
+  3. **Ladder:** configurable, with the published schedules shipped as named presets.
+     **The 2018 SI has since landed** (literature, 2026-09-21) and the 12-stage
+     schedule is a different *shape*, not a longer version of the 10-stage one -- so
+     they are two presets, and neither may be derived from the other.  Which one
+     should be the default is now **an open question for Cameron**: the 10-stage 2012
+     table was chosen when it was the only complete one, but the 12-stage schedule is
+     the one used in the papers that carry the validation (`Khare2018Quantitative`,
+     `Khare2021Atomistic`) and the only one with its full run conditions published.
+
+     *2012, `Khare2012Directed`, ten 20 ps NVT stages at 703 K:* k doubles each stage
+     while b0 walks down with it -- (1,10) (2,9) (4,8) (8,7) (16,6) (32,5) (64,4)
+     (128,3) (256,2) (332.7,1.458).
+
+     *2018 SI Table S1, twelve stages at 700 K, 10.13 MPa, 37.5 ps each:* two phases
+     rather than one ramp.  Stages 1-5 pull b0 in from 15 A to 3 A at almost constant,
+     very weak k; stages 6-11 hold b0 at 1.5 A and ramp k over three decades; stage 12
+     switches to the real GAFF bond.
+
+         stage  1       2      3     4     5     6    7    8   9   10   11   12
+         k      0.0625  0.125  0.25  0.25  0.25  0.25 0.5  1   5   25   125  333.27
+         b0     15      12     9     6     3     1.5  1.5  1.5 1.5 1.5  1.5  1.458
+
+     Final k is 333.27 in the SI and 332.7 in the 2012 figure for the same bond; one
+     is a transposition or a force-field version difference.  Do not read their near
+     agreement as confirmation of either.
+  4. **Naming:** the config block is `single_step:`, not a person's name; the docs
+     credit Khare and cite the papers.
+
+  **The detail that is in no paper, and would otherwise have been found by failure.**
+  The 2018 SI states that during directed diffusion the **pairwise nonbonded
+  interaction between each connecting pair is switched off**: "Since Van der Waals
+  forces would ordinarily limit the distance between the terminal carbon atom of Epon
+  1001F and the nitrogen atom of 4,4'-DDS to no less than 3.3 A, pairwise interactions
+  between these connecting atoms are excluded."  Without that, b0 = 1.5 A is simply
+  unreachable and the ladder stalls against a wall it cannot cross.  In GROMACS terms
+  this is an `[ exclusions ]` entry per candidate pair, added for the duration of the
+  ladder and removed when the real bond forms.  **This applies to CURE's drag stage
+  too**, which pulls pairs together under type-6 restraints with vdW fully on -- which
+  is very likely what `CURE.drag.limit` exists to work around.  Worth trying there
+  once the mechanism exists.
+
+  **Two things the SI settles, one of which matches htpolynet already.**
+  - *Objective:* sum of the **squares** -- "minimizing the sum of the squares of the
+    individual distances of each of the connections", average connection length going
+    from ~70 A to ~10 A.  So squares is the Khare line and sum-of-lengths is Lin 2009
+    / Jang 2015.  Our default stays lengths (decision 1), but it is now a real fork
+    between two published choices rather than an unresolved ambiguity, and the config
+    option must be documented as such.
+  - *Loop prevention:* "allowing only a single connection between a given pair of Epon
+    1001F and 4,4'-DDS molecules".  That is **exactly what htpolynet's
+    `makes_shortcircuit` already enforces**, via the deliberately stale `molecule`
+    attribute -- see the filtering entry above.  Nothing to build.
+
+  **Their topology transformation, for contrast with ours.**  Delete one H from each
+  terminal epoxy carbon and both from each amine N; **recompute partial charges near
+  the new bonds with AM1-BCC**; fix angles, dihedrals and impropers for GAFF
+  consistency; then relax 10 ns at 820 K and 5 MPa.  htpolynet does this differently
+  and, arguably, better: charges and types come from a pre-parameterized product
+  template rather than an in-situ recomputation, which is reproducible and cached.
+  Worth saying in the docs that this is a deliberate difference from the published
+  method, not an oversight.
+
+  **An acceptance test to lift directly.**  Figure S4 of the 2018 SI shows the epoxy
+  monomer end-to-end distance distribution **essentially unchanged before and after
+  crosslinking** -- their own check that the restraint ladder does not unphysically
+  stretch molecules.  It is cheap, it tests the thing most likely to go wrong, and it
+  can be computed for CURE builds too as a baseline.  Make it part of the acceptance
+  criteria alongside the Jang comparison.
+
+  **What it reuses.**  Templates, box construction, densification and precure
+  unchanged; reactive-site enumeration from the same `reactions:` declarations that
+  CURE uses, minus the radius test, so bonds get the same template parameters;
+  type-6 restraints between not-yet-bonded pairs (`TopoCoord.add_restraints`), which
+  is the same mechanism as CURE's drag; batch bond formation through
+  `update_topology_and_coordinates`, which already forms hundreds of bonds per CURE
+  iteration; and the whole postcure path.  The second-shell templates added in 2.9.0
+  matter here: at 100% conversion every multi-site residue ends fully substituted,
+  which is exactly the context they cover.
+
+  **What it needs that does not exist.**
+  - `src/htpolynet/singlestep/anneal.py`: cost, move set, acceptance, schedule, with
+    no MD in it, so it can be tested on a lattice with a known optimum.
+  - A controller mirroring `CureController`: the viability-gate loop, the restraint
+    ladder, its own restart state beside `cure_state.yaml`.
+  - Restraint parameters set explicitly per stage.  `attenuate_bond_parameters`
+    interpolates from each bond's initial distance toward equilibrium; this method
+    prescribes (k, b0) per stage for every bond alike.
+  - A `single_step:` schema section, and a `do_crosslink` dispatch in the workflow
+    that runs either this or CURE.  `do_cure` is not touched.
+  - One fix: `check_iterations_vs_functionality` warns when iterations < site count,
+    which is meaningless at 100% conversion in a single step.  Skip it there.
+
+  **Validation, and the result to design against.**  `Jang2015Comparison` built
+  chemically and stoichiometrically identical systems both ways: thermal and
+  mechanical properties and the N-to-N contour length distribution were insensitive
+  to the choice, but the fragment molecular-weight distribution after cutting each
+  crosslinker was **not** -- single-step gave fewer, larger fragments.  The two
+  methods build qualitatively different networks that agree on the properties usually
+  reported.  So the acceptance test is example 3 (DGEBA/PACM) built both ways,
+  comparing density, thermal and mechanical properties, N-to-N contour length, and
+  that fragment distribution.
+
+  **But do not treat the fragment result as a target to hit.**  Because the papers
+  never state their network adaptation (see decision 2), that difference belongs to
+  whatever connectivity rule their implementation used, not to "single-step" as a
+  class.  A capacitated matching may not reproduce it, and would not be wrong for
+  failing to.  Read it as the reason to *measure* the fragment distribution both ways
+  rather than assume the networks are interchangeable; agreement on density, thermal
+  and mechanical properties is the part worth requiring.  Builds belong to htpolynet-sweep.  The per-molecule charge check applies
+  unchanged and is worth watching: this forms every bond in one batch.
+
 - **Chain-growth cure leaves whole chains charged.**  The v2.10.0 sweep's new
   molecule-charge check found example 1's polystyrene warning: 7 of 49 chains
   over 0.01 e, the largest -0.040 e on the longest (1410-atom) chain, with the
@@ -1324,3 +1736,17 @@ Coverage as of the last measurement: **38.8%** overall.
   thioether, sulfone, dicyclopentadiene. A homologous series would
   exercise the repair stage across chemistries and give the tutorials a
   structure-property story.
+
+
+- **A ring-closing ladder stops around 0.22 nm, not at its 0.15 nm target.**
+  The closure restraints pull three cyanate groups together before any ring bond
+  exists, and they consistently stall at ~0.225 nm regardless of how far apart
+  they started -- in the isolated trimer template too, so it is not crowding by
+  the surrounding system.  The cause is that the groups still carry their
+  sp-hybridized C#N parameters while being pulled, and a linear triple bond
+  resists closing the angle a triazine needs; no force constant fixes that.  It
+  is benign today: the bonds are formed at that length, the template splice
+  replaces the types, and the relax step brings them to 1.35 A, which every
+  build has confirmed.  The warning threshold (twice the target) has never
+  fired.  If it ever does, the fix is to attenuate the C#N bonded parameters
+  along the closure ladder rather than to pull harder.

{htpolynet-2.10.3 → htpolynet-2.11.0}/docs/source/htpolynetpackage.rst

@@ -60,6 +60,11 @@ htpolynet.core
    :undoc-members:
    :show-inheritance:
 
+.. automodule:: htpolynet.core.productsplice
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 .. automodule:: htpolynet.core.projectfilesystem
    :members:
    :undoc-members:
@@ -121,6 +126,16 @@ htpolynet.cure
    :undoc-members:
    :show-inheritance:
 
+.. automodule:: htpolynet.cure.ringcontroller
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: htpolynet.cure.triplesearch
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 htpolynet.external
 ------------------
 
@@ -177,6 +192,11 @@ htpolynet.geometry
    :undoc-members:
    :show-inheritance:
 
+.. automodule:: htpolynet.geometry.placement
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 .. automodule:: htpolynet.geometry.ring
    :members:
    :undoc-members: