BREAKING CHANGE: Parameterize tool (#361)

Requires reinstall because it changes cli names.

* everything except for gro handling

* black

* update docs

* typing

* feat: let del_atom deal with multiple atoms at a time.

* black

* single del_atom call

* typo

* add gro treatment (untested)

* bug fix

* fix gro handling

* new black

* minor filename fix

---------

Co-authored-by: Eric Hartmann <hartmaec@rh05659.villa-bosch.de>
Co-authored-by: Kai Riedmiller <kai.riedmiller@web.de>

Author: 3 people

guide/references/cmd_ref.qmd

@@ -24,7 +24,7 @@ The prefered method of starting a KIMMDY run is via the command line, though [Py
 This module builds or restores the example directory in the package.
 
 ```{python}
-!kimmdy-remove-hydrogen --help
+!kimmdy-modify-top --help
 ```
 
 ## Examples

setup.cfg

@@ -77,4 +77,4 @@ console_scripts =
     kimmdy = kimmdy.cmd:entry_point_kimmdy
     kimmdy-analysis = kimmdy.analysis:entry_point_analysis
     kimmdy-build-examples = kimmdy.tools:entry_point_build_examples
-    kimmdy-remove-hydrogen = kimmdy.tools:entry_point_remove_hydrogen
+    kimmdy-modify-top = kimmdy.tools:entry_point_modify_top

src/kimmdy/analysis.py

@@ -1,6 +1,7 @@
 """Analysis tools for KIMMDY runs.
 For command line usage, run `kimmdy-analysis -h`.
 """
+
 from typing import Union
 from pathlib import Path
 import MDAnalysis as mda

src/kimmdy/cmd.py

@@ -2,6 +2,7 @@
 Functions for starting KIMMDY either from python or the command line.
 Other entry points such as `kimmdy-analysis` also live here.
 """
+
 import argparse
 from os import chmod
 from pathlib import Path
@@ -107,7 +108,7 @@ def get_cmdline_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         description="Welcome to KIMMDY. `kimmdy` runs KIMMDY, further tools "
         "are available as `kimmdy-...` commands. These are `-analysis`, "
-        "`-remove-hydrogen` and `-build-examples`. Access their help with "
+        "`-modify-top` and `-build-examples`. Access their help with "
         "`kimmdy-... -h.`"
     )
     parser.add_argument(

src/kimmdy/config.py

@@ -2,6 +2,7 @@
 Read and validate kimmdy.yml configuration files
 and package into a parsed format for internal use.
 """
+
 from __future__ import annotations
 import shutil
 from pprint import pformat, pprint

src/kimmdy/constants.py

@@ -2,7 +2,6 @@
 Comstants used throughout KIMMDY
 """
 
-
 ATOM_ID_FIELDS = {
     "atoms": [0, 5],  # atomnr, chargegroup
     "bonds": [0, 1],

src/kimmdy/kmc.py

@@ -7,6 +7,7 @@
 because of the fundamental premise of chemical kinetics
 and because we have one reactant molecule
 """
+
 from typing import Optional
 import logging
 import numpy as np

src/kimmdy/parsing.py

@@ -1,6 +1,7 @@
 """
 All read_<...> and write_<...> functions.
 """
+
 import os
 import logging
 import json

src/kimmdy/recipe.py

@@ -1,5 +1,6 @@
 """Contains the Reaction Recipe, RecipeStep and RecipeCollection.
 """
+
 from __future__ import annotations
 from typing import TYPE_CHECKING, Callable, Optional
 

src/kimmdy/runmanager.py

@@ -4,6 +4,7 @@
 It manages the queue of tasks, communicates with the
 rest of the program and keeps track of global state.
 """
+
 from __future__ import annotations
 import logging
 from pathlib import Path

src/kimmdy/schema.py

@@ -10,6 +10,7 @@
     - type
     - required
 """
+
 import json
 import importlib.resources as pkg_resources
 import logging

src/kimmdy/tools.py

@@ -5,10 +5,10 @@
 from pathlib import Path
 import shutil
 import argparse
+from typing import Optional
 
 from kimmdy.topology.topology import Topology
 from kimmdy.parsing import read_top, write_top
-from kimmdy.utils import run_gmx, run_shell_cmd
 from kimmdy.plugins import parameterization_plugins
 from kimmdy.plugins import discover_plugins
 
@@ -83,163 +83,149 @@ def entry_point_build_examples():
     build_examples(args.restore)
 
 
-def remove_hydrogen(
-    gro: str,
-    top: str,
-    nr: str,
+def modify_top(
+    top_str: str,
+    out_str: str,
     parameterize: bool,
-    equilibrate: bool,
-    gmx_mdrun_flags: str = "",
+    removeH: Optional[list[int]],
+    gro_str: Optional[str],
 ):
-    """Remove one hydrogen from a gro and top file to create a radical.
+    """Modify topology in various ways.
 
     Parameters
     ----------
-    gro
-        Path to GROMACS gro file
-    top
+    top_path
         Path to GROMACS top file
-    nr
-        Atom number as indicated in the GROMACS gro and top file
+    out_path
+        Output topology file name, stem also used for gro
     parameterize
-        Parameterize topology with grappa after removing hydrogen.
-    equilibrate
-        Do a minimization and equilibration with GROMACS. Uses mdp files from kimmdy assets.
+        Parameterize topology with grappa after removing hydrogen
+    removeH
+        Remove one or more hydrogens by atom nrs in the top file.
+        One based.
+    gro_path
+        GROMACS gro input file. Updates structure when deleting H.
+        Output named like top output.
     """
-    gro_path = Path(gro)
-    top_path = Path(top)
 
-    topology = Topology(read_top(top_path))
+    top_path = Path(top_str)
+    out_path = top_path.with_name(out_str).with_suffix(".top")
+    update_map = {}
+    gro_out = None
+
+    if gro_str:
+        if removeH:
+            gro_path = Path(gro_str)
+            gro_out = gro_path.with_stem(out_path.stem)
+            while gro_out.exists():
+                gro_out = gro_out.with_stem(gro_out.stem + "_mod")
+
+    print(
+        "Changing topology\n"
+        f"top: \t\t\t{top_str}\n"
+        f"output: \t\t{out_str}\n"
+        f"parameterize: \t\t{parameterize}\n"
+        f"remove hydrogen: \t{removeH}\n"
+        f"optional gro: \t\t{gro_str}\n"
+        f"gro output: \t\t{gro_out}\n"
+    )
 
-    ## check for input validity
-    assert (atom_type := topology.atoms[nr].type).startswith(
-        "H"
-    ), f"Wrong atom type {atom_type} with nr {nr} for remove hydrogen, should start with 'H'"
+    top = Topology(read_top(top_path))
+
+    # remove hydrogen
+    if removeH:
+        broken_idxs = []
+        # check for input validity
+        for i, nr in enumerate(removeH):
+            if not (atom_type := top.atoms[str(nr)].type).startswith("H"):
+                print(
+                    f"Wrong atom type {atom_type} with nr {nr} for remove hydrogen, should start with 'H'."
+                )
+                broken_idxs.append(i)
+                continue
+        for broken_idx in sorted(broken_idxs, reverse=True):
+            removeH.pop(broken_idx)
 
-    ## deal with top file, order is important here
-    # [heavy_nr] = topology.atoms[nr].bound_to_nrs
+        top.del_atom([str(nr) for nr in removeH], parameterize=parameterize)
 
     # parameterize with grappa
     if parameterize:
+        # load grappa
         discover_plugins()
-
         if "grappa" in parameterization_plugins.keys():
-            topology.parametrizer = parameterization_plugins["grappa"]()
-
+            top.parametrizer = parameterization_plugins["grappa"]()
         else:
             raise KeyError(
                 "No grappa in parameterization plugins. Can't continue to parameterize molecule"
             )
+        # require parameterization when writing topology to dict
+        top.needs_parameterization = True
+
+    # write top file
+    write_top(top.to_dict(), out_path)
+
+    # deal with gro file
+    if gro_str:
+        if removeH:
+            with open(gro_path, "r") as f:
+                gro_raw = f.readlines()
+
+            with open(gro_out, "w") as f:
+                f.write(gro_raw[0])
+                f.write(f"   {str(int(gro_raw[1])-len(removeH))}\n")
+
+                for i, line in enumerate(gro_raw[2:]):
+                    if i + 1 in removeH:
+                        continue
+                    f.write(line)
+        else:
+            print(
+                "Gro file supplied but no action requested that requires changes to it."
+            )
 
-    update_map = topology.del_atom(nr, parameterize=parameterize)
-
-    ## write top file
-    top_stem = top_path.stem
-    top_outpath = top_path.with_stem(top_stem + f"_d{nr}")
-    write_top(topology.to_dict(), top_outpath)
-
-    ## deal with gro file
-    with open(gro_path, "r") as f:
-        gro_raw = f.readlines()
-
-    if len(gro_raw[3].split()) > 6:
-        print("gro file likely contains velocities. These will be discarded.")
-
-    gro_stem = gro_path.stem
-    gro_outpath = gro_path.with_stem(gro_stem + f"_d{nr}")
-    with open(gro_outpath, "w") as f:
-        f.write(gro_raw[0])
-        f.write(f"   {str(int(gro_raw[1])-1)}\n")
-        for line in gro_raw[2:-1]:
-            linesplit = line.split()
-            if val := update_map.get(linesplit[2]):
-                linesplit[2] = val
-            else:
-                continue
-            f.write("{:>8s}   {:>4s} {:>4s} {:>7s} {:>7s} {:>7s}\n".format(*linesplit))
-            # format not exactly as defined by GROMACS but should be good enough
-        f.write(gro_raw[-1])
-
-    ## minimize and equilibrate system using GROMACS
-    if equilibrate:
-        cwd = top_outpath.parent
-        run_shell_cmd(
-            f"cp {str(Path(__file__).parents[2] / 'tests'/'test_files'/'assets'/'md'/'*')} .",
-            cwd=cwd,
-        )
-        run_gmx(
-            f"gmx editconf -f {gro_outpath.name} -o {gro_outpath.stem}_box.gro -c -d 1.0 -bt dodecahedron",
-            cwd=cwd,
-        )
-        run_gmx(
-            f"gmx solvate -cp {gro_outpath.stem}_box.gro -p {top_outpath.name} -o {gro_outpath.stem}_solv.gro",
-            cwd=cwd,
-        )
-        run_gmx(
-            f"gmx grompp -f ions.mdp -c {gro_outpath.stem}_solv.gro -p {top_outpath.name} -o {gro_outpath.stem}_genion.tpr",
-            cwd=cwd,
-        )
-        run_gmx(
-            f"echo 'SOL' | gmx genion -s {gro_outpath.stem}_genion.tpr -p {top_outpath.name} -o {gro_outpath.stem}_ion.gro -conc 0.15 -neutral",
-            cwd=cwd,
-        )
-        run_gmx(
-            f"gmx grompp -f minim.mdp -c {gro_outpath.stem}_ion.gro -p {top_outpath.name} -o {gro_outpath.stem}_min.tpr -maxwarn 2",
-            cwd=cwd,
-        )
-        run_gmx(f"gmx mdrun -deffnm {gro_outpath.stem}_min" + gmx_mdrun_flags, cwd=cwd)
-        run_gmx(
-            f"gmx grompp -f nvt.mdp -c {gro_outpath.stem}_min.gro -p {top_outpath.name} -o {gro_outpath.stem}_nvt.tpr -maxwarn 2",
-            cwd=cwd,
-        )
-        run_gmx(f"gmx mdrun -deffnm {gro_outpath.stem}_nvt" + gmx_mdrun_flags, cwd=cwd)
-        run_gmx(
-            f"gmx grompp -f npt.mdp -c {gro_outpath.stem}_nvt.gro -p {top_outpath.name} -o {gro_outpath.stem}_npt.tpr -maxwarn 2",
-            cwd=cwd,
-        )
-        run_gmx(
-            f"gmx mdrun -v -deffnm {gro_outpath.stem}_npt" + gmx_mdrun_flags, cwd=cwd
-        )
-
-
-def get_remove_hydrogen_cmdline_args() -> argparse.Namespace:
+
+def get_modify_top_cmdline_args() -> argparse.Namespace:
     """
-    parse cmdline args for remove_hydrogen
+    parse cmdline args for modify_top
     """
     parser = argparse.ArgumentParser(
-        description="Welcome to the KIMMDY remove hydrogen module",
+        description="Welcome to the KIMMDY modify top module",
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
-    parser.add_argument("gro", help="GROMACS gro file")
     parser.add_argument("top", help="GROMACS top file")
-    parser.add_argument(
-        "nr", help="Atom number as indicated in the GROMACS gro and top file"
-    )
+    parser.add_argument("out", help="Output top file name")
+
     parser.add_argument(
         "-p",
         "--parameterize",
         action="store_true",
-        help="Parameterize topology with grappa after removing hydrogen.",
+        help="Parameterize topology with grappa.",
         default=False,
     )
     parser.add_argument(
-        "-e",
-        "--equilibrate",
-        action="store_true",
-        help="Do a minimization and equilibration with GROMACS. Uses mdp files from kimmdy assets.",
-        default=False,
+        "-r",
+        "--removeH",
+        help="Remove one or more hydrogens by atom nrs in the top file.",
+        nargs="+",
+        type=int,
+    )
+    parser.add_argument(
+        "-c",
+        "--grofile",
+        help="If necessary, also apply actions on gro file to create a compatible gro/top file pair.",
+        type=str,
     )
     return parser.parse_args()
 
 
-def entry_point_remove_hydrogen():
-    """Remove hydrogen by atom nr in a gro and topology file"""
-    args = get_remove_hydrogen_cmdline_args()
+def entry_point_modify_top():
+    """Modify topology file in various ways"""
+    args = get_modify_top_cmdline_args()
 
-    remove_hydrogen(args.gro, args.top, args.nr, args.parameterize, args.equilibrate)
+    modify_top(args.top, args.out, args.parameterize, args.removeH, args.grofile)
 
 
-## dot graphs
+# dot graphs
 def topology_to_edgelist(top: Topology):
     """Convert a topology to a list of edges for a dot graph."""
     ls = []

src/kimmdy/topology/atomic.py

@@ -634,9 +634,9 @@ def from_section(cls, residue, d: dict[str, list[list[str]]]):
         if ls := d.get("dihedrals"):
             for l in ls["content"]:
                 proper = ResidueProperSpec.from_top_line(l)
-                propers[
-                    (proper.atom1, proper.atom2, proper.atom3, proper.atom4)
-                ] = proper
+                propers[(proper.atom1, proper.atom2, proper.atom3, proper.atom4)] = (
+                    proper
+                )
         if ls := d.get("impropers"):
             for l in ls["content"]:
                 improper = ResidueImproperSpec.from_top_line(l)