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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiida-chemshell
-Version: 0.3.0
+Version: 0.3.1
 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

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

@@ -3,7 +3,7 @@ requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
 
 [project]
-version = "0.3.0"
+version = "0.3.1"
 name = "aiida-chemshell"
 description = "AiiDA workflow plugin for the ChemShell chemical modelling software package"
 authors = [

{aiida_chemshell-0.3.0 → aiida_chemshell-0.3.1}/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(
@@ -209,11 +263,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 +378,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 +433,7 @@ class ChemShellCalculation(CalcJob):
 
         Returns
         -------
-         : tuple[str]
+        tuple[str]
             A tuple of valid optimisation parameter keys for the ChemShell
             calculation.
         """
@@ -437,12 +491,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 +582,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 +816,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
@@ -933,12 +1001,30 @@ 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
+
     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 +1034,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:

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

@@ -0,0 +1,226 @@
+"""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_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")

{aiida_chemshell-0.3.0 → aiida_chemshell-0.3.1}/src/aiida_chemshell/parsers/base.py

@@ -10,6 +10,7 @@ from aiida.orm import ArrayData, Dict, Float, SinglefileData, TrajectoryData
 from aiida.parsers.parser import Parser
 
 from aiida_chemshell.calculations.base import ChemShellCalculation
+from aiida_chemshell.utils import chemsh_cjson_to_structure_data
 
 
 class ChemShellParser(Parser):
@@ -31,7 +32,17 @@ class ChemShellParser(Parser):
 
         # Extract the final energy
         try:
-            self.out("energy", Float(results["energy"][0], label="Final SCF Energy"))
+            self.out(
+                "energy",
+                Float(
+                    results["energy"][0],
+                    label="Final SCF Energy",
+                    description=(
+                        "The total (final SCF) energy of the system calculated by "
+                        "ChemShell."
+                    ),
+                ),
+            )
         except (KeyError, ValueError):
             return self.exit_codes.ERROR_MISSING_FINAL_ENERGY
         except ModificationNotAllowed as e:
@@ -91,17 +102,25 @@ class ChemShellParser(Parser):
                 if isinstance(self.node.inputs.structure, SinglefileData):
                     input_fname = self.node.inputs.structure.filename
                     descrip += f" ({input_fname})"
-                # Store the optimised structure file
-                with open(dl_find_path, "rb") as f:
-                    self.out(
-                        "optimised_structure",
-                        SinglefileData(
-                            file=f,
-                            filename=ChemShellCalculation.FILE_DLFIND,
-                            label="CJSON Structure File",
-                            description=descrip,
-                        ),
-                    )
+                # Store the optimised structure either as a SinglefileData '.cjson'
+                # file or (by default) as an AiiDA StructureData node.
+                if self.node.base.extras.get("output_structure_as_file", False):
+                    with open(dl_find_path, "rb") as f:
+                        self.out(
+                            "optimised_structure",
+                            SinglefileData(
+                                file=f,
+                                filename=ChemShellCalculation.FILE_DLFIND,
+                                label="CJSON Structure File",
+                                description=descrip,
+                            ),
+                        )
+                else:
+                    with open(dl_find_path, "rb") as f:
+                        structure = chemsh_cjson_to_structure_data(f.read())
+                    structure.label = "Optimised Structure"
+                    structure.description = descrip
+                    self.out("optimised_structure", structure)
                 self.parse_optimisation_path(
                     self.retrieved.get_object_content(
                         ChemShellCalculation.FILE_STDOUT, "r"
@@ -115,17 +134,7 @@ class ChemShellParser(Parser):
                 trj_frc_path = retrieved_tmp_folder / ChemShellCalculation.FILE_TRJFRC
                 if trj_path.exists():
                     self.parse_xyz_path(trj_path, "trajectory_path")
-                    with open(trj_frc_path, "rb") as f:
-                        self.out(
-                            "trajectory_force",
-                            SinglefileData(
-                                file=f,
-                                filename=ChemShellCalculation.FILE_TRJFRC.replace(
-                                    "/", "_"
-                                ),
-                                label="ChemShell optimisation trajectory.",
-                            ),
-                        )
+                    self.parse_xyz_forces(trj_frc_path, "trajectory_force")
                 else:
                     return self.exit_codes.ERROR_MISSING_OPTIMISED_STRUCTURE_FILE
 
@@ -161,7 +170,17 @@ class ChemShellParser(Parser):
                 read = True
             elif "total S vib" in line:
                 read = False
-        self.out("vibrational_energies", Dict(energies))
+        self.out(
+            "vibrational_energies",
+            Dict(
+                energies,
+                label="Thermochemical Properties",
+                description=(
+                    "Thermochemical properties (ZPE, enthalpy, entropy, etc.) "
+                    "calculated by ChemShell."
+                ),
+            ),
+        )
         modes = numpy.asarray(modes)
         modes_data_node = ArrayData(
             label="Vibrational Modes",
@@ -214,6 +233,47 @@ class ChemShellParser(Parser):
         self.out(output_link, path)
         return
 
+    def parse_xyz_forces(self, file_path: Path, output_link: str) -> None:
+        """
+        Parse an XYZ style forces trajectory into an AiiDA ArrayData node.
+
+        Each frame is stored as a separate '(natoms, 3)' array labelled
+        'Frame_{i}' (zero-indexed). An underscore is used in place of a space as
+        AiiDA array names may only contain digits, letters and underscores.
+
+        Parameters
+        ----------
+        file_path : Path
+            Path to the XYZ style forces trajectory file to parse.
+        output_link : str
+            The output link label under which the resulting ArrayData node is
+            attached to the calculation.
+        """
+        with open(file_path) as f:
+            lines = f.readlines()
+        natoms = int(lines[0])
+        forces = ArrayData(
+            label="Optimisation Path Forces",
+            description=(
+                "Per-atom forces at each step of a ChemShell geometry optimisation, "
+                "stored as one (natoms, 3) array per frame."
+            ),
+        )
+        frame = 0
+        i = 0
+        while i < len(lines):
+            frame_forces = numpy.zeros((natoms, 3), dtype=float)
+            for atm_index, atm_line in enumerate(lines[i + 2 : i + 2 + natoms]):
+                line = atm_line.split()
+                frame_forces[atm_index][0] = float(line[1])
+                frame_forces[atm_index][1] = float(line[2])
+                frame_forces[atm_index][2] = float(line[3])
+            forces.set_array(f"Frame_{frame}", frame_forces)
+            frame += 1
+            i += natoms + 2
+        self.out(output_link, forces)
+        return
+
     def parse_neb_info(self, file_path: Path) -> None:
         """Parse the NEB info file into an AiiDA ArrayData noe."""
         output = ArrayData(

{aiida_chemshell-0.3.0 → aiida_chemshell-0.3.1}/src/aiida_chemshell/units.py

@@ -4,13 +4,13 @@
 class UnitsConverter:
     """Unit conversion utility."""
 
-    ANGSTROM = 0.529177
+    ANGSTROM = 0.529177210903
     EV = 27.2114
 
     @classmethod
     def angstrom_to_bohr(cls, val: float) -> float:
         """Convert Angstrom to Bohr (a.u.)."""
-        return val * 1.8897259886
+        return val / UnitsConverter.ANGSTROM
 
     @classmethod
     def bohr_to_angstrom(cls, val: float) -> float: