mbe-step 2026.10.3__py2.py3-none-any.whl

mbe_step/__init__.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+
+"""
+mbe_step
+A SEAMM plug-in for many-body expansion (MBE) corrections of periodic cells and clusters
+"""
+
+# Bring up the classes so that they appear to be directly in
+# the mbe_step package.
+
+from .mbe import Mbe  # noqa: F401, E501
+from .mbe_parameters import MbeParameters  # noqa: F401, E501
+from .mbe_step import MbeStep  # noqa: F401, E501
+from .tk_mbe import TkMbe  # noqa: F401, E501
+
+from .metadata import metadata  # noqa: F401
+
+# Handle versioneer
+from ._version import get_versions
+
+__author__ = "Paul Saxe"
+__email__ = "psaxe@molssi.org"
+versions = get_versions()
+__version__ = versions["version"]
+__git_revision__ = versions["full-revisionid"]
+del get_versions, versions

mbe_step/_version.py

@@ -0,0 +1,21 @@
+
+# This file was generated by 'versioneer.py' (0.18) from
+# revision-control system data, or from the parent directory name of an
+# unpacked source archive. Distribution tarballs contain a pre-generated copy
+# of this file.
+
+import json
+
+version_json = '''
+{
+ "date": "2026-10-03T17:26:32-0400",
+ "dirty": false,
+ "error": null,
+ "full-revisionid": "75d8c631ab753ad62195bb5914986616eee5eda3",
+ "version": "2026.10.3"
+}
+'''  # END VERSION_JSON
+
+
+def get_versions():
+    return json.loads(version_json)

mbe_step/counterpoise.py

@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+
+"""Pairwise counterpoise for the MBE step, through seamm_bsse.
+
+For a selected pair, the Boys-Bernardi correction needs each monomer in the
+pair's basis (the other monomer's atoms as ghosts): two extra calculations per
+pair at each molecular level. With the pair itself and the two monomers (both
+already computed as fragments), seamm_bsse.combine gives the counterpoise-
+corrected pair energy and gradient, guarded against unphysical ghost gradients.
+
+The correction enters the sum only (seamm_mbe's ``corrections``): with
+[high - low] for the pair,
+
+    correction = (E_high^CP - E_high) - (E_low^CP - E_low)
+
+the second term only when the pair is referenced to the molecular low level (a
+plane-wave periodic level has no basis-set superposition error). Triples still
+subtract the uncorrected pairs.
+"""
+
+import numpy as np
+import seamm_bsse
+from seamm_util import Q_
+
+from . import levels
+
+HARTREE_KJ = Q_(1.0, "E_h").m_as("kJ/mol")
+EV_KJ = Q_(1.0, "eV").m_as("kJ/mol")
+BOHR = Q_(1.0, "bohr").m_as("Å")
+
+
+def specs(system, pair):
+    """The seamm_bsse job specs for a pair (atom indices within the pair)."""
+    types = [system.types[system.molecules[m].type] for m in pair.molecules]
+    fragments = [
+        seamm_bsse.Fragment(
+            label=label,
+            atom_indices=[int(i) for i in pair.slot_atoms[slot]],
+            charge=types[slot].charge,
+            multiplicity=types[slot].multiplicity,
+        )
+        for slot, label in enumerate(("A", "B"))
+    ]
+    return seamm_bsse.generate_job_specs(fragments)
+
+
+def ghost_jobs(system, pair):
+    """The extra calculations for a pair: {label: (structure, options)} for
+    each monomer in the pair's basis."""
+    geometry = levels.geometry(system, pair)
+    jobs = {}
+    for spec in specs(system, pair):
+        if spec.kind != seamm_bsse.FRAGMENT_IN_CLUSTER:
+            continue
+        jobs[spec.label] = (
+            geometry,
+            {
+                "atom_indices": list(spec.atom_indices),
+                "ghost_atoms": sorted(spec.ghost_indices),
+                "charge": spec.charge,
+                "multiplicity": spec.multiplicity,
+            },
+        )
+    return jobs
+
+
+def key(prefix, pair_name, label):
+    """The task key of a ghost job."""
+    return f"{prefix}{pair_name}-cp-{label}"
+
+
+def _job_result(result):
+    """An EvaluatorResult (kJ/mol, kJ/mol/Å) as a seamm_bsse.JobResult (E_h,
+    E_h/bohr)."""
+    gradient = np.asarray(result.gradients, dtype=float) * BOHR / HARTREE_KJ
+    return seamm_bsse.JobResult(energy=result.energy / HARTREE_KJ, gradient=gradient)
+
+
+def correction(system, fragments, pair, results, prefix):
+    """The counterpoise correction of one pair at one level.
+
+    Parameters
+    ----------
+    results : {str: EvaluatorResult}
+        The level's results by key (the pair, its monomers and its ghost jobs).
+
+    Returns
+    -------
+    energy : float
+        E^CP - E for the pair, eV.
+    forces : numpy.ndarray
+        (n_atoms, 3) the change of the pair's forces, eV/Å.
+    fallback : bool
+        Whether seamm_bsse kept the uncorrected gradient (unphysical ghost
+        gradients: the energy is corrected, the forces are not).
+    """
+    monomers = {slots[0]: name for name, slots in pair.subfragments if len(slots) == 1}
+    by_label = {
+        "cluster": results[prefix + pair.name],
+        "A-alone": results[prefix + monomers[0]],
+        "B-alone": results[prefix + monomers[1]],
+        "A-in-cluster": results[key(prefix, pair.name, "A-in-cluster")],
+        "B-in-cluster": results[key(prefix, pair.name, "B-in-cluster")],
+    }
+    for label, result in by_label.items():
+        if not result.ok:
+            raise KeyError(f"{pair.name} {label}: {result.reason}")
+    job_results = {label: _job_result(r) for label, r in by_label.items()}
+    cp = seamm_bsse.combine(specs(system, pair), job_results, n_atoms=pair.n_atoms)
+    cluster = job_results["cluster"]
+    d_energy = (cp.energy - cluster.energy) * HARTREE_KJ / EV_KJ
+    d_gradient = np.asarray(cp.gradient) - np.asarray(cluster.gradient)
+    d_forces = -d_gradient * HARTREE_KJ / BOHR / EV_KJ
+    return d_energy, d_forces, bool(cp.gradient_fallback)

mbe_step/data/properties.csv

@@ -0,0 +1,4 @@
+Property,Type,Units,Description,URL
+energy#MBE#{model},float,kJ/mol,The MBE-corrected total energy,
+gradients#MBE#{model},json,kJ/mol/Å,The MBE-corrected gradients,
+stress#MBE#{model},json,GPa,"The MBE-corrected stress, Voigt, sigma = -P",

mbe_step/data/references.bib

@@ -0,0 +1,82 @@
+This is an initial library of BibTex references for the mbe_step plug-in for SEAMM,
+generated automatically by the cookiecutter. You may wish to edit the first entry to correct some
+of the information.
+
+Add other references to the end of the file and add code in the plug-in to cite the references as
+appropriate. This is done with code like this:
+
+        self.references.cite(
+            raw=self._bibliography['doi:10.1002/jcc.21224'],
+            alias='packmol',
+            module='packmol_step',
+            level=1,
+            note='The principle PACKMOL citation.'
+        )
+
+which is typically in the run() method of the plug-in.
+
+The base node class in SEAMM automatically reads this list of references into a dictionary in
+self._bibliography with the key being the key of the BibTex entry -- usually the name on the
+first line of the entry after the 'article' or 'misc' (for software) keyword.
+
+See the documentation for the Reference Handler for the other arguments to cite().
+
+# End of initial comments #
+
+# This is the citation for this plug-in, generated and used automatically.
+# You might need to edit the author, address, etc. The month, year and version fields
+# are automatically filled in with information about current version of the plug-in.
+# This is handled in seamm/nody.py, the run() method.
+
+@Misc{mbe_step,
+	author = {Paul Saxe},
+	title = {MBE plug-in for SEAMM},
+	month = {$month},
+	year = {$year},
+	organization = {molssi-seamm},
+	url = {https://github.com/molssi-seamm/mbe_step },
+	address = {USA},
+	version = {$version}
+}
+
+@Misc{seamm_mbe,
+	author = {Paul Saxe},
+	title = {seamm_mbe: many-body expansion bookkeeping for SEAMM},
+	year = {2026},
+	organization = {molssi-seamm},
+	url = {https://github.com/molssi-seamm/seamm_mbe},
+	address = {USA}
+}
+
+@article{Herbert_2019,
+	title = {Fantasy versus reality in fragment-based quantum chemistry},
+	volume = {151},
+	number = {17},
+	pages = {170901},
+	journal = {The Journal of Chemical Physics},
+	author = {Herbert, John M.},
+	year = {2019},
+	doi = {10.1063/1.5126216}
+}
+
+@article{Richard_2014,
+	title = {Aiming for Benchmark Accuracy with the Many-Body Expansion},
+	volume = {47},
+	number = {9},
+	pages = {2828--2836},
+	journal = {Accounts of Chemical Research},
+	author = {Richard, Ryan M. and Lao, Ka Un and Herbert, John M.},
+	year = {2014},
+	doi = {10.1021/ar500119q}
+}
+
+@article{Beran_2016,
+	title = {Modeling Polymorphic Molecular Crystals with Electronic Structure Theory},
+	volume = {116},
+	number = {9},
+	pages = {5567--5613},
+	journal = {Chemical Reviews},
+	author = {Beran, Gregory J. O.},
+	year = {2016},
+	doi = {10.1021/acs.chemrev.5b00648}
+}

mbe_step/labels.py

@@ -0,0 +1,207 @@
+# -*- coding: utf-8 -*-
+
+"""Helpers of the MBE step that need no flowchart: parsing the cutoff and
+offset tables, the stress layout, and the extended XYZ labels file."""
+
+import numpy as np
+
+import seamm_mbe
+
+
+def parse_table(text, what="cutoff"):
+    """A table of values by molecule-type pair.
+
+    Parameters
+    ----------
+    text : str
+        Entries 'type type value' separated by ';' or new lines, e.g.
+        'water water 4.5; Li+ * 3.0'. '*' matches any type.
+
+    Returns
+    -------
+    {(str, str): float}
+    """
+    table = {}
+    for entry in text.replace("\n", ";").split(";"):
+        entry = entry.strip()
+        if not entry:
+            continue
+        fields = entry.split()
+        if len(fields) != 3:
+            raise ValueError(
+                f"The {what} table entry '{entry}' should be 'type type value', "
+                "e.g. 'water water 4.5'."
+            )
+        try:
+            value = float(fields[2])
+        except ValueError:
+            raise ValueError(f"The {what} in '{entry}' is not a number.") from None
+        table[(fields[0], fields[1])] = value
+    if not table:
+        raise ValueError(f"The {what} table is empty.")
+    return table
+
+
+def parse_offsets(text):
+    """Energy offsets in eV per molecule by type, from entries 'type value'
+    separated by ';' or new lines, or None for 'none' or an empty text."""
+    text = text.strip()
+    if text.lower() in ("", "none"):
+        return None
+    offsets = {}
+    for entry in text.replace("\n", ";").split(";"):
+        entry = entry.strip()
+        if not entry:
+            continue
+        fields = entry.split()
+        if len(fields) != 2:
+            raise ValueError(
+                f"The energy offset '{entry}' should be 'type value', e.g. "
+                "'water 2074.69325'."
+            )
+        try:
+            offsets[fields[0]] = float(fields[1])
+        except ValueError:
+            raise ValueError(f"The offset in '{entry}' is not a number.") from None
+    return offsets
+
+
+def voigt(tensor):
+    """A (3, 3) tensor as Voigt [6]: xx yy zz yz xz xy (symmetrized)."""
+    t = np.asarray(tensor, dtype=float)
+    t = (t + t.T) / 2
+    return [t[0, 0], t[1, 1], t[2, 2], t[1, 2], t[0, 2], t[0, 1]]
+
+
+def write_extxyz(
+    path,
+    system,
+    labels,
+    *,
+    name,
+    model,
+    identifier=None,
+    counterpoise=False,
+    extra="",
+):
+    """Add one configuration's labels to an extended XYZ file.
+
+    The file collects configurations (several in one step, or across a loop's
+    iterations when it is a job-level file). Writing is idempotent: an earlier
+    frame with the same ``identifier`` (SEAMM/configuration_id) is replaced, so
+    rerunning a job does not duplicate labels.
+
+    The columns are species, pos and REF_forces (eV/Å); the header carries
+    REF_energy (eV, the reference scale), REF_stress (the nine values of
+    sigma = -P in eV/ų, for a cell), the Lattice and pbc, the model, whether
+    counterpoise was used and the configuration's name. Note that ASE reads the
+    nine-value REF_stress as a flat vector: a reader must reshape it.
+    """
+    fields = []
+    if system.periodic:
+        lattice = " ".join(f"{v:.8f}" for v in system.cell.ravel())
+        fields.append(f'Lattice="{lattice}"')
+    fields.append("Properties=species:S:1:pos:R:3:REF_forces:R:3")
+    fields.append(f"REF_energy={labels.reference_energy:.8f}")
+    if system.periodic:
+        stress = " ".join(f"{v:.10e}" for v in labels.stress.ravel())
+        fields.append(f'REF_stress="{stress}"')
+        fields.append('pbc="T T T"')
+    else:
+        fields.append('pbc="F F F"')
+    fields.append(f'model="{model}"')
+    fields.append(f"counterpoise={'T' if counterpoise else 'F'}")
+    fields.append(f'SEAMM/configuration_name="{name}"')
+    if identifier is not None:
+        fields.append(f"SEAMM/configuration_id={identifier}")
+    if extra:
+        fields.append(extra)
+    lines = [str(len(system.symbols)), " ".join(fields)]
+    for symbol, xyz, force in zip(system.symbols, system.coordinates, labels.forces):
+        lines.append(
+            f"{symbol:2s} {xyz[0]:14.8f} {xyz[1]:14.8f} {xyz[2]:14.8f} "
+            f"{force[0]:14.8f} {force[1]:14.8f} {force[2]:14.8f}"
+        )
+    frames = _read_frames(path)
+    if identifier is not None:
+        tag = f"SEAMM/configuration_id={identifier}"
+        frames = [f for f in frames if tag not in f[1].split()]
+    frames.append(lines)
+    with open(path, "w") as fd:
+        for frame in frames:
+            fd.write("\n".join(frame) + "\n")
+
+
+def _read_frames(path):
+    """The frames of an extended XYZ file as lists of lines ([] if none)."""
+    try:
+        text = open(path).read().splitlines()
+    except FileNotFoundError:
+        return []
+    frames = []
+    i = 0
+    while i < len(text):
+        if not text[i].strip():
+            i += 1
+            continue
+        try:
+            n = int(text[i])
+        except ValueError:
+            raise ValueError(
+                f"{path}, line {i + 1}: expected the number of atoms of a frame, "
+                f"found '{text[i][:40]}'. Is it an extended XYZ file?"
+            ) from None
+        frames.append(text[i : i + n + 2])
+        i += n + 2
+    return frames
+
+
+def counts_text(fragments):
+    """'64 monomers, 391 pairs (+268 outer), 559 triples'."""
+    names = {1: "monomers", 2: "pairs", 3: "triples", 4: "4-bodies"}
+    parts = []
+    for order, count in sorted(fragments.counts().items()):
+        text = f"{count['selected']} {names.get(order, f'{order}-bodies')}"
+        if count["auxiliary"]:
+            extra = "outer" if order == 2 else "auxiliary"
+            text += f" (+{count['auxiliary']} {extra})"
+        parts.append(text)
+    return ", ".join(parts)
+
+
+def to_seamm(labels, volume):
+    """The labels in SEAMM's units for store_results: energies kJ/mol,
+    gradients kJ/mol/Å, stress Voigt [6] in GPa as sigma = -P, pressures in
+    atm."""
+    units = seamm_mbe.units
+    data = units.to_seamm(energy=labels.energy, forces=labels.forces)
+    data["gradients"] = data["gradients"].tolist()
+    data["reference energy"] = float(units.ev_to_kj_per_mol(labels.reference_energy))
+    if labels.virial is not None:
+        stress = units.tensor_from_virial(
+            labels.virial, volume, convention="stress", units="GPa"
+        )
+        data["stress"] = voigt(stress)
+        data["pressure"] = labels.pressure
+        data["molecular pressure"] = labels.molecular_pressure
+        data["MBE pressure"] = labels.breakdown["MBE"]["pressure"]
+    data["MBE energy"] = float(
+        units.ev_to_kj_per_mol(labels.breakdown["MBE"]["energy"])
+    )
+    data["per-body energies"] = {
+        str(k): float(units.ev_to_kj_per_mol(v["energy"]))
+        for k, v in labels.per_body.items()
+    }
+    if labels.virial is not None:
+        data["per-body pressures"] = {
+            str(k): v["pressure"] for k, v in labels.per_body.items()
+        }
+    data["maximum increment net force"] = float(
+        units.ev_to_kj_per_mol(labels.max_increment_net_force)
+    )
+    forces = np.asarray(labels.forces)
+    data["maximum force"] = float(units.ev_to_kj_per_mol(np.abs(forces).max()))
+    data["rms force"] = float(
+        units.ev_to_kj_per_mol(np.sqrt((forces**2).sum(1).mean()))
+    )
+    return data

mbe_step/levels.py

@@ -0,0 +1,213 @@
+# -*- coding: utf-8 -*-
+
+"""The MBE step's levels of theory: resolving their model chemistries and
+evaluating structures with each through seamm_exec's Evaluator.
+
+The step uses up to four levels:
+
+* high: every fragment (by default the flowchart's current Model Chemistry);
+* molecular: the molecular low level, on the fragments referenced to it;
+* periodic: the periodic low level, on the compact fragments referenced to it;
+* cell: the low level of the whole cell (or cluster).
+
+Each level is one Evaluator with its own directory, so each keeps its own task
+manifest (restart) and bundles; the Evaluator chooses how the level runs
+(batch tasks or an MDI engine). In this phase the levels run one after the
+other; running them concurrently is a seamm_exec follow-up.
+"""
+
+import logging
+from pathlib import Path
+
+import numpy as np
+
+import seamm_mbe
+
+logger = logging.getLogger(__name__)
+
+#: The sentinel for the flowchart's current Model Chemistry
+CURRENT = "current model chemistry"
+
+
+def resolve(text, context, current=None, periodic=False):
+    """The ``_model_chemistry`` wrapper for a level given as text.
+
+    Parameters
+    ----------
+    text : str
+        A level spec such as ``"ORCA:DFT@r2SCAN-D4/def2-TZVPPD"``, possibly with
+        ``$variable`` components, or :data:`CURRENT`.
+    context : dict
+        The flowchart variables, to dereference any ``$variable``.
+    current : dict or None
+        The flowchart's ``_model_chemistry``, for :data:`CURRENT`.
+    periodic : bool
+        Whether the level must handle periodic systems.
+
+    Returns
+    -------
+    dict
+        The ``_model_chemistry`` wrapper: level, step, options, ...
+    """
+    from model_chemistry_step.model_chemistry import (
+        availability_problem,
+        discover_model_chemistries,
+        match_model_chemistry,
+        resolve_level,
+    )
+
+    if text == CURRENT:
+        if current is None:
+            raise ValueError(
+                "The MBE step's high level is the current model chemistry, but "
+                "there is none: add a Model Chemistry step before the MBE step, "
+                "or give the high level explicitly."
+            )
+        return current
+    text = resolve_level(text, context)
+    available = discover_model_chemistries(periodic_only=periodic)
+    if text in available:
+        return available[text]
+    mc = match_model_chemistry(text, available)
+    if mc is None:
+        raise ValueError(availability_problem(text, available, periodic=periodic))
+    return mc
+
+
+def stress_convention(mc):
+    """The sign convention of a level's stress, as its provider declares it
+    ("pressure" or "stress"); refuse a periodic level that does not."""
+    convention = (mc.get("options") or {}).get("stress_convention")
+    if convention not in seamm_mbe.units.CONVENTIONS:
+        raise ValueError(
+            f"The model chemistry '{mc['level']}' does not declare the sign "
+            "convention of its stress (options['stress_convention'] = 'pressure' "
+            "or 'stress'), so its stress cannot be used for a periodic cell."
+        )
+    return convention
+
+
+class Level:
+    """One level of theory and how it runs.
+
+    Parameters
+    ----------
+    name : str
+        "high", "molecular", "periodic" or "cell"; also the directory name.
+    mc : dict
+        The ``_model_chemistry`` wrapper.
+    ranks : int
+        MPI ranks per calculation.
+    memory : float
+        Memory per rank, in MB.
+    bundle : int
+        Calculations per batch job on a queue.
+    walltime : float
+        Seconds per batch job.
+    archive : bool
+        Tar finished bundles.
+    """
+
+    def __init__(self, name, mc, *, ranks, memory, bundle, walltime, archive):
+        self.name = name
+        self.mc = mc
+        self.ranks = int(ranks)
+        self.memory = float(memory)
+        self.bundle = int(bundle)
+        self.walltime = float(walltime)
+        self.archive = bool(archive)
+
+    @property
+    def level(self):
+        return self.mc["level"]
+
+    def resources(self):
+        from seamm_exec import Resources
+
+        return Resources(ntasks=self.ranks, mem_per_cpu=int(self.memory * 1e6))
+
+    def evaluate(self, node, structures, *, stress=False):
+        """Evaluate structures at this level.
+
+        Parameters
+        ----------
+        node : seamm.Node
+            The MBE step.
+        structures : {str: object}
+            Configurations or ``seamm_exec.Geometry`` objects by key.
+        stress : bool
+            Request the stress (for a periodic cell).
+
+        Returns
+        -------
+        {str: seamm_exec.EvaluatorResult}
+        """
+        import seamm_exec
+
+        properties = ("energy", "gradients") + (("stress",) if stress else ())
+        options = {"archive": self.archive, "bundle_tasks": self.bundle}
+        if self.walltime > 0:
+            options["bundle_walltime"] = self.walltime
+        results = {}
+        with seamm_exec.Evaluator(
+            node,
+            self.mc,
+            properties=properties,
+            directory=Path(node.directory) / self.name,
+            task_set_options=options,
+            resources=self.resources(),
+            name=f"MBE_{self.name}",  # no spaces: it goes into MDI_Init
+        ) as evaluator:
+            for key, structure in structures.items():
+                options = None
+                if isinstance(structure, tuple):
+                    structure, options = structure
+                evaluator.submit(structure, key=key, options=options)
+            for result in evaluator.results():
+                results[result.key] = result
+        return results
+
+
+def geometry(system, fragment):
+    """The isolated fragment as a ``seamm_exec.Geometry``: its atoms in
+    fragment order at the fragment's coordinates, with its charge and
+    multiplicity."""
+    from seamm_exec import Geometry
+
+    return Geometry(
+        system.atomic_numbers[fragment.atoms],
+        fragment.coordinates,
+        charge=fragment.charge,
+        multiplicity=fragment.multiplicity,
+        name=fragment.name,
+    )
+
+
+def whole(system):
+    """The whole cell or cluster as a ``seamm_exec.Geometry`` with the charge
+    the molecules add up to (their types' charges, from the formal charges or
+    the catalog) -- the same charges the fragments use -- and multiplicity 1
+    (open-shell molecules are refused before this)."""
+    from seamm_exec import Geometry
+
+    charge = sum(system.types[m.type].charge for m in system.molecules)
+    return Geometry(
+        system.atomic_numbers,
+        system.coordinates,
+        charge=charge,
+        multiplicity=1,
+        cell=system.cell,
+        name="whole system",
+    )
+
+
+def to_library(result, *, volume=None, convention=None):
+    """An EvaluatorResult in seamm_mbe's units: (energy eV, forces eV/Å), plus
+    the virial (eV) when the result has a stress."""
+    data = {"energy": result.energy, "gradients": np.asarray(result.gradients)}
+    if result.stress is not None and volume is not None:
+        data["stress"] = result.stress
+    out = seamm_mbe.units.from_analyze_task(
+        data, volume=volume, stress_convention=convention
+    )
+    return out