abmptools 2.2.0__tar.gz → 2.3.0__tar.gz

{abmptools-2.2.0/abmptools.egg-info → abmptools-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abmptools
-Version: 2.2.0
+Version: 2.3.0
 Summary: Pre/post-processing and analysis toolkit for ABINIT-MP Fragment Molecular Orbital calculations
 Author-email: Koji Okuwaki <koujioku81@gmail.com>
 License-Expression: Apache-2.0
@@ -121,7 +121,7 @@ A Python toolkit for pre-processing, post-processing, and analysis of Fragment M
 
 - **udf2gro**: Convert OCTA UDF files to GROMACS format (`.gro`, `.top`, `.mdp`, `.itp`)
 - **gro2udf**: Convert GROMACS files to OCTA UDF format (supports `--from-top` mode)
-- **udfcharge**: Transfer per-atom partial charges from a single-molecule UDF to every same-named molecule in a bulk UDF
+- **udfcharge**: Transfer per-atom partial charges from a single-molecule UDF to bulk molecules (`transfer`), or restore a neutralized UDF's charges to a target integer formal charge (`restore`)
 
 ### Geometry Optimization (`geomopt`)
 
@@ -314,7 +314,10 @@ python -m abmptools.udf2gro.cli -i system.udf -o output
 python -m abmptools.gro2udf.cli -i system.gro -t system.top -o output.udf
 
 # Transfer charges from a single-molecule UDF to all same-named molecules in a bulk UDF
-python -m abmptools.udfcharge --template mol.udf --bulk bulk.udf --out bulk_charged.udf
+python -m abmptools.udfcharge transfer --template mol.udf --bulk bulk.udf --out bulk_charged.udf
+
+# Restore a neutralized UDF's charges to a target integer formal charge
+python -m abmptools.udfcharge restore --udf mol.udf --formal-charge 12 --out mol_q+12.udf
 
 # Build an amorphous mixture from SMILES (50 ketoprofen molecules, density 0.8 g/cm^3)
 python -m abmptools.amorphous --smiles "OC(=O)C(C)c1cccc(C(=O)c2ccccc2)c1" \

{abmptools-2.2.0 → abmptools-2.3.0}/README.md

@@ -37,7 +37,7 @@ A Python toolkit for pre-processing, post-processing, and analysis of Fragment M
 
 - **udf2gro**: Convert OCTA UDF files to GROMACS format (`.gro`, `.top`, `.mdp`, `.itp`)
 - **gro2udf**: Convert GROMACS files to OCTA UDF format (supports `--from-top` mode)
-- **udfcharge**: Transfer per-atom partial charges from a single-molecule UDF to every same-named molecule in a bulk UDF
+- **udfcharge**: Transfer per-atom partial charges from a single-molecule UDF to bulk molecules (`transfer`), or restore a neutralized UDF's charges to a target integer formal charge (`restore`)
 
 ### Geometry Optimization (`geomopt`)
 
@@ -230,7 +230,10 @@ python -m abmptools.udf2gro.cli -i system.udf -o output
 python -m abmptools.gro2udf.cli -i system.gro -t system.top -o output.udf
 
 # Transfer charges from a single-molecule UDF to all same-named molecules in a bulk UDF
-python -m abmptools.udfcharge --template mol.udf --bulk bulk.udf --out bulk_charged.udf
+python -m abmptools.udfcharge transfer --template mol.udf --bulk bulk.udf --out bulk_charged.udf
+
+# Restore a neutralized UDF's charges to a target integer formal charge
+python -m abmptools.udfcharge restore --udf mol.udf --formal-charge 12 --out mol_q+12.udf
 
 # Build an amorphous mixture from SMILES (50 ketoprofen molecules, density 0.8 g/cm^3)
 python -m abmptools.amorphous --smiles "OC(=O)C(C)c1cccc(C(=O)c2ccccc2)c1" \

{abmptools-2.2.0 → abmptools-2.3.0}/abmptools/hbond/analyzer.py

@@ -140,6 +140,12 @@ class AnalyzerConfig:
     distance_d_max: float = 3.6        # Å, upper edge (Luzar-Chandler cutoff 3.5 + slack)
     distance_bin_width: float = 0.05   # Å
     angle_bin_width: float = 5.0       # deg, used for the 2-D (d, θ) heatmap
+    # Per-molecule 2D structure diagram marking the detected H-bond sites
+    # (red = donor, cyan = acceptor). Requires RDKit; skipped with a warning if
+    # unavailable or if bond-order perception fails. diagram_charge is the net
+    # molecular charge passed to DetermineBondOrders (0 = neutral).
+    do_diagram: bool = True
+    diagram_charge: int = 0
 
     def get_criteria(self) -> HBondCriteria:
         if self.criteria_mode == "luzar-chandler":
@@ -302,6 +308,36 @@ class Analyzer:
                 meta_by_type["ether_O"] = [(s.mol_index, s.acceptor_a) for s in sites]
         return sites_by_type, meta_by_type
 
+    def _auto_groups(self) -> Tuple[List[str], List[str]]:
+        """Auto-detect donor/acceptor group types present in the system.
+
+        Used by ``classify_mode='auto'``. Returns ``(donor_groups,
+        acceptor_groups)`` listing only the functional-group types actually
+        detected (carboxyl / amide / secondary-amide N-H / amine N-H /
+        hydroxyl). ``ether_O`` is NOT auto-listed because there is no reliable
+        ether detector yet (GAFF2 ``os``-tag only); pass ``--acceptor-groups
+        ether_O`` explicitly if needed.
+        """
+        if self.traj is None:
+            self.load()
+        from .functional_groups import detect_hydroxyls
+        donors: List[str] = []
+        acceptors: List[str] = []
+        if self.carboxyls:
+            donors.append("carboxyl")
+            acceptors.append("carboxyl_O")
+        if any(g.from_amide for g in self.amine_donors):
+            donors.append("amide_donor")
+        if any(not g.from_amide for g in self.amine_donors):
+            donors.append("amine_donor")
+        hydroxyls = detect_hydroxyls(self.traj.molecules, mapping=self.mapping)
+        if hydroxyls:
+            donors.append("hydroxyl")
+            acceptors.append("hydroxyl_O")
+        if self.amides:
+            acceptors.append("amide_O")
+        return donors, acceptors
+
     def run(self) -> List[FrameResult]:
         if self.traj is None:
             self.load()
@@ -309,12 +345,28 @@ class Analyzer:
         end = c.record_end if c.record_end >= 0 else self.traj.n_records
         criteria = c.get_criteria()
         mode = (c.classify_mode or "imc").lower()
-        if mode not in {"imc", "generic"}:
+        if mode not in {"imc", "generic", "auto"}:
             raise ValueError(
                 f"Unknown classify_mode={c.classify_mode!r}; "
-                "must be 'imc' or 'generic'"
+                "must be 'imc', 'generic', or 'auto'"
             )
 
+        if mode == "auto":
+            # Detect which functional-group donor/acceptor types are present and
+            # run them through the generic pair-stats path. Explicit
+            # --donor-groups / --acceptor-groups still override the auto picks.
+            auto_donors, auto_acceptors = self._auto_groups()
+            if c.donor_groups is None:
+                c.donor_groups = auto_donors
+            if c.acceptor_groups is None:
+                c.acceptor_groups = auto_acceptors
+            if c.verbose:
+                print(f"  [auto] donor groups   : {c.donor_groups or '(none detected)'}")
+                print(f"  [auto] acceptor groups: {c.acceptor_groups or '(none detected)'}")
+            # Resolve to generic so run()/write_outputs use the generic path.
+            c.classify_mode = "generic"
+            mode = "generic"
+
         donor_groups = c.donor_groups or (
             ["carboxyl"] if mode == "imc" else []
         )
@@ -328,6 +380,9 @@ class Analyzer:
         acceptor_sites_by_type, acceptor_meta_by_type = (
             self._build_acceptor_sites_by_type(acceptor_groups)
         )
+        # Stash detected sites so write_outputs() can render the 2D diagram.
+        self.donor_sites_by_type = donor_sites_by_type
+        self.acceptor_sites_by_type = acceptor_sites_by_type
 
         # IMC mode keeps backward-compat names for hb_cc/hb_ca path
         carb_donors = donor_sites_by_type.get("carboxyl", [])
@@ -654,17 +709,36 @@ class Analyzer:
                 import matplotlib.pyplot as plt
                 recs = [fr.record for fr in self.frame_results]
                 fig, ax = plt.subplots(figsize=(7, 4))
-                ax.plot(recs, [fr.n_dual_mols for fr in self.frame_results],
-                        "o-", color="red", label="dual COOH-COOH mols")
-                ax.plot(recs, [fr.n_chain_mols for fr in self.frame_results],
-                        "D-", color="magenta", label="chain COOH-COOH mols")
-                ax.plot(recs, [fr.n_single_mols for fr in self.frame_results],
-                        "s-", color="blue", label="single COOH-amide mols")
-                ax.plot(recs, [fr.n_free_mols for fr in self.frame_results],
-                        "^-", color="gray", label="free mols")
+                if mode == "imc":
+                    ax.plot(recs, [fr.n_dual_mols for fr in self.frame_results],
+                            "o-", color="red", label="dual COOH-COOH mols")
+                    ax.plot(recs, [fr.n_chain_mols for fr in self.frame_results],
+                            "D-", color="magenta", label="chain COOH-COOH mols")
+                    ax.plot(recs, [fr.n_single_mols for fr in self.frame_results],
+                            "s-", color="blue", label="single COOH-amide mols")
+                    ax.plot(recs, [fr.n_free_mols for fr in self.frame_results],
+                            "^-", color="gray", label="free mols")
+                    ax.set_ylabel("number of molecules")
+                    ax.set_title(f"H-bond classification ({c.criteria_mode})")
+                else:
+                    # generic / auto: one line per donor→acceptor pair type
+                    pair_types = sorted(
+                        {pt for fr in self.frame_results
+                         for pt in fr.hbonds_by_pair_type}
+                    )
+                    for pt in pair_types:
+                        counts = [len(fr.hbonds_by_pair_type.get(pt, []))
+                                  for fr in self.frame_results]
+                        ax.plot(recs, counts, "o-", markersize=3,
+                                label=f"{pt[0]}→{pt[1]}")
+                    if not pair_types:
+                        ax.plot(recs, [0] * len(recs), "o-", color="gray",
+                                label="(no H-bonds detected)")
+                    ax.set_ylabel("number of H-bonds")
+                    ax.set_title(
+                        f"H-bond count per pair type ({c.criteria_mode})"
+                    )
                 ax.set_xlabel("record")
-                ax.set_ylabel("number of molecules")
-                ax.set_title(f"H-bond classification ({c.criteria_mode})")
                 ax.legend()
                 ax.grid(True, alpha=0.3)
                 fig.tight_layout()
@@ -682,6 +756,86 @@ class Analyzer:
         if c.compute_lifetime and len(self.frame_results) >= 2:
             out_paths.update(self._write_lifetime_outputs())
 
+        # Per-molecule 2D structure diagram of the detected H-bond sites
+        if c.do_diagram:
+            out_paths.update(self._write_diagram_outputs())
+
+        return out_paths
+
+    def _write_diagram_outputs(self) -> Dict[str, str]:
+        """Render a 2D structure diagram per molecular species, marking the
+        detected donor (red) / acceptor (cyan) atoms. Requires RDKit; skipped
+        with a warning if unavailable or if a molecule cannot be perceived."""
+        from . import diagram as _dg
+        c = self.config
+        out_paths: Dict[str, str] = {}
+
+        donor_by_type = getattr(self, "donor_sites_by_type", {}) or {}
+        acceptor_by_type = getattr(self, "acceptor_sites_by_type", {}) or {}
+        donors_per_mol: Dict[int, set] = {}
+        acceptors_per_mol: Dict[int, set] = {}
+        donor_types_per_mol: Dict[int, set] = {}
+        acceptor_types_per_mol: Dict[int, set] = {}
+        for dtype, sites in donor_by_type.items():
+            for s in sites:
+                donors_per_mol.setdefault(s.mol_index, set()).add(s.d_local)
+                donor_types_per_mol.setdefault(s.mol_index, set()).add(dtype)
+        for atype, sites in acceptor_by_type.items():
+            for s in sites:
+                acceptors_per_mol.setdefault(s.mol_index, set()).add(s.a_local)
+                acceptor_types_per_mol.setdefault(s.mol_index, set()).add(atype)
+
+        if not donors_per_mol and not acceptors_per_mol:
+            if c.verbose:
+                print("  (diagram skipped: no donor/acceptor atoms detected)")
+            return {}
+
+        rec0 = c.record_start
+        try:
+            frame = self.traj.get_frame(rec0)
+        except Exception:
+            frame = self.traj.get_frame(0)
+
+        # Group molecules into unique species by element signature (robust to
+        # per-atom-unique force-field type names).
+        species: Dict[tuple, int] = {}
+        for mi, topo in enumerate(self.traj.molecules):
+            sig = tuple(_dg.element_from_name(a.atom_name) for a in topo.atoms)
+            species.setdefault(sig, mi)
+        multi = len(species) > 1
+        n_done = 0
+        for sig, mi in species.items():
+            d_atoms = sorted(donors_per_mol.get(mi, set()))
+            a_atoms = sorted(acceptors_per_mol.get(mi, set()))
+            if not d_atoms and not a_atoms:
+                continue
+            topo = self.traj.molecules[mi]
+            coords = frame.positions[mi]
+            mol, reason = _dg.build_mol_from_topology(
+                topo, coords, charge=c.diagram_charge,
+            )
+            if mol is None:
+                print(f"Warning: diagram skipped for {topo.mol_name}: {reason}")
+                continue
+            dnames = ", ".join(sorted(donor_types_per_mol.get(mi, set()))) or "—"
+            anames = ", ".join(sorted(acceptor_types_per_mol.get(mi, set()))) or "—"
+            legend = (f"{topo.mol_name}   red = donor ({dnames})   "
+                      f"cyan = acceptor ({anames})")
+            suffix = f"_diagram_{topo.mol_name}" if multi else "_diagram"
+            png = f"{c.out_prefix}{suffix}.png"
+            svg = f"{c.out_prefix}{suffix}.svg"
+            try:
+                _dg.draw_hbond_diagram(mol, d_atoms, a_atoms, png, svg,
+                                       legend=legend)
+            except Exception as e:  # noqa: BLE001
+                print(f"Warning: diagram render failed for {topo.mol_name}: {e}")
+                continue
+            key = f"diagram_{topo.mol_name}" if multi else "diagram"
+            out_paths[key] = png
+            out_paths[key + "_svg"] = svg
+            n_done += 1
+        if c.verbose and n_done:
+            print(f"  diagram: {n_done} molecular species rendered")
         return out_paths
 
     def _write_distance_outputs(self) -> Dict[str, str]:

{abmptools-2.2.0 → abmptools-2.3.0}/abmptools/hbond/cli.py

@@ -62,9 +62,11 @@ def main(argv=None) -> int:
         help="Base molecule name for renamed groups (default: IMC)"
     )
     parser.add_argument(
-        "--classify-mode", choices=["imc", "generic"], default="imc",
+        "--classify-mode", choices=["imc", "generic", "auto"], default="imc",
         help="imc: COOH-centric 4-species (dual/chain/single/free, IMC default). "
-             "generic: donor-type x acceptor-type pair stats (PVA/peptide/etc.)"
+             "generic: donor-type x acceptor-type pair stats (PVA/peptide/etc.). "
+             "auto: detect functional groups present and run generic with them "
+             "(no need to pass --donor-groups/--acceptor-groups; ether_O excluded)"
     )
     parser.add_argument(
         "--no-element-fallback", action="store_true",
@@ -148,6 +150,17 @@ def main(argv=None) -> int:
         "--no-distance-plots", action="store_true",
         help="Skip d(D...A) distance distribution + (d, ∠) 2-D heatmap"
     )
