Skip to content

commands

Research CLI subcommands: model, simulate, compare, and run.

add_research_parsers

add_research_parsers(subparsers: _SubParsersAction) -> None

Register model, simulate, compare, and run.

Source code in shadowsim/cli/commands.py
def add_research_parsers(subparsers: argparse._SubParsersAction) -> None:
    """Register ``model``, ``simulate``, ``compare``, and ``run``."""
    add_model_parser(subparsers)
    add_simulate_parser(subparsers)
    add_compare_parser(subparsers)
    add_run_parser(subparsers)

add_model_parser

add_model_parser(subparsers: _SubParsersAction) -> None

Register shadowsim model.

Source code in shadowsim/cli/commands.py
def add_model_parser(subparsers: argparse._SubParsersAction) -> None:
    """Register ``shadowsim model``."""
    parser = subparsers.add_parser("model", help="Build a model section from factory arguments.")
    parser.add_argument(
        "model",
        choices=_model_ids(),
        help="Model factory id from the catalog.",
    )
    parser.add_argument("--qubits", type=int, help="Qubit count for factories that take n_qubits.")
    _add_model_param_flags(parser)
    _add_format_flags(parser)
    parser.set_defaults(handler=run_model)

add_simulate_parser

add_simulate_parser(subparsers: _SubParsersAction) -> None

Register shadowsim simulate.

Source code in shadowsim/cli/commands.py
def add_simulate_parser(subparsers: argparse._SubParsersAction) -> None:
    """Register ``shadowsim simulate``."""
    parser = subparsers.add_parser("simulate", help="Run one simulator from CLI flags.")
    _add_shared_run_flags(parser, backends=False)
    parser.set_defaults(handler=run_simulate)

add_compare_parser

add_compare_parser(subparsers: _SubParsersAction) -> None

Register shadowsim compare.

Source code in shadowsim/cli/commands.py
def add_compare_parser(subparsers: argparse._SubParsersAction) -> None:
    """Register ``shadowsim compare``."""
    parser = subparsers.add_parser(
        "compare",
        help="Run one simulator on multiple backends and compare them.",
    )
    _add_shared_run_flags(parser, backends=True)
    parser.set_defaults(handler=run_compare)

add_run_parser

add_run_parser(subparsers: _SubParsersAction) -> None

Register shadowsim run.

Source code in shadowsim/cli/commands.py
def add_run_parser(subparsers: argparse._SubParsersAction) -> None:
    """Register ``shadowsim run``."""
    parser = subparsers.add_parser("run", help="Run a version 1 JSON or YAML experiment file.")
    parser.add_argument("path", help="Path to a .json, .yaml, or .yml run document.")
    parser.add_argument(
        "--output-dir",
        help="Directory that save and export paths must stay under.",
    )
    _add_format_flags(parser)
    parser.set_defaults(handler=run_run)

run_model

run_model(args: Namespace) -> int

Print a model stub built from factory flags.

Source code in shadowsim/cli/commands.py
def run_model(args: argparse.Namespace) -> int:
    """Print a model stub built from factory flags."""
    stub = model_stub(
        args.model,
        arguments=_model_arguments(args.model, args),
        qubits=getattr(args, "qubits", None),
    )
    if args.print_document or args.format == "json":
        _emit_json(stub)
        return 0
    model = stub["model"]
    assert isinstance(model, Mapping)
    print(f"model: {model['id']}")
    arguments = model.get("arguments", {})
    assert isinstance(arguments, Mapping)
    if not arguments:
        print("arguments: (defaults)")
        return 0
    print("arguments:")
    for key in sorted(arguments):
        print(f"  {key}: {arguments[key]}")
    return 0

run_simulate

run_simulate(args: Namespace) -> int

Build and run a single-simulator document.

Source code in shadowsim/cli/commands.py
def run_simulate(args: argparse.Namespace) -> int:
    """Build and run a single-simulator document."""
    document = _document_from_run_args(args, backends=None)
    return _execute_document(document, args)

run_compare

run_compare(args: Namespace) -> int

Build and run a multi-backend compare document.

Source code in shadowsim/cli/commands.py
def run_compare(args: argparse.Namespace) -> int:
    """Build and run a multi-backend compare document."""
    backends = parse_id_list(args.backends)
    document = _document_from_run_args(args, backends=backends)
    return _execute_document(document, args)

run_run

run_run(args: Namespace) -> int

Load a document from disk and run it.

Source code in shadowsim/cli/commands.py
def run_run(args: argparse.Namespace) -> int:
    """Load a document from disk and run it."""
    document = load_document(args.path)
    if args.print_document:
        _emit_json(document)
        return 0
    return _execute_document(document, args)