Skip to content

catalog

List the concrete simulators for the builder page.

ListedSimulatorField

Bases: TypedDict

One constructor setting the builder page can edit.

choices is present when kind is choice. minimum and maximum are present when the integer is bounded. default is the text that fills the chip. A missing posted value uses that default.

Source code in shadowsim/simulators/catalog.py
class ListedSimulatorField(TypedDict):
    """One constructor setting the builder page can edit.

    ``choices`` is present when ``kind`` is ``choice``. ``minimum`` and
    ``maximum`` are present when the integer is bounded. ``default`` is the
    text that fills the chip. A missing posted value uses that default.
    """

    name: str
    label: str
    kind: Literal["integer", "choice"]
    default: str
    choices: NotRequired[list[str]]
    minimum: NotRequired[int]
    maximum: NotRequired[int]

ListedSimulator

Bases: TypedDict

Display record for one concrete simulator.

Source code in shadowsim/simulators/catalog.py
class ListedSimulator(TypedDict):
    """Display record for one concrete simulator."""

    id: str
    title: str
    detail: str
    phrase: str
    setup: str
    observables: bool
    samples: bool
    closed_system: bool
    fields: list[ListedSimulatorField]

listed_simulators

listed_simulators() -> list[ListedSimulator]

Return the exported simulator classes whose modules import successfully.

:class:~shadowsim.simulators.simulator.Simulator itself is omitted. A class is skipped when its extra is not installed. observables is true when the constructor takes observables, so the page uses the explicit-operator path. samples is true when the class sets requires_sampling_backend, so the page pairs it only with a backend that has a shot budget. closed_system is true when the class sets that attribute. title and phrase are the class title attribute. A class without one uses its name with Simulator removed.

fields lists the chip parameters that constructor takes, in signature order. The names are time_steps, num_steps, trotter_depth, order, and seed. A parameter the constructor does not take is absent. time_steps defaults to 101 when the constructor records observables and 11 otherwise. num_steps defaults to 4 and seed to 0. trotter_depth and order use the constructor default. A bounded integer carries minimum and maximum. order is a choice taken from its Literal annotation.

setup names the class and walks the constructor. The page's values stay as placeholders: {name}, {hamiltonians}, {lindblads}, state, e_ops, {qubits}, {total}, and {backend}. {basis} is glued to the argument before basis. Each chip parameter is written {name}. An optional parameter that is not a chip is omitted. A required parameter the page does not fill is left as its name.

Returns:

Raises:

  • ImportError –

    None of the simulator modules could be imported.

Source code in shadowsim/simulators/catalog.py
def listed_simulators() -> list[ListedSimulator]:
    """Return the exported simulator classes whose modules import successfully.

    :class:`~shadowsim.simulators.simulator.Simulator` itself is omitted. A class
    is skipped when its extra is not installed. ``observables`` is true when the
    constructor takes ``observables``, so the page uses the explicit-operator
    path. ``samples`` is true when the class sets ``requires_sampling_backend``,
    so the page pairs it only with a backend that has a shot budget.
    ``closed_system`` is true when the class sets that attribute. ``title`` and
    ``phrase`` are the class ``title`` attribute. A class without one uses its
    name with ``Simulator`` removed.

    ``fields`` lists the chip parameters that constructor takes, in signature
    order. The names are ``time_steps``, ``num_steps``, ``trotter_depth``,
    ``order``, and ``seed``. A parameter the constructor does not take is
    absent. ``time_steps`` defaults to 101 when the constructor records
    observables and 11 otherwise. ``num_steps`` defaults to 4 and ``seed`` to
    0. ``trotter_depth`` and ``order`` use the constructor default. A bounded
    integer carries ``minimum`` and ``maximum``. ``order`` is a choice taken
    from its ``Literal`` annotation.

    ``setup`` names the class and walks the constructor. The page's values stay
    as placeholders: ``{name}``, ``{hamiltonians}``, ``{lindblads}``, ``state``,
    ``e_ops``, ``{qubits}``, ``{total}``, and ``{backend}``. ``{basis}`` is
    glued to the argument before ``basis``. Each chip parameter is written
    ``{name}``. An optional parameter that is not a chip is omitted. A required
    parameter the page does not fill is left as its name.

    Returns:
        Simulators the builder page can offer.

    Raises:
        ImportError: None of the simulator modules could be imported.
    """
    listed: list[ListedSimulator] = []
    for class_name, (module_name, extra) in simulators._EXPORTS.items():
        try:
            module = (
                importlib.import_module(module_name) if extra is None else import_optional(module_name, extra=extra)
            )
        except ImportError:
            continue
        value = getattr(module, class_name, None)
        if not isinstance(value, type) or not issubclass(value, Simulator) or value is Simulator:
            continue
        listed.append(_describe_simulator(value))
    if not listed:
        raise ImportError("no simulators could be imported")
    return listed