Skip to content

catalog

List the builder page's initial states, measurements, and result actions.

The page renders a lane from :func:listed_states, :func:listed_measurements, or :func:listed_actions. :func:listed_measurements is the generic list an added Hamiltonian posts: z, x, y, and counts. A preexisting model posts model and records the measurements that factory defines. A posted catalog id is prepared by the matching function in this module. An id that is not listed is an error from that function.

ListedBitsField

Bases: TypedDict

A bit-string chip for one initial state.

cap is how many characters the page will type, and how long a posted string may be. display is ket to show the bits, or gray to show the Gray-decoded ket. encode is the class the script preview imports. empty is the alert when the string is blank. mismatch and size use {n} for the qubit count the model fixed. blank is the detail before any bits are typed, and may use {cap}.

Source code in shadowsim/cli/catalog.py
class ListedBitsField(TypedDict):
    """A bit-string chip for one initial state.

    ``cap`` is how many characters the page will type, and how long a posted
    string may be. ``display`` is ``ket`` to show the bits, or ``gray`` to show
    the Gray-decoded ket. ``encode`` is the class the script preview imports.
    ``empty`` is the alert when the string is blank. ``mismatch`` and ``size``
    use ``{n}`` for the qubit count the model fixed. ``blank`` is the detail
    before any bits are typed, and may use ``{cap}``.
    """

    kind: Literal["bits"]
    label: str
    aria: str
    cap: int
    encode: str
    display: Literal["ket", "gray"]
    empty: str
    mismatch: str
    size: str
    blank: str

ListedNumbersField

Bases: TypedDict

A number-list chip for one initial state.

match is length when the list must have one entry per qubit, or padded when the encoding zero-pads to a power of two. nonzero asks the page to reject an all-zero list. unit is the singular noun in a filled detail, such as angle. cap is the page typing limit and is not enforced on a posted list. The other text fields match :class:ListedBitsField.

Source code in shadowsim/cli/catalog.py
class ListedNumbersField(TypedDict):
    """A number-list chip for one initial state.

    ``match`` is ``length`` when the list must have one entry per qubit, or
    ``padded`` when the encoding zero-pads to a power of two. ``nonzero`` asks
    the page to reject an all-zero list. ``unit`` is the singular noun in a
    filled detail, such as ``angle``. ``cap`` is the page typing limit and is
    not enforced on a posted list. The other text fields match
    :class:`ListedBitsField`.
    """

    kind: Literal["numbers"]
    label: str
    aria: str
    cap: int
    encode: str
    match: Literal["length", "padded"]
    nonzero: bool
    unit: str
    empty: str
    mismatch: str
    size: str
    blank: str

ListedState

Bases: TypedDict

Display record for one initial state.

Source code in shadowsim/cli/catalog.py
class ListedState(TypedDict):
    """Display record for one initial state."""

    id: str
    title: str
    detail: str
    phrase: str
    field: ListedBitsField | ListedNumbersField

ListedExpressionField

Bases: TypedDict

The expression chip on a counts measurement.

Source code in shadowsim/cli/catalog.py
class ListedExpressionField(TypedDict):
    """The expression chip on a counts measurement."""

    kind: Literal["expression"]
    label: str
    aria: str

ListedMeasurement

Bases: TypedDict

Display record for one measurement.

kind is pauli or counts. A Pauli record has letter and rotate. rotate is true when a circuit simulator reads those qubits in this record's letter, X or Y, and every other qubit in Z. A counts record has field instead.

Source code in shadowsim/cli/catalog.py
class ListedMeasurement(TypedDict):
    """Display record for one measurement.

    ``kind`` is ``pauli`` or ``counts``. A Pauli record has ``letter`` and
    ``rotate``. ``rotate`` is true when a circuit simulator reads those qubits
    in this record's letter, ``X`` or ``Y``, and every other qubit in Z. A
    counts record has ``field`` instead.
    """

    id: str
    title: str
    detail: str
    phrase: str
    kind: Literal["pauli", "counts"]
    letter: NotRequired[str]
    rotate: NotRequired[bool]
    field: NotRequired[ListedExpressionField]

ListedPathField

Bases: TypedDict

A path chip on a result action.

key is the posted actions object key. default fills the chip and is the path used when that key is missing.

Source code in shadowsim/cli/catalog.py
class ListedPathField(TypedDict):
    """A path chip on a result action.

    ``key`` is the posted actions object key. ``default`` fills the chip and is
    the path used when that key is missing.
    """

    kind: Literal["path"]
    key: str
    default: str
    label: str
    aria: str

ListedAction

Bases: TypedDict

Display record for one result action.

plot has no field. The page draws it, and preparing a run accepts the id without writing a file.

Source code in shadowsim/cli/catalog.py
class ListedAction(TypedDict):
    """Display record for one result action.

    ``plot`` has no ``field``. The page draws it, and preparing a run accepts
    the id without writing a file.
    """

    id: str
    title: str
    detail: str
    phrase: str
    field: NotRequired[ListedPathField]

listed_states

listed_states() -> list[ListedState]

Return the initial states in catalog order.

field.cap is the page typing limit. Basis and Gray preparation also reject a longer bit string. Angle and amplitude preparation do not reject a list longer than cap.

Returns:

  • list[ListedState] –

    States the builder page can offer.

Source code in shadowsim/cli/catalog.py
def listed_states() -> list[ListedState]:
    """Return the initial states in catalog order.

    ``field.cap`` is the page typing limit. Basis and Gray preparation also
    reject a longer bit string. Angle and amplitude preparation do not reject a
    list longer than ``cap``.

    Returns:
        States the builder page can offer.
    """
    return [entry.listed() for entry in _STATES]

listed_measurements

listed_measurements() -> list[ListedMeasurement]

Return the generic measurements in catalog order.

The ids are z, x, y, and counts. GET /measurements returns this list, and an added Hamiltonian posts one of these ids. A preexisting model posts model and records the measurements that factory defines.

Returns:

  • list[ListedMeasurement] –

    Measurements the builder page offers for an added Hamiltonian.

Source code in shadowsim/cli/catalog.py
def listed_measurements() -> list[ListedMeasurement]:
    """Return the generic measurements in catalog order.

    The ids are ``z``, ``x``, ``y``, and ``counts``. ``GET /measurements``
    returns this list, and an added Hamiltonian posts one of these ids. A
    preexisting model posts ``model`` and records the measurements that
    factory defines.

    Returns:
        Measurements the builder page offers for an added Hamiltonian.
    """
    return [entry.listed() for entry in _MEASUREMENTS]

listed_actions

listed_actions() -> list[ListedAction]

Return the result actions in catalog order.

Returns:

  • list[ListedAction] –

    Actions the builder page can offer.

Source code in shadowsim/cli/catalog.py
def listed_actions() -> list[ListedAction]:
    """Return the result actions in catalog order.

    Returns:
        Actions the builder page can offer.
    """
    return [entry.listed() for entry in _ACTIONS]

measurement_record

measurement_record(measure_id: str) -> ListedMeasurement

Return the measurement named measure_id.

Parameters:

  • measure_id (str) –

    An id from :func:listed_measurements.

Returns:

Raises:

  • ValueError –

    measure_id is not listed.

Source code in shadowsim/cli/catalog.py
def measurement_record(measure_id: str) -> ListedMeasurement:
    """Return the measurement named ``measure_id``.

    Args:
        measure_id: An id from :func:`listed_measurements`.

    Returns:
        The display record, including ``kind`` and any chip field.

    Raises:
        ValueError: ``measure_id`` is not listed.
    """
    return _measurement(measure_id).listed()

action_record

action_record(action_id: str) -> ListedAction

Return the result action named action_id.

Parameters:

  • action_id (str) –

    An id from :func:listed_actions.

Returns:

  • ListedAction –

    The display record. A path action includes its default.

Raises:

  • ValueError –

    action_id is not listed.

Source code in shadowsim/cli/catalog.py
def action_record(action_id: str) -> ListedAction:
    """Return the result action named ``action_id``.

    Args:
        action_id: An id from :func:`listed_actions`.

    Returns:
        The display record. A path action includes its default.

    Raises:
        ValueError: ``action_id`` is not listed.
    """
    entry = _ACTION_BY_ID.get(action_id)
    if entry is None:
        raise ValueError("unknown action")
    return entry.listed()

prepare_state

prepare_state(
    state_id: str, num_qubits: int, data: object = None
) -> State

Prepare state_id on num_qubits qubits from the posted data.

A bit-string state must be that many characters of 0 and 1, and no longer than its cap. angle is one finite real per qubit. amplitude is a non-empty list of finite reals, and the padded state must use num_qubits.

Parameters:

  • state_id (str) –

    An id from :func:listed_states.

  • num_qubits (int) –

    Qubits the model has.

  • data (object, default: None ) –

    The posted state.value.

Returns:

  • State –

    The encoded initial state.

Raises:

  • ValueError –

    state_id is not listed, or data does not fit it.

Source code in shadowsim/cli/catalog.py
def prepare_state(state_id: str, num_qubits: int, data: object = None) -> State:
    """Prepare ``state_id`` on ``num_qubits`` qubits from the posted ``data``.

    A bit-string state must be that many characters of 0 and 1, and no longer
    than its ``cap``. ``angle`` is one finite real per qubit. ``amplitude`` is a
    non-empty list of finite reals, and the padded state must use ``num_qubits``.

    Args:
        state_id: An id from :func:`listed_states`.
        num_qubits: Qubits the model has.
        data: The posted ``state.value``.

    Returns:
        The encoded initial state.

    Raises:
        ValueError: ``state_id`` is not listed, or ``data`` does not fit it.
    """
    entry = _STATE_BY_ID.get(state_id)
    if entry is None:
        raise ValueError("unknown initial state")
    if entry.kind == "bits":
        return _prepare_bits(entry, num_qubits, data)
    return _prepare_numbers(entry, num_qubits, data)

