jinko-calibration-cmaes

Jinkō CMA-ES 校准 SDK 工作流

UI 文案	API 项目项类型	SDK 入口点
校准	Calibration	client.create_calibration(...)、model.create_calibration(...)、Calibration 领域对象

校准管理器 API 仅支持 CMA-ES——不存在类型或方法判别器。“Subsampling” 是与校准类型无关的 VPop 生成器功能。 此技能仅介绍 SDK 的使用机制：不提供默认值、诊断信息或何时进行校准的指导。

前置条件： 此技能需要已初始化的 jinko-sdk 连接，且 SDK 满足其 metadata.requires_sdk 范围。运行 jinko-sdk-setup 技能 （../jinko-sdk-setup/SKILL.md），只有在检查通过后才能继续。会话代码只能交换一次，因此在此技能自身的 SDK 进程开始前，请再次调用 get_session_code。如果找不到该技能，请从 novainsilico/jinko-skills 安装。

最小校准配置

• parameters：要校准的先验（必填，≥1）。
• 至少需要一个适应度函数来源（必填）：dataTableDesigns（数据表必须报告 metadata.public.validForFitnessFunction: True，参见 jinko-data-table），和/或包含目标的高级输出集（参见 jinko-output-set）。此技能不会创建这些输入。
• CalibrationOptions：seed + thresholdWeightedScore 为架构必填项，契约默认值分别为 0 和 1；populationSize + numberOfIterations 没有契约默认值，且在功能上必填。随附的创建脚本要求提供种群大小和迭代次数；省略 seed 和 threshold 时使用契约默认值。若可复现性策略要求，请明确传入全部四项。

创建前必须遵守两条编码规则：

• 当 log_transform=True 时，mean 和 std 使用 log10(x) 坐标，但 min_bound 和 max_bound 仍使用 x 的原始物理坐标。若计划中的边界以 log10 坐标表示，请先将其转换为幂：physical_bound = 10**log10_bound。出现 MAX_BOUND_LOWER_THAN_MEAN_LOG 等校准合理性警告，表明此映射不一致。
• 对于每个附加的适应度数据表，除非用户明确要求对指定观测量使用线性边界缩放，否则请将该表中的每个不同 obsId 都设为 options.log_transform_wide_bounds。这是 SDK 中对应 UI 缩放边界选项的字段。

创建

model = client.get_model("cm-...")
data_table = client.get_data_table("dt-...")
calibration = model.create_calibration(
    parameters=[
        {
            "id": "k_elim",
            "mean": -1.0,
            "std": 0.5,
            "log_transform": True,
            "min_bound": 0.001,
            "max_bound": 10.0,
        }
    ],
    data_tables=[
        {
            "data_table": data_table,
            "include": True,
            "options": {
                "weight": 1.0,
                "log_transform_wide_bounds": sorted({
                    row["obsId"] for row in data_table.export()
                }),
            },
        }
    ],
    calib_seed=42,
    calib_threshold_weighted_score=1.0,
    calib_number_of_iterations=100,
    calib_population_size=12,
)

等效的客户端级调用：client.create_calibration(model=model, ...)。 calibrationOptionsOverride、solvingOptionsOverride、coreVersion 没有带类型的关键字参数——请使用 client.create_calibration_from_json(json_content=payload) / client.calibrations.create_raw(payload)。 完整字段表请参阅 references/creating-a-calibration.md。

创建后可通过 calibration.set_solving_times(t_max=timedelta(days=28), t_step="P1D") 设置求解时长；每个时长都可以是 timedelta 或 ISO 8601 字符串。

运行与轮询

calibration.run()
final_status = calibration.wait_until_completed(timeout=3600)

.get_sanity()、.status() 和 StoppingReason 的取值请参阅 references/running-and-polling.md。

结果

calibration.performance()  # raw dict
calibration.results_summary()  # raw dict
calibration.objective_weights()  # raw dict, {objective_id: weight}
calibration.results.sorted_patients(
    sort_by="optimizationWeightedScore desc"
)  # raw, low-level

目前所有结果访问器都返回未经解析的字典。请参阅 references/results-and-inspection.md。

项目文件夹管理

与 jinko-trial / jinko-data-table 相同：建议使用 YYYY-MM-DD-<experiment> 文件夹；通过 client.get_folder_by_name(name, exact_match_only=True) 重用名称完全匹配的文件夹；仅在确认后，或使用 --create-folder --apply 时创建文件夹。

SDK 脚本

安装 SDK 后，这些脚本会作为控制台脚本出现在 PATH 中，也可按下方所示通过 python -m 运行。

• jinko.cli.create_cmaes_calibration：默认执行试运行；使用 --apply 创建校准。
• jinko.cli.run_calibration：使用 --apply 运行已有校准并轮询。
• jinko.cli.inspect_calibration：打印或写出原始的 performance/results_summary/objective_weights/sorted_patients JSON。

python -m jinko.cli.create_cmaes_calibration --model-sid cm-... --data-table-sid dt-... --parameter "k_elim:-1.0:0.5:0.001:10.0:log" --seed 42 --threshold-weighted-score 1.0 --iterations 100 --population-size 12
python -m jinko.cli.create_cmaes_calibration --model-sid cm-... --data-table-sid dt-... --parameter "k_elim:-1.0:0.5:0.001:10.0:log" --seed 42 --threshold-weighted-score 1.0 --iterations 100 --population-size 12 --folder 2026-07-07-calib --create-folder --apply
python -m jinko.cli.run_calibration --calibration-sid ca-... --apply --timeout 3600
python -m jinko.cli.inspect_calibration --calibration-sid ca-... --performance --results-summary --objective-weights --output-dir calib-results

参考资料导航

• references/creating-a-calibration.md：完整字段表、三种创建模式。
• references/running-and-polling.md：运行／停止／状态／健全性检查、JobStatus、StoppingReason。
• references/results-and-inspection.md：performance/results_summary/objective_weights/results.* 字段表及注意事项。