The Guppy Swarm Simulator

About Guppy - Development - Instructions - Publications - Contact




Installing Guppy

The guppy files can be downloaded here.

To run, guppy requires several libraries. These libraries are the CLI, Math and Primitives libraries of the Jakarta Commons, and the Colt library. The libraries can be downloaded from the following websites:

         Jakarta Commons – CLI library

         Jakarta Commons – Math library

         Jakarta Commons – Primitives library

         Colt Library

To use guppy, these libraries must be extracted and included in the classpath. For OS X, copying the .jar file within each library to the ~/Library/Java/Extensions directory will include it in the classpath. For windows XP and Linux, the path of each library must be added to the classpath variable. For Eclipse, each .jar file can be added to the build path using the “Add External JAR” option in Projects > Preferences > Java Build Path > Libraries.

Once the libraries are installed, extract guppy to an appropriate directory.


Running Guppy

There are a number of runnable methods within Guppy, but the two main runnable classes are main.RunGuppy and main.RunGuppyBatch. main.RunGuppy is designed for single simulation runs, and runs using Guppy’s GUI. main.RunGuppyBatch is designed for batches of simulation runs using text or file output.

main.RunGuppy has one required argument: -f <name of configuration file>. This gives the path of the configuration file which describes the run to be performed. More details on the content of a configuration file are given below. It also has one option argument: -o <name of output file>, which gives the filename of an output file. Any strings printed using the util.GuppyWriter object will be printed to this file.

main.RunGuppyBatch has three required arguments: the name of the configuration file, the name of the output file, and the number of runs to be performed using the supplied configuration file.


Configuration Files

The configuration file specifies all the parameters of the simulation run. An example file is shown below. Each line of a configuration file takes the form:

<parameter> = <value>

Values can take the form of a string, a class name, or a number. Some values have extra parameters associated with them; these are placed after the value, separated by commas. The list of configuration parameters are given below:



Value Type




The number of runs for this simulation. Should be set to 1; RunGuppyBatch is designed for the performance of multiple runs.



Whether a GUI is used in this simulation. Set to false for RunGuppyBatch runs (unless you want to create multiple GUIs). If this is set to true, and the OUTPUT_TYPE variable is set to an output without graphical representation (see below), this will cause an error.




The path of the file in which the repository is to be saved.



Class name

The name of the particle class used in this simulation.



The number of particles per swarm.



Class name

The name of the swarm class used in this simulation.




The number of swarms







The seeds for each of the random number generators. A value of -1 will cause the system to generate its own random value for that particular seed.


Class name

The environment or problem in which the simulation occurs.



{maxacceptableerror, runtoiterations}

The stopping criteria for the system – either when the best fitness value reaches a certain specified level, or when a set number of iterations have elapsed.




The number of iterations for this simulation to run. Only referenced if STOPPING_CRITERIA = runtoiterations.




The value of maximum fitness at which the simulation will stop. Only referenced if STOPPING_CRITERIA = maxacceptableerror.


Class name

The output class – the class controlling the way in which the results of the simulation are presented. If SHOW_GUI = true, the class referred to in OUTPUT must support a visual representation (i.e. be a subclass of <x>), else an error will be called.



The speed at which a Guppy run with GUI runs.


Setting up a Guppy run

If using the existing classes, any Guppy run you wish to perform can be organised by creating a new configuration file (or modifying an existing configuration file) and altering the parameters to fit the run you wish to do.


Creating your own Guppy classes

To test your own swarms, you will need to create new particle or swarm classes. To test your own problems, you will need to create new landscape classes. This section describes how to create new classes so they will work seamlessly with Guppy.



All the types of particle have the class Particle as their superclass. The Particle class is abstract, requiring one method to be implemented in its subclasses. This method is public void update (Swarm parent). The other method that is implemented in the Particle class, but may be necessary to overwrite in a new form of particle, is the initalize method.

The update(Swarm parent) method is called at each iteration of the simulation. The update method can access the current state of the particle and elements of the state of the entire swarm (as determined by the type of swarm it is within) and use this information to determine the next position of the swarm. The Particle has an array of doubles representing its position; the update method for any class you write should move the particle by updating this position array.


