flowchem-virtual 1.0.0__tar.gz

flowchem_virtual-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Automated Chemistry @ Max Plank Institute of Colloids and Interfaces
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flowchem_virtual-1.0.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: flowchem_virtual
+Version: 1.0.0
+Summary: Flowchem-Virtual is a virtual version of the flowchem - library to control instruments and devices commonly found in chemistry labs via an interoperable web API.
+Author-email: Jakob Wolf <75418671+JB-Wolf@users.noreply.github.com>, Samuel Saraiva <88909409+samuelvitorsaraiva@users.noreply.github.com>
+Maintainer-email: Jakob Wolf <75418671+JB-Wolf@users.noreply.github.com>, Samuel Saraiva <88909409+samuelvitorsaraiva@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/automatedchemistry/flowchem-virtual
+Project-URL: repository, https://github.com/automatedchemistry/flowchem-virtual
+Keywords: chemistry,automation,laboratory,science
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flowchem
+Provides-Extra: all
+Requires-Dist: black; extra == "all"
+Requires-Dist: mypy; extra == "all"
+Requires-Dist: pre-commit; extra == "all"
+Requires-Dist: ruff>=0.0.252; extra == "all"
+Provides-Extra: ci
+Requires-Dist: black; extra == "ci"
+Requires-Dist: mypy; extra == "ci"
+Requires-Dist: pre-commit; extra == "ci"
+Requires-Dist: ruff>=0.0.252; extra == "ci"
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff>=0.0.252; extra == "dev"
+Provides-Extra: test
+Requires-Dist: httpx; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Requires-Dist: pytest-xprocess; extra == "test"
+Dynamic: license-file
+
+# flowchem-virtual
+
+`flowchem-virtual` provides **virtual devices (digital twins)** for the hardware implemented in the main `flowchem` [package](https://github.com/automatedchemistry/flowchem).
+
+It’s designed as a **drop-in replacement** for `flowchem` when you want to:
+
+* Develop and debug flows
+
+* Test configuration files
+
+* Run CI pipelines
+
+…without having the physical hardware connected.
+
+
+# Installation
+
+```bash
+pip install flowchem-virtual
+```
+
+# Usage
+
+If you already know how `flowchem` works, using `flowchem-virtual` is straightforward.
+
+Normally, you would start a flowchem server with:
+
+```bash
+flowchem /path/to/configuration_file.toml
+```
+
+To use the virtual devices instead, simply run:
+
+```bash
+flowchem-virtual /path/to/configuration_file.toml
+```
+
+`flowchem-virtual` will:
+
+* Read the same configuration file
+
+* Expose **virtual counterparts** of all devices defined there
+
+* Keep the same API and behavior as much as possible, but without touching real hardware
+
+This makes it a convenient **simulation layer** for your existing setups.
+
+# When should I use flowchem-virtual?
+
+Typical scenarios:
+
+* 💻 **Local development** of client code without access to the lab
+
+* 🧪 **Unit tests / CI** where hardware is not available (or not desirable)
+
+* 📦 **Trying out configuration changes** before deploying them to a real setup
+
+* 📚 **Teaching and demos** of flowchem-based automation
+
+# Tips
+
+If you are **not yet familiar with flowchem**, it’s highly recommended to learn the basics there first.
+
+👉 [flowchem documentation](https://flowchem.readthedocs.io/en/latest/)
+
+Once you understand how devices and configuration files work in `flowchem`, switching to the virtual version is just a matter of changing the command from:
+```bash
+flowchem ...
+```
+to:
+```bash
+flowchem-virtual ...
+```
+
+# Limitations
+
+* Virtual devices **do not control real hardware** (obviously 😄).
+
+* Most part of device-specific behavior (e.g. exact timing, error states) may be simplified.
+
+* If your code depends on very low-level hardware quirks, the virtual version might not reproduce them perfectly.
+
+# Contributing
+
+Pull requests, bug reports and feature requests are welcome!
+
+# License
+
+This project is licensed under the MIT License – see the LICENSE file for details.

flowchem_virtual-1.0.0/README.md

@@ -0,0 +1,89 @@
+# flowchem-virtual
+
+`flowchem-virtual` provides **virtual devices (digital twins)** for the hardware implemented in the main `flowchem` [package](https://github.com/automatedchemistry/flowchem).
+
+It’s designed as a **drop-in replacement** for `flowchem` when you want to:
+
+* Develop and debug flows
+
+* Test configuration files
+
+* Run CI pipelines
+
+…without having the physical hardware connected.
+
+
+# Installation
+
+```bash
+pip install flowchem-virtual
+```
+
+# Usage
+
+If you already know how `flowchem` works, using `flowchem-virtual` is straightforward.
+
+Normally, you would start a flowchem server with:
+
+```bash
+flowchem /path/to/configuration_file.toml
+```
+
+To use the virtual devices instead, simply run:
+
+```bash
+flowchem-virtual /path/to/configuration_file.toml
+```
+
+`flowchem-virtual` will:
+
+* Read the same configuration file
+
+* Expose **virtual counterparts** of all devices defined there
+
+* Keep the same API and behavior as much as possible, but without touching real hardware
+
+This makes it a convenient **simulation layer** for your existing setups.
+
+# When should I use flowchem-virtual?
+
+Typical scenarios:
+
+* 💻 **Local development** of client code without access to the lab
+
+* 🧪 **Unit tests / CI** where hardware is not available (or not desirable)
+
+* 📦 **Trying out configuration changes** before deploying them to a real setup
+
+* 📚 **Teaching and demos** of flowchem-based automation
+
+# Tips
+
+If you are **not yet familiar with flowchem**, it’s highly recommended to learn the basics there first.
+
+👉 [flowchem documentation](https://flowchem.readthedocs.io/en/latest/)
+
+Once you understand how devices and configuration files work in `flowchem`, switching to the virtual version is just a matter of changing the command from:
+```bash
+flowchem ...
+```
+to:
+```bash
+flowchem-virtual ...
+```
+
+# Limitations
+
+* Virtual devices **do not control real hardware** (obviously 😄).
+
+* Most part of device-specific behavior (e.g. exact timing, error states) may be simplified.
+
+* If your code depends on very low-level hardware quirks, the virtual version might not reproduce them perfectly.
+
+# Contributing
+
+Pull requests, bug reports and feature requests are welcome!
+
+# License
+
+This project is licensed under the MIT License – see the LICENSE file for details.

flowchem_virtual-1.0.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flowchem_virtual"
+version = "1.0.0"
+
+description = "Flowchem-Virtual is a virtual version of the flowchem - library to control instruments and devices commonly found in chemistry labs via an interoperable web API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ['LICEN[CS]E*',]
+keywords = ["chemistry", "automation", "laboratory", "science"]
+authors = [
+    { name = "Jakob Wolf", email = "75418671+JB-Wolf@users.noreply.github.com" },
+    { name = "Samuel Saraiva", email = "88909409+samuelvitorsaraiva@users.noreply.github.com" },
+]
+maintainers = [
+    { name = "Jakob Wolf", email = "75418671+JB-Wolf@users.noreply.github.com" },
+    { name = "Samuel Saraiva", email = "88909409+samuelvitorsaraiva@users.noreply.github.com" }
+]
+dependencies = [
+    "flowchem",
+]
+[project.optional-dependencies]
+all = [
+    "black",
+    "mypy",
+    "pre-commit",
+    "ruff>=0.0.252"
+]
+ci = [
+    "black",
+    "mypy",
+    "pre-commit",
+    "ruff>=0.0.252"
+]
+dev = [
+    "black",
+    "mypy",
+    "pre-commit",
+    "ruff>=0.0.252"
+]
+test = [
+    "httpx",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "pytest-mock",
+    "pytest-xprocess",
+]
+[project.urls]
+homepage = "https://github.com/automatedchemistry/flowchem-virtual"
+repository = "https://github.com/automatedchemistry/flowchem-virtual"
+
+[project.scripts]
+flowchem-virtual = "flowchem_virtual.__main__:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.mypy]
+ignore_missing_imports = true
+python_version = "3.11"
+
+[tool.ruff]
+line-length = 120

flowchem_virtual-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flowchem_virtual-1.0.0/src/flowchem_virtual/__main__.py

@@ -0,0 +1,85 @@
+"""Entry-point module for the command line prefixes, called in case you use `python -m flowchem`.
+Why does this file exist, and why `__main__`? For more info, read:
+- https://www.python.org/dev/peps/pep-0338/
+- https://docs.python.org/3/using/cmdline.html#cmdoption-m.
+"""
+import asyncio
+import sys
+from pathlib import Path
+
+import rich_click as click
+import uvicorn
+from loguru import logger
+
+from flowchem_virtual.server.core import FlowchemVirtual
+
+
+@click.argument("device_config_file", type=click.Path(), required=True)
+@click.option(
+    "-l",
+    "--log",
+    "logfile",
+    type=click.Path(),
+    default=None,
+    help="Save logs to file.",
+)
+@click.option(
+    "-h",
+    "--host",
+    "host",
+    type=str,
+    default="0.0.0.0",
+    help="Server host. 0.0.0.0 is used to bind to all addresses, do not use for internet-exposed devices__!",
+)
+@click.option("-d", "--debug", is_flag=True, help="Print debug info.")
+@click.version_option()
+@click.command()
+def main(device_config_file, logfile, host, debug):
+    """Flowchem main program.
+
+    Parse device_config_file and starts a server exposing the devices__ via REST-ful API.
+
+    In order to operate a simulated device for educational purposes without requiring
+    any connected device, simply execute 'flowchem example'
+
+    Args:
+    ----
+        device_config_file: Flowchem configuration file specifying device connection settings (TOML)
+        logfile: Output file for logs.
+        host: IP on which the server will be listening. Loopback IP as default, use LAN IP to enable remote access.
+        debug: Print debug info
+    """
+    if sys.platform == "win32":
+        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+    if not debug:
+        # Set stderr to info
+        logger.remove()
+        logger.add(sys.stderr, level="INFO")
+
+    logger.info("Starting flowchem-virtual!")
+    if logfile:
+        logger.add(Path(logfile), level="DEBUG")
+    logger.debug(f"Starting server with configuration file: '{device_config_file}'")
+
+    async def main_loop():
+        """Main application loop, the event loop is shared between uvicorn and flowchem."""
+        flowchem = FlowchemVirtual()
+        await flowchem.setup(Path(device_config_file))
+
+        config = uvicorn.Config(
+            flowchem.http.app,
+            host=host,
+            port=flowchem.port,
+            log_level="info",
+            timeout_keep_alive=3600,
+        )
+        server = uvicorn.Server(config)
+        logger.info("Click on http://127.0.0.1:8000 to access device server.")
+        await server.serve()
+
+    asyncio.run(main_loop())
+
+
+if __name__ == "__main__":
+    main()

flowchem_virtual-1.0.0/src/flowchem_virtual/devices/__init__.py

@@ -0,0 +1,18 @@
+# ruff: noqa
+from .biochem import *
+from .bronkhorst import *
+from .dataapex import *
+from .hamilton import *
+from .harvardapparatus import *
+from .huber import *
+from .knauer import *
+from .magritek import *
+from .manson import *
+from .mettlertoledo import *
+from .phidgets import *
+from .vacuubrand import *
+from .vapourtec import *
+from .vicivalco import *
+from .runze import *
+from .custom import *
+from .waters import *

flowchem_virtual-1.0.0/src/flowchem_virtual/devices/biochem/__init__.py

@@ -0,0 +1,6 @@
+from .virtual_solenoid import (
+    VirtualBioChemSolenoidValve,
+    VirtualBioChemSolenoid2WayValve,
+)
+
+__all__ = ["VirtualBioChemSolenoidValve", "VirtualBioChemSolenoid2WayValve"]

flowchem_virtual-1.0.0/src/flowchem_virtual/devices/biochem/virtual_solenoid.py

@@ -0,0 +1,55 @@
+from flowchem.devices.biochem.solenoid_valve import (
+    BioChemSolenoidValve,
+    SolenoidValve,
+    SolenoidValve2Way,
+)
+from flowchem.components.technical.relay import Relay
+
+from loguru import logger
+import asyncio
+
+
+class VirtualBioChemSolenoidValve(BioChemSolenoidValve):
+    async def initialize(self):
+        n = 0
+        while self.support_platform not in Relay.INSTANCES:
+            await asyncio.sleep(0.5)
+            n += 1
+            if n > 6:
+                raise Exception(
+                    f"The relay support_platform '{self.support_platform}' was not declared or initialized. "
+                    "The valve cannot be initialized without a support_platform "
+                    f"(Please add '{self.support_platform}' to the configuration file!)."
+                )
+
+        self._io = Relay.INSTANCES[self.support_platform]
+        # Register the standard SolenoidValve component/API on this device
+        self.components.append(SolenoidValve("valve", self))
+        conf_valve = "normally open" if self.normally_open else "normally closed"
+        logger.info(
+            f"Connected to Virtual BioChemSolenoidValve {conf_valve} on "
+            f"'{self.support_platform}' channel {self.channel}!"
+        )
+
+
+class VirtualBioChemSolenoid2WayValve(VirtualBioChemSolenoidValve):
+    async def initialize(self):
+        n = 0
+        while self.support_platform not in Relay.INSTANCES:
+            await asyncio.sleep(0.5)
+            n += 1
+            if n > 6:
+                raise Exception(
+                    f"The relay support_platform '{self.support_platform}' was not declared or initialized. "
+                    "The valve cannot be initialized without a support_platform "
+                    f"(Please add '{self.support_platform}' to the configuration file!)."
+                )
+
+        self._io = Relay.INSTANCES[self.support_platform]
+        # Register the standard SolenoidValve component/API on this device
+        self.components.append(SolenoidValve2Way("valve", self))
+        conf_valve = "normally open" if self.normally_open else "normally closed"
+        logger.info(
+            f"Connected to Virtual BioChemSolenoidValve {conf_valve} on "
+            f"'{self.support_platform}' channel {self.channel}!"
+        )

flowchem_virtual-1.0.0/src/flowchem_virtual/devices/bronkhorst/__init__.py

@@ -0,0 +1,3 @@
+from .virtal_el_flow import VirtualEPC, VirtualMFC
+
+__all__ = ["VirtualEPC", "VirtualMFC"]

flowchem_virtual-1.0.0/src/flowchem_virtual/devices/bronkhorst/virtal_el_flow.py

@@ -0,0 +1,71 @@
+from flowchem.devices.bronkhorst.el_flow_component import EPCComponent, MFCComponent
+from flowchem.devices.flowchem_device import FlowchemDevice
+from flowchem.utils.people import samuel_saraiva
+from flowchem import ureg
+from loguru import logger
+
+
+def isfloat(num):
+    try:
+        float(num)
+        return True
+    except ValueError:
+        return False
+
+
+class VirtualEPC(FlowchemDevice):
+    def __init__(self, name="", *args, max_pressure: float = 10, **kwargs) -> None:
+        super().__init__(name)
+        self.device_info.authors = [samuel_saraiva]
+        self.device_info.manufacturer = "VirtualBronkhorst"
+        self.device_info.model = "EPC"
+        logger.info("Connected virtual EPC")
+
+        self.pressure = "0 bar"
+        self.max_pressure = max_pressure
+
+    async def initialize(self):
+        await self.set_pressure("0 bar")
+        self.components.append(EPCComponent("EPC", self))
+
+    async def set_pressure(self, pressure: str):
+        if pressure.isnumeric() or isfloat(pressure):
+            pressure = pressure + "bar"
+            logger.warning("No units provided to set_pressure, assuming bar.")
+        self.pressure = pressure
+
+    async def get_pressure(self) -> float:
+        return ureg.Quantity(self.pressure).magnitude
+
+    async def get_pressure_percentage(self) -> float:
+        return 100 * ureg.Quantity(self.pressure).magnitude / self.max_pressure
+
+
+class VirtualMFC(FlowchemDevice):
+    def __init__(self, name="", *args, max_flow: float = 9, **kwargs) -> None:
+        super().__init__(name)
+        self.device_info.authors = [samuel_saraiva]
+        self.device_info.manufacturer = "VirtualBronkhorst"
+        self.device_info.model = "EL-FLOW"
+        logger.debug("Connected virtual MFC")
+
+        self.max_flow = max_flow
+        self.flow = "0 ml/min"
+
+    async def initialize(self):
+        await self.set_flow_setpoint("0 ml/min")
+        self.components.append(MFCComponent("MFC", self))
+
+    async def set_flow_setpoint(self, flowrate: str):
+        if flowrate.isnumeric() or isfloat(flowrate):
+            flowrate = flowrate + "ml/min"
+            logger.warning(
+                "No units provided to set_flow_rate, assuming milliliter/minutes.",
+            )
+        self.flow = flowrate
+
+    async def get_flow_setpoint(self) -> float:
+        return ureg.Quantity(self.flow).magnitude
+
+    async def get_flow_percentage(self) -> float:
+        return 100 * ureg.Quantity(self.flow).magnitude / self.max_flow

flowchem_virtual-1.0.0/src/flowchem_virtual/devices/custom/__init__.py

@@ -0,0 +1,5 @@
+"""custom devices__."""
+from .virtual_peltier_cooler import VirtualPeltierCooler
+from .virtual_mpikg_box import VirtualSwitchBoxMPIKG
+
+__all__ = ["VirtualPeltierCooler", "VirtualSwitchBoxMPIKG"]

flowchem_virtual-1.0.0/src/flowchem_virtual/devices/custom/virtual_mpikg_box.py

@@ -0,0 +1,88 @@
+from flowchem.devices.custom.mpikg_switch_box import SwitchBoxMPIKG
+from flowchem.devices.custom.mpikg_switch_box_component import (
+    SwitchBoxADC,
+    SwitchBoxRelay,
+    SwitchBoxDAC,
+)
+from pint.registry import Quantity
+from loguru import logger
+
+
+class VirtualSwitchBoxMPIKG(SwitchBoxMPIKG):
+    """Switch Box MPIKG module class"""
+
+    def __init__(self, box_io, name: str = "") -> None:
+        super().__init__(box_io, name)
+
+        self.rele = [0] * 32
+        self.ADC = [0]
+        self.DAC = [0]
+
+    @classmethod
+    def from_config(
+        cls,
+        port: str,
+        name: str = "",
+        **serial_kwargs,
+    ):
+        return cls(box_io="switch_io", name=name)
+
+    async def initialize(self):
+        self.device_info.version = "Virtual"
+        self.components.extend(
+            [
+                SwitchBoxADC("adc", self),
+                SwitchBoxDAC("dac", self),
+                SwitchBoxRelay("relay-A", self, "a"),  # Channel 1 to 8
+                SwitchBoxRelay("relay-B", self, "b"),  # Channel 9 to 16
+                SwitchBoxRelay("relay-C", self, "c"),  # Channel 17 to 24
+                SwitchBoxRelay("relay-D", self, "d"),  # Channel 25 to 32
+            ]
+        )
+
+        logger.info("Connected to Virtual SwitchBoxMPIKG!")
+
+    async def set_relay_port(self, values: list[int], port: str = "a"):
+        map_ch = {"a": 0, "b": 7, "c": 15, "d": 23}
+        n = len(values)
+        if n >= 8:
+            self.rele[map_ch[port] : map_ch[port] + 8] = values[:8]
+        else:
+            self.rele[map_ch[port] : map_ch[port] + 8] = values + [0] * (
+                8 - len(values)
+            )
+        return True
+
+    async def set_relay_single_channel(
+        self,
+        channel: int,
+        value: int = 2,
+        keep_port_status=True,
+        port_identify: str = "a",
+    ):
+        if channel > 8:
+            self.rele[channel] = value
+        else:
+            map_ch = {"a": 0, "b": 7, "c": 15, "d": 23}
+            self.rele[map_ch[port_identify] + channel] = value
+        return True
+
+    async def get_relay_channels(self):
+        return {
+            "a": self.rele[:8],
+            "b": self.rele[8:16],
+            "c": self.rele[16:24],
+            "d": self.rele[24:],
+        }
+
+    """ ADC/DAC Commands """
+
+    async def get_adc(self):
+        return {f"ADC{i}": v for i, v in enumerate(self.ADC)}
+
+    async def get_dac(self, channel: int = 1, volts: bool = True):
+        return self.DAC[channel - 1]
+
+    async def set_dac(self, value: Quantity, channel: int = 1) -> bool:
+        self.DAC[channel - 1] = value.to("V").magnitude
+        return True