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

{aiida_chemshell-0.2.2/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.2.2
+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
@@ -46,6 +46,7 @@ Provides-Extra: dev
 Requires-Dist: aiida-core>=2.8; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0; extra == "dev"
 Requires-Dist: ruff>=0.11.0; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Provides-Extra: docs
@@ -64,30 +65,28 @@ Dynamic: license-file
 
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.18392782-blue.svg)](https://doi.org/10.5281/zenodo.18392782)
 
-
 # AiiDA ChemShell
 
-An [AiiDA](https://www.aiida.net) plugin for the [ChemShell](https://chemshell.org/) multiscale 
-computational chemistry software package. 
+An [AiiDA](https://www.aiida.net) plugin for the [ChemShell](https://chemshell.org/) multiscale
+computational chemistry software package.
 
-## Installation 
+## Installation
 
-This plugin is available through PyPI and should be installed using [`pip`](https://pip.pypa.io/en/stable/) python package manager. 
+This plugin is available through PyPI and should be installed using [`pip`](https://pip.pypa.io/en/stable/) python package manager.
 
-```
+``` bash
 pip install aiida-chemshell 
 ```
 
-## Requirements 
-
-To use this plugin a configured AiiDA profile and computer configuration are required, see the 
-[AiiDa documentation](https://aiida.readthedocs.io/projects/aiida-core/en/latest/intro/get_started.html) 
-for instructions on how to install and configure AiiDA. 
+## Requirements
 
+To use this plugin a configured AiiDA profile and computer configuration are required, see the
+[AiiDa documentation](https://aiida.readthedocs.io/projects/aiida-core/en/latest/intro/get_started.html)
+for instructions on how to install and configure AiiDA.
 
-## Setup 
+## Setup
 
-To configure the ChemShell plugin an AiiDA code instance needs to be configured for the ChemShell executable. 
+To configure the ChemShell plugin an AiiDA code instance needs to be configured for the ChemShell executable.
 The following is an example of a basic YAML configuration file:
 
 ```yaml
@@ -109,30 +108,31 @@ step. The code can then be configured by running:
 verdi code create core.code.installed --config chemshell.yml -n 
 ```
 
-If successful this will have created a code with the label `chemsh` which can then be used to run ChemShell jobs within the AiiDA workflow. 
+If successful this will have created a code with the label `chemsh` which can then be used to run ChemShell jobs within the AiiDA workflow.
 
 ### ChemShell with MPI
 
-It is important to note that the configuration of an MPI enabled ChemShell code differs slightly depending on whether the code instance uses 
+It is important to note that the configuration of an MPI enabled ChemShell code differs slightly depending on whether the code instance uses
 the `chemsh` or `chemsh.x` executable. If you have a parallel (MPI enabled) build of ChemShell but are using the `chemsh` wrapper executable
 please set `with_mpi: false` as the underlying plugin will handle how to call the mpi runtime. If you are calling the `chemsh.x` executable
-directly then `with_mpi: true` is required to run parallel jobs. 
+directly then `with_mpi: true` is required to run parallel jobs.
 
-## Examples 
+## Examples
 
-### QM Based Single Point Energy 
+### QM Based Single Point Energy
 
-The following is a python script that will run a Quantum Mechanics based single point energy calculation using the NWChem ChemShell interface. 
-The associated structure file can be found in the `tests/data/` folder. 
+The following is a python script that will run a Quantum Mechanics based single point energy calculation using the NWChem ChemShell interface.
+The associated structure file can be found in the `tests/data/` folder.
 
-```python 
-from aiida.engine import run 
+```python
+from aiida.engine import run
 from aiida.orm import load_code, SinglefileData, Dict
-from aiida import load_profile 
+from aiida import load_profile
 
-load_profile("user_profile")  # This is not required if running in a verdi shell environment 
+# This is not required if running in a verdi shell environment
+load_profile("user_profile")
 
-builder = load_code("chemsh").get_builder() 
+builder = load_code("chemsh").get_builder()
 builder.structure = SinglefileData(file="/absolute/path/to/water.cjson")
 builder.qm_parameters = Dict({"theory": "NWChem", "method": "HF", "basis": "3-21G"})
 builder.calculation_parameters = Dict({"gradients": False, "hessian": False})
@@ -142,19 +142,20 @@ results, node = run.get_node(builder)
 print("Final Energy = ", results.get("energy"))
 ```
 
-This can either be run as a script or as directly within a verdi shell python environment. 
+This can either be run as a script or as directly within a verdi shell python environment.
 
-### QM/MM Based Geometry Optimisation 
+### QM/MM Based Geometry Optimisation
 
 The following is a python script that will run a combined QM/MM based geometry optimisation using the NWChem and DL_POLY ChemShell interfaces.
-The associated structure and force field files can be found in the `tests/data/` folder. 
+The associated structure and force field files can be found in the `tests/data/` folder.
 
-```python 
-from aiida.engine import run 
+```python
+from aiida.engine import run
 from aiida.orm import load_code, SinglefileData, Dict
-from aiida import load_profile 
+from aiida import load_profile
 
-load_profile("user_profile")  # This is not required if running in a verdi shell environment 
+# This is not required if running in a verdi shell environment
+load_profile("user_profile")
 
 builder = load_code("chemsh").get_builder()
 builder.structure = SinglefileData(file="/absolute/path/to/h2o_dimer.cjson")

{aiida_chemshell-0.2.2 → aiida_chemshell-0.3.1}/README.md

@@ -7,30 +7,28 @@
 
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.18392782-blue.svg)](https://doi.org/10.5281/zenodo.18392782)
 
-
 # AiiDA ChemShell
 
-An [AiiDA](https://www.aiida.net) plugin for the [ChemShell](https://chemshell.org/) multiscale 
-computational chemistry software package. 
+An [AiiDA](https://www.aiida.net) plugin for the [ChemShell](https://chemshell.org/) multiscale
+computational chemistry software package.
 
-## Installation 
+## Installation
 
-This plugin is available through PyPI and should be installed using [`pip`](https://pip.pypa.io/en/stable/) python package manager. 
+This plugin is available through PyPI and should be installed using [`pip`](https://pip.pypa.io/en/stable/) python package manager.
 
-```
+``` bash
 pip install aiida-chemshell 
 ```
 
-## Requirements 
-
-To use this plugin a configured AiiDA profile and computer configuration are required, see the 
-[AiiDa documentation](https://aiida.readthedocs.io/projects/aiida-core/en/latest/intro/get_started.html) 
-for instructions on how to install and configure AiiDA. 
+## Requirements
 
+To use this plugin a configured AiiDA profile and computer configuration are required, see the
+[AiiDa documentation](https://aiida.readthedocs.io/projects/aiida-core/en/latest/intro/get_started.html)
+for instructions on how to install and configure AiiDA.
 
-## Setup 
+## Setup
 
-To configure the ChemShell plugin an AiiDA code instance needs to be configured for the ChemShell executable. 
+To configure the ChemShell plugin an AiiDA code instance needs to be configured for the ChemShell executable.
 The following is an example of a basic YAML configuration file:
 
 ```yaml
@@ -52,30 +50,31 @@ step. The code can then be configured by running:
 verdi code create core.code.installed --config chemshell.yml -n 
 ```
 
-If successful this will have created a code with the label `chemsh` which can then be used to run ChemShell jobs within the AiiDA workflow. 
+If successful this will have created a code with the label `chemsh` which can then be used to run ChemShell jobs within the AiiDA workflow.
 
 ### ChemShell with MPI
 
-It is important to note that the configuration of an MPI enabled ChemShell code differs slightly depending on whether the code instance uses 
+It is important to note that the configuration of an MPI enabled ChemShell code differs slightly depending on whether the code instance uses
 the `chemsh` or `chemsh.x` executable. If you have a parallel (MPI enabled) build of ChemShell but are using the `chemsh` wrapper executable
 please set `with_mpi: false` as the underlying plugin will handle how to call the mpi runtime. If you are calling the `chemsh.x` executable
-directly then `with_mpi: true` is required to run parallel jobs. 
+directly then `with_mpi: true` is required to run parallel jobs.
 
-## Examples 
+## Examples
 
-### QM Based Single Point Energy 
+### QM Based Single Point Energy
 
-The following is a python script that will run a Quantum Mechanics based single point energy calculation using the NWChem ChemShell interface. 
-The associated structure file can be found in the `tests/data/` folder. 
+The following is a python script that will run a Quantum Mechanics based single point energy calculation using the NWChem ChemShell interface.
+The associated structure file can be found in the `tests/data/` folder.
 
-```python 
-from aiida.engine import run 
+```python
+from aiida.engine import run
 from aiida.orm import load_code, SinglefileData, Dict
-from aiida import load_profile 
+from aiida import load_profile
 
-load_profile("user_profile")  # This is not required if running in a verdi shell environment 
+# This is not required if running in a verdi shell environment
+load_profile("user_profile")
 
-builder = load_code("chemsh").get_builder() 
+builder = load_code("chemsh").get_builder()
 builder.structure = SinglefileData(file="/absolute/path/to/water.cjson")
 builder.qm_parameters = Dict({"theory": "NWChem", "method": "HF", "basis": "3-21G"})
 builder.calculation_parameters = Dict({"gradients": False, "hessian": False})
@@ -85,19 +84,20 @@ results, node = run.get_node(builder)
 print("Final Energy = ", results.get("energy"))
 ```
 
-This can either be run as a script or as directly within a verdi shell python environment. 
+This can either be run as a script or as directly within a verdi shell python environment.
 
-### QM/MM Based Geometry Optimisation 
+### QM/MM Based Geometry Optimisation
 
 The following is a python script that will run a combined QM/MM based geometry optimisation using the NWChem and DL_POLY ChemShell interfaces.
-The associated structure and force field files can be found in the `tests/data/` folder. 
+The associated structure and force field files can be found in the `tests/data/` folder.
 
-```python 
-from aiida.engine import run 
+```python
+from aiida.engine import run
 from aiida.orm import load_code, SinglefileData, Dict
-from aiida import load_profile 
+from aiida import load_profile
 
-load_profile("user_profile")  # This is not required if running in a verdi shell environment 
+# This is not required if running in a verdi shell environment
+load_profile("user_profile")
 
 builder = load_code("chemsh").get_builder()
 builder.structure = SinglefileData(file="/absolute/path/to/h2o_dimer.cjson")

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

@@ -3,7 +3,7 @@ requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
 
 [project]
-version = "0.2.2"
+version = "0.3.1"
 name = "aiida-chemshell"
 description = "AiiDA workflow plugin for the ChemShell chemical modelling software package"
 authors = [
@@ -46,11 +46,23 @@ dev = [
     "aiida-core>=2.8",
     "pytest>=8.0",
     "pytest-cov>=6.0",
+    "pytest-xdist>=3.0",
     "ruff>=0.11.0",
     "pre-commit",
 ]
 docs = ["sphinx>=8.0.2", "piccolo-theme>=0.14.0", "sphinx-toolbox", "numpydoc"]
 
+[tool.pytest.ini_options]
+filterwarnings = [
+    # Third-party warnings we cannot act on and that only add noise:
+    # plumpy still calls the deprecated asyncio.get_event_loop().
+    "ignore:There is no current event loop:DeprecationWarning",
+    # AiiDA's SQLAlchemy storage backend emits autoflush session warnings.
+    "ignore::sqlalchemy.exc.SAWarning",
+    # AiiDA reports creating its config folder inside the temp test profile.
+    "ignore:Creating AiiDA configuration folder:UserWarning",
+]
+
 [tool.ruff]
 target-version = "py310"
 line-length = 88

{aiida_chemshell-0.2.2 → 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: