文档版本

Waveform¶

from cascaqit import Waveform

Waveform ¶

Waveform(
    waveform_ir: WaveformIR,
    _value_templates: tuple[AnalogWaveformValue, ...]
    | None = None,
)

声明模拟控制的时间变化。通常从 constant()、linear() 或分段构造方法开始；直接构造 Waveform(waveform_ir) 适用于已有 IR 的情况。构造方法返回新波形，bind() 和 concat() 也不会修改原波形。

时间以 us 表示，幅值的单位由 value_unit 指定，默认 rad/us；相位波形应使用 rad。数值必须有限，布尔值不能充当幅值。Parameter 或表达式的单位必须与波形一致。波形构造不等于目标校验通过：持续时间、采样时间和目标幅值限制仍需在程序校验时检查。

见波形设计与插值波形。

构造波形¶

constant ¶

constant(
    value: AnalogWaveformValue,
    *,
    duration: float,
    waveform_id: str = "waveform",
    value_unit: str = "rad/us",
) -> Waveform

在整个 duration 内保持 value。幅值可为数值、参数或表达式。返回 Waveform；不符合数值类型、有限性或单位要求时抛出 TypeError 或 ValueError。

linear ¶

linear(
    start: AnalogWaveformValue,
    stop: AnalogWaveformValue,
    *,
    duration: float,
    waveform_id: str = "waveform",
    value_unit: str = "rad/us",
) -> Waveform

在 duration 内从 start 线性变化到 stop。两端可带参数，绑定后才得到数值波形。

piecewise_linear ¶

piecewise_linear(
    *,
    times: Sequence[float],
    values: Sequence[AnalogWaveformValue],
    waveform_id: str = "waveform",
    value_unit: str = "rad/us",
) -> Waveform

用等长的 times 与 values 声明折线，相邻点之间线性插值。最终时间决定总时长。时间应从零开始并严格递增；空时间序列或长度不一致立即抛出 ValueError，其余时间约束应通过程序校验确认。

piecewise_constant ¶

piecewise_constant(
    *,
    times: Sequence[float],
    values: Sequence[AnalogWaveformValue],
    waveform_id: str = "waveform",
    value_unit: str = "rad/us",
) -> Waveform

用 times 与 values 声明阶梯波形，两者等长。每个区间采用左端点的值；当前求值实现把分界时刻归入左侧区间，因此在最后时刻仍取前一个值，超过最后时刻才返回最后一个值。它与“区间数个值、边界数个时间”的输入约定不同。最终时间决定总时长，空时间或长度不一致抛出 ValueError。

interpolated ¶

interpolated(
    *,
    times: Sequence[float],
    values: Sequence[AnalogWaveformValue],
    waveform_id: str = "waveform",
    value_unit: str = "rad/us",
) -> Waveform

用形状保持的 PCHIP 插值连接采样点。至少需要两个有限时间点，从 0.0 开始并严格递增；非法时间立即抛出 ValueError。times 与 values 等长，幅值可以带参数。PCHIP 控制过冲，但不能代替目标的带宽或变化率校验。

parameter ¶

parameter(
    name: str,
    *,
    duration: float,
    waveform_id: str = "waveform",
    value_unit: str = "rad/us",
    scale: float = 1.0,
    offset: float = 0.0,
) -> Waveform

创建常数波形，其值为 scale * 参数值 + offset。参数按 name 引用，持续时间由 duration 指定。推荐新程序先通过 AHSProgram.parameter() 声明参数，再传给 constant()；按名称引用的表达式也需要匹配程序声明和单位。

绑定与组合¶

bind ¶

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

用名称到数值的映射求值，返回独立波形。具体参数的默认值和边界由其声明处理。程序通常应调用 AHSProgram.bind()，让全部波形和空间权重使用同一组值。

concat ¶

concat(
    *others: Waveform,
    waveform_id: str | None = None,
    max_points: int = 1024,
) -> Waveform

把当前波形与至少一个后续波形串接，返回新波形，总时长为各段之和。各段必须具有相同单位和兼容类型：常数/阶梯为一类，线性/折线为另一类。线性段在连接处必须连续；符号端点按表达式是否相同判断。

不支持 PCHIP 段串接，因为重新拟合会改变原曲线。按名称引用的旧式常数表达式需先绑定。max_points 为 2–1024 的整数，限制输出采样点数；无后续段、类型不兼容、连接点不连续或超限会产生错误。

to_ir ¶

to_ir() -> WaveformIR

返回数值 WaveformIR 的独立副本。未绑定时抛出 ProgramValidationError，不会用占位值导出。

参数检查¶

is_bound ¶

is_bound: bool

所有幅值均已数值化时返回 True。

is_parameter_reference ¶

is_parameter_reference: bool

判断波形是否保存按名称引用的规范表达式。它与“是否还含任何符号值”不同；检查能否导出应使用 is_bound。

referenced_parameter_names ¶

referenced_parameter_names: tuple[str, ...]

返回引用的参数名称元组，名称去重。普通参数模板按名称排序；规范表达式使用其依赖顺序。

validate_parameter_references ¶

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

用 declarations 检查参数归属、名称和单位，成功返回 None。直接传入的 Parameter 必须就是当前程序拥有的声明对象；表达式依赖必须能在声明映射中找到。不匹配时抛出 ProgramValidationError。此方法不检查物理波形是否符合目标限制。