文档版本 dev

GraphProblemIR

from cascaqit import GraphProblemIR

GraphProblemIR

GraphProblemIR(
    problem_id: str,
    nodes: tuple[str, ...],
    edges: tuple[tuple[str, str], ...],
    node_positions: tuple[
        tuple[str, tuple[float, float]], ...
    ] = (),
    graph_type: Literal["undirected"] = "undirected",
    schema_version: str = SCHEMA_VERSION,
    metadata: dict[str, Any] = dict(),
)

保存无向图的节点、边和可选二维坐标，供 MIS 建模、布局参考及结果解码使用。通常调用 from_edges()；直接构造会保留输入顺序，不自动完成结构校验，应显式查看 validate()。

nodes 定义节点与结果位序。没有边的孤立节点也会影响问题，需在 from_edges(nodes=...) 中明确列出。node_positions 只是坐标提示，不保证其距离产生的相互作用图与 edges 相同，也不表示已经找到可执行原子布局。problem_id、metadata 和 schema_version 保存标识、附加信息与格式。

from cascaqit import GraphProblemIR

problem = GraphProblemIR.from_edges(problem_id="edge_and_isolated",
    nodes=("c", "b", "a"), edges=(("b", "a"), ("a", "b")))
assert problem.nodes == ("a", "b", "c")
assert problem.edges == (("a", "b"),)
assert not problem.validate()
assert problem.result_decoding_metadata().variable_order == problem.nodes
assert problem.to_mis_instance().node_order() == problem.nodes
assert GraphProblemIR.from_json(problem.to_json()) == problem

实验见图问题建模。

from_edges

from_edges(
    *,
    problem_id: str,
    edges: list[tuple[str, str]]
    | tuple[tuple[str, str], ...],
    nodes: list[str] | tuple[str, ...] | None = None,
    positions: dict[str, tuple[float, float]] | None = None,
    metadata: dict[str, Any] | None = None,
) -> GraphProblemIR

将节点 ID 转为字符串、去重并排序；无向边两端排序，重复或反向重复边只保留一条。省略 nodes 时仅从边推断节点；显式提供 nodes 时以它为节点集合，不自动补入遗漏的边端点，后续 validate() 会报告未知节点。positions 转为按键排序的坐标元组。构建后仍需校验自环、空图与节点引用。

position_by_node

position_by_node() -> dict[str, tuple[float, float]]

返回坐标字典副本。它只转换已保存的 node_positions，不补全缺失节点，也不验证坐标或图嵌入。

validate

validate() -> tuple[DiagnosticsIR, ...]

返回诊断元组，检查空图、重复节点、自环和引用未知节点的边，不修改原图。当前检查不验证坐标覆盖、坐标有限性或物理目标约束；无错误诊断不代表布局可用于模拟实验。

to_mis_instance

to_mis_instance(
    *, fallback_spacing: float = 5.0
) -> MISInstance

返回 cascaqit.problems.MISInstance。坐标键集合恰好覆盖 nodes 时保留坐标；否则用 fallback_spacing 生成全部节点的直线坐标，原有部分坐标不会保留。边仍来自图声明，不根据距离重建。MISInstance 按节点名称排序，直接构造的 GraphProblemIR 若用了其他顺序，应重新读取 node_order()。此转换不求解 MIS，也不检查目标可行性。

result_decoding_metadata

result_decoding_metadata() -> ProblemResultDecodingIR

返回 ProblemResultDecodingIR，记录节点顺序、源问题摘要及“1 表示选中节点”的约定。它不包含完整边约束；只有这些元数据不能判断某个选中集合是否独立。

layout_candidate

layout_candidate(
    *,
    layout: Literal["line", "grid"] = "line",
    spacing: float = 5.0,
    columns: int | None = None,
) -> ProblemCandidateIR

返回直线或网格 ProblemCandidateIR，保存新生成的坐标、边与限制诊断，不修改图的 node_positions。spacing 须为正；grid 的 columns 指定列数，省略时取能容纳节点的近方形列数。它不优化布局、不生成脉冲，也不验证布局是否复现图的所有边和非边。

from_dict

from_dict(data: dict[str, Any]) -> GraphProblemIR

从字典还原 GraphProblemIR。还原 nodes、edges 与坐标的保存顺序，不应用 from_edges() 的去重排序；结构检查需另行调用 validate()。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json

from_json(text: str) -> GraphProblemIR

解析 JSON 对象并调用 from_dict()，返回 GraphProblemIR。非法 JSON 会抛出解析错误；顶层不是对象时抛出 TypeError。

to_dict

to_dict() -> dict[str, Any]

返回可写入 JSON 的字典，嵌套对象一并序列化。元组转成数组；这个字典是保存的声明，不是执行结果。

to_json

to_json(*, indent: int | None = None) -> str

返回 JSON 字符串，不写文件。indent=None 使用紧凑格式；提供缩进宽度可便于阅读。

stable_hash

stable_hash() -> str

返回规范 JSON 的 SHA-256 十六进制摘要。字段、标识或元数据变化都可能改变摘要；它用于比较保存内容，不判断两个声明在物理上是否等价。