# how_to_use_particle_swarm_optimisation

## Call the library

    set.seed(42)
    library(particle.swarm.optimisation)

To use the Particle or the swarm we need to define a fitness function and a range of value.

    range_of_value <- list(c(1,300),c(1,300),c(1,300))
    fitness_function <- function(values){
      return(values[[1]]+values[[2]]+values[[3]])
    }

## The Particle Class

This class is used to create a Particle for the Particle Swarm Optimisation.

### method new() (initialize):

Used to create the Particle, take different parameters:

- values_ranges : A list of ranges for each value of the Particle, his size need to be the same as values.
- values : A numeric vector, each number represented the position of the Particle.
- fitness_function : The function used to find the fitness (or the score) of the particle. It needs to take a list as input and return a single value.
- acceleration_coefficient : A vector of two values, one for c1 (personal coefficient) and one for c2 (global coefficient).
- inertia : A numeric who represent the inertia of the Particle (the effect of the current velocity on the next velocity).

    exemple <- Particle$new(values_ranges = range_of_value,
                               values = c(50,120,187),
                               fitness_function = fitness_function,
                               acceleration_coefficient = c(0.3,0.4),
                               inertia = 0.4)
    print(exemple)
    #> Particle:
    #> Values 1: 50
    #> Values 2: 120
    #> Values 3: 187
    #> fitness : NA

### method get_fitness()

Used to calculate the fitness of the Particle (with the fitness function)

    exemple$get_fitness() # 50+120+187
    print(exemple)
    #> Particle:
    #> Values 1: 50
    #> Values 2: 120
    #> Values 3: 187
    #> fitness : 357

### method update()

Used to change the position of the Particle based on his personal best and Swarm best, it also changes the personal best if needed. It takes one param:

- swarm_best : best values of the swarm

    print(paste('best fitness before :',exemple$personal_best_fitness,sep = ' '))
    #> [1] "best fitness before : 0"
    exemple$update(swarm_best = c(200,300,300)) # the swarm best is just a random value here
    print(exemple)
    #> Particle:
    #> Values 1: 106.2245
    #> Values 2: 187.4694
    #> Values 3: 229.3558
    #> fitness : 523.0498
    print(paste('best fitness after :',exemple$personal_best_fitness,sep = ' '))
    #> [1] "best fitness after : 523.049763236381"

### method update_personal_best_fitness()

This method is used to change the personal best values and fitness with the current values and fitness of the Particles.

    exemple$update_personal_best_fitness() # do nothing because the update method of the previous chunck also call this method.

### method print()

This method print the current values of the particle and the fitness.

    print(exemple)
    #> Particle:
    #> Values 1: 106.2245
    #> Values 2: 187.4694
    #> Values 3: 229.3558
    #> fitness : 523.0498
    # or :
    exemple$print()
    #> Particle:
    #> Values 1: 106.2245
    #> Values 2: 187.4694
    #> Values 3: 229.3558
    #> fitness : 523.0498

## The ParticleSwarm Class

This class is used to create the swarm and launch the PSO. As a user you just need to init the ParticleSwarm object with the $new method and launch the PSO with the $run method.

### method new()

Used to create the ParticleSwarm object, take different parameters:

- ranges_of_values : A list of ranges for each value for the particles.
- fitness_function : The function used to find the fitness (or the score) of the particle. It needs to take a list as input and return a single value.
- acceleration_coefficient_range : A list with two vectors with the min and max for c1 and c2.
- max_it : maximum number of itération
- inertia : A numeric who represent the inertia of the particle (the effect of the current velocity on the next velocity)
- pop_size : number of particle in the swarm.

    swarm_exemple <- ParticleSwarm$new(pop_size = 10,
                                        ranges_of_values = range_of_value,
                                        fitness_function = fitness_function,
                                        max_it = 10,
                                        values_names = list('a','b','c'),
                                        acceleration_coefficient_range = list(c(0,1),c(0,1)),
                                        inertia = 0.4)

### method generate_pop()

The generate pop is the method used to create the population of particles. The values of the particles are randomly selected in the range of values, the same goes for the acceleration coefficient. There is no need to call this method because the run does it for us. It takes one parameter:

- verbose : if the methods do the print or not

    swarm_exemple$generate_pop(verbose = FALSE)
    print(swarm_exemple)
    #> [1] "Population result : "
    #>            a         b          c accuracy
    #> 1   86.55572 249.30384 192.881910 528.7415
    #> 2   41.26531 197.44069 211.814370 450.5204
    #> 3  280.46700  77.37322 139.225554 497.0658
    #> 4   36.12872 143.02413 168.539491 347.6923
    #> 5  296.67863 284.05380  25.648830 606.3813
    #> 6  271.81570 134.64392 250.965274 657.4249
    #> 7  117.04438 205.86575   2.180553 325.0907
    #> 8   63.09003 272.07382 183.921814 519.0857
    #> 9   12.19188 292.08843 130.093623 434.3739
    #> 10 192.35365 291.31902 186.032624 669.7053

### method move_the_swarm()

This method is used to move the particle in the swarm. it takes one argument:

- verbose : If the method print or not the result in the console

The swarm’s move are based on the following equation: V(t+1) = V(t) * i + c1 * r1 * (pb - x(t)) + c2 * r2 * (gb - x(t)) x(t+1) = x(t) + V(t+1)

Where:

- V is the velocity
- t is the number of the iteration
- i is the inertia
- c1 and c2 are the acceleration coefficient
- r1 and r2 are two random value between 0 and 1 who follow a uniform distribution
- pb is the personal best value of the particle
- gb is the best value of the swarm
- x is the current value of the particle

    swarm_exemple$move_the_swarm(verbose = FALSE)
    print(swarm_exemple)
    #> [1] "Population result : "
    #>            a        b         c accuracy
    #> 1  147.70645 273.5884 188.92305 610.2179
    #> 2  122.62154 247.9912 197.93173 568.5444
    #> 3  265.70491 113.2167 147.06739 525.9890
    #> 4   47.27604 153.6056 169.78770 370.6693
    #> 5  256.67014 286.8400  87.15580 630.6659
    #> 6  235.30660 206.6288 221.13175 663.0672
    #> 7  117.14903 205.9845   2.43604 325.5696
    #> 8  109.73971 279.0192 184.68358 573.4425
    #> 9   50.66448 291.9241 142.03910 484.6277
    #> 10 192.35365 291.3190 186.03262 669.7053

### method save_pop()

This method is used to save the current population in a csv file, the result is a data frame with the particle in row and the values in col, the last col is the fitness of the particle.

    swarm_exemple$save_pop()

### method plot_the_swarm_2D()

this method is used to plot the swarm if the problem used two values (if there is 3 values you can use plot3D).

    swarm_exemple$plot_the_swarm_2D(nb_it=0,save_file=FALSE)

### method plot_the_swarm_3D()

this method is used to plot the swarm if the problem used three values. it take one param:

- nb_it : the number of the iteration used to save the plot

    swarm_exemple$plot_the_swarm_3D(nb_it=0,save_file=FALSE)

### method run()

This is the main method of the call, it call all the other method to do the PSO (you just need to call this method) It takes two params:

- plot TRUE or FALSE, it is used to plot or not the result of each iteration
- verbose TRUE or FALSE, it is used to display or not the result in the console

    swarm_exemple$run(verbose = FALSE,plot = FALSE,save_file = FALSE)
    print(swarm_exemple)
    #> [1] "Population result : "
    #>           a        b         c accuracy
    #> 1  248.2917 300.0000 183.70191 731.9936
    #> 2  254.1725 300.0000 187.24311 741.4156
    #> 3  256.0629 300.0000 185.70251 741.7655
    #> 4  205.1951 273.4246 181.62059 660.2403
    #> 5  245.0168 300.0000 185.81011 730.8269
    #> 6  253.1121 300.0000 186.36813 739.4802
    #> 7  124.1800 211.8905  14.17278 350.2433
    #> 8  249.7794 300.0000 184.30445 734.0838
    #> 9  252.6738 300.0000 185.75742 738.4312
    #> 10 244.3993 299.8249 184.77123 728.9954