Error Model
-----------
.. include:: replace.txt

.. heading hierarchy:
   ------------- Chapter
   ************* Section (#.#)
   ============= Subsection (#.#.#)
   ############# Paragraph (no number)

This section documents a few error model objects, typically associated with
NetDevice models, that are maintained as part of the ``network`` module:

* RateErrorModel
* ListErrorModel
* ReceiveListErrorModel
* BurstErrorModel
* BinaryErrorModel

Error models are used to indicate that a packet should be considered to
be errored, according to the underlying (possibly stochastic or
empirical) error model.

Model Description
*****************

The source code for error models live in the directory ``src/network/utils``.

Two types of error models are generally provided.  The first are stochastic
models.  In this case, packets are errored according to underlying
random variable distributions.  An example of this is the ``RateErrorModel``.

The ``ns3::RateErrorModel`` errors packets according to an underlying
random variable distribution, which is by default a UniformRandomVariable
distributed between 0.0 and 1.0.  The error rate and error units (bit,
byte, or packet) are set by the user.  For instance, by setting ErrorRate
to 0.1 and ErrorUnit to "Packet", in the long run, around 10% of the
packets will be lost.

Another stochastic error model is the ``BurstErrorModel`` which allows
configuration of (random) burst error drop patterns.

The other type of model is a deterministic model, in which
packets are errored according to a particular prescribed pattern.
An example is the ``ListErrorModel`` that allows users to specify
the list of packets to be errored, by listing the specific packet UIDs.
A variant of the ``ListErrorModel``, the ``ReceiveListErrorModel``, allows
users to list packets to be errored by the order of their arrivals (without
regard to their UIDs).
The ``BinaryErrorModel`` alternates between errored and error-free packets.

Design
======

Error models are |ns3| objects and can be created using the typical
pattern of ``CreateObject<>()``.  They have configuration attributes.

An ErrorModel can be applied anywhere, but are commonly deployed on
NetDevice models so that artificial losses (mimicking channel losses)
can be induced.

Scope and Limitations
=====================

No known limitations.  There are no existing models that try to modify
the packet contents (e.g. apply bit or byte errors to the byte buffers).
This type of operation will likely be performance-expensive, and existing
Packet APIs may not easily support it.

Most |ns3| wireless models have their own technology-specific error models
and do not typically use these packet error models, although some (e.g.,
Wi-Fi) support the addition of ``ErrorModel`` as an optional model.

References
==========

The initial |ns3| error models were ported from ns-2 (queue/errmodel.{cc,h})

Usage
*****

The base class API is as follows:

* ``bool ErrorModel::IsCorrupt (Ptr<Packet> pkt)``:  Evaluate the packet and
  return true or false whether the packet should be considered errored or not.
  Some models could potentially alter the contents of the packet bit buffer.
* ``void ErrorModel::Reset ()``:  Reset any state.
* ``void ErrorModel::Enable ()``:  Enable the model
* ``void ErrorModel::Disable ()``:  Disable the model; IsCorrupt() will
  always return false.
* ``bool ErrorModel::IsEnabled () const``:  Return the enabled state

Several |ns3| NetDevices contain attributes holding pointers to error
models.  The error model is applied in the notional physical layer
processing chain of the device, and drops should show up on the ``PhyRxDrop``
trace source of the device.  The following are known to include an attribute
with a pointer available to hold this type of error model:

* ``SimpleNetDevice``
* ``PointToPointNetDevice``
* ``CsmaNetDevice``
* ``VirtualNetDevice``

However, the ErrorModel could be used anywhere where packets are used

Helpers
=======

This model is typically not used with helpers.

Examples
========

Error models are used in the tutorial ``fifth`` and ``sixth`` programs.

The directory ``examples/error-model/`` contains an example
``simple-error-model.cc`` that exercises the Rate and List error models.

Troubleshooting
===============

No known issues.

Validation
**********

The ``error-model`` unit test suite provides a single test case of
of a particular combination of ErrorRate and ErrorUnit for the
``RateErrorModel`` applied to a ``SimpleNetDevice``.

Acknowledgements
****************

The basic ErrorModel, RateErrorModel, and ListErrorModel classes were ported
from |ns2| to |ns3| in 2007.  The ReceiveListErrorModel was added at that
time.

The burst error model is due to Truc Anh N. Nguyen at the University of
Kansas (James P.G. Sterbenz <jpgs@ittc.ku.edu>, director, ResiliNets
Research Group (https://resilinets.org/), Information and
Telecommunication Technology Center (ITTC) and Department of Electrical
Engineering and Computer Science, The University of Kansas Lawrence, KS USA).
Work supported in part by NSF FIND (Future Internet Design) Program
under grant CNS-0626918 (Postmodern Internet Architecture),
NSF grant CNS-1050226 (Multilayer Network Resilience Analysis and
Experimentation on GENI), US Department of Defense (DoD), and ITTC at
The University of Kansas.
