NUPACK replica / Design workflow notes

Design 使用笔记

这份笔记只讲当前网页里已经接入的功能：Design domains、target complexes、target tubes、hard constraints、soft constraints 和 defect weights。

1. 快速跑通

主界面选择 Design，点击 载入示例，会得到一个可直接运行的双链设计：

domain:
  a = N10

strands:
  A = a
  B = ~a

target complex:
  AB_target = A+B
  structure = (10+)10

target tube:
  AB_target = 1 uM
  off-target max size = 2

~a 表示 domain a 的反向互补，因此 (10+)10 这个全双链目标结构是合法的。

2. Targets 怎么填

区域	含义	示例
Design Domains	给每段可设计区域命名，并写 IUPAC 约束。	`a = N10`
链输入	Design 模式下，序列框可以写 domain composition。	`A = a`, `B = ~a`
Target Complex	指定哪些链组成目标复合物，以及目标二级结构。	`A+B`, `(10+)10`
Target Tube	Tube design 才需要。指定 on-target 浓度，off-target 由 max size 自动补全。	`AB_target = 1 uM`

3. 混合材料 Design

选择 rna-dna06 或 rna-merna06 后，Domain 约束必须显式标注小写材料前缀。点击“插入混合片段模板”可生成可直接编辑的起点：

RNA/DNA:      mixed1 = rN6dN6
RNA/2′OMe:    mixed1 = rN6mN6
材料也可设计: mixed1 = wN12

r、d、m 分别表示 RNA、DNA、2′OMe-RNA；w 表示 wildcard material。材料前缀不计入碱基长度，IUPAC 约束与计数仍可组合，例如 rS4dN8。

链输入仍推荐填写 Domain composition，例如 A = mixed1、B = ~mixed1。反向互补由所选模型的 material alphabet 计算，结果和“载入为 Analysis”都会保留材料前缀。

4. Hard constraints 怎么用

Hard constraint 是“必须满足”的约束，写错会让设计空间为空，或直接报错。

类型	必填字段	当前推荐示例
Match	左侧、右侧	`a` 与 `a`
Complementarity	左侧、右侧	`A` 与 `B`
Similarity	scope、reference、上下限	`scope=a`, `reference=R10`
Window	scope、source sequences	`scope=a`, 每行一个 10 nt source
Pattern	patterns；scope 可空表示全局	`AAAA, UUUU`

如果看到 “Constraint scope cannot be empty”，就是当前 constraint 类型需要填写 scope，但该字段为空。新版界面会在提交前拦截这类错误。

5. Soft constraints 和 weights

Soft constraint 不会替代 ensemble defect，只是给优化目标增加加权惩罚。权重越大，设计器越偏向满足它，但也可能变慢。

Defect weights 用来告诉设计器哪些 domain、strand、complex 或 tube 更重要。初学时建议先不填，确认 target 能跑通后再逐步添加。

6. 推荐的分阶段流程

复杂体系不要一开始就把搜索条件设到最终验证强度。推荐把“找候选序列”和“验证候选序列”分开：

阶段	建议设置	目的
输入检查	1 trial，max size 2，`f_stop=0.1–0.2`，填写明确的最大时间	先确认 targets、结构和约束可行，并快速暴露填写错误。
正式设计	从已验证输入逐步收紧 `f_stop`；确有需要时再增加 trials	获得候选序列。每个 trial 都是一次完整随机搜索，不是免费的重复采样。
最终验证	把设计结果载入 Analysis，以 max size 3–4 检查更大的复合物集合	保留严格的最终热力学验证，同时避免在每一步优化迭代中反复枚举大集合。

分阶段流程会改变“在哪个阶段计算哪些集合”，但不会偷减最终验证。若研究目标明确要求在优化目标中直接包含 size 3–4 off-target，应保留该设置并给任务填写最大时间。

7. 为什么 Design 会慢

NUPACK design 是优化问题，不是一次性的结构分析。影响耗时的主要因素：

off-target max size 越大，需要考虑的非目标复合物越多。
f_stop 越小，停止条件越严格，通常越慢。
trials 大于 1 时会跑多个随机种子，NUPACK 源码里会并行提交多个 trial。
hard constraints 太多或互相矛盾，会反复搜索甚至失败。

页面的“设计预检”会实时显示可变碱基数、固定目标数和复合物上限，并提醒无限时长、严格停止阈值、多 trial 与大 off-target 集合。它只做估算和提示，不会改写提交参数。

当前服务会按 CPU 和内存自动限制同时运行的任务数，并已显式设置 NUPACK 的 config.threads。这些调度参数不改变模型、约束或结果目标；它们主要用于防止多个 8–9 GB 任务把机器内存耗尽。增加线程不保证单个 design 等比例加速，因为部分优化阶段主要使用单核；多任务通常比单任务更容易占满多核。增加内存本身也不会让搜索更快，只会减少 OOM、换页和缓存压力。

当前 NUPACK 4.1.0.1 wheel/镜像不是 CUDA 构建，且官方分发包中没有附带 source/ 源码树；直接填写环境变量或安装显卡不能生效。GPU 路线需要重新编译或替换核心 wheel，并对结果一致性与稳定性重新测试。