+This page focuses on the **performance models** that compute the duration of :ref:`all activities <S4U_main_concepts>`
+throughout the simulation, based on the platform characteristics and on the other activities that concurrently use the
+resources. If you are looking for information on other kinds of models (such as routing models or compute model), please refer to :ref:`the
+bottom of this page <models_other>`.
+
+Modeled resources
+*****************
+
+The primary objective of SimGrid is to provide simulated timing information
+for the usage of three kinds of resources: networks, CPUs, and disks.
+
+The **network models** have been improved and regularly validated for almost 20 years. It should be possible to get
+accurate simulations once you properly :ref:`calibrate the models for your settings<models_calibration>`. As detailed
+in the next sections, SimGrid provides several network models. Two plugins can also be used to compute the energy
+consumption of the network: one for :ref:`wired networks<plugin_link_energy>` and another one for :ref:`Wi-Fi networks
+<plugin_link_energy>`. Note that at first some users find the way in which SimGrid simulates :ref:`TCP performance<understanding_lv08>` to be
+counter-intuitive; in our experience this is due these users misunderstandings the (complex) behavior
+of TCP in real networks.
+
+The **CPU models** are less developed in SimGrid. Through the S4U API, the user can specify amounts of
+computational work (expressed in FLOPs, for floating point operations) that each computation "consumes", and the model
+simply divides this amount by a CPU's FLOP rate to compute the duration of the computation
+(accounting for number of cores and all concurrent computations with a time-sharing model). In SMPI, the user code
+is automatically timed, and the :ref:`computing speed<cfg=smpi/host-speed>` of the host machine is used to evaluate
+the corresponding amount of FLOPs. This model should be sufficient for most users, even though assuming a constant FLOP
+rate for each machine remains a crude simplification (in reality, the FLOP rate varies because of I/O, memory, and
+cache effects). It is possible to :ref:`overcome this simplification<cfg=smpi/comp-adjustment-file>`, but the
+required calibration process is rather intricate and not documented yet (feel free to
+:ref:`contact the community<community>`).
+In the future, more advanced models may be added but the existing model have proven good enough
+over the last two decades. The CPU energy consumption can be computed with the
+:ref:`relevant plugin<plugin_host_energy>`.
+
+The **disk models** in SimGrid have been included more recently than those for networks and CPUs, but they should
+still prove useful to most users. `Studies have shown <https://hal.inria.fr/hal-01197128>`_ that these models are sensitive
+to various conditions, and a :ref:`calibration process<howto_disk>` is provided. As usual, you probably want to
+assess simulation accuracy through an appropriate validation campaign.
+
+.. _models-lmm:
+
+LMM-based Models
+****************
+
+SimGrid aims at the sweet spot between simulation accuracy and simulation speed. In terms of accuracy, the goal is for simulations
+to report correct
+performance trends when comparing competing designs while placing minimal burden on the user. We also want to allow power users to
+fine tune the simulation models to achieve simulation results that are within 5% or less of what would be observed
+on a real platform. For example, we accurately determined the `speedup achieved by the Tibidabo ARM-based cluster <http://hal.inria.fr/hal-00919507>`_
+before it was even built. In terms of simulation speed, the goal it to be fast and scalable enough to allow the study of modern IT systems
+at scale. SimGrid was, for example, used to simulate `a Chord ring with millions of actors
+<https://hal.inria.fr/inria-00602216>`_ (even though results were not really more instructive than those obtained at smaller scales),
+or `a qualification run at full-scale of the Stampede supercomputer
+<https://hal.inria.fr/hal-02096571>`_.
+
+Most SimGrid models are based on a linear max-min solver (LMM), as depicted below. The actors' activities are
+represented by actions in the simulation kernel, accounting for both the initial amount of work of the corresponding
+activity (in FLOPs for CPU activities or bytes for network and disk activities), and the currently remaining
+amount of work to process.
+
+At each simulation step, the instantaneous speed for each action is computed according
+to the model. A set of constraints is used to express resource capacity constraints, i.e., that the cumulative instantaneous consumption of a
+given resource by a set actions must remain below the nominal capacity of that resource. In the example
+below, it is stated that the compute speed :math:`\varrho_1` of activity 1 plus the compute speed :math:`\varrho_n`
+of activity :math:`n`, which both run on host A, must remain smaller than that host's total compute speed :math:`C_A`.
+
+.. image:: img/lmm-overview.svg
+
+There are many valuations of :math:`\varrho_1, \ldots{}, \varrho_n` that must respect sets of constraints.
+SimGrid usually computes the instantaneous speeds according to a Max-Min objective function, that is, maximizing the
+minimum over all :math:`\varrho_i`. The coefficients associated to each variable in the inequalities are used to model
+some performance effects, such as the fact that TCP tends to favor communications with small RTTs. These coefficients
+are computed from both hard-coded values and :ref:`latency and bandwidth factors<cfg=network/latency-factor>` (more
+details on network performance modeling are given in the next section).
+
+Once the instantaneous speeds are computed for all acttions, the simulation kernel computes the earliest terminating action
+given their respective speeds and remaining amounts of work. The simulated time is then updated along with remaning
+amounts of work. At this point, some actions have no remaining work and are removed from the LMM. The corresponding activities thus terminate, which in turn
+unblocks the corresponding actors that can then continue executing.
+
+Most of the SimGrid models build upon the LMM solver, which they adapt and configure in various ways. For CPU
+and disk activities, the LMM-based models are respectively named **Cas01** and **S19**. The existing network models are
+described in the next section.
+
+.. _models_TCP:
+
+The TCP models
+**************
+
+SimGrid provides several network performance models that compute the time taken by each communication in isolation.
+**CM02** is the simplest one. It captures TCP windowing effects, but does not introduce any correction factors. This
+model should be used if you prefer human-understandable results over realistic ones. **LV08** (the default model) uses
+constant factors that are intended to capture common effects such as slow-start, the fact that TCP headers reduce the
+*effective* bandwidth, or TCP's ACK messages. **SMPI** uses more advanced factors that also capture the MPI-specific
+effects such as the switch between the eager vs. rendez-vous communication modes. You can :ref:`choose the
+model <options_model_select>` on via command-line arguments, and each model can be :ref:`further configured <options_model>`.
+
+The LMM solver is then used as described above to compute the effect of contention on the communication time when using TCP.
+For the sake of realism, the sharing on saturated links is not necessarily a fair sharing
+(unless when ``weight-S=0``, in which case the following mechanism is disabled).
+Instead, flows receive an amount of bandwidth inversely proportional to their round trip time. This is modeled
+in the LMM as a priority that depends on the :ref:`weight-S <cfg=network/weight-S>` parameter. More precisely, this
+priority is computed for each flow as :math:`\displaystyle\sum_{l\in links}\left(Lat(l)+\frac{weightS}{Bandwidth(l)}\right)`, i.e., as the sum of the
+latencies of all links traversed by the communication, plus the sum of `weight-S` over the bandwidth of each link along
+the path. This dependency on the link bandwidths is for the model to account for the TCP protocol's reactivity.
+
+Regardless of the TCP model in used, the latency is paid beforehand. It is as if the communication only starts after a
+small delay that corresponds to the end-to-end latency. During that time, the communication has no impact on the links (i.e., the other
+communications are not slowed down, because there is no contention yet).
+
+As an alternative to the above LMM-based models, it is possible to use the :ref:`ns-3 simulator as a network model <models_ns3>`. ns-3 performs
+a much more detailed, packet-level simulation
+than the above models. As a result is is much slower but will produce more accurate results.
+Both simulators have time complexity that is linear in the size of their input, but ns-3 has a much larger input in case of large communications
+because it considers individual network packets.
+However, the above SimGrid models must be carefully :ref:`calibrated <models_calibration>` if
+achieve very high accuracy is needed, while ns-3 is less demanding in this regard.
+
+.. _understanding_cm02:
+
+CM02
+====
+
+This is a simple model of TCP performance, where the sender stops sending packets when its TCP window is full. If the
+acknowledgment packets are returned in time to the sender, the TCP window has no impact on the performance, which is then
+only limited by link bandwidths. Otherwise, late acknowledgments will reduce the data transfer rate.
+
+SimGrid models this mechanism as follows: :math:`real\_BW = min(physical\_BW, \frac{TCP\_GAMMA}{2\times latency})` The used
+bandwidth is either the physical bandwidth that is configured in the platform, or a value that represents a bandwidth
+limit due to late acknowledgments. This value is the maximal TCP window size (noted TCP Gamma in SimGrid) divided by the
+round-trip time (i.e. twice the one-way latency). The default value of TCP Gamma is 4194304. This value can be changed with
+the :ref:`network/TCP-gamma <cfg=network/TCP-gamma>` configuration item.
+
+If you want to disable this mechanism altogether (e.g.,to model UDP or memory operations), you should set TCP-gamma
+to 0. Otherwise, the time it takes to send 10 Gib of data over a 10 Gib/s link that is otherwise unused is computed as
+:math:`latency + \frac{size}{bandwidth}`, but the bandwidth in the denominator may be the physical
+one (10Gb/s) or the one induced by the TCP window, depending on the latency:
+
+ - If the link latency is 0, the communication, expectedly, takes one second.
+ - If the link latency is 0.00001s, :math:`\frac{gamma}{2\times lat}=209,715,200,000 \approx 209Gib/s` which is larger than the
+ physical bandwidth. So the physical bandwidth is used (the link is fully utilized) and the communication takes 1.00001s
+ - If the link latency is 0.001s, :math:`\frac{gamma}{2\times lat}=2,097,152,000 \approx 2Gib/s`, which is smaller than the
+ physical bandwidth. The communication thus fails to fully utilize the link and takes about 4.77s.
+ - With a link latency of 0.1s, :math:`gamma/2\times lat \approx 21Mb/s`, so the communication takes about 476.84 + 0.1 seconds!
+ - More cases are tested and their validity checked by the test ``teshsuite/models/cm02-tcpgamma/cm02-tcpgamma.tesh`` in our test suite.
+
+For more details, please refer to "A Network Model for Simulation of Grid Application" by Henri Casanova and Loris
+Marchal (published in 2002, hence the model name).