aiida-chemshell 0.3.0__tar.gz → 0.3.2__tar.gz

{aiida_chemshell-0.3.0/src/aiida_chemshell.egg-info → aiida_chemshell-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiida-chemshell
-Version: 0.3.0
+Version: 0.3.2
 Summary: AiiDA workflow plugin for the ChemShell chemical modelling software package
 Author-email: "Dr. Benjamin T. Speake" <benjamin.speake@stfc.ac.uk>
 License: BSD 3-Clause License
@@ -42,6 +42,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiida-core>=2.5
+Requires-Dist: ase>=3.29
 Provides-Extra: dev
 Requires-Dist: aiida-core>=2.8; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"

{aiida_chemshell-0.3.0 → aiida_chemshell-0.3.2}/pyproject.toml

@@ -3,13 +3,13 @@ requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
 
 [project]
-version = "0.3.0"
+version = "0.3.2"
 name = "aiida-chemshell"
 description = "AiiDA workflow plugin for the ChemShell chemical modelling software package"
 authors = [
     { name = "Dr. Benjamin T. Speake", email = "benjamin.speake@stfc.ac.uk" },
 ]
-dependencies = ["aiida-core >= 2.5"]
+dependencies = ["aiida-core >= 2.5", "ase>=3.29"]
 readme = "README.md"
 license = { file = "LICENSE" }
 keywords = ["aiida", "workflows", "chemshell"]

{aiida_chemshell-0.3.0 → aiida_chemshell-0.3.2}/src/aiida_chemshell/calculations/base.py

@@ -36,6 +36,47 @@ class ChemShellCalculation(CalcJob):
     FILE_TRJPTH = "path.xyz"
     FILE_TRJFRC = "path_force.xyz"
 
+    # Default labels and descriptions applied to input nodes that do not already
+    # have them set, keyed by the input port name.
+    DEFAULT_INPUT_TAGS = {
+        "structure": (
+            "Input Chemical Structure",
+            "The input structure for the ChemShell calculation.",
+        ),
+        "structure_index": (
+            "Structure Input Index",
+            "Index used to select a structure from a multi-structure input.",
+        ),
+        "structure2": (
+            "Secondary Input Structure",
+            "The additional (final) input structure for the ChemShell calculation.",
+        ),
+        "calculation_parameters": (
+            "ChemShell Calculation Parameters",
+            "Base parameters for the ChemShell Task object.",
+        ),
+        "optimisation_parameters": (
+            "ChemShell Optimisation Parameters",
+            "Parameters for the ChemShell geometry optimisation task.",
+        ),
+        "qm_parameters": (
+            "ChemShell QM Parameters",
+            "Parameters for the ChemShell QM Theory object.",
+        ),
+        "mm_parameters": (
+            "ChemShell MM Parameters",
+            "Parameters for the ChemShell MM interface.",
+        ),
+        "force_field_file": (
+            "ChemShell Force Field File",
+            "Force field parameters for the ChemShell MM interface.",
+        ),
+        "qmmm_parameters": (
+            "ChemShell QM/MM Parameters",
+            "Parameters for the ChemShell QM/MM interface.",
+        ),
+    }
+
     @classmethod
     def define(cls, spec: CalcJobProcessSpec) -> None:
         """
@@ -136,6 +177,17 @@ class ChemShellCalculation(CalcJob):
             required=False,
             help="A dictionary of parameters for the ChemShell QM/MM interface.",
         )
+        spec.input(
+            "output_structure_as_file",
+            valid_type=bool,
+            non_db=True,
+            default=False,
+            help=(
+                "If True, the optimised structure is returned as a SinglefileData "
+                "node containing a ChemShell '.cjson' file. By default (False) it is "
+                "returned as an AiiDA StructureData node."
+            ),
+        )
 
         ## Calculation outputs
         spec.output(
@@ -156,12 +208,14 @@ class ChemShellCalculation(CalcJob):
         )
         spec.output(
             "optimised_structure",
-            valid_type=SinglefileData,
+            valid_type=(StructureData, SinglefileData),
             required=False,
             help=(
                 "The optimised structure of the given system, if a geometry "
-                "optimisation task was configured and successfully completed. The "
-                "structure is contained within a ChemShell '.pun' file."
+                "optimisation task was configured and successfully completed. By "
+                "default this is an AiiDA StructureData node; if the "
+                "'output_structure_as_file' input is True it is instead a "
+                "SinglefileData node containing a ChemShell '.cjson' file."
             ),
         )
         spec.output(
@@ -182,7 +236,10 @@ class ChemShellCalculation(CalcJob):
             "vibrational_modes",
             valid_type=ArrayData,
             required=False,
-            help="The calculated vibrational modes of the system.",
+            help=(
+                "The calculated vibrational modes of the system. A negative "
+                "frequency indicates an imaginary frequency."
+            ),
         )
 
         # Validate inputs namespace
@@ -209,11 +266,11 @@ class ChemShellCalculation(CalcJob):
         )
         spec.output(
             "trajectory_force",
-            valid_type=SinglefileData,
+            valid_type=ArrayData,
             required=False,
             help=(
-                "XYZ style trajectory file containing forces at each step of a geometry"
-                " optimisation."
+                "Per-atom forces (natoms, 3) at each step of a geometry optimisation, "
+                "stored one array per frame labelled 'Frame {i}'."
             ),
         )
 
@@ -324,13 +381,13 @@ class ChemShellCalculation(CalcJob):
         return None
 
     @classmethod
-    def get_valid_calculation_parameter_keys(cls) -> tuple[str]:
+    def get_valid_calculation_parameter_keys(cls) -> tuple[str, str]:
         """
         Return the valid parameter keys for the ChemShell Single Point calculation.
 
         Returns
         -------
-         : tuple[str]
+        tuple[str, str]
             A tuple of valid parameter keys for the ChemShell calculation.
         """
         return ("gradients", "hessian")
@@ -379,7 +436,7 @@ class ChemShellCalculation(CalcJob):
 
         Returns
         -------
-         : tuple[str]
+        tuple[str]
             A tuple of valid optimisation parameter keys for the ChemShell
             calculation.
         """
@@ -437,12 +494,13 @@ class ChemShellCalculation(CalcJob):
     @classmethod
     def get_valid_qm_parameter_keys(cls) -> dict:
         """
-        Return a tuple of valid parameter keys for the ChemShell calculation.
+        Return a dictionary of valid parameter keys for the ChemShell calculation.
 
         Returns
         -------
-        validKeys : dict[str: type]
-            A tuple of valid Theory parameter keys for the ChemShell calculation.
+        dict[str, type]
+            A mapping of valid Theory parameter keys to their expected value
+            types for the ChemShell calculation.
         """
         return {
             "theory": str,
@@ -527,14 +585,21 @@ class ChemShellCalculation(CalcJob):
         return None
 
     @classmethod
-    def get_valid_mm_parameter_keys(cls, theory: str = "") -> dict[str:type]:
+    def get_valid_mm_parameter_keys(cls, theory: str = "") -> dict[str, type]:
         """
-        Return a tuple of valid parameter keys for the ChemShell MM interface.
+        Return a dictionary of valid parameter keys for the ChemShell MM interface.
+
+        Parameters
+        ----------
+        theory : str
+            The MM theory whose valid parameter keys should be returned (e.g.
+            'DL_POLY'). Defaults to an empty string.
 
         Returns
         -------
-        validKeys : dict[str: type]
-            A tuple of valid MM parameter keys for the ChemShell calculation.
+        dict[str, type]
+            A mapping of valid MM parameter keys to their expected value types
+            for the ChemShell calculation.
         """
         if theory == "DL_POLY":
             valid_keys = {
@@ -754,6 +819,12 @@ class ChemShellCalculation(CalcJob):
         Defines the process label to be associated with the created ProcessNode
         stored in the AiiDA database.
 
+        Parameters
+        ----------
+        node : ProcessNode
+            The process (or its ProcessNode) whose inputs are inspected to build
+            the label.
+
         Returns
         -------
         str
@@ -771,6 +842,8 @@ class ChemShellCalculation(CalcJob):
         if "optimisation_parameters" in node.inputs:
             if node.inputs.optimisation_parameters.get("thermal", False):
                 return "ChemShell_Vibrational_Frequencies" + theory_key
+            if node.inputs.optimisation_parameters.get("neb", "no") != "no":
+                return "ChemShell_NEB" + theory_key
             return "ChemShell_Geometry_Optimisation" + theory_key
 
         return "ChemShell_Single_Point_Calculation" + theory_key
@@ -820,7 +893,6 @@ class ChemShellCalculation(CalcJob):
                 fname = self.inputs.structure2.filename
             else:
                 fname = ChemShellCalculation.FILE_TMP_STRUCTURE2
-            print(fname)
             script += f"frg2 = Fragment(coords='{fname:s}')\n"
 
         ## Setup Theory objects
@@ -933,12 +1005,31 @@ class ChemShellCalculation(CalcJob):
 
         return script
 
+    def apply_default_input_tags(self) -> None:
+        """
+        Apply default labels and descriptions to the calculation input nodes.
+
+        Iterates over the provided input nodes and, for any node defined in
+        :attr:`DEFAULT_INPUT_TAGS` that does not already have a label or
+        description set, assigns the corresponding default value. Existing
+        labels and descriptions are left untouched.
+        """
+        for port_name, (label, description) in self.DEFAULT_INPUT_TAGS.items():
+            if port_name not in self.inputs:
+                continue
+            node = self.inputs[port_name]
+            if not node.label:
+                node.label = label
+                if not node.description:
+                    node.description = description
+        return
+
     def prepare_for_submission(self, folder: Folder) -> CalcInfo:
         """
         Prepare the ChemShell calculation for submission.
 
-        Params
-        ------
+        Parameters
+        ----------
         folder : Folder
             An `aiida.common.folders.Folder` specifying the temporary working
             directory for the calculation.
@@ -948,6 +1039,16 @@ class ChemShellCalculation(CalcJob):
         calcInfo : CalcInfo
             An `aiida.common.CalcInfo` instance.
         """
+        # Apply default labels/descriptions to input nodes lacking them
+        self.apply_default_input_tags()
+
+        # Record the (non_db) output structure format choice as a node extra so
+        # that the parser can determine whether to return the optimised structure
+        # as a StructureData or SinglefileData node.
+        self.node.base.extras.set(
+            "output_structure_as_file", bool(self.inputs.output_structure_as_file)
+        )
+
         # Create the ChemShell input script
         input_script = self.chemsh_script_generator()
         with folder.open(ChemShellCalculation.FILE_SCRIPT, "w") as f:
@@ -1005,7 +1106,7 @@ class ChemShellCalculation(CalcJob):
         # Copy data for second input fragment if required
         if "structure2" in self.inputs:
             if isinstance(self.inputs.structure2, StructureData):
-                with folder.open(ChemShellCalculation.FILE_TMP_STRUCTURE, "wb") as f:
+                with folder.open(ChemShellCalculation.FILE_TMP_STRUCTURE2, "wb") as f:
                     f.write(self.inputs.structure2._prepare_xyz()[0])
             else:
                 calc_info.local_copy_list.append(

aiida_chemshell-0.3.2/src/aiida_chemshell/calculations/utils.py

@@ -0,0 +1,307 @@
+"""A collection of smaller utility AiiDA CalcFunctions."""
+
+import re
+from io import BytesIO
+
+from aiida.engine import calcfunction
+from aiida.orm import (
+    ArrayData,
+    Dict,
+    Float,
+    SinglefileData,
+    StructureData,
+    TrajectoryData,
+)
+
+
+@calcfunction
+def create_isolated_atom_structures(structure) -> dict[str, StructureData]:
+    """
+    Create an isolated single-atom StructureData for each unique atom type.
+
+    The unique atom types present in ``structure`` are determined and, for each,
+    a non-periodic StructureData node containing a single atom at the origin is
+    created.
+
+    Parameters
+    ----------
+    structure : StructureData | SinglefileData
+        The input structure to extract isolated atomic species from. Either a
+        StructureData node or a SinglefileData node wrapping a structure file in
+        any format readable by ``ase.io.read``.
+
+    Returns
+    -------
+    dict[str, StructureData]
+        A mapping of atom type to its isolated single-atom StructureData node.
+        As a calcfunction return value, this is registered as a namespace of
+        output nodes, with the atom type used as the output link label.
+
+    Raises
+    ------
+    Exception
+        If the structure file format is not supported by the ASE reader.
+    """
+    unique_atoms = _determine_unique_atoms(structure)
+    structures = {}
+    for atom_symbol in unique_atoms:
+        atom = StructureData()
+        atom.append_atom(position=(0.0, 0.0, 0.0), symbols=atom_symbol)
+        atom.set_pbc((False, False, False))
+        atom.label = f"{atom_symbol} atom"
+        atom.description = (
+            f"Isolated {atom_symbol} atom extracted from Node: {structure.pk}"
+        )
+        structures[atom_symbol] = atom
+    return structures
+
+
+def _determine_unique_atoms(structure: SinglefileData | StructureData) -> list[str]:
+    """Determine all unique atom types within the given structure."""
+    if isinstance(structure, StructureData):
+        return _atom_types_from_structuredata(structure)
+    return _atom_types_from_file(structure)
+
+
+def _atom_types_from_structuredata(structure: StructureData) -> list[str]:
+    """Determine the unique atom types from a StructureData object."""
+    unique_atoms: list[str] = []
+    for site in structure.sites:
+        if site.kind_name not in unique_atoms:
+            unique_atoms.append(site.kind_name)
+    return unique_atoms
+
+
+def _atom_types_from_file(structure: SinglefileData) -> list[str]:
+    """Determine the unique atom types from a SinglefileData object using ASE."""
+    import os
+    import tempfile
+
+    from ase.io import read
+    from ase.io.formats import UnknownFileTypeError
+
+    suffix = os.path.splitext(structure.filename)[1]
+    with tempfile.NamedTemporaryFile(suffix=suffix) as tmp:
+        with structure.open(mode="rb") as f:
+            tmp.write(f.read())
+        tmp.flush()
+        try:
+            atoms = read(tmp.name)
+        except UnknownFileTypeError as e:
+            raise Exception(
+                f"Unsupported structure file format for isolated atom extraction: "
+                f"{structure.filename}"
+            ) from e
+    return list(dict.fromkeys(atoms.get_chemical_symbols()))
+
+
+@calcfunction
+def create_atomic_energy_dictionary(atoms, energies) -> Dict:
+    """Collate a series of isolated atom energies into a dictionary output."""
+    if len(atoms) != len(energies):
+        raise ValueError(
+            f"Mismatched lengths: Got {len(atoms)} atoms and {len(energies)} energies."
+        )
+    return Dict(dict(zip(atoms, energies, strict=False)))
+
+
+@calcfunction
+def extract_structures_from_xyz(file: SinglefileData) -> dict[str, StructureData]:
+    """
+    Split a multi-frame XYZ file into individual StructureData nodes.
+
+    Each frame in the (optionally extended) XYZ file is parsed into its own
+    StructureData node. Extended XYZ 'Lattice=' and 'pbc=' fields on the comment
+    line are honoured when present; frames without them are treated as
+    non-periodic.
+
+    Parameters
+    ----------
+    file : SinglefileData
+        A SinglefileData node wrapping an XYZ (or extended XYZ) file that may
+        contain one or more frames.
+
+    Returns
+    -------
+    dict[str, StructureData]
+        A mapping of output link labels to StructureData nodes, one per frame.
+        Keys are of the form '<filename>_frame_<index>' (zero-indexed, with
+        spaces in the filename replaced by underscores). As a calcfunction
+        return value, this dictionary is registered as a namespace of output
+        nodes.
+
+    Raises
+    ------
+    Exception
+        If the file is not valid XYZ, is truncated, or contains a malformed
+        atom line.
+    """
+    with file.open(mode="r") as f:
+        lines = f.readlines()
+
+    structures = {}
+    line_count = len(lines)
+    i = 0
+    frame_idx = 0
+
+    while i < line_count:
+        line = lines[i].strip()
+        try:
+            natoms = int(line)
+        except ValueError as e:
+            raise Exception("Invalid XYZ format detected.") from e
+        if (i + 2 + natoms) > line_count:
+            raise Exception("XYZ file truncation detected.")
+
+        # Create the base StructureData object
+        structure = StructureData(pbc=(False, False, False))
+
+        # Read the comment line
+        i += 1
+        line = lines[i].strip()
+        cell = None
+        if "Lattice=" in line:
+            match = re.search(r'Lattice="([^"]+)"', line)
+            if match:
+                lat_vals = [float(x) for x in match.group(1).split()]
+                if len(lat_vals) == 9:
+                    cell = [lat_vals[0:3], lat_vals[3:6], lat_vals[6:9]]
+            pbc = [True, True, True]
+            if "pbc=" in line:
+                match_pbc = re.search(r'pbc="([^"]+)"', line)
+                if match_pbc:
+                    pbc_vals = match_pbc.group(1).split()
+                    if len(pbc_vals) == 3:
+                        # Robust check: converts 'T', 'True', or '1' to True
+                        pbc = [val.upper() in ["T", "TRUE", "1"] for val in pbc_vals]
+
+            # Assign the parse cell parameters to the StructureData object
+            structure.cell = cell
+            structure.pbc = pbc
+
+        i += 1
+        for atmi in range(natoms):
+            atom_line = lines[i + atmi].strip().split()
+            if len(atom_line) < 4:
+                raise Exception(
+                    f"Invalid atom entry in xyz file: {line[i + atmi].strip()}"
+                )
+
+            structure.append_atom(
+                position=[
+                    float(atom_line[1]),
+                    float(atom_line[2]),
+                    float(atom_line[3]),
+                ],
+                symbols=atom_line[0],
+            )
+
+        structures[
+            f"{file.filename.replace(' ', '_').strip('.xyz')}_frame_{frame_idx}"
+        ] = structure
+        frame_idx += 1
+        i += natoms
+
+    return structures
+
+
+@calcfunction
+def combine_into_extended_xyz(
+    **kwargs: StructureData | TrajectoryData | Float | ArrayData,
+) -> SinglefileData:
+    """
+    Collate a batch of single-point results into one extended XYZ file.
+
+    The keyword nodes are sorted by type into three parallel lists: structures
+    (from StructureData, or each frame of a TrajectoryData), energies (Float)
+    and, optionally, force arrays (ArrayData). They are then written out as an
+    extended XYZ file with an 'Energy=' label per frame and, when forces are
+    supplied, a 'force' property column. The lists are paired positionally, so
+    the caller is responsible for passing matched sets of nodes (equal numbers
+    of structures, energies and, if used, arrays).
+
+    Parameters
+    ----------
+    **kwargs : StructureData | TrajectoryData | Float | ArrayData
+        Arbitrary keyword arguments whose values are the result nodes to
+        combine. Only the values are used; the keys are ignored. Forces are read
+        from the 'gradients' array of any ArrayData node.
+
+    Returns
+    -------
+    SinglefileData
+        A SinglefileData node wrapping the combined
+        'chemshell_batch_workchain.extxyz' file.
+
+    Raises
+    ------
+    ValueError
+        If an unsupported node type is passed, if no structures are provided, or
+        if the numbers of structures, energies and (when given) arrays do not
+        match.
+    """
+    structures: list[StructureData] = []
+    energies: list[Float] = []
+    arrays: list[ArrayData] = []
+
+    # Extract individual structures and SP calculation results.
+    for _key, node in kwargs.items():
+        if isinstance(node, TrajectoryData):
+            for tindex in range(node.numsteps):
+                structures.append(node.get_step_structure(tindex))
+        elif isinstance(node, StructureData):
+            structures.append(node)
+        elif isinstance(node, Float):
+            energies.append(node)
+        elif isinstance(node, ArrayData):  # Ensure after TrajectoryData !!
+            arrays.append(node)
+        else:
+            raise ValueError(
+                f"Invalid input of type {node} to 'combine_into_extended_xyz' "
+                "calcfunction."
+            )
+    if not structures:
+        raise ValueError("No StructureData nodes were provided.")
+    if len(structures) != len(energies):
+        raise ValueError(
+            f"Mismatched input lengths: received {len(structures)} structures and "
+            f"{len(energies)} energies."
+        )
+    if arrays:
+        if len(arrays) != len(energies):
+            raise ValueError(
+                f"Mismatched input lengths: received {len(arrays)} arrays and "
+                f"{len(energies)} energies."
+            )
+
+    xyz_lines = []
+
+    for i in range(len(structures)):
+        structure = structures[i]
+        energy = energies[i]
+
+        xyz_lines.append(str(len(structure.sites)))
+
+        header_line = f"Energy={energy.value}"
+        if arrays:
+            forces = arrays[i].get_array("gradients")
+            header_line += " Properties=species:S:1:pos:R:3:force:R:3"
+        else:
+            forces = None
+            header_line += " Properties=species:S:1:pos:R:3"
+        xyz_lines.append(header_line)
+
+        for j, site in enumerate(structure.sites):
+            kind = structure.get_kind(site.kind_name)
+            symbol = kind.symbols[0]
+            x, y, z = site.position
+            site_line = f"{symbol:<4} {x:15.8f} {y:15.8f} {z:15.8f}"
+            if forces is not None:
+                fx, fy, fz = forces[j]
+                site_line += f" {fx:15.8f} {fy:15.8f} {fz:15.8f}"
+            xyz_lines.append(site_line)
+
+    content = "\n".join(xyz_lines)
+    stream = BytesIO(content.encode("utf-8"))
+
+    return SinglefileData(file=stream, filename="chemshell_batch_workchain.extxyz")