Metadata-Version: 2.4
Name: cmtqoutilities
Version: 0.9.4
Summary: API for all cmtqo devices
Home-page: https://gitlab.phys.ethz.ch/code/experiment/mm-runexperiment
Author: Sebastian Huber
Author-email: huberse@phys.ethz.ch
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.18.0
Requires-Dist: requests>=2.25.0
Requires-Dist: scipy>=1.5.0
Requires-Dist: pyserial>=3.5
Requires-Dist: zaber.serial>=0.9
Requires-Dist: pymysql>=1.1.1
Requires-Dist: nbconvert>=7.0.0
Requires-Dist: nbformat>=5.0.0
Requires-Dist: jupyter>=1.1.1
Requires-Dist: cmtqoutilities[clients]
Provides-Extra: clients
Requires-Dist: digipigi; extra == "clients"
Requires-Dist: delimux; extra == "clients"
Requires-Dist: stitchlockin; extra == "clients"
Requires-Dist: mumobo; extra == "clients"
Requires-Dist: rbcomb; extra == "clients"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# cmtqoutilities

[![PyPI](https://img.shields.io/pypi/v/cmtqoutilities.svg)](https://pypi.org/project/cmtqoutilities/)

**cmtqoutilities** is a Python toolkit that provides high-level APIs to control and automate a diverse range of laboratory hardware devices used in quantum optics and condensed matter experiments. The package offers abstraction layers for devices such as pressure controllers, serial interfaces, positioning stages, databases, and data acquisition tools.

---

## 🚀 Key Features

- 🧪 **Experiment automation** through a unified `Operator` class
- 📡 **Instrument control** for Zaber actuators, Numato relays, Picoscope oscilloscopes, Atto IDS3010 sensors, and more
- 🧾 **Database integration** for logging and tracking experimental metadata
- 🗃️ **Filesystem and code snapshot utilities** for reproducible research
- ⚙️ **Cross-platform support** for Windows and Unix-like systems

---

## 🧱 Module Overview

### `modOp.py`
Defines the `Operator` class — a central controller for experiments, handling setup configuration, data and code paths, database connections, and version management.

### `database.py`
Handles experimental metadata logging, MySQL interactions, and retrieval of recent or historical experiment data.

### `pressureControl.py`
Provides an interface to communicate with pressure controllers over serial, supporting pressure reading and basic control commands.

### `zaber*.py`
Multiple modules to control Zaber linear actuators (LRQ600, LSQ150, etc.), supporting movement, homing, and axis configuration. The legacy modules (`zaberLRQ600`, `zaberLRQ600YZ`, `zaberLRQ600XYZ`, `zaberLSQ150`) each hard-code one configuration with a single microstep size. New setups use **`zaberChain`**, where every axis carries its own model, device number, microstep, travel and direction, read from the device documentation below:

```python
from utilities import zaberChain as zc
stage = zc.ZaberChain('/dev/zaber0')          # default zc.SENSORHEAD: X-LRQ600BL-E01 x=1, y=2 + X-LSM025A-E03 z=3
stage.home(); stage.getPos(); stage.moveTo([10, 20, 5]); stage.moveAxis('z', 5.2); stage.setCoordSys('here')
stage.fullStep('x')                           # microstepping period for knife_edge.fit_edge(periodic=True)
stage.checkSettings(); stage.warnings(); stage.info()
# another chain: zc.ZaberChain(port, axes=[zc.Axis('x', 1, 'X-LRQ600BL-E01', invert=True), zc.Axis('z', 2, 'X-LSM025A-E03')])
```
Device documentation (links to the ASCII protocol manual, datasheet and the factory default settings) is shipped with the package: `from utilities import devices; devices.list(); print(devices.doc("X-LRQ600BL-E01"))` (sources in [utilities/devices/](https://gitlab.phys.ethz.ch/code/experiment/mm-runexperiment/-/tree/main/cmtqoutilities/utilities/devices)). The factory defaults are in `utilities/devices/<device>.json`, and `zaberLRQ600.checkSettings(stage, axis)` lists every live setting that differs from them (modified soft limits, speeds, ...). Manufacturer PDFs are archived on the group share (`//home.phys.ethz.ch/cmtqo/manuals/`), not in this repository.

### `numatoLabRL002.py`
Enables control of Numato Lab USB relay modules for hardware switching tasks.

### `picoscope.py`, `ps4000a.py`
Modules for acquiring data from PicoTech oscilloscopes (e.g. PS4000 series), integrating with the experiment automation flow.

### `attoIDS3010.py`
Interface to Atto IDS3010 displacement sensors, providing sub-nanometer position measurement capabilities.

### `operatorManualSetup.py`
Support functions for setting up manual experimental configurations, such as pre-alignment or testing.

### `picam.py`, `photodiode.py`
HTTP clients for the daemons on the experiment Raspberry Pi (deployed with `delicont`): the HQ camera (`picam-server`) and the knife-edge photodiode readout (`pd-server`, ADS1115). `knife_edge.py` has the scan helper and the erf / w(z) fits for beam-size measurements.

### Device clients from their own packages: `digipigi`, `delimux`, `stitchlockin`
These devices keep client and documentation in their own repositories and publish a client package on PyPI. `cmtqoutilities` depends on them and re-exports them, so every client is reached the same way:
```python
from utilities import digipigi, delimux, stitchlockin, picam, photodiode
```
Use attribute access afterwards (`dp = digipigi.DigiPigi(HOST="digipigi1")`); don't deep-import through the alias (`from utilities.digipigi.x import ...` loads the module a second time).

---

## 📦 Installation

The modop infrastructure to run experiments is optimally enabled in the following way: Create a virtual environment as
```bash
python -m venv ~/.ve/modop
```
Then activate it and install the `cmtqoutilities` package 
```bash
source ~/.ve/modop/bin/activate
pip install cmtqoutilities
```
or in a windows power shell
```bash
~/.ve/modop/Scripts/Activate.ps1
pip install cmtqoutilities
```
While still in the modop virtual environment install the kernel
```bash
python -m ipykernel install --user --name=modop --display-name "Python (modop)"
```
You can then develop in ipython notebooks and run the experiments with the mopdop infrastructure. 


Requires Python 3.8 or higher. Dependencies include `numpy`, `scipy`, `requests`, `pyserial`, `pymysql`, `nbconvert`, `jupyter`, the device client packages `digipigi`, `delimux` and `stitchlockin`, and hardware-specific libraries.