measurements_for

measurements_for(
    measure: Mapping[str, object], num_qubits: int
) -> list[Measurement]

Return one expectation per selected qubit, or one counts expression.

Missing sites measures every qubit. A Pauli measurement reads each selected qubit in the basis it was measured in.

Parameters:

  • measure (Mapping[str, object]) –

    Posted measurement with id, optional sites, and expression for counts.

  • num_qubits (int) –

    Qubits the model has.

Returns:

Raises:

  • ValueError –

    The id is not listed, sites is not a list of indexes, or a counts measurement has no expression.

Source code in shadowsim/cli/catalog.py
def measurements_for(measure: Mapping[str, object], num_qubits: int) -> list[Measurement]:
    """Return one expectation per selected qubit, or one counts expression.

    Missing ``sites`` measures every qubit. A Pauli measurement reads each
    selected qubit in the basis it was measured in.

    Args:
        measure: Posted measurement with ``id``, optional ``sites``, and
            ``expression`` for counts.
        num_qubits: Qubits the model has.

    Returns:
        Measurements in ``sites`` order.

    Raises:
        ValueError: The id is not listed, ``sites`` is not a list of indexes, or
            a counts measurement has no expression.
    """
    entry = _measurement(_measure_id(measure))
    sites = _sites(measure, num_qubits)
    if entry.kind == "pauli":
        return [Measurement((site,), '(counts["0"] - counts["1"]) / shots', f"expectation on {site}") for site in sites]
    expression = measure.get("expression")
    if not isinstance(expression, str):
        raise ValueError("a counts measurement needs an expression")
    return [Measurement(tuple(sites), expression)]

labels_for

labels_for(
    measure: Mapping[str, object], num_qubits: int
) -> list[str]

Return one chart name per curve.

A Pauli measurement on qubits 0 and 1 is ⟨Z⟩ on 0 and ⟨Z⟩ on 1, using that record's letter. Counts uses its expression.

Parameters:

  • measure (Mapping[str, object]) –

    Posted measurement, as in :func:measurements_for.

  • num_qubits (int) –

    Qubits the model has.

Returns:

  • list[str] –

    Chart names in sites order.

Raises:

  • ValueError –

    The id is not listed, or the measurement cannot be built.

Source code in shadowsim/cli/catalog.py
def labels_for(measure: Mapping[str, object], num_qubits: int) -> list[str]:
    """Return one chart name per curve.

    A Pauli measurement on qubits 0 and 1 is ``⟨Z⟩ on 0`` and ``⟨Z⟩ on 1``,
    using that record's letter. Counts uses its expression.

    Args:
        measure: Posted measurement, as in :func:`measurements_for`.
        num_qubits: Qubits the model has.

    Returns:
        Chart names in ``sites`` order.

    Raises:
        ValueError: The id is not listed, or the measurement cannot be built.
    """
    entry = _measurement(_measure_id(measure))
    if entry.kind == "counts":
        return [item.label for item in measurements_for(measure, num_qubits)]
    return [f"⟨{entry.letter}⟩ on {site}" for site in _sites(measure, num_qubits)]

observables_for

observables_for(
    num_qubits: int, measure_id: str, sites: list[int]
) -> list[Operator]

Return one Pauli on each selected qubit.

Parameters:

  • num_qubits (int) –

    Qubits the operator acts on.

  • measure_id (str) –

    A Pauli id from :func:listed_measurements.

  • sites (list[int]) –

    Qubit indexes, in the order the operators are returned.

Returns:

  • list[Operator] –

    One operator per site, with that measurement's letter on the site and

  • list[Operator] –

    I elsewhere.

Raises:

  • ValueError –

    measure_id is not listed, or it is not a Pauli measurement.

Source code in shadowsim/cli/catalog.py
def observables_for(num_qubits: int, measure_id: str, sites: list[int]) -> list[Operator]:
    """Return one Pauli on each selected qubit.

    Args:
        num_qubits: Qubits the operator acts on.
        measure_id: A Pauli id from :func:`listed_measurements`.
        sites: Qubit indexes, in the order the operators are returned.

    Returns:
        One operator per site, with that measurement's letter on the site and
        ``I`` elsewhere.

    Raises:
        ValueError: ``measure_id`` is not listed, or it is not a Pauli measurement.
    """
    entry = _measurement(measure_id)
    if entry.kind != "pauli":
        raise ValueError("a counts measurement has no Pauli operators")
    observables: list[Operator] = []
    for site in sites:
        label = ["I"] * num_qubits
        label[site] = entry.letter
        observables.append(Operator("".join(label)))
    return observables