document
¶
Build and load version 1 run documents for the research CLI.
parse_id_list
¶
Split a comma-separated id list, stripping blanks.
Raises:
-
ValueError–texthas no ids after splitting.
Source code in shadowsim/cli/document.py
model_section
¶
model_section(
model_id: str,
*,
arguments: Mapping[str, object] | None = None,
qubits: int | str | None = None,
) -> dict[str, object]
Return the model section for a factory model_id.
qubits is written as n_qubits when the catalog marks the factory as
taking that argument. Explicit arguments win over qubits when both
set n_qubits.
Raises:
-
ValueError–model_idis not a listed factory.
Source code in shadowsim/cli/document.py
simulator_entry
¶
simulator_entry(
simulator_id: str,
*,
arguments: Mapping[str, object] | None = None,
backend_id: str | None = None,
backend_arguments: Mapping[str, object] | None = None,
) -> dict[str, object]
Return one simulators entry.
Raises:
-
ValueError–simulator_idorbackend_idis not listed.
Source code in shadowsim/cli/document.py
expand_compare_backends
¶
expand_compare_backends(
simulator_id: str,
backends: Sequence[str],
*,
simulator_arguments: Mapping[str, object] | None = None,
backend_arguments: Mapping[str, object] | None = None,
) -> list[dict[str, object]]
Expand one simulator and many backends into simulators entries.
The first backend is the benchmark reference. Shared backend_arguments
are copied onto every entry.
Raises:
-
ValueError–Fewer than two backends, a duplicate id, or an unknown id.
Source code in shadowsim/cli/document.py
actions_section
¶
actions_section(
*,
action_ids: Sequence[str] | None = None,
save_path: str | None = None,
export_path: str | None = None,
) -> dict[str, object]
Return the actions section.
When action_ids is omitted, save and/or export are included for
any path that was passed. An empty id list is allowed for stdout-only runs.
Raises:
-
ValueError–An action id is not listed.
Source code in shadowsim/cli/document.py
build_document
¶
build_document(
*,
model: Mapping[str, object],
simulators: Sequence[Mapping[str, object]],
total: object = "0.5",
state_id: str = "basis",
state_value: object | None = None,
measure_id: str = "model",
measure_sites: object | None = None,
measure_expression: object | None = None,
actions: Mapping[str, object] | None = None,
) -> dict[str, object]
Assemble a version 1 run document.
Missing state_value defaults to an all-zero bit string when state_id
is basis or gray and the model arguments include n_qubits.
Raises:
-
ValueError–A listed id is unknown,
simulatorsis empty, or the model section is not a factory object.
Source code in shadowsim/cli/document.py
build_run_document
¶
build_run_document(
*,
model: str,
simulator: str,
model_arguments: Mapping[str, object] | None = None,
qubits: int | str | None = None,
total: object = "0.5",
state: str = "basis",
state_value: object | None = None,
simulator_arguments: Mapping[str, object] | None = None,
backend: str | None = None,
backend_arguments: Mapping[str, object] | None = None,
backends: Sequence[str] | None = None,
measure: str = "model",
measure_sites: object | None = None,
measure_expression: object | None = None,
save_path: str | None = None,
export_path: str | None = None,
action_ids: Sequence[str] | None = None,
) -> dict[str, object]
Build a version 1 document from research-CLI fields.
Pass backend for a single run, or backends (at least two) for a
compare document. Passing both is an error.
Raises:
-
ValueError–Both
backendandbackendsare set, compare has fewer than two backends, or a catalog id is unknown.
Source code in shadowsim/cli/document.py
model_stub
¶
model_stub(
model_id: str,
*,
arguments: Mapping[str, object] | None = None,
qubits: int | str | None = None,
) -> dict[str, object]
Return a document stub that only fills the model section.
The stub keeps empty simulators out of the validated run shape so
callers can print construction output without choosing a simulator.
Source code in shadowsim/cli/document.py
load_document
¶
Load a version 1 run document from JSON or YAML.
.json is always supported. .yaml / .yml need the yaml extra.
Raises:
-
ValueError–The suffix is unsupported, or the file is not a JSON/YAML object.
-
OSError–The file cannot be read.
-
ImportError–A YAML file was given without the
yamlextra. -
JSONDecodeError–The JSON text is invalid.