Metadata-Version: 2.4
Name: amrl-transport
Version: 0.2.0
Summary: Hardware abstraction and task queue for autonomous atom manipulation with STM/AFM. Drop-in LabVIEW replacement for DeepSPM.
Project-URL: Homepage, https://github.com/formeo/amrl-transport
Project-URL: Repository, https://github.com/formeo/amrl-transport
Project-URL: Issues, https://github.com/formeo/amrl-transport/issues
Project-URL: Documentation, https://github.com/formeo/amrl-transport#readme
Author-email: Roman Gordienko <grlformeo@gmail.com>
License: MIT
License-File: LICENSE
Keywords: AFM,Createc,DeepSPM,Nanonis,STM,atom-manipulation,automation,hardware-abstraction,laboratory-automation,nanoassembly,nanofabrication,quantum-computing-fabrication,reinforcement-learning,scanning-probe-microscopy,scientific-instruments,tip-induced-manipulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: findiff>=0.9; extra == 'all'
Requires-Dist: mypy>=1.0; extra == 'all'
Requires-Dist: opencv-python>=4.5; extra == 'all'
Requires-Dist: pika>=1.3; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: redis>=4.0; extra == 'all'
Requires-Dist: ruff>=0.1; extra == 'all'
Requires-Dist: scikit-image>=0.19; extra == 'all'
Requires-Dist: torch>=1.12; extra == 'all'
Provides-Extra: createc
Requires-Dist: pywin32; extra == 'createc'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: ml
Requires-Dist: findiff>=0.9; extra == 'ml'
Requires-Dist: opencv-python>=4.5; extra == 'ml'
Requires-Dist: scikit-image>=0.19; extra == 'ml'
Requires-Dist: torch>=1.12; extra == 'ml'
Provides-Extra: queue
Requires-Dist: pika>=1.3; extra == 'queue'
Requires-Dist: redis>=4.0; extra == 'queue'
Description-Content-Type: text/markdown

