Modeling

#summary Chapter two of Shanks User Manual #labels Phase-Support

== 2. NETWORK MODEL == We have made a detailed description of the network we want to simulate. Now we need to model the network in java for which we will use the tools provided by SHANKS.

=== 2.1. Creating the Project === Create a new Java project then add to the Build Path the packages listed below:

• Itext-1.2.3.jar
• jason.jar
• jcommon-1.0.16.jar
• jfreechart-1.0.13.jar
• jmf-2.1.1e.jar
• Junit-4.8.2.jar
• mason.16.jar
• shanks-core-0.2.1-SNAPSHOT.jar These packages are provided in shanks-demo.zip/required-libraries. Figure 2 shows this configuration in eclipse project. or you can import the shank project if you have the project installed.

A recurrent instalation issue for Java3D import was detected, more info: [http://code.google.com/p/shanks-with-mason/wiki/InstallationManual?ts=1331736987&updated=InstallationManual#1._Dependency_problem_detected Dependecies problem detected]

http://shanks-with-mason.googlecode.com/svn/wiki/images/manuals/userManual/dependencies.jpg

In this new project replicate the package tree shown in Figure 3. Next we will give a brief explanation of the hierarchical distribution of this package tree.

• agent: In this package are located all agents acting on the simulation. We will discussed how to include agents in the project in detail in Section 7 of this manual.
• model: Here you will find the actual model of the network we want to simulate. The network can be divided on diferent sections that the user considers independent to each other. For each of this sections a model subpackage have to be made. I.e.: If you want to simulate the computer network of an company, perhaps you could consider divide the network in one section for each floor of the building in wich the company is located, or by departments of the company, or by sectors, etc... The ideal is that this division is determined by the distribution of the network to be simulated. Each of the models created must submit the following contents:
• myModel.element.device: In this package are located the classes that implements the devices of the model.
• myModel.element.link: In this package are located the classes that implements the links of the model.
• myModel.failure: In this package are located the classes that implement the events that affect network performance through the simulation. Although we have not mentioned the concept of failure, which is discussed below in section 3.4. of this manual.
• myModel.scenario: In this package are located the classes that implements different model scenarios. Usually there is only one scenario by model, but it could be useful have several. In SHANKS the scenario is where you describe how the elements of the network interact with each other as a set.
• simulation: In this package are located the classes responsible for launch and run the simulation.

http://shanks-with-mason.googlecode.com/svn/wiki/images/manuals/userManual/package.tree.jpg

==== 2.1.1. HAN-Model: Project ==== Figure 2 and Figure 3 are screenshots of the configuration process of the sample project. Following is a brief explanation about customization of the package tree:

• model.han: Here you will find the network elements that make up the home area network or HAN. There are six devices and three links listed in their respective packages containers. This example for its simplicity lacks the need to implement more than one network section, however in later chapters a second model will be made to add the connection of the HAN to the ISP, with the intention of create and show the complex scenario managment.
• element.device: In this package will be located implementations of devices: Computer, Smartphones, Wireless Access Point, Ethernet Router and ADSL Modem.
• element.link: In this package will be located implementations of links: Etherneth, Wireless Bandwidth and Internal Bus.
• failure: In this package will be located implementations of the failures that may affect the home network.
• scenario: In this package are located the classes that defines how the network elements of the HAN interact with each other. It could be say that the scenario is the direct representation of the model in java as a whole.
• simulation: In this package will be located the class that we will use for launch and run the simulation.

=== 2.2. Device Modeling === For each of the devices that we have drawn on the outline (and listed above) we must have a java class that defines it on the package model.myModel.element.device. Network devices are instances of classes that defines them, so several devices can be defined by a single class. i.e.: In a conventional computer network with multiple computers, it is not necessary to implement a class for each computer (PC1.java, PC2.java ...) it is enough to define a single class that implements a generic computer (Computer.java ) then each of the computers on the network will be an instance of this class. Classes that define the network devices must extend the interface device, which in turn extends NetworkElement class of SHANKS build. Therefore those classes must implement the abstract methods derived from these two interfaces. In the HAN-Model example the details of this implementatio are clarified as well as the use of the named interfaces.

==== 2.2.1. HAN-Model: Modeling devices ==== Figure 4 shows the final state of model.han.element.device package with the five classes that define the six devices of our HAN.

(IMAGE HERE) Figure 4: Model HAN devices.

We will explain briefly Smartphones.java class implementation. To facilitate the read of this document the class code is available here. {{{

package es.upm.gsi.tsag.demo.model.han.element.device; import es.upm.dit.gsi.shanks.model.element.device.Device; […]

public class Smartphone extends Device{

public static final String STATUS_OFF = "OFF"; public static final String STATUS_OK = "OK"; public static final String STATUS_OUT_OF_RANGE = "Out of range"; public static final String STATUS_DISCONNECTED = "Disconnected"; public static final String PROPERTY_SIGNAL = "Signal"; public static final String PROPERTY_BATTERY_CAPACITY = "Battery Power"; public static final String PROPERTY_CONNECTION = "Connection"; public static final String PROPERTY_POWER = "Power";

public void checkProperties()throws Exception {

String status = this.getCurrentStatus(); if (status.equals(Smartphone.STATUS_OUT_OF_RANGE)) { this.changeProperty(Smartphone.PROPERTY_SIGNAL, 0.1); this.changeProperty(Smartphone.PROPERTY_CONNECTION, "Disconnected"); this.changeProperty(Smartphone.PROPERTY_POWER, "ON");

} else if (status.equals(Smartphone.STATUS_OFF)) { this.changeProperty(Smartphone.PROPERTY_BATTERY_CAPACITY, 0); this.changeProperty(Smartphone.PROPERTY_CONNECTION, "Disconnected"); this.changeProperty(Smartphone.PROPERTY_SIGNAL, 0); this.changeProperty(Smartphone.PROPERTY_POWER, "OFF");

} else if (status.equals(Smartphone.STATUS_OK)) { this.changeProperty(Smartphone.PROPERTY_BATTERY_CAPACITY, 50 + Math.random() * 10); this.changeProperty(Smartphone.PROPERTY_SIGNAL, 70 + Math.random() * 10); this.changeProperty(Smartphone.PROPERTY_CONNECTION, "Connected"); this.changeProperty(Smartphone.PROPERTY_POWER, "ON");

} else if (status.equals(Smartphone.STATUS_DISCONNECTED)) { this.changeProperty(Smartphone.PROPERTY_CONNECTION, "Disconnected"); this.changeProperty(Smartphone.PROPERTY_POWER, "ON"); } }

public void checkStatus() throws Exception {

double battery = this.getProperty(Smartphone.PROPERTY_BATTERY_CAPACITY); double signal = this.getProperty(Smartphone.PROPERTY_SIGNAL); String connection = this.getProperty(Smartphone.PROPERTY_CONNECTION); String power = this.getProperty(Smartphone.PROPERTY_POWER);

if (power.equals("OFF")) { this.updateStatusTo(Smartphone.STATUS_OFF); } else { if (battery <= 5) { this.updateStatusTo(Smartphone.STATUS_OFF); } else if (signal > 70) { if (connection.equals("Connected")) { this.updateStatusTo(Smartphone.STATUS_OK); } else { this.updateStatusTo(Smartphone.STATUS_DISCONNECTED); } } else { this.updateStatusTo(Smartphone.STATUS_OUT_OF_RANGE); } } } public void fillIntialProperties() { this.addProperty(PROPERTY_CONNECTION, "Connected"); this.addProperty(PROPERTY_POWER, "ON"); this.addProperty(PROPERTY_SIGNAL, 70+Math.random()*10); this.addProperty(PROPERTY_BATTERY_CAPACITY, 50+Math.random()*10); }

public void setPossibleStates() { this.addPossibleStatus(Smartphone.STATUS_DISCONNECTED); this.addPossibleStatus(Smartphone.STATUS_OFF); this.addPossibleStatus(Smartphone.STATUS_OK); this.addPossibleStatus(Smartphone.STATUS_OUT_OF_RANGE); } }

}}} The inheritance from NetworkElement interface provides to the Smartphone implemetantion the following attributes and their accessories methods:

• id (String): ID of network element.
• possibleStates (<String> List): List of possible states that can take the device. In SHANKS that a device takes a given state means that some of the properties of that device take certain value. The list of possible states of a device must be initialized in the simulation setup. Although you can add and remove possible states in simulation time it is unusual. We recommend you only to do it if you're really sure that it's the best way to model the real system. i.e.: That the smartphopne implementation take a OK state may imply that the properties of BATTERY_CAPACITY, SIGNAL_LEVEL and CONNECTION have taken respectively the values ">20%", ">70%" and "connected".
• currentStatus (String): Current state of the network element. The state of the element must be initialized in the setup and can be asked or modified at any time during the simulation.
• properties (HashMap <String, Object>): reference name and current value of the item's properties. In SHANKS a device has a list of properties that shape their characteristics. The current values of all properties dictates the current state of the device. i.e.: On a Smartphone BATTERY_POWER property with value "empty" indicates that the device cannot adopt the OK state, in addition that the state -OUT_OF_RANGE_ could have any value because the device may or may not be in range of a wifi access point and finally that the device is in the _OFF _state.

The inheritance from the Device interfaces complements the Smartphone implementation with the following attributes and accessorie methods:

• linksList (<Link> List): List of links connected to the device. This list must be defined in the setup of the simulation. Although you can add and remove links in simulation time it is unusual. We recommend you only to do it if you're really sure it's the best way to model the real system.
• isGateway (boolean): property that distinguishes a type of special devices in the simulation. Becomes important when we need to manage complex scenarios, the subject will be discussed in Chapter 6.

We have let well defined the relations between NetworkElement, Device and our implementation of the network model. Now we will talk about lines of code to implement by the user.

For each class representing a device must be defined the properties and states to govern such devices throughout the simulation. In the example states and properties are listed at the beginning of the file as a serie of static fields of type String. Note that although the definition is identical, functionally and conceptually both types of fields are different.

When all the states and properties of the device we want to model have been declared it is necessary to implement the four abstract methods inherited from NetworkElements.

• public void checkProperties(): This method starts from the current state value of the device and verify that the values ​​of all properties stay in concordance. If the value of any property does not correspond to a logical one for the current state, this method must change the value of these properties with a value in concordance to that state. When something in our simulation actively change the state of a device will use this method to change properties in a manner consistent with the new state. Note that this implementation can be as complicated as the user wants it. The new property values ​​can be obtained from a database, a class project with a compilation of definitions, random values, or ordered directly to another node in the simulation. In the example of Smartphone device, we decided to make a very simple implementation. When calling this method is not performed verification of the properties, but directly get these properties have default values ​​for the current state.

• public void checkStatus (): This method starts from current values ​​of all the properties of the device and based on these values ​​sets the current device state. If the current state does not correspond logically with the collection of current property values, this method should change the current state by one in concordance. When something in our simulation actively change the value of some properties of a device, we will use this method to change the status of the device accordingly. Again this implementation can be as complicated as the user wants it. In this case the decision of the appropriate state for property values ​​can be calculated based on a weighting of these values ​​to a univocal correspondence, a random choice between several candidates, etc... In the Smartphone example we decided to make a very simple implementation. When this method is called a check is made with univocal values ​​of the properties and based on those values the current state is chosen from among the possible states of the device.

• public void fillIntialProperties(): This method is called on the scenario setup at the beginning of the simulation. It has two missions: first it must set the initial value of the properties of the device and second it must add all the properties in the field properties inherited from interface NetworkElement.

• public void setPossibleStates(): This method is called on the scenario setup at the beginning of the simulation. Its mission is to add the possible states declared in the class in the field posibleStates inherited by NetworkElement interface.

=== 2.3. Link Modeling === In the same way we did with devices modeling, for each link described in the outline must have a java class that defines the package model.myModel.element.link.

Again it should be noted that, as with the devices, the links in the simulation are instances of classes that define them, so you only need to make a class for each type of link.

Classes that define the links of the network must extend the Link interface, which in turn extends NetworkElement interface of SHANKS build. The reader will surely have noticed the resemblance between links and devices. As both are implementations of the concept network element can be expected that its implementation are identical, and so it is. In the example HAN-Module we can check it, which also will show the difference between Link and Device.

Figure 5: Links HAN-Model

==== 2.3.1. HAN-Model: Modeling links ==== Figure 5 shows the model.han.element.link package, with the three classes that define the links on our HAN. To continue with an example close to Smartphone devices, we will briefly explain the WifiConnection.java class implementation, defining the network wireless link.

To facilitate the read of this document the class lines of code are shown below.

{{{ package es.upm.gsi.tsag.demo.model.han.element.link; import es.upm.dit.gsi.shanks.model.element.link.Link;

public class WifiConnection extends Link {

public static final String STATUS_OK = "OK"; public static final String STATUS_INTERFEARENCES = "Interfearences"; public static final String STATUS_HIGH_BER = "High BER";

public static final String PROPERTY_INTERFEARENCE = "Length"; public static final String PROPERTY_PACKETLOSSRATIO = "Packet loss ratio";

public void checkProperties() throws Exception { String status = this.getCurrentStatus(); if (status.equals(WifiConnection.STATUS_OK)) { this.changeProperty(WifiConnection.PROPERTY_PACKETLOSSRATIO, 0.001); this.changeProperty(WifiConnection.PROPERTY_INTERFEARENCE, 0.001); } else if (status.equals(WifiConnection.STATUS_INTERFEARENCES)) { this.changeProperty(WifiConnection.PROPERTY_INTERFEARENCE, 1.0); } else if (status.equals(WifiConnection.STATUS_HIGH_BER)) { this.changeProperty(WifiConnection.PROPERTY_PACKETLOSSRATIO, 0.7); } }

public void checkStatus() throws Exception { double ratio = this.getProperty(WifiConnection.PROPERTY_PACKETLOSSRATIO); double interference = this.getProperty( WifiConnection.PROPERTY_INTERFEARENCE); if (interference < 0.01) { this.updateStatusTo(WifiConnection.STATUS_INTERFEARENCES); } else if (ratio >= 0.7) { this.updateStatusTo(WifiConnection.STATUS_HIGH_BER); } else { this.updateStatusTo(WifiConnection.STATUS_OK); } }

public void fillIntialProperties() { this.addProperty(WifiConnection.PROPERTY_INTERFEARENCE, 0.001); this.addProperty(WifiConnection.PROPERTY_PACKETLOSSRATIO, 0.001); }

public void setPossibleStates() { this.addPossibleStatus(WifiConnection.STATUS_OK); this.addPossibleStatus(WifiConnection.STATUS_HIGH_BER); this.addPossibleStatus(WifiConnection.STATUS_INTERFEARENCES); } }

}}}

What has been said about the relation betwen links implementation and NetworkElement in the previous section Device Modeling is also valid in this. However the inheritance of Link interface complements differently the links implementation, adding the following attributes.

• linkDevices (<Link> List): List of devices connected to the link. This list must be defined on the setup of the simulation. You can add and remove links in simulation time.
• deviceCapacity: An integer that contains the maximum number of devices that can be bind at the same time for the current link instance. i.e.: When modeling a cable itis immediately determine that the link capacity is two, a device at each end of the cable. But not always have to be so. Suppose our simulation wants to model a data bus that supports five machines. The bus can still be modeled as a cable, but has the capacity to connect more than two machines.

The implementation of the states, properties and methods inherited from class NetworkElements is homologous to that of the previous section, as you can see on the previous code lines.

=== 2.4. Failure Modeling === Before proceeding with the implementation we must return to the piece of paper with the network outline and then think about the way the environment affects our model. Each of the network elements can fail for almost any reason, so you have be to judge what level of detail you want to use.

Once you've thought a bit about it go over each network element that have designed before, both devices and links, and for each failure that you feel is relevant to your simulation there must be a class that defines it on the package model.han.failure.

The classes that define the fault must extend the interface Failure of SHANKS build, as will be seen in the example is even simpler to implement it that the network elements.

==== 2.4.1. HAN-Model: Modeling failures ==== To continue the example we have chosen to show the implementation of the wireless connection failure due to noise. As you can see in Figure 6 we have made some others failures more related to different network devices.

To facilitate the read of this document we put the lines code of the class WifiNoiseFailure.java next. {{{ package es.upm.gsi.tsag.demo.model.han.failure; import es.upm.dit.gsi.shanks.model.failure.Failure; import es.upm.gsi.tsag.demo.model.han.element.link.WifiConnection;

public class WifiNoiseFailure extends Failure {

public WifiNoiseFailure() { super(WifiNoiseFailure.class.getName(), 0.01); }

public void addPossibleAffectedElements() { this.addPossibleAffectedElements(WifiConnection.class, WifiConnection.STATUS_INTERFEARENCES); } }

}}}

There are only two steps to consider when implementing any kind of failure:

• In the constructor of the superclass is passed as a parameter the name of the class that defines the error and a real number that represents the probability that such failure can occur at every step of the simulation.
• It is necessary to implement the method addPossibleAffectedElements(). This method is called in the setup of the scenario and defines what types of network elements are afected by this failiure. A single failure may affect one or more network elements.

=== 2.5. Scenario Modeling === Until now we have defined network elements that we want to simulate, and failures that can occur and affect the network elements. But we still have not worried about how these elements interact with each other.

The scenario is the platform on which the instances of the network elements are created, and establishes how these actors interact with each other.

The scenario is created in the package model.han.secenario. The scenario implementation must extend the scenario interface of SHANKS build, and therefore must implement the abstract methods defined for the that interface. You can define several scenarios, and for each one of them you must implemente a diferente scenario class.

==== 2.5.1. HAN-Model: Modeling scenario ==== In this part of the example we will model a single scenario. To facilitate the read of the document presents the code lines of the implementation next.

===== Textbox5:HANModelScenario.java =====

{{{ package es.upm.gsi.tsag.demo.model.han.scenario; [import]

public class HANScenario extends Scenario {

public static final String STATUS_SUNNY = "Sunny"; public static final String STATUS_RAINY = "Rainy"; public static final String STATUS_SNOWY = "Snowy";

public HANScenario(String id, String initialState, Properties properties) throws UnsupportedNetworkElementStatusException, TooManyConnectionException, UnsupportedScenarioStatusException, DuplicatedIDException { super(id, initialState, properties); }

public void addNetworkElements() throws UnsupportedNetworkElementStatusException, TooManyConnectionException, DuplicatedIDException { Computer computer = new Computer("PC",Computer.STATUS_OK); EthernetRouter router = new EthernetRouter("Router"); EthernetCable ethernetCable = new EthernetCable("Ethernet PC", 1.5); router.connectToDeviceWithLink(computer, ethernetCable);

this.addNetworkElement(computer); this.addNetworkElement(router); this.addNetworkElement(ethernetCable); }

public void addPossibleFailures() {
Set set = new HashSet(); set.add(this.getNetworkElement("PC")); set.add(this.getNetworkElement("Ethernet PC")); Set set2 = new HashSet(); set2.add(this.getNetworkElement("HDMI PC Monitor")); List<Set> possibleCombinations = new ArrayList<Set>(); possibleCombinations.add(set); possibleCombinations.add(set2); this.addPossibleFailure(CutCable.class, possibleCombinations);

NetworkElement router = this.getNetworkElement("Router"); this.addPossibleFailure(NoIPFailure.class, router); NetworkElement pc = this.getNetworkElement("PC"); this.addPossibleFailure(BrokenFan.class, pc); }

public HashMap<Class<? extends Failure>, Double> getPenaltiesInStatus( String status) throws UnsupportedScenarioStatusException { if (status.equals(HANScenario.STATUS_RAINY)) { return this.getRainyPenalties(); } else if (status.equals(HANScenario.STATUS_SNOWY)) { return this.getSnowyPenalties(); } else if (status.equals(HANScenario.STATUS_SUNNY)){ return this.getSunnyPenalties(); } else { throw new UnsupportedScenarioStatusException(); }

public void setPossibleStates() { this.addPossibleStatus(HANScenario.STATUS_SUNNY); this.addPossibleStatus(HANScenario.STATUS_RAINY); this.addPossibleStatus(HANScenario.STATUS_SNOWY); }}

}}}

The Scenario interface has two main methods that must be implemented by the user:

• addNetworkElement(): This method is called at the setup of the scenario, its mission is to create and add to the simulation all network elements that we wish to include in it.
• addPossibleFailures(): This method is called at the setup of the scenario, immediately after the previous step and therefore the network elements have been already added to the scenario. Its mission is to define sets of elements that relate to each other through the network failures. in adition the scenario support the definition of scenario states, as with the network elements. Scenario states can affect all actors in the network. A state is associated with a number of modifiers to the likelihood of a failure and his chance to ocur, thus entering the state SUNNY in HAN-Scenario may generate failures due to temperature more likely than in any other circumstances.