FRI 与 KG-TOWER 二次开发教程12结果结构化落盘与设计裕度判定版本与事实声明环境Python 3.8仅标准库Parquet 落盘可换 pandas 2.3.3 pyarrow。判据阈值均为示例值经验法则须按企业标准与体系调整。判据出处泛点率上限与操作/漏液比下限为经验法则见第 05/07 篇降液管背压判据来自 KLM《Tray Hydraulics》p.45–49E9。文中任何数值为示例性建模不代表任何标准规定不对应任何真实装置数据。不涉及 FRI/KG-TOWER 的任何 API两者均无公开 API。一句话结论设计裕度不是一个布尔量而是一组带归一化的裕度——把泛点率、漏液比、背压比、压降四类判据各自算出占阈值的比例取最小值即为最紧项binding示例 5 行中 4 行最紧项是dP如 D1.0/load0.85 的最紧归一裕度 -0.747判为越限唯一合格行是 D1.3/load0.85最紧项weep归一裕度 0.011而落盘的 JSON 必须同时含limits / units / rows三段才可审计。〇、本篇要解决的认知问题Q1结果应该落成长表还是宽表为什么这是可审计性的问题Q2四类裕度分别是什么为什么必须归一化后才能比大小Q3最紧项binding有什么工程意义它比合格/不合格多给了什么信息Q4判据阈值为什么必须三级标注铁律/最佳实践/经验法则混用会出什么事Q5CSV/JSON 元数据里必须有哪些字段才能让一年后的你或审计员复现结论一、机制解析1.1 长表 vs 宽表可审计性决定选择为什么这对你重要落盘格式看着是技术细节其实是可审计性的基础。形式结构优点缺点适用长表long一行 一个 (案例 × 判据量)新增判据零成本、易追加、易 SQL 过滤单案例读起来要透视结果表、审计底账宽表wide一行 一个案例列 各判据量人读直观、配图方便新增判据要改表结构、旧文件不兼容交付报表、展示本系列的纪律长表存底账、宽表做交付。底账长表是唯一事实来源任何展示/报表都由它生成这样即使报表版式变了底账仍是可信的与第 08 篇报表解析的纪律同源。1.2 四类裕度与归一化判据量与裕度定义示例阈值判据量阈值裕度定义方向泛点率flood_pct≤ 85%85 − flood_pct越大越好操作/漏液比weep_ratio≥ 1.5weep_ratio − 1.5越大越好背压比dc_ratio≤ 1.01.0 − dc_ratio越大越好单板压降h_t≤ 150 mm 液柱150 − h_t越大越好为什么要归一化四类裕度的量纲与量级都不同百分点、无量纲比、毫米液柱。直接比大小等于拿苹果比卡车。归一化方式除以各自阈值得到占阈值的比例归一裕度i裕度i阈值i,最紧归一裕度mini(归一裕度i)\text{归一裕度}_i\frac{\text{裕度}_i}{\text{阈值}_i},\qquad \text{最紧归一裕度}\min_i(\text{归一裕度}_i)归一裕度i阈值i裕度i,最紧归一裕度imin(归一裕度i)最紧项就是取到最小值的那个判据名flood/weep/dc/dP。1.3 binding 的工程意义从合格到往哪改只报合格/不合格的信息量极低一旦报出最紧项行动方向立刻明确最紧项 dP - 压降是瓶颈加大开孔率 / 减小孔径 / 改阀塔板 / 加大板间距 最紧项 flood - 容量是瓶颈加大塔径 / 加板间距 / 换高容量内件 最紧项 weep - 操作下限是瓶颈减小开孔率 / 减小孔径 / 改阀塔板 最紧项 dc - 降液管是瓶颈加大降液管面积 / 降压降 / 加板间距示例中 4 行最紧项都是dP最紧归一裕度约 -0.25 ~ -0.77、1 行是weep0.011。读这张表的方式负值即越限绝对值越大越偏离得远weep那一行为 0.011 说明刚刚够——工程上这种贴线合格应当引起警惕第 15 篇会把它翻译成概率。1.4 阈值的三级标注混用是灾难本系列的规则分级体系三级不可混用级别含义示例能否改动铁律违反必出硬错单位必须显式Fp 必须先统一到 ft⁻¹不可改最佳实践推荐但有例外先做物理量级校验再做判定可依场景调整经验法则行业常用阈值泛点率 ≤85%、操作/漏液比 ≥1.5、压降 ≤150 mm可配置但必须写明来源与版本为什么必须分开如果泛点率 ≤85%被当成铁律写死在代码里那么换体系发泡体系应更保守时就得改代码反之如果把单位必须显式当成可配置经验值系统迟早会因某次配置改错而整体失真。阈值必须进配置文件并在结果里回写用的哪一版阈值。1.5 落盘元数据三段式设计_margins.json ├── limits : 本次使用的全部阈值含版本/来源 ├── units : 每个量的单位铁律 5 的落地 └── rows : 长表结果含裕度与 binding为什么把limits和units与rows放在同一个文件这样任何一行结果都能自证它当时是在什么阈值与单位下判定的。没有limits的结果表是不可审计的——因为阈值一改所有判定结论都可能翻转。1.6 阈值配置的工程落地从常量到版本化文件阈值从代码常量升级为版本化配置需要三步抽取把所有经验阈值移出代码放进一个带版本号的配置文件如limits_v3.yaml文件头写明每个阈值的来源与调整历史如泛点率上限 85%来源企业内部设计规定第 X 条 / 经验法则。回写每次计算时把实际使用的阈值写进结果的limits段本文代码已如此使结果自证前提。回归阈值升级时同时重算全部历史结果并对比结论变化第 20 篇的回归测试机制。若某阈值一改就让大批方案从合格变不合格这本身就是需要上报的信息——它说明阈值的语义或口径此前被误解。为什么这对你重要经验阈值天然会随企业标准、体系特性与运行经验演化。把它们写死在代码里会让标准演进变成代码改动从而无法审计当时按哪版标准判定的。而版本化 回写 回归三步把标准演进变成数据演进。经验法则配置文件里的每个阈值都应有四要素——数值、单位、来源、生效日期。缺来源的阈值等于一个没人负责的数字。1.7 贴线合格的分类与处置本文的裕度体系会频繁遇到worst_norm很小正值但接近 0的情形。建议按下表分档处置阈值为示例经验值归一裕度区间判定处置建议≥ 0.20合格裕度充裕正常交付0.05 ~ 0.20合格裕度偏紧交付时标注建议复核0 ~ 0.05贴线合格标注marginal要求软件复核与不确定度分析第 15 篇 0越限回到设计自由度调整第 13 篇为什么单靠合格/不合格不够贴线合格意味着关联式误差一偏向不利侧结论就翻转。把它与裕度充裕的合格混为一谈等于把风险藏进了平均数里。二、完整代码与逐行剖析代码 2-1裕度计算 最紧项 三段式落盘可直接运行# -*- coding: utf-8 -*- margin.py —— 结果结构化落盘与设计裕度判定 判据三级标注铁律(单位)、最佳实践(先量级校验)、经验法则(阈值区间) 输出长表 CSV 三段式 JSONlimits / units / rows importcsv,json LIMITS{# 经验法则示例值可配置须写明来源与版本flood_pct_max:85.0,# 泛点率上限 %weep_ratio_min:1.5,# 操作/漏液比下限dc_ratio_max:1.0,# 充气背压/判据上限dP_mm_max:150.0,# 单板压降经验上限 mm 液柱}UNITS{flood_pct:%,h_t:mm liquid,weep_ratio:-,dc_ratio:-}defmargin_row(rec):m{}m[flood_margin]LIMITS[flood_pct_max]-rec[flood_pct]m[weep_margin]rec[weep_ratio]-LIMITS[weep_ratio_min]m[dc_margin]LIMITS[dc_ratio_max]-rec[dc_ratio]m[dP_margin]LIMITS[dP_mm_max]-rec[h_t]# 归一化裕度越接近 0 越危险负值越限norm{flood:m[flood_margin]/LIMITS[flood_pct_max],weep:m[weep_margin]/LIMITS[weep_ratio_min],dc:m[dc_margin]/LIMITS[dc_ratio_max],dP:m[dP_margin]/LIMITS[dP_mm_max],}m[worst_norm]min(norm.values())m[binding]min(norm.items(),keylambdakv:kv[1])[0]# 最紧项returnmdefcheck_units(rec,units):铁律校验关键量必须有单位标注need[flood_pct,h_t,weep_ratio,dc_ratio]return[kforkinneedifknotinunits]defmain():raw[{D:1.0,load:0.65,flood_pct:50.1,h_t:260.0,weep_ratio:1.60,dc_ratio:0.41},{D:1.0,load:0.85,flood_pct:65.5,h_t:262.0,weep_ratio:2.09,dc_ratio:0.52},{D:1.0,load:1.10,flood_pct:84.7,h_t:266.0,weep_ratio:2.71,dc_ratio:0.69},{D:1.2,load:0.65,flood_pct:34.9,h_t:170.0,weep_ratio:1.12,dc_ratio:0.30},{D:1.3,load:0.85,flood_pct:38.7,h_t:148.3,weep_ratio:1.55,dc_ratio:0.40},]misscheck_units(raw[0],UNITS)rows[]forrecinraw:merged{**rec,**margin_row(rec)}rows.append({k:(round(v,4)ifisinstance(v,float)elsev)fork,vinmerged.items()})withopen(_margins.csv,w,newline,encodingutf-8)asf:wcsv.DictWriter(f,fieldnameslist(rows[0].keys()))w.writeheader();w.writerows(rows)print(单位标注缺失项:,missor无)forrinrows:print(fD{r[D]}load{r[load]:.2f}: 泛点率{r[flood_pct]:.1f}% f压降裕度{r[dP_margin]:7.1f}最紧项{r[binding]:5}f最紧归一裕度{r[worst_norm]:.3f}-{合格ifr[worst_norm]0else越限})withopen(_margins.json,w,encodingutf-8)asf:json.dump({limits:LIMITS,units:UNITS,rows:rows},f,ensure_asciiFalse,indent2)print(\n已写出 _margins.csv 与 _margins.json含 limits/units/rows 三段可审计)if__name____main__:main()实测输出本机 Python 3单位标注缺失项: 无 D1.0 load0.65 : 泛点率50.1% 压降裕度 -110.0 最紧项 dP 最紧归一裕度-0.733 - 越限 D1.0 load0.85 : 泛点率65.5% 压降裕度 -112.0 最紧项 dP 最紧归一裕度-0.747 - 越限 D1.0 load1.10 : 泛点率84.7% 压降裕度 -116.0 最紧项 dP 最紧归一裕度-0.773 - 越限 D1.2 load0.65 : 泛点率34.9% 压降裕度 -20.0 最紧项 dP 最紧归一裕度-0.253 - 越限 D1.3 load0.85 : 泛点率38.7% 压降裕度 1.7 最紧项 weep 最紧归一裕度0.011 - 合格 已写出 _margins.csv 与 _margins.json含 limits/units/rows 三段可审计逐段剖析LIMITS明确注释为经验法则示例值可配置须写明来源与版本——把阈值从代码里解放出来。在生产实现中它会来自一个带版本号的配置文件如limits_v3.yaml并被回写进结果。margin_row()先算绝对裕度再算归一裕度最后min()取最紧项逻辑分两步是因为绝对裕度对人有用-110 mm 直观归一裕度对机器有用可跨判据比较。反直觉点 1D1.0/load1.10 的泛点率已经84.7%非常贴近 85% 上限但它不是最紧项——最紧项仍是dP-0.773。这告诉你看起来最危险的指标未必是真正的瓶颈只有归一化后才能分辨。反直觉点 2唯一合格行的worst_norm是0.011——归一化裕度只有 1.1%。用绝对量看漏液比 1.55 vs 下限 1.5“只多了 0.05”很不起眼归一化后立刻暴露这是贴线合格。贴线合格 高风险这正是归一化的价值。check_units()返回空列表 → 打印无这是铁律级校验单位必须标注它不参与LIMITS因为铁律不可配置。_margins.json的三段式limits与units与rows同源同文件——任何行都能自证判定前提。代码 2-2阈值改编后的结论翻转演示为什么必须版本化阈值# -*- coding: utf-8 -*-threshold_flip.py —— 阈值小幅调整如何翻转结论说明阈值必须版本化LIMITS_V1{dP_mm_max:150.0}LIMITS_V2{dP_mm_max:270.0}# 若企业标准放宽defverdict(h_t,limits):return合格ifh_tlimits[dP_mm_max]else越限if__name____main__:cases[(D1.0/load0.85,262.0),(D1.3/load0.85,148.3)]forname,h_tincases:print(f{name:18}h_t{h_t:6.1f}mm : V1(150)-{verdict(h_t,LIMITS_V1):4}f V2(270)-{verdict(h_t,LIMITS_V2)})实测输出D1.0/load0.85 h_t 262.0 mm : V1(150)-越限 V2(270)-合格 D1.3/load0.85 h_t 148.3 mm : V1(150)-合格 V2(270)-合格逐段剖析同一批数据阈值从 150 改到 270 mm第一行结论从越限翻成合格。这就是为什么limits必须随结果落盘——否则一年后你看到这批工况都合格却无法知道当时用的是哪一版阈值。最佳实践阈值改进时同时重算全部历史结果回归测试第 20 篇而不是只对新结果用新阈值。三、常见报错与排查报错 3-1KeyError: flood_pctinmargin_row。现象裕度计算报缺字段。根因上游扫描表列名不一致如Flooding %或该行解析失败。解法入口统一列名第 08 篇的别名表缺字段的行标 NA 并进warnings不要让裕度函数去猜。报错 3-2所有行的最紧项都是同一个判定怀疑算错。现象如本例 4/5 行都是dP。根因很可能算对了——该设计点的确压降是瓶颈开孔率偏小。解法用敏感性验证第 07 篇代码 2-2加大开孔率后最紧项是否切换到weep。若切换说明判定正确。报错 3-3worst_norm为正但很接近 0是否算通过现象如 0.011 的行判定合格。根因当前实现只判符号。解法经验法则——增加贴线告警如worst_norm 0.05时标warning: marginal第 15 篇进一步用不确定度给出贴线通过的超限概率。报错 3-4改了阈值但没有记录。现象审计时无法复现判定。根因limits未随结果落盘。解法三段式 JSON并把阈值文件纳入版本控制第 16 篇的可复现检查会校验units/sources。报错 3-5把泛点率 ≤85%写死为常量并四处复制。现象换体系时改漏一处结论不一致。根因经验法则被当铁律硬编码。解法阈值集中在配置层代码只引用铁律单位/量纲才允许硬编码。四、动手练习练习 1跑通运行代码 2-1。判定输出 5 行判定其中 4 行最紧项 dP - 越限1 行最紧项 weep 最紧归一裕度0.011 - 合格容差 ±0.005并生成_margins.csv与含三段结构的_margins.json。练习 2找瓶颈给定某行最紧项为flood写出两条改设计的方向。判定方向正确加大塔径 / 加板间距 / 换高容量内件且说明它们分别改变了什么前者降表观气速、后者在泛点关联式里是容量参数。练习 3阈值翻转运行代码 2-2。判定输出显示第一行在 V1 下越限、V2 下合格并能说明为什么阈值必须随结果版本化落盘。练习 4长表/宽表转换把_margins.csv转成一行一案例的宽表并说明为什么底账仍应保留长表。判定宽表列数 案例字段数 裕度字段数解释要点为新增判据时长表零成本、宽表要改结构。五、小结与下一篇预告本篇把结果升级为可审计的裕度体系四类裕度泛点率/漏液比/背压/压降→归一化→最紧项binding给出改进方向阈值按三级标注管理经验法则可配置、铁律不可动落盘用三段式 JSONlimits/units/rows让每一行自证前提并识别出贴线合格0.011就是高风险这一关键信号。四条读表规律最紧项指示改进方向、归一化才可跨判据比较、阈值必须版本化、底账保长表。第 13 篇《塔内件选型自动化》把合格域变成排序问题——方案族枚举、约束过滤、多目标代价模型在 (方案 × 塔径 × 负荷) 的可行域里找代价最小的候选。示例从 4 种方案中搜出 55 个可行候选推荐sieve-8mm-4% D1.3 m, 负荷 0.85×。本篇认知问题回显FAQQ1结果应该落成长表还是宽表A底账落长表、交付做宽表。长表一行 一个案例 × 判据量新增判据零成本、易追加与过滤适合做审计底账宽表一行 一个案例、列 各判据量人读直观、配图方便但新增判据要改结构、旧文件不兼容。纪律是长表存底账、宽表做交付任何报表都由底账生成这样报表版式变化不影响事实来源。Q2四类裕度是什么为什么必须归一化后比大小A泛点率裕度85−flood_pct、操作/漏液比裕度weep_ratio−1.5、背压裕度1.0−dc_ratio、压降裕度150−h_t阈值均为示例经验值。必须归一化因为四者量纲与量级不同百分点、无量纲比、毫米液柱直接比大小是拿苹果比卡车归一化做法是各自除以阈值得到占阈值的比例再取最小值作为最紧归一裕度。Q3最紧项binding有什么工程意义A它把合格/不合格升级为往哪改。若最紧项是dP说明压降是瓶颈加大开孔率/减小孔径/改阀塔板/加板间距是flood说明容量是瓶颈加大塔径/加板间距/换高容量内件是weep说明操作下限是瓶颈减小开孔率或孔径/改阀塔板是dc说明降液管是瓶颈加大降液管面积/降压降/加板间距。示例 D1.0/load1.10 泛点率已达 84.7% 却不是最紧项说明看起来最危险的指标未必是瓶颈。Q4判据阈值为什么必须三级标注混用会出什么事A三级为铁律违反必出硬错如单位必须显式、Fp 必须先统一到 ft⁻¹、最佳实践推荐但有例外如先做物理量级校验、经验法则行业常用阈值如泛点率≤85%、操作/漏液比≥1.5、压降≤150 mm。混用的后果把经验阈值当铁律硬编码换体系如发泡体系需更保守时要改代码且容易改漏把铁律当可配置项则某次配置改错会让整体失真。正确做法是阈值集中配置、随结果落盘、并回写所用版本。Q5落盘元数据必须含哪些字段才可审计A三段式limits本次使用的全部阈值及其来源/版本、units每个量的单位、rows长表结果含各类裕度与 binding。三者同文件的价值在于任何一行结果都能自证判定前提。示例中把压降阈值从 150 改到 270 mm 会让同一行从越限翻成合格——没有limits就无法复现结论因此阈值改进时应同时重算全部历史结果回归测试。