type the following on the command-line:
.. code-block:: shell
-
+
my_simulator --cfg=Item:Value (other arguments)
Several ``--cfg`` command line arguments can naturally be used. If you
file:
.. code-block:: xml
-
+
<config>
<prop id="Item" value="Value"/>
</config>
with :cpp:func:`simgrid::s4u::Engine::set_config` or :cpp:func:`MSG_config`.
.. code-block:: cpp
-
+
#include <simgrid/s4u.hpp>
int main(int argc, char *argv[]) {
simgrid::s4u::Engine e(&argc, argv);
-
+
e->set_config("Item:Value");
-
+
// Rest of your code
}
.. _options_list:
-
+
Existing Configuration Items
----------------------------
.. note::
The full list can be retrieved by passing ``--help`` and
- ``--help-cfg`` to an executable that uses SimGrid.
-
-- **clean-atexit:** :ref:`cfg=clean-atexit`
+ ``--help-cfg`` to an executable that uses SimGrid. Try passing
+ ``help`` as a value to get the list of values accepted by a given
+ option. For example, ``--cfg=plugin:help`` will give you the list
+ of plugins available in your installation of SimGrid.
- **contexts/factory:** :ref:`cfg=contexts/factory`
- **contexts/guard-size:** :ref:`cfg=contexts/guard-size`
- **cpu/model:** :ref:`options_model_select`
- **cpu/optim:** :ref:`Cpu Optimization Level <options_model_optim>`
+- **debug/breakpoint:** :ref:`cfg=debug/breakpoint`
+- **debug/clean-atexit:** :ref:`cfg=debug/clean-atexit`
+- **debug/verbose-exit:** :ref:`cfg=debug/verbose-exit`
+
- **exception/cutpath:** :ref:`cfg=exception/cutpath`
- **host/model:** :ref:`options_model_select`
- **model-check/hash:** :ref:`cfg=model-checker/hash`
- **model-check/max-depth:** :ref:`cfg=model-check/max-depth`
- **model-check/property:** :ref:`cfg=model-check/property`
-- **model-check/record:** :ref:`cfg=model-check/record`
- **model-check/reduction:** :ref:`cfg=model-check/reduction`
- **model-check/replay:** :ref:`cfg=model-check/replay`
- **model-check/send-determinism:** :ref:`cfg=model-check/send-determinism`
-- **model-check/sparse-checkpoint:** :ref:`cfg=model-check/sparse-checkpoint`
- **model-check/termination:** :ref:`cfg=model-check/termination`
- **model-check/timeout:** :ref:`cfg=model-check/timeout`
- **model-check/visited:** :ref:`cfg=model-check/visited`
- **path:** :ref:`cfg=path`
- **plugin:** :ref:`cfg=plugin`
-- **simix/breakpoint:** :ref:`cfg=simix/breakpoint`
-
- **storage/max_file_descriptors:** :ref:`cfg=storage/max_file_descriptors`
- **surf/precision:** :ref:`cfg=surf/precision`
- **Tracing configuration options** can be found in Section :ref:`tracing_tracing_options`
- **storage/model:** :ref:`options_model_select`
-- **verbose-exit:** :ref:`cfg=verbose-exit`
- **vm/model:** :ref:`options_model_select`
models for all existing resources.
- ``network/model``: specify the used network model. Possible values:
-
+
- **LV08 (default one):** Realistic network analytic model
(slow-start modeled by multiplying latency by 13.01, bandwidth by
.97; bottleneck sharing uses a payload of S=20537 for evaluating
RTT). Described in `Accuracy Study and Improvement of Network
Simulation in the SimGrid Framework
- <http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf>`_.
+ <http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf>`_.
- **Constant:** Simplistic network model where all communication
take a constant time (one second). This model provides the lowest
realism, but is (marginally) faster.
without corrective factors. The timings of small messages are thus
poorly modeled. This model is described in `A Network Model for
Simulation of Grid Application
- <ftp://ftp.ens-lyon.fr/pub/LIP/Rapports/RR/RR2002/RR2002-40.ps.gz>`_.
- - **Reno/Reno2/Vegas:** Models from Steven H. Low using lagrange_solve instead of
- lmm_solve (experts only; check the code for more info).
- - **NS3** (only available if you compiled SimGrid accordingly):
+ <https://hal.inria.fr/inria-00071989/document>`_.
+ - **ns-3** (only available if you compiled SimGrid accordingly):
Use the packet-level network
- simulators as network models (see :ref:`pls_ns3`).
+ simulators as network models (see :ref:`model_ns3`).
This model can be :ref:`further configured <options_pls>`.
-
+
- ``cpu/model``: specify the used CPU model. We have only one model
for now:
allow parallel tasks because these beasts need some collaboration
between the network and CPU model. That is why, ptask_07 is used by
default when using SimDag.
-
+
- **default:** Default host model. Currently, CPU:Cas01 and
network:LV08 (with cross traffic enabled)
- **compound:** Host model that is automatically chosen if
configurations.
- items ``network/optim`` and ``cpu/optim`` (both default to 'Lazy'):
-
+
- **Lazy:** Lazy action management (partial invalidation in lmm +
heap in action remaining).
- **TI:** Trace integration. Highly optimized mode when using
now).
- **Full:** Full update of remaining and variables. Slow but may be
useful when debugging.
-
+
- items ``network/maxmin-selective-update`` and
``cpu/maxmin-selective-update``: configure whether the underlying
should be lazily updated or not. It should have no impact on the
and you should use the last one, which is the maximal size.
.. code-block:: shell
-
+
cat /proc/sys/net/ipv4/tcp_rmem # gives the sender window
cat /proc/sys/net/ipv4/tcp_wmem # gives the receiver window
.. _cfg=network/bandwidth-factor:
.. _cfg=network/latency-factor:
.. _cfg=network/weight-S:
-
+
Correcting Important Network Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _options_pls:
-Configuring NS3
-^^^^^^^^^^^^^^^
+Configuring ns-3
+^^^^^^^^^^^^^^^^
-**Option** ``ns3/TcpModel`` **Default:** "default" (NS3 default)
+**Option** ``ns3/TcpModel`` **Default:** "default" (ns-3 default)
-When using NS3, there is an extra item ``ns3/TcpModel``, corresponding
+When using ns-3, there is an extra item ``ns3/TcpModel``, corresponding
to the ``ns3::TcpL4Protocol::SocketType`` configuration item in
-NS3. The only valid values (enforced on the SimGrid side) are
-'default' (no change to the NS3 configuration), 'NewReno' or 'Reno' or
+ns-3. The only valid values (enforced on the SimGrid side) are
+'default' (no change to the ns-3 configuration), 'NewReno' or 'Reno' or
'Tahoe'.
Configuring the Storage model
computations. More details in @ref plugin_energy.
- **link_energy:** keeps track of the energy dissipated by
communications. More details in @ref SURF_plugin_energy.
- - **host_load:** keeps track of the computational load.
+ - **host_load:** keeps track of the computational load.
More details in @ref plugin_load.
.. _options_modelchecking:
-
+
Configuring the Model-Checking
------------------------------
be executed using the simgrid-mc wrapper:
.. code-block:: shell
-
+
simgrid-mc ./my_program
Safety properties are expressed as assertions using the function
:cpp:func:`void MC_assert(int prop)`.
.. _cfg=model-check/property:
-
+
Specifying a liveness property
..............................
.. code-block:: shell
-
+
simgrid-mc ./my_program --cfg=model-check/property:<filename>
.. _cfg=model-check/checkpoint:
-
+
Going for Stateful Verification
...............................
communication determinism mode of the model-checker which checks
determinism properties of the communications of an application.
-.. _cfg=model-check/sparse-checkpoint:
-
-Incremental Checkpoints
-.......................
-
-When the model-checker is configured to take a snapshot of each
-explored state (with the ``model-checker/visited`` item), the memory
-consumption can rapidly reach GiB ou Tib of memory. However, for many
-workloads, the memory does not change much between different snapshots
-and taking a complete copy of each snapshot is a waste of memory.
-
-The ``model-check/sparse-checkpoint`` option item can be set to
-**yes** to avoid making a complete copy of each snapshot. Instead,
-each snapshot will be decomposed in blocks which will be stored
-separately. If multiple snapshots share the same block (or if the
-same block is used in the same snapshot), the same copy of the block
-will be shared leading to a reduction of the memory footprint.
-
-For many applications, this option considerably reduces the memory
-consumption. In somes cases, the model-checker might be slightly
-slower because of the time taken to manage the metadata about the
-blocks. In other cases however, this snapshotting strategy will be
-much faster by reducing the cache consumption. When the memory
-consumption is important, by avoiding to hit the swap or reducing the
-swap usage, this option might be much faster than the basic
-snapshotting strategy.
-
-This option is currently disabled by default.
-
Verification Performance Considerations
.......................................
consumption of the snapshots to be @f$ @mbox{number of processes}
@times @mbox{stack size} @times @mbox{number of states} @f$.
-The ``model-check/sparse-checkpoint`` can be used to reduce the memory
-consumption by trying to share memory between the different snapshots.
-
When compiled against the model checker, the stacks are not
protected with guards: if the stack size is too small for your
application, the stack will silently overflow on other parts of the
implementation was found to be buggy and this options is not as useful as
it could be. For this reason, it is currently disabled by default.
-.. _cfg=model-check/record:
.. _cfg=model-check/replay:
-Record/Replay of Verification
-.............................
+Replaying buggy execution paths out of the model-checker
+........................................................
-As the model-checker keeps jumping at different places in the execution graph,
-it is difficult to understand what happens when trying to debug an application
-under the model-checker. Event the output of the program is difficult to
-interpret. Moreover, the model-checker does not behave nicely with advanced
-debugging tools such as valgrind. For those reason, to identify a trajectory
-in the execution graph with the model-checker and replay this trajcetory and
-without the model-checker black-magic but with more standard tools
-(such as a debugger, valgrind, etc.). For this reason, Simgrid implements an
-experimental record/replay functionnality in order to record a trajectory with
-the model-checker and replay it without the model-checker.
+Debugging the problems reported by the model-checker is challenging: First, the
+application under verification cannot be debugged with gdb because the
+model-checker already traces it. Then, the model-checker may explore several
+execution paths before encountering the issue, making it very difficult to
+understand the outputs. Fortunately, SimGrid provides the execution path leading
+to any reported issue so that you can replay this path out of the model checker,
+enabling the usage of classical debugging tools.
When the model-checker finds an interesting path in the application
execution graph (where a safety or liveness property is violated), it
-can generate an identifier for this path. To enable this behavious the
-``model-check/record`` must be set to **yes**, which is not the case
-by default.
-
-Here is an example of output:
+generates an identifier for this path. Here is an example of output:
.. code-block:: shell
[ 0.000000] (0:@) *** PROPERTY NOT VALID ***
[ 0.000000] (0:@) **************************
[ 0.000000] (0:@) Counter-example execution trace:
+ [ 0.000000] (0:@) [(1)Tremblay (app)] MC_RANDOM(3)
+ [ 0.000000] (0:@) [(1)Tremblay (app)] MC_RANDOM(4)
[ 0.000000] (0:@) Path = 1/3;1/4
- [ 0.000000] (0:@) [(1)Tremblay (app)] MC_RANDOM(3)
- [ 0.000000] (0:@) [(1)Tremblay (app)] MC_RANDOM(4)
[ 0.000000] (0:@) Expanded states = 27
[ 0.000000] (0:@) Visited states = 68
[ 0.000000] (0:@) Executed transitions = 46
-This path can then be replayed outside of the model-checker (and even
-in non-MC build of simgrid) by setting the ``model-check/replay`` item
-to the given path. The other options should be the same (but the
-model-checker should be disabled).
-
-The format and meaning of the path may change between different
-releases so the same release of Simgrid should be used for the record
-phase and the replay phase.
+The interesting line is ``Path = 1/3;1/4``, which means that you should use
+`--cfg=model-check/replay:1/3;1/4`` to replay your application on the buggy
+execution path. The other options should be the same (but the model-checker
+should be disabled). Note that format and meaning of the path may change between
+different releases.
Configuring the User Code Virtualization
----------------------------------------
interrupted, and only gets released when the simulated clock reaches
the point where the blocking operation is done. This is explained
graphically in the `relevant tutorial, available online
-<http://simgrid.gforge.inria.fr/tutorials/simgrid-simix-101.pdf>`_.
+<https://simgrid.org/tutorials/simgrid-simix-101.pdf>`_.
In SimGrid, the containers in which user processes are virtualized are
called contexts. Several context factory are provided, and you can
raw implementation.
|br| Install the relevant library (e.g. with the
libboost-contexts-dev package on Debian/Ubuntu) and recompile
- SimGrid.
+ SimGrid.
- **raw:** amazingly fast factory using a context switching mechanism
of our own, directly implemented in assembly (only available for x86
and amd64 platforms for now) and without any unneeded system call.
.. _cfg=contexts/nthreads:
.. _cfg=contexts/parallel-threshold:
.. _cfg=contexts/synchro:
-
+
Running User Code in Parallel
.............................
your machine for no good reason. You probably prefer the other less
eager schemas.
-
Configuring the Tracing
-----------------------
- SMPI simulator and traces for a space/time view:
.. code-block:: shell
-
+
smpirun -trace ...
The `-trace` parameter for the smpirun script runs the simulation
- Add the contents of a textual file on top of the trace file as comment:
.. code-block:: shell
-
+
--cfg=tracing/comment-file:my_file_with_additional_information.txt
Please, use these two parameters (for comments) to make reproducible
application, the variable ``smpi/simulate-computation`` should be set
to no. This option just ignores the timings in your simulation; it
still executes the computations itself. If you want to stop SMPI from
-doing that, you should check the SMPI_SAMPLE macros, documented in
+doing that, you should check the SMPI_SAMPLE macros, documented in
Section :ref:`SMPI_adapting_speed`.
+------------------------------------+-------------------------+-----------------------------+
| Solution | Computations executed? | Computations simulated? |
-+====================================+=========================+=============================+
++====================================+=========================+=============================+
| --cfg=smpi/simulate-computation:no | Yes | Never |
+------------------------------------+-------------------------+-----------------------------+
| --cfg=smpi/cpu-threshold:42 | Yes, in all cases | If it lasts over 42 seconds |
bandwidth of the link).
An experimental script to compute these factors is available online. See
-http://simgrid.gforge.inria.fr/contrib/smpi-calibration-doc.html
-http://simgrid.gforge.inria.fr/contrib/smpi-saturation-doc.html
+https://framagit.org/simgrid/platform-calibration/
+https://simgrid.org/contrib/smpi-saturation-doc.html
.. _cfg=smpi/display-timing:
-
+
Reporting Simulation Time
.........................
increase the latency, i.e., values larger than or equal to 1 are valid here.
.. _cfg=smpi/papi-events:
-
+
Trace hardware counters with PAPI
.................................
files (See Section :ref:`tracing_tracing_options`).
.. warning::
-
+
This feature currently requires superuser privileges, as registers
are queried. Only use this feature with code you trust! Call
smpirun for instance via ``smpirun -wrapper "sudo "
use. Example:
.. code-block:: shell
-
+
ldd allpairf90
...
libgfortran.so.3 => /usr/lib/x86_64-linux-gnu/libgfortran.so.3 (0x00007fbb4d91b000)
Then, it can be deallocated by calling SMPI_SHARED_FREE(mem).
When smpi/shared-malloc:global is used, the memory consumption problem
-is solved, but it may induce too much load on the kernel's pages table.
+is solved, but it may induce too much load on the kernel's pages table.
In this case, you should use huge pages so that we create only one
entry per Mb of malloced data instead of one entry per 4k.
To activate this, you must mount a hugetlbfs on your system and allocate
at least one huge page:
.. code-block:: shell
-
+
mkdir /home/huge
sudo mount none /home/huge -t hugetlbfs -o rw,mode=0777
sudo sh -c 'echo 1 > /proc/sys/vm/nr_hugepages' # echo more if you need more
to issue if your application contains such a loop:
.. code-block:: cpp
-
+
while(MPI_Wtime() < some_time_bound) {
/* some tests, with no communication nor computation */
}
Other Configurations
--------------------
-.. _cfg=clean-atexit:
+.. _cfg=debug/clean-atexit:
Cleanup at Termination
......................
-**Option** ``clean-atexit`` **default:** on
+**Option** ``debug/clean-atexit`` **default:** on
If your code is segfaulting during its finalization, it may help to
disable this option to request SimGrid to not attempt any cleanups at
item. To add several directory to the path, set the configuration
item several times, as in ``--cfg=path:toto --cfg=path:tutu``
-.. _cfg=simix/breakpoint:
+.. _cfg=debug/breakpoint:
Set a Breakpoint
................
-**Option** ``simix/breakpoint`` **default:** unset
+**Option** ``debug/breakpoint`` **default:** unset
This configuration option sets a breakpoint: when the simulated clock
reaches the given time, a SIGTRAP is raised. This can be used to stop
set variable simgrid::simix::breakpoint = 3.1416
-.. _cfg=verbose-exit:
-
+.. _cfg=debug/verbose-exit:
+
Behavior on Ctrl-C
..................
-**Option** ``verbose-exit`` **default:** on
+**Option** ``debug/verbose-exit`` **default:** on
By default, when Ctrl-C is pressed, the status of all existing actors
is displayed before exiting the simulation. This is very useful to
