This repository contains a series of examples showing how to use SimBricks.
Welcome! To use the examples shown in this repository effectively, you’ll need to follow a few setup steps. These steps ensure that you have access to the SimBricks cloud backend and the necessary tools to run the examples provided.
The examples in this repository utilize the SimBricks cloud version. To run them as-is, you’ll need access to this backend. Start by registering for a SimBricks demo account. The registration ensures you have the proper credentials to interact with the backend.
The easiest way to run examples here, is in [GitHub Codespaces]((https://codespaces.new/simbricks/simbricks-examples/?quickstart=1) or the pre-configured devcontainer in the repo. For the former, just click on the link above and create a new codespace. For the latter, open the repo in an IDE with devcontainer support, such as vscode and its Dev Containers Extension.
** With devcontainers no additional setup is required and you can directly move on to first steps.** For manual setup continue with the steps below.
Once you have your SimBricks demo account, clone this repository and set up a Python virtual environment to manage dependencies:
- Clone the repository:
git clone git@github.com:simbricks/simbricks-examples.git cd simbricks-examples - Create and activate a Python virtual environment:
python3 -m venv venv source venv/bin/activate
To run the examples in this repository, you need to install the following SimBricks Python packages:
- simbricks-orchestration: For creating virtual prototype configurations as shown in the examples.
- simbricks-client: For sending configurations to the SimBricks server via Python.
- simbricks-cli: For managing configurations via the terminal CLI.
You can install these packages using pip:
pip install -r requirements.txt
With the above steps completed, you’re ready to dive into the examples provided in this repository.
If you encounter any issues, consult the SimBricks documentation or reach out to us directly.
You can make your life a bit easier by enabling tab-completion for the simbricks-cli command:
simbricks-cli --install-completion
Depending on your shell you may then have to reload completion settings or relaunch. For example for bash:
exec bash
Under first-steps/first_steps.ipynb you will
find an iPython Notebook with an interactive introductions for your first steps
with SimBricks. This introduces the basic concepts for how to configure and run
SimBricks virtual prototypes. For initial quick playing around, you can even
immediately open this in the browser with
mybinder
(although there you will not have enough compute for anything interesting).
Within the netwroking-case-study folder you will find SimBricks examples that demonstrates how to leverage SimBricks orchestration framework to create increasingly complex virtual prototypes of network topologies.
It makes use of the concepts shown in the FirstSteps example and shows a simple setup in which multiple components of a virtual prototype are simulated by the same simulator.
The Corundum examples showcases the integration of the open-source, high-performance FPGA-based Corundum NIC.
Example that showcases how SimBricks can be used to consisting of one spine switch and a number of racks. Each rack contains a TOR switch and a mix of abstractly simulated hosts for background traffic that are simulated in ns-3 and hosts simulated in QEMU that each are connected to a dedicated NIC simulator. The QEMU hosts run a full Linux stack and execute Iperf. The topology created looks as depicted here.
SimBricks orchestration framework is written in Python. This makes it easy to write convenience functions yourself to share orchestration bits across experiments. Besides, SimBricks allows you to run your virtual prototype through python directly. This is useful in order to retrieve the simulation ourput line by line in python for parsing and testing. In the Api demo you can see simple examples for this.
In case you have any questions regarding one of the examples, SimBricks in general or how you can use SimBricks in your workflow feel free to reach out directly to us or open a issue in the simbricks main repository.