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.
