HTRI二次开发教程08实战一——Xist 壳管式换热器参数扫描与断点续扫版本与事实声明版本锚点当前Xchanger Suite 9.49.4 起支持run selected cases individually可单选中案例运行对大规模案例集管理有直接价值。官方对照物HTRI Parametric Study Tool基于 Excel 与 OLE按模板*.htri批量改变参数官方称其intended for users with experience using and knowledge of the underlying data models。示例代码中所有标识符为占位符所有数值为示例性建模不代表任何标准规定不对应任何真实装置。一句话结论Xist 参数扫描的正确工程形态是模板案例 变量-目标契约 状态机 断点账本——用一份*.htri模板派生 N 个案例每个案例的状态待跑/成功/超时/失败落进账本脚本可随时中断再续结果汇成案例编号 × 变量 × 目标的长表这与官方 Parametric Study Tool 是同一思路区别只在于自建脚本更灵活、官方工具更省事。〇、本篇要解决的认知问题Q1官方 Parametric Study Tool 已经能批量跑案例为什么还要自己写扫描脚本Q2一个规范的变量-目标契约应该长什么样为什么它是扫描工程的地基Q3全因子扫描和拉丁超立方Latin Hypercube扫描各自适合什么场景Q4批量状态机提交→运行→超时→重试怎么设计才能既跑得完又不失控Q5断点账本为什么是批量扫描敢中断、能续跑的关键一、机制解析1.1 官方工具有多能自建脚本补什么官方知识库对 Parametric Study Tool 的描述很明确用 Excel OLE基于模板*.htri文件在系列中运行大量案例、改变你选择的参数用于研究灵敏度同时强调它面向熟悉底层数据模型的用户。那么自建脚本的定位是维度官方 Parametric Study Tool自建脚本本篇上手成本低Excel 界面中需要探测 编码灵活性受工具设计约束高任意变量组合、任意目标函数与外部系统集成弱强可接优化器、数据库、报表管道无人值守/调度一般强可进计划任务/CI适用快速灵敏度研究平台级批量核算、参数辨识、多目标筛选决策逻辑经验法则一次性灵敏度研究先用官方工具要进生产流水线定时、断点续跑、结果落库、联动优化则自建脚本。两者底层都是同一条 Automation Server 通道思路一致。1.2 变量-目标契约扫描工程的地基是一张契约表扫哪些变量、每个变量的取值集合、看哪些目标量、单位是什么。契约最少含variable: name规范路径, values[] 或 (min, max, step) 或 distribution target: name规范路径, unit, aggregationlast/mean/max fixed: 保持不变的字段模板里已设好扫描时不动 mode: rating / simulation / design决定变量可写性为什么它是地基没有契约“扫描就退化成随手改数”。契约让扫描可复现、可审计、可交给同事它还是断点账本的 schema 来源。1.3 全因子 vs 拉丁超立方方法特点维度爆炸适合全因子full factorial每个变量每个水平都组合覆盖完整极快k^n变量少2~3 个、水平少、要完整响应面拉丁超立方LHS每维分层采样样本在空间中分布均匀线性给定样本数变量多、只要趋势/统计特征反直觉点全因子听起来最完整但 5 个变量各 5 水平 3125 个案例——在桌面 OLE 上按每个案例几十秒到几分钟算是数天到数周的量级。先算清案例数 × 单案例耗时再决定采样方法这是扫描设计的第一颗刹车。1.4 批量状态机单个案例的四个状态pending待跑→running运行中→done成功或timeout/failed。状态机要点超时即转 timeout不阻塞后续案例重试有上限如 1 次避免永远重试失败分类可重试超时、偶发 COM 错误vs 不可重试字段写错、模式不匹配每案例记账账本即状态机的外部存储。1.5 断点账本断点续扫的关键每完成或失败一个案例就落一次账。脚本重启时先读账本跳过已经是done的案例只补pending/timeout/failed。最佳实践账本写追加 幂等。同一个案例编号允许多条记录取最新一条为当前状态——这样重跑天然安全不会产生重复行歧义。1.6 扫描设计的三条刹车为什么这对你重要参数扫描最容易犯的错是直接开跑跑到一半发现案例数失控、或者结论根本无法解释。三条刹车必须在设计阶段踩下。刹车一先算案例数 × 单案例耗时。全因子是 k^n5 个变量各 5 水平就是 3125 个案例若单案例 90 秒串行约 78 小时——这不叫扫一下叫跑一周。算不出这个数就不许按 Run。刹车二先圈定哪些变量真的需要扫。第 03 篇说过Xist 自带 Grid design option按步长扫几何与 Smart Design启发式找最优。凡是程序内能替你扫的就别在外层脚本再扫一遍——外层扫描应聚焦程序内做不了的组合如跨模块、跨工况、带外部数据。变量裁剪的先问改这个变量工程上会做出不同决策吗会才扫。刹车三先定看完结果做什么。扫描的产物是决策依据而非数据量。开始前就要写下看哪个目标量、超过什么阈值算关注、不同结论分别触发什么动作。没有这三句的扫描跑完只会得到一张没人会用的表。一条纪律模板只读。扫描的每一个案例都从同一份原始模板派生第 07 篇的绝不覆盖模板模板置为只读或单独备份。模板一旦被某次运行污染后续所有案例都是垃圾进垃圾出而且这种错误不会报错。二、完整代码与逐行剖析代码 8-1扫描契约与案例矩阵生成# -*- coding: utf-8 -*- sweep_contract.py —— 定义扫描契约并生成案例矩阵不触碰 HTRI 用法python sweep_contract.py 输出cases.csv案例矩阵含 case_id 与各变量取值 importitertoolsimportcsvimportjson# 扫描契约示例性建模CONTRACT{template:template.htri,mode:rating,variables:{geometry.exchanger.shell_id:[700.0,800.0,900.0],# mmgeometry.tube_geometry.tube_length:[5000.0,6000.0],# mmgeometry.exchanger.baffle_spacing:[250.0,300.0,350.0],# mm},targets:{outputs.summary.overall_u:{unit:W/(m2·K),agg:last},outputs.summary.shell_dP:{unit:kPa,agg:last},},method:full_factorial,# full_factorial / lhsdisclaimer:示例性建模不代表任何标准规定不对应任何真实装置,}defgen_full_factorial(variables):keyslist(variables.keys())forcomboinitertools.product(*(variables[k]forkinkeys)):yielddict(zip(keys,combo))defmain():rows[]fori,comboinenumerate(gen_full_factorial(CONTRACT[variables]),start1):row{case_id:fcase_{i:04d}}row.update(combo)rows.append(row)withopen(cases.csv,w,newline,encodingutf-8-sig)asf:wcsv.DictWriter(f,fieldnameslist(rows[0].keys()))w.writeheader()w.writerows(rows)withopen(sweep_contract.json,w,encodingutf-8)asf:json.dump(CONTRACT,f,ensure_asciiFalse,indent2)nlen(rows)print(f案例矩阵{n}个案例 - cases.csv)print(f提示请先估算{n}× 单案例耗时再决定是否改用拉丁超立方。)if__name____main__:main()逐行剖析契约把变量取值集合与目标量分开列variables是自变量targets是观测量。目标的agg聚合方式字段很重要——同一目标可能有多处值总览/局部需声明取哪个。gen_full_factorial用itertools.product生成笛卡尔积3×2×3 18 个案例是个能一眼看懂的小例子。case_id用零填充编号case_0001保证字符串排序与数值排序一致账本里好排查。sweep_contract.json落盘契约本身也是待审计产物第 10 篇的落盘纪律。打印先估算实例数与耗时把 1.3 节的刹车机制写进脚本输出提醒使用者别一头冲进维度爆炸。代码 8-2带断点账本的批量扫描器占位符# -*- coding: utf-8 -*- sweep_xist.py —— Xist 参数扫描 断点续扫占位符须替换真实标识符 用法python sweep_xist.py 依赖cases.csv、sweep_contract.json、datadict.csvreal_identifier 已填 账本ledger.csv追加 幂等取每个 case_id 的最新记录为当前状态 importcsvimportjsonimporttimeimportdatetimefromdrive_caseimportsession,set_field,load_writable_map,cleanup_leftover PROGIDHTRIAutomationServer.ProgID本机枚举所得OP_LOAD打开案例的方法探测所得OP_RUN运行案例的方法探测所得OP_SAVE另存案例的方法探测所得RUN_TIMEOUT_S300MAX_RETRY1defload_ledger(pathledger.csv):读账本 - {case_id: 最新状态}state{}try:forrincsv.DictReader(open(path,encodingutf-8-sig)):state[r[case_id]]r# 后出现覆盖先出现 取最新exceptFileNotFoundError:passreturnstatedefappend_ledger(path,case_id,status,detail,resultsNone):header[case_id,status,detail,timestamp,results_json]existsTruetry:open(path,encodingutf-8-sig).close()exceptFileNotFoundError:existsFalsewithopen(path,a,newline,encodingutf-8-sig)asf:wcsv.DictWriter(f,fieldnamesheader)ifnotexists:w.writeheader()w.writerow({case_id:case_id,status:status,detail:detail,timestamp:datetime.datetime.now().isoformat(timespecseconds),results_json:json.dumps(resultsor{},ensure_asciiFalse),})defrun_one(case_row,contract,wmap,out_dir):跑单个案例返回 (status, results, detail)case_idcase_row[case_id]skipped[]withsession(PROGID,RUN_TIMEOUT_S60)as(app,start):casegetattr(app,OP_LOAD)(contract[template])forvar_pathincontract[variables]:set_field(case,var_path,float(case_row[var_path]),contract[mode],wmap,skipped)getattr(case,OP_RUN)()iftime.time()-startRUN_TIMEOUT_S:returntimeout,{},运行超时results{}fortgtincontract[targets]:entrywmap.get(tgt)ifnotentry:continuenodecaseforpartinentry[ident].split(.):nodegetattr(node,part)results[tgt]getattr(node,叶子属性名探测所得)getattr(case,OP_SAVE)(f{out_dir}/{case_id}.htri)ifskipped:returndone,results,f跳过{len(skipped)}个字段returndone,results,defmain():contractjson.load(open(sweep_contract.json,encodingutf-8))caseslist(csv.DictReader(open(cases.csv,encodingutf-8-sig)))wmapload_writable_map()stateload_ledger()forrowincases:cidrow[case_id]curstate.get(cid)ifcurandcur[status]done:continue# 断点续扫跳过已完成attempt0whileattemptMAX_RETRY:try:status,results,detailrun_one(row,contract,wmap,out)breakexceptExceptionase:# noqa: BLE001status,results,detailfailed,{},f{type(e).__name__}:{e}attempt1append_ledger(ledger.csv,cid,status,detail,results)print(f{cid}:{status}{detail})cleanup_leftover()print(扫描结束。结果是 ledger.csv 中每个 case_id 的最新记录。)if__name____main__:main()逐行剖析load_ledger用后出现覆盖先出现取最新记录实现追加 幂等的账本语义重跑安全。append_ledger每次只追加一行崩溃也不会损坏已写数据这是断点续扫能成立的前提。run_one把模式守卫复用set_field→ run → 超时判定 → 取目标 → 另存封装成一次完整生命周期直接复用第 07 篇的组件——组件化让本篇只需关心扫描逻辑。while attempt MAX_RETRY把重试限定为有限次避免永远重试把批处理拖死可重试/不可重试的分类实际工程里应按异常类型细化。跳过status done的案例断点续扫的核心动作一行搞定。结果写进账本的results_json列账本既是状态机、又是结果暂存第 10 篇会把它规范化为结果长表。三、常见报错与排查报错 3-1扫描跑了几十个案例后HTRI 实例堆积、机器变卡。现象进程数随时间增长。根因某条异常路径没走到释放。解法确保所有运行都包在session里每 N 个案例调一次cleanup_leftover清点必要时把批处理拆成多个短进程每个进程跑几十个案例后退出。报错 3-2某个案例反复失败脚本卡在那一个。现象批处理停住。根因重试无上限或该案例触发了桌面弹窗阻塞。解法设MAX_RETRY如 1把不可重试的错误分类出来记failed后继续对弹窗类阻塞超时后转timeout不强等。报错 3-3重跑扫描后结果重复/矛盾。现象结果表里同一case_id出现矛盾值。根因账本语义没约定取最新或结果既写账本又写独立文件造成两处不一致。解法约定账本取最新记录结果落盘以账本为唯一真相源第 10 篇规范化。报错 3-4扫描结果整体偏移像被平移了。现象趋势对但数值系统性偏差。根因模板被save覆盖后续案例基于被改过的模板派生。解法断言out_case ! template模板置为只读每轮从原始模板 load。报错 3-5全因子案例数远超预期跑不完。现象矩阵 3000 案例。根因维度爆炸没提前估算。解法先按 1.3 节估算实例数×耗时改用 LHS 采样或先在程序内用 Xist 的 Grid design option 缩小范围再对关键点做脚本扫描。四、动手练习练习 1契约与矩阵修改代码 8-1 的variables为你的场景运行生成cases.csv。判定案例数 各变量取值数之积全因子case_id连续且零填充。练习 2案例数估算在笔记里写下案例数 × 单案例实测耗时的估算值并据此决定是否改用 LHS。判定能给出具体数字如 18 × 90 s ≈ 27 min并说明结论。练习 3断点续扫跑代码 8-2 到一半时用 CtrlC 中断再重跑。判定重跑时已完成案例被跳过账本中done的case_id不再出现在运行日志最终ledger.csv每个case_id的最新记录为done。练习 4失败注入故意把一个变量值设成非法值如负壳径跑一次。判定该案例记为failed或timeout但整批继续账本中其余案例正常done。五、小结与下一篇预告本篇把生命周期骨架套进真实批量场景契约先行变量-目标-模式、采样方法按案例数决定全因子 vs LHS、状态机pending/running/done/timeout/failed 有限重试、断点账本追加 幂等 取最新。产出sweep_contract.json、cases.csv、ledger.csv三件套为平台化打下骨架。同时明确了与官方 Parametric Study Tool 的分工一次性用官方生产化自建。第 09 篇《结果取数》扫描产出了账本但逐字段读对象只是取数的一条路。我们要系统比较对象模型取数与报表导出件解析两条路讲清 summary/detailed 报表的结构差异、多单位集的换算纪律并把取数结果规范化为可分析的 DataFrame。本篇认知问题回显FAQQ1官方 Parametric Study Tool 已能批量跑案例为什么还要自建扫描脚本A官方工具基于 Excel 与 OLE、按模板*.htri批量改参数上手成本低适合一次性灵敏度研究但它灵活性受工具设计约束、与外部系统集成弱、无人值守与调度能力一般。自建脚本底层走同一条 Automation Server 通道胜在可任意组合变量、接优化器/数据库/报表管道、进计划任务与 CI适合平台级批量核算与参数辨识。Q2规范的变量-目标契约应该长什么样A至少含四类信息变量规范路径 取值集合或范围/分布、目标规范路径 单位 聚合方式 last/mean/max、固定项模板已设、扫描不动、模式rating/simulation/design决定变量可写性。契约是扫描可复现、可审计、可交接的地基也是断点账本 schema 的来源。Q3全因子与拉丁超立方各适合什么场景A全因子full factorial覆盖完整适合变量少2~3 个、水平少、需要完整响应面的场景但案例数随维度呈 k^n 爆炸拉丁超立方LHS每维分层采样、样本分布均匀案例数线性可控适合变量多、只取趋势或统计特征的场景。决策前先算案例数 × 单案例耗时。Q4批量状态机怎么设计才既跑得完又不失控A单案例四状态 pending→running→done/timeout/failed超时即转 timeout 不阻塞后续重试设上限如 1 次避免永远重试区分可重试超时、偶发 COM 错误与不可重试字段写错、模式不匹配每个案例完成或失败立即落一次账账本即状态机的外部存储。Q5断点账本为什么关键A账本让扫描敢中断、能续跑。做法是每个案例完成(或失败)即追加一行记录脚本重启时先读账本、跳过done的案例只补 pending/timeout/failed。约定同一 case_id 取最新记录实现幂等重跑天然安全不会产生重复行歧义也便于失败注入演练后回看每案例状态。