-Correcting Important Network Parameters
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-SimGrid can take network irregularities such as a slow startup or
-changing behavior depending on the message size into account. You
-should not change these values unless you really know what you're
-doing. The corresponding values were computed through data fitting
-one the timings of packet-level simulators, as described in `Accuracy
-Study and Improvement of Network Simulation in the SimGrid Framework
-<http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf>`_.
-
-- **network/latency-factor**: apply a multiplier to latency.
- Models the TCP slow-start mechanism.
-- **network/bandwidth-factor**: actual bandwidth perceived by the
- user.
-- **network/weight-S**: bottleneck sharing constant parameter. Used
- to calculate RTT.
-
-These parameters are the same for all communications in your simulation,
-independently of message size or source/destination hosts. A more flexible
-mechanism based on callbacks was introduced in SimGrid. It provides the user
-a callback that will be called for each communication, allowing the user
-to set different latency and bandwidth factors, based on the message size, links used
-or zones traversed. To more details of how to use it, please look at the
-`examples/cpp/network-factors/s4u-network-factors.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/cpp/network-factors/s4u-network-factors.cpp>`_.
-
-
-If you are using the SMPI model, these correction coefficients are
-themselves corrected by constant values depending on the size of the
-exchange. By default SMPI uses factors computed on the Stampede
-Supercomputer at TACC, with optimal deployment of processes on
-nodes. Again, only hardcore experts should bother about this fact.
-For more details, see SMPI sections about :ref:`cfg=smpi/bw-factor` and :ref:`cfg=smpi/lat-factor`.
+Manual calibration factors
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SimGrid can take network irregularities such as a slow startup or changing behavior depending on the message size into account.
+The values provided by default were computed a long time ago through data fitting one the timings of either packet-level simulators or direct
+experiments on real platforms. These default values should be OK for most users, but if simulation realism is really important to
+you, you probably want to recalibrate the models (i.e., devise sensible values for your specific settings). This section only
+describes how to pass new values to the models while the calibration process involved in the computation of these values is
+described :ref:`in the relevant chapter <models_calibration>`.
+
+We found out that many networking effects can be realistically accounted for with the three following correction factors. They were shown
+to be enough to capture slow-start effects, the different transmission modes of MPI systems (eager vs. rendez-vous mode), or the
+non linear effects of wifi sharing.
+
+**Option** ``network/latency-factor`` **Default:** 1.0, but overridden by most models
+
+This option specifies a multiplier to apply to the *physical* latency (i.e., the one described in the platform) of the set of links involved in a communication. The factor can either be a constant to apply to any
+communication, or it may depend on the message size. The ``CM02`` model does not use any correction factor, so the
+latency-factor remains to 1. The ``LV08`` model sets it to 13.01 to model slow-start, while the ``SMPI`` model has several
+possible values depending on the interval in which the message size falls. The default SMPI setting given below specifies for example that a message smaller than
+257 bytes will get a latency multiplier of 2.01467 while a message whose size is in [15424, 65472] will get a latency multiplier
+of 3.48845. The ``wifi`` model goes further and uses a callback in the program to compute the factor that must be non-linear in
+this case.
+
+This multiplier is applied to the latency computed from the platform, that is the sum of all link *physical* latencies over the :ref:`network path <platform_routing>` used by the considered communication, to derive the *effective* end-to-end latency.
+
+Constant factors are easy to express, but the interval-based syntax used in SMPI is somewhat complex. It expects a set of
+factors separated by semicolons, each of the form ``boundary:factor``. For example if your specification is
+``0:1;1000:2;5000:3``, it means that on [0, 1000) the factor is 1. On [1000,5000), the factor is 2 while the factor is 3 for
+5000 and beyond. If your first interval does include size=0, then the default value of 1 is used before. Changing the factor
+callback is not possible from the command line and must be done from your code, as shown in `this example
+<https://framagit.org/simgrid/simgrid/tree/master/examples/cpp/network-factors/s4u-network-factors.cpp>`_. Note that the chosen
+model only provide some default settings, not more. You can pick a ``LV08`` to get some of the settings, and override the latency
+with an interval-based value.