文档版本 dev

Parameter

from cascaqit import Parameter

Parameter

Parameter(
    name: str,
    dtype: ParameterDType = "float",
    unit: str | None = None,
    default: ParameterScalar | None = None,
    lower_bound: int | float | None = None,
    upper_bound: int | float | None = None,
    expression: Expression | None = None,
    compile_impact: CompileImpact = "bind_only",
    source_span: SourceSpan | None = None,
    metadata: Mapping[str, Any] = dict(),
    schema_version: str = CANONICAL_PARAMETER_SCHEMA_VERSION,
)

声明一个带类型、单位和可选边界的参数。name 必须是非关键字的 Python 标识符。dtype 支持 float、int、bool：float 接受整数或浮点数，int 不接受浮点数，布尔值只用于 bool 参数。数值必须有限，边界包含端点；bool 参数不能设置数值边界。

default 用于缺省绑定。expression 声明由其他参数算出的值，与 default 互斥，且其类型、单位必须匹配。unit 是单位标签，不会触发隐式换算。compile_impact 为 bind_only 或 recompile，供绑定与编译层区分处理；source_span、metadata 和 schema_version 保存来源及格式信息。

参数支持 +、-、*、/、** 和正负号，返回 Expression；表达式仍受类型与单位规则约束。构造或求值时的错误类型抛出 TypeError，无效名称、单位、范围或非有限值通常抛出 ValueError。在线路或模拟程序中，应优先用 Circuit.parameter() 或 AHSProgram.parameter() 声明，确保参数归属正确。

from cascaqit import Parameter

angle = Parameter("theta", unit="rad", default=0.25, lower_bound=0.0)
assert angle.evaluate({}) == 0.25
assert angle.contains(0.0)
assert Parameter.from_json(angle.to_json()) == angle

完整绑定流程见数字参数绑定与共享参数。

required

required: bool

没有 default 且没有 expression 时返回 True，表示绑定需提供此参数。

dependencies

dependencies: tuple[str, ...]

返回派生表达式依赖的参数名称元组；普通参数返回空元组。它不表示当前参数自身的名称。

contains

contains(value: ParameterScalar) -> bool

先校验类型和有限性，再判断是否在含端点的边界内。合法类型但越界时返回 False；错误类型或非有限值会抛异常，不会一律返回 False。

evaluate

evaluate(
    values: Mapping[str, ParameterScalar],
) -> ParameterScalar

返回解析出的标量。派生参数始终按 expression 求值；普通参数先取 values[name]，再取 default。缺值、表达式计算失败或结果越界会报错。此方法不会自动解析完整的参数依赖图；多个互相依赖的声明应交给 ParameterManager.bind()。

to_ir

to_ir() -> ParameterIR

返回 ParameterIR，保留类型、单位、边界、默认值、表达式和编译影响等声明。

from_ir

from_ir(parameter: ParameterIR) -> Parameter

从 cascaqit.parameters.ParameterIR 返回新的 Parameter；其他输入类型抛出 TypeError。

from_dict

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

从字典还原 Parameter。嵌套 expression 与 source_span 会还原为对应类型，并重新执行构造校验。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json

from_json(text: str) -> Parameter

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