2.5. Running Virtual Prototypes#
Tip
Before running virtual prototypes check out our chapter on the Orchestration Framework for Virtual Prototypes that allows to configure virtual prototypes using python scripts.
Additionally you should also check out our chapter on the SimBricks Architecture to get a better overview over some of the concepts talked about throughout the rest of this chapter.
In this chapter we provide an overview on how to execute your SimBricks virtual prototypes, both locally and in cloud environments.
The following information assumes some familiarity with SimBricks and that you already wrote a python script configuring your virtual prototype. Make sure this python script is ready and contains the necessary information.
2.5.1. Cloud#
Attention
Throughout this section we will assume that you already set up Runner properly in order to execute your virtual prototypes in the cloud. That means we assume that you are using a setup in which Runner were created and that they have the required dependencies installed. These respective Runner should additionally be properly tagged to match your virtual prototyping script’s configuration.
Tip
If want to leatrn how to setup up Runner and how they function check out our documentation here.
SimBricks cloud version comes with a hosted SimBricks Backend that serves as the central hub for managing and executing virtual prototype simulations Therefore, once users specified thier virtual prototypes through our python Orchestration Framework for Virtual Prototypes, users can submit those to the Backend (along with outputs and results) were they are stored, ensuring these can be retrieved at any time in the future.
Further will the Backend schedule virtual prototype execution Runs on Runners provided by users ensuring seamless resource sharing across multiple users of the same organization.
Users interact with the Backend through SimBricks Command-Line Interface (CLI) or directly in python through the Client Library.
2.5.1.1. Runs#
SimBricks Cloud introduces the concept of Runs, a foundational feature that simplifies and structures the execution of virtual prototypes defined through user-submitted configurations. A Run encapsulates the lifecycle of a single execution instance of one of your virtual prototypes and is managed by the SimBricks backend.
That means a Run represents the execution of a virtual prototype which in turn is defined by the System-, Simulation- and Instantiation Configuration. Once these configurations are submitted to the SimBricks Backend by a user, they can use those stored configurations to create Runs. A Run will then encapsulate those configurations for executing the virtual prototype.
The Backend will automatically schedule available Runs (i.e. once the user created a Run or multiple Runs in the Backend) for execution. During scheduling decisions are made the Backend will consider multiple factors:
Availability: There must be enough Runners available to execute virtual prototypes. Especially when in scenarios were the execution shall be distributed across multiple machines.
Resources: To execute a virtual prototype (or a part thereof) on a Runner, enough computational resources must still be available on that RUnner for execution.
Tags: The backend matches Runner tags specified in the Instantiation-Configuration to ensure Runs are executed by Runners with the appropriate tags.
If the necessary resources or tags are not available, the Run is queued until suitable Runners are accessible.
The creation and execution of a Run will not modify or alter the submitted System-, Simulation- and Instantiation Configurations. Instead, the Run establishes the necessary connections between these configurations and the output data generated during its execution. This ensures that the original configurations remain unchanged, allowing users to reuse them for additional Runs while maintaining a clear link to the results and logs associated with each specific execution i.e. Run.
2.5.1.2. CLI#
The CLI i.e. the simbricks-cli package provides a command-line interface for managing SimBricks virtual prototypes. That means either sending them to or managing virtual protoypes already stored in the SimBricks Backend.
Hint
You can simply install CLI package by running pip install simbricks-cli.
It is ideal when working in a terminal environment if a lightweight way to interact with the SimBricks Backend is needed.
Through the CLI you can:
Submit Instantiation Configurations for execution:
simbricks-cli runs submit <path to tour virtual prototype python script>
Note that in order to submit a virtual prototype python script to the backend via the CLI, it must declare a list of Instantiation Configurations. In case submitting yout virtual prototype was successful, you should be able to see output that looks similar to the following:
$ simbricks-cli runs submit <path to tour virtual prototype python script> Run -------------------------------------------- | id | instantiation_id | state | -------------------------------------------- | 10 | 10 | RunState.SPAWNED | --------------------------------------------
Alternatively users can also create a Run from an existing Instantiation Configuration that they submitted beforehand:
simbricks-cli runs create <id of the instantiation configoration>
Assuming the execution of a virtual prototypes already started. Then, in case one wants to follow the output created by that execution, its easy to do so:
simbricks-cli runs follow <id of the run to follow>
When following an active Run you should be able to see output that looks similar to the following:
[host.QemuSim-25] Formatting '/workspaces/simbricks_docker/runner-work/run-10-767b3eb9-f93f-495a-80ee-d9754981d7aa/tmp/imgs/hdcopy.2', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=42949672960 backing_file=/workspaces/simbricks_docker/images/output-base/base backing_fmt=qcow2 lazy_refcounts=off refcount_bits=16 [host.QemuSim-25] prepare command exited with code 0 [host.QemuSim-26] Formatting '/workspaces/simbricks_docker/runner-work/run-10-767b3eb9-f93f-495a-80ee-d9754981d7aa/tmp/imgs/hdcopy.10', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=42949672960 backing_file=/workspaces/simbricks_docker/images/output-base/base backing_fmt=qcow2 lazy_refcounts=off refcount_bits=16 [host.QemuSim-26] prepare command exited with code 0 [net.SwitchNet-29] Switch connecting to: /workspaces/simbricks_docker/runner-work/run-10-767b3eb9-f93f-495a-80ee-d9754981d7aa/tmp/shm/eth-5.21.20 [net.SwitchNet-29] Switch connecting to: /workspaces/simbricks_docker/runner-work/run-10-767b3eb9-f93f-495a-80ee-d9754981d7aa/tmp/shm/eth-13.23.22 [host.QemuSim-25] qemu-system-x86_64: warning: host doesn't support requested feature: CPUID.07H:EBX.hle [bit 4] [host.QemuSim-25] qemu-system-x86_64: warning: host doesn't support requested feature: CPUID.07H:EBX.rtm [bit 11] [host.QemuSim-25] Wrong EFI loader signature. [host.QemuSim-25] early console in extract_kernel ...
View Runs that are currently stored on the server along their status:
simbricks-cli runs ls
Hint
SimBricks CLI does offer more commands which allow users to interact with SimBricks backend for managing virtual prototypes and their execution. For a complete list check out references.
2.5.1.3. Client Library#
The Client Library i.e. the simbricks-client package is used for interacting with the SimBricks Backend and implements its API. It provides the interface i.e. python functions to:
Upload virtual prototype configurations. That means it offers functions to send System-, Simulation-, and Instantiation-Configurations to the SimBricks Backend in order to store those there.
Users can upload their Python simulation scripts and related configurations to the cloud.
Manage Simulations: It allows users to cerate, stop, monitor and alter the execution of virtual prototypes through Runs.
Retrieve Results: After a simulation is complete, users can download logs and output files for analysis.
Hint
You can simply install client library by running pip install simbricks-client.
This package is particularly useful if users want to interact with SimBricks virtual prototypes in python directly. This can e.g. be very useful when integrating SimBricks into yout CI/CD setup.
Through the Client Library you can:
extend the experiment script to send the virtual prototype through the python API to the SimBricks Backend:
... sys = system.System() ... simulation = sim.Simulation("My-very-first-test-simulation", sys) ... instance = inst.Instantiation(simulation) ... await opus_base.create_run(instance) ...
re-submit script: submit via python script itself using the api:
python3 simple_demo.py
Hint
If you want to have a closer look at the funcitons offered by our python client library check out its refernce here.
2.5.2. On-Premise#
Attention
The SimBricks on-premise version for local execution is designed to provide a lightweight solution for running simulations on a single machine and is primarily meant to facilitate testing, debugging, and running very small simulations. Compared to the loud offering it comes with some following limitations and a reduced feature set (e.g. no distributed simulations) and generally limited support.
It is also possible to run SimBricks virtual prototypes locally without a cloud setup or Runners.
For this SimBricks ships the simbricks-local python package that comes with a command line tool to execute simulations. You can check that it is installed by invoking simbricks-run –help. In that case you should see output similar to the following:
usage: simbricks-run [-h] [--list] [--filter PATTERN [PATTERN ...]] [--runs N] [--firstrun N] [--force] [--verbose] [--pcap] [--profile-int S] [--repo DIR] [--workdir DIR] [--parallel] [--cores N] [--mem N] EXP [EXP ...]
positional arguments:
EXP Python modules to load the experiments from
options:
-h, --help show this help message and exit
--list List available experiment names
--filter PATTERN [PATTERN ...]
Only run experiments matching the given Unix shell style patterns
--runs N Number of repetition of each experiment
--firstrun N ID for first run
--force Run experiments even if output already exists (overwrites output)
--verbose Verbose output, for example, print component simulators' output
--pcap Dump pcap file (if supported by component simulator)
--profile-int S Enable periodic sigusr1 to each simulator every S seconds.
Environment:
--repo DIR SimBricks repository directory
--workdir DIR Work directory base
Parallel Runtime:
--parallel Use parallel instead of sequential runtime
--cores N Number of cores to use for parallel runs
--mem N Memory limit for parallel runs (in MB)
Having it installed, users can simply execute their virtual prototypes (assuming the necessary simulators and their dependencies are available locally) by running the following:
simbricks-run --verbose <path to your virtual prototype python script>
This command will cause SimBricks to run your virtual prototype locally.
Hint
You can simply install SimBricks package for local execution by running pip install simbricks-local
All output is collected in a JSON file, which allows easy post-processing afterwards. Output files generated through local execution will be placed in a local folder that user can investigate to extract data from the execution.