这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

快速开始

从零开始搭建 Quatm 实验控制环境，只需几分钟即可运行第一个实验。

欢迎！下面几步就能让 Quatm 在你的机器上跑起来。

完成本指南后，你将能够：

  • ✅ 在本地安装并验证 Quatm 环境
  • ✅ 理解 device_db.py 的设备配置方式
  • ✅ 编写一个带有参数面板的完整实验脚本
  • ✅ 在模拟模式下运行和调试实验

环境要求

  • Python：3.9 及以上版本
  • 操作系统：Windows 7 以上、Linux（内核版本 5.10.261 及以上）、macOS 10.12 及以上
  • 硬件：模拟模式无需硬件；实际实验需要支持 TTL/DAC 的控制器，实时控制需要 FPGA 模块（如 ADwin、Red Pitaya、NI-FPGA 等）

安装

git clone https://github.com/quatm/quatm.git
cd quatm
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

验证

from quatm.experiment import Experiment

class HelloQuatm(Experiment):
    def build(self):
        print("Quatm 就绪！")
    def run(self):
        print("Hello, Quatm!")

HelloQuatm().run()

下一步

1 - 编写第一个实验

从零开始编写你的第一个 Quatm 实验脚本，学习实验类的基本结构和运行方式。

实验的基本结构

每个 Quatm 实验都是一个继承自 Experiment 的 Python 类。只需定义 build() 和 run() 两个核心方法：

from quatm.experiment import Experiment, NumberValue
from quatm.experiment.experiment import delay

class MyFirstExperiment(Experiment):
    def build(self):
        # 声明设备
        self.setattr_device("fpga")
        # 声明参数
        self.setattr_argument(
            "target_voltage",
            NumberValue("target_voltage", ndecimals=2, step=0.01, value=4.00)
        )

    def run(self):
        # 设置 DAC 通道输出并等待后切换
        self.my_dac = 1.0
        delay(0.5)
        self.my_dac = self.target_voltage

build() — 声明阶段

build() 在实验加载时执行一次，用于声明实验中使用的设备和参数。

设备声明模式

# DAQ/控制器设备（type: local）
self.setattr_device("fpga")

# 属性设备（type: attr），直接作为实验属性使用
self.setattr_device("cooling_ttl")

# 通用属性设备（type: generic_attr）
self.setattr_device("Li_frequency")

参数类型

类型类使用场景
数值NumberValue电压、频率、时间等连续量
布尔BoolValue开关、使能等二值选项
选项StringCombo模式选择、扫描类型等固定选项
self.setattr_argument("b_field", NumberValue("b_field", ndecimals=1, step=0.5, value=5.0))
self.setattr_argument("cooling", BoolValue("cooling", True))
self.setattr_argument("scan", StringCombo("scan", ["完整扫描", "快速扫描"]))

run() — 执行阶段

run() 是实验的主体逻辑，每次运行按钮点击时执行。

设备控制

def run(self):
    # 模拟量输出
    self.trap_dac = 3.5        # 设置 DAC 输出
    
    # TTL 数字输出
    self.aom_ttl = True        # 打开 AOM
    delay(0.1)
    self.aom_ttl = False       # 关闭 AOM

数据采集

def run(self):
    self.camera.expose(0.1)
    img = self.camera.last_image
    
    # 发送到数据管理器
    self._dataq.send({"atom_count": analyze(img)})

运行实验

将 .py 文件放入 experiments/ 目录，启动 Quatm 浏览器：

python -m quatm.GUI.browser

2 - 常见问题

Quatm 安装和使用中的常见问题及解决方案。

Windows 系统

pyzmq 安装失败

安装 Microsoft C++ Build Tools 后重试。

FPGA 控制器驱动

需安装厂商提供的 SDK，FPGA 需要按照实际需求定义和烧录timetable。模拟模式下无需实际硬件。

Linux 系统

Qt 图形库依赖

sudo apt install libxcb-cursor0 libxcb-xinerama0 libegl1-mesa

相机权限

Andor / BlackFly 需配置 udev 规则。

Windows Subsystem for Linux (WSL)

WSL 用户请确保在 Linux 文件系统挂载上运行，避免在 Windows 文件系统上操作导致意外错误。

3 - 配置仪器设备

通过 device_db.py 将实验仪器接入 Quatm 框架。

Quatm 通过 configuration/device_db.py 管理所有实验仪器。该文件定义一个名为 device_db 的字典，每个键对应一个可在实验中使用的设备名称。

设备类型

device_db 支持三种设备类型：

type说明使用场景
local驱动类实例FPGA 控制器、相机等需要完整驱动对象的设备
attr属性映射将驱动的某个通道映射为实验属性（如 DAC、TTL）
generic_attr通用属性调用驱动的任意函数，实现灵活的功能映射

配置示例

device_db = {
    # 驱动设备：加载完整的驱动实例
    "fpga": {
        "type": "local",
        "module": "quatm.drivers.fpga.client",
        "class": "fpgaClient",
        "arguments": {},
    },
    # 属性设备：TTL 通道映射
    "cooling_aom": {
        "type": "attr",
        "module": "quatm.experiment.attributes",
        "class": "TTLOut",
        "arguments": {"channel": 5, "logic": "a"},
    },
    # 属性设备：DAC 通道映射
    "trap_coil_x": {
        "type": "attr",
        "module": "quatm.experiment.attributes",
        "class": "DAC",
        "arguments": {"channel": 2},
    },
}

属性设备参数

TTLOut — 数字输出

参数说明
channelFPGA 控制器 TTL 通道编号
logic"l" 为正逻辑，"a" 为反逻辑

DAC — 模拟输出

参数说明
channelFPGA 控制器 DAC 通道编号
gaugefile校准文件路径（可选）

通用属性配置

对于需要灵活映射的驱动功能，使用 genericAttr：

"Li_frequency": {
    "type": "generic_attr",
    "module": "quatm.experiment.attributes",
    "class": "genericAttr",
    "driver": "lithium_dds_0",
    "function": "set_frequency",
    "arguments": {
        "function_kwargs": {"channel": [0]},
        "minval": 40, "maxval": 90,
        "multiplier": 1E6, "display_unit": "MHz",
    },
}

校准文件

对于非线性响应的设备，可使用两列空格分隔的文本文件进行校准：

2.2  4.0
2.0  3.8
1.8  3.6
1.6  3.34

在 DAC 配置中通过 gauge 参数引用：

"rf_power": {
    "type": "attr",
    "module": "quatm.experiment.attributes",
    "class": "DAC",
    "arguments": {"channel": 3, "gauge": "configuration/gauge-rf-power.txt"},
}

自定义驱动接入

编写自定义驱动类后，在 device_db 中以 type: "local" 注册：

"my_laser": {
    "type": "local",
    "module": "my_lab.my_laser_driver",
    "class": "MyLaserDriver",
    "arguments": {"port": "/dev/ttyUSB0"},
}

然后在实验中通过 self.setattr_device("my_laser") 使用。