23.2. Error Model

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.

23.2.1. 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.

23.2.1.1. Design

Error models are ns-3 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.

23.2.1.2. 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 ns-3 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.

23.2.1.3. References

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

23.2.2. 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 ns-3 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

23.2.2.1. Helpers

This model is typically not used with helpers.

23.2.2.2. 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.

23.2.2.3. Troubleshooting

No known issues.

23.2.3. 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.

23.2.4. Acknowledgements

The basic ErrorModel, RateErrorModel, and ListErrorModel classes were ported from ns-2 to ns-3 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.