mhl 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6451520f742d76561c0caf54cde03a7da4643898
-  data.tar.gz: f37fb25a97bb1b718c5ab2e7078f6853574b3749
+  metadata.gz: 3e0490b924de2e42d7fd0935673abd7d232b07ed
+  data.tar.gz: 51076e97078fc49710f9b6d86dc236e09cac5d99
 SHA512:
-  metadata.gz: aa0d5beb542b0889e042486421d8d878b427042c046d8c72b9cea1c4913d9bb01a5ec0f9d38bb34c6d48de49723346c2f9430d30a593bf1eb01d9786292270ea
-  data.tar.gz: a848727a22034af0a4a59bd58c3db415af71715e3e9fce35d17305312d4649cbecf93d2ee78eee157e3d5dcfc8b158a6ba7b85901e2236c87ce82d159878b7ad
+  metadata.gz: a1aac62bdff38e7c43d0bd58c06703ccf0df63a365b9c9e004b8f1a2a8f2cba59d2772a6e37c2dbba2c928e3ce5dffad6fd8b7c258c40979789a09217fdde090
+  data.tar.gz: 383e9ce734b17fbb47f843ff91e487b53dfed05a1df65bb70a09678b61eb98948b542eff2f3b45f9435d030ae5f7cbc816dc12ac2ba4447ad86e704469a1db97

data/README.md

@@ -1,10 +1,33 @@
-#ruby-mhl
+# ruby-mhl - A Ruby metaheuristics library
 
-A Ruby metaheuristics library
+ruby-mhl is a scientific library that provides a fairly large array of advanced
+computational intelligence methods for continuous optimization solutions.
+
+More specifically, ruby-mhl currently supports several implementations of
+Genetic Algorithms (bitstring and integer vector genotype representations) and
+Particle Swarm Optimization (constrained PSO, quantum-inspired PSO, and a
+multi-swarm version of quantum-inspired PSO), extended with adaptation 
+mechanisms to provide support for dynamic optimization problems.
+
+ruby-mhl was designed for _high duty_ target functions, whose evaluation
+typically involves one or more simulation runs, possibly defined on very
+complex domains (or search spaces), and implemented in JRuby for performance
+reasons. To this end, ruby-mhl automatically takes advantage of the parallelism
+provided by the processor.
 
 
 ## Installation
 
+To install ruby-mhl you first have to install Java and JRuby. This is a system
+dependent step, so I won't show you how to do it. However, if you are on Linux
+or OS X I recommend you to use [rbenv](https://github.com/rbenv/rbenv) to
+install and manage your Ruby installations.
+
+Once you have JRuby installed, you need to install bundler:
+
+    gem install bundler
+
+
 ### Stable version
 
 You can get the stable version of ruby-mhl by installing the mhl gem from
@@ -12,6 +35,16 @@ RubyGems:
 
     gem install mhl
 
+or by adding:
+
+```ruby
+gem 'mhl'
+```
+
+to your application's Gemfile and running:
+
+    bundle install
+
 ### Development version
 
 If you want to try the development version of ruby-mhl, instead, just place
@@ -26,46 +59,204 @@ in your Gemfile and run:
     bundle install
 
 
-## Examples
+## Genetic Algorithm (GA)
+
+ruby-mhl provides a GA solver capable of working with either the traditional
+bitstring chromosome representation or a integer vector representation variant.
+
+#### Example: Solving the parabola function with a integer vector GA
 
 Here is an example demonstrating how to find the argument that minimizes the
-2-dimension parabola x_1 ^ 2 + x_2 ^ 2 equation with a genetic algorithm:
+2-dimension parabola _f(x) = x<sub>1</sub><sup>2</sup> +
+x<sub>2</sub><sup>2</sup>_ equation with a genetic algorithm:
 
 ```ruby
 require 'mhl'
 
 solver = MHL::GeneticAlgorithmSolver.new(
-  :population_size           => 40,
+  :population_size           => 80,
   :genotype_space_type       => :integer,
   :mutation_probability      => 0.5,
   :recombination_probability => 0.5,
   :genotype_space_conf       => {
     :dimensions         => 2,
     :recombination_type => :intermediate,
-    :random_func        => lambda { Array.new(2) { rand(20) } }
+    :random_func        => lambda { Array.new(2) { rand(100) } }
   },
   :exit_condition => lambda {|generation,best| best[:fitness] == 0}
 )
 solver.solve(Proc.new{|x| -(x[0] ** 2 + x[1] ** 2) })
 ```
 
-and with particle swarm optimization:
+
+## Particle Swarm Optimization (PSO)
+
+ruby-mhl implements the constrained version of PSO, defined by equation 4.30 of
+[SUN11], which we report here for full clarity. The velocity and position
+update equation for particle _i_ are:
+
+<!--
+```latex
+\begin{aligned}
+    V_{i,j}(t+1) =& \; \chi [ V_{i,j}(t) + \\
+                  & \quad C_1 * r_{i,j}(t) * (P_{i,j}(t) - X_{i,j}(t)) + \\
+                  & \quad C_2 * R_{i,j}(t) * (G_j(t) - X_{i,j}(t)) ] \\
+    X_{i,j}(t+1) =& \; X_{i,j}(t) + V_{i,j}(t+1)
+\end{aligned}
+```
+-->
+
+![Movement equations for Constrained PSO](http://mathurl.com/z9zxe8q.png)
+
+In which _X<sub>i</sub>(t) = (X<sub>i,1</sub>(t), ..., X<sub>i,N</sub>(t))_ is
+the particle location, whose components _X<sub>i,j</sub>(t)_ represent the
+decision variables of the problem; _V<sub>i</sub>(t) = (V<sub>i,1</sub>(t),
+..., V<sub>i,N</sub>(t))_ is a velocity vector which captures the movement of
+the particle; _P<sub>i</sub>(t) = (P<sub>i,1</sub>(t), ...,
+P<sub>i,N</sub>(t))_ is a _particle attractor_ representing the 'highest'
+(best) position that the particle has encountered so far; _G(t)_ is the _swarm
+attractor_, representing the 'highest' (best) position that the entire swarm
+has encountered so far; _r<sub>i,j</sub>(t)_ and _R<sub>i,j</sub>(t)_ are
+random sequences uniformly sampled in the (0,1) interval; and _C<sub>1</sub>_
+and _C<sub>2</sub>_ are constants.
+
+Note that, in order to guarantee convergence, we must have:
+
+<!--
+```latex
+\begin{aligned}
+    \phi =& C_1 + C_2 > 4\\
+    \chi =& \frac{2}{\lvert 2-\phi-\sqrt{\phi^2-4\phi} \rvert}
+\end{aligned}
+```
+-->
+
+![Convergence criteria for Constrained PSO](http://mathurl.com/zjakqww.png)
+
+As a result, by default ruby-mhl sets _C<sub>1</sub> = C<sub>2</sub> = 2.05_
+and calculates &chi; accordingly (approximately 0.72984), which is considered
+the best practice [BLACKWELL04]. For more information about this (much more
+than you'll ever want to know, believe me) please refer to [CLERC02].
+
+#### Example: Solving the parabola function with PSO
+
+Here is an example demonstrating how to find the argument that minimizes the
+2-dimension parabola _f(x) = x<sub>1</sub><sup>2</sup> +
+x<sub>2</sub><sup>2</sup>_ equation with PSO:
 
 ```ruby
 require 'mhl'
 
 solver = MHL::ParticleSwarmOptimizationSolver.new(
-  :swarm_size           => 40,
-  :random_position_func => lambda { Array.new(2) { rand(20) } },
-  :random_velocity_func => lambda { Array.new(2) { rand(10) } },
-  :exit_condition       => lambda {|generation,best| best[:height].abs < 0.001 },
+  :swarm_size     => 40, # 40 is the default swarm size
+  :constraints    => {
+    :min => [ -100, -100 ],
+    :max => [  100,  100 ],
+  },
+  :exit_condition => lambda {|iteration,best| best[:height].abs < 0.001 },
 )
 solver.solve(Proc.new{|x| -(x[0] ** 2 + x[1] ** 2) })
 ```
 
-Other examples and a full documentation will be publised as ruby-mhl matures.
+
+## Quantum-Inspired Particle Swarm Optimization (QPSO)
+
+Quantum-inspired PSO is another particularly interesting PSO variant. It aims
+at simulating interactions between a group of humans by borrowing concepts
+from (the uncertainty typical of) quantum mechanics.
+
+ruby-mhl implements the Quantum-inspired version of PSO (QPSO), Type 2, as
+defined by equation 4.82 of [SUN11], which we report here for full clarity.
+
+<!--
+```latex
+\begin{equation}
+\begin{aligned}
+  C_j(t)       &= \frac{1}{M} \sum_{i=1}^{M} P_{i,j}(t) \\
+  p_{i,j}(t)   &= \phi_{i,j}(t) P_{i,j}(t) + (1-\phi_{i,j}(t)) G_j(t) \\
+  X_{i,j}(t+1) &= p_{i,j}(t) + \alpha \lvert X_{i,j}(t) - C_j(t) \rvert \ln \frac{1}{u_{i,j}(t+1)}
+\end{aligned}
+\end{equation}
+```
+-->
+
+![Movement Equations for Quantum-inspired PSO](http://mathurl.com/jkw88ue.png)
+
+where _P<sub>i</sub>(t)_ is the personal best of particle _i_; _C(t)_ is
+the mean of the personal bests of all the particles in the swarm; _G(t)_ is the
+swarm attractor; and _&phi;<sub>i,j</sub>(t)_ and _u<sub>i,j</sub>(t+1)_ are
+sequences of random numbers uniformly distributed on the (0,1) interval.
+
+
+#### Example: Solving the parabola function with QPSO
+
+Here is an example demonstrating how to find the argument that minimizes the
+2-dimension parabola _f(x) = x<sub>1</sub><sup>2</sup> +
+x<sub>2</sub><sup>2</sup>_ equation with PSO:
+
+```ruby
+require 'mhl'
+
+solver = MHL::QuantumPSOSolver.new(
+  :swarm_size     => 40, # 40 is the default swarm size
+  :constraints    => {
+    :min => [ -100, -100 ],
+    :max => [  100,  100 ],
+  },
+  :exit_condition => lambda {|iteration,best| best[:height].abs < 0.001 },
+)
+solver.solve(Proc.new{|x| -(x[0] ** 2 + x[1] ** 2) })
+```
 
 
 ## License
 
 MIT
+
+
+## Publications
+
+ruby-mhl was used in the following scientific publications:
+
+[TORTONESI16] M. Tortonesi, L. Foschini, "Business-driven Service Placement for
+Highly Dynamic and Distributed Cloud Systems", IEEE Transactions on Cloud
+Computing, 2016 (in print).
+
+[TORTONESI15] M.Tortonesi, "Exploring Continuous Optimization Solutions for
+Business-driven IT Managment Problems", in Proceedings of the 14th
+IFIP/IEEE Integrated Network Management Symposium (IM 2015) - Short papers
+track, 11-15 May 2015, Ottawa, Canada.
+
+[GRABARNIK14] G. Grabarnik, L. Shwartz, M. Tortonesi, "Business-Driven
+Optimization of Component Placement for Complex Services in Federated Clouds",
+in Proceedings of the 14th IEEE/IFIP Network Operations and Management
+Symposium (NOMS 2014) - Mini-conference track, 5-9 May 2014, Krakow, Poland.
+
+[FOSCHINI13] L. Foschini, M. Tortonesi, "Adaptive and Business-driven Service
+Placement in Federated Cloud Computing Environments", in Proceedings of the 8th
+IFIP/IEEE International Workshop on Business-driven IT Management (BDIM 2013),
+27 May 2013, Ghent, Belgium.
+
+If you are interested in ruby-mhl, please consider reading and citing them.
+
+
+## References
+
+[SUN11] Jun Sun, Choi-Hong Lai, Xiao-Jun Wu, "Particle Swarm Optimisation:
+Classical and Quantum Perspectives", CRC Press, 2011.
+
+[CLERC02] M. Clerc, J. Kennedy, "The particle swarm - explosion,
+stability, and convergence in a multidimensional complex space", IEEE
+Transactions on Evolutionary Computation, Vol. 6, No. 1, pp. 58-73,
+2002, DOI: 10.1109/4235.985692
+
+[BLACKWELL04] Tim Blackwell, Jürgen Branke, "Multi-swarm Optimization in
+Dynamic Environments", Applications of Evolutionary Computing, pp. 489-500,
+Springer, 2004. DOI: 10.1007/978-3-540-24653-4\_50
+
+[REZAEEJORDEHI13] A. Rezaee Jordehi, J. Jasni, "Parameter selection in particle
+swarm optimisation: a survey", Journal of Experimental & Theoretical Artificial
+Intelligence, Vol. 25, No. 4, pp. 527-542, 2013. DOI: 10.1080/0952813X.2013.782348
+
+[CLERC12] M. Clerc, "Standard Particle Swarm Optimisation - From 2006 to 2011",
+available at: [http://clerc.maurice.free.fr/pso/SPSO\_descriptions.pdf](http://clerc.maurice.free.fr/pso/SPSO_descriptions.pdf)

data/lib/mhl/charged_swarm.rb

@@ -1,5 +1,3 @@
-require 'matrix'
-
 require 'mhl/generic_swarm'
 
 
@@ -13,7 +11,7 @@ module MHL
     def initialize(size, initial_positions, initial_velocities, params={})
       @size = size
 
-      # retrieve ratio between charged (QPSO) and neutral (PSO w/ inertia) particles
+      # retrieve ratio between charged (QPSO) and neutral (constrained PSO) particles
       ratio = (params[:charged_to_neutral_ratio] || DEFAULT_CHARGED_TO_NEUTRAL_RATIO).to_f
       unless ratio > 0.0
         raise ArgumentError, 'Parameter :charged_to_neutral_ratio should be a real greater than zero!'
@@ -35,51 +33,65 @@ module MHL
       # find problem dimension
       @dimension  = initial_positions[0].size
 
-      @generation = 1
+      @iteration = 1
 
       # define procedure to get dynamic value for alpha
       @get_alpha = if params.has_key? :alpha and params[:alpha].respond_to? :call
         params[:alpha]
       else
-        ->(gen) { (params[:alpha] || DEFAULT_ALPHA).to_f }
+        ->(it) { (params[:alpha] || DEFAULT_ALPHA).to_f }
       end
 
       # get values for parameters C1 and C2
       @c1 = (params[:c1] || DEFAULT_C1).to_f
       @c2 = (params[:c1] || DEFAULT_C2).to_f
 
-      # define procedure to get dynamic value for omega
-      @get_omega = if params.has_key? :omega and params[:omega].respond_to? :call
-        params[:omega]
+      # define procedure to get dynamic value for chi
+      @get_chi = if params.has_key? :chi and params[:chi].respond_to? :call
+        params[:chi]
       else
-        ->(gen) { (params[:omega] || DEFAULT_OMEGA).to_f }
+        ->(it) { (params[:chi] || DEFAULT_CHI).to_f }
+      end
+
+      if params.has_key? :constraints
+        puts "ChargedSwarm called w/ constraints: #{params[:constraints]}"
       end
+
+      @constraints = params[:constraints]
     end
 
     def mutate
       # get alpha parameter
-      alpha = @get_alpha.call(@generation)
+      alpha = @get_alpha.call(@iteration)
 
-      # get omega parameter
-      omega = @get_omega.call(@generation)
+      # get chi parameter
+      chi = @get_chi.call(@iteration)
 
-      # this calculates the C_n parameter (basically, the centroid of particle
-      # attractors) as defined in [SUN11], formulae 4.81 and 4.82
+      # this calculates the C_n parameter (the centroid of the set of all the
+      # particle attractors) as defined in equations 4.81 and 4.82 of [SUN11].
       #
-      # (note: the neutral particles influence the behavior of the charged ones
-      # not only by defining the swarm attractor, but also by forming this centroid)
-      c_n = @particles.inject(Vector[*[0]*@dimension]) {|s,p| s += p.attractor[:position] } / @size.to_f
+      # Note: we consider ALL the particles here, not just the charged (QPSO)
+      # ones. As a result, the neutral particles influence the behavior of the
+      # charged ones not only by defining the swarm attractor, but also the
+      # centroid.
+      attractors = @particles.map {|p| p.attractor[:position] }
+      c_n = 0.upto(@dimension-1).map do |j|
+        attractors.inject(0.0) {|s,attr| s += attr[j] } / @size.to_f
+      end
 
       @particles.each_with_index do |p,i|
         # remember: the particles are kept in a PSO-first and QPSO-last order
         if i < @num_neutral_particles
-          p.move(omega, @c1, @c2, @swarm_attractor)
+          p.move(chi, @c1, @c2, @swarm_attractor)
         else
           p.move(alpha, c_n, @swarm_attractor)
         end
+        if @constraints
+          p.remain_within(@constraints)
+        end
       end
 
-      @generation += 1
+      @iteration += 1
     end
   end
 end

data/lib/mhl/generic_particle.rb

@@ -19,34 +19,6 @@ module MHL
       end
     end
 
-    def remain_within(constraints)
-      new_pos = @position.map.with_index do |x,i|
-        puts "resetting #{x} within #{constraints[:min][i]} and #{constraints[:max][i]}"
-        d_max = constraints[:max][i]
-        d_min = constraints[:min][i]
-        d_size = d_max - d_min
-        if x > d_max
-          while x > d_max + d_size
-            x -= d_size
-          end
-          if x > d_max
-            x = 2 * d_max - x
-          end
-        elsif x < d_min
-          while x < d_min - d_size
-            x += d_size
-          end
-          if x < d_min
-            x = 2 * d_min - x
-          end
-        end
-        puts "now x is #{x}"
-        x
-      end
-      puts "new_pos: #{new_pos}"
-      @position = new_pos # Vector[new_pos]
-    end
-
   end
 
 end

data/lib/mhl/generic_swarm.rb

@@ -3,20 +3,22 @@ require 'forwardable'
 module MHL
   class GenericSwarmBehavior
 
-    # The following values were taken from [BLACKWELLBRANKE04] Tim Blackwell,
-    # Jürgen Branke, "Multi-swarm Optimization in Dynamic Environments",
-    # Applications of Evolutionary Computing, pp.  489-500, Springer, 2004.
-    # DOI: 10.1007/978-3-540-24653-4_50
+    # The following values are considered a best practice [SUN11] [CLERC02]
+    # [BLACKWELLBRANKE04].
     # C_1 is the cognitive acceleration coefficient
     DEFAULT_C1 = 2.05
     # C_2 is the social acceleration coefficient
     DEFAULT_C2 = 2.05
+    # \chi is the constraining factor for normal particles
     PHI = DEFAULT_C1 + DEFAULT_C2
-    # \omega is the inertia weight
-    DEFAULT_OMEGA = 2.0 / (2 - PHI - Math.sqrt(PHI ** 2 - 4.0 * PHI)).abs
-
-    # \alpha is the inertia weight
-    # According to [SUN11], this looks like a sensible default parameter
+    DEFAULT_CHI = 2.0 / (2 - PHI - Math.sqrt((PHI ** 2 - 4.0 * PHI))).abs
+
+    # \alpha is the contraction-expansion (CE) coefficient for quantum
+    # particles [SUN11].
+    # In order for the QPSO algorithm to converge, \alpha must be lower than
+    # $e^{\gamma} \approx 1.781$, where $\gamma \approx 0.5772156649$ is the
+    # Euler constant. According to [SUN11], 0.75 looks like a sensible default
+    # parameter.
     DEFAULT_ALPHA = 0.75
 
     extend Forwardable
@@ -29,7 +31,7 @@ module MHL
       particle_attractors = @particles.map { |p| p.attractor }
 
       # update swarm attractor (if needed)
-      if @swarm_attractor.nil?
+      unless (defined?(@swarm_attractor))
         @swarm_attractor = particle_attractors.max_by {|p| p[:height] }
       else
         @swarm_attractor = [ @swarm_attractor, *particle_attractors ].max_by {|p| p[:height] }