Documentation version

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",
)

Select which sites receive an addressed control, optionally changing that binary selection over time. Time is always in us and duration is finite and positive. Directly supplied times must start at zero, increase strictly and remain below duration. active_site_ids supplies one tuple per frame. Names are unique within a frame; individual frames may be empty, but not all frames. Only step interpolation is supported.

Unlike continuous SitePattern weights, masks mark sites as selected or unselected. A boundary belongs to the new frame; a query exactly at duration returns the last frame. Construction does not verify register membership; the consuming program checks that.

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",)

See Local detuning.

constant ¶

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

Create a one-frame mask active throughout duration from nonempty site_ids. Supply a sequence of names, not a single string. Return a new SiteMask.

piecewise ¶

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

Create a mask from (start_time, active_sites) pairs. Input must already be in increasing time order; the method does not sort frames. Site names are sorted within each frame.

active_sites_at ¶

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

Return the active site-name tuple at time. Time must be finite and in [0, duration]; wrong types raise TypeError and nonfinite or out-of-range values raise ValueError.

frame_count ¶

frame_count: int

Return the number of declared frames.

is_dynamic ¶

is_dynamic: bool

Return True for more than one frame, even if adjacent frames select identical sites.

is_bound ¶

is_bound: bool

Always True: current masks do not support symbolic frame times or symbolic site selections.

referenced_parameter_names ¶

referenced_parameter_names: tuple[str, ...]

Return an empty tuple because current masks have no parameter dependencies.

validate_parameter_references ¶

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

Participate in the addressing interface by ignoring declarations and returning None. This does not validate target sites.

bind ¶

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

Ignore values and return this same object. Frame values are already numeric, so no copy is created.

from_dict ¶

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

Restore SiteMask from a dictionary. Restore time and per-frame site arrays and rerun all frame constraints. Missing required fields or invalid values can raise KeyError, TypeError or ValueError.

from_json ¶

from_json(text: str) -> SiteMask

Parse a JSON object and call from_dict(), returning SiteMask. Invalid JSON raises a parsing error; a non-object root raises TypeError.

to_dict ¶

to_dict() -> dict[str, Any]

Return a JSON-compatible dictionary, serializing nested objects and converting tuples to arrays. This stores the declaration, not an execution result.

to_json ¶

to_json(*, indent: int | None = None) -> str

Return a JSON string without writing a file. indent=None uses compact formatting; supply an indentation width for readable output.

stable_hash ¶

stable_hash() -> str

Return the SHA-256 hex digest of canonical JSON. Fields, identifiers and metadata can affect it. Use it to compare saved content, not to decide physical equivalence.