pychemstation 0.7.0.dev2__tar.gz → 0.8.1__tar.gz

pychemstation-0.8.1/.gitignore

@@ -0,0 +1,7 @@
+.idea/*
+.pytest_cache/*
+.env
+.venv
+**/__pycache__/
+target
+.DS_Store

pychemstation-0.8.1/.gitlab-ci.yml

@@ -0,0 +1,18 @@
+stages:
+  - deploy
+
+pages:
+  stage: deploy
+  image: python:3.12-slim
+  before_script:
+    - apt-get update && apt-get install make --no-install-recommends -y
+    - python -m pip install -e .
+  script:
+    - pdoc -o doc pychemstation
+  after_script:
+    - mv doc/ ./public/
+  artifacts:
+    paths:
+    - public
+  rules:
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

pychemstation-0.8.1/CHANGELOG.md

@@ -0,0 +1,5 @@
+## 0.4.3 (2024-12-29)
+
+### changed (1 change)
+
+- [Add new  version to pypi](https://gitlab.com/heingroup/hein-analytical-control/-/commit/727d09d38ed43d56e4791983c4d740b73237b557)

pychemstation-0.8.1/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing Guide
+
+Modified from [here](https://github.com/cncf/project-template/blob/main/CONTRIBUTING.md#contributing-guide).
+
+* [Ways to Contribute](#ways-to-contribute)
+* [Find an Issue](#find-an-issue)
+* [Ask for Help](#ask-for-help)
+* [Pull Request Lifecycle](#pull-request-lifecycle)
+* [Development Environment Setup](#development-environment-setup)
+* [Sign Your Commits](#sign-your-commits)
+* [Pull Request Checklist](#pull-request-checklist)
+
+Welcome! We are glad that you want to contribute to Hein Analytical Control! 💖
+
+As you get started, you are in the best position to give us feedback on areas of
+our project that we need help with including:
+
+* Problems found during setting up a new developer environment
+* Gaps in our Quickstart Guide or documentation
+* Bugs in our Python scripts
+
+If anything doesn't make sense, or doesn't work when you run it, please open a
+bug report and let us know!
+
+## Ways to Contribute
+
+We welcome many different types of contributions including:
+
+* New features
+* Bug fixes
+* Documentation
+
+## Find an Issue
+
+If there are currently issues present, please feel free to take one! 
+Comment with something like "I would like to take this issue", 
+and our team will communicate further with you in that issue.
+
+## Ask for Help
+
+The best way to reach us with a question when contributing is to ask on:
+
+* The original GitLab issue
+* Via email at: hao.lucyy@gmail.com (only inquiries sent to this email regarding this library will be answered)
+
+## Pull Request Lifecycle
+
+⚠️ **Explain your pull request process**
+
+## Development Environment Setup
+
+First, clone this repo. All required packages are specified in `pyproject.toml`. 
+We use [poetry](https://python-poetry.org/), but you can adjust the `pyproject.toml` to 
+work with your Python package manager. Activate your environment via your package manager's instructions
+and this should be all you need to start development.
+
+To update documentation, we use [Sphinx](https://www.sphinx-doc.org/en/master/). Install via instructions on
+Sphinx's website. If you want a local version of the documentation website, then `cd docs`, `make clean`, `make html`.
+Then within `docs/build`, open `index.html` in your browser.
+
+## Sign Your Commits
+
+### DCO
+Licensing is important to open source projects. It provides some assurances that
+the software will continue to be available based under the terms that the
+author(s) desired. We require that contributors sign off on commits submitted to
+our project's repositories. The [Developer Certificate of Origin
+(DCO)](https://probot.github.io/apps/dco/) is a way to certify that you wrote and
+have the right to contribute the code you are submitting to the project.
+
+You sign-off by adding the following to your commit messages. Your sign-off must
+match the git user and email associated with the commit.
+
+    This is my commit message
+
+    Signed-off-by: Your Name <your.name@example.com>
+
+Git has a `-s` command line option to do this automatically:
+
+    git commit -s -m 'This is my commit message'
+
+If you forgot to do this and have not yet pushed your changes to the remote
+repository, you can amend your commit with the sign-off by running 
+
+    git commit --amend -s 
+
+## Pull Request Checklist
+
+When you submit your pull request, or you push new commits to it, our automated
+systems will run some checks on your new code. We require that your pull request
+passes these checks, but we also have more criteria than just that before we can
+accept and merge it. We recommend that you check the following things locally
+before you submit your code:
+
+- have you provided a doc string for new functionality OR if you have extended an existing function,
+ensure the doc string is still valid 
+- are you using type annotations? 
+- are your commit messages following the mentioned conventions?

{pychemstation-0.7.0.dev2/pychemstation.egg-info → pychemstation-0.8.1}/PKG-INFO

@@ -1,21 +1,24 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: pychemstation
-Version: 0.7.0.dev2
-Summary: Library to interact with Chemstation software, primarily used in Hein lab
-Home-page: https://gitlab.com/heingroup/device-api/pychemstation
-Author: Lucy Hao
-Author-email: lhao03@student.ubc.ca
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Description-Content-Type: text/markdown
+Version: 0.8.1
+Author-email: lucyhao <hao.lucyy@gmail.com>
 License-File: LICENSE
-Requires-Dist: polling
-Requires-Dist: seabreeze
-Requires-Dist: xsdata
-Requires-Dist: result
-Requires-Dist: rainbow-api
-Requires-Dist: aghplctools==4.8.6
+Requires-Python: >=3.8
+Requires-Dist: aghplctools>=4.8.8
+Requires-Dist: coverage>=7.6.1
+Requires-Dist: matplotlib>=3.7.5
+Requires-Dist: pandas>=2.0.3
+Requires-Dist: pdoc>=14.7.0
+Requires-Dist: polling>=0.3.2
+Requires-Dist: pytest>=7.3.5
+Requires-Dist: rainbow-api>=1.0.10
+Requires-Dist: result>=0.17.0
+Requires-Dist: scipy>=1.10.1
+Requires-Dist: seabreeze>=2.9.2
+Requires-Dist: setuptools>=75.3.2
+Requires-Dist: twine>=6.1.0
+Requires-Dist: xsdata>=24.9
+Description-Content-Type: text/markdown
 
 # Agilent HPLC Macro Control
 
@@ -67,13 +70,14 @@ from pychemstation.control import HPLCController
 import pandas as pd
 
 # these paths will be unique to your Chemstation setup
-DEFAULT_COMMAND_PATH = "C:\\Users\\User\\Desktop\\Lucy\\"
 DEFAULT_METHOD = "GENERAL-POROSHELL"
+DEFAULT_COMMAND_PATH = "C:\\Users\\User\\Desktop\\Lucy\\"
 DEFAULT_METHOD_DIR = "C:\\ChemStation\\1\\Methods\\"
-DATA_DIR = "C:\\Users\\Public\\Documents\\ChemStation\\2\\Data"
-SEQUENCE_DIR = "C:\\USERS\\PUBLIC\\DOCUMENTS\\CHEMSTATION\\2\\Sequence"
+DATA_DIR_2 = "C:\\Users\\Public\\Documents\\ChemStation\\2\\Data\\"
+DATA_DIR_3 = "C:\\Users\\Public\\Documents\\ChemStation\\3\\Data\\"
+SEQUENCE_DIR = "C:\\USERS\\PUBLIC\\DOCUMENTS\\CHEMSTATION\\2\\Sequence\\"
 
-hplc_controller = HPLCController(data_dir=DATA_DIR,
+hplc_controller = HPLCController(data_dirs=[DATA_DIR_2, DATA_DIR_3],
                                  comm_dir=DEFAULT_COMMAND_PATH,
                                  sequence_dir=SEQUENCE_DIR,
                                  method_dir=DEFAULT_METHOD_DIR)
@@ -107,4 +111,4 @@ Lucy Hao, Maria Politi
   Group. Copyright © Cronin Group, used under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) license.
 - Adapted from the [MACROS](https://github.com/Bourne-Group/HPLCMethodOptimisationGUI)
   used in [**Operator-free HPLC automated method development guided by Bayesian optimization**](https://pubs.rsc.org/en/content/articlelanding/2024/dd/d4dd00062e),
-  created by members in the Bourne Group.  Copyright © Bourne Group, used under the [MIT](https://opensource.org/license/mit) license.
+  created by members in the Bourne Group.  Copyright © Bourne Group, used under the [MIT](https://opensource.org/license/mit) license.

{pychemstation-0.7.0.dev2 → pychemstation-0.8.1}/README.md

@@ -48,13 +48,14 @@ from pychemstation.control import HPLCController
 import pandas as pd
 
 # these paths will be unique to your Chemstation setup
-DEFAULT_COMMAND_PATH = "C:\\Users\\User\\Desktop\\Lucy\\"
 DEFAULT_METHOD = "GENERAL-POROSHELL"
+DEFAULT_COMMAND_PATH = "C:\\Users\\User\\Desktop\\Lucy\\"
 DEFAULT_METHOD_DIR = "C:\\ChemStation\\1\\Methods\\"
-DATA_DIR = "C:\\Users\\Public\\Documents\\ChemStation\\2\\Data"
-SEQUENCE_DIR = "C:\\USERS\\PUBLIC\\DOCUMENTS\\CHEMSTATION\\2\\Sequence"
+DATA_DIR_2 = "C:\\Users\\Public\\Documents\\ChemStation\\2\\Data\\"
+DATA_DIR_3 = "C:\\Users\\Public\\Documents\\ChemStation\\3\\Data\\"
+SEQUENCE_DIR = "C:\\USERS\\PUBLIC\\DOCUMENTS\\CHEMSTATION\\2\\Sequence\\"
 
-hplc_controller = HPLCController(data_dir=DATA_DIR,
+hplc_controller = HPLCController(data_dirs=[DATA_DIR_2, DATA_DIR_3],
                                  comm_dir=DEFAULT_COMMAND_PATH,
                                  sequence_dir=SEQUENCE_DIR,
                                  method_dir=DEFAULT_METHOD_DIR)

pychemstation-0.8.1/build/lib/pychemstation/control/comm.py

@@ -0,0 +1,206 @@
+"""
+Module to provide API for the communication with Agilent HPLC systems.
+
+HPLCController sends commands to Chemstation software via a command file.
+Answers are received via reply file. On the Chemstation side, a custom
+Macro monitors the command file, executes commands and writes to the reply file.
+Each command is given a number (cmd_no) to keep track of which commands have
+been processed.
+
+Authors: Alexander Hammer, Hessam Mehr, Lucy Hao
+"""
+
+import os
+import time
+
+from result import Result, Ok, Err
+from ..utils.macro import *
+from ..utils.method_types import *
+
+
+class CommunicationController:
+    """
+    Class that communicates with Agilent using Macros
+    """
+
+    # maximum command number
+    MAX_CMD_NO = 255
+
+    def __init__(
+            self,
+            comm_dir: str,
+            cmd_file: str = "cmd",
+            reply_file: str = "reply",
+    ):
+        """
+        :param comm_dir:
+        :param cmd_file: Name of command file
+        :param reply_file: Name of reply file
+        """
+        if os.path.isdir(comm_dir):
+            self.cmd_file = os.path.join(comm_dir, cmd_file)
+            self.reply_file = os.path.join(comm_dir, reply_file)
+            self.cmd_no = 0
+        else:
+            raise FileNotFoundError(f"comm_dir: {comm_dir} not found.")
+        self._most_recent_hplc_status = None
+
+        # Create files for Chemstation to communicate with Python
+        open(self.cmd_file, "a").close()
+        open(self.reply_file, "a").close()
+
+        self.reset_cmd_counter()
+
+    def get_num_val(self, cmd: str) -> Union[int, float, Err]:
+        self.send(Command.GET_NUM_VAL_CMD.value.format(cmd=cmd))
+        res = self.receive()
+        if res.is_ok():
+            return res.ok_value.num_response
+        else:
+            raise RuntimeError("Failed to get number.")
+
+    def get_text_val(self, cmd: str) -> str:
+        self.send(Command.GET_TEXT_VAL_CMD.value.format(cmd=cmd))
+        res = self.receive()
+        if res.is_ok():
+            return res.ok_value.string_response
+        else:
+            raise RuntimeError("Failed to get string")
+
+    def get_status(self) -> Union[HPLCRunningStatus, HPLCAvailStatus, HPLCErrorStatus]:
+        """Get device status(es).
+
+        :return: list of ChemStation's current status
+        """
+        self.send(Command.GET_STATUS_CMD)
+        time.sleep(1)
+
+        try:
+            parsed_response = self.receive().value.string_response
+            self._most_recent_hplc_status = str_to_status(parsed_response)
+            return self._most_recent_hplc_status
+        except IOError:
+            return HPLCErrorStatus.NORESPONSE
+        except IndexError:
+            return HPLCErrorStatus.MALFORMED
+
+    def set_status(self):
+        """Updates current status of HPLC machine"""
+        self._most_recent_hplc_status = self.get_status()
+
+    def check_if_running(self) -> bool:
+        """Checks if HPLC machine is in an available state, meaning a state that data is not being written.
+
+        :return: whether the HPLC machine is in a safe state to retrieve data back."""
+        self.set_status()
+        hplc_avail = isinstance(self._most_recent_hplc_status, HPLCAvailStatus)
+        time.sleep(30)
+        self.set_status()
+        hplc_actually_avail = isinstance(self._most_recent_hplc_status, HPLCAvailStatus)
+        return hplc_avail and hplc_actually_avail
+
+    def _send(self, cmd: str, cmd_no: int, num_attempts=5) -> None:
+        """Low-level execution primitive. Sends a command string to HPLC.
+
+        :param cmd: string to be sent to HPLC
+        :param cmd_no: Command number
+        :param num_attempts: Number of attempts to send the command before raising exception.
+        :raises IOError: Could not write to command file.
+        """
+        err = None
+        for _ in range(num_attempts):
+            time.sleep(1)
+            try:
+                with open(self.cmd_file, "w", encoding="utf8") as cmd_file:
+                    cmd_file.write(f"{cmd_no} {cmd}")
+            except IOError as e:
+                err = e
+                continue
+            else:
+                return
+        else:
+            raise IOError(f"Failed to send command #{cmd_no}: {cmd}.") from err
+
+    def _receive(self, cmd_no: int, num_attempts=100) -> Result[str, str]:
+        """Low-level execution primitive. Recives a response from HPLC.
+
+        :param cmd_no: Command number
+        :param num_attempts: Number of retries to open reply file
+        :raises IOError: Could not read reply file.
+        :return: Potential ChemStation response
+        """
+        err = None
+        for _ in range(num_attempts):
+            time.sleep(1)
+
+            try:
+                with open(self.reply_file, "r", encoding="utf_16") as reply_file:
+                    response = reply_file.read()
+            except OSError as e:
+                err = e
+                continue
+
+            try:
+                first_line = response.splitlines()[0]
+                response_no = int(first_line.split()[0])
+            except IndexError as e:
+                err = e
+                continue
+
+            # check that response corresponds to sent command
+            if response_no == cmd_no:
+                return Ok(response)
+            else:
+                continue
+        else:
+            return Err(f"Failed to receive reply to command #{cmd_no} due to {err}.")
+
+    def sleepy_send(self, cmd: Union[Command, str]):
+        self.send("Sleep 0.1")
+        self.send(cmd)
+        self.send("Sleep 0.1")
+
+    def send(self, cmd: Union[Command, str]):
+        """Sends a command to Chemstation.
+
+        :param cmd: Command to be sent to HPLC
+        """
+        if self.cmd_no == self.MAX_CMD_NO:
+            self.reset_cmd_counter()
+
+        cmd_to_send: str = cmd.value if isinstance(cmd, Command) else cmd
+        self.cmd_no += 1
+        self._send(cmd_to_send, self.cmd_no)
+        f = open("out.txt", "a")
+        f.write(cmd_to_send + "\n")
+        f.close()
+
+    def receive(self) -> Result[Response, str]:
+        """Returns messages received in reply file.
+
+        :return: ChemStation response 
+        """
+        num_response_prefix = "Numerical Responses:"
+        str_response_prefix = "String Responses:"
+        possible_response = self._receive(self.cmd_no)
+        if Ok(possible_response):
+            lines = possible_response.value.splitlines()
+            for line in lines:
+                if str_response_prefix in line and num_response_prefix in line:
+                    string_responses_dirty, _, numerical_responses = line.partition(num_response_prefix)
+                    _, _, string_responses = string_responses_dirty.partition(str_response_prefix)
+                    return Ok(Response(string_response=string_responses.strip(),
+                                       num_response=float(numerical_responses.strip())))
+            return Err(f"Could not retrieve HPLC response")
+        else:
+            return Err(f"Could not establish response to HPLC: {possible_response}")
+
+    def reset_cmd_counter(self):
+        """Resets the command counter."""
+        self._send(Command.RESET_COUNTER_CMD.value, cmd_no=self.MAX_CMD_NO + 1)
+        self._receive(cmd_no=self.MAX_CMD_NO + 1)
+        self.cmd_no = 0
+
+    def stop_macro(self):
+        """Stops Macro execution. Connection will be lost."""
+        self.send(Command.STOP_MACRO_CMD)