1.1. Setup#

Hint

If you already set up your SimBricks environment, you can immediately proceed by configuring your first virtual prototype

The examples within the Examples repository utilize the SimBricks Cloud version. To run them as-is, you will need access to the SimBricks Demo Backend (or your own if already present).

To get access to the SimBricks Demo Backend, start by registering for the SimBricks Demo. The registration ensures you have the proper credentials to interact with the Backend. This is necessary to send your virtual prototypes to our Backend such that the virtual prototype’s execution will be scheduled on one of our Runners.

Once you got access to our Backend, you can proceed by cloning our Examples Repository:

git clone git@github.com:simbricks/simbricks-examples.git
cd simbricks-examples

1.1.1. Option 1: Dev Container / GitHub Codespaces (no further setup)#

The examples repository ships a pre-configured Visual Studio Code Development Container. If you open the repository in VS Code with the VS Code Dev Containers extension installed (or directly in GitHub Codespaces), all required SimBricks Python packages are installed automatically and you can skip straight ahead to creating your first virtual prototype.

1.1.2. Option 2: Manual setup with a Python virtual environment#

Alternatively, set up a Python Virtual Environment (Python 3.10 or newer). You can create and activate a virtual environment as follows:

python3 -m venv venv
source venv/bin/activate

Then install the required SimBricks Python packages. To run the examples given in the repository (or your own virtual prototypes), the following SimBricks packages are required:

  • simbricks-orchestration: For creating virtual prototype configurations as shown in the following.

  • simbricks-client: For sending configurations to the SimBricks server via Python.

  • simbricks-cli: For managing configurations via the terminal CLI.

  • The Python packages of the component simulators an example uses, e.g. simbricks-qemu-sim-py, simbricks-i40e-sys-py, simbricks-i40e-sim-bm-py, or simbricks-net-base-sim-py. Since simulators no longer live inside the core packages, every virtual prototype script installs exactly the component packages it imports (see Installing SimBricks Packages (Conda Channel) for the full package list and naming scheme).

You can conveniently install all packages needed by the examples using pip and the requirements.txt file we provide with the examples repository:

pip install -r requirements.txt

Note

The Python packages installed here are all you need for writing virtual prototypes and submitting them to the SimBricks Cloud, where the actual simulators run on our Runners. If you instead want to execute virtual prototypes on your own machine, you additionally need the simulator binaries, which are distributed through the SimBricks conda channel — see Advanced Setup & Building.

1.1.3. Your namespace#

The SimBricks CLI and Client submit your runs to a namespace on the Backend. When you register for the demo, we automatically create the namespace demo/<your demo email address> for you and configure it as your default — so there is nothing you need to set up here.

Note

If you ever want to work with a different namespace than your default, you can override it through the NAMESPACE environment variable, e.g. export NAMESPACE=demo/<your demo email address>.

Optionally, you can also enable tab completion for the SimBricks CLI:

simbricks-cli --install-completion

With the above steps completed, you are ready to dive into using SimBricks.

If you encounter any issues, feel free to reach out to us directly.