README.md 33.1 KB
Newer Older
Manoel Campos's avatar
Manoel Campos committed
1
<a id="top"></a>
2

Manoel Campos's avatar
Manoel Campos committed
3
4
5
[![Build Status](https://img.shields.io/travis/manoelcampos/cloudsim-plus/master.svg)](https://travis-ci.org/manoelcampos/cloudsim-plus) [![Dependency Status](https://www.versioneye.com/user/projects/587a137d2ef9ab000eff9d41/badge.svg?style=rounded-square)](https://www.versioneye.com/user/projects/587a137d2ef9ab000eff9d41) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/3f132b184d5e475dbbcd356ee84499fc)](https://www.codacy.com/app/manoelcampos/cloudsim-plus?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=manoelcampos/cloudsim-plus&amp;utm_campaign=Badge_Grade) [![Codacy Badge](https://api.codacy.com/project/badge/Coverage/3f132b184d5e475dbbcd356ee84499fc)](https://www.codacy.com/app/manoelcampos/cloudsim-plus?utm_source=github.com&utm_medium=referral&utm_content=manoelcampos/cloudsim-plus&utm_campaign=Badge_Coverage) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.cloudsimplus/cloudsim-plus/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.cloudsimplus/cloudsim-plus) [![Documentation Status](https://readthedocs.org/projects/cloudsimplus/badge/?version=latest)](http://cloudsimplus.rtfd.io/en/latest/?badge=latest) 
[![GitHub Closed Issues](https://img.shields.io/github/issues-closed-raw/manoelcampos/cloudsim-plus.svg?style=rounded-square)](http://github.com/manoelcampos/cloudsim-plus/issues) 
[![GPL licensed](https://img.shields.io/badge/license-GPL-blue.svg)](http://www.gnu.org/licenses/gpl-3.0)
6

7
8
9
<p align="center">
<b><a href="#overview">Overview</a></b>
|
Manoel Campos's avatar
Manoel Campos committed
10
<b><a href="#exclusive-features">Exclusive Features</a></b>
11
|
Manoel Campos's avatar
Manoel Campos committed
12
<b><a href="#projects-structure">Structure</a></b>
13
|
14
15
<b><a href="#how-to-use-cloudsim-plus">How to use</a></b>
|
16
<b><a href="#a-minimal-and-complete-simulation-example">Examples</a></b>
17
18
19
20
21
|
<b><a href="#documentation-and-help">Docs and Help</a></b>
|
<b><a href="#why-care">Why should I care?</a></b>
|
Manoel Campos's avatar
Manoel Campos committed
22
<b><a href="#why-another-fork">Why an independent fork?</a></b>
23
24
25
|
<b><a href="#differences">Differences from CloudSim</a></b>
|
Manoel Campos's avatar
Manoel Campos committed
26
<b><a href="#general-features-of-the-simulator">General Features</a></b>
27
28
29
|
<b><a href="#publications">Publications</a></b>
|
Manoel Campos's avatar
Manoel Campos committed
30
31
<b><a href="#license">License</a></b>
|
Manoel Campos's avatar
Manoel Campos committed
32
<b><a href="#contributing">Contributing</a></b>
33
34
35
36
</p>

# Overview

37
CloudSim Plus is a full-featured, highly extensible simulation framework enabling modeling, simulation, and experimentation of Cloud computing infrastructures and application services. It allows users to focus on specific system design issues to be investigated, without the concern of the low level details related to Cloud-based infrastructures and services.
38
 
39
Cloud computing is the leading technology for delivery of reliable, secure, fault-tolerant, sustainable, and scalable computational services. For assurance of such characteristics in cloud systems under development, it is required timely, repeatable, and controllable methodologies for evaluation of new cloud applications and policies, before actual development of cloud products. Because utilization of real testbeds limits the experiments to the scale of the testbed and makes the reproduction of results cumbersome, computer-base simulation may constitute an interesting tool. This project is suitable to quickly develop such simulation scenarios and run them quickly, in a typical PC. 
Manoel Campos's avatar
Manoel Campos committed
40

41
CloudSim Plus is a fork of [CloudSim 3](https://github.com/Cloudslab/cloudsim/tree/20a7a55e537181489fcb9a2d42a3e539db6c0318), re-engineered primarily to avoid code duplication. It provides [code reusability](https://en.wikipedia.org/wiki/Code_reuse) and ensures compliance with software engineering principles and recommendations for extensibility improvements. It focuses on usage of software engineering standards and recommendations such as [Design Patterns](https://en.wikipedia.org/wiki/Software_design_pattern), [SOLID principles](https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)) and other ones such as [KISS](https://en.wikipedia.org/wiki/KISS_principle) and [DRY](https://pt.wikipedia.org/wiki/Don't_repeat_yourself).
Manoel Campos's avatar
Manoel Campos committed
42

romantic668's avatar
romantic668 committed
43
The efforts dedicated to this project have been recognized by the [EU/Brasil Cloud FORUM](https://eubrasilcloudforum.eu). A post about CloudSim Plus is available at [this page of the Forum](https://eubrasilcloudforum.eu/en/instituto-federal-de-educação-do-tocantins-brazil-instituto-de-telecomunicações-portugal-and), including a White Paper available in the [Publications Section](#publications).
44

Manoel Campos's avatar
Manoel Campos committed
45
46
CloudSim Plus is developed through a partnership among the Systems, Security and Image Communication Lab of [Instituto de Telecomunicações (IT, Portugal)](http://www.it.pt), the [Universidade da Beira Interior (UBI, Portugal)](http://www.ubi.pt) and the [Instituto Federal de Educação Ciência e Tecnologia do Tocantins (IFTO, Brazil)](http://www.ifto.edu.br). It is supported by the Portuguese [Fundação para a Ciência e a Tecnologia (FCT)](https://www.fct.pt) and by the [Brazilian foundation Coordenação de Aperfeiçoamento de Pessoal de Nível Superior (CAPES)](http://www.capes.gov.br).

47
**There are different ways you can contribute to CloudSim Plus, as it is shown in the [contribution guide](CONTRIBUTING.md). One easy way is to click on the "Star" button at the top of the project's GitHub page, so that you are helping to promote the project.**
Manoel Campos's avatar
Manoel Campos committed
48

Manoel Campos's avatar
Manoel Campos committed
49
The original [CloudSim](http://github.com/Cloudslab/cloudsim) project is developed in the [Cloud Computing and Distributed Systems (CLOUDS) Laboratory](http://cloudbus.org/), at the [Computer Science and Software Engineering Department](http://www.csse.unimelb.edu.au/) of the [University of Melbourne](http://www.unimelb.edu.au/).
50

51
52
<p align="right"><a href="#top">:arrow_up:</a></p>

53
# Exclusive Features
54

55
CloudSim Plus provides a lot of exclusive features, from the most basic ones to build simple simulations, to advanced features for simulating more realistic cloud scenarios: 
56

57
1. It is easier to use. A complete and easy-to-understand simulation scenario can be built in few lines of code. Check the [Examples Section](#a-minimal-and-complete-simulation-example); 
Manoel Campos's avatar
Manoel Campos committed
58
1. [Vertical VM Scaling](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/autoscaling/VerticalVmCpuScalingExample.java) that performs on-demand up and down allocation of VM resources such as Ram, Bandwidth and PEs (CPUs) ([#7](https://github.com/manoelcampos/cloudsim-plus/issues/7));
Manoel Campos's avatar
Manoel Campos committed
59
1. [Horizontal VM scaling](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/autoscaling/LoadBalancerByHorizontalVmScalingExample.java), allowing dynamic creation of VMs according to an overload condition. Such a condition is defined by a predicate that checks different VM resources usage such as CPU, RAM or BW ([#41](https://github.com/manoelcampos/cloudsim-plus/issues/41));
Manoel Campos's avatar
Manoel Campos committed
60
1. Enables power-aware simulations using regular classes such as `DatacenterSimple`, `HostSimple` and `VmSimple`. This way, it automatically allows creation of simulations that are both power- and network-aware by using the network version of such classes ([#45](https://github.com/manoelcampos/cloudsim-plus/issues/45));
61
1. [Parallel execution of simulations](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/ParallelSimulationsExample.java), allowing several simulations to be run simultaneously, in a isolated way, inside a multi-core computer ([#38](https://github.com/manoelcampos/cloudsim-plus/issues/38));
Manoel Campos's avatar
Manoel Campos committed
62
1. Delay creation of submitted VMs and [Cloudlets](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/DynamicCloudletsArrival1.java), enabling simulation of dynamic arrival of tasks ([#11](https://github.com/manoelcampos/cloudsim-plus/issues/11), [#23](https://github.com/manoelcampos/cloudsim-plus/issues/23)); 
Manoel Campos's avatar
Manoel Campos committed
63
64
1. [Allow dynamic creation of VMs and Cloudlets without requiring creation of Datacenter Brokers at runtime](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/dynamic/DynamicCreationOfVmsAndCloudletsExample.java), enabling VMs to be created on-demand according to arrived cloudlets ([#43](https://github.com/manoelcampos/cloudsim-plus/issues/43));
1. [Listeners](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/listeners) to enable simulation monitoring and creation of VMs and Cloudlets at runtime;
Manoel Campos's avatar
Manoel Campos committed
65
1. [Builders](/cloudsim-plus/src/main/java/org/cloudsimplus/builders/SimulationScenarioBuilder.java) to enable creating multiple simulation objects with same configuration;
66
1. It is a strongly object-oriented framework that creates relationships among classes and allows chained calls such as `cloudlet.getVm().getHost().getDatacenter()`. And guess what? You don't even have to worry about `NullPointerException` when making such a chained call because CloudSim Plus uses the [Null Object Design Pattern](https://en.wikipedia.org/wiki/Null_Object_pattern) to avoid that ([#10](https://github.com/manoelcampos/cloudsim-plus/issues/10));
67
1. Classes and interfaces to allow implementation of [heuristics](http://en.wikipedia.org/wiki/Heuristic) such as [Tabu Search](http://en.wikipedia.org/wiki/Tabu_search), [Simulated Annealing](http://en.wikipedia.org/wiki/Simulated_annealing), [Ant Colony Systems](http://en.wikipedia.org/wiki/Ant_colony_optimization_algorithms) and so on. See an [example using Simulated Annealing here](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/brokers/DatacenterBrokerHeuristicExample.java);
68
69
1. [Implementation of the Completely Fair Scheduler](https://en.wikipedia.org/wiki/Completely_Fair_Scheduler) used in recent versions of the Linux Kernel. See an example [here](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/LinuxCompletelyFairSchedulerExample.java) ([#58](https://github.com/manoelcampos/cloudsim-plus/issues/58));
1. Completely re-designed and reusable Network module. Totally refactored network examples to make them clear and easy to change ([#13](https://github.com/manoelcampos/cloudsim-plus/issues/13), [#49](https://github.com/manoelcampos/cloudsim-plus/issues/49), [#57](https://github.com/manoelcampos/cloudsim-plus/issues/57));
Manoel Campos's avatar
Manoel Campos committed
70
1. Enables the use of any regular `CloudletScheduler` with a `NetworkVm`, such as the `CloudletSchedulerTimeShared`, `CloudletSchedulerSpaceShared` or the new `CloudletSchedulerCompletelyFair`. The new `PacketScheduler` is used internally with all `CloudletSchedulers` to dispatch network packets when you are building a network simulation;
71
1. Simpler constructors to instantiate simulation objects, making it less confusing to use the framework. It applies the [Convention over Configuration principle (CoC)](https://en.wikipedia.org/wiki/Convention_over_configuration) to ask just mandatory parameters when instantiating objects ([#30](https://github.com/manoelcampos/cloudsim-plus/issues/30));
72
1. TableBuilder objects that are used in all examples and enable printing simulation results in different formats such as ASCII Table, CSV or HTML. It shows simulation results in perfectly aligned tables, including data units and additional data. Check the last line of the [BasicFirstExample](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/BasicFirstExample.java) constructor to see how it is easy to print results;
Manoel Campos's avatar
Manoel Campos committed
73
1. Throughout documentation update, improvement and extension;
74
1. Improved class hierarchy, modules and package structure that is easier to understand and follows the [Separation of Concerns principle (SoC)](https://en.wikipedia.org/wiki/Separation_of_concerns);
Manoel Campos's avatar
Manoel Campos committed
75
1. As it is usual to extend framework classes to provide some specific behaviors for your simulations, you will find a totally refactored code that follows clean code programming, [SOLID](https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)), [Design Patterns](https://en.wikipedia.org/wiki/Software_design_pattern) and several other software engineering principles and practices. This way, it will be easier to understand the code and implement the feature you want;
Manoel Campos's avatar
Manoel Campos committed
76
1. Integration Tests to increase framework accuracy by testing entire simulation scenarios;
77
1. Updated to Java 8 to provide some [Functional Programming](https://en.wikipedia.org/wiki/Functional_programming) features (such as the next one), using [Lambda Expressions](http://www.oracle.com/webfolder/technetwork/tutorials/obe/java/Lambda-QuickStart/index.html) and [Streams API](http://www.oracle.com/technetwork/articles/java/ma14-java-se-8-streams-2177646.html) to improve efficiency and make the code cleaner and easier to maintain;
78
1. <a id="exclusive-features-broker"></a> A [Functional](https://en.wikipedia.org/wiki/Functional_programming) `DatacenterBrokerSimple` class that enables changing, at runtime, policies for different goals. This dynamic behavior allows implementing specific policies, without requiring the creation of new `DatacenterBroker` classes (check [this example](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/brokers/CloudletToVmMappingBestFit.java)). Consider *P* the number of policies and *I* the number of implementations for each policy. For *P = 3* and *I = 2*, if you want to try all possible combinations of policies and implementations, without CloudSim Plus, it would be required to create 12 `DatacenterBroker` classes (*P* * *I^(P-1)*), instead of just using the existing one. Some of these behaviors which can be changed are:
Manoel Campos's avatar
Manoel Campos committed
79
80
81
82
    - selection of a Datacenter to place waiting VMs and a fallback Datacenter when a previous selected one fails in finding a suitable Host for a VM ([#28](https://github.com/manoelcampos/cloudsim-plus/issues/28)); 
    - selection of a VM to run each Cloudlet ([#25](https://github.com/manoelcampos/cloudsim-plus/issues/25));
    - definition of the time when an idle VM should be destroyed ([#99](https://github.com/manoelcampos/cloudsim-plus/issues/99));
    - sorting of requests to create submitted VMs and Cloudlets, defining priorities to create such objects ([#102](https://github.com/manoelcampos/cloudsim-plus/issues/102)). 
Manoel Campos's avatar
Manoel Campos committed
83
1. [Host Fault Injection Mechanism](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/HostFaultInjectionExample1.java) to enable injection of random failures into Hosts PEs: it injects failures into Host PEs and reallocates working PEs to running VMs. When all PEs from a Host fail, it starts clones of failed VMs to recovery from failure. This way, it is simulated the instantiation of VM snapshots into different Hosts ([#81](https://github.com/manoelcampos/cloudsim-plus/issues/81)).
Manoel Campos's avatar
Manoel Campos committed
84
1. [Creation of Hosts at Simulation Runtime](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/dynamic/DynamicHostCreation.java) to enable physical expansion of Datacenter capacity ([#124](https://github.com/manoelcampos/cloudsim-plus/issues/124)).
Manoel Campos's avatar
Manoel Campos committed
85
1. [Enables the simulation to keep running, waiting for dynamic and even random events such as the arrival of Cloudlets and VMs](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/dynamic/KeepSimulationRunningExample.java) ([#130](https://github.com/manoelcampos/cloudsim-plus/issues/130)).
86

Manoel Campos's avatar
Manoel Campos committed
87
# Project's Structure
88

Manoel Campos's avatar
Manoel Campos committed
89
90
CloudSim Plus has a simpler structure to make it ease to use and understand. It consists of 4 modules, 2 of which are new, as presented below.

91
![CloudSim Plus Modules](https://github.com/manoelcampos/cloudsim-plus/raw/master/docs/images/modules.png)
92

93
94
- [cloudsim-plus](/cloudsim-plus): the CloudSim Plus cloud simulation framework API, which is used by all other modules. 
  It is the main and only required module you need to write cloud simulations. 
95
- [cloudsim-plus-examples](/cloudsim-plus-examples): includes a series of different examples, since minimal simulation scenarios using basic 
Manoel Campos's avatar
Manoel Campos committed
96
  CloudSim Plus features, to complex scenarios using workloads from trace files or Vm migration examples. This is an excellent starting point for learning how to build cloud simulations using CloudSim Plus.
97
- [cloudsim-plus-testbeds](/cloudsim-plus-testbeds): enables implementation of simulation testbeds in a repeatable manner, 
98
  allowing a researcher to execute several simulation runs for a given experiment and collect statistical data using a scientific approach. 
99
- [cloudsim-plus-benchmarks](/cloudsim-plus-benchmarks): a new module used just internally to implement micro benchmarks to assess framework performance.
100

Manoel Campos's avatar
Manoel Campos committed
101
102
It also has a better package organization, improving [Separation of Concerns (SoC)](https://en.wikipedia.org/wiki/Separation_of_concerns) and making it easy to know where a desired class is and what is inside each package. The figure below presents the new package organization. The dark yellow packages are new in CloudSim Plus and include its exclusive interfaces and classes. The light yellow ones were introduced just to better organize existing CloudSim classes and interfaces. 

103
![CloudSim Plus Packages](https://github.com/manoelcampos/cloudsim-plus/raw/master/docs/images/package-structure-reduced.png)
104

105

Manoel Campos's avatar
Manoel Campos committed
106
107
<p align="right"><a href="#top">:arrow_up:</a></p>

Manoel Campos's avatar
Manoel Campos committed
108
# How to Use CloudSim Plus 
Manoel Campos's avatar
Manoel Campos committed
109
There are 3 ways to use CloudSim Plus. It can be downloaded and executed: (i) directly from some IDE; (ii) from the command line; or (iii) from [Maven Central](https://maven-badges.herokuapp.com/maven-central/org.cloudsimplus/cloudsim-plus) once you include it as a dependency inside your own project.
110

111
You can watch the video below ([high quality version here](https://youtu.be/k2enNoxTYVw)) or follow the instructions in one of the next subsections.
112

113
![Downloading CloudSim Plus and running Examples using NetBeans](https://github.com/manoelcampos/cloudsim-plus/raw/master/docs/images/cloudsim-plus-netbeans.gif)
114

Manoel Campos's avatar
Manoel Campos committed
115
## Via Command Line
116
Considering that you have [git](https://git-scm.com) and [maven](http://maven.apache.org) installed on your operating system, 
Manoel Campos's avatar
Manoel Campos committed
117
download the project source by cloning the repository issuing the command `git clone https://github.com/manoelcampos/cloudsim-plus.git` 
118
at a terminal. 
119

romantic668's avatar
romantic668 committed
120
The project has a [bash script](script/bootstrap.sh) you can use to build and run CloudSim Plus examples. 
121
This is a script for Unix-like systems such as Linux, FreeBDS and Mac OSX.
122

123
To run some example type the command: `sh script/bootstrap.sh package.ExampleClassName`.
124
For instance, to run the `CloudSimExample0` you can type: `sh script/bootstrap.sh org.cloudbus.cloudsim.examples.CloudSimExample0`. 
125

126
The script checks if it is required to build the project, using maven in this case, making sure to download all dependencies. 
127
128
To see which examples are available, just navigate through the [examples directory](/cloudsim-plus-examples/src/main/java/).
To check more script options, run it without any parameter.  
129
 
Manoel Campos's avatar
Manoel Campos committed
130
## By Means of an IDE
131
The easiest way to use the project is relying on some IDE such as [NetBeans](http://netbeans.org), [Eclipse](http://eclipse.org) 
132
or [IntelliJ IDEA](http://jetbrains.com/idea/).
133
Below are the steps to start using the project:
134

135
- Download the project sources by using: the download button on top of this page; your own IDE for it; or the command line as described above.
136
- Open/import the project in your IDE:
137
138
    - For NetBeans, just use the "Open project" menu and select the directory where the project was downloaded/cloned.
    - For Eclipse or IntelliJ IDEA, 
139
      you have to import the project selecting the folder where the project was cloned. 
140
- Inside the opened/imported project you will have the cloudsim-plus and cloudsim-plus-examples modules. 
141
142
  The cloudsim-plus module is where the simulator source code is, that usually you don't have to change, unless you want to contribute to the project. 
  The cloudsim-plus-examples is where you can start.
143
144
- Open the cloudsim-plus-examples module. The most basic examples are in the root of the org.cloudbus.cloudsim.examples package. 
  You can run any one of the classes in this package to get a specific example. 
145
146
- If you want to build your own simulations, the easiest way is to create another class inside this module.

Manoel Campos's avatar
Manoel Campos committed
147
148
<a id="maven"></a>

Manoel Campos's avatar
Manoel Campos committed
149
## Adding it as a Maven Dependency into Your Own Project
150
151

You can add CloudSim Plus API module, that is the only one required to build simulations, as a dependency inside the pom.xml file or your own maven project,
Manoel Campos's avatar
Manoel Campos committed
152
as presened below (check if the informed version is the latest one). This way you can start building your simulations from scratch.
153
154
155
156
157

```xml
<dependency>
    <groupId>org.cloudsimplus</groupId>
    <artifactId>cloudsim-plus</artifactId>
158
159
    <!-- Set a specific version or use the latest one -->
    <version>LATEST</version>
160
161
162
</dependency>
```

163
164
<p align="right"><a href="#top">:arrow_up:</a></p>

Manoel Campos's avatar
Manoel Campos committed
165
# A Minimal and Complete Simulation Example
166

167
In order to build a simulation scenario you have to create, at least: 
168
- a datacenter with a list of physical machines (Hosts); 
169
- a broker that allows submission of VMs and Cloudlets to be executed, on behalf of a given customer, into the cloud infrastructure; 
170
- a list of customer's virtual machines (VMs); 
171
- and a list of customer's cloudlets (objects that model resource requirements of different applications).
172

Manoel Campos's avatar
Manoel Campos committed
173
Due to the simplicity provided by CloudSim Plus, all the code to create a minimal simulation scenario can be as simple as presented below.
174
A more adequate and reusable example is available
175
[here](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/BasicFirstExample.java),
176
177
together with [other examples](/cloudsim-plus-examples). Specific examples of CloudSim Plus, showing several
new exclusive features and advanced scenarios, can be found [here](/cloudsim-plus-examples/src/main/java/org/cloudsimplus/examples/). 
178
179

```java
Manoel Campos's avatar
Manoel Campos committed
180
//Creates a CloudSim object to initialize the simulation.
181
182
CloudSim cloudsim = new CloudSim();

183
/*Creates a Broker that will act on behalf of a cloud user (customer).*/
184
185
DatacenterBroker broker0 = new DatacenterBrokerSimple(cloudsim);

186
//Creates a list of Hosts, each host with a specific list of CPU cores (PEs).
187
188
List<Host> hostList = new ArrayList<>(1);
List<Pe> hostPes = new ArrayList<>(1);
189
hostPes.add(new PeSimple(20000, new PeProvisionerSimple()));
190
191
192
193
194
195
196
long ram = 10000; //in Megabytes
long storage = 100000; //in Megabytes
long bw = 100000; //in Megabits/s
Host host0 = new HostSimple(ram, bw, storage, hostPes);
host0.setRamProvisioner(new ResourceProvisionerSimple())
      .setBwProvisioner(new ResourceProvisionerSimple())
      .setVmScheduler(new VmSchedulerSpaceShared());
197
198
hostList.add(host0);

Manoel Campos's avatar
Manoel Campos committed
199
//Creates a Datacenter with a list of Hosts.
Manoel Campos's avatar
Manoel Campos committed
200
Datacenter dc0 = new DatacenterSimple(cloudsim, hostList, new VmAllocationPolicySimple());
201
202

//Creates VMs to run applications.
203
List<Vm> vmList = new ArrayList<>(1);
204
Vm vm0 = new VmSimple(0, 1000, 1);
205
206
vm0.setRam(1000).setBw(1000).setSize(1000)
   .setCloudletScheduler(new CloudletSchedulerSpaceShared());
207
vmList.add(vm0);
208

209
//Creates Cloudlets that represent applications to be run inside a VM.
Manoel Campos's avatar
Manoel Campos committed
210
List<Cloudlet> cloudletList = new ArrayList<>(1);
211
Cloudlet cloudlet0 = new CloudletSimple(0, 10000, 1);
Manoel Campos's avatar
Manoel Campos committed
212
cloudlet0.setUtilizationModel(new UtilizationModelFull());
Manoel Campos's avatar
Manoel Campos committed
213
cloudletList.add(cloudlet0);
214
Cloudlet cloudlet1 = new CloudletSimple(1, 10000, 1);
Manoel Campos's avatar
Manoel Campos committed
215
cloudlet1.setUtilizationModel(new UtilizationModelFull());
Manoel Campos's avatar
Manoel Campos committed
216
cloudletList.add(cloudlet1);
217
218

broker0.submitVmList(vmList);
Manoel Campos's avatar
Manoel Campos committed
219
broker0.submitCloudletList(cloudletList);
220

221
222
/*Starts the simulation and waits all cloudlets to be executed, automatically
stopping when there is no more events to process.*/
223
cloudsim.start();
224

225
/*Prints results when the simulation is over
Manoel Campos's avatar
Manoel Campos committed
226
(you can use your own code here to print what you want from this cloudlet list).*/
227
new CloudletsTableBuilder(broker0.getCloudletFinishedList()).build();
228
229
```

Manoel Campos's avatar
Manoel Campos committed
230
The presented results are structured and clear to allow better understanding. For example, the image below shows the output for a simulation with two cloudlets (applications).
231
![Simulation Results](https://github.com/manoelcampos/cloudsim-plus/raw/master/docs/images/simulation-results.png)
232

233
234
<p align="right"><a href="#top">:arrow_up:</a></p>

235
# Documentation and Help
Manoel Campos's avatar
Manoel Campos committed
236

237
238
The project documentation originated from CloudSim was entirely updated and extended. 
You can see the javadoc documentation for classes and their elements directly on your IDE.
239

240
The documentation is available online at [ReadTheDocs](http://cloudsimplus.rtfd.io/en/latest/?badge=latest), which includes a FAQ and guides.
Manoel Campos's avatar
Manoel Campos committed
241
CloudSim Plus has extended documentation of classes and interfaces and also includes extremely helpful
242
package documentation that can be viewed directly on your IDE or at the link provided above.
243
Such a package documentation gives a general overview of the classes used to build a cloud simulation.
244

245
246
A Google Group forum is also available at <https://groups.google.com/group/cloudsim-plus>.
See the [publications](#publications) section to access published CloudSim Plus papers.
247

248
249
250
<p align="right"><a href="#top">:arrow_up:</a></p>

<a id="why-care"></a>
Manoel Campos's avatar
Manoel Campos committed
251

252
# Why should I care about this CloudSim fork? I just want to build my simulations. :neutral_face:
Manoel Campos's avatar
Manoel Campos committed
253
Well, the design of the tool has a direct impact when you need to extend it to include some feature required for your simulations. 
254
255
The simulator has a set of classes that implement interfaces such as `VmScheduler`, `CloudletScheduler`, `VmAllocationPolicy`, `ResourceProvisioner`, 
`UtilizationModel`, `PowerModel` and `DatacenterBroker` and provide basic algorithms for different goals. 
256
For instance, the `VmAllocationPolicySimple` class implements a Worst Fit
Manoel Campos's avatar
Manoel Campos committed
257
policy that selects the PM which less processor cores in use to host a VM and, in fact, it is the only policy available. 
258

259
260
Usually you have to write your own implementations of these classes, such as a Best Fit `VmAllocationPolicy`, 
a resource `UtilizationModel` with an upper threshold or a `DatacenterBroker` that selects the best `Datacenter` to submit a VM.
261

262
Several software engineering principles aim to ease the task of creating new classes to implement those features. 
263
They also try to avoid forcing you to change core classes of the simulator in order to introduce a feature you need to implement.
Manoel Campos's avatar
Manoel Campos committed
264
**Changing these core classes just to implement a particular feature which will be used only in your simulations is a bad practice, since you will not be able to automatically update your project to new versions of the simulator, without losing your changes or struggling to fix merge conflicts.**
265

266
As we have seen in forums that we've attended, many times users have to perform these changes in core classes 
Manoel Campos's avatar
Manoel Campos committed
267
just to implement some specific features they need. We think those problems are enough reasons that show the need of a new re-engineered version of the simulator.  
268

269
270
271
<p align="right"><a href="#top">:arrow_up:</a></p>

<a id="why-another-fork"></a>
Manoel Campos's avatar
Manoel Campos committed
272

Manoel Campos's avatar
Manoel Campos committed
273
# But why an independent CloudSim fork? :unamused:
Manoel Campos's avatar
Manoel Campos committed
274
The original CloudSim moved on to a new major release, introducing a completely new set of classes to provide Container as a Service (CaaS) simulations, 
Manoel Campos's avatar
Manoel Campos committed
275
before the changes proposed here being merged to the official repository. This way, all the work performed here was not incorporated to allow this new CaaS module to be developed using this redesigned version. Unfortunately, there are several months of hard work that would need to be replicated to merge both projects. In reason of that, CloudSim Plus was born as an independent fork, following its own way and philosophies.
276

277
278
279
<p align="right"><a href="#top">:arrow_up:</a></p>

<a id="differences"></a>
Manoel Campos's avatar
Manoel Campos committed
280

Manoel Campos's avatar
Manoel Campos committed
281
# What are the practical differences of using CloudSim Plus instead of CloudSim? How can I update my simulations to use CloudSim Plus?
282

Manoel Campos's avatar
Manoel Campos committed
283
It's much easier to use CloudSim Plus. A complete, side-by-side [comparison between CloudSim and CloudSim Plus Java simulation scenarios is available here](http://cloudsimplus.org/docs/CloudSim-and-CloudSimPlus-Comparison.html).
284

Manoel Campos's avatar
Manoel Campos committed
285
286
To update your simulations to use the CloudSim Plus you have to change the way that some objects are instantiated, because some new interfaces were introduced to follow the "program to an interface, not an implementation" recommendation and also to increase [abstraction](https://en.wikipedia.org/wiki/Abstraction_(software_engineering)). 
These new interfaces were also crucial to implement the [Null Object Pattern](https://en.wikipedia.org/wiki/Null_Object_pattern) to try avoiding `NullPointerException`s.
287

288
The initialization of the simulation is not performed by the static `CloudSim.startSimulation` method anymore, which required a lot of parameters.
289
Now you have just to instantiate a `CloudSim` object using the default, no-arguments constructor, as shown below. This instance is used in the constructor of `DatacenterBroker` and `Datacenter` objects: 
290
291
292
293
294

```java
CloudSim cloudsim = new CloudSim();
```

Manoel Campos's avatar
Manoel Campos committed
295
The classes `Datacenter`, `DatacenterCharacteristics`, `Host`, `Pe`, `Vm` and `Cloudlet` were renamed due to 
296
297
298
the introduction of interfaces with these same names. Now all these classes have a suffix *Simple* 
(as already defined for some previous classes such as `PeProvisionerSimple` and `VmAllocationPolicySimple`). 
For instance, to instantiate a `Cloudlet` you have to execute a code such as:
299

300
301
302
303
 ```java
CloudletSimple cloudlet = new CloudletSimple(required, parameters, here);
```   

304
However, since these interfaces were introduced in order to also enable the creation of different cloudlet classes, 
305
the recommendation is to declare your object using the interface, not the class: 
306
307
308
309
310
 
 ```java
Cloudlet cloudlet = new CloudletSimple(required, parameters, here);
```   

311
312
313
The method `setBrokerId(int userId)` from `Vm` and `Cloudlet` were refactored to `setBroker(DatacenterBroker broker)`,
now requiring a `DatacenterBroker` instead of just an int ID which may be even nonexistent.

Manoel Campos's avatar
Manoel Campos committed
314
315
You don't need to explicitly create a `DatacenterCharacteristics` anymore. Such object is created internally when a `Datacenter` is created.
A `VmAllocationPolicy` doesn't require any parameter at all. A `Datacenter` doesn't require a name, storage list and scheduling interval too.
316
The name will be automatically defined. It and all the other parameter can be set further using the respective setter methods.
Manoel Campos's avatar
Manoel Campos committed
317
Now it is just required a `CloudSim`, a `Host` list and a `VmAllocationPolicy` instance.
318

319
```java
Manoel Campos's avatar
Manoel Campos committed
320
Datacenter dc0 = new DatacenterSimple(cloudsim, hostList, new VmAllocationPolicySimple());
321
322
```

323
324
The way you instantiate a host has changed too. The classes `RamProvisionerSimple` and `BwProvisionerSimple` don't exist anymore. Now you just have the generic class `ResourceProvisionerSimple` and you can just use its default no-args constructor. RAM and bandwidth capacity of the host now are given in the constructor, as it already was for storage. A `VmScheduler` constructor doesn't require any parameter. You don't need to set an ID for each Host, since
if one is not given, when the List of hosts is attached to a Datacenter, it will generate an ID for those hosts. Instantiating a host should be now similar to:
325
326

```java
327
328
329
long ram = 20480; //in MB
long bw = 1000000; //in Megabits/s
long storage = 1000000; //in MB
330
331
332
Host host = new HostSimple(ram, bw, storage, pesList);
host.setRamProvisioner(new ResourceProvisionerSimple())
    .setBwProvisioner(new ResourceProvisionerSimple())
333
    .setVmScheduler(new VmSchedulerTimeShared());
334
``` 
335

336
Additionally, the interface `Storage` was renamed to `FileStorage` and its implementations are `SanStorage` and `HarddriveStorage`, that can be used as before. Finally, since the packages were reorganized, you have to adjust them. However, use your IDE to correct the imports for you. A complete and clear example was presented in the <a href="#a-minimal-and-complete-simulation-example">Examples</a> section above.
337

338
339
<p align="right"><a href="#top">:arrow_up:</a></p>

Manoel Campos's avatar
Manoel Campos committed
340
# General Features of the Framework
341

Manoel Campos's avatar
Manoel Campos committed
342
343
344
345
346
347
348
* Support for modeling and simulation of large scale Cloud computing data centers.
* Support for modeling and simulation of virtualized server hosts, with customizable policies for provisioning host resources to virtual machines.
* Support for modeling and simulation of energy-aware computational resources.
* Support for modeling and simulation of data center network topologies and message-passing applications.
* Support for modeling and simulation of federated clouds.
* Support for dynamic insertion of simulation elements, stop and resume of simulation.
* Support for user-defined policies for allocation of hosts to virtual machines and policies for allocation of host resources to virtual machines.
349

350
<p align="right"><a href="#top">:arrow_up:</a></p>
351

352
<a id="publications"></a>
Manoel Campos's avatar
Manoel Campos committed
353

354
# CloudSim Plus Publications
Manoel Campos's avatar
Manoel Campos committed
355
356
357

1. [M. C. Silva Filho, R. L. Oliveira, C. C. Monteiro, P. R. M. Inácio, and M. M. Freire, “CloudSim Plus: a Cloud Computing Simulation Framework Pursuing Software Engineering Principles for Improved Modularity, Extensibility and Correctness,” in IFIP/IEEE International Symposium on Integrated Network Management, 2017, p. 7](https://doi.org/10.23919/INM.2017.7987304). If you are using CloudSim Plus in your research, please make sure you cite that paper. You can check the paper presentation [here](http://cloudsimplus.org/docs/presentation/).
2. White Paper ["CloudSim Plus: A Modern Java 8 Framework for Modeling and Simulation of Cloud Computing Infrastructures and Services"](https://github.com/manoelcampos/cloudsim-plus/blob/master/docs/cloudsim-plus-white-paper.pdf)
358
  
359
360
<p align="right"><a href="#top">:arrow_up:</a></p>
  
361
362
# License

363
This project is licensed under [GNU GPLv3](http://www.gnu.org/licenses/gpl-3.0), as defined inside CloudSim 3 source files.
Manoel Campos's avatar
Manoel Campos committed
364

365
366
<p align="right"><a href="#top">:arrow_up:</a></p>

Manoel Campos's avatar
Manoel Campos committed
367
# Contributing
Manoel Campos's avatar
Manoel Campos committed
368

Manoel Campos's avatar
Manoel Campos committed
369
You are welcome to contribute to the project. However, make sure you read the [contribution guide](CONTRIBUTING.md) before starting. The guide provides information on the different ways you can contribute, such as by requesting a feature, reporting an issue, fixing a bug or providing some new feature.
370
371

<p align="right"><a href="#top">:arrow_up:</a></p>