Competitive Lotka-Volterra

The aim of this project is to calibrate an Agent-Based model representing a competitive N-species Lotka-Volterra model with its numerical solution.

Jump to a section:

• Theoretical model
• Agent-Based model
• Structure of the code
• Requirements
• Usage
• Testing
• Documentation

The theoretical model

The model describes the evolution of N species competing for the same resources. In particular, the evolution of each species i normalized with respect to its own carrying capacity is described by the following first-order nonlinear differential equation:

where r_i > 0 is the growth rate of the species i and α_ij >= 0 is the element of the interaction matrix α which quantifies the effect of the species j on the species i (conventionally α_ii = 1). The evolution of each species is bounded between 0 and 1 with respect to its own carrying capacity.

For references regarding the chaotic dynamics or attractor phenomena that this model can exhibit, check the Wikipedia page.

This model is numerically solved by using the Runge-Kutta 4 algorithm, which allows to solve a general ordinary differential equation with known initial conditions x( t₀ ) in the form:

In particular, the solution for a time increment h is:

where we introduced four auxiliary fields F_1,2,3,4 defined as:

The Agent-Based model

An Agent-Based model is realized by considering a n x n grid in which the individuals move and interact according to stochastic events based on the values of the parameters of the model. The rules are the following:

1. at the beginning, each cell of the grid is initialized with an individual belonging to a species i with a probability:

   

   where K_i is the carrying capacity of the species i (i.e. maximum number that the population can reach).

2. then for each iteration we pick a cell:

   • if it is empty, an individual of a certain species is created with a probability given by:

     

     where g_i is the occupation number in the eight-cells neighborhood and Z is a normalization constant (the rate associated to the empty cells r₀ is fixed to one and it leaves the cell unoccupied).

   • if it is occupied, it interact with one kind of the neighborhood cells according to the occupation number:

     

     If j = 1, ..., N then the individual in the considered cell dies with a probability α_ij. Therefore, we require that α_ij <= 1. If j = 0 then the individual can move to an empty cell (or it stays in the current one) with a uniform probability. If the parameter ENABLE_BIRTHS in the setup.h is set to true, the individual has the opportunity to generate another individual in an empty cell with a probability:

     

     If this event does not occur, the individual can move according to an uniform probability.

The simulation evolves up to the chosen number of iterations (check the setup_usage file).

Structure of the code

The code is structured in the following folders:

• agent_based_model: in this folder three blocks of files are present, i.e. main_abm.cpp, which handles the glutMainLoop (if the graphical part is enabled), graphics.cpp/h in which the rules concerning the graphical part are defined, and LV.cpp/h, in which the dynamics of the agent-based model is specified.
• data: this folder contains some examples of data regarding the dynamics of the model (growth rates in rates.txt, initial conditions in values.txt, interaction matrix in matrix.txt and carrying capacities in capacity.txt) with different number of species. It is possible to add new configuration files following this format.
• docs: this folder contains the setup_usage.md file, which is a markdown file that explains the usage of the parameters in the setup.h file, and a folder with a configuration file for the doxygen documentation. In particular, if this latter is realized a new folder containing the documentation files named html will be created.
• numerical_simulation: in this folder the numerical solution of the competitive Lotka-Volterra model is computed through the RK4 algorithm. In particular, main_ns.cpp handles the main loop and it calls the algorithm and the model that are present in lotka_volterra.cpp/h files.
• output: this folder will contain the plots if SAVE_PLOT in utilies.h is set to true.
• testing: in this folder the main functions of the program are tested using the Catch2 framework.
• utilites: this folder contains several files that are required both for the numerical simulation and the agent-based model. In particular, we distinguish the reader.cpp/h files, in which the functions to read the data from file are defined, plotter.py, which handles the visualization of the trends, and utilities.h, which contains the parameters for the simulation.

Requirements

C++

The C++ version required is the C++11 standard.

