User Documentation

Introduction

Aevol is a forward-in-time evolutionary simulator that simulates the evolution of a population of organisms through a process of variation and selection. The design of the model focuses on the realism of the genome structure and of the mutational process: the mutations affect directly the sequence, without any a priori fitness effect. Aevol can therefore be used to decipher the effect of different operators or processes on genome evolution.

To run Aevol, you must first initiate a population of organisms with the desired parameters (Sections Parameter File and Initialize a Simulation), and then run the simulation for the desired number of steps (Section Run a simulation). The simulations can be further analyzed afterward with dedicated tools (Section Post-Treatments).

Aevol exists in three flavors: Standard, 4-Bases and Eukaryote. Most of the model is identical across the different flavors, and variations will be presented explicitly throughout the model presentation. In short:

In Standard Aevol, each organism is asexual, haploid, and owns a single circular chromosome. The genome is encoded as a double-strand binary string. This is inspired by prokaryotic organisms
In 4-Bases Aevol, the genome is not binary but encoded with $4$ letters. That changes the genotype-to-phenotype map, but not the rest of the model.
In Eukaryote Aevol, each organism owns two linear chromosomes, and the reproduction is sexual and includes a meiotic recombination event. The genome is binary.

Note: although the 4-Bases and Eukaryote versions should work together, this has not been sufficiently tested yet.

Please note it is assumed you have fully installed Aevol on your computer and that the executables can be run directly from the command line. If this is not the case, you can use the full path to the Aevol executables instead of their name. E.g. if you have built aevol in /home/login/aevol/build, you can use:

/home/login/aevol/build/bin/aevol_2b_create --help # beware of the additional bin level

instead of

aevol_2b_create --help

Please also note that each independent Aevol simulation should be run in its own separate directory.

Parameter File

To run a simulation, you will generally want to provide a parameter file to specify the experimental conditions for the run (it is also possible to use default parameters, but this is not recommended).

Examples are provided in the example directory: example directory on the GitLab.

For a description of all the parameters used in aevol, visit this page.

Initialize a simulation (aevol_create)

There are two main ways to initialize a simulation: from scratch, using a randomly generated initial genome, or providing a sequence (usually a WildType). The latter is the only recommended way of starting a Eukaryote Aevol simulation.

In both cases, aevol_create generates an initial checkpoint (checkpoint at generation 0) containing all the necessary information to run a simulation.

For details about aevol_create, visit this page.

Run a simulation (aevol_run)

After you have initialized a simulation, you can run it with aevol_run.

aevol_run will produce a checkpoint every CHECKPOINT_STEP (see section parameters), which can be used to resume a simulation after it was stopped.

For details about aevol_run, visit this page.

Post-Treatments

Aevol comes with several post-treatments that enable to analyze the evolutionary runs or the evolved organisms. Two of them being especially important. Aevol simulates the evolution of a population of individuals. However, when replication is asexual (i.e. for the Standard and 4-bases Aevol flavors), the line of descent of any given final individual can be reconstructed. This lineage corresponds to fixed individuals (up to the coalescence point) and all mutations that occurred in this lineage have themselves reached fixation (again, up to the coalescent point). Analysing the lineage of fixed individuals and the sequence of fixed mutations provides a very precise view of the evolutionary dynamics and enables to analyze the relative contribution of selection, mutation and drift to the evolutionary dynamics. In Aevol this information can be obtained using two tools, provided the tree files (that record all replication events during the simulation) have been generated at runtime (see Section Parameter File): aevol_post_lineage that recover the line of descent of any individual in a checkpoint, and aevol_post_ancestor_stats that, from the lineage file, reconstruct the genomes of all the individuals along this lineage and and export the list of all fixed mutations that have occurred in these genomes.

Reconstruct a lineage (available only for Standard and 4-bases flavors)

The lineage of a given individual can be reconstructed from the tree files using aevol_post_lineage, provided the tree files have been generated at runtime .

For details about aevol_post_lineage, visit this page.

Compute stats on a lineage

Once you have reconstructed a lineage (see reconstruct a lineage), you can compute statistics on this lineage and reconstructs the list of all fixed mutations that have occurred in the lineage using aevol_post_ancestor_stats.

For details about aevol_post_ancestor_stats, visit this page.