aiidalab-chemshell 0.0.1__tar.gz

aiidalab_chemshell-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, UKRI Science and Technology Facilities Council
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

aiidalab_chemshell-0.0.1/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: aiidalab-chemshell
+Version: 0.0.1
+Summary: AiiDAlab application for ChemShell based workflows
+Home-page: https://github.com/stfc/aiidalab-chemshell
+Author: Dr. Benjamin T. Speake
+Author-email: benjamin.speake@stfc.ac.uk
+Project-URL: Logo, https://raw.githubusercontent.com/stfc/aiidalab-chemshell/refs/heads/main/images/alc-100.webp
+Project-URL: Source, https://github.com/stfc/aiidalab-chemshell
+Project-URL: Bug Tracker, https://github.com/stfc/aiidalab-chemshell/issues
+Project-URL: Documentation, https://stfc.github.io/aiidalab-chemshell
+Classifier: Framework :: AiiDA
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiida-core
+Requires-Dist: aiidalab-widgets-base
+Requires-Dist: aiida-chemshell>=0.1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.11.0; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.0.2; extra == "docs"
+Requires-Dist: piccolo-theme>=0.14.0; extra == "docs"
+Requires-Dist: sphinx-toolbox; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Dynamic: license-file

aiidalab_chemshell-0.0.1/README.md

@@ -0,0 +1,124 @@
+# AiiDAlab ChemShell Plugin
+
+![Release](https://img.shields.io/badge/Release-none-red)
+[![PyPI Version](https://img.shields.io/badge/PyPI-none-red)](https://pypi.org/)
+
+[![Pipeline Status](https://github.com/stfc/aiidalab-chemshell/actions/workflows/ci-testing.yml/badge.svg?branch=main)](https://github.com/stfc/aiidalab-chemshell/actions)
+[![Docs status](https://github.com/stfc/aiidalab-chemshell/actions/workflows/ci-docs.yml/badge.svg?branch=main)](https://stfc.github.io/aiidalab-chemshell/)
+<!-- [![Coverage Status]( https://coveralls.io/repos/github/stfc/aiidalab-chemshell/badge.svg?branch=main)](https://coveralls.io/github/stfc/aiidalab-chemshell?branch=main) -->
+
+[![DOI](badge)](https://zenodo.org/)
+
+This is an AiiDAlab application plugin for ChemShell based scientific workflows, maintained by the [Ada Lovelace Center](https://adalovelacecentre.ac.uk/) (ALC).
+The app is still in early development stage and any input/contributions are welcome.
+Full documentation can be found here: [https://stfc.github.io/aiidalab-chemshell/](https://stfc.github.io/aiidalab-chemshell/).
+
+## Usage
+
+This plugin is hosted on the AiiDAlab plugin registry and therefore can be installed via the AiiDAlab plugin
+management UI page from within the AiiDAlab application interface. Instructions for how to run AiiDAlab
+itself can be found in its [documentation](https://aiidalab.readthedocs.io/en/latest/usage/access/index.html)
+and are also included in the documentation associated with this project
+[https://stfc.github.io/aiidalab-chemshell/](https://stfc.github.io/aiidalab-chemshell/).
+It is generally recommended to run AiiDAlab through a container engine such as Docker or Apptainer, both of
+which are discussed in more detail in the documentation provided. In general the core docker image applicable
+to most use cases is [aiidalab/full-stack:latest](https://hub.docker.com/r/aiidalab/full-stack) however, many
+other options exist for more tailored startup environments.
+
+## ChemShell Containers
+
+Multiple docker images are provided with this repository which build on the core foundation of the images
+provided by AiiDAlab bundling various components of the ChemShell workflows on-top of the core AiiDAlab
+application. At present two images are available; [base](https://github.com/stfc/aiidalab-chemshell/pkgs/container/aiidalab-chemshell%2Fbase) includes the AiiDAlab ChemShell plugin pre-installed including all
+required dependencies,
+[full](https://github.com/stfc/aiidalab-chemshell/pkgs/container/aiidalab-chemshell%2Ffull) builds upon
+the base package including a working installation of ChemShell (version 25) configured with DL_POLY, NWChem
+and PySCF as available backends.
+
+To run one of the provided containers, first install and setup your desired container engine, then run the
+image as follows,
+
+``` sh
+docker run -it --rm -p 8888:8888 -v $HOME:/home/jovyan ghcr.io/stfc/aiidalab-chemshell/base:latest
+```
+
+The additional run parameters will run the container interactively (``-it``), delete it when it is finished
+(``--rm``), expose the required port for the jupyter notebook instance (``-p 8888:8888``) and the final flag
+(``-v``) binds the home directory into the containers home directory so data can be made available and will
+persist beyond the container instance. For more information on how to configure containers for AiiDAlab
+see [https://stfc.github.io/alc-ux](https://stfc.github.io/alc-ux).
+
+## For Developers
+
+### Style Checking
+
+This package uses pre-commit hooks to check for style consistency, to use these the ``pre-commit`` tool is required.
+This can be installed alongside the base package by running,
+
+``` sh
+pip install .[dev]
+```
+
+or separately via,
+
+``` sh
+pip install pre-commit 
+```
+
+Once installed run,
+
+``` sh
+pre-commit install 
+```
+
+in the base repository to enable the pre-commit hooks.
+This will now run style and formatting checks on every commit.
+
+### Testing
+
+This package uses [pytest](https://docs.pytest.org/en/stable/)
+to run all unit tests which is included in the ```[dev]``` optional
+package dependencies. Once installed it can be run from the project root directory.
+The CI workflows are configured to ensure all tests pass
+before a pull request can be accepted into the main repository.
+It is important that any new additions to the code base are accompanied
+by appropriate testing, maintaining a high code coverage. The coverage
+can be checked via,
+
+``` sh
+pytest --cov=aiidalab_alc 
+```
+
+### Documentation
+
+The documentation, including a User Guide, Developer Guide and an API reference,
+is built using [sphinx](https://www.sphinx-doc.org/). The source
+for which is contained in the ```docs/``` directory. At present
+only the html generator has been fully tested. All required packages can
+be installed alongside the core package via,
+
+``` sh
+pip install .[docs]
+```
+
+and then the documentation can be built using sphinx-build,
+
+``` sh
+sphinx-build -b html docs/source/ docs/build/html 
+```
+
+from the root directory.
+
+## License
+
+[BSD 3-Clause License](LICENSE)
+
+## Funding
+
+Contributors to this project were funded by
+
+<div align="center">
+    <a href="https://adalovelacecentre.ac.uk/">
+        <img src="images/alc.svg" alt="ALC Logo" style="width: 30%">
+    </a>
+</div>

aiidalab_chemshell-0.0.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=62.6"]
+build-backend = "setuptools.build_meta" 
+
+
+[tool.ruff]
+target-version = "py310" 
+exclude = ["conf.py",]
+
+[tool.ruff.lint]
+select = [
+    # flake8-bugbear
+    "B",
+    # pylint
+    "C", "R",
+    # pydocstyle
+    "D",
+    # pycodestyle
+    "E", "W",
+    # Pyflakes
+    "F", "FA",
+    # isort
+    "I",
+    # pep8-naming
+    "N",
+    # pyupgrade
+    "UP",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"

aiidalab_chemshell-0.0.1/setup.cfg

@@ -0,0 +1,55 @@
+[aiidalab]
+title = AiiDAlab ChemShell
+categories = 
+	Classical
+	Quantum
+
+[metadata]
+name = aiidalab-chemshell
+version = 0.0.1
+author = Dr. Benjamin T. Speake
+author_email = benjamin.speake@stfc.ac.uk
+description = AiiDAlab application for ChemShell based workflows
+long_description = file: README
+long_description_content_type = text/markdown
+url = https://github.com/stfc/aiidalab-chemshell
+project_urls = 
+	Logo = https://raw.githubusercontent.com/stfc/aiidalab-chemshell/refs/heads/main/images/alc-100.webp
+	Source = https://github.com/stfc/aiidalab-chemshell
+	Bug Tracker = https://github.com/stfc/aiidalab-chemshell/issues
+	Documentation = https://stfc.github.io/aiidalab-chemshell
+classifiers = 
+	Framework :: AiiDA
+	Operating System :: OS Independent
+	Programming Language :: Python :: 3
+	Development Status :: 4 - Beta
+
+[options]
+package_dir = 
+	= src
+packages = find:
+install_requires = 
+	aiida-core
+	aiidalab-widgets-base
+	aiida-chemshell>=0.1.5
+python_requires = >=3.9
+
+[options.packages.find]
+where = src
+
+[options.extras_require]
+dev = 
+	pytest>=8.0
+	pytest-cov>=6.0
+	ruff>=0.11.0
+	pre-commit
+docs = 
+	sphinx>=8.0.2
+	piccolo-theme>=0.14.0
+	sphinx-toolbox
+	numpydoc
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

aiidalab_chemshell-0.0.1/src/aiidalab_chemshell/__init__.py

@@ -0,0 +1,5 @@
+"""The main AiiDAlab ChemShell python package."""
+
+from importlib.metadata import version
+
+__version__ = version("aiidalab-chemshell")

aiidalab_chemshell-0.0.1/src/aiidalab_chemshell/common/__init__.py

@@ -0,0 +1 @@
+"""Package for general common components."""

aiidalab_chemshell-0.0.1/src/aiidalab_chemshell/common/chemshell.py

@@ -0,0 +1,53 @@
+"""Module containing common settings for configuring ChemShell."""
+
+from enum import Enum, auto
+
+
+class BasisSetOptions(Enum):
+    """Pre-defined basis set levels for simplified ChemShell inputs."""
+
+    FAST = 0
+    BALANCED = auto()
+    QUALITY = auto()
+
+    @property
+    def label(self) -> str:
+        """Convert enum value to a string representation for ChemShell input."""
+        match self:
+            case BasisSetOptions.FAST:
+                return "3-21G"
+            case BasisSetOptions.BALANCED:
+                return "cc-pvdz"
+            case BasisSetOptions.QUALITY:
+                return "aug-cc-pvtz"
+            case "":
+                return ""
+
+
+class WorkflowOptions(Enum):
+    """Enum defining the available ChemShell based AiiDA workflows."""
+
+    GEOMETRY = 0
+    NEB = auto()
+
+    @property
+    def label(self) -> str:
+        """Convert enum value into a more human readable string."""
+        match self:
+            case WorkflowOptions.GEOMETRY:
+                return "Geometry Optimisation"
+            case WorkflowOptions.NEB:
+                return "Nudged Elastic Band"
+            case _:
+                return ""
+
+    @property
+    def tab_label(self) -> str:
+        """Create a tab title for the given enum option."""
+        match self:
+            case WorkflowOptions.GEOMETRY:
+                return "Optimisation"
+            case WorkflowOptions.NEB:
+                return "NEB"
+            case _:
+                return "ChemShell"

aiidalab_chemshell-0.0.1/src/aiidalab_chemshell/common/database.py

@@ -0,0 +1,170 @@
+"""Module for components relating to AiiDA database management."""
+
+import datetime
+
+import ipywidgets as ipw
+import traitlets as tl
+from aiida.orm import (
+    CalcFunctionNode,
+    CalcJobNode,
+    Node,
+    QueryBuilder,
+    WorkChainNode,
+)
+
+
+class AiiDADatabaseWidget(ipw.VBox, tl.HasTraits):
+    """Widget for AiiDA database querying."""
+
+    data_object = tl.Instance(Node, allow_none=True)
+
+    def __init__(self, title: str = "", query: list | None = None):
+        if query is None:
+            query = []
+        self.title = title
+        self.query_type = tuple(query)
+
+        qbuilder = QueryBuilder().append((CalcJobNode, WorkChainNode), project="label")
+
+        self.drop_down = ipw.Dropdown(
+            options=sorted({"All"}.union({i[0] for i in qbuilder.iterall() if i[0]})),
+            value="All",
+            description="Process Label",
+            disabled=True,
+            style={"description_width": "120px"},
+            layout={"width": "50%"},
+        )
+        self.drop_down.observe(self.search, names="value")
+
+        # Disable process labels selection if we are not looking for the calculated
+        # structures.
+        def disable_drop_down(change):
+            self.drop_down.disabled = not change["new"] == "calculated"
+
+        # Select structures kind.
+        self.mode = ipw.RadioButtons(
+            options=["all", "uploaded", "calculated"], layout={"width": "25%"}
+        )
+        self.mode.observe(self.search, names="value")
+        self.mode.observe(disable_drop_down, names="value")
+
+        # Date range.
+        # Note: there is Date picker widget, but it currently does not work in Safari:
+        # https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html#Date-picker
+        date_text = ipw.HTML(value="<p>Select the date range:</p>")
+        self.start_date_widget = ipw.Text(
+            value="", description="From: ", style={"description_width": "120px"}
+        )
+        self.end_date_widget = ipw.Text(value="", description="To: ")
+
+        # Search button.
+        btn_search = ipw.Button(
+            description="Search",
+            button_style="info",
+            layout={"width": "initial", "margin": "2px 0 0 2em"},
+        )
+        btn_search.on_click(self.search)
+
+        age_selection = ipw.VBox(
+            [
+                date_text,
+                ipw.HBox([self.start_date_widget, self.end_date_widget, btn_search]),
+            ],
+            layout={"border": "1px solid #fafafa", "padding": "1em"},
+        )
+
+        h_line = ipw.HTML("<hr>")
+        box = ipw.VBox([age_selection, h_line, ipw.HBox([self.mode, self.drop_down])])
+
+        self.results = ipw.Dropdown(layout={"width": "900px"})
+        self.results.observe(self._on_select_structure, names="value")
+        self.search()
+        super().__init__([box, h_line, self.results])
+
+    def search(self, _=None) -> None:
+        """Search structures in the AiiDA database."""
+        qbuild = QueryBuilder()
+
+        # If the date range is valid, use it for the search
+        try:
+            start_date = datetime.datetime.strptime(
+                self.start_date_widget.value, "%Y-%m-%d"
+            )
+            end_date = datetime.datetime.strptime(
+                self.end_date_widget.value, "%Y-%m-%d"
+            ) + datetime.timedelta(hours=24)
+
+        # Otherwise revert to the standard (i.e. last 7 days)
+        except ValueError:
+            start_date = datetime.datetime.now() - datetime.timedelta(days=7)
+            end_date = datetime.datetime.now() + datetime.timedelta(hours=24)
+
+            self.start_date_widget.value = start_date.strftime("%Y-%m-%d")
+            self.end_date_widget.value = end_date.strftime("%Y-%m-%d")
+
+        filters = {}
+        filters["ctime"] = {"and": [{">": start_date}, {"<=": end_date}]}
+
+        if self.mode.value == "uploaded":
+            qbuild2 = (
+                QueryBuilder()
+                .append(self.query_type, project=["id"], tag="structures")
+                .append(Node, with_outgoing="structures")
+            )
+            processed_nodes = [n[0] for n in qbuild2.all()]
+            if processed_nodes:
+                filters["id"] = {"!in": processed_nodes}
+            qbuild.append(self.query_type, filters=filters)
+
+        elif self.mode.value == "calculated":
+            if self.drop_down.value == "All":
+                qbuild.append((CalcJobNode, WorkChainNode), tag="calcjobworkchain")
+            else:
+                qbuild.append(
+                    (CalcJobNode, WorkChainNode),
+                    filters={"label": self.drop_down.value},
+                    tag="calcjobworkchain",
+                )
+            qbuild.append(
+                self.query_type,
+                with_incoming="calcjobworkchain",
+                filters=filters,
+            )
+
+        elif self.mode.value == "edited":
+            qbuild.append(CalcFunctionNode)
+            qbuild.append(
+                self.query_type,
+                with_incoming=CalcFunctionNode,
+                filters=filters,
+            )
+
+        elif self.mode.value == "all":
+            qbuild.append(self.query_type, filters=filters)
+
+        qbuild.order_by({self.query_type: {"ctime": "desc"}})
+        matches = {n[0] for n in qbuild.iterall()}
+        matches = sorted(matches, reverse=True, key=lambda n: n.ctime)
+
+        options = [(f"Select a Node ({len(matches)} found)", False)]
+        for mch in matches:
+            label = f"PK: {mch.pk}"
+            label += " | " + mch.ctime.strftime("%Y-%m-%d %H:%M")
+            label += " | " + mch.base.extras.get("formula", "")
+            label += " | " + mch.node_type.split(".")[-2]
+            label += " | " + mch.label
+            label += " | " + mch.description
+            options.append((label, mch))
+
+        self.results.options = options
+        return
+
+    def _on_select_structure(self, _) -> None:
+        self.data_object = self.results.value or None
+        return
+
+    def disable(self, val: bool) -> None:
+        """Disable the widget."""
+        self.results.disabled = True
+        # self.
+        return

aiidalab_chemshell-0.0.1/src/aiidalab_chemshell/common/file_handling.py

@@ -0,0 +1,89 @@
+"""Module for providing functionality to deal with files."""
+
+from io import BytesIO
+
+import traitlets as tl
+from aiida.orm import SinglefileData
+from ipywidgets import FileUpload, HBox, Text
+
+
+class FileUploadWidget(HBox, tl.HasTraits):
+    """A widget for uploading files."""
+
+    file = tl.Instance(SinglefileData, allow_none=True)
+
+    def __init__(self, description: str = "File: ", **kwargs):
+        """
+        FileUploadWidget constructor.
+
+        Parameters
+        ----------
+        **kwargs :
+            Keyword arguments passed to the parent class's constructor.
+        """
+        super().__init__(**kwargs)
+        self.file_dict = None
+
+        self.file_upload = FileUpload(
+            accept="",
+            multiple=False,
+            description="Upload",
+            layout={"width": "20%"},
+        )
+        self.file_handle = Text(
+            value="",
+            placeholder="",
+            description=description,
+            disabled=True,
+            layout={"width": "70%"},
+        )
+        self.children = [self.file_handle, self.file_upload]
+
+        self.file_upload.observe(self._on_file_upload, names="value")
+
+        return
+
+    @property
+    def has_file(self) -> bool:
+        """True if a file has been uploaded."""
+        return self.file is not None
+
+    def _on_file_upload(self, _):
+        """Handle file upload events."""
+        if self.file_upload.value:
+            self.file_dict = self.file_upload.value[
+                list(self.file_upload.value.keys())[0]
+            ]
+            self.file_handle.value = self.file_dict["metadata"]["name"]
+            self.file = self.get_aiida_file_object()
+        else:
+            self.file_handle.value = ""
+        return
+
+    def get_file_contents(self) -> BytesIO | None:
+        """Get the contents of the uploaded file as a BytesIO object."""
+        if self.file_dict is not None:
+            return BytesIO(self.file_dict["content"])
+        return None
+
+    def filename(self) -> str:
+        """Get the name of the uploaded file."""
+        if self.file_dict is not None:
+            return self.file_dict["metadata"]["name"]
+        return ""
+
+    def get_aiida_file_object(self):
+        """Get the uploaded file as an AiiDA SinglefileData object."""
+        if self.file_dict is not None:
+            return SinglefileData(
+                file=self.get_file_contents(),
+                filename=self.filename(),
+                label=self.filename(),
+                description=self.file_handle.description,
+            )
+        return None
+
+    def disable(self, val: bool) -> None:
+        """Disable the file upload widget."""
+        self.file_upload.disabled = val
+        return

aiidalab_chemshell-0.0.1/src/aiidalab_chemshell/common/navigation.py

@@ -0,0 +1,81 @@
+"""Module handling navigation controls within the app."""
+
+from functools import partial
+
+import ipywidgets as ipw
+
+from aiidalab_chemshell.utils import open_link_in_new_tab
+
+_APPS_DIRECTORY = "/apps/apps/"
+
+
+class QuickAccessButtons(ipw.HBox):
+    """Quick access buttons present in the apps header and start banner."""
+
+    def __init__(self, **kwargs):
+        """
+        QuickAccessButtons constructor.
+
+        Parameters
+        ----------
+        **kwargs :
+            Keyword arguments passed to the `ipywidgets.HBox.__init__()`.
+        """
+        self.new_calc_link = ipw.Button(
+            description="New Calculation",
+            disabled=False,
+            button_style="success",
+            tooltip="Start a new calculation",
+            icon="plus",
+        )
+        self.new_calc_link.on_click(
+            partial(
+                open_link_in_new_tab,
+                _APPS_DIRECTORY + "aiidalab-chemshell/notebooks/main.ipynb",
+            )
+        )
+
+        self.history_link = ipw.Button(
+            description="History",
+            disabled=False,
+            button_style="primary",
+            tooltip="View Calculation History",
+            icon="history",
+        )
+        self.history_link.on_click(
+            partial(
+                open_link_in_new_tab,
+                _APPS_DIRECTORY + "aiidalab-chemshell/notebooks/history.ipynb",
+            )
+        )
+
+        self.resource_setup_link = ipw.Button(
+            description="Setup Resources",
+            disabled=False,
+            button_style="primary",
+            tooltip="Configure Computational Resources",
+            icon="cogs",
+        )
+        self.resource_setup_link.on_click(
+            partial(open_link_in_new_tab, _APPS_DIRECTORY + "home/code_setup.ipynb")
+        )
+
+        self.docs_link = ipw.Button(
+            description="Documentation",
+            disabled=False,
+            button_style="info",
+            tooltip="Open Documentation",
+            icon="book",
+        )
+        self.docs_link.on_click(
+            partial(open_link_in_new_tab, "https://github.com/stfc/aiidalab-chemshell")
+        )
+
+        children = [
+            self.new_calc_link,
+            self.history_link,
+            self.resource_setup_link,
+            self.docs_link,
+        ]
+        super().__init__(children=children, layout={"margin": "auto"}, **kwargs)
+        return