Documentation of package org.cloudbus.cloudsim.power improved.

This was the last package updated from the 12 CloudSim packages.

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/Host.java

@@ -65,7 +65,7 @@ public class Host {
 	 * @param ramProvisioner the ram provisioner
 	 * @param bwProvisioner the bw provisioner
 	 * @param storage the storage capacity
-	 * @param peList the pe list
+	 * @param peList the host's PEs list
 	 * @param vmScheduler the vm scheduler
 	 */
 	public Host(

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/HostDynamicWorkload.java

@@ -18,7 +18,7 @@ import org.cloudbus.cloudsim.provisioners.BwProvisioner;
 import org.cloudbus.cloudsim.provisioners.RamProvisioner;
 
 /**
- * The class of a host supporting dynamic workloads and performance degradation.
+ * A host supporting dynamic workloads and performance degradation.
  * 
  * @author Anton Beloglazov
  * @since CloudSim Toolkit 2.0
@@ -40,8 +40,8 @@ public class HostDynamicWorkload extends Host {
 	 * @param id the id
 	 * @param ramProvisioner the ram provisioner
 	 * @param bwProvisioner the bw provisioner
-	 * @param storage the storage
-	 * @param peList the pe list
+	 * @param storage the storage capacity
+	 * @param peList the host's PEs list
 	 * @param vmScheduler the VM scheduler
 	 */
 	public HostDynamicWorkload(

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/VmAllocationPolicy.java

@@ -13,8 +13,9 @@ import java.util.Map;
 
 /**
  * VmAllocationPolicy is an abstract class that represents the provisioning policy of hosts to
- * virtual machines in a Datacenter. It supports two-stage commit of reservation of hosts: first, we
- * reserve the host and, once commited by the user, it is effectivelly allocated to he/she
+ * virtual machines in a Datacenter. It allocates hosts for placing VMs. 
+ * It supports two-stage commit of reservation of hosts: first, we
+ * reserve the host and, once committed by the user, it is effectively allocated to he/she.
  * 
  * @author Rodrigo N. Calheiros
  * @author Anton Beloglazov

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerDatacenter.java

@@ -40,25 +40,24 @@ import org.cloudbus.cloudsim.core.predicates.PredicateType;
  */
 public class PowerDatacenter extends Datacenter {
 
-	/** The power. */
+	/** The datacenter consumed power. */
 	private double power;
 
-	/** The disable migrations. */
+	/** Indicates if migrations are disabled or not. */
 	private boolean disableMigrations;
 
-	/** The cloudlet submited. */
+	/** The last time submitted cloudlets were processed. */
 	private double cloudletSubmitted;
 
-	/** The migration count. */
+	/** The VM migration count. */
 	private int migrationCount;
 
 	/**
-	 * Instantiates a new datacenter.
+	 * Instantiates a new PowerDatacenter.
 	 * 
-	 * @param name the name
-	 * @param characteristics the res config
+	 * @param name the datacenter name
+	 * @param characteristics the datacenter characteristics
 	 * @param schedulingInterval the scheduling interval
-	 * @param utilizationBound the utilization bound
 	 * @param vmAllocationPolicy the vm provisioner
 	 * @param storageList the storage list
 	 * @throws Exception the exception
@@ -77,14 +76,6 @@ public class PowerDatacenter extends Datacenter {
 		setMigrationCount(0);
 	}
 
-	/**
-	 * Updates processing of each cloudlet running in this PowerDatacenter. It is necessary because
-	 * Hosts and VirtualMachines are simple objects, not entities. So, they don't receive events and
-	 * updating cloudlets inside them must be called from the outside.
-	 * 
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	protected void updateCloudletProcessing() {
 		if (getCloudletSubmitted() == -1 || getCloudletSubmitted() == CloudSim.clock()) {
@@ -155,6 +146,12 @@ public class PowerDatacenter extends Datacenter {
 	 * Update cloudet processing without scheduling future events.
 	 * 
 	 * @return the double
+         * @see #updateCloudetProcessingWithoutSchedulingFutureEventsForce() 
+         * @todo There is an inconsistence in the return value of this
+         * method with return value of similar methods
+         * such as {@link #updateCloudetProcessingWithoutSchedulingFutureEventsForce()},
+         * that returns {@link Double#MAX_VALUE} by default.
+         * The current method returns 0 by default.
 	 */
 	protected double updateCloudetProcessingWithoutSchedulingFutureEvents() {
 		if (CloudSim.clock() > getLastProcessTime()) {
@@ -166,7 +163,8 @@ public class PowerDatacenter extends Datacenter {
 	/**
 	 * Update cloudet processing without scheduling future events.
 	 * 
-	 * @return the double
+	 * @return expected time of completion of the next cloudlet in all VMs of all hosts or
+	 *         {@link Double#MAX_VALUE} if there is no future events expected in this host
 	 */
 	protected double updateCloudetProcessingWithoutSchedulingFutureEventsForce() {
 		double currentTime = CloudSim.clock();
@@ -284,7 +282,7 @@ public class PowerDatacenter extends Datacenter {
 	/**
 	 * Checks if PowerDatacenter is in migration.
 	 * 
-	 * @return true, if PowerDatacenter is in migration
+	 * @return true, if PowerDatacenter is in migration; false otherwise
 	 */
 	protected boolean isInMigration() {
 		boolean result = false;
@@ -298,18 +296,18 @@ public class PowerDatacenter extends Datacenter {
 	}
 
 	/**
-	 * Checks if is disable migrations.
+	 * Checks if migrations are disabled.
 	 * 
-	 * @return true, if is disable migrations
+	 * @return true, if  migrations are disable; false otherwise
 	 */
 	public boolean isDisableMigrations() {
 		return disableMigrations;
 	}
 
 	/**
-	 * Sets the disable migrations.
+	 * Disable or enable migrations.
 	 * 
-	 * @param disableMigrations the new disable migrations
+	 * @param disableMigrations true to disable migrations; false to enable
 	 */
 	public void setDisableMigrations(boolean disableMigrations) {
 		this.disableMigrations = disableMigrations;
@@ -325,7 +323,7 @@ public class PowerDatacenter extends Datacenter {
 	}
 
 	/**
-	 * Sets the cloudlet submited.
+	 * Sets the cloudlet submitted.
 	 * 
 	 * @param cloudletSubmitted the new cloudlet submited
 	 */

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerDatacenterBroker.java

@@ -14,7 +14,7 @@ import org.cloudbus.cloudsim.core.CloudSimTags;
 import org.cloudbus.cloudsim.core.SimEvent;
 
 /**
- * A broker for the power package.
+ * A power-aware {@link DatacenterBroker}.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>
@@ -32,9 +32,9 @@ import org.cloudbus.cloudsim.core.SimEvent;
 public class PowerDatacenterBroker extends DatacenterBroker {
 
 	/**
-	 * Instantiates a new power datacenter broker.
+	 * Instantiates a new PowerDatacenterBroker.
 	 * 
-	 * @param name the name
+	 * @param name the name of the broker
 	 * @throws Exception the exception
 	 */
 	public PowerDatacenterBroker(String name) throws Exception {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerDatacenterNonPowerAware.java

@@ -21,7 +21,7 @@ import org.cloudbus.cloudsim.core.CloudSimTags;
 import org.cloudbus.cloudsim.core.predicates.PredicateType;
 
 /**
- * PowerDatacenterNonPowerAware is a class that represents a non-power aware data center in the
+ * PowerDatacenterNonPowerAware is a class that represents a <b>non-power</b> aware data center in the
  * context of power-aware simulations.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
@@ -42,10 +42,9 @@ public class PowerDatacenterNonPowerAware extends PowerDatacenter {
 	/**
 	 * Instantiates a new datacenter.
 	 * 
-	 * @param name the name
-	 * @param characteristics the res config
+	 * @param name the datacenter name
+	 * @param characteristics the datacenter characteristics
 	 * @param schedulingInterval the scheduling interval
-	 * @param utilizationBound the utilization bound
 	 * @param vmAllocationPolicy the vm provisioner
 	 * @param storageList the storage list
 	 * 
@@ -60,14 +59,6 @@ public class PowerDatacenterNonPowerAware extends PowerDatacenter {
 		super(name, characteristics, vmAllocationPolicy, storageList, schedulingInterval);
 	}
 
-	/**
-	 * Updates processing of each cloudlet running in this PowerDatacenter. It is necessary because
-	 * Hosts and VirtualMachines are simple objects, not entities. So, they don't receive events and
-	 * updating cloudlets inside them must be called from the outside.
-	 * 
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	protected void updateCloudletProcessing() {
 		if (getCloudletSubmitted() == -1 || getCloudletSubmitted() == CloudSim.clock()) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerHost.java

@@ -35,17 +35,17 @@ import org.cloudbus.cloudsim.provisioners.RamProvisioner;
  */
 public class PowerHost extends HostDynamicWorkload {
 
-	/** The power model. */
+	/** The power model used by the host. */
 	private PowerModel powerModel;
 
 	/**
-	 * Instantiates a new host.
+	 * Instantiates a new PowerHost.
 	 * 
-	 * @param id the id
+	 * @param id the id of the host
 	 * @param ramProvisioner the ram provisioner
 	 * @param bwProvisioner the bw provisioner
-	 * @param storage the storage
-	 * @param peList the pe list
+	 * @param storage the storage capacity
+	 * @param peList the host's PEs list
 	 * @param vmScheduler the VM scheduler
 	 */
 	public PowerHost(
@@ -70,10 +70,11 @@ public class PowerHost extends HostDynamicWorkload {
 	}
 
 	/**
-	 * Gets the power. For this moment only consumed by all PEs.
+	 * Gets the current power consumption of the host. For this moment only consumed by all PEs.
 	 * 
-	 * @param utilization the utilization
-	 * @return the power
+	 * @param utilization the utilization percentage (between [0 and 1]) of a resource that
+         * is critical for power consumption
+	 * @return the power consumption
 	 */
 	protected double getPower(double utilization) {
 		double power = 0;
@@ -105,8 +106,8 @@ public class PowerHost extends HostDynamicWorkload {
 	/**
 	 * Gets the energy consumption using linear interpolation of the utilization change.
 	 * 
-	 * @param fromUtilization the from utilization
-	 * @param toUtilization the to utilization
+	 * @param fromUtilization the initial utilization percentage
+	 * @param toUtilization the final utilization percentage
 	 * @param time the time
 	 * @return the energy
 	 */

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerHostUtilizationHistory.java

@@ -18,7 +18,7 @@ import org.cloudbus.cloudsim.provisioners.RamProvisioner;
 import org.cloudbus.cloudsim.util.MathUtil;
 
 /**
- * The class of a host that stores its CPU utilization history. The history is used by VM allocation
+ * A host that stores its CPU utilization percentage history. The history is used by VM allocation
  * and selection policies.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
@@ -37,15 +37,15 @@ import org.cloudbus.cloudsim.util.MathUtil;
 public class PowerHostUtilizationHistory extends PowerHost {
 
 	/**
-	 * Instantiates a new power host utilization history.
+	 * Instantiates a new PowerHostUtilizationHistory.
 	 * 
-	 * @param id the id
+	 * @param id the host id
 	 * @param ramProvisioner the ram provisioner
 	 * @param bwProvisioner the bw provisioner
-	 * @param storage the storage
-	 * @param peList the pe list
+	 * @param storage the storage capacity
+	 * @param peList the host's PEs list
 	 * @param vmScheduler the vm scheduler
-	 * @param powerModel the power model
+	 * @param powerModel the power consumption model
 	 */
 	public PowerHostUtilizationHistory(
 			int id,
@@ -59,9 +59,9 @@ public class PowerHostUtilizationHistory extends PowerHost {
 	}
 
 	/**
-	 * Gets the host utilization history.
+	 * Gets the host CPU utilization percentage history.
 	 * 
-	 * @return the host utilization history
+	 * @return the host CPU utilization percentage history
 	 */
 	protected double[] getUtilizationHistory() {
 		double[] utilizationHistory = new double[PowerVm.HISTORY_LENGTH];

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVm.java

@@ -17,7 +17,7 @@ import org.cloudbus.cloudsim.core.CloudSim;
 import org.cloudbus.cloudsim.util.MathUtil;
 
 /**
- * The class of a VM that stores its CPU utilization history. The history is used by VM allocation
+ * A class of VM that stores its CPU utilization percentage history. The history is used by VM allocation
  * and selection policies.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
@@ -38,17 +38,18 @@ public class PowerVm extends Vm {
 	/** The Constant HISTORY_LENGTH. */
 	public static final int HISTORY_LENGTH = 30;
 
-	/** The utilization history. */
+	/** The CPU utilization percentage history. */
 	private final List<Double> utilizationHistory = new LinkedList<Double>();
 
-	/** The previous time. */
+	/** The previous time that cloudlets were processed. */
 	private double previousTime;
 
-	/** The scheduling interval. */
+	/** The scheduling interval to update the processing of cloudlets
+         * running in this VM. */
 	private double schedulingInterval;
 
 	/**
-	 * Instantiates a new power vm.
+	 * Instantiates a new PowerVm.
 	 * 
 	 * @param id the id
 	 * @param userId the user id
@@ -78,18 +79,6 @@ public class PowerVm extends Vm {
 		setSchedulingInterval(schedulingInterval);
 	}
 
-	/**
-	 * Updates the processing of cloudlets running on this VM.
-	 * 
-	 * @param currentTime current simulation time
-	 * @param mipsShare array with MIPS share of each Pe available to the scheduler
-	 * 
-	 * @return time predicted completion time of the earliest finishing cloudlet, or 0 if there is
-	 * 		no next events
-	 * 
-	 * @pre currentTime >= 0
-	 * @post $none
-	 */
 	@Override
 	public double updateVmProcessing(final double currentTime, final List<Double> mipsShare) {
 		double time = super.updateVmProcessing(currentTime, mipsShare);
@@ -106,7 +95,7 @@ public class PowerVm extends Vm {
 	/**
 	 * Gets the utilization MAD in MIPS.
 	 * 
-	 * @return the utilization mean in MIPS
+	 * @return the utilization MAD in MIPS
 	 */
 	public double getUtilizationMad() {
 		double mad = 0;
@@ -168,9 +157,9 @@ public class PowerVm extends Vm {
 	}
 
 	/**
-	 * Adds the utilization history value.
+	 * Adds a CPU utilization percentage history value.
 	 * 
-	 * @param utilization the utilization
+	 * @param utilization the CPU utilization percentage to add
 	 */
 	public void addUtilizationHistoryValue(final double utilization) {
 		getUtilizationHistory().add(0, utilization);
@@ -180,9 +169,9 @@ public class PowerVm extends Vm {
 	}
 
 	/**
-	 * Gets the utilization history.
+	 * Gets the CPU utilization percentage history.
 	 * 
-	 * @return the utilization history
+	 * @return the CPU utilization percentage history
 	 */
 	protected List<Double> getUtilizationHistory() {
 		return utilizationHistory;

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmAllocationPolicyAbstract.java

@@ -19,7 +19,7 @@ import org.cloudbus.cloudsim.VmAllocationPolicy;
 import org.cloudbus.cloudsim.core.CloudSim;
 
 /**
- * The class of an abstract power-aware VM allocation policy.
+ * An abstract power-aware VM allocation policy.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>
@@ -36,11 +36,12 @@ import org.cloudbus.cloudsim.core.CloudSim;
  */
 public abstract class PowerVmAllocationPolicyAbstract extends VmAllocationPolicy {
 
-	/** The vm table. */
+	/** The map map where each key is a VM id and
+         * each value is the host where the VM is placed. */
 	private final Map<String, Host> vmTable = new HashMap<String, Host>();
 
 	/**
-	 * Instantiates a new power vm allocation policy abstract.
+	 * Instantiates a new PowerVmAllocationPolicyAbstract.
 	 * 
 	 * @param list the list
 	 */
@@ -73,10 +74,10 @@ public abstract class PowerVmAllocationPolicyAbstract extends VmAllocationPolicy
 	}
 
 	/**
-	 * Find host for vm.
+	 * Finds the first host that has enough resources to host a given VM.
 	 * 
-	 * @param vm the vm
-	 * @return the power host
+	 * @param vm the vm to find a host for it
+	 * @return the first host found that can host the VM
 	 */
 	public PowerHost findHostForVm(Vm vm) {
 		for (PowerHost host : this.<PowerHost> getHostList()) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmAllocationPolicyMigrationInterQuartileRange.java

@@ -16,7 +16,8 @@ import org.cloudbus.cloudsim.Vm;
 import org.cloudbus.cloudsim.util.MathUtil;
 
 /**
- * The Inter Quartile Range (IQR) VM allocation policy.
+ * A VM allocation policy that uses Inter Quartile Range (IQR)  to compute
+ * a dynamic threshold in order to detect host over utilization.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>
@@ -34,14 +35,29 @@ import org.cloudbus.cloudsim.util.MathUtil;
 public class PowerVmAllocationPolicyMigrationInterQuartileRange extends
 		PowerVmAllocationPolicyMigrationAbstract {
 
-	/** The safety parameter. */
+	/** The safety parameter in percentage (at scale from 0 to 1).
+         * It is a tuning parameter used by the allocation policy to 
+         * estimate host utilization (load). The host overload detection is based
+         * on this estimation.
+         * This parameter is used to tune the estimation
+         * to up or down. If the parameter is set as 1.2, for instance, 
+         * the estimated host utilization is increased in 20%, giving
+         * the host a safety margin of 20% to grow its usage in order to try
+         * avoiding SLA violations. As this parameter decreases, more
+         * aggressive will be the consolidation (packing) of VMs inside a host,
+         * what may lead to optimization of resource usage, but rising of SLA 
+         * violations. Thus, the parameter has to be set in order to balance
+         * such factors.
+         */
 	private double safetyParameter = 0;
 
-	/** The fallback vm allocation policy. */
+	/** The fallback VM allocation policy to be used when
+         * the IQR over utilization host detection doesn't have
+         * data to be computed. */
 	private PowerVmAllocationPolicyMigrationAbstract fallbackVmAllocationPolicy;
 
 	/**
-	 * Instantiates a new power vm allocation policy migration mad.
+	 * Instantiates a new PowerVmAllocationPolicyMigrationInterQuartileRange.
 	 * 
 	 * @param hostList the host list
 	 * @param vmSelectionPolicy the vm selection policy
@@ -60,7 +76,7 @@ public class PowerVmAllocationPolicyMigrationInterQuartileRange extends
 	}
 
 	/**
-	 * Instantiates a new power vm allocation policy migration mad.
+	 * Instantiates a new PowerVmAllocationPolicyMigrationInterQuartileRange.
 	 * 
 	 * @param hostList the host list
 	 * @param vmSelectionPolicy the vm selection policy
@@ -77,10 +93,10 @@ public class PowerVmAllocationPolicyMigrationInterQuartileRange extends
 	}
 
 	/**
-	 * Checks if is host over utilized.
+	 * Checks if the host is over utilized, based on CPU utilization.
 	 * 
-	 * @param _host the _host
-	 * @return true, if is host over utilized
+	 * @param host the host
+	 * @return true, if the host is over utilized; false otherwise
 	 */
 	@Override
 	protected boolean isHostOverUtilized(PowerHost host) {
@@ -101,10 +117,10 @@ public class PowerVmAllocationPolicyMigrationInterQuartileRange extends
 	}
 
 	/**
-	 * Gets the host utilization iqr.
+	 * Gets the host CPU utilization percentage IQR.
 	 * 
 	 * @param host the host
-	 * @return the host utilization iqr
+	 * @return the host CPU utilization percentage IQR
 	 */
 	protected double getHostUtilizationIqr(PowerHostUtilizationHistory host) throws IllegalArgumentException {
 		double[] data = host.getUtilizationHistory();

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmAllocationPolicyMigrationLocalRegression.java

@@ -15,7 +15,8 @@ import org.cloudbus.cloudsim.Vm;
 import org.cloudbus.cloudsim.util.MathUtil;
 
 /**
- * The Local Regression (LR) VM allocation policy.
+ * A VM allocation policy that uses Local Regression (LR) to predict host utilization (load)
+ * and define if a host is overloaded or not.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>
@@ -32,17 +33,32 @@ import org.cloudbus.cloudsim.util.MathUtil;
  */
 public class PowerVmAllocationPolicyMigrationLocalRegression extends PowerVmAllocationPolicyMigrationAbstract {
 
-	/** The scheduling interval. */
+	/** The scheduling interval that defines the periodicity of VM migrations. */
 	private double schedulingInterval;
 
-	/** The safety parameter. */
+	/** The safety parameter in percentage (at scale from 0 to 1).
+         * It is a tuning parameter used by the allocation policy to 
+         * estimate host utilization (load). The host overload detection is based
+         * on this estimation.
+         * This parameter is used to tune the estimation
+         * to up or down. If the parameter is set as 1.2, for instance, 
+         * the estimated host utilization is increased in 20%, giving
+         * the host a safety margin of 20% to grow its usage in order to try
+         * avoiding SLA violations. As this parameter decreases, more
+         * aggressive will be the consolidation (packing) of VMs inside a host,
+         * what may lead to optimization of resource usage, but rising of SLA 
+         * violations. Thus, the parameter has to be set in order to balance
+         * such factors.
+         */
 	private double safetyParameter;
 
-	/** The fallback vm allocation policy. */
+	/** The fallback VM allocation policy to be used when
+         * the Local REgression over utilization host detection doesn't have
+         * data to be computed. */
 	private PowerVmAllocationPolicyMigrationAbstract fallbackVmAllocationPolicy;
 
 	/**
-	 * Instantiates a new power vm allocation policy migration local regression.
+	 * Instantiates a new PowerVmAllocationPolicyMigrationLocalRegression.
 	 * 
 	 * @param hostList the host list
 	 * @param vmSelectionPolicy the vm selection policy
@@ -64,7 +80,7 @@ public class PowerVmAllocationPolicyMigrationLocalRegression extends PowerVmAllo
 	}
 
 	/**
-	 * Instantiates a new power vm allocation policy migration local regression.
+	 * Instantiates a new PowerVmAllocationPolicyMigrationLocalRegression.
 	 * 
 	 * @param hostList the host list
 	 * @param vmSelectionPolicy the vm selection policy
@@ -84,10 +100,10 @@ public class PowerVmAllocationPolicyMigrationLocalRegression extends PowerVmAllo
 	}
 
 	/**
-	 * Checks if is host over utilized.
+	 * Checks if a host is over utilized.
 	 * 
 	 * @param host the host
-	 * @return true, if is host over utilized
+	 * @return true, if is host over utilized; false otherwise
 	 */
 	@Override
 	protected boolean isHostOverUtilized(PowerHost host) {
@@ -117,10 +133,10 @@ public class PowerVmAllocationPolicyMigrationLocalRegression extends PowerVmAllo
 	}
 
 	/**
-	 * Gets the parameter estimates.
+	 * Gets utilization estimates.
 	 * 
-	 * @param utilizationHistoryReversed the utilization history reversed
-	 * @return the parameter estimates
+	 * @param utilizationHistoryReversed the utilization history in reverse order
+	 * @return the utilization estimates
 	 */
 	protected double[] getParameterEstimates(double[] utilizationHistoryReversed) {
 		return MathUtil.getLoessParameterEstimates(utilizationHistoryReversed);

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmAllocationPolicyMigrationLocalRegressionRobust.java

@@ -14,7 +14,8 @@ import org.cloudbus.cloudsim.Host;
 import org.cloudbus.cloudsim.util.MathUtil;
 
 /**
- * The Local Regression Robust (LRR) VM allocation policy.
+ * A VM allocation policy that uses Local Regression Robust (LRR) to predict host utilization (load)
+ * and define if a host is overloaded or not.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>
@@ -33,7 +34,7 @@ public class PowerVmAllocationPolicyMigrationLocalRegressionRobust extends
 		PowerVmAllocationPolicyMigrationLocalRegression {
 
 	/**
-	 * Instantiates a new power vm allocation policy migration local regression.
+	 * Instantiates a new PowerVmAllocationPolicyMigrationLocalRegressionRobust.
 	 * 
 	 * @param hostList the host list
 	 * @param vmSelectionPolicy the vm selection policy
@@ -58,7 +59,7 @@ public class PowerVmAllocationPolicyMigrationLocalRegressionRobust extends
 	}
 
 	/**
-	 * Instantiates a new power vm allocation policy migration local regression.
+	 * Instantiates a new PowerVmAllocationPolicyMigrationLocalRegressionRobust.
 	 * 
 	 * @param hostList the host list
 	 * @param vmSelectionPolicy the vm selection policy
@@ -75,10 +76,10 @@ public class PowerVmAllocationPolicyMigrationLocalRegressionRobust extends
 	}
 
 	/**
-	 * Gets the parameter estimates.
+	 * Gets the utilization estimates.
 	 * 
 	 * @param utilizationHistoryReversed the utilization history reversed
-	 * @return the parameter estimates
+	 * @return the utilization estimates
 	 */
 	@Override
 	protected double[] getParameterEstimates(double[] utilizationHistoryReversed) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmAllocationPolicyMigrationMedianAbsoluteDeviation.java

@@ -16,7 +16,8 @@ import org.cloudbus.cloudsim.Vm;
 import org.cloudbus.cloudsim.util.MathUtil;
 
 /**
- * The Median Absolute Deviation (MAD) VM allocation policy.
+ * A VM allocation policy that uses Median Absolute Deviation (MAD) to compute
+ * a dynamic threshold in order to detect host over utilization.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>
@@ -57,15 +58,16 @@ public class PowerVmAllocationPolicyMigrationMedianAbsoluteDeviation extends
          * utilization threshold that may lead to lower SLA violations but higher
          * resource wastage. Thus this parameter has to be tuned in order to 
          * trade-off between SLA violation and resource wastage.
-
          */
 	private double safetyParameter = 0;
 
-	/** The fallback vm allocation policy. */
+	/** The fallback VM allocation policy to be used when
+         * the MAD over utilization host detection doesn't have
+         * data to be computed. */
 	private PowerVmAllocationPolicyMigrationAbstract fallbackVmAllocationPolicy;
 
 	/**
-	 * Instantiates a new power vm allocation policy migration mad.
+	 * Instantiates a new PowerVmAllocationPolicyMigrationMedianAbsoluteDeviation.
 	 * 
 	 * @param hostList the host list
 	 * @param vmSelectionPolicy the vm selection policy
@@ -84,7 +86,7 @@ public class PowerVmAllocationPolicyMigrationMedianAbsoluteDeviation extends
 	}
 
 	/**
-	 * Instantiates a new power vm allocation policy migration mad.
+	 * Instantiates a new PowerVmAllocationPolicyMigrationMedianAbsoluteDeviation.
 	 * 
 	 * @param hostList the host list
 	 * @param vmSelectionPolicy the vm selection policy
@@ -101,10 +103,10 @@ public class PowerVmAllocationPolicyMigrationMedianAbsoluteDeviation extends
 	}
 
 	/**
-	 * Checks if is host over utilized.
+	 * Checks if a host is over utilized.
 	 * 
-	 * @param _host the _host
-	 * @return true, if is host over utilized
+	 * @param host the host
+	 * @return true, if the host is over utilized; false otherwise
 	 */
 	@Override
 	protected boolean isHostOverUtilized(PowerHost host) {
@@ -125,10 +127,10 @@ public class PowerVmAllocationPolicyMigrationMedianAbsoluteDeviation extends
 	}
 
 	/**
-	 * Gets the host utilization mad.
+	 * Gets the host utilization MAD.
 	 * 
 	 * @param host the host
-	 * @return the host utilization mad
+	 * @return the host utilization MAD
 	 */
 	protected double getHostUtilizationMad(PowerHostUtilizationHistory host) throws IllegalArgumentException {
 		double[] data = host.getUtilizationHistory();

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmAllocationPolicyMigrationStaticThreshold.java

@@ -14,7 +14,8 @@ import org.cloudbus.cloudsim.Host;
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * The Static Threshold (THR) VM allocation policy.
+ * A VM allocation policy that uses a Static CPU utilization Threshold (THR) to detect host over
+ * utilization.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>
@@ -31,11 +32,13 @@ import org.cloudbus.cloudsim.Vm;
  */
 public class PowerVmAllocationPolicyMigrationStaticThreshold extends PowerVmAllocationPolicyMigrationAbstract {
 
-	/** The utilization threshold. */
+	/** The static host CPU utilization threshold to detect over utilization.
+         * It is a percentage value from 0 to 1
+         * that can be changed when creating an instance of the class. */
 	private double utilizationThreshold = 0.9;
 
 	/**
-	 * Instantiates a new power vm allocation policy migration mad.
+	 * Instantiates a new PowerVmAllocationPolicyMigrationStaticThreshold.
 	 * 
 	 * @param hostList the host list
 	 * @param vmSelectionPolicy the vm selection policy
@@ -50,10 +53,10 @@ public class PowerVmAllocationPolicyMigrationStaticThreshold extends PowerVmAllo
 	}
 
 	/**
-	 * Checks if is host over utilized.
+	 * Checks if a host is over utilized, based on CPU usage.
 	 * 
-	 * @param _host the _host
-	 * @return true, if is host over utilized
+	 * @param host the host
+	 * @return true, if the host is over utilized; false otherwise
 	 */
 	@Override
 	protected boolean isHostOverUtilized(PowerHost host) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmAllocationPolicySimple.java

@@ -15,7 +15,7 @@ import org.cloudbus.cloudsim.Host;
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * This a simple class representing a simple VM allocation policy that does not perform any
+ * A class representing a simple VM allocation policy that does not perform any
  * optimization of the VM allocation.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
@@ -34,7 +34,7 @@ import org.cloudbus.cloudsim.Vm;
 public class PowerVmAllocationPolicySimple extends PowerVmAllocationPolicyAbstract {
 
 	/**
-	 * Instantiates a new power vm allocation policy simple.
+	 * Instantiates a new PowerVmAllocationPolicySimple.
 	 * 
 	 * @param list the list
 	 */
@@ -42,8 +42,15 @@ public class PowerVmAllocationPolicySimple extends PowerVmAllocationPolicyAbstra
 		super(list);
 	}
 
+        /**
+         * The method doesn't perform any VM allocation optimization
+         * and in fact has no effect.
+         * @param vmList
+         * @return 
+         */
 	@Override
 	public List<Map<String, Object>> optimizeAllocation(List<? extends Vm> vmList) {
+                //@todo It is better to return an empty map in order to avoid NullPointerException or extra null checks
 		// This policy does not optimize the VM allocation
 		return null;
 	}

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmSelectionPolicy.java

@@ -14,7 +14,8 @@ import java.util.List;
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * The class of an abstract VM selection policy.
+ * An abstract VM selection policy used to select VMs from a list of migratable VMs.
+ * The selection is defined by sub classes.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>
@@ -32,18 +33,18 @@ import org.cloudbus.cloudsim.Vm;
 public abstract class PowerVmSelectionPolicy {
 
 	/**
-	 * Gets the vms to migrate.
+	 * Gets a VM to migrate from a given host.
 	 * 
 	 * @param host the host
-	 * @return the vms to migrate
+	 * @return the vm to migrate
 	 */
 	public abstract Vm getVmToMigrate(PowerHost host);
 
 	/**
-	 * Gets the migratable vms.
+	 * Gets the list of migratable VMs from a given host.
 	 * 
 	 * @param host the host
-	 * @return the migratable vms
+	 * @return the list of migratable VMs
 	 */
 	protected List<PowerVm> getMigratableVms(PowerHost host) {
 		List<PowerVm> migratableVms = new ArrayList<PowerVm>();

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmSelectionPolicyMaximumCorrelation.java

@@ -16,7 +16,8 @@ import org.cloudbus.cloudsim.Vm;
 import org.cloudbus.cloudsim.util.MathUtil;
 
 /**
- * The Maximum Correlation (MC) VM selection policy.
+ * A VM selection policy that selects for migration the VM with the Maximum Correlation Coefficient (MCC) among 
+ * a list of migratable VMs.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>
@@ -33,11 +34,12 @@ import org.cloudbus.cloudsim.util.MathUtil;
  */
 public class PowerVmSelectionPolicyMaximumCorrelation extends PowerVmSelectionPolicy {
 
-	/** The fallback policy. */
+	/** The fallback VM selection policy to be used when
+         * the  Maximum Correlation policy doesn't have data to be computed. */
 	private PowerVmSelectionPolicy fallbackPolicy;
 
 	/**
-	 * Instantiates a new power vm selection policy maximum correlation.
+	 * Instantiates a new PowerVmSelectionPolicyMaximumCorrelation.
 	 * 
 	 * @param fallbackPolicy the fallback policy
 	 */
@@ -71,13 +73,20 @@ public class PowerVmSelectionPolicyMaximumCorrelation extends PowerVmSelectionPo
 	}
 
 	/**
-	 * Gets the utilization matrix.
+	 * Gets the CPU utilization percentage matrix for a given list of VMs.
 	 * 
-	 * @param vmList the host
-	 * @return the utilization matrix
+	 * @param vmList the VM list
+	 * @return the CPU utilization percentage matrix, where each line i
+         * is a VM and each column j is a CPU utilization percentage history for that VM.
 	 */
 	protected double[][] getUtilizationMatrix(final List<PowerVm> vmList) {
 		int n = vmList.size();
+                /*@todo It gets the min size of the history among all VMs considering
+                that different VMs can have different history sizes.
+                However, the j loop is not using the m variable
+                but the size of the vm list. If a VM list has 
+                a size greater than m, it will thow an exception.
+                It as to be included a test case for that.*/
 		int m = getMinUtilizationHistorySize(vmList);
 		double[][] utilization = new double[n][m];
 		for (int i = 0; i < n; i++) {
@@ -90,10 +99,10 @@ public class PowerVmSelectionPolicyMaximumCorrelation extends PowerVmSelectionPo
 	}
 
 	/**
-	 * Gets the min utilization history size.
+	 * Gets the min CPU utilization percentage history size among a list of VMs.
 	 * 
-	 * @param vmList the vm list
-	 * @return the min utilization history size
+	 * @param vmList the VM list
+	 * @return the min CPU utilization percentage history size of the VM list
 	 */
 	protected int getMinUtilizationHistorySize(final List<PowerVm> vmList) {
 		int minSize = Integer.MAX_VALUE;

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmSelectionPolicyMinimumMigrationTime.java

@@ -13,7 +13,7 @@ import java.util.List;
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * The Minimum Migration Time (MMT) VM selection policy.
+ * A VM selection policy that selects for migration the VM with Minimum Migration Time (MMT).
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmSelectionPolicyMinimumUtilization.java

@@ -14,7 +14,8 @@ import org.cloudbus.cloudsim.Vm;
 import org.cloudbus.cloudsim.core.CloudSim;
 
 /**
- * The Minimum Utilization (MU) VM selection policy.
+ * A VM selection policy that selects for migration the VM with Minimum Utilization (MU)
+ * of CPU.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/power/PowerVmSelectionPolicyRandomSelection.java

@@ -14,7 +14,7 @@ import java.util.Random;
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * The Random Selection (RS) VM selection policy.
+ * A VM selection policy that randomly select VMs to migrate from a host.
  * 
  * <br/>If you are using any algorithms, policies or workload included in the power package please cite
  * the following paper:<br/>

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/util/ExecutionTimeMeasurer.java

@@ -48,8 +48,8 @@ public class ExecutionTimeMeasurer {
 	 * Finalizes measuring the execution time of a method/process.
 	 * 
 	 * @param name the name of the method/process being measured.
-         * @see #executionTimes
 	 * @return the time the method/process spent in execution (in seconds)
+         * @see #executionTimes
 	 */
 	public static double end(String name) {
 		double time = (System.currentTimeMillis() - getExecutionTimes().get(name)) / 1000.0;

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/util/MathUtil.java

@@ -232,10 +232,10 @@ public class MathUtil {
 	}
 
 	/**
-	 * Gets the loess parameter estimates.
+	 * Gets the Local Regression (Loess) parameter estimates.
 	 * 
 	 * @param y the y array
-	 * @return the loess parameter estimates
+	 * @return the Loess parameter estimates
 	 */
 	public static double[] getLoessParameterEstimates(final double[] y) {
 		int n = y.length;
@@ -268,8 +268,6 @@ public class MathUtil {
 		double[] xW = new double[x.length];
 		double[] yW = new double[y.length];
 
-		// As to Flanagan's documentation they perform weigthed regression if the
-		// number or non-zero weigths is more than 40%
 		int numZeroWeigths = 0;
 		for (int i = 0; i < weigths.length; i++) {
 			if (weigths[i] <= 0) {