TMgen: Traffic matrix generation tool¶

TMgen is a python library designed to easily generate network traffic matrices. The library supports a number of TM models, export to a number of cross-language formats, and very basic visualization tools.

Quickstart¶

This document oulitnes how to easily start using the TMgen tool.

Download and installation¶

Using pip¶

pip install tmgen

From source¶

Clone

git clone https://github.com/progwriter/tmgen

Install using pip in development mode
```
cd tmgen
pip install -e .
```

Example usage¶

TMgen defines a TrafficMatrix object that is returned by all generator functions. Internally it contains a 3-d numpy array which contains volume of traffic between origin-destination pairs for different time epochs. For TM models that do not have a time component, the third dimension is of size 1.

Quick overview on how to use them is given here, for full details please see the TMgen API

Generating a traffic matrix¶

Lets generate a uniform traffic matrix for a network with 3 nodes:

>>> from tmgen.models import uniform_tm
>>> tm = uniform_tm(3, 100, 300)
>>> print(tm) 
array([[[...

...

...]]])

This gives us a 3x3x1 array with values between 100 and 300 — volume for each node pair, with only one time epoch.

Accessing tm entries¶

TMgen gives you a number of ways to access the TM values. Lets generate an exponential TM with the mean volume of 500 and 2 time epochs.

>>> from tmgen.models import exp_tm
>>> tm = exp_tm(3, 500, 2)

Accessing the matrix attrbute gives us the underlying Numpy array:

>>> tm.matrix 
array([[[...

...

...]]])

Also we can request a traffic matrix at a specific epoch (0-indexed):

>>> tm.at_time(1) 
array([[...]])

Or the values between any node pair, with a particular aggregation metric:

>>> tm.between(0,2,'all') 
array([...])
>>> tm.between(0,2,'max') 
>>> tm.between(0,2,'mean') 

See TMgen API for all supported functions.

Saving/Loading a traffic matrix¶

TMs can be easily loaded using the python-native pickle format:

>>> from tmgen import TrafficMatrix
>>> tm.to_pickle('mytm')
>>> tm = TrafficMatrix.from_pickle('mytm')

TMgen API¶

Generators¶

tmgen.models.modulated_gravity_tm()¶

Generate a modulated gravity traffic matrix with the given parameters

Parameters:

num_nodes – number of Points-of-Presence (i.e., origin-destination pairs)
num_tms – total number of traffic matrices to generate (i.e., time epochs)
mean_traffic – the average total volume of traffic
pm_ratio – peak-to-mean ratio. Peak traffic will be larger by this much (must be bigger than 1). Default is 1.5
t_ratio – trough-to-mean ratio. Default is 0.75
diurnal_freq – Frequency of modulation. Default is 1/24 (i.e., hourly) if you are generating multi-day TMs
spatial_variance – Variance on the volume of traffic between origin-destination pairs. Pick something reasonable with respect to your mean_traffic. Default is 100
temporal_variance – Variance on the volume in time

Returns:

tmgen.models.random_gravity_tm()¶

Random gravity model, parametrized by the mean traffic per ingress-egress pair. See http://dl.acm.org/citation.cfm?id=1096551 for full description

Parameters:	num_nodes – number of nodes in the network mean_traffic – average traffic volume between a pair of nodes
Returns:	a new `TrafficMatrix`

tmgen.models.gravity_tm()¶

Compute the gravity traffic matrix, based on node populations (sizes). The TM will have no randomness and only contains one epoch.

..note::: A possible way of generating populations is to sample from a log-normal distribution

Parameters:	populations – array/list with populations (weights) for each node total_traffic – total volume of traffic in the network (will be divided among all ingres-egress pairs)
Returns:	a new `TrafficMatrix`

tmgen.models.uniform_tm()¶

Return a uniform traffic matrix. Entries are chosen independently from each other, uniformly at random, between given values of low and high.

Parameters:	num_nodes – number of points-of-presence low – lowest allowed value high – highest allowed value num_epochs – number of
Returns:	TrafficMatrix object

tmgen.models.exp_tm()¶

Exponential traffic matrix. Values are drawn from an exponential distribution, with a mean value of mean_traffic.

Parameters:	num_nodes – number of nodes in the network mean_traffic – mean value of the distribution num_epochs – number of epochs in the traffic matrix
Returns:	TrafficMatrix object

tmgen.models.spike_tm()¶

Generate a traffic matrix using the spike model.

Parameters:	num_nodes – number of nodes in the network num_spikes – number of ingress-egress spikes. Must be fewer than \(numpops^2\) mean_spike – average volume of a single spike num_epochs – number of time epochs
Returns:	TrafficMatrix object

tmgen.models.exact_tm()¶

Create a traffic matrix where each value has exact value val.

Mostly used for unit tests when exact values are needed to check the solution, unlikely to be needed in practice.

Parameters:	num_nodes – number of nodes in the network val – the value to use for each entry num_epochs – number of epochs
Returns:	a new TrafficMatrix object

TrafficMatrix instance¶

class tmgen.TrafficMatrix¶

Represents a traffic matrix.

at_time()¶

Return a numpy array reprenseting a single TM at epoch t.

Parameters:	t – the number of the epoch (0-indexed).
Return type:	numpy array

between()¶

Return the traffic matrix between the given ingress and egress nodes. This method supports multiple temporal modes: ‘all’, ‘min’, ‘max’, and ‘mean’

Parameters:	o – source node (origin) d – destination node modestr – temporal mode
Returns:	Numpy array if modestr==’all’, double otherwise

static from_pickle()¶

Load a TrafficMatrix object from a file

Parameters:	fname – the file name on disk
Returns:	new TrafficMatrix

mean()¶: Returns a new traffic matrix that is the average across all epochs.

num_epochs()¶

Returns:	The number of epochs in this traffic matrix

num_nodes()¶

Returns:	The number of nodes in this traffic matrix

to_csv()¶: Save the matrix to a CSV file.

to_pickle()¶

Save the matrix to a python pickle file

Parameters:	fname – the file name

worst_case()¶

Return a new, single-epoch traffic matrix that chooses maximum volume per OD pair (in time)

Returns:	a new TrafficMatrix