orchestration.rst: pass over existing content

doc/user/orchestration.rst

@@ -28,11 +28,11 @@ SimBricks Orchestration
 ###################################
 
 Our orchestration framework replaces hand-crafted scripts for setting up and
-running experiments. Instead, they are described in a declarative fashion. The
-orchestration framework then takes care of the details managing launching the
-respective component simulators, setting up the SimBricks communication channels
-between them, and monitoring their execution. All output is collected in a JSON
-file, which allows post-processing afterwards. 
+running experiments. Instead, experiments are described in a declarative
+fashion. The orchestration framework then takes care of the details, manages
+launching the respective component simulators, sets up the SimBricks
+communication channels between them, and monitors their execution. All output is
+collected in a JSON file, which allows easy post-processing afterwards. 
 
 ******************************
 Concepts
@@ -44,11 +44,12 @@ which we now introduce.
 Experiments
 ===========
 
-An *experiment* defines which component simulators to run, how they are
-connected, and which workload is executed. To define an experiment, instantiate
-the class :class:`~simbricks.orchestration.experiments.Experiment` in your own
-Python module, which has member functions to further define the component
-simulators to run. SimBricks comes with many pre-defined experiments, which can serve as starting guides and are located in the repository under ``experiments/pyexps``.
+An *experiment* defines which component simulators to run and how they are
+connected. To define one, instantiate the class
+:class:`~simbricks.orchestration.experiments.Experiment` in your own Python
+module, which has member functions to further define the component simulators to
+run. SimBricks comes with many pre-defined experiments, which can serve as
+starting guides and are located in the repository under ``experiments/pyexps``.
 
 .. autoclass:: simbricks.orchestration.experiments.Experiment
   :members: add_host, add_pcidev, add_nic, add_network
@@ -58,86 +59,80 @@ Runs
 
 Experiments can be executed multiple times, for example, to gain statistical
 insights when including a random or non-deterministic component. We call each
-execution one *run* of the experiment. Each run produces its own output JSON
-file. The file name includes the number of the run.
+execution a *run* of the experiment. Each run produces its own output JSON file.
+The file name includes the number of the run.
 
 The number of runs can be specified when invoking the orchestration framework,
 see :ref:`sec-command-line`. When using simulator checkpointing, we use one run
-to boot the simulator and take the checkpoint, and a second one to execute the
-actual experiment. This is the reason for two output JSON files being produced.
-For more information, see :ref:`sec-checkpointing`.
+to boot the simulator and take the checkpoint, and a second one to carry out the
+actual experiment. This is the reason for two output JSON files being produced
+in this case. For more information, see :ref:`sec-checkpointing`.
 
 Component Simulators
 ====================
 
-SimBricks provides multiple already implemented component simulators, which
-can be used in experiments. This selection includes host, NIC, network, and PCI
-device simulators. Each simulator is implemented in a class deriving from
+SimBricks comes with multiple, ready-to-use component simulators for your
+experiments in :mod:`simbricks.orchestration.simulators`. These include host,
+NIC, network, and PCIe device simulators. On the orchestration side, each
+simulator is implemented in a class deriving from
 :class:`~simbricks.orchestration.simulators.Simulator`, which provides the
-necessary commands and arguments for its execution and for specifying the
-SimBricks communication channel to connect to. We also offer more specialized
-base classes for the different component types, which implement common member
-functions, for example, add connected NICs or network component simulators to a
-host component simulator. Every already implemented component simulator can be
-found in the module. :mod:`simbricks.orchestration.simulators`.
+necessary commands for their execution. We also offer more specialized base
+classes for the different component types, which implement common member
+functions, for example, to connect NICs or network component simulators to a
+host simulator.
 
 .. automodule:: simbricks.orchestration.simulators
-
-  .. autoclass:: simbricks.orchestration.simulators.Simulator
-    :members: resreq_cores, resreq_mem, prep_cmds, run_cmd, dependencies
-
-  .. autoclass:: simbricks.orchestration.simulators.HostSim
-    :members: add_pcidev, add_nic, add_netdirect
-
-  .. autoclass:: simbricks.orchestration.simulators.NICSim
-    :members: set_network
-
-  .. autoclass:: simbricks.orchestration.simulators.NetSim
-    :members: connect_network
-
-  .. autoclass:: simbricks.orchestration.simulators.PCIDevSim
-
-
-.. _sec-node-config:
-
-Node Configuration
-==================
-
-The configuration and workload to run on individual host simulators or, more
-generally, nodes that should run in the experiment, are defined using the
-classes :class:`~simbricks.orchestration.nodeconfig.NodeConfig` and
-:class:`~simbricks.orchestration.nodeconfig.AppConfig`, respectively.
-
-:class:`~simbricks.orchestration.nodeconfig.NodeConfig` defines, for example,
-the networking configuration like IP address and subnet mask, how much system
-memory the node has, and which disk image to run. The latter can be used, for
-example, to run a specific version of the Linux kernel on a node. You can find
-more information on this in the :ref:`next section <sec-howto-custom_image>`.
-:class:`~simbricks.orchestration.nodeconfig.NodeConfig` contains an attribute
-for a :class:`~simbricks.orchestration.nodeconfig.AppConfig`.
+  
+.. autoclass:: simbricks.orchestration.simulators.Simulator
+  :members: prep_cmds, run_cmd, resreq_cores, resreq_mem
+
+.. autoclass:: simbricks.orchestration.simulators.HostSim
+  :members: sync_mode, sync_period, pci_latency, add_pcidev, add_nic, add_netdirect
+  :show-inheritance:
+
+.. autoclass:: simbricks.orchestration.simulators.NetSim
+  :members: sync_mode, sync_period, eth_latency, connect_network
+  :show-inheritance:
+
+.. autoclass:: simbricks.orchestration.simulators.PCIDevSim
+  :members: sync_mode, sync_period, pci_latency
+  :show-inheritance:
+
+.. autoclass:: simbricks.orchestration.simulators.NICSim
+  :members: eth_latency, set_network
+  :show-inheritance:
+
+.. _sec-node_app_config:
+
+*******************
+Node and App Config
+*******************
+
+To configure the workload and the software environment of nodes, use the classes
+:class:`~simbricks.orchestration.nodeconfig.NodeConfig` and
+:class:`~simbricks.orchestration.nodeconfig.AppConfig`. The former is passed to
+every host simulator and defines, for example, the networking configuration like
+IP address and subnet mask, how much system memory the node has, but also which
+disk image to run. You can read more about the latter under
+:ref:`sec-howto-custom_image`.
+
+The :class:`~simbricks.orchestration.nodeconfig.NodeConfig` contains an
+attribute for an instance of
+:class:`~simbricks.orchestration.nodeconfig.AppConfig`, which defines the
+workload or the concrete commands that are executed on the node. You can also
+override :meth:`~simbricks.orchestration.nodeconfig.AppConfig.config_files` to
+specify additional files to be copied into the host. These are specified as key
+value pairs, where the key represents the path/filename inside the simulated
+guest system and the value is an IO handle of the file to be copied over.
 
 .. automodule:: simbricks.orchestration.nodeconfig
 
-  .. autoclass:: simbricks.orchestration.nodeconfig.NodeConfig
-    :members: ip, prefix, mtu, cores, memory, disk_image, app, run_cmds, cleanup_cmds, config_files 
-
-
-.. _sec-app-config:
-
-Application Configuration
--------------------------
-
-The class :class:`~simbricks.orchestration.nodeconfig.AppConfig` offers member
-functions to define the concrete commands to run on the node. It also provides a
-member function
-:meth:`~simbricks.orchestration.nodeconfig.AppConfig.config_files` to specify
-additional files to be made available on the host, which are specified as key
-value pairs, where the key represents the filename inside the simulated guest
-system and the value is an IO handle to the file on the host running the
-simulators.
+.. autoclass:: simbricks.orchestration.nodeconfig.NodeConfig
+  :members: ip, prefix, mtu, cores, memory, disk_image, app, run_cmds,
+    cleanup_cmds, config_files 
 
-  .. autoclass:: simbricks.orchestration.nodeconfig.AppConfig
-    :members: run_cmds, config_files
+.. autoclass:: simbricks.orchestration.nodeconfig.AppConfig
+  :members: run_cmds, config_files
 
 
 .. _sec-command-line:
@@ -153,9 +148,9 @@ practice, running experiments will look similar to this:
 
 .. code-block:: bash
 
-  $ python3.10 run.py --verbose --force pyexps/qemu_i40e_pair.py
+  $ python run.py --verbose --force pyexps/simple_ping.py
   # only available inside docker images
-  $ simbricks-run --verbose --force qemu_i40e_pair.py
+  $ simbricks-run --verbose --force pyexps/simple_ping.py
 
 Here are all the command line arguments for the ``experiments/run.py`` script: