文档版本

SiteMask¶

from cascaqit import SiteMask

SiteMask ¶

SiteMask(
    duration: float,
    times: tuple[float, ...],
    active_site_ids: tuple[tuple[str, ...], ...],
    time_unit: str = "us",
    interpolation: Literal["step"] = "step",
)

用二值选择指定哪些站点接受局域控制，并允许选择随时间切换。时间单位固定为 us，duration 为有限正数。直接构造的 times 必须从 0 开始、严格递增且每个时间小于 duration；active_site_ids 每帧一个元组。各帧名称必须唯一，帧内可为空，但所有帧不能都为空。当前只支持 step 插值。

与 SitePattern 的连续权重不同，掩码只表示选中或未选中。帧边界属于新帧，恰在 duration 查询时仍返回最后一帧。构造不会验证站点在阵列中是否存在，这一步由使用它的程序完成。

from cascaqit import SiteMask

mask = SiteMask.piecewise(duration=1.0, frames=[(0.0, ("q0",)), (0.5, ("q1",))])
assert mask.active_sites_at(0.499) == ("q0",)
assert mask.active_sites_at(0.5) == ("q1",)
assert mask.active_sites_at(1.0) == ("q1",)

见局域失谐。

constant ¶

constant(
    site_ids: Iterable[str], *, duration: float
) -> SiteMask

用非空 site_ids 创建持续整个 duration 的单帧掩码。传名称序列，不要传单个字符串。返回新 SiteMask。

piecewise ¶

piecewise(
    *,
    duration: float,
    frames: Iterable[tuple[float, Iterable[str]]],
) -> SiteMask

从 (start_time, active_sites) 对创建分帧掩码。输入顺序必须已经按时间递增；方法不会替你重排时间。各帧站点名称会排序保存。

active_sites_at ¶

active_sites_at(time: float) -> tuple[str, ...]

返回 time 对应帧的站点名称元组。time 必须为 [0, duration] 内的有限数；错误类型抛出 TypeError，越界或非有限值抛出 ValueError。

frame_count ¶

frame_count: int

返回声明的帧数。

is_dynamic ¶

is_dynamic: bool

帧数超过一帧时返回 True，即使相邻帧碰巧选择相同站点。

is_bound ¶

is_bound: bool

当前掩码不支持符号帧时间或符号站点选择，此属性始终为 True。

referenced_parameter_names ¶

referenced_parameter_names: tuple[str, ...]

返回空元组，当前没有参数依赖。

validate_parameter_references ¶

validate_parameter_references(
    declarations: Mapping[str, Parameter],
) -> None

为寻址接口一致性保留的方法，忽略 declarations 并返回 None；不做目标站点校验。

bind ¶

bind(values: Mapping[str, float]) -> SiteMask

忽略 values 并返回当前对象本身。帧值已经是数值，所以这里不创建副本。

from_dict ¶

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

从字典还原 SiteMask。还原时间数组和逐帧站点数组，并重新检查完整的帧约束。缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json ¶

from_json(text: str) -> SiteMask

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