2.5. Runners#

Runners are the core execution engines within the SimBricks architecture. They are responsible for the actual execution of virtual prototypes (VPs). While users interface with the SimBricks Cloud through our Python API, the heavy lifting of running complex, heterogeneous simulations occurs on Runners.

Because we support both SimBricks-hosted and self-hosted execution environments, the Runner logic is entirely open-source. It is implemented in Python and can be found in the main repository under symphony/runner/simbricks/runner, distributed as the simbricks-runner package.

2.5.1. Resource Management and Scheduling#

Runners are designed to allow safe and efficient resource sharing across multiple users on the same infrastructure.

When a user submits a virtual prototyping configuration to the SimBricks Backend, the backend evaluates the resource requirements of the run. It then schedules the execution on an available Runner that has sufficient capacity.

To ensure stability and prevent Runners from overwhelming the host machines they operate on, they can be strictly constrained via the backend. Administrators can configure exact limits on the computational resources and memory a specific Runner is allowed to allocate, ensuring predictable performance even in shared environments.

Runners carry labels (tags). In the Instantiation Configuration, users can constrain a Fragment to Runners that have all of a given set of labels by setting runner_tags on the Fragment — this is how, e.g., a Fragment requiring a special simulator environment is steered to a suitably provisioned Runner.

2.5.2. Runner Architecture: Main vs. Fragment Runner#

../../_images/SimBricks-Runner-Architecture.png

Fig. 2.5 Architectural Overview over Main and Fragment Runners.#

To support highly complex and distributed simulations, SimBricks execution is decoupled into Main Runners and Fragment Runners.

Users have the option to split the execution of a virtual prototype across multiple “Fragments.” When a run is scheduled, a Main Runner takes charge of the orchestration. It evaluates the configuration and spawns Fragment Runners on demand to execute specific portions of the virtual prototype.

Splitting execution into fragments provides two major advantages:

  1. Distributed Simulation: Fragments can be distributed across multiple Runners, allowing massive virtual prototypes (e.g., hundreds of simulated hosts) to scale horizontally across a cluster.

  2. Heterogeneous Environments: Multiple fragments can be executed on the same Runner using different environments. For example, one fragment containing a specific simulator can run bare-metal on the host, while another fragment runs simultaneously inside an isolated Docker container.

2.5.3. Main Runner Plugins#

To facilitate these heterogeneous environments, the Main Runner utilizes a plugin system to determine how a Fragment Runner should be spawned. The available fragment executors are declared in the Runner’s configuration file, each with a tag that Fragments can reference through fragment.fragment_executor_tag:

fragment_executors:
  - base_executor:
      plugin: simbricks.runner.main_runner.plugins.local_plugin

Currently, SimBricks supports two primary plugins:

2.5.3.1. The Local Plugin#

The Local plugin is used for bare-metal execution. When this plugin is invoked, the Main Runner spawns a Fragment Runner (simbricks-executor-local) directly on the host OS. This approach assumes that all required simulators and dependencies for that specific fragment are natively installed on the machine the Runner is operating on — typically by installing the respective simbricks-*-bin conda packages into the Runner’s environment (see Installing SimBricks Packages (Conda Channel)).

2.5.3.2. The Docker Plugin#

The Docker plugin allows for containerized execution. Instead of relying on local host dependencies, the Main Runner starts the Fragment Runner inside a Docker container (by default the pre-built simbricks/simbricks-executor image, which contains the standard simulators and the base disk image; see Using Pre-Built Docker Images). The image to use is configurable per fragment executor, and administrators can restrict the allowed images through allow/deny lists in the Runner configuration.

Note

Use Case: Custom Simulator Integrations

We utilize fragment executor tags in our Corundum example (available in the SimBricks examples repository simbricks/simbricks-examples): the virtual prototype’s Fragment sets fragment.fragment_executor_tag = "corundum_executor", selecting a fragment executor whose environment has the simbricks-corundum-sim-rtl-bin conda package installed. This setup is powerful for custom hardware development: teams maintain and build their custom simulator integration in a completely separate component repository, package it as conda packages, and provision a fragment executor with them — without ever needing to modify the SimBricks core or the other simulators’ environments.