run.py: improve help messages and documentation in orchestration.rst

doc/user/howto.rst

@@ -68,7 +68,7 @@ write.
 
 Finally, to run your experiment, invoke ``<repository>/experiments/run.py`` and
 provide the path to your experiment module. In our docker containers, you can
-just use the following command from anywhere:
+also just use the following command from anywhere:
 
 .. code-block:: bash
 

doc/user/orchestration.rst

@@ -150,34 +150,64 @@ Running Experiments
 Command Line
 ====================
 
-.. code-block:: bash
-
-   usage: simbricks-run [-h] [--filter PATTERN [PATTERN ...]] [--pickled] [--runs N]
-               [--firstrun N] [--force] [--verbose] [--pcap] [--repo DIR]
-               [--workdir DIR] [--outdir DIR] [--cpdir DIR] [--parallel]
-               [--cores N] [--mem N] [--slurm] [--slurmdir DIR]
-               EXP [EXP ...]
-
-Positional arguments
---------------------
+To run experiments using our orchestration framework, use the
+``experiments/run.py`` script. For your convenience, you can also use
+``simbricks-run`` in the Docker images from anywhere to run experiments. In
+practice, running experiments will look similar to this:
 
-   *  ``EXP``
-
-      An experiment file to run.
-
-Optional arguments
-------------------
+.. code-block:: bash
 
-   *  `` -h, --help``
+  $ python3.10 run.py --verbose --force pyexps/qemu_i40e_pair.py
+  # only available inside docker images
+  $ simbricks-run --verbose --force qemu_i40e_pair.py
 
-      show this help message and exit.
+Here are all the command line arguments for the ``experiments/run.py`` script:
 
-   * `` --filter PATTERN [PATTERN ...] ``
-      Pattern to match experiment names against
+.. code-block:: text
 
-Environment
------------
+  usage: run.py [-h] [--list] [--filter PATTERN [PATTERN ...]] [--pickled] [--runs N]
+                [--firstrun N] [--force] [--verbose] [--pcap] [--repo DIR] [--workdir DIR]
+                [--outdir DIR] [--cpdir DIR] [--hosts JSON_FILE] [--shmdir DIR]
+                [--parallel] [--cores N] [--mem N] [--slurm] [--slurmdir DIR] [--dist]
+                [--auto-dist] [--proxy-type TYPE]
+                EXP [EXP ...]
 
+  positional arguments:
+    EXP                   Python modules to load the experiments from
+
+  options:
+    -h, --help            show this help message and exit
+    --list                List available experiment names
+    --filter PATTERN [PATTERN ...]
+                          Only run experiments matching the given Unix shell style patterns
+    --pickled             Interpret experiment modules as pickled runs instead of .py files
+    --runs N              Number of repetition of each experiment
+    --firstrun N          ID for first run
+    --force               Run experiments even if output already exists (overwrites output)
+    --verbose             Verbose output, for example, print component simulators\' output
+    --pcap                Dump pcap file (if supported by component simulator)
+
+  Environment:
+    --repo DIR            SimBricks repository directory
+    --workdir DIR         Work directory base
+    --outdir DIR          Output directory base
+    --cpdir DIR           Checkpoint directory base
+    --hosts JSON_FILE     List of hosts to use (json)
+    --shmdir DIR          Shared memory directory base (workdir if not set)
+
+  Parallel Runtime:
+    --parallel            Use parallel instead of sequential runtime
+    --cores N             Number of cores to use for parallel runs
+    --mem N               Memory limit for parallel runs (in MB)
+
+  Slurm Runtime:
+    --slurm               Use slurm instead of sequential runtime
+    --slurmdir DIR        Slurm communication directory
+
+  Distributed Runtime:
+    --dist                Use sequential distributed runtime instead of local
+    --auto-dist           Automatically distribute non-distributed experiments
+    --proxy-type TYPE     Proxy type to use (sockets,rdma) for auto distribution
 
 ******************************
 Images

experiments/run.py

@@ -59,35 +59,35 @@ parser.add_argument(
     metavar='EXP',
     type=str,
     nargs='+',
-    help='An experiment file to run'
+    help='Python modules to load the experiments from'
 )
 parser.add_argument(
     '--list',
     action='store_const',
     const=True,
     default=False,
-    help='Only list available experiment names'
+    help='List available experiment names'
 )
 parser.add_argument(
     '--filter',
     metavar='PATTERN',
     type=str,
     nargs='+',
-    help='Pattern to match experiment names against'
+    help='Only run experiments matching the given Unix shell style patterns'
 )
 parser.add_argument(
     '--pickled',
     action='store_const',
     const=True,
     default=False,
-    help='Read exp files as pickled runs instead of exp.py files'
+    help='Interpret experiment modules as pickled runs instead of .py files'
 )
 parser.add_argument(
     '--runs',
     metavar='N',
     type=int,
     default=1,
-    help='Number of repetition for each experiment'
+    help='Number of repetition of each experiment'
 )
 parser.add_argument(
     '--firstrun', metavar='N', type=int, default=1, help='ID for first run'
@@ -97,26 +97,30 @@ parser.add_argument(
     action='store_const',
     const=True,
     default=False,
-    help='Run experiments even if output already exists'
+    help='Run experiments even if output already exists (overwrites output)'
 )
 parser.add_argument(
     '--verbose',
     action='store_const',
     const=True,
     default=False,
-    help='Verbose output'
+    help='Verbose output, for example, print component simulators\' output'
 )
 parser.add_argument(
     '--pcap',
     action='store_const',
     const=True,
     default=False,
-    help='Dump pcap file (if supported by simulator)'
+    help='Dump pcap file (if supported by component simulator)'
 )
 
 g_env = parser.add_argument_group('Environment')
 g_env.add_argument(
-    '--repo', metavar='DIR', type=str, default='..', help='Repo directory'
+    '--repo',
+    metavar='DIR',
+    type=str,
+    default='..',
+    help='SimBricks repository directory'
 )
 g_env.add_argument(
     '--workdir',