Net2Plan User’s Guide

Version 0.3.1 - November 23, 2015

1 Description of the document

2 What is Net2Plan?

• Offline network design: Targeted to evaluate the network designs generated by built-in or user-defined offline network design algorithms, deciding on aspects such as the network topology, the traffic routing, link capacities, protection routes and so on. If needed, those algorithms based on constrained optimization formulations (i.e. ILPs) can be fast-prototyped using the open-source Java Optimization Modeler library (JOM [1]), to interface to a number of external solvers such as GPLK, CPLEX or IPOPT.
• Traffic matrix generation: Assists users in the process of generating, normalizing and manipulating traffic matrices. Traffic matrix generation can be automated following several random models found in the literature, gravity model, etc. Traffic matrices can be normalized in different forms, e.g. so that the new matrices match a particular value of traffic in the nodes, or becomes an upper bound to the traffic a given network can carry In addition, it is possible to manually edit or automatically create variations to seminal traffic matrices (e.g. random variations, traffic forecasts according to compound-annual growths...).
• Online simulation: Permits the (joint) evaluation of network recovery schemes, connection-admission-control (CAC) systems, or dynamic provisioning algorithms for time-varying traffic. At the end of the simulation, some metrics (including either predefined metrics or custom ones) are presented.
• Reporting: Net2Plan permits the generation of built-in or user-defined reports, from any network design. The report generation tool is integrated within all the previous functionalities, so that it is possible to create reports collecting performance measures in any of these aspects.

2.1 Why should I use Net2Plan?

Figure 2.1 Workflow

3 Network model in Net2Plan

3.1 Network representation

3.1.1 Network

3.1.2 Layers

3.1.3 Nodes

3.1.4 Links

3.1.5 Traffic demands

Figure 3.1 Ambiguity in traffic matrices

3.1.6 Routing

3.1.6.1 Source routing

• If a protection segment is associated to one single route, we model the so-called dedicated protection: the reserved bandwidth in that segment can only be used if the (primary) route fails. If a protection segment is associated to more than one routes, we are modeling a shared protection scheme.
• If the reserved bandwidth of a protection segment is below the carried traffic by the primary route, you are modeling a partial-protection scheme.
• If a protection segment shares the origin and destination nodes of the route, you are modeling a path-protection scheme. If only shares the origin and destination nodes of a link in the network, you are modeling a link-protection scheme. Otherwise, it is the subpath-protection scheme.

3.1.6.2 Hop-by-hop routing

3.1.7 Shared-risk groups

3.1.8 Failure modeling

3.1.8.1 Failure modeling in multilayer networks

3.1.9 Technology-specific representation

3.1.10 Quick reference card

3.2 Integration of users’ code

• Algorithms for offline network design should implement the interface com.net2plan.interfaces.networkDesign.IAlgorithm.
• Reports should implement the interface com.net2plan.interfaces.networkDesign.IReport
• Reaction algorithms that react to network events (e.g., used in the online simulation tool, and some reports), should implement the interface com.net2plan.interfaces.simulation.IEventProcessor Modules that generate events to be consumed by reaction algorithms should implement the com.net2plan.interfaces.simulation.IEventGenerator interface.

3.2.1 Net2Plan Library, Built-in Examples and Code Repository

• Input/Output interfaces: Provides a set of classes and interfaces for the different tools: offline network design, reporting and simulators.
• Libraries: Provides a set of useful libraries to develop algorithms and reports (i.e. to compute candidate path list, graph metrics...)
• Utils: General utility static methods for Java language (i.e. methods to work with int/double arrays)

3.2.2 JOM: Java Optimization Modeler

3.2.3 Preparing a Java IDE for Net2Plan programming

4 Installation guide, system requirements and starting Net2Plan

4.1 Directory structure

5 Using Net2Plan

Figure 5.1 Welcome screen

• File menu: Provides access to general configuration and debugging functionalities
• Tools menu: Provides access to the set of applications developed for Net2Plan: Offline network design, Traffic generation, and Online simulator
• Help menu: Provides access to the help documentation of Net2Plan and return to the welcome (about) screen

Figure 5.2 Main menu

5.1 Getting started

5.1.1 File menu

5.1.1.1 Options

• precisionFactor: Precision factor for checks to overcome numeric errors. Default: 1e-3. This parameter allows considering in the kernel small tolerances in the sanity-checks of the network designs. It avoids situations in which numerical inaccuracies (e.g. caused by finite precision of the solvers) would be interpreted as errors. For instance, if an algorithm returns a design where the traffic carried by a link is 10.0000001 and link capacity is 10, the kernel may show a warning. The precision factor applies since the actual check performed has a margin given by the precision factor. Default value of precisionFactor is $10^{-3}$ , and its value is constrained to be in range (0,1).
• defaultRunnableCodePath: Default path that will be used by tools in the GUI as the first option to load external code (i.e. algorithms). It can be either a .jar file or a folder. Default value is the BuiltInExamples.jar included within Net2Plan.

• defaultILPSolver: Default solver to be used for solving Linear Programs (LP) or Mixed Integer Linear Programs (MILP). Default: glpk.
• defaultNLPSolver: Default solver to be used for solving Non-Linear Programs (NLP). Default: ipopt.
• cplexSolverLibraryName: Default path for cplex library (.dll/.so file). Default: None
• glpkSolverLibraryName: Default path for glpk library (.dll/.so file). Default: None
• ipoptSolverLibraryName: Default path for ipopt library (.dll/.so file). Default: None

Figure 5.3 Options

5.1.1.2 Classpath editor

Figure 5.4 Classpath editor

5.1.1.3 Java error console

Figure 5.5 Error console

5.1.1.4 Exit

5.1.2 Tools menu

5.1.3 Help menu

5.1.3.1 About

5.1.3.2 User’s guide

5.1.3.3 Library API Javadoc

5.1.3.4 Examples in website

5.1.3.5 Show tool key combinations

Figure 5.6 Key combinations for the offline network design tool

5.2 Offline network design

• Topology Assignment (TA): Decides on the nodes and/or links in the network.
• Capacity Assignment (CA): Decides on the capacities in the links are decision variables to optimize.
• Flow Assignment (FA): Decide on the routing of the traffic demands over the network links .
• Bandwidth Assignment (BA): Decide on the traffic volume to be carried by each demand

Figure 5.7 Network design window

5.2.1 Network topology

Figure 5.8 Inserting a node

Figure 5.9 Inserting a link graphically

Figure 5.10 Inserting a link using a popup menu

• First button loads a network design from a .n2p file. Loaded design becomes the current network design, previous design is lost.
• Second button loads a .n2p file, but only extracting the set of offered demands from it (ignoring any other information). The loaded traffic demands replace the set of demands in the current network design, and leaves unchanged the rest of the current network design. Typically, the loaded file was generated using the Traffic matrix design functionality. If the number of nodes in the loaded file and the current network design are different, the operation is not completed and an error message is shown.
• Third button saves current design into a .n2p file.
• Fourth and fifth buttons are devoted to zoom-in and zoom-out, respectively, whereas the sixth one is to zoom-all.
• Seventh button allows to take a snapshot of the canvas and save it to a .png file.
• Eighth button toggles between showing or not node name.
• Ninth button toggles between showing or not link identifiers.
• Tenth button toggles between showing or not non-connected nodes.
• Next buttons are used to increase/decrease node and font sizes, to enhance visualization.
• Finally, the Reset button erases the current network design, which becomes an empty design

5.2.2 Warnings

5.2.3 View/edit network state

Figure 5.11 Edit network plan tab

• Network
  This tab shows statistical information describing the current network design at a network level (see Section 3.1.1↑).
  • Name, Description and Attributes: Shows the network name, description message, and set of user-defined key-value parameters associated to the Network element in the design. Right-clicking in the Parameters panel pemits adding/removing/editing attributes.
  • Number of layers, nodes and SRGs: These three (read-only) fields indicate the number of these elements in the network.
  • Layer information: This panel shows basic information about all the layers in the network such as name, description, link and demand units, attributes, and number of items for each layer-dependent element (links, demands, and so on). Here users can add/remove layers by right clicking on the table and using the corresponding option.
• Layer
  This tab shows statistical information describing the current network design at a layer level (see Section 3.1.2↑).
  • Name, Description, Link capacity units name, Demand traffic units name and Attributes: Shows the layer name, description message, link and capacity units, and set of user-defined key-value parameters associated to the Layer element in the design. Right-clicking in the Parameters panel pemits adding/removing/editing attributes.
  • Routing type: Allows setting the routing type of the layer between source routing and hop-by-hop routing. Note that users may change between them, and the kernel automatically will translate a routing into the other one. Source routing can be always translated into hop-by-hop routing. However, the other situation is not always possible. If forwarding rules are bad defined, i.e. traffic gets trapped into a loop, their equivalent routes cannot be found.
  • Topology and link capacities: This panels shows information characterizing the topology of nodes and links. The total number of nodes and links is just a count of these quantities. The maximum, minimum and average node out-degree is the max/min/average number of outgoing links of a node. The network diameter is the maximum shortest path distance between any node pair, where the distance is measured in hops, km and miliseconds. The link length in km is obtained from the NetPlan object (getLinkLengthInKm() method). The link propagation delay in seconds, converted to miliseconds later on, is obtained from the NetPlan object (getLinkPropagationDelayInSeconds() method). The conversion from km to miliseconds applies the propagationSpeedInKmPerSecond attribute of the link (getLinkPropagationSpeedInKmPerSecond() method) parameter. The total capacity installed sums the capacities in all the links (as they are stored in NetPlan object).
  • Traffic: This panel shows information characterizing the offered and (if exists) carried traffic in the network. If current design has no offered traffic, this panel is empty. The number of demands is just a count of this quantity. The total offered traffic sums the demand volumes. The average traffic per node pair divides the previous quantities by $N(N-1)$ being $N$ the number of nodes in the network. The “is symmetric” field indicates whether or not the offered traffic is symmetric: if for every demand from node A to node B, exists a demand from B to A with the same volume. The percentage of blocked traffic is the fraction of the offered traffic that is not routed.
  • Routing: This panel shows information characterizing the routing of the traffic, and is empty if the design contains no routes. The number of routes is just a count of the number of route entries in the NetPlan object. The routing is qualified as bifurcated if at least one demand has two associated routed carrying traffic. Network congestion value with reserved bandwidth is the highest ratio between the occupied bandwidth (summing carried traffic and reserved bandwidth by protection segments) and the link bandwidth, among all the network links. The value without reserved bandwidth does not consider the bandwidth occupied by the protection segments. If the design has no protection segments, both values are equal. The average route length is the sum of the route distance (in number of hops, km or miliseconds) weighted by the fraction of the route carried traffic respect to the total amount of carried traffic in the network. Its meaning is the average distance followed by a fraction of traffic (e.g. a packet in packet-switched networks), chosen randomly. The field “Routing has loops?” prints “no” if all the routes are loopless (do not traverse any node more than once), and prints “yes” otherwise. In hop-by-hop routing, only network congestion and routing loops information are shown.
  • Resilience information (only source routing): This panel shows information that characterize the protection scheme defined in the design. The number of protection segments field is just a count of the number of protection segment entries in the NetPlan object. The average link capacity reserved for protection in % sums the reserved bandwidth by the protection segments among all the links, and divides it by the total capacity installed in the network links. The three next fields show the type of protection that receive the carried traffic. These percentages are computed as follows. Let a route $p$ have a carried traffic of $x_p$ . If the route has no associated protection segment, then the amount $x_p$ is considered unprotected traffic. If $p$ has one protection segment associated with a reserved bandwidth of at least $x_p$ , so that this segment is not associated to any other route, then the amount $x_p$ is considered a traffic with complete and dedicated protection. If $p$ does not fit into the previous definitions, $x_p$ sums as a traffic with partial and/or shared protection. The number of SRGs is a count of the number of SRGs defined in the NetPlan object. SRG definition characteristic observes if the SRGs defined follow one of some typical arrangements: one SRG per node, one SRG per unidirectional link, one SRG per unidirectional link bundle (all the links in the same direction together), one SRG per bidirectional link bundle (all the links between a node pair in the same SRG), or none. Finally, the % of routes protected (from the total defined routing, irrespective of the carried traffic) with SRG disjoint segments.
  

  Figure 5.12 Layer view
• Nodes
  This sub-tab shows the information related to network nodes (see Section 3.1.3↑). Clicking on each node highlights it in the left panel. Right-clicking in the panel provides several options as adding or removing nodes. Node Id is a serial number starting from 0 identifying the node. Node name, a user-defined string. xCoord and yCoord are the node X and Y coordinates to plot them in a map. Ingress and egress traffic is the sum of the carried traffic incoming to and outgoing from the node respectively. Traversing traffic is the carried traffic that enter the node, but is not targeted to it. The total traffic is the sum of previous three quantities. SRGs are the SRG identifiers that include the node. Finally, the last column shows the user-defined key-value attributes attached to the node. The two additional options allows showing/hiding the nodes and setting them as up/down, respectively. Note that the Show non-connected nodes option, when disabled, has priority over the setting in the Nodes tab. The up/down option allows users to play with the network to see the effect, in terms of traffic losses, of a failure. We would like to remark, as mentioned in Section 3.1.8↑, that the network does not react to failures i.e. rerouting traffic, and this can be done by algorithms. When nodes are again up, all associated routing is restored. Nodes in down state are highlighted in red in the topology view.
  

  Figure 5.13 Nodes view
• Links
  This tab shows the information related to network links (see Section 3.1.4↑). Clicking on each link highlights it in the left panel (only if its node is not hidden). Link Id is a serial number starting from identifying the link. Link origin and destination nodes are the node identifiers of the link ends. Link capacity column shown the link capacity. Carried traffic sums the total amount of bandwidth that is occupied by the carried traffic of the routes traversing the link. Reserved for protection sums the total amount of bandwidth reserved by the protection segments traversing the link. Utilization is the fraction of link capacity occupied by the carried traffic plus the reserved for protection. Link length in km is the lengh of the link. Commonly, this value is equal to the euclidean distance between the link end nodes, but any other non-negative value could be stored. The number of routes counts the number of routes that traverse the link. The check box Is bottleneck is checked in the link (or links) that have the highest utilization in the network. Finally, the last column shows the user-defined key-value attributes attached to the link. The fields capacity, length and attributes are directly editable by the user in this panel. Right-clicking in the panel provides several options as adding or removing links, or setting the same attribute to all the links. Again, there are two options to play with link visibility and up/down state, where the same rationale than for the nodes applies.
  

  Figure 5.14 Links view
• Demands
  This sub-tab shows the information related to traffic demands (see Section 3.1.5↑). Clicking on each demand highlights its associated ingress and egress nodes in the left panel. Demand Id is a serial number starting from 0 identifying the traffic demand. Ingress node and Egress node are the initial and ending nodes of the demand. The offered traffic is the traffic volume offered, while the carried traffic is the amount actually carried by the routes associated to the demand. Lost traffic is the percentage of the offered traffic that is not carried. Note that if the demand has no associated routes, 100% of the offered traffic is lost. The column Bifurcated shows a “yes” is the demand routing is bifurcated i.e. the demand has two or more associated routes with carried traffic. The #Routes column indicates the number of routes and route identifiers associated to the demand. Finally, the last column shows the user-defined key-value attributes attached to the demand.
  

  Figure 5.15 Demands view
• Routes (only source routing)
  This sub-tab shows the information related to the routes in the network (see Section 1↑). Clicking on each route highlights its associated path in the left panel. In the sub-tab, Route Id column is a serial number starting from 0 identifying the route. Demand is the identifier of the demand associated to the route (the route carries traffic of one and only one demand). Ingress and egress node are the initial and end node of the route, that must match those of the demand. Demand offered traffic informs about the total offered traffic of the associated demand. Carried traffic is the amount of traffic carried by this route. The columns sequence of links and sequence of nodes describe the path followed by the route. The length in km sums the lengths of the links in the route. Bottleneck utilization indicates the highest utilization among the links in the route. Backup segment shows the identifiers of the protection segments associated to this route. Finally, the last column shows the user-defined key-value attributes attached to the route.
  

  Figure 5.16 Routes view
• Protection segments (only source routing)This sub-tab shows the information related to the protection segments defined in the network (see Section 2↑). Clicking on each segment highlights its associated path in the left panel. In the sub-tab, Segment Id column is a serial number starting from 0 identifying the protection segment. Origin and destination node are the end nodes of the protection segment. Both nodes should be part of the route or routes that the protections segment is protecting. Reserved bandwidth is the amount of bandwidth that the segment reserves in each traversing link. The sequence of links and nodes describe the path followed by the segment. The segment length sums the lengths of the links in the path. The segment is tagged as dedicated, when it is assigned to protect only one route. Otherwise, it is tagged as shared. The #Routes column indicates the number of routes this segment is associated to, and their identifiers. Finally, the last column shows the user-defined key-value attributes attached to the protection segment.
  

  Figure 5.17 Protection segments view
• Forwarding rules (only hop-by-hop routing)
  This sub-tab shows the information related to the forwarding rules defined in the network (see Section 2↑). Clicking on each segment highlights its associated path in the left panel. In the sub-tab, Segment Id column is a serial number starting from 0 identifying the protection segment. Origin and destination node are the end nodes of the protection segment. Both nodes should be part of the route or routes that the protections segment is protecting. Reserved bandwidth is the amount of bandwidth that the segment reserves in each traversing link. The sequence of links and nodes describe the path followed by the segment. The segment length sums the lengths of the links in the path. The segment is tagged as dedicated, when it is assigned to protect only one route. Otherwise, it is tagged as shared. The #Routes column indicates the number of routes this segment is associated to, and their identifiers. Finally, the last column shows the user-defined key-value attributes attached to the protection segment.
  

  Figure 5.18 Forwarding rules view
• Shared-risk groups
  This sub-tab shows the information related to the shared-risk groups (SRGs) defined in the network (see Section 3.1.7↑). Clicking on each SRG highlights its associated nodes/links in the left panel (the nodes and links that simultaneoously fail, if the failure event represented by the SRG occur). In the sub-tab, SRG Id column is a serial number starting from 0 identifying the SRG. MTTF and MTTR columns show the mean-time to fail and mean time to repair information in hours, that statistically characterize the occurrence of failures and the duration of repairment periods. “Nodes” and “Links” columns shows the identifiers of the nodes/links affected by the failure. The #Affected routes column indicates the number of rge routes affected by the failure, and their identifiers. Finally, the last column shows the user-defined key-value attributes attached to the SRG.
  

  Figure 5.19 Shared-risk groups view

5.2.4 Algorithm execution

Figure 5.20 Executing an algorithm

5.2.5 View reports

Figure 5.21 Showing a report

5.2.6 How to build an offline network design algorithm

• String executeAlgorithm(NetPlan netPlan, Map<String, String> algorithmParameters, Map<String, String> net2planParameters): This method will be called by Net2Plan when the user clicks the “Execute” button in the graphical interface. The method receives as input parameters (i) the netPlan object containing the current network design, (ii) the values assigned by the user in the graphical interface to the algorithm parameters, (iii) the values of the Net2Plan global configuration options (see 5.1.1.1↑). The user’s code is responsible of reading and parsing the values of the input parameters (they are received as strings). Any changes that the algorithm wishes to make to the current network design, should be performed using the appropriate methods in the netPlan object received. When the algorithm ends, the user returns a message that is printed in the graphical interface, and the netPlan object becomes the new current network design. If the algorithm raises an exception, any changes performed to the netPlan do not affect the current network design, that remains unchanged.
• String getDescription(): This method should produce a description message of the algorithm. The method will be called by Net2Plan when the user selects the algorithm to be executed, and the String received is shown in the graphical interface.
• List<Triple<String, String, String>> getParameters(): This method should produce a list with the definition of the input parameters that the algorithm will receive. Each parameter definition is composed of three strings: (i) the name of the parameter, (ii) the default value of the parameter, (iii) a description message of the parameter. This method will be called by Net2Plan when the user selects the algorithm to be executed. The definition of the parameters received, is used to create the Parameters panel in the graphical interface, that permits the user setting the values of the input parameters, that will be passed to the algorithm when executed.
  It is possible to define type-specific parameters if the default value is set according to the following rules (but user is responsible of checking in its own code):
  • If the default value is #select# and a set of space- or comma-separated values, the GUI will show a combobox with all the values, where the first one will be the selected one by default. For example: "#select# hops km" will allow choosing in the GUI between hops and km, where hops will be the default value.
  • If the default value is #boolean# and true or false, the GUI will show a checkbox, where the default value will be true or false, depending on the value accompanying to #boolean#. For example: "#boolean# true" will show a checkbox marked by default.
  • If the default value is #algorithm#, the GUI will prepare a new interface to select an algorithm as parameter. Three new fields will be added, including "_file", "_classname" and "_parameters" suffixes to the indicated parameter name, refer to the .class or .jar file where the code is located, the class name, and a set of parameters (pair of key-values separated by commas, where individual * key and value are separated with an equal symbol. The same applies to reports (#report#), * event generators (#eventGenerator#) and event processors (#eventProcessor#).

5.3 Traffic matrix design

Figure 5.22 Traffic matrix design window

5.3.1 Traffic generation: general traffic models

• Constant: Generates a $NxN$ ($N=$ number of nodes) traffic matrix with a given constant value in all its coordinates.
• Uniform $\textbf{(0,10)}$ : Generates a $NxN$ ($N=$ number of nodes) traffic matrix with random values in the range $(0,10)$ .
• Uniform $\textbf{(0,100)}$ : Generates a $NxN$ ($N=$ number of nodes) traffic matrix with random values in the range $(0,100)$ .
• 50% Uniform $\textbf{(0,10)}$ & 50% Uniform $\textbf{(0,100)}$ : Generates a $NxN$ ($N=$ number of nodes) traffic matrix with 50% of its entries with random values in the range $(0,100)$ , and the rest of the entries with random values in the range $(0,10)$ .
• 25% Uniform $\textbf{(0,10)}$ & 75% Uniform $\textbf{(0,100)}$ : Generates a $NxN$ ($N=$ number of nodes) traffic matrix with 25% of its entries with random values in the range $(0,100)$ , and the rest of the entries with random values in the range $(0,10)$ .
• Gravity model: Generates a $NxN$ ($N=$ number of nodes) traffic matrix according to the gravity model. The user should provide for each node $n$ , its total traffic generated $OUT(n)$ and received $IN(n)$ . Naturally, the sum of all the traffic generated by all the nodes should be equal to the sum of the traffic received by all the nodes (we denote it as $H$ ). From this information, the coordinate $(i,j)$ of the traffic matrix is given by $\frac{OUT(i)IN(j)}{H}$ . Then, the traffic from node $i$ to node $j$ is proportional to the total traffic produced at $i$ and proportional to the total traffic received at $j$ .

Figure 5.23 Uniform traffic models

5.3.2 Traffic generation: population-distance traffic model

• Random factor $(1-rf+2\cdot rf\cdot rand()) \in [1-rf , 1+rf]$ : This random factor is controlled by the input parameter $rf \in [0 , 1]$ , that tunes the amount of randomicity in the model. If $rf=0$ the factor $(1-rf+2\cdot rf\cdot rand())$ is always equal to 1, and the coordinates in the traffic matrix are not random. If $rf=1$ , the factor $(1-rf+2\cdot rf\cdot rand())$ equals to $1-rand()$ , and thus is a uniform random variable in $[0 , 2]$ . Intermediate values of $rf$ yield to uniform random variables in the range $[1-rf , 1+rf]$
• Node level factor $Level(L_{i},L_{j})$ : This factor permits multiplying the traffic between two nodes by a constant dependent on the level of each node. The $Level(L_{i},L_{j})$ values are defined in a $L\times L$ matrix (being $L$ : number of levels or node types defined by the user). For instance, imagine we have a network with two types of nodes, “clients” and “servers”. We want to create a traffic matrix for this network where clients do not send traffic to clients, and servers do not send traffic to servers. This can be done defining two node levels in the network for separating “client nodes” and “server nodes”. Then, we can use a level matrix with 0s in the diagonals, so the client-client traffic and server-server traffic is multiplied by 0 in the model.
• Population factor $\left(\frac{Pop_{i}\cdot Pop_{j}}{Pop_{max}^{2}}+Pop_{off}\right)$ : The population factor makes the traffic between two nodes proportional to the product of the population of both nodes divided normalized by the maximum node population $Pop_{max}^2$ . The factor $Pop_{off}$ is used to smooth the effects of the product (e.g. if a population is 0, the traffic is still not zero). The $Pop_{power}$ factor controls the effect of the population in the matrices. Typical values are:
  • $Pop_{power}=1$ in models based on so-called gravitation attraction.
  • $Pop_{power}=0$ if site traffic is independent of population.
• Distance factor $\left(\frac{dist(i,j)}{dist_{max}}+dist_{off}\right)^{dist_{power}}$ : The distance factor makes the traffic between two nodes inversely proportional to the distance between them. The $dist_{off}$ , $dist_{max}$ and $dist_{power}$ values have a similar function as in the population factor. is to avoid any possible division by 0. Typical values are:
  • $dist_{power}=2$ in models based on so-called gravitation attraction.
  • $dist_{power}=3$ in models based on so-called magnetism.
• Note that the population and/or distance normalization factors can be also disabled.

Figure 5.24 Population-distance traffic models

5.3.3 Manual traffic matrix introduction/edition

5.3.4 Traffic normalization

• Total normalization: The target of total normalization, is modifying a traffic matrix $M_T$ , so that in the normalized matrix $M_T’$ , the total amount of traffic generated equals a matches a user-defined value $M$ . This is done by multiplying all the elements of the original traffic matrix by a constant factor according to the expression:

• Row normalization: The target of row normalization, is modifying a traffic matrix $M_T$ , so that in the normalized matrix $M_T’$ , the total amount of traffic generated by each node $i$ , equals a user-defined value $M_i$ . This is done by multiplying all the elements in the $i$ -th row of the original traffic matrix by the same constant factor according to the expression:.

• Column normalization: The target of column normalization, is modifying a traffic matrix $M_T$ , so that in the normalized matrix $M_T’$ , the total amount of traffic received by each node $j$ , equals a user-defined value $M_j$ . This is done by multiplying all the elements in the $j$ -th column of the original traffic matrix by the same constant factor according to the expression:.

• Normalize to maximum traffic that can be carried: The target is to multiply the traffic matrix $M_T$ by a constant factor $\alpha$ so that the normalized matrix $\alpha M_T$ , is the largest traffic matrix that can be carried by a particular network using the optimum routing (without oversubscribing the links). The user can choose between two forms of calculating this: an estimative method, and an exact method:
  • Estimative method. This method actually produces a matrix which is an upper bound to the maximum traffic that an optimal routing could carry. For each input/output pair in the network $(i,j)$ , it calculates the number of hops that the shortest path (either in hops or in km) between those nodes has $SP_{ij}$ . For each node pair $(i,j)$ , the quantity $\alpha M_T(i,j) SP_{ij}$ is the minimum possible amount of link bandwidth that the traffic between those nodes could consume in any routing. Then, the normalized matrix $\alpha M_T$ is such that the sum of this quatity along all the coordinates, equals the total amount of bandwidth summing the links in the netowork $\sum_e u_e$ . In other words: $\alpha = \frac{\sum_{ij} M_T(i,j) SP_{ij}}{sum_e u_e}$ . Note that this may produce a traffic matrix larger than what any routing could carry.
  • Exact method. This method solves the linear program that exactly computes the maximum factor $\alpha$ for which the matrix $\alpha M_T$ still has a feasible routing in the network. The formulation is solved using the JOM library. The solver used and its .DLL/.so location is obtained from the default values in the Options menu (see 5.1.1.1↑).

Figure 5.25 Traffic normalization

5.3.5 Creating a set of traffic matrices from a seminal one

• New matrices with a compound annual growth rate:A sequence of traffic matrices is created, representing one for each of the incoming years, being the seminal matrix the traffic today. Each matrix is equal to the matrix of the previous year, multiplied by a factor $(1+CAGR)$ , where CAGR is the Compound Annual Growth Rate.
• Uniform random variations: A set of matrices is created from a seminal one. For each new matrix, each coordinate is given by a sample of a uniform random variable with average $x$ (the coordinate value in the seminal matrix), and a user-defined maximum relative variation (in the range [0, 1]). For instance, a value 0.2 of the maximum relative variation means that the new coordinate is taken uniformly between $(1-0.2)x$ and $(1+0.2)x$ .
• Gaussian random variations: A set of matrices is created from a seminal one. For each new matrix, each coordinate is given by the same coordinate in the seminal matrix, plus a sample of a gaussian random variable, with average $x$ (the coordinate value in the seminal matrix), and a user-defined coefficient of variation (quotient between standard deviation and average), and a user-defined maximum relative variation. This latter value is used to truncate the sample. For instance, a value 0.2 of the maximum relative variation means that if the sample is below $(1-0.2)x$ then the value $(1-0.2)x$ is produced, and if the sample is greater than $(1+0.2)x$ , the value $(1+0.2)x$ is produced. Finally, if the sample is below 0, the coordinate is set to 0.

Figure 5.26 Traffic normalization

5.4 Online simulation

Figure 5.27 Online simulation window

5.4.1 Network topology

5.4.2 View network state

Figure 5.28 View network state for a path restoration algorithm (links in red are failed links, links with dashed lines are the primary path, and the ones with complete lines are the current ones)

5.4.3 Execution controller

• Simulation parameters: general parameters for the simulation.
  • “disableStatistics”: In some occasions, users might be interested in collecting only their own statistics, and would prefer avoiding the overhead that requires statistics collection by the Kernel. This can be done with this parameter. In this case, kernel statistics will present zero-valued results, while algorithm-specific statistics are shown. Allowed values are “true” or “false”.
  • “omitProtectionSegments”: As stated in Section 2↑, protection segments reserve a certain amount of bandwidth to provide (partial) backup-paths for primary routes. However, in some situations, users might be interested in executing their simulations assuming that no protection segments are defined. If this parameter is set to true, then protection segments are removed from the network plan just before the simulation starts, and their bandwidth in the links is available for carrying common routed traffic. Allowed values are “true” or “false”.
  • “refreshTime”: If the option “Refresh” has been activated in the simulation controller panel, information about the current simulation, (number of processed events, simulation and cpu time...) will be shown there. This information will be refreshed every number of seconds given by this parameter. Allowed values are integers greater than 0.
  • “simEvents”: Total number of events (including transitory events) to be simulated. If the parameter “simTime” is also specified, the simulation will automatically finish when the first stopping condition is met. Allowed values are integers greater than zero, or -1 for no limit (simulation must be manually stopped).
  • “simTime”: Total simulation time (including transitory events) in seconds. If the parameter “simEvents” is also specified, the simulation will automatically finish when the first stopping condition is met. Allowed values are integers greater than zero, or -1 for no limit (simulation must be manually stopped).
  • “transitoryEvents”: Number of events for the transitory period. If “transitoryTime” is also specified, the transitory period will finish when the first condition is met. Allowed values are integers grater than 0, or -1 for no transitory period.
  • “transitoryTime”: Transitory time in seconds. If “transitoryEvents” is also specified, the transitory period will finish when the condition is met. Allowed values are integers greater than 0, or -1 for no transitory period.
• Event generator: the event generator algorithm, as a Java class extending the IEventGenerator class. This is the class in charge of generating events. Net2Plan includes several algorithms, but others can also be implemented and loaded by the user (using the Load button). A description of the algorithm will be show in this panel as well as any input parameter thay may be modified by the user.
• Provisioning algorithm: the event processor algorithm, as a Java class extending the IEventProcessor class. This is the class in charge of reacting to events. Net2Plan includes several algorithms, but others can also be implemented and loaded by the user (using the Load button). A description of the algorithm will be shown in this panel as well as any input parameter that may be modified by the user.
  Algorithms can be loaded as .jar or .class files. More information about user-made algorithms can be found in the Library API Javadoc.

Figure 5.29 Execution controller view

5.4.4 Simulation controller

