IsingModelIR¶
from cascaqit import IsingModelIR
IsingModelIR ¶
IsingModelIR(
problem_id: str,
spins: tuple[str, ...],
fields: tuple[tuple[str, float], ...] = (),
couplings: tuple[tuple[str, str, float], ...] = (),
offset: float = 0.0,
schema_version: str = SCHEMA_VERSION,
metadata: dict[str, Any] = dict(),
)
保存经典 Ising 目标：E(s) = offset + sum(h_i*s_i) + sum(J_ij*s_i*s_j)，其中 s 为 −1 或 +1。spins 定义自旋与结果位序，fields 为单体场，couplings 为不同自旋之间的二体项。系数可正可负，offset 保存常数能量。
本接口的位串约定为 0→−1、1→+1，即 s=2*x-1。这与计算基中 Pauli Z 的 0→+1、1→−1 相反，因此不能直接把经典单体场系数当作同号 Pauli Z 系数。使用 SDK 的模型到哈密顿量转换路径，并用小规模枚举核对能量。
通常从 from_terms() 或 QUBOProblemIR.to_ising_model() 得到对象。直接构造和序列化还原都不会自动校验结构；提供有限实系数并调用 validate()。metadata 可保留源问题信息，但不会自行生成原子坐标或驱动波形。
from cascaqit import IsingModelIR
from cascaqit.problems import evaluate_ising_bitstring
model = IsingModelIR.from_terms(problem_id="field", fields={"a": 2.0}, offset=0.5)
assert not model.validate()
assert evaluate_ising_bitstring(model, "0") == -1.5
assert evaluate_ising_bitstring(model, "1") == 2.5
assert model.to_ahs_candidate_metadata()["schedule_status"] == "not_generated"
assert IsingModelIR.from_json(model.to_json()) == model
from_terms ¶
from_terms(
*,
problem_id: str,
fields: dict[str, float] | None = None,
couplings: dict[tuple[str, str], float] | None = None,
offset: float = 0.0,
spins: list[str] | tuple[str, ...] | None = None,
metadata: dict[str, Any] | None = None,
) -> IsingModelIR
从场与耦合字典生成确定顺序的模型。所有项引用的自旋与显式 spins 取并集、转成字符串后排序；耦合两端排序，正反两项系数相加。它不会把自耦合自动移入 offset；应先用 s²=1 化简，再检查 validate()。
返回空或重复自旋、未知引用和自耦合等结构诊断。当前不全面验证系数/offset 的有限性，也不校验是否可映射到某个物理目标。
返回含自旋顺序、场、耦合、offset 与来源的字典，并明确记录未生成布局和脉冲、未请求优化器。若 metadata 已保存 source_problem_id/hash，则沿用它们，否则使用当前模型身份。这个字典不能直接当作可执行 AHSProgram。
返回 ProblemResultDecodingIR，保存 spins 顺序与 0→−1、1→+1 的约定。source_problem_hash 优先使用已有源元数据，便于追溯 QUBO 转换。返回值不计算能量。
返回 Ising 目标摘要 ProblemCandidateIR，含项数、系数、常数与来源。未运行优化器、未生成布局或脉冲；candidate 不能作为最优解或实际执行证据。
从字典还原 IsingModelIR。保持保存的自旋与项顺序，不重新合并反向耦合；恢复后显式调用 validate()。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。
解析 JSON 对象并调用 from_dict()，返回 IsingModelIR。非法 JSON 会抛出解析错误；顶层不是对象时抛出 TypeError。
返回可写入 JSON 的字典，嵌套对象一并序列化。元组转成数组；这个字典是保存的声明，不是执行结果。
返回 JSON 字符串，不写文件。indent=None 使用紧凑格式；提供缩进宽度可便于阅读。
返回规范 JSON 的 SHA-256 十六进制摘要。字段、标识或元数据变化都可能改变摘要；它用于比较保存内容，不判断两个声明在物理上是否等价。