The graphical part of the agent-based model is made with OpenGL using the FreeGlut library. To install it, type (Ubuntu or Debian Linux):

sudo apt-get install freeglut3 freeglut3-dev

To install the GNU binutils tools, type:

sudo apt-get install binutils-gold

Python

At the moment to run the program the python3 version is required. For the python script the following libraries are required:

• numpy
• matplotlib

If they are not already installed, type:

pip3 install numpy>=1.20.0 matplotlib>=3.3.4

Usage

Clone the repository:

git clone https://github.com/tommasomarzi/Competitive-Lotka-Volterra.git

Then type:

cd Competitive-Lotka-Volterra 

Run the model

Once the configuration in the setup.h file has been chosen (please refer to the setup_usage file), in order to build and run the simulation type (the flag '-s' silences the output of make, but it is not strictly necessary):

make model -s

Once the simulation has been performed, the output files of the two models can be found in the folder with the parameters chosen in setup.h. If the variable ENABLE_PLOT has not been set to true, you can realize the plots from those files once the simulation is finished by typing:

/usr/bin/python3 utilities/plotter.py

Otherwise, if ENABLE_PLOT is set to true the plots will be realized automatically.

Example

Once the simulation has been run, if ENABLE_GRAPHICS is set to true the evolution of the grid will be shown on screen as follows:

in which the green cells represent the empty cells, while the yellow and the black cells represent the two species. These informations are shown on the shell as well as the chosen parameters and the help menu:

If ENABLE_GRAPHICS is set to false, only the chosen configuration will appear on the shell.

In the presented case, the simulation is performed with the parameters reported in the 2-species_example folder with an increment h=0.0003 and ENABLE_BIRTHS set to false. The simulation evolves up to 80000 iteration. The comparison of the trends of the two populations shows good agreement between the theoretical model and the agent-based model:

In the numerical simulation, in the case of two species the system tends to a stable fixed point which can be easily computed by imposing the time-derivative of the species equal to zero. Therefore, the trajectory in the two-species plane tends to that fixed point:

On the other hand, the spatial information and the inner stochasticity of the agent-based model do not allow an exact stabilization of the populations. As a matter of fact, in this case the trajectory in the two-species plane follows a trend which deviates randomly from the one of the numerical solution and it ends up to fluctuate around the fixed point, creating a cloud:

Testing

The testing is performed with the Catch2 framework: you do not have to install anything since it is a single-header file that is already present in the testing folder to avoid path conflicts.

The testing can be done by typing (the flag '-s' silences the output of make, but it is not strictly necessary):

make test -s

WARNING: before starting the testing please set the DEBUG_MODE variable in the setup.h file to true in order to fix the seed of the sequence of random numbers and ensure the reproducibility of the results of the agent-based model test (a seed cannot be set specifically for the test as it would conflict with that of the model). Otherwise, the tests will still be performed and a warning message will appear on the shell.

Documentation

The documentation can be realized with doxygen. As this issue explains, in the doxygen versions before the 1.8.3 there are problems with the TOC page which lead to an incorrect hierarchy of headers. Therefore you should install one of the latest versions of doxygen by following this guide. However, since these problems are layout problems and they do not change the content of the documentation, you can install the version 1.8.17 by simply typing (Ubuntu or Debian Linux):

sudo apt-get install doxygen

which will also avoid problems related to possible missing GNU tools as flex, bison and libiconv. In this case, please remember that the TOC page will not be displayed correctly.

In order to create the html documentation file, from the Competitive-Lotka-Volterra folder type:

doxygen docs/doxygen/Doxyfile

After some processing time, a folder named html which contains a bunch of files will be created in docs/: the documentation can be viewed in the file index.html and you can open it in your browser directly from the shell by typing (in my case I'm using firefox):

firefox docs/html/index.html 

The testing folder is excluded from the doxygen documentation (simple docstrings are present in the code).