• Run: This button will start the simulation. Information about the current simulation will be shown in the text panel (the refresh time is defined by the “refreshTime” parameter). If a previous simulation has already been started it must be stopped and reset before starting a new one.
• Step: Instead of running continuously, the simulation can be advanced in steps.. Each time the “Step” button is clicked the simulation will consume one event of the future event list, and then pause and refresh the text panel.
• Pause/Continue: The simulation will be paused or resumed each time this button is clicked. A simulation must be started in order for this button to work.
• Stop: Users can stop the simulation at any time, but then the simulation cannot continue.
• Refresh: The information in the text panel will be refreshed if this check-box is activated.
• View FEL: Clicking this option will show the Future Event List, where users can examine the future events to be processed by the provisioning algorithm:
  

  Figure 5.30 Future Event List (FEL)

5.4.5 Simulation report

Figure 5.31 Viewing a simulation report

5.4.5.1 View reports

6 Command-line interface

• To obtain a brief information, including only the execution modes, users should execute the CLI without arguments: java -jar Net2Plan-cli.jar
• To obtain the complete information, including individual help for every execution mode, users should execute: java -jar Net2Plan-cli.jar --help
• To obtain the information about a certain execution mode, users should execute: java -jar Net2Plan-cli.jar --help mode-name

• Network design: java -jar Net2Plan-cli.jar --mode net-design [more options]
• Traffic matrix design: java -jar Net2Plan-cli.jar --mode traffic-design [more options]
• Online simulation: java -jar Net2Plan-cli.jar --mode online-sim [more options]
• Reporting: java -jar Net2Plan-cli.jar --mode report

• To execute the FA_shortestPath algorithm for the NSFNet network and its reference matrix: java -jar Net2Plan-cli.jar --mode net-design --input-file workspace\data\networkTopologies\NSFNet_N14_E42.n2p --traffic-file workspace\data\trafficMatrices\NSFNet.n2p --output-file workspace\data\NSFNet.n2p --class-file workspace\BuiltInExamples.jar --class-name FA_shortestPath --alg-param shortestPathType=km
• To execute the network design report over the previous design: java -jar Net2Plan-cli.jar --mode report --input-file workspace\data\NSFNet.n2p --output-file workspace\data\report.html --class-file workspace\BuiltInExamples.jar --class-name Report\networkDesign
• To generate a series of 4 10x10 traffic matrices using a (0, 100) random uniform model: java -jar Net2Plan-cli.jar --mode traffic-design --num-nodes 10 --traffic-pattern uniform-random-100 --output-file workspace\data\trafficMatrices\tm10nodes.n2p --num-matrices 4
• To execute a simulation: java -jar Net2Plan-cli.jar --mode online-sim --input-file workspace\data\networkTopologies\NSFNet_N14_E42_complete.n2p --output-file workspace\data\simReport.html --generator-class-file workspace\BuiltInExamples.jar --processor-class-file workspace\BuiltInExamples.jar --generator-class-name NRSim_EG_exponentialSRGFailureGenerator --processor-class-name NRSim_AA_genericRestorationAlgorithm --sim-param simEvents=100000 --sim-param transitoryEvents=10000

7 Release notes

• Minor changes
• Improved documentation
• New: A new plugin architecture (undocumented) has been created to support the integration of external CLI/GUI tools or I/O filters. Original plugins are dettached from kernel and are also located into plugins folder

• Major changes in network model:
  • New: Complete multilayer support, including layer coupling (links at an upper layer become demands at a lower layer, or viceversa)
  • New: Identifiers for nodes, links, demands, and so on, are now long values. get() methods, whose output were arrays, now return maps
  • New: Internal speed-up via caching of common get() methods
• New: ’Online simulation’ is a new tool that merges the previous simulators into a common one, and it uses the same network model than for network design
• Improved documentation

• Minor changes
• Improved documentation

• Minor changes
• Improved documentation

• New: ’Time-varying traffic’ simulator
• New: ’Network design’ is now able to execute multilayer algorithms
• Minor changes

• Initial Java version, many major changes from latest MATLAB version

8 Authors

• “Telecommunication networks theory” (2nd year, 2nd quarter, “Degree in Telematics Engineering” and “Degree in Telecommunication Systems Engineering”
• “Network planning and management” (3rd year, 2nd quarter, “Degree in Telematics Engineering”)

• Pablo Pavón Mariño
• José Luis Izquierdo Zaragoza

A Mathematical notation

A.1 Topology

Figure A.1 Topology with $|N|$ = 3 nodes, $N = \{n_1,n_2,n_3\}$ , $|E|$ = 3, $E = \{e_1,e_2,e_3\}$ . End nodes of $e_1$ are $a(e_1) = n_1$ and $b(e_1) = n_2$ . Outgoing links from node $n_2$ are $d^{+}(n_2) = \{e_2,e_3\}$ , and the incoming one is $d^{-}(n_2) = \{e_1\}$

A.2 Installed capacities

A.3 Traffic model

A.4 Routing

Figure A.2 Topology with $|N|$ = 4 nodes, $N = \{n_1,\dots,n_4\}$ , $|E|$ = 4 links, $E = \{e_{12},e_{23},e_{34},e_{42}\}$

A.5 Protection segments

A.6 Notation

B Metrics

B.1 Topology

• Number of nodes $$|N|$$
• Number of links $$|E|$$
• Average node degree: It is the average number of (incoming or outgoing) links per node $$\frac{|E|}{|N|}$$
• Network density $$\frac{|E|}{|N|(|N|-1)}$$
• Network diameter: It is the largest path among all pairs shortest paths $$\max SP_{i\rightarrow j}$$ where $SP_{i\rightarrow j}$ is the length of the shortest path from node $i$ to node $j$
• Average shortest-path length: Average length among all pairs shortest paths $$\overline{n}=\frac{\sum_{i\in N}\sum_{j\in N,\ j\neq i}SP_{i\rightarrow j}}{|N|(|N|-1)}$$
• Average link distance $$\frac{\sum_{e\in E}l_{e}}{|E|}$$

B.2 Link capacities

• Total capacity installed $$U_{e}=\sum_{e\in E}u_{e}$$
• Average capacity installed $$\frac{U_{e}}{|E|}$$
• Capacity module size: Shows the greatest common divider among all link capacities

B.3 Offered traffic

• Number of demands $$|D|$$
• Average number of demands per node pair $$\frac{|D|}{|N|(|N|-1)}$$
• Total offered traffic $$H_{d}=\sum_{d\in D}h_{d}$$
• Average offered traffic per demand $$\frac{H_{d}}{|D|}$$

B.4 Routing (carried traffic)

B.4.1 Source routing

• Link carried traffic: It is equal to the sum of the occupied capacity of each route traversing the link $$y_{e}=\sum_{p\in P_{e}}y_{p}\quad\forall e\in E$$
• Link utilization: It is equal to the carried traffic by the link and the total reserved bandwidth by protection segments associated to the link, all divided by the link capacity $$\rho_{e}=\frac{y_{e}+\sum_{s\in S_{e}}u_{s}}{u_{e}}\quad\forall e\in E$$
• Demand carried traffic: It is equal to the sum of the carried traffic of each route associated to the demand $$r_{d}=\sum_{p\in P_{d}}x_{p}\quad\forall d\in D$$

B.4.2 Hop-by-hop routing

• Link carried traffic: It is equal to the sum of the occupied capacity $$y_{e}=\sum_{d\in D}x_{de}\quad\forall e\in E$$
• Link utilization: It is equal to the carried traffic by the link divided by the link capacity $$\rho_{e}=\frac{y_{e}}{u_{e}}\quad\forall e\in E$$
• Demand carried traffic (considering that egress node does not forward its own traffic): It is equal to the sum of the carried traffic of each route associated to the demand $$r_{d}=\sum_{e\in\delta^{-}(b(d))}x_{de}\quad\forall d\in D$$

B.4.3 General metrics

• Network congestion (or bottleneck utilization): Maximum load among all links $$\max_{e\in E}\rho_{e}$$
• Throughput: Total traffic injected to the network $$R_{d}=\sum_{d\in D}r_{d}$$
• Total in-network carried traffic: Total traffic traversing the network $$Y_{e}=\sum_{e\in E}y_{e}$$
• Average number of hops $$\overline{n}=\frac{Y_{e}}{R_{d}}$$
• Average ingress -and egress- traffic per node $$\frac{R_{d}}{|N|}$$
• Average traversing traffic per node $$\frac{Y_{e}-R_{d}}{|N|}$$
• Bifurcation degree: Average number of paths carrying traffic per each demand $$\frac{\sum_{d\in D}|\{x_{p}>0,\ p\in P_{d}\}|}{|D|}$$

B.5 Rate

• % Lost traffic $$100\cdot\frac{\sum_{d\in D}(h_{d}-r_{d})}{H_{d}}$$
• Jain’s fairness index (absolute) $$\frac{\left[\sum_{d\in D}(h_{d}-r_{d})\right]^{2}}{|D|\cdot\sum_{d\in D}(h_{d}-r_{d})^{2}}$$
• Jain’s fairness index (proportional) $$\frac{\left[\sum_{d\in D}\frac{h_{d}-r_{d}}{h_{d}}\right]^{2}}{|D|\cdot\sum_{d\in D}\left(\frac{h_{d}-r_{d}}{h_{d}}\right)^{2}}$$

B.6 Delay

• Propagation delay per link (seconds) $$T_{e}^{prop}=\frac{l_{e}}{v_{e}^{prop}}\quad\forall e\in E$$ where $v^{prop}_{e}$ is the speed of light when traverses link $e$
• Transmission delay per link (seconds) $$T_{e}^{tx}=\frac{S}{R_{b}u_{e}}\quad\forall e\in E$$ where $S$ is the average packet length (in bits), and $R_{b}$ is the capacity in bits per second per one capacity unit
• Buffering delay per link (seconds) $$T_{e}^{buf}=T_{e}^{tx}\frac{\rho_{e}^{\left[2(1-H)\right]^{-1}}}{\left(1-\rho_{e}\right)^{H/(1-H)}}\quad\forall e\in E$$ where $H\triangleq$ Hurst Parameter. Choosing $H=0.5$ yields to same result as that predicted by M/M/1 queue model
• Delay per link (seconds) $$T_{e}=T_{e}^{prop}+T_{e}^{tx}+T_{e}^{buf}\quad\forall e\in E$$
• Average network delay (seconds) $$T=\frac{1}{R_{d}}\sum_{e\in E}y_{e}T_{e}$$

B.7 Blocking

• Blocking probability of a link $$B_{e}=\text{Erlang-B}(u_{e},y_{e})$$
• Average network blocking probability $$B=\frac{1}{R_{d}}\sum_{e\in E}y_{e}B_{e}$$
• Worst link blocking probability $$\max_{e\in E}B_{e}$$