The initialize(int dimensions, double[] min_values, double[] max_values) method within the Particle class copies the number of dimensions, the minimum value for each dimension, and the maximum value for each dimension. These values can be found in the integer NUM_DIMENSIONS and the double arrays MIN_VALUES and MAX_VALUES respectively. It also initializes the position vector, without giving any values to the vector. If you wish to initialize any other variables, or give initial values to the position vector, you should do so in an overwritten version of the Particle class. Another Particle class, BaseRealParticle, implements the Particle of the Particle Swarm Optimisation algorithm of the version favoured by our research group. This may be a better starting point for your own particle class, as more has been implemented.



All the swarms have a single class, class Swarm, as their superclass. This basic class contains, like the Particle class, an integer giving the dimension of the Swarm, and two arrays of doubles giving the maximum and minimum values in each dimension. The Swarm also contains a map pointing to all the Particles within that Swarm. This map references the Particles by their ID numbers. The Swarm contains a number of methods for accessing a random Particle within the Swarm, accessing the list of IDs, and accessing specific Particles by their ID. If another class has access to the Swarm class, it has sufficient available methods to traverse the list of Particles within the Swarm.


If creating a new Swarm class, one method must be implemented – the update() method. In this case, nothing is passed to the method – the environment, and the repository, are accessed directly rather than passed to the Swarm. For your own Swarm class, you must implement the update() method. This method is called at each iteration, and the update() method must perform all the actions you wish a Swarm to perform during this iteration. This includes the process of updating each of the Particles. The class BaseRealSwarm implements the Swarm class for the Particle Swarm Optimization algorithm, and is a good basis for creating your own Swarm classes.


The other method that may be extended is the initialize method(int num_parts, String part_type, int num_dims, double[] min_vals, double[] max_vals). If you wish to initialize any variables or structures at the start of each simulation run, this can be done by extending the existing initialize method.



If you wish to solve a particular problem with Guppy, or have your particles interact with a particular environment, you can create a new Landscape class to represent this problem or environment.


All landscape classes are subclasses of the Landscape class. Like the Swarm and Particle classes, the base Landscape class records the number of dimensions and the maximum and minimum values for each dimension. Any subclass of Landscape has to implement two methods: evaluateParticlePosition(double[] position) and update(Environment parentEnv).


The evaluateParticlePosition returns a double value when given a double array value representing the position of a particle. This is used to give the value of a problem for a certain set of input values, or some variable of another landscape (such as food, or height). If using Guppy as a ‘sandbox’ – to analyze the movements of interacting particles with no influence from the environment – this method could just return a fixed value. If using Guppy to optimize a problem, the evaluateParticlePosition method should just run the value of the function given the inputs.


The update(Environment parentEnv) is called each iteration to update the state of the landscape. If the landscape is not altered over the course of a run – say, if optimizing a problem – then this method can be implemented without doing anything:


Public void update(Environment parentEnv) {



If the landscape changes, or responds to the movements of particles, then these changes should be implemented within the update method.


An example: Particle Swarm Optimization on the Sphere function.

As an example of how to create a Particle, Swarm and Environment in Guppy, let’s look at a set of classes in the Guppy libraries that can be used to perform Particle Swarm Optimization.


The Particle class for this is BaseRealParticle. This class implements an update() method and an initialize() method. The initialize() method sets the initial position and velocity of each particle. The update() method calculates the new position and new velocity according to the equations for particle swarm optimization.


The Swarm class for this is BaseRealSwarm. This class implements an initialize method that updates the fitness for all particles, then calls the initialize method in the superclass. As the Swarm class is responsible for calling each of the particle’s update methods, the update method for the Swarm iterates through each of the particles, calling each particle’s update method then updating the best fitness of the particles.


The Landscape class for this is Sphere30D. In the class constructor, it specifies the number of dimensions of the sphere and the boundaries of the problem space. In the evaluateParticlePosition, it evaluates the sphere function for a specified position and returns this as a double.


In the configuration file, this can be run by using the lines:






And appropriate values for the other parameters.



Top of Page