[![CI](https://github.com/formeo/amrl-transport/actions/workflows/ci.yml/badge.svg)](https://github.com/formeo/amrl-transport/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/amrl-transport.svg)](https://pypi.org/project/amrl-transport/)
[![codecov](https://codecov.io/gh/formeo/amrl-transport/branch/main/graph/badge.svg)](https://codecov.io/gh/formeo/amrl-transport)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19049387.svg)](https://doi.org/10.5281/zenodo.19049387)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![PyPI Downloads](https://static.pepy.tech/badge/amrl-transport/month)](https://pepy.tech/projects/amrl-transport)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)


# AMRL Transport

**Hardware abstraction layer for autonomous atom manipulation with STM/AFM.**

Drop-in replacement for [SINGROUP](https://github.com/SINGROUP/Atom_manipulation_with_RL)'s `RealExpEnv` — train RL agents on a simulator, deploy on real hardware without code changes. Also replaces the [DeepSPM](https://github.com/abred/DeepSPM) LabVIEW instrument server with a pure Python asyncio implementation.

## The problem

RL frameworks for atom manipulation ([DeepSPM](https://github.com/abred/DeepSPM), [SINGROUP/AMRL](https://github.com/SINGROUP/Atom_manipulation_with_RL)) are hardwired to specific STM controllers — Createc COM on Windows, Nanonis TCP, or custom LabVIEW servers. If your lab has different hardware, you rewrite everything. If you want to develop without a $500K microscope, you can't.

## What this solves

- **`STMTransport` ABC** — 12 methods with physical units (nm, mV, pA). Implement once per vendor, use any RL agent.
- **Simulator backend** — Gaussian atom physics, tip-sample interaction, configurable noise. No hardware, no Windows, no license fees.
- **DeepSPM server replacement** — pure Python asyncio server that speaks the DeepSPM wire protocol. Replaces LabVIEW (BSD-3, Windows-only, ~$3500/yr). Existing DeepSPM agent code works unchanged — just point it at the Python server.
- **Distributed task queue** — RabbitMQ + Redis for queuing manipulation tasks across multiple instruments with retry, backoff, and graceful shutdown.
- **`TransportEnv`** — drop-in for SINGROUP's `RealExpEnv`. Existing training code works as-is.

## Architecture

```
┌───────────────────────────────────────────────────────┐
│                    Task Client                        │
│  amrl-submit --atoms '[[0,0],[1,0],[0.5,0.87]]'      │
└──────────────────────┬────────────────────────────────┘
                       │ ManipulationTask (JSON)
                       ▼
              ┌─────────────────┐
              │    RabbitMQ     │
              │  amrl.tasks Q   │
              └────────┬────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │Worker 01│   │Worker 02│   │Worker 03│
   │ Createc │   │ Nanonis │   │Simulator│
   └────┬────┘   └────┬────┘   └────┬────┘
        │              │              │
        ▼              ▼              ▼
   STMTransport   STMTransport   STMTransport
   (protocol.py)  (protocol.py)  (protocol.py)
        │              │              │
        ▼              ▼              ▼
   ┌─────────┐   ┌─────────┐   ┌──────────┐
   │Createc  │   │Nanonis  │   │Simulated │
   │COM/Win  │   │TCP/IP   │   │Surface   │
   └─────────┘   └─────────┘   └──────────┘
                       │
                       ▼
              ┌─────────────────┐
              │     Redis       │
              │  Results + TTL  │
              └─────────────────┘
```

## Quick start

### Install

```bash
# Core (numpy + pydantic only)
pip install amrl-transport

# With task queue support
pip install amrl-transport[queue]

# With ML dependencies (for SINGROUP RL agent integration)
pip install amrl-transport[all]
```

### Run with simulator (no hardware needed)

```python
from amrl_transport.transport import SimulatorTransport
import numpy as np

with SimulatorTransport(seed=42) as stm:
    # Scan a 5nm × 5nm area
    result = stm.scan_image(
        size_nm=5.0,
        offset_nm=np.array([0.0, 0.0]),
        pixel=128,
        bias_mv=100,
    )
    print(f"Image shape: {result.img_forward.shape}")

    # Lateral manipulation
    manip = stm.lateral_manipulation(
        x_start_nm=0.0, y_start_nm=0.0,
        x_end_nm=1.0, y_end_nm=0.0,
        bias_mv=20, current_pa=57000,
        offset_nm=np.array([0, 0]), size_nm=5.0,
    )
    print(f"Current trace length: {len(manip.current)}")
```

### Use as RL environment (drop-in for RealExpEnv)

```python
from amrl_transport.transport import SimulatorTransport
from amrl_transport.integration import TransportEnv

stm = SimulatorTransport(seed=42)
stm.connect()

env = TransportEnv(
    transport=stm,
    step_nm=0.2,
    max_mvolt=20,
    max_pcurrent_to_mvolt_ratio=2850,
    goal_nm=2.0,
)

# Existing SINGROUP training code works as-is
state, info = env.reset()
next_state, reward, done, info = env.step(action)
```

### DeepSPM server (replaces LabVIEW)

```bash
# Start the Python instrument server with simulator backend
python -m amrl_transport.deepspm --transport simulator

# Existing DeepSPM agent connects to localhost:5556 — no code changes
```

### Distributed task queue

```bash
# Start infrastructure
docker compose up -d

# Start a worker
python -m amrl_transport.cli worker --transport simulator --worker-id sim-01

# Submit a task
python -m amrl_transport.cli submit --atoms '[[0,0],[1,0],[0.5,0.866]]'
```

## Implementing a new adapter

To support a new STM brand, implement the `STMTransport` ABC:

```python
from amrl_transport.transport.protocol import STMTransport, ScanResult

class MySTMTransport(STMTransport):
    def connect(self) -> None: ...
    def scan_image(self, size_nm, offset_nm, pixel, bias_mv) -> ScanResult: ...
    def lateral_manipulation(self, ...) -> ManipResult: ...
    # ... 12 methods total, all in physical units (nm, mV, pA)
```

See [amrl_transport/transport/simulator.py](amrl_transport/transport/simulator.py) for a complete reference implementation.

## Adapters

| Backend | Status | Platform | Notes |
|---------|--------|----------|-------|
| **Simulator** | ✅ Ready | Any | Gaussian atoms, noise, tip physics |
| **Createc** | ✅ Ready | Windows | COM interface via `pyvisa` |
| **Nanonis** | 🔧 Stub | Any | TCP socket protocol |

## Testing

```bash
pip install -e ".[dev]"
pytest tests/ -v --cov=amrl_transport
# 56 tests passing — simulator, protocol, models, config
```

## Related work

- [SINGROUP/Atom_manipulation_with_RL](https://github.com/SINGROUP/Atom_manipulation_with_RL) — RL agent for atom manipulation (Aalto University)
- [abred/DeepSPM](https://github.com/abred/DeepSPM) — automated SPM with deep learning
- [Probe-Particle/ppafm](https://github.com/Probe-Particle/ppafm) — AFM image simulator
- [bluesky/ophyd-async](https://github.com/bluesky/ophyd-async) — hardware abstraction for synchrotron beamlines (similar pattern at larger scale)


## Keywords

`STM` · `AFM` · `scanning probe microscopy` · `atom manipulation` ·
`reinforcement learning` · `nanofabrication` · `laboratory automation` ·
`hardware abstraction` · `DeepSPM` · `Nanonis` · `Createc` ·
`quantum computing fabrication` · `nanoassembly` · `tip-induced manipulation`

## License

MIT
