Stuntman 的实验设计存成 .stunt 文件,格式是 HDF5。这个文件可以在 PLAN 里拖拽生成,也可以用一段 Python 脚本生成。脚本调用 Stuntman 自带的 .NET 类库,逐项写出化学品、样品库、源和分液步骤,最后写成 .stunt。
内容依据原厂 Stuntman Python Authoring Guide(2026 年 4 月版)。代码里的类名、属性名和示例值照原文保留,注释改成中文。
三条路径最后都要经过同一个校验步骤。校验依据的是 SystemConfiguration.xml,也就是这台仪器的硬件配置。
手里已有一份接近的设计时,先导出 .py,在脚本上改,不必从空白开始。没有现成设计、流程要完全由代码决定时,从零写 Python。
操作 / PLAN / CONVERT / AI
图形界面编辑设计:PLAN ✓
打开、浏览 .stunt 文件:PLAN ✓;CONVERT ✓
从 .stunt 导出 .py:PLAN ✓;CONVERT ✓
运行 .py 生成 .stunt:CONVERT ✓;AI ✓
按 SystemConfig.xml 校验 .stunt:PLAN ✓;CONVERT ✓;AI ✓
指定 Python DLL 路径:CONVERT ✓;AI ✓(-p)
指定输出 .stunt 路径:CONVERT ✓;AI ✓(-o)
表格依据原厂指南第 8 页。PLAN 和 AI 的界面介绍见 Stuntman 软件概览。
所有数据类都在 UL.StuntmanHdf 命名空间里,Python 通过 pythonnet 提供的 clr 模块调用。
类 / 代表什么 / 每份脚本用几次
StuntmanDesign:代表什么 一份实验设计的根容器,存元数据和下面四个集合;每份脚本用几次 每份脚本一个
StuntmanChemical:代表什么 一种试剂:名称、SMILES、分子量、浓度、单位;每份脚本用几次 设计里用到的每种试剂一个
StuntmanLibrary:代表什么 一块板或一组样品瓶:行列数、台面位置、初始状态;每份脚本用几次 每块板一个;至少一个源、一个目标
StuntmanSource:代表什么 把一种化学品对应到台面上的具体位置和体积;每份脚本用几次 每种放在台面上的化学品一个
StuntmanMap:代表什么 一个步骤:分液、转移或仪器参数;每份脚本用几次 每个不同的分液步骤一个
StuntmanFile:代表什么 HDF 容器,可装一份或多份设计;每份脚本用几次 每次保存一个
化学品和样品库的 Key 是自动生成的 GUID。StuntmanSource.ChemicalKey 指向化学品的 Key。StuntmanMap.SourceKey 指向化学品或源样品库的 Key,DestinationKey 永远指向一个样品库的 Key。
StuntmanDesign 上几个常用属性:
组件 / 要求 / 说明
Python:要求 3.8–3.11,64 位;说明 位数要和 Stuntman 安装一致
pythonnet:要求 3.0 及以上;说明 提供 clr 模块,用来调用 .NET
UL.StuntmanHdf.dll:要求 随 CONVERT 安装;说明 默认在 C:\Program Files\Unchained Labs\Stuntman
UL.Core.dll:要求 随 CONVERT 安装;说明 ASUnit 等共用类型在这里
.NET Framework:要求 4.8;说明 Windows 10 / 11 自带
脚本开头做三件事:把 DLL 所在目录加进搜索路径,载入 UL.Core 和 UL.StuntmanHdf,再导入要用的类和枚举。按名称载入失败时,改用完整文件路径载入。
`
import clr
import os
import sys
dll_path = r"C:\Program Files\Unchained Labs\Stuntman"
if os.path.exists(dll_path):
sys.path.append(dll_path)
os.environ['PATH'] = dll_path + os.pathsep + os.environ.get('PATH', '')
try:
clr.AddReference("UL.Core")
clr.AddReference("UL.StuntmanHdf")
except Exception as e:
clr.AddReferenceToFileAndPath(os.path.join(dll_path, "UL.Core.dll"))
clr.AddReferenceToFileAndPath(os.path.join(dll_path, "UL.StuntmanHdf.dll"))
import System
from System import String, Double, Int32, Boolean, Array, DateTime, Guid
from System.Collections.Generic import List
from UL.StuntmanHdf import (InitState, MapType, StuntmanChemical, StuntmanDesign,
StuntmanFile, StuntmanLibrary, StuntmanMap, StuntmanPrompt, StuntmanSource, Writer)
from UL.Core.Enumerations import ASUnit
`
`
design = StuntmanDesign()
design.DesignID = Guid.NewGuid().ToString()
design.DesignName = "My Experiment"
`
名称在构造时传入,之后只读。分子量 MolWt 的单位是 g/mol,密度 Density 是 g/mL,Concentration 是储备液浓度,单位由 Unit 指定。Category 是功能类别,原文举例 "Solvent"、"Compound"。
`
chem = StuntmanChemical("Reagent-Name") # 名称构造后只读
chem.MolWt = 100.0 # 分子量,g/mol
chem.Density = 1.0 # 密度,g/mL
chem.Barcode = "000000000001"
chem.Category = "Reagent"
chem.Concentration = 1.0 # 储备液浓度
chem.Unit = ASUnit.unMOLAR # 浓度单位
chem.Reagents = []
chem.Conc = []
chem.ConcUnit = []
design.Chemicals.Add(chem) # Add 之后 chem.Key 才有效
`
StuntmanLibrary 构造时传入名称、行数、列数,三者之后都只读。下面的例子是 4 行 6 列,对应 4 × 6 的样品瓶架。SubstrateType 是硬件类型,原文举例 "Rack 8x12 1mL";SubstratePosition 是台面位置,原文举例 "Deck 1-2"。
InitialState 取 InitState.Empty、Full 或 Partial。SelectedWells 由 design.UpdateSelectedWells() 计算,属性表注明不要手动设置。
`
lib = StuntmanLibrary("LIB001", 4, 6) # 名称、行数、列数
lib.SubstrateType = "RackType" # 架子 / 板的硬件类型
lib.SubstratePosition = "" # 台面位置
design.Libraries.Add(lib)
`
StuntmanSource 把一种化学品放到台面上的某个孔里。Row 和 Column 从 0 开始,下面例子里的 Row = 1、Column = 1 是第 2 行第 2 列。Amount 是可用的体积或质量,单位由 Unit 指定。试剂不放在台面上时,IsOffDeck 为 True。
`
src = StuntmanSource()
src.ChemicalKey = chem.Key # 指向已加入设计的化学品
src.SubstrateType = "SourceRack"
src.SubstratePosition = "Deck"
src.Row = 1 # 从 0 数,即第 2 行
src.Column = 1 # 从 0 数,即第 2 列
design.Sources.Add(src)
`
MapType / 用途 / SourceKey 指向
MapType.Source:用途 把一种化学品分到一个样品库;SourceKey 指向 化学品的 Key
MapType.Array:用途 把一个样品库按孔转移到另一个样品库;SourceKey 指向 源样品库的 Key
MapType.Parameter:用途 给样品库加一个处理步骤,比如延时;SourceKey 指向 属性表写为化学品的 Key;原文参数示例只设了 DestinationKey
ValuesFloat 是每个孔的数值,长度等于目标样品库的行数乘列数。字符串参数用 ValuesString,它和 ValuesFloat 只能二选一。Rows、Columns 是目标孔的行列号,SourceRows、SourceColumns 是源孔的行列号。属性表注明这四项只用于 Array map,但原文另两种 map 的示例也设了 Rows、Columns。
GroupNumber 是执行分组,同一组的 map 可以同时执行。DispenseCategory 是分液类别标签;Tags 是给系统执行用的标记,取值和仪器配置有关。
单位用 ASUnit 枚举。原厂指南不同页的写法不一致,有 ASUnit.unMICROLITER,也有 ASUnit.uMICROLITER。写脚本时以本机 UL.Core 里的实际枚举名为准。
`
m_src = StuntmanMap()
m_src.MapType = MapType.Source
m_src.MapName = "Liquid Dispense"
m_src.MapObject = src
m_src.ValuesFloat = [50.0] * n # n = 目标库行数 × 列数,每孔 50
m_src.Unit = ASUnit.unMICROLITER
m_src.Rows = list(rows_list) # 目标孔行号
m_src.Columns = list(cols_list) # 目标孔列号
m_src.Tags = ["PDT", "10uLTip", "SourceTracking"]
m_src.DispenseCategory = "Non-Viscous Liquid"
m_src.GroupNumber = 1
m_src.Description = "Source map: bottle to LIB-DST"
m_src.SourceKey = chem.Key # 源:化学品
m_src.DestinationKey = lib_dst.Key # 目标:样品库
design.Maps.Add(m_src) # 把这一步加进设计
`
`
m_arr = StuntmanMap()
m_arr.MapType = MapType.Array
m_arr.MapName = "Liquid Dispense"
m_arr.MapObject = lib_src
m_arr.ValuesFloat = [5.0] * n
m_arr.Unit = ASUnit.uMICROLITER
m_arr.Rows = list(rows_list) # 目标孔
m_arr.Columns = list(cols_list)
m_arr.SourceRows = list(rows_list) # 源孔
m_arr.SourceColumns = list(cols_list)
m_arr.Tags = ["PDT", "10uLTip", "SourceTracking"]
m_arr.DispenseCategory = "Non-Viscous Liquid"
m_arr.GroupNumber = 2
m_arr.Description = "Array map: LIB-SRC to LIB-DST"
m_arr.SourceKey = lib_src.key # 源:样品库
m_arr.DestinationKey = lib_dst.key
design.Maps.Add(m_arr)
`
`
m_p1 = StuntmanMap()
m_p1.MapType = MapType.Parameter
m_p1.MapName = "Delay"
m_p1.MapObject = "Delay"
m_p1.ValuesFloat = [1.0] * n
m_p1.Unit = ASUnit.uMINUTE
m_p1.Rows = list(rows_list)
m_p1.Columns = list(cols_list)
m_p1.Tags = ["Processing"]
m_p1.GroupNumber = G_PROC # 处理步骤所在的执行组
m_p1.DestinationKey = lib_dst.Key
m_p1.Description = "Parameter: delay"
design.Maps.Add(m_p1)
`
三段代码照原厂指南第 17–18 页。原文第 18 页 Key 的大小写有 .Key 和 .key 两种,这里照原文保留。
然后把设计放进 StuntmanFile,交给 Writer.WriteStuntmanHdf() 写盘。一个 StuntmanFile 可以装多份设计。
`
design.SetMapObjects() # 解析 MapObject 交叉引用
design.UpdateSelectedWells() # 计算每个样品库的 SelectedWells
file_container = StuntmanFile()
file_container.Designs.Add(design)
output_path = r"C:\Stuntman\MyExperiment.stunt"
Writer.WriteStuntmanHdf(output_path, file_container)
print("[SUCCESS] File generation complete!")
`
写出的 .stunt 是 HDF5 文件,里面是一份完整的实验设计。要回看内容,用 PLAN 或 CONVERT 打开浏览;要改,从 .stunt 导出 .py,改完再生成新的 .stunt。
CONVERT 的命令行程序做两件事:运行 .py 生成 .stunt,以及按硬件配置校验已有的 .stunt。校验确认设计正确、能在这台仪器上执行。退出码 0 表示成功,1 表示出错,包括脚本异常、校验失败和找不到文件。
参数 / 取值 / 作用
第一个位置参数:取值 script.py;作用 要运行的 Python 脚本
第二个位置参数:取值 output.stunt;作用 输出文件路径,可省略
-o, --output:取值 路径;作用 输出 .stunt 文件路径
-p, --python-dll:取值 路径;作用 Python DLL 路径,如 python38.dll
-i, --input:取值 路径;作用 要校验的 .stunt 文件
-c, --system-config:取值 路径;作用 SystemConfiguration.xml 路径
-h, --help, /?:作用 显示用法
`
Stuntman.Convert.exe my_design.py
Stuntman.Convert.exe my_design.py my_output.stunt
Stuntman.Convert.exe my_design.py -o my_output.stunt
Stuntman.Convert.exe my_design.py -p "C:\Python38\python38.dll"
Stuntman.Convert.exe -i my_design.stunt -c SystemConfiguration.xml
Stuntman.Convert.exe --help
`
批处理或外部调度脚本可以按退出码判断生成和校验是否成功。由脚本逐轮生成设计、转成 .stunt 的例子见 闭环优化应用笔记。