QUBOProblemIR¶
from cascaqit import QUBOProblemIR
QUBOProblemIR ¶
QUBOProblemIR(
problem_id: str,
variables: tuple[str, ...],
linear_terms: tuple[tuple[str, float], ...] = (),
quadratic_terms: tuple[
tuple[str, str, float], ...
] = (),
offset: float = 0.0,
variable_positions: tuple[
tuple[str, tuple[float, float]], ...
] = (),
schema_version: str = SCHEMA_VERSION,
metadata: dict[str, Any] = dict(),
)
保存二次无约束二进制优化目标：E(x) = offset + sum(a_i*x_i) + sum(b_ij*x_i*x_j)，每个 x 为 0 或 1，每个二次项按保存的系数计一次。它是系数项列表，不是默认采用某种上三角约定的 Q 矩阵。若输入同时包含 (a,b) 与 (b,a)，from_terms() 会将两者系数相加。
variables 给出变量与结果位序；variable_positions 可选，但提供时应完整覆盖变量。offset 必须保留才能比较转换前后的能量。直接构造或从字典还原不会自动执行 validate()；调用者应提供有限的实系数，结构诊断不能代替完整数值检查。problem_id、metadata、schema_version 分别记录标识、附加信息和格式。
下面穷举两变量，核对转换前后每个赋值的能量，包含常数项。
from itertools import product
from math import isclose
from cascaqit import QUBOProblemIR
from cascaqit.problems import evaluate_ising_bitstring, evaluate_qubo_bitstring
qubo = QUBOProblemIR.from_terms(problem_id="pair", linear_terms={"a": -1, "b": -2},
quadratic_terms={("a", "b"): 3}, offset=0.25)
assert not qubo.validate()
ising = qubo.to_ising_model()
for bits in product("01", repeat=2):
bitstring = "".join(bits)
assert isclose(evaluate_qubo_bitstring(qubo, bitstring),
evaluate_ising_bitstring(ising, bitstring), abs_tol=1e-12)
assert QUBOProblemIR.from_json(qubo.to_json()) == qubo
推导见 QUBO 与哈密顿量。
from_terms ¶
from_terms(
*,
problem_id: str,
linear_terms: dict[str, float] | None = None,
quadratic_terms: dict[tuple[str, str], float]
| None = None,
offset: float = 0.0,
variables: list[str] | tuple[str, ...] | None = None,
positions: dict[str, tuple[float, float]] | None = None,
metadata: dict[str, Any] | None = None,
) -> QUBOProblemIR
从线性/二次系数字典生成模型。变量集合为所有项涉及的变量与显式 variables 的并集，转成字符串后排序；显式 variables 可补充无系数变量。二次项两端排序并累加反向重复系数，坐标按变量名排序并检查两个有限实数。它不会把 (x,x) 自动折入线性项；应先用 x²=x 整理，再调用 validate()。
返回结构诊断：空或重复变量、未知变量引用、自二次项，以及坐标重复、覆盖不全或非有限二维坐标。当前不全面检查系数与 offset 的有限性，也不执行求解；空诊断不保证下游算法或物理编码接受模型。
返回已保存的变量坐标字典，不生成缺失布局，不修改模型。
按 x=(1+s)/2 返回 IsingModelIR，保留全部赋值的能量。线性项 ax 对 offset 和对应场各贡献 a/2；二次项 bx_i*x_j 对 offset、两个场和耦合各贡献 b/4。生成的 ID 为 ising.from.
返回变量顺序、源摘要和“位值等于二进制变量 x”的解码元数据。它没有求值或寻找最优位串。
返回 ProblemCandidateIR，保存变量顺序、项数、系数、offset 和未生成求解/调度的说明。这里的 candidate 是目标摘要，不是优化得到的候选解。
从字典还原 QUBOProblemIR。还原系数、坐标与变量顺序，不进行 from_terms() 的项合并；恢复后需要显式 validate()。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。
解析 JSON 对象并调用 from_dict()，返回 QUBOProblemIR。非法 JSON 会抛出解析错误；顶层不是对象时抛出 TypeError。
返回可写入 JSON 的字典，嵌套对象一并序列化。元组转成数组；这个字典是保存的声明，不是执行结果。
返回 JSON 字符串，不写文件。indent=None 使用紧凑格式；提供缩进宽度可便于阅读。
返回规范 JSON 的 SHA-256 十六进制摘要。字段、标识或元数据变化都可能改变摘要；它用于比较保存内容，不判断两个声明在物理上是否等价。