qccompute 0.13.0__py3-none-any.whl

qccompute/__init__.py

@@ -0,0 +1,10 @@
+from importlib import metadata as _metadata
+
+try:
+    __version__ = _metadata.version(__name__)
+except _metadata.PackageNotFoundError:
+    # Source tree / build hook / CI checkout
+    __version__ = "0.0.0+local"
+
+from .main import compute, compute_args  # noqa: F401
+from .utils import get_adapter  # noqa: F401

qccompute/adapters/__init__.py

@@ -0,0 +1,12 @@
+"""Must import all adapters here for them to be found by the AdapterRegistry."""
+
+from .base import *  # noqa: F403
+from .crest import CRESTAdapter  # noqa: F401
+from .file import FileAdapter  # noqa: F401
+from .geometric import GeometricAdapter  # noqa: F401
+from .orca import OrcaAdapter  # noqa: F401
+from .qcengine import QCEngineAdapter  # noqa: F401
+from .terachem import TeraChemAdapter  # noqa: F401
+from .terachem_fe import TeraChemFEAdapter  # noqa: F401
+from .terachem_pbs import TeraChemPBSAdapter  # noqa: F401
+from .xtb import XTBAdapter  # noqa: F401

qccompute/adapters/base.py

@@ -0,0 +1,325 @@
+import traceback
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from time import time
+from typing import Any, Generic
+
+from qcdata import (
+    CalcType,
+    Data,
+    DataType,
+    FileInput,
+    Files,
+    InputType,
+    ProgramOutput,
+    StructuredInputs,
+)
+from qcdata.helper_types import StrOrPath
+
+from qccompute.exceptions import (
+    AdapterInputError,
+    ProgramNotFoundError,
+    QCComputeBaseError,
+)
+
+from .utils import construct_provenance, tmpdir
+
+__all__ = ["BaseAdapter", "registry"]
+
+# Registry for all Adaptors.
+# NOTE: Registry stores class objects, not instances.
+# Use registry[program]() to instantiate an adaptor
+# Or use the higher level qccompute.utils.get_adapter() function.
+registry = {}
+
+
+class BaseAdapter(ABC, Generic[InputType, DataType]):
+    """Base class for all adapters."""
+
+    # Whether to this program reads or writes files to disk.
+    # If True, the adapter will write all files from input_data to a disk before executing
+    # the program. If False, the adapter must handle input files itself in some other
+    # way. Generally this should be True for most adapters unless the program can
+    # handle input files directly from memory, stdin, or some other mechanism that is
+    # more efficient than writing to disk.
+    uses_files = True
+    program: str  # All subclasses must define this attribute.
+
+    def program_version(self, stdout: str | None) -> str | None:
+        """Return program version. Adapters should override this method.
+
+        Args:
+            stdout: The stdout from the program. Because running "program --version"
+                can be extremely slow for some programs, the stdout from the program
+                is passed in here so that the version can be extracted from it if
+                possible. If the version cannot be extracted from the stdout, then
+                this function should return the program version in some other way.
+        """
+        return None
+
+    @abstractmethod
+    def validate_input(self, input_data: InputType) -> None:
+        """Validate input_data to ensure compatibility with adapter.
+        Adapters should override this method.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def compute_data(
+        self,
+        input_data: InputType,
+        update_func: Callable | None = None,
+        update_interval: float | None = None,
+        **kwargs,
+    ) -> tuple[DataType, str]:
+        """Subclasses should implement this method with custom compute logic."""
+        raise NotImplementedError
+
+    def compute(
+        self,
+        input_data: InputType,
+        *,
+        scratch_dir: StrOrPath | None = None,
+        rm_scratch_dir: bool = True,
+        collect_logs: bool = True,
+        collect_files: bool = False,
+        collect_wfn: bool = False,
+        update_func: Callable | None = None,
+        update_interval: float | None = None,
+        print_logs: bool = False,
+        raise_exc: bool = True,
+        propagate_wfn: bool = False,
+        **adapter_kwargs,
+    ) -> ProgramOutput[InputType, DataType]:
+        """Compute the given input using the adapter's program.
+
+        Args:
+            input_data: A qcdata input object for a computation. E.g. A FileInput,
+                ProgramInput or DualProgramInput.
+            scratch_dir: The scratch directory for the program. If None, a new directory
+                is created in the system default temporary directory. If rm_scratch_dir
+                is True this directory will be deleted after the program finishes.
+            rm_scratch_dir: Delete the scratch directory after the program exits.
+            collect_logs: Whether to collect stdout/stderr from the program as output.
+                Failed computations will always collect stdout/stderr.
+            collect_files: Collect all files generated by the QC program as output.
+            collect_wfn: Collect the wavefunction file(s) from the calculation.
+                Not every program will support this. Use collect_files to collect
+                all files including the wavefunction.
+            update_func: A function to call as the program executes. The function must
+                accept the in-process stdout/stderr output as a string for its first
+                argument.
+            update_interval: The minimum time in seconds between calls to the
+                update_func.
+            print_logs: Whether to print stdout/stderr to the terminal in real time as
+                the program executes. Will be ignored if an update_func passed.
+            raise_exc: If False, qccompute will return a ProgramOutput object when the QC
+                program fails rather than raise an exception.
+            propagate_wfn: For any adapter performing a sequential task, such
+                as a geometry optimization, propagate the wavefunction from the previous
+                step to the next step. This is useful for accelerating convergence by
+                using a previously computed wavefunction as a starting guess. If an
+                adapter does not support wavefunction propagation, an AdapterInputError
+                will be raised.
+            **adapter_kwargs: Additional keyword arguments to pass to the adapter or
+                qcng.compute().
+
+        Returns:
+            A ProgramOutput object containing the results of the computation.
+
+        Raises:
+            AdapterNotFoundError: If the program is not supported (i.e., no Adapter
+                is implemented for the program in qccompute or qcengine).
+            ProgramNotFoundError: If the program executable is not found on the
+                system at execution time. This likely means the program is not installed
+                or not available on the $PATH.
+            AdapterInputError: If the input is invalid for the adapter.
+            ExternalProgramExecutionError: If the QC program fails during execution.
+            QCEngineError: If QCEngine performs the computation raises an error.
+        """
+        # Print stdout to terminal in real time as program executes
+        if print_logs and update_func is None:
+            update_func, update_interval = (
+                lambda _, stdout_new: print(stdout_new),
+                0.1,
+            )
+
+        # cd to a temporary directory to run the program.
+        with tmpdir(self.uses_files, scratch_dir, rm_scratch_dir) as final_scratch_dir:
+            if self.uses_files:  # Write non structured input files to disk.
+                input_data.save_files()
+
+            # Define outputs
+            prog_output_dict: dict[str, Any] = {}
+            logs: str | None = None
+            data: Data
+            exc: QCComputeBaseError | None = None
+            program_version: str | None = None
+
+            start = time()
+            try:
+                # Validate input object
+                self.validate_input(input_data)
+
+                # Execute the program. data will be Files for FileInput
+                data, logs = self.compute_data(
+                    input_data,
+                    update_func,
+                    update_interval,
+                    propagate_wfn=propagate_wfn,
+                    **adapter_kwargs,
+                )
+                # None value covers FileInput case
+                prog_output_dict["success"] = True
+
+                # Optionally collect wavefunction file
+                if collect_wfn and not collect_files:
+                    data.files.update(self.collect_wfn())
+
+            except QCComputeBaseError as e:
+                exc = e
+                prog_output_dict["success"] = False
+                # Any half-completed data
+                data = getattr(e, "data") or Files()
+                logs = getattr(e, "logs", logs) or logs
+                # For mypy because e.logs is not of a known type
+                logs = str(logs) if logs is not None else None
+                prog_output_dict["traceback"] = traceback.format_exc()
+
+            wall_time = time() - start
+
+            # Check for parsed version in extras at default location
+            program_version = data.extras.get("program_version")
+            if not program_version:
+                try:
+                    program_version = self.program_version(logs)
+                except ProgramNotFoundError:
+                    pass  # program_version = None set above
+
+            # Construct Provenance object
+            provenance = construct_provenance(
+                self.program,
+                program_version,
+                final_scratch_dir,
+                wall_time,
+            )
+
+            # Always collect for failures; otherwise obey collect_logs
+            logs = logs if not prog_output_dict["success"] or collect_logs else None
+
+            # Construct ProgramOutput
+            prog_output_dict.update(
+                {
+                    "input_data": input_data,
+                    "logs": logs,
+                    "data": data,
+                    "provenance": provenance,
+                }
+            )
+            prog_output = ProgramOutput[InputType, DataType](**prog_output_dict)
+
+            # Collect files generated by the program
+            if self.uses_files and (collect_files or type(input_data) is FileInput):
+                prog_output.data.add_files(
+                    final_scratch_dir,
+                    recursive=True,
+                    exclude=list(input_data.files.keys()),
+                )
+
+        # Append ProgramOutput to exception and raise if raise_exc=True
+        # Helpful for BigChem and ChemCloud exception handling
+        if raise_exc and exc:
+            exc.prog_output = prog_output
+            raise exc
+
+        return prog_output
+
+    def collect_wfn(self) -> dict[str, str | bytes]:
+        """Collect the wavefunction file(s) from the scratch_dir.
+
+        Returns:
+            Dictionary of filenames and file data. E.g. {"c0": b"filedata"}
+
+        """
+        # Collect wavefunction file from the calc_dir
+        raise AdapterInputError(
+            program=self.program,
+            message=f"Adapter for {self.program} does not support wavefunction collection.",
+        )
+
+
+class ProgramAdapter(BaseAdapter, Generic[InputType, DataType]):
+    """Base adapter for all program adapters (all but FileAdaptor)."""
+
+    supported_calctypes: list[
+        CalcType
+    ]  # All subclasses must specify supported calctypes
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        # Ensure that subclasses define the required class attributes
+        if not getattr(cls, "program", None):
+            raise NotImplementedError(
+                f"Subclasses of {ProgramAdapter.__name__} must define a program "
+                f"string. {cls.__name__} does not meet this requirement."
+            )
+
+        # Automatically register all subclasses
+        registry[cls.program] = cls
+
+        if not getattr(cls, "supported_calctypes", None):
+            raise NotImplementedError(
+                f"Subclasses of {ProgramAdapter.__name__} must define a nonempty "
+                f"supported_calctypes list. {cls.__name__} does not meet this "
+                "requirement."
+            )
+
+    @abstractmethod
+    def program_version(self, stdout: str | None) -> str:
+        """Get the version of the program.
+
+        Args:
+            stdout: The stdout from the program. Because running "program --version"
+                can be extremely slow for some programs, the stdout from the program
+                is passed in here so that the version can be extracted from it if
+                possible. If the version cannot be extracted from the stdout, then
+                this function should return the program version in some other way.
+        """
+
+    @abstractmethod
+    def compute_data(
+        self,
+        input_data: InputType,
+        update_func: Callable | None = None,
+        update_interval: float | None = None,
+        **kwargs,
+    ) -> tuple[DataType, str]:
+        """All ProgramAdapters must return a DataType."""
+        raise NotImplementedError
+
+    def validate_input(self, input_data: StructuredInputs) -> None:
+        """Validate the input object for compatibility with the adapter.
+
+        Args:
+            input_data: The input object to validate.
+
+        Raises:
+            AdapterInputError: If the input object's calctype is not supported.
+        """
+        if input_data.calctype not in self.supported_calctypes:
+            raise AdapterInputError(
+                program=self.program,
+                message=(
+                    f"The {self.program} adapter does not yet support "
+                    f"'{input_data.calctype.value}' calculations. This adaptor can "
+                    f"compute: {[ct.value for ct in self.supported_calctypes]}"
+                ),
+            )
+        if input_data.files and not self.uses_files:
+            raise AdapterInputError(
+                program=self.program,
+                message=(
+                    f"The {self.program} adapter does not support files as additional "
+                    "inputs. Remove the files from your input."
+                ),
+            )

qccompute/adapters/crest.py

@@ -0,0 +1,134 @@
+"""Adapter for CREST package. https://crest-lab.github.io/crest-docs/"""
+
+from collections.abc import Callable
+from pathlib import Path
+
+import qccodec
+from qccodec.parsers.crest import parse_version
+from qcdata import (
+    CalcType,
+    ConformerSearchResults,
+    OptimizationResults,
+    ProgramInput,
+    SinglePointData,
+)
+
+from qccompute.exceptions import AdapterInputError, ExternalProgramError
+
+from .base import ProgramAdapter
+from .utils import execute_subprocess
+
+
+class CRESTAdapter(
+    ProgramAdapter[
+        ProgramInput,
+        SinglePointData | OptimizationResults | ConformerSearchResults,
+    ]
+):
+    """Adapter for CREST.
+
+    Note:
+        The `ProgramInput.keywords` attribute is used to create the input file for
+        CREST. This means that the structure of the `keywords` attribute should match
+        that of [CREST's input specification](https://crest-lab.github.io/crest-docs/page/documentation/inputfiles.html).
+        Keywords such as method, charge, and uhf (which are stored on the `Model` and
+        `Structure`; uhf is `multiplicity - 1`) will be added to the input file
+        automatically.
+
+    Warning:
+        CREST does not exit with a non-zero exit code on failure. Instead, it prints
+        "FAILED" in the stdout. This adapter will raise an ExternalProgramError if
+        "FAILED" is found in the stdout.
+
+    Warning:
+        CREST automatically translates the input geometry to the origin. This means
+        that the input geometry printed to CREST's stdout will not match the input
+        structure; however, all computed values (such as energies, gradients, etc.) are
+        still valid because they are translationally invariant.
+    """
+
+    supported_calctypes = [
+        CalcType.energy,
+        CalcType.gradient,
+        CalcType.hessian,
+        CalcType.optimization,
+        CalcType.conformer_search,
+    ]
+    """Supported calculation types."""
+    program = "crest"
+
+    def program_version(self, stdout: str | None = None) -> str:
+        """Get the program version.
+
+        Args:
+            stdout: The stdout from the program.
+
+        Returns:
+            The program version.
+        """
+        if not stdout:
+            stdout = execute_subprocess(self.program, ["--version"])
+        return parse_version(stdout)
+
+    def compute_data(
+        self,
+        input_data: ProgramInput,
+        update_func: Callable | None = None,
+        update_interval: float | None = None,
+        collect_rotamers: bool = False,
+        **kwargs,
+    ) -> tuple[SinglePointData | OptimizationResults | ConformerSearchResults, str]:
+        """Execute CREST on the given input.
+
+        Args:
+            input_data: The qcdata ProgramInput object for a computation.
+            update_func: A function to call with the stdout at regular intervals.
+            update_interval: The interval at which to call the update function.
+            collect_rotamers: Collect rotamers if doing a conformer_search. Defaults to
+                False since rotamers are usually not of interest and there will be many.
+
+        Returns:
+            A tuple of ConformerSearchResults and the stdout str.
+        """
+        # Create CREST native input files
+        try:
+            native_inp = qccodec.encode(input_data, self.program)
+        except qccodec.exceptions.EncoderError as e:
+            raise AdapterInputError(program=self.program) from e
+
+        # Write the input files to disk
+        inp_file, struct_file = Path("input.toml"), Path(native_inp.geometry_filename)
+        inp_file.write_text(native_inp.input_file)
+        struct_file.write_text(native_inp.geometry_file)
+
+        # Execute CREST
+        stdout = execute_subprocess(
+            self.program, [inp_file.name], update_func, update_interval
+        )
+
+        # CREST does not exit with a non-zero exit code on failure
+        if "FAILED" in stdout:
+            raise ExternalProgramError(
+                program=self.program,
+                message=f"CREST calculation failed. See the stdout for more information.",
+                logs=stdout,
+            )
+
+        # Parse the output
+        try:
+            results = qccodec.decode(
+                self.program,
+                input_data.calctype,
+                stdout=stdout,
+                directory=".",
+                input_data=input_data,
+            )
+        except qccodec.exceptions.ParserError as e:
+            raise ExternalProgramError(
+                program="qccodec",
+                message="Failed to parse CREST output.",
+                logs=stdout,
+                original_exception=e,
+            ) from e
+
+        return results, stdout

qccompute/adapters/file.py

@@ -0,0 +1,49 @@
+from collections.abc import Callable
+
+from qcdata import FileInput, Files
+
+from qccompute.adapters.base import BaseAdapter
+
+from .utils import execute_subprocess
+
+
+class FileAdapter(BaseAdapter[FileInput, Files]):
+    """adapter for running a program on files."""
+
+    def __init__(self, program: str) -> None:
+        super().__init__()
+        self.program = program
+
+    def validate_input(self, input_data: FileInput) -> None:
+        """No validation checks performed for FileAdapter"""
+        pass
+
+    def compute_data(
+        self,
+        input_data: FileInput,
+        update_func: Callable | None = None,
+        update_interval: float | None = None,
+        **kwargs,
+    ) -> tuple[Files, str]:
+        """Compute the given program on the given files.
+
+        Args:
+            input_data: The qcdata FileInput object for a computation.
+            update_func: A callback function to call as the program executes.
+            update_interval: The minimum time in seconds between calls to the
+            update_func.
+
+        Returns:
+            Tuple of a `Files` object and the program output string for a
+            computation. The returned `Files` instance is initially empty and
+            will be populated with file data by the :meth:`.compute` method.
+
+        Raises:
+            ProgramNotFoundException: If the program is not found.
+
+        """
+        stdout = execute_subprocess(
+            self.program, input_data.cmdline_args, update_func, update_interval
+        )
+        # Files will be added to this object by the .compute() method
+        return Files(), stdout