Merge pull request #9 from OpenBioSim/feature_linearise_ring_break

Author: lohedges

CHANGELOG.md

@@ -5,6 +5,8 @@ Changelog
 -------------------------------------------------------------------------------------
 
 * Please add an item to this CHANGELOG for any new features or bug fixes when creating a PR.
+* Add linear spacer modification for ring-breaking ghost bridges.
+* Remove cross-bond angles spanning ring-making/breaking bonds in the state where the bond is absent.
 
 [2025.2.0](https://github.com/openbiosim/loch/compare/2025.1.0...2025.2.0) - Mar 2026
 -------------------------------------------------------------------------------------

README.md

@@ -23,6 +23,31 @@ differences.
 2) To avoid spurious coupling between the physical and ghost systems, which
 can affect the equilibrium geometry of the physical system.
 
+Ghostly implements many extensions beyond the original modification scheme to
+handle the diversity of perturbations encountered in practice:
+
+- **Anchor selection scoring:** physical anchor atoms are scored to avoid
+  transmuting or bridge atoms, preventing geometrically inconsistent constraints.
+- **Ring and sp2 bridge handling:** angle stiffening is skipped by default for
+  ring and sp2 bridges, where local geometry already constrains the ghost and
+  90° stiffening would introduce significant strain. It can be re-enabled via
+  `--stiffen-ring-bridges` and `--stiffen-sp2-bridges`.
+- **Residual term cleanup:** a post-processing pass removes mixed improper
+  dihedrals and cross-bridge dihedrals missed by the per-bridge junction
+  handlers, as well as angles where a ghost atom is the central atom and both
+  terminal atoms are physical.
+- **Mixed dihedral softening:** surviving mixed ghost/physical dihedrals can
+  be softened via `--soften-anchors` to allow ghost groups to reorient and
+  avoid steric clashes at small λ.
+- **Rotamer stiffening:** `--stiffen-rotamers` replaces rotatable sp3 anchor
+  dihedrals with a stiff single-well cosine to control ghost orientation
+  through flexible bonds.
+- **Ring-breaking perturbations:** adjacent bridges with independent ghost
+  groups retain each other as physical neighbours; angles with a ghost central
+  atom spanning two physical neighbours are replaced by a linear spacer
+  (180°, soft force constant); and angles and dihedrals spanning the
+  ring-making/breaking bond are removed in the state where that bond is absent.
+
 Ghostly is incorporated into the [SOMD2](https://github.com/openbiosim/somd2)
 free-energy perturbation engine.
 

src/ghostly/_cli.py

@@ -205,6 +205,21 @@ def run():
         required=False,
     )
 
+    parser.add_argument(
+        "--linearise-ring-break",
+        action=argparse.BooleanOptionalAction,
+        help="""
+             Apply a linear spacer modification to ghost atoms that bridge two
+             physical atoms (ring-breaking topology). Instead of removing the
+             P1-G-P2 angle, this sets it to 180 degrees with force constant
+             k-soft and reduces the ghost bond force constants to k-soft.
+             Recommended for ring-breaking and chain-expansion perturbations.
+             Disabled by default as it is experimental.
+             """,
+        default=False,
+        required=False,
+    )
+
     parser.add_argument(
         "--output-prefix",
         type=str,
@@ -369,6 +384,7 @@ def run():
             k_rotamer=k_rotamer.value(),
             stiffen_ring_bridges=args.stiffen_ring_bridges,
             stiffen_sp2_bridges=args.stiffen_sp2_bridges,
+            linearise_ring_break=args.linearise_ring_break,
         )
     except Exception as e:
         logger.error(