howto.rst 6.98 KB
Newer Older
Antoine Kaufmann's avatar
Antoine Kaufmann committed
1
..
Antoine Kaufmann's avatar
Antoine Kaufmann committed
2
  Copyright 2022 Max Planck Institute for Software Systems, and
Antoine Kaufmann's avatar
Antoine Kaufmann committed
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
  National University of Singapore
..
  Permission is hereby granted, free of charge, to any person obtaining
  a copy of this software and associated documentation files (the
  "Software"), to deal in the Software without restriction, including
  without limitation the rights to use, copy, modify, merge, publish,
  distribute, sublicense, and/or sell copies of the Software, and to
  permit persons to whom the Software is furnished to do so, subject to
  the following conditions:
..
  The above copyright notice and this permission notice shall be
  included in all copies or substantial portions of the Software.
..
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

24
25
.. _sec-howto:

26
###################################
Antoine Kaufmann's avatar
Antoine Kaufmann committed
27
How To
28
29
30
###################################


31
32
.. _sec-howto-createrun:

33
******************************
Antoine Kaufmann's avatar
Antoine Kaufmann committed
34
Create and Run an Experiment
35
36
******************************

37
38
39
Experiments are defined in a declarative fashion inside Python modules using
classes. Basically, create a `.py` file and add a global variable
``experiments``, a list which contains multiple instances of the class
40
:class:`~simbricks.orchestration.experiments.Experiment`, each one describing a
41
42
standalone experiment. This is very helpful if you wish to evaluate your work in
different environments, for example, you may want to swap out some simulator or
43
investigate multiple topologies with different scale. 
44
45
46

The class :class:`~simbricks.orchestration.experiments.Experiment` provides
methods to add the simulators you wish to run. All available simulators can be
47
found in the module :mod-orchestration:`simulators.py`. Instantiating
48
49
:class:`~simbricks.orchestration.simulators.HostSim` requires you to specify a
:class:`~simbricks.orchestration.nodeconfig.NodeConfig`, which contains the
50
51
configuration for your host, for example, its networking settings, how much
system memory it should have, and most importantly, which applications to run by
52
53
assigning an :class:`~simbricks.orchestration.nodeconfig.AppConfig`. You can
find predefined classes for node and app configs in the module
54
55
56
:mod-orchestration:`nodeconfig.py`. Feel free to add new ones or just create a
new class locally in your experiment's module. For more details, see
:ref:`sec-orchestration`.
57
58
59
60

The last step to complete your virtual testbed is to specify which virtual
components connect to each other. You do this by invoking the respective methods
on the simulators you have instantiated. See the different simulator types' base
61
62
63
classes in the module :mod-orchestration:`simulators.py` for more information. A
simple and complete experiment module in which a client host pings a server can
be found :ref:`below <simple_ping_experiment>`.
64
65

If you plan to simulate a topology with multiple hosts, it may be helpful to
66
67
take a look at the module :mod-orchestration:`simulator_utils.py` in which we
provide some helper functions to reduce the amount of code you have to write.
68

69
70
71
Finally, to run your experiment, invoke ``experiments/run.py`` and provide the
path to your experiment module. In our docker containers, you can also just use
the following command from anywhere:
72
73
74
75
76

.. code-block:: bash

  $ simbricks-run --verbose --force <path_to_your_module.py>

77
``--verbose`` prints all simulators' output to the terminal and ``--force``
78
79
forces execution even if there already exist result files for the experiment. If
``simbricks-run`` is not available, you can always do 
80
81
82
83
84
85

.. code-block:: bash
  
  $ cd experiments
  $ python run.py --verbose --force <path_to_your_module.py>

86
While running, you can interrupt the experiment using Ctrl+C in your terminal.
87
88
89
This will cleanly stop all simulators and collect their output in a JSON file in
the directory ``experiments/out/<experiment_name>``. These are the necessary
basics to create and run your first experiment. Have fun.
90
91
92

.. literalinclude:: /../experiments/pyexps/simple_ping.py
  :linenos:
93
  :lines: 29-
94
95
  :language: python
  :name: simple_ping_experiment
96
97
98
  :caption: A simple experiment with a client host pinging a server, both are
    connected through a network switch. The setup of the two hosts could be
    simplified by using
99
    :func:`simbricks.orchestration.simulator_utils.create_basic_hosts`.
100
101
102

.. _sec-howto-nodeconfig:

Antoine Kaufmann's avatar
Antoine Kaufmann committed
103
104
105
********************************
Add a Node or Application Config
********************************
106

107
108
A host's configuration and the workload to run are defined via
:ref:`sec-node_app_config`. SimBricks already comes with a few examples in the
109
110
111
112
113
module :mod-orchestration:`nodeconfig.py`. If they don't fit your use-case, you
need to add your own by overriding the pre-defined member functions of
:class:`~simbricks.orchestration.nodeconfig.NodeConfig` and
:class:`~simbricks.orchestration.nodeconfig.AppConfig`. The most important one
is :meth:`~simbricks.orchestration.nodeconfig.AppConfig.run_cmds`, which defines
114
the commands to execute for your workload/application. Further information can
115
be found in the module :mod-orchestration:`nodeconfig.py` directly.
116
117
118

.. _sec-howto-custom_image:

119
******************************
Antoine Kaufmann's avatar
Antoine Kaufmann committed
120
Add a Custom Image
121
122
123
******************************

******************************
Antoine Kaufmann's avatar
Antoine Kaufmann committed
124
Integrate a New Simulator
125
126
******************************

127
128
The first step when integrating a new simulator into SimBricks is to implement a
SimBricks adapter for it. You can find the necessary information in the
129
130
131
132
:ref:`Simulator Adapters <Simulator Adapters>` section. To then make running
experiments and setting up the communication channels with other simulators more
convenient, add a class for the simulator to the orchestration framework that
inherits from :class:`~simbricks.orchestration.simulators.Simulator` or one of
133
134
135
136
the more specialized base classes in :mod-orchestration:`simulators.py`. In
this class you define the command to execute the simulator together with further
parameters, for example, to connect to the communication channels with other
simulators. Below is an example of what this looks like.
137

Jonas Kaufmann's avatar
Jonas Kaufmann committed
138
.. code-block:: python
139
  :linenos:
140
141
  :caption: Orchestration framework class for WireNet, a simple Ethernet wire
    that attaches to the SimBricks Ethernet adapters of two simulators.
Jonas Kaufmann's avatar
Jonas Kaufmann committed
142

143
  class WireNet(NetSim):
Jonas Kaufmann's avatar
Jonas Kaufmann committed
144
145

    def run_cmd(self, env):
146
147
        connects = self.connect_sockets(env)
        assert len(connects) == 2
Jonas Kaufmann's avatar
Jonas Kaufmann committed
148
        cmd = (
149
150
151
            f'{env.repodir}/sims/net/wire/net_wire {connects[0][1]}'
            f' {connects[1][1]} {self.sync_mode} {self.sync_period}'
            f' {self.eth_latency}'
Jonas Kaufmann's avatar
Jonas Kaufmann committed
152
        )
153
154
155
        if env.pcap_file:
            cmd += ' ' + env.pcap_file
        
Jonas Kaufmann's avatar
Jonas Kaufmann committed
156
        return cmd
157
158


159
******************************
Antoine Kaufmann's avatar
Antoine Kaufmann committed
160
Add a New Interface
161
******************************