文档版本 dev

ParameterManager

from cascaqit import ParameterManager

ParameterManager

ParameterManager(
    schema: ParameterSchemaIR = ParameterSchemaIR(),
    assignments: dict[str, ParameterScalar] = dict(),
    assignment_units: dict[str, str | None] = dict(),
    targets: tuple[ParameterTargetIR, ...] = (),
    metadata: dict[str, Any] = dict(),
    schema_version: str = CANONICAL_PARAMETER_SCHEMA_VERSION,
)

集中保存参数 schema、已有赋值和参数到程序位置的映射。常用入口是 ParameterManager() 或 HybridProgram.parameters。declare()、assign()、map_target() 返回新管理器，调用时要接住返回值；bind() 返回绑定结果。不要直接修改其公开字典来绕开绑定校验。

直接构造可提供 schema、assignments、assignment_units、targets、metadata 和 schema_version。schema 与 target 类型位于 cascaqit.parameters。映射 target 记录参数作用的位置，不会自行改写或执行一个程序。

from cascaqit import Parameter, ParameterManager

manager = ParameterManager().declare(Parameter("theta", unit="rad", lower_bound=0.0))
manager = manager.assign("theta", 0.5, unit="rad")
binding = manager.bind()
assert not binding.has_errors
assert binding.bind_set is not None
assert binding.bind_set.values["theta"] == 0.5
assert manager.bind({"theta": -0.1}).has_errors

使用方式见Hybrid 参数。

declare

declare(parameter: Parameter) -> ParameterManager

追加一个 Parameter 声明，返回新管理器。非 Parameter 输入抛出 TypeError，重复名称抛出 ValueError。

assign

assign(
    name: str,
    value: ParameterScalar,
    *,
    unit: str | None = None,
) -> ParameterManager

保存 name 的值及可选 unit，返回新管理器；再次赋值覆盖已存值。这里先检查基本形状，参数是否已声明、类型、范围及单位是否匹配由 bind() 检查。

map_target

map_target(target: ParameterTargetIR) -> ParameterManager

追加 ParameterTargetIR。目标 ID 必须唯一，错误类型抛出 TypeError，重复 ID 抛出 ValueError。

bind

bind(
    values: Mapping[str, ParameterScalar] | None = None,
    *,
    units: Mapping[str, str | None] | None = None,
    bind_id: str = "bind.default",
) -> ParameterBindingResult

合并已有赋值与本次 values，本次同名值优先；units 同样覆盖已存单位。解析默认值和派生表达式，返回 ParameterBindingResult。成功时 bind_set 为 ParameterBindIR；失败时 has_errors=True、bind_set=None，具体原因在 diagnostics。派生参数不能直接赋值，循环依赖也会失败。传入非 None 的单位必须精确匹配声明，省略单位不会进行换算。

bind_many

bind_many(
    value_sets: Sequence[Mapping[str, ParameterScalar]],
    *,
    units: Mapping[str, str | None] | None = None,
    bind_id_prefix: str = "bind",
) -> tuple[ParameterBindingResult, ...]

按输入顺序逐项调用 bind，返回绑定结果元组。ID 为 bind_id_prefix.0、.1 等；前缀不能为空。一个点失败不会让其他点的结果消失，应逐项检查 has_errors。

from_dict

from_dict(data: Mapping[str, Any]) -> ParameterManager

从字典还原 ParameterManager。还原 schema、赋值、单位和 target 映射；这不等于绑定已经通过。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json

from_json(text: str) -> ParameterManager

解析 JSON 对象并调用 from_dict()，返回 ParameterManager。非法 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 十六进制摘要。字段、标识或元数据变化都可能改变摘要；它用于比较保存内容，不判断两个声明在物理上是否等价。