orca-step 2026.6.27__py2.py3-none-any.whl

orca_step/__init__.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+
+"""
+orca_step
+A SEAMM plug-in for ORCA, with a sub-flowchart of capabilities (Energy,
+Optimization, ...), modeled on the MOPAC and Gaussian steps.
+"""
+
+# Metadata and the shared base first (others import them).
+from .metadata import metadata  # noqa: F401
+from .orca_base import ORCABase  # noqa: F401
+
+# Sub-step parameters / nodes / Tk / factories.
+from .energy_parameters import EnergyParameters  # noqa: F401
+from .energy import Energy  # noqa: F401
+from .tk_energy import TkEnergy  # noqa: F401
+from .energy_step import EnergyStep  # noqa: F401
+
+from .optimization_parameters import OptimizationParameters  # noqa: F401
+from .optimization import Optimization  # noqa: F401
+from .tk_optimization import TkOptimization  # noqa: F401
+from .optimization_step import OptimizationStep  # noqa: F401
+
+# Main node, Tk, and factory.
+from .orca import ORCA  # noqa: F401
+from .tk_orca import TkORCA  # noqa: F401
+from .orca_step import ORCAStep  # noqa: F401
+
+# 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

orca_step/__main__.py

@@ -0,0 +1,16 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""Handle the installation of the ORCA step."""
+
+from .installer import Installer
+
+
+def run():
+    """Find and/or register the ORCA executable in seamm.ini."""
+    installer = Installer()
+    installer.run()
+
+
+if __name__ == "__main__":
+    run()

orca_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-06-27T21:40:25-0400",
+ "dirty": false,
+ "error": null,
+ "full-revisionid": "fafca4b1d969cf0c6ca3e0ae5c8e21afc8f78b1c",
+ "version": "2026.6.27"
+}
+'''  # END VERSION_JSON
+
+
+def get_versions():
+    return json.loads(version_json)

orca_step/data/configuration.txt

@@ -0,0 +1,16 @@
+[orca-step]
+# Path to the ORCA executable, if it is not on the PATH. ORCA must be invoked by
+# its full path so it can find its sub-programs.
+# orca-path =
+
+# How many cores/processes ORCA may use (via %pal). Default is serial (1).
+# Parallel ORCA requires a matching OpenMPI runtime (see library-path).
+# ncores = 1
+
+# Directory holding ORCA's required OpenMPI libraries (e.g. libmpi.40.dylib),
+# prepended to (DY)LD_LIBRARY_PATH for parallel runs. On this machine the
+# seamm-orca conda environment provides them.
+# library-path =
+
+# Maximum number of atoms for which to print detailed per-atom results.
+# max_atoms_to_print = 25

orca_step/data/properties.csv

@@ -0,0 +1 @@
+Property,Type,Units,Description,URL

orca_step/data/references.bib

@@ -0,0 +1,40 @@
+This is an initial library of BibTex references for the orca_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{orca_step,
+	author = {Paul Saxe},
+	title = {ORCA plug-in for SEAMM},
+	month = {$month},
+	year = {$year},
+	organization = {molssi-seamm},
+	url = {https://github.com/molssi-seamm/orca_step },
+	address = {USA},
+	version = {$version}
+}

orca_step/energy.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+
+"""An ORCA single-point energy sub-step."""
+
+import logging
+import pprint  # noqa: F401
+
+import orca_step
+import seamm
+from seamm_util import ureg, Q_  # noqa: F401
+import seamm_util.printing as printing
+from seamm_util.printing import FormattedText as __
+
+logger = logging.getLogger(__name__)
+job = printing.getPrinter()
+printer = printing.getPrinter("ORCA")
+
+
+class Energy(orca_step.ORCABase):
+    """A single-point energy with ORCA.
+
+    See Also
+    --------
+    TkEnergy, EnergyParameters, Optimization
+    """
+
+    def __init__(self, flowchart=None, title="Energy", extension=None, logger=logger):
+        """Initialize the Energy sub-step."""
+        logger.debug(f"Creating ORCA Energy {self}")
+
+        super().__init__(
+            flowchart=flowchart,
+            title=title,
+            extension=extension,
+            module=__name__,
+            logger=logger,
+        )
+
+        self._calculation = "energy"
+        self._metadata = orca_step.metadata
+        self.parameters = orca_step.EnergyParameters()
+
+    def description_text(self, P=None):
+        """Describe what this sub-step will do."""
+        if not P:
+            P = self.parameters.values_to_dict()
+
+        use_mc = P["use model chemistry"]
+        if not isinstance(use_mc, bool):
+            use_mc = use_mc == "yes"
+
+        if use_mc:
+            text = (
+                "Single-point energy with ORCA using the model chemistry from a "
+                "preceding Model Chemistry step."
+            )
+        else:
+            text = f"Single-point energy with ORCA at {P['method']}/{P['basis']}."
+        return self.header + "\n" + __(text, indent=4 * " ").__str__()
+
+    def keyword_line(self, P):
+        """Build the ORCA '!' keyword line.
+
+        If ``use model chemistry`` is set, the method (and basis, if given) come
+        from the global ``_model_chemistry`` variable defined by a preceding
+        Model Chemistry step; ORCA raises a clear error if it cannot provide that
+        model chemistry. Otherwise the explicit method/basis parameters are used.
+        The auxiliary basis and extra keywords always come from this node.
+        """
+        use_mc = P["use model chemistry"]
+        if not isinstance(use_mc, bool):
+            use_mc = use_mc == "yes"
+
+        if use_mc:
+            method, basis = self._method_basis_from_model_chemistry(P)
+        else:
+            method, basis = P["method"], P["basis"]
+
+        keywords = [method, basis]
+        aux = P["auxiliary basis"]
+        if aux and aux.lower() != "none":
+            keywords.append(aux)
+        extra = P["extra keywords"].strip()
+        if extra:
+            keywords.append(extra)
+        return " ".join(k for k in keywords if k)
+
+    def _method_basis_from_model_chemistry(self, P):
+        """Resolve (method, basis) from the global model chemistry, erroring
+        clearly if ORCA cannot provide it.
+        """
+        if not self.variable_exists("_model_chemistry"):
+            raise RuntimeError(
+                "'Use the global model chemistry' is selected, but no Model "
+                "Chemistry step has defined one (the '_model_chemistry' variable "
+                "is not set). Add a Model Chemistry step before this ORCA step, "
+                "or turn off 'use model chemistry' and set the method and basis "
+                "explicitly."
+            )
+        mc = self.get_variable("_model_chemistry")
+        level = mc.get("level", "") or mc.get("method", "")
+        owner = (mc.get("owner") or "").strip()
+        mtype = (mc.get("type") or "").strip()
+        method = (mc.get("method") or "").strip()
+        basis = mc.get("basis") or ""
+
+        # ORCA can evaluate an ORCA-owned or program-agnostic level of theory,
+        # but not another program's (e.g. MOPAC/xTB/LAMMPS) or a non-QC type.
+        if owner not in ("", "ORCA"):
+            raise RuntimeError(
+                f"The model chemistry '{level}' is owned by '{owner}', which "
+                "ORCA cannot provide. Choose an ORCA (or program-agnostic) model "
+                "chemistry, or set the method explicitly in the ORCA step."
+            )
+        if mtype.upper() in ("SQM", "FF", "MLFF"):
+            raise RuntimeError(
+                f"The model chemistry '{level}' is of type '{mtype}', which ORCA "
+                "does not provide. ORCA handles HF, DFT, MP2, and coupled-cluster "
+                "(QC) methods."
+            )
+        if method == "":
+            raise RuntimeError(
+                f"The model chemistry '{level}' does not name a method ORCA can " "use."
+            )
+        # If the model chemistry omits a basis, fall back to this node's basis.
+        if basis == "":
+            basis = P["basis"]
+        return method, basis
+
+    def run(self, keywords=None):
+        """Run the single-point energy."""
+        next_node = super().run(printer)
+
+        P = self.parameters.current_values_to_dict(
+            context=seamm.flowchart_variables._data
+        )
+
+        printer.important(__(self.description_text(P), indent=self.indent))
+
+        keyword_line = self.keyword_line(P)
+        if keywords:
+            keyword_line += " " + " ".join(keywords)
+
+        data = self.run_orca(keyword_line)
+
+        self._data = data
+        self.analyze(P=P, data=data)
+
+        return next_node
+
+    def analyze(self, indent="", P=None, data=None, **kwargs):
+        """Report the energy."""
+        if data is None:
+            data = getattr(self, "_data", {})
+        energy = data.get("energy")
+        if energy is None:
+            printer.normal(
+                __(
+                    "ORCA finished but no final single-point energy was found.",
+                    indent=self.indent + 4 * " ",
+                )
+            )
+            return
+
+        # Store on the configuration as a property.
+        _, configuration = self.get_system_configuration(None)
+        try:
+            configuration.properties.put(
+                "total energy#ORCA#{model}",
+                energy,
+                _type="float",
+                units="E_h",
+            )
+        except Exception as e:  # pragma: no cover - property store is best-effort
+            logger.debug(f"Could not store energy property: {e}")
+
+        printer.normal(
+            __(
+                f"The total energy is {energy:.8f} E_h.",
+                indent=self.indent + 4 * " ",
+            )
+        )
+
+    def cleanup(self):
+        """Nothing to clean up for a single point."""
+        pass

orca_step/energy_parameters.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+"""Control parameters for an ORCA single-point energy."""
+
+import logging
+
+import orca_step
+import seamm
+
+logger = logging.getLogger(__name__)
+
+
+class EnergyParameters(seamm.Parameters):
+    """The control parameters for an ORCA energy calculation.
+
+    The default path takes the method from a preceding Model Chemistry step; the
+    user can turn that off and choose the method and basis explicitly (similar to
+    the Gaussian step). The explicit choices are driven by the step's metadata.
+    """
+
+    parameters = {
+        "use model chemistry": {
+            "default": "yes",
+            "kind": "boolean",
+            "default_units": "",
+            "enumeration": ("yes", "no"),
+            "format_string": "",
+            "description": "Use the global model chemistry:",
+            "help_text": (
+                "Use the model chemistry defined by a preceding Model Chemistry "
+                "step (the '_model_chemistry' variable). If ORCA cannot provide "
+                "it, an error is raised. Turn this off to set the method and basis "
+                "explicitly below."
+            ),
+        },
+        "method": {
+            "default": "DLPNO-CCSD(T)",
+            "kind": "enum",
+            "default_units": "",
+            "enumeration": tuple(orca_step.metadata["methods"].keys()),
+            "format_string": "",
+            "description": "Method:",
+            "help_text": "The ORCA method (an ORCA '!' keyword).",
+        },
+        "basis": {
+            "default": "def2-TZVP",
+            "kind": "enum",
+            "default_units": "",
+            "enumeration": tuple(orca_step.metadata["basis sets"]),
+            "format_string": "",
+            "description": "Basis set:",
+            "help_text": (
+                "The orbital basis set. ORCA's built-in name is used; a valid "
+                "name may also be typed in. (Basis Set Exchange is a planned "
+                "opt-in alternative.)"
+            ),
+        },
+        "auxiliary basis": {
+            "default": "AutoAux",
+            "kind": "enum",
+            "default_units": "",
+            "enumeration": tuple(orca_step.metadata["auxiliary basis sets"]),
+            "format_string": "",
+            "description": "Auxiliary (fitting) basis:",
+            "help_text": (
+                "The auxiliary/fitting basis. 'AutoAux' generates a fitting basis "
+                "automatically and is the robust choice for correlated methods "
+                "(DLPNO, MP2). 'none' omits it."
+            ),
+        },
+        "extra keywords": {
+            "default": "TightSCF",
+            "kind": "string",
+            "default_units": "",
+            "enumeration": tuple(),
+            "format_string": "",
+            "description": "Extra keywords:",
+            "help_text": (
+                "Any additional ORCA '!' keywords to append, e.g. 'TightSCF', "
+                "'RIJCOSX', 'Grid5'."
+            ),
+        },
+        "results": {
+            "default": {},
+            "kind": "dictionary",
+            "default_units": "",
+            "enumeration": tuple(),
+            "format_string": "",
+            "description": "results",
+            "help_text": "The results to save to variables or in tables.",
+        },
+    }
+
+    def __init__(self, defaults={}, data=None):
+        """Initialize with the parameters above plus any overrides."""
+        logger.debug("EnergyParameters.__init__")
+        super().__init__(
+            defaults={**EnergyParameters.parameters, **defaults}, data=data
+        )

orca_step/energy_step.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+
+"""Stevedore helper for the ORCA Energy sub-step."""
+
+import orca_step
+
+
+class EnergyStep(object):
+    my_description = {
+        "description": "Single-point energy with ORCA",
+        "group": "Calculation",
+        "name": "Energy",
+    }
+
+    def __init__(self, flowchart=None, gui=None):
+        pass
+
+    def description(self):
+        return EnergyStep.my_description
+
+    def create_node(self, flowchart=None, **kwargs):
+        return orca_step.Energy(flowchart=flowchart, **kwargs)
+
+    def create_tk_node(self, canvas=None, **kwargs):
+        return orca_step.TkEnergy(canvas=canvas, **kwargs)

orca_step/installer.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+
+"""Installer for the ORCA plug-in.
+
+ORCA is licensed software installed manually from https://www.faccts.de / the
+ORCA forum, so this installer locates the existing ``orca`` executable and
+registers its full path in seamm.ini (ORCA needs its full path to launch its
+sub-programs).
+"""
+
+import importlib
+import logging
+import shutil
+
+import seamm_installer
+
+logger = logging.getLogger(__name__)
+
+
+class Installer(seamm_installer.InstallerBase):
+    """Locate the ORCA executable and register it in seamm.ini."""
+
+    def __init__(self, logger=logger):
+        super().__init__(logger=logger)
+        logger.debug("Initializing the ORCA installer object.")
+
+        self.section = "orca-step"
+        self.executables = ["orca"]
+        self.resource_path = importlib.resources.files("orca_step") / "data"
+
+    def exe_version(self, config):
+        """Return the ORCA name and version.
+
+        ORCA has no stable ``--version`` flag (the version is in the run banner),
+        so this just confirms the executable is reachable.
+        """
+        code = config.get("code", "orca")
+        path = shutil.which(code) or code
+        return "ORCA", "unknown" if path is None else "unknown"

orca_step/metadata.py

@@ -0,0 +1,80 @@
+# -*- coding: utf-8 -*-
+
+"""Metadata describing ORCA's methods, basis sets, and results.
+
+This drives the explicit method/basis GUI (like the Gaussian step) and will also
+back the model-chemistry protocol (``get_model_chemistry_options``) used by the
+Model Chemistry step. It is kept deliberately small for now and will be filled
+out as more of ORCA's capabilities are exposed.
+"""
+
+metadata = {}
+
+# Methods offered in the explicit GUI. Each is an ORCA "!" keyword. "type"
+# groups them for the model-chemistry protocol (QC = wavefunction, DFT, etc.).
+metadata["methods"] = {
+    "HF": {"type": "HF", "description": "Hartree-Fock"},
+    "MP2": {"type": "MP2", "description": "second-order Moller-Plesset (MP2)"},
+    "RI-MP2": {"type": "MP2", "description": "RI-MP2 (resolution of identity)"},
+    "CCSD(T)": {"type": "QC", "description": "coupled cluster CCSD(T)"},
+    "DLPNO-CCSD(T)": {
+        "type": "QC",
+        "description": "near-linear-scaling DLPNO-CCSD(T)",
+        "needs_aux": True,
+    },
+    "B3LYP": {"type": "DFT", "description": "B3LYP hybrid functional"},
+    "PBE": {"type": "DFT", "description": "PBE GGA functional"},
+    "PBE0": {"type": "DFT", "description": "PBE0 hybrid functional"},
+    "wB97X-D3": {
+        "type": "DFT",
+        "description": "range-separated wB97X-D3 functional",
+    },
+    "M06-2X": {"type": "DFT", "description": "M06-2X meta-hybrid functional"},
+}
+
+# Curated basis-set families (ORCA's built-in names). Free text is also allowed
+# in the GUI; these are the guided choices.
+metadata["basis sets"] = [
+    # Pople
+    "6-31G",
+    "6-31G*",
+    "6-31G**",
+    "6-31+G*",
+    "6-311G**",
+    "6-311++G**",
+    # Dunning correlation-consistent
+    "cc-pVDZ",
+    "cc-pVTZ",
+    "cc-pVQZ",
+    "aug-cc-pVDZ",
+    "aug-cc-pVTZ",
+    # Karlsruhe def2
+    "def2-SVP",
+    "def2-TZVP",
+    "def2-TZVPP",
+    "def2-QZVP",
+]
+
+# Auxiliary / fitting basis choices. AutoAux generates a fitting basis for any
+# method/basis and is the robust default for correlated (DLPNO/MP2) methods.
+metadata["auxiliary basis sets"] = [
+    "AutoAux",
+    "none",
+    "def2/J",
+    "def2/JK",
+]
+
+"""Results ORCA can produce. Same recognized fields as the other QM steps."""
+metadata["results"] = {
+    "energy": {
+        "description": "The total energy",
+        "dimensionality": "scalar",
+        "property": "total energy#ORCA#{model}",
+        "type": "float",
+        "units": "E_h",
+    },
+}
+
+# Placeholder for the model-chemistry protocol; populated in the Model Chemistry
+# integration phase via get_model_chemistry_options() on ORCAStep.
+metadata["computational models"] = {}

orca_step/optimization.py

@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+
+"""An ORCA geometry-optimization sub-step.
+
+Extends the Energy sub-step by adding the ``Opt`` keyword and, after the run,
+updating the configuration with the optimized geometry.
+"""
+
+import logging
+from pathlib import Path
+import pprint  # noqa: F401
+
+import orca_step
+from .energy import Energy
+import seamm  # noqa: F401
+from seamm_util.printing import FormattedText as __
+import seamm_util.printing as printing
+
+logger = logging.getLogger(__name__)
+printer = printing.getPrinter("ORCA")
+
+
+class Optimization(Energy):
+    """A geometry optimization with ORCA.
+
+    See Also
+    --------
+    TkOptimization, OptimizationParameters, Energy
+    """
+
+    def __init__(
+        self, flowchart=None, title="Optimization", extension=None, logger=logger
+    ):
+        logger.debug(f"Creating ORCA Optimization {self}")
+        super().__init__(
+            flowchart=flowchart, title=title, extension=extension, logger=logger
+        )
+        self._calculation = "optimization"
+        self.parameters = orca_step.OptimizationParameters()
+
+    def description_text(self, P=None):
+        if not P:
+            P = self.parameters.values_to_dict()
+        use_mc = P["use model chemistry"]
+        if not isinstance(use_mc, bool):
+            use_mc = use_mc == "yes"
+        method = "the model chemistry" if use_mc else f"{P['method']}/{P['basis']}"
+        conv = P["optimization convergence"]
+        text = f"Geometry optimization with ORCA at {method} ({conv})."
+        return self.header + "\n" + __(text, indent=4 * " ").__str__()
+
+    def run(self, keywords=None):
+        """Run the optimization by adding the Opt keyword to the energy run."""
+        P = self.parameters.current_values_to_dict(
+            context=seamm.flowchart_variables._data
+        )
+        opt_keywords = [P["optimization convergence"]]
+        if keywords:
+            opt_keywords += list(keywords)
+        return super().run(keywords=opt_keywords)
+
+    def analyze(self, indent="", P=None, data=None, **kwargs):
+        """Report the energy and update the configuration with the optimized
+        geometry, plus check that the optimization converged.
+        """
+        super().analyze(indent=indent, P=P, data=data)
+
+        directory = Path(self.directory)
+
+        # Convergence check from the output.
+        out = directory / "orca.out"
+        converged = False
+        if out.exists():
+            text = out.read_text()
+            converged = "THE OPTIMIZATION HAS CONVERGED" in text
+        if not converged:
+            printer.normal(
+                __(
+                    "Warning: the ORCA geometry optimization did not report "
+                    "convergence.",
+                    indent=self.indent + 4 * " ",
+                )
+            )
+
+        # Update the configuration with the optimized geometry (ORCA writes it
+        # to orca.xyz).
+        xyz = directory / "orca.xyz"
+        if xyz.exists():
+            coords = self._read_xyz_coordinates(xyz)
+            _, configuration = self.get_system_configuration(None)
+            if len(coords) == configuration.n_atoms:
+                configuration.atoms.set_coordinates(coords, fractionals=False)
+                printer.normal(
+                    __(
+                        "Updated the structure with the optimized geometry.",
+                        indent=self.indent + 4 * " ",
+                    )
+                )
+            else:
+                logger.warning(
+                    f"orca.xyz has {len(coords)} atoms, configuration has "
+                    f"{configuration.n_atoms}; not updating geometry."
+                )
+
+    @staticmethod
+    def _read_xyz_coordinates(path):
+        """Read [[x, y, z], ...] in Angstrom from a standard .xyz file."""
+        lines = path.read_text().splitlines()
+        n = int(lines[0].split()[0])
+        coords = []
+        for line in lines[2 : 2 + n]:
+            fields = line.split()
+            coords.append([float(fields[1]), float(fields[2]), float(fields[3])])
+        return coords