+    parser.add_argument(
+        "--no-diagram", action="store_true",
+        help="Skip the per-molecule 2D structure diagram of the detected "
+             "H-bond sites (red=donor/cyan=acceptor). Requires RDKit; the "
+             "diagram is auto-generated by default when RDKit is available."
+    )
+    parser.add_argument(
+        "--diagram-charge", type=int, default=0,
+        help="Net molecular charge for diagram bond-order perception "
+             "(DetermineBondOrders), default 0 = neutral"
+    )
     parser.add_argument(
         "--distance-d-min", type=float, default=2.0,
         help="d(D...A) histogram lower edge [Å] (default 2.0)"
@@ -213,6 +226,8 @@ def main(argv=None) -> int:
         distance_d_max=args.distance_d_max,
         distance_bin_width=args.distance_bin_width,
         angle_bin_width=args.angle_bin_width,
+        do_diagram=not args.no_diagram,
+        diagram_charge=args.diagram_charge,
     )
 
     analyzer = Analyzer(config)

abmptools-2.3.0/abmptools/hbond/diagram.py

@@ -0,0 +1,150 @@
+"""Per-molecule 2D structure diagrams marking the detected H-bond sites.
+
+Builds an RDKit molecule from the COGNAC UDF topology (element from
+``Atom_Name`` + connectivity + a single frame's 3D coordinates) and renders a
+2D depiction with the **detected** donor / acceptor atoms highlighted
+(red = donor, cyan = acceptor). One diagram is produced per unique molecular
+species.
+
+COGNAC UDFs (and OpenFF-interchange-exported ones in particular) usually carry
+**no bond orders** (every ``order`` is 1.0), so aromaticity and C=O double
+bonds are recovered from the 3D geometry via
+``rdkit.Chem.rdDetermineBonds.DetermineBondOrders`` (assumes a neutral, closed
+shell molecule by default — override with ``charge``).
+
+RDKit is an optional dependency: if it is not importable, or the molecule
+cannot be perceived (e.g. an ion with the wrong ``charge``), diagram generation
+is skipped with a warning rather than aborting the analysis.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Sequence, Tuple
+
+# Two-letter elements first so "Cl"/"Br" are not truncated to "C"/"B".
+_TWO_LETTER = ("Cl", "Br", "Si", "Na", "Mg", "Ca", "Fe", "Zn", "Li", "Se")
+_ONE_LETTER = set("HCNOFPSKIBW")
+
+DONOR_COLOR = (0.92, 0.30, 0.30)     # red
+ACCEPTOR_COLOR = (0.20, 0.75, 0.90)  # cyan
+
+
+def element_from_name(name: str) -> str:
+    """Best-effort element symbol from a UDF ``Atom_Name``.
+
+    Handles clean symbols (``"Cl"``, ``"O"``), element+index (``"C10"``,
+    ``"HO"`` → ``H``), and is case-insensitive on the trailing letter so
+    ``"CL"`` and ``"cl"`` both resolve to ``Cl``.
+    """
+    s = "".join(ch for ch in (name or "") if ch.isalpha())
+    if not s:
+        return ""
+    cap = s[0].upper() + s[1:2].lower()
+    for two in _TWO_LETTER:
+        if cap.startswith(two):
+            return two
+    if s[0].upper() in _ONE_LETTER:
+        return s[0].upper()
+    return s[0].upper()
+
+
+def build_mol_from_topology(topology, coords, charge: int = 0):
+    """Build an RDKit ``Mol`` from a ``MoleculeTopology`` + 3D coordinates.
+
+    Returns ``(mol, None)`` on success or ``(None, reason)`` on failure.
+    ``coords`` is an ``(n_atoms, 3)`` array-like (Å). Atom order is preserved,
+    so caller-supplied atom indices map 1:1 onto the returned molecule.
+    """
+    try:
+        from rdkit import Chem
+        from rdkit.Chem import rdDetermineBonds
+        from rdkit.Geometry import Point3D
+    except ImportError:
+        return None, "rdkit not installed"
+
+    atoms = topology.atoms
+    if coords is None or len(coords) != len(atoms):
+        return None, "coordinate/atom count mismatch"
+
+    rw = Chem.RWMol()
+    for a in atoms:
+        sym = element_from_name(a.atom_name)
+        if not sym:
+            return None, f"could not resolve element for {a.atom_name!r}"
+        rw.AddAtom(Chem.Atom(sym))
+    for b in topology.bonds:
+        rw.AddBond(int(b.atom1), int(b.atom2), Chem.BondType.SINGLE)
+    mol = rw.GetMol()
+
+    conf = Chem.Conformer(mol.GetNumAtoms())
+    for i in range(mol.GetNumAtoms()):
+        x, y, z = coords[i]
+        conf.SetAtomPosition(i, Point3D(float(x), float(y), float(z)))
+    mol.AddConformer(conf, assignId=True)
+
+    try:
+        # Perceive bond orders / aromaticity from geometry (bonds already set).
+        rdDetermineBonds.DetermineBondOrders(mol, charge=int(charge))
+        Chem.SanitizeMol(mol)
+    except Exception as e:  # noqa: BLE001 - any perception failure → skip
+        return None, f"bond-order perception failed: {type(e).__name__}: {e}"
+    return mol, None
+
+
+def draw_hbond_diagram(
+    mol,
+    donor_atoms: Sequence[int],
+    acceptor_atoms: Sequence[int],
+    png_path: str,
+    svg_path: Optional[str] = None,
+    legend: str = "",
+    donor_note: str = "donor",
+    acceptor_note: str = "acceptor",
+) -> List[str]:
+    """Render ``mol`` 2D with donor (red) / acceptor (cyan) atoms highlighted.
+
+    ``donor_atoms`` / ``acceptor_atoms`` are atom indices into ``mol`` (the
+    heavy donor atom, e.g. amide N, and the acceptor atom, e.g. carbonyl O).
+    Non-polar H are removed for clarity; the highlighted heavy atoms are tracked
+    across H removal via an atom property. Returns the list of written paths.
+    """
+    from rdkit import Chem
+    from rdkit.Chem import AllChem
+    from rdkit.Chem.Draw import rdMolDraw2D
+
+    work = Chem.Mol(mol)
+    for i in donor_atoms:
+        work.GetAtomWithIdx(int(i)).SetProp("_hb_role", "donor")
+    for i in acceptor_atoms:
+        work.GetAtomWithIdx(int(i)).SetProp("_hb_role", "acceptor")
+
+    heavy = Chem.RemoveHs(work)
+    AllChem.Compute2DCoords(heavy)  # 2D depiction, not a projection of the 3D pose
+
+    hi_atoms: List[int] = []
+    atom_cols: Dict[int, Tuple[float, float, float]] = {}
+    for a in heavy.GetAtoms():
+        if not a.HasProp("_hb_role"):
+            continue
+        role = a.GetProp("_hb_role")
+        hi_atoms.append(a.GetIdx())
+        atom_cols[a.GetIdx()] = DONOR_COLOR if role == "donor" else ACCEPTOR_COLOR
+        a.SetProp("atomNote", donor_note if role == "donor" else acceptor_note)
+
+    written: List[str] = []
+    targets = [("png", png_path)] + ([("svg", svg_path)] if svg_path else [])
+    for kind, path in targets:
+        drawer = (rdMolDraw2D.MolDraw2DCairo if kind == "png"
+                  else rdMolDraw2D.MolDraw2DSVG)(1100, 820)
+        op = drawer.drawOptions()
+        op.legendFontSize = 20
+        op.bondLineWidth = 2
+        rdMolDraw2D.PrepareAndDrawMolecule(
+            drawer, heavy, legend=legend,
+            highlightAtoms=hi_atoms, highlightAtomColors=atom_cols,
+        )
+        drawer.FinishDrawing()
+        data = drawer.GetDrawingText()
+        with open(path, "wb" if kind == "png" else "w") as f:
+            f.write(data)
+        written.append(path)
+    return written

{abmptools-2.2.0 → abmptools-2.3.0}/abmptools/udfcharge/__init__.py

@@ -14,8 +14,10 @@ from .core import (
     POINT_CHARGE,
     AssignResult,
     MoleculeChargeTemplate,
+    RestoreResult,
     assign_charges_to_bulk,
     read_molecule_charges,
+    restore_formal_charge,
 )
 
 __all__ = [
@@ -23,6 +25,8 @@ __all__ = [
     "POINT_CHARGE",
     "AssignResult",
     "MoleculeChargeTemplate",
+    "RestoreResult",
     "assign_charges_to_bulk",
     "read_molecule_charges",
+    "restore_formal_charge",
 ]

abmptools-2.3.0/abmptools/udfcharge/__main__.py

@@ -0,0 +1,117 @@
+"""CLI: OCTA/COGNAC UDF の per-atom 電荷操作。
+
+    # 単分子 UDF の電荷をバルク UDF の同名分子へ転写
+    python -m abmptools.udfcharge transfer --template mol.udf --bulk bulk.udf \
+        [--out bulk_charged.udf] [--mol-name NAME] [--mol-index I] \
+        [--no-verify-types] [--non-strict]
+
+    # 中和 (Σq≈0) された 1 分子 UDF の電荷を指定形式電荷に復元
+    python -m abmptools.udfcharge restore --udf mol.udf --formal-charge 12 \
+        [--out mol_q+12.udf] [--mol-index I] [--mol-name NAME]
+
+後方互換: サブコマンド省略時は ``transfer`` として解釈する。
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from .core import (
+    assign_charges_to_bulk,
+    read_molecule_charges,
+    restore_formal_charge,
+)
+
+_SUBCOMMANDS = {"transfer", "restore"}
+
+
+def _run_transfer(args) -> int:
+    tmpl = read_molecule_charges(
+        args.template, mol_name=args.mol_name, mol_index=args.mol_index,
+    )
+    res = assign_charges_to_bulk(
+        args.bulk, tmpl, args.out,
+        verify_atom_types=not args.no_verify_types,
+        strict=not args.non_strict,
+    )
+    print(f"template : {tmpl.mol_name} (n_atoms={tmpl.n_atoms}, "
+          f"net_charge={tmpl.net_charge:+.4f})")
+    print(f"assigned : {res.n_molecules_assigned}/{res.n_molecules_total} molecules")
+    if res.skipped_indices:
+        print(f"skipped  : {res.skipped_indices}")
+    print(f"output   : {res.out_path}")
+    return 0
+
+
+def _run_restore(args) -> int:
+    res = restore_formal_charge(
+        args.udf, args.formal_charge, args.out,
+        mol_index=args.mol_index, mol_name=args.mol_name, mode=args.mode,
+    )
+    detail = (f"λ={res.lam:.8f}" if res.mode == "proportional"
+              else f"shift=S/N={res.shift:.8f}")
+    print(f"molecule     : {res.mol_name} (n_atoms={res.n_atoms})")
+    print(f"mode         : {res.mode}")
+    print(f"input total  : {res.input_total:+.6f}  (中和済み想定)")
+    print(f"formal charge: {res.formal_charge:+d}  ({detail})")
+    print(f"output total : {res.output_total:+.6f}")
+    print(f"output       : {res.out_path}")
+    return 0
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # 後方互換: 旧フラット呼び出し (transfer の --template ...) を許容
+    if argv and argv[0] not in _SUBCOMMANDS and not argv[0].startswith("-"):
+        pass  # 不明な位置引数 → そのまま argparse にエラーさせる
+    elif argv and argv[0].startswith("-") and "--template" in argv:
+        argv = ["transfer"] + argv
+
+    p = argparse.ArgumentParser(
+        prog="python -m abmptools.udfcharge",
+        description="OCTA/COGNAC UDF の per-atom 電荷操作 (転写 / 形式電荷復元)。",
+    )
+    sub = p.add_subparsers(dest="cmd")
+
+    pt = sub.add_parser("transfer",
+                        help="単分子 UDF の電荷をバルク UDF の同名分子へ転写")
+    pt.add_argument("--template", required=True, help="電荷を持つ単分子 UDF")
+    pt.add_argument("--bulk", required=True, help="割り当て先のバルク UDF")
+    pt.add_argument("--out", default=None, help="出力 (省略時 <bulk>_charged.udf)")
+    pt.add_argument("--mol-name", default=None)
+    pt.add_argument("--mol-index", type=int, default=None)
+    pt.add_argument("--no-verify-types", action="store_true")
+    pt.add_argument("--non-strict", action="store_true")
+    pt.add_argument("-v", "--verbose", action="store_true")
+    pt.set_defaults(func=_run_transfer)
+
+    pr = sub.add_parser("restore",
+                        help="中和済み 1 分子 UDF の電荷を指定形式電荷に復元")
+    pr.add_argument("--udf", required=True, help="中和 (Σq≈0) された 1 分子 UDF")
+    pr.add_argument("--formal-charge", type=int, required=True,
+                    help="目標の形式電荷 (整数)")
+    pr.add_argument("--out", default=None, help="出力 (省略時 <udf>_q<±S>.udf)")
+    pr.add_argument("--mode", choices=["proportional", "uniform"],
+                    default="proportional",
+                    help="中和ルール: proportional (|q| 比例、 既定) / uniform (均等分配)")
+    pr.add_argument("--mol-name", default=None)
+    pr.add_argument("--mol-index", type=int, default=0)
+    pr.add_argument("-v", "--verbose", action="store_true")
+    pr.set_defaults(func=_run_restore)
+
+    args = p.parse_args(argv)
+    if not getattr(args, "cmd", None):
+        p.print_help()
+        return 2
+
+    logging.basicConfig(
+        level=logging.INFO if getattr(args, "verbose", False) else logging.WARNING,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())