Add CLI entry-point for Boresch ghost atom modifications.

Author: lohedges

README.md

@@ -149,6 +149,22 @@ can be controlled via the `--null-energy` option. The number of neighbours shoul
 be chosen as a trade off between accuracy and computational cost. A value of around
 20% of the number of replicas has been found to be a good starting point.
 
+## Ghost atom modifications
+
+We support the modification of ghost atom bonded terms to avoid spurious coupling
+to the physical system using the approach described in [this](https://pubs.acs.org/doi/10.1021/acs.jctc.0c01328) paper.
+These are enabled by default, but can be disabled using the ``--no-ghost-modifications``
+option. Alternatively, we also provide the `ghostly` command-line tool that can
+be used to apply the modifications to perturbable system without running a simulation,
+e.g. for use elsewhere. This can be used via:
+
+```bash
+ghostly perturbable_system.bss --output perturbable_system_ghosted.bss --log-level debug
+```
+
+(Here the log level is set to debug to provide more information on the modifications
+that are applied.)
+
 ## Note for SOMD1 users
 
 For existing users of `somd1`, it's possible to generate input for `somd2` by passing

pyproject.toml

@@ -20,7 +20,8 @@ dynamic = ["version"]
 license-files = ["LICENSE"]
 
 [project.scripts]
-somd2 = "somd2.app:cli"
+somd2 = "somd2.app:somd2"
+ghostly = "somd2.app:ghostly"
 
 [project.urls]
 repository = "https://github.com/OpenBioSim/somd2"

src/somd2/app/__init__.py

@@ -28,7 +28,8 @@
 .. autosummary::
     :toctree: generated/
 
-    cli
+    somd2
+    ghostly
 """
 
-from .run import *
+from ._cli import *

src/somd2/app/run.py src/somd2/app/_cli.pysrc/somd2/app/run.py renamed to src/somd2/app/_cli.py

@@ -20,17 +20,11 @@
 #####################################################################
 
 """
-The somd2 command line program.
-
-Usage:
-    To get the help for this program and list all of the
-    arguments (with defaults) use:
-
-    somd2 --help
+SOMD2 command line interface.
 """
 
 
-def cli():
+def somd2():
     """
     SOMD2: Command line interface.
     """
@@ -91,3 +85,75 @@ def cli():
     except Exception as e:
         _logger.error(f"An error occurred during the simulation: {e}")
         exit(1)
+
+
+def ghostly():
+    """
+    SOMD2: Command line interface.
+    """
+
+    import argparse
+    import sys
+
+    import sire as sr
+
+    from somd2 import _logger
+    from somd2._utils._ghosts import boresch
+
+    parser = argparse.ArgumentParser(
+        description="Ghostly: ghost atom bonded term modifications"
+    )
+
+    parser.add_argument(
+        "system",
+        type=str,
+        help="Path to a stream file containing the perturbable system.",
+    )
+
+    parser.add_argument(
+        "--output",
+        type=str,
+        help="File prefix for the output file.",
+        default="ghostly",
+        required=False,
+    )
+
+    parser.add_argument(
+        "--log-level",
+        type=str,
+        help="Log level for the logger.",
+        default="info",
+        choices=["debug", "info", "warning", "error", "critical"],
+        required=False,
+    )
+
+    # Parse the arguments.
+    args = parser.parse_args()
+
+    # Set the logger level.
+    _logger.remove()
+    _logger.add(sys.stderr, level=args.log_level.upper(), enqueue=True)
+
+    # Try to load the system.
+    try:
+        system = sr.stream.load(args.system)
+        system = sr.morph.link_to_reference(system)
+    except Exception as e:
+        _logger.error(f"An error occurred while loading the system: {e}")
+        exit(1)
+
+    # Try to apply the modifications.
+    try:
+        system = boresch(system)
+    except Exception as e:
+        _logger.error(
+            f"An error occurred while applying the ghost atom modifications: {e}"
+        )
+        exit(1)
+
+    # Try to save the system.
+    try:
+        sr.stream.save(system, f"{args.output}.bss")
+    except Exception as e:
+        _logger.error(f"An error occurred while saving the system: {e}")
+        exit(1)