Appearance
附录：命令参考、文件格式与示例索引
来源：
mystic_ug.pdf（W‑2024.09），综合各章节汇总整理。
本附录汇集 Mystic 在日常使用中最常查阅的三类参考信息：命令行选项速查、核心 JSON/文件格式规范，以及各章示例的索引。
A.1 命令行选项速查
完整调用形式：
bash
Mystic <strategy.py> [选项]| 选项 | 长格式 | 说明 |
|---|---|---|
<script> | — | 必填。包含提取策略的 Python 脚本路径。 |
-ac | --auto-close | GUI 模式下策略完成后自动关闭窗口。 |
-ar | --auto-run | GUI 模式下自动开始执行策略（常与 -g 联用）。 |
-d <path> | --db <path> | 指定 TCAD to SPICE 数据库配置文件路径。 |
-ds <name> | --dataset <name> | 指定当前运行结果写入数据库的 dataset 名称。 |
-g | --gui | 以 GUI 交互模式启动 Mystic。 |
-h | --help | 打印帮助信息并退出。 |
-l <path> | --location <path> | 指定 PrimeSim HSPICE 可执行文件路径，覆盖系统默认版本。 |
-m <file> | --model <file> | 指定初始 SPICE 模型卡文件（.mdl / .scs）。 |
-o <name> | --optimizer <name> | 在命令行覆盖策略脚本中默认的优化算法。 |
-v | --version | 打印 Mystic 版本信息并退出。 |
-x <args> | --spice-args <args> | 将额外参数传递给 PrimeSim HSPICE 运行时。 |
典型调用示例：
bash
# 独立命令行运行（非 SWB 环境）
Mystic strategy_stage1.py -d db_config.json -m init.mdl -ds stage1
# GUI 模式下自动运行并完成后关闭
Mystic strategy.py -g -ar -ac
# 仅启动 GUI，手动选择脚本
Mystic --guiA.2 核心文件格式说明
A.2.1 数据库配置文件（db_config.json）
当以独立模式（非 SWB）运行时，需手动提供数据库连接配置：
jsonc
{
"db_type": "local", // 目前支持 "local"（文件系统数据库）
"db_path": "./mystic_db", // 数据库根目录（自动创建）
"project": "my_project" // 项目名，对应数据库顶层节点
}A.2.2 数据对象元数据结构
通过 mdb.Load() 或 Data 类上传数据时，每条记录均包含以下元数据字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
temperature | float | 是 | 仿真温度，单位开尔文（K）。 |
bias | dict | 是 | 静态偏置，键名须与 SPICE 端点名一致，例如 {"vg": 0.0, "vd": 0.0}。 |
instances | dict | 是 | 器件实例参数，无额外参数时传空字典 {}。 |
nodes | list | 是 | 端点顺序列表，顺序需与 bias 键匹配。 |
ivar | str | 自动 | 主变量（扫描变量）标签，上传时由框架自动设置。 |
dvar | str | 自动 | 从变量（目标变量）标签，上传时由框架自动设置。 |
| 自定义键 | any | 否 | 任意键值对，可用于后续筛选，例如 "type": "nMOS"。 |
A.2.3 PLT 目标数据文件格式
Sentaurus Visual 导出的 .plt 文件为空格/制表符分隔的多列文本：
# 第一行为注释（可选）
# ivar_name dvar_name [其他列...]
0.0 1.23e-12
0.1 5.67e-10
0.2 1.89e-8
...上传时使用 Data.upload_plt(filepath, ivar="vg", dvar="ids", metadata={...})，框架会自动解析列名与数值并校验元数据完整性。
A.2.4 CSV 目标数据文件格式
CSV 文件要求首行为列标题，标题须与 ivar/dvar 名称对应：
csv
vg,ids,vd
0.0,1.23e-12,0.05
0.1,5.67e-10,0.05
0.2,1.89e-8,0.05上传时使用 Data.upload_csv(filepath, ivar="vg", dvar="ids", metadata={...})。
A.2.5 SPICE 模型卡格式（参考）
Mystic 兼容标准 HSPICE .mdl 与 Spectre .scs 格式：
spice
* BSIMCMG NMOS 示例模型卡（.mdl 格式）
.model nfet bsimcmg
+ type=1
+ toxe=1.2e-9 toxp=1.0e-9
+ lg=14e-9 lgs=0 lgd=0
+ ...Model 对象通过 -m 参数载入初始模型卡，并在每次迭代中就地修改参数值。
A.3 核心 Python API 速查
以下列出最常使用的 API，详细参数请查阅本地安装的 API 文档（$STROOT/tcad/$STRELEASE/manuals/tcad_spice/mystic_api/index.html）。
A.3.1 数据操作
python
from mystic import mdb, SimData, Data
# 上传 PLT 文件
d = Data()
d.upload_plt("idvg_room.plt", ivar="vg", dvar="ids",
metadata={"temperature": 300, "bias": {"vd": 0.05}, "instances": {}, "nodes": ["vg", "vd"]})
# 从数据库加载目标数据（首阶段）
sim_data = mdb.Load(dataset="stage1", filter={"type": "nMOS"})
# 从数据库加载上阶段拟合结果（后续阶段）
fit_data = mdb.GetFitData(dataset="stage1")A.3.2 模型与仿真
python
from mystic import Model, Simulator, OptimizationParameter as OptParam
# 载入模型卡
model = Model("init.mdl")
# 定义待提取参数
params = [
OptParam("toxe", init=1.2e-9, min=0.8e-9, max=1.8e-9),
OptParam("lg", init=14e-9, min=10e-9, max=20e-9),
]
# 配置仿真器
sim = Simulator(model, temperature=300)
sim.set_options({"scale": 1e6})A.3.3 优化器调用
python
from mystic import Optimizer
opt = Optimizer("Gradient") # 或 "GA", "SA", "LM", "LBFGSB"
opt.run(sim_data, params, model, sim)A.4 各章示例索引
| 章节 | 示例主题 | 关键 API / 概念 |
|---|---|---|
| Ch2：上传目标数据 | PLT/CSV 数据上传、元数据校验 | Data.upload_plt, Data.upload_csv, mdb.Load |
| Ch3：提取策略 | 三阶段 MOSFET 提取、ML 加速 | SimData, Model, Simulator, Optimizer, ExtractionUtils |
| Ch4：特殊提取场景 | 瞬态、MOSRA、PCA 变异、RF、LUT、约瑟夫结 | SimData.transient, Corrector, LinkedOptimizationParameter |
| Ch5：Mystic GUI | GUI 面板布局、调试与可视化 | --gui, -ar, -ac 选项；SWB 集成 |
| Ch6：示例项目 | 14 nm FinFET 三阶段完整提取 | 全流程脚本、mdb.StoreInitialModel, mdb.GetFitModel |
A.5 常见错误与排查
| 错误信息 | 原因 | 解决方法 |
|---|---|---|
KeyError: 'temperature' | 元数据缺少 temperature 字段 | 在 metadata 字典中添加 "temperature": 300（单位 K）。 |
Model is None | 未通过 -m 提供模型卡 | 在命令行加 -m <model.mdl>，或在策略脚本中手动初始化 Model。 |
mdb is None | 独立模式下未提供 -d 数据库配置 | 加 -d db_config.json 或在策略中直接使用 SimData 而非 mdb。 |
| 优化停在边界 | 参数上下限设置过窄 | 先基于 PDF 默认值放宽范围，收敛后再缩小区间。 |
| HSPICE 仿真超时 | 网表复杂度过高或步长过细 | 使用 -x "+accurate=0" 降低精度要求，或缩短扫描范围。 |
nodes 与 bias 不匹配 | 端点顺序与偏置键名不一致 | 确保 nodes 列表的顺序与 bias 字典的键完全对应。 |
如需查阅完整 Python API 文档，请访问本地安装路径：
$STROOT/tcad/$STRELEASE/manuals/tcad_spice/mystic_api/index.html
或通过 SWB 菜单 Help › Python API Documentation › Mystic 打开。