\chapter{Your first \aevol{} runs}
\label{chap:first-runs}


\vspace{5mm}

Aevol comes along with a set of simple but representative examples. The \verb?workflow? example proposes a typical \emph{``experiments on a previously generated wild-type''} workflow. The other examples are showcases for different features of the model such as spatially structured populations, plasmids and horizontal transfer.

If in doubt, you can always \verb?man aevol_cmd? or \verb?aevol_cmd -h? for help.


\section{Basic examples}

To run all but the \verb?workflow? examples, simply follow the following steps:

\begin{enumerate}
\item Install Aevol, preferentially with graphics enabled (see chapter \ref{chap:install})
\item cd into the directory of the example (\emph{e.g.} \verb?examples/basic?)
\item
run \verb?aevol_create?
\item
run \verb?aevol_run?
\item Have a look at the graphical outputs (Ctrl+Q to quit)
\item [Optional] Explore the different statistics created in the \verb?stats? directory.
\end{enumerate}


\section{The \emph{workflow} example}

The workflow example provides an example of the workflow that can be used for experiments with \aevol{}.

The main idea underlying this workflow is to parallel wet lab experiments, which are conducted on evolved organisms.
To use already evolved organisms for your experiments in Aevol, one can either use an evolved genome provided by the community or evolve its own. The following describes the latter (more complete) case.


\subsection{\emph{Wild-Type generation}}
Generating a Wild-Type in \aevol{} is very easy, all you need is a parameter file describing the conditions in which it (the Wild-Type) should be created (population size, mutation rates, task to perform, ...).
However, have in mind that founding effects can influence the course of evolution, especially in the case of overconstrained evolution. It is recommended to use mild mutation and rearrangement rates and a to let the environment vary over time to avoid overconstrained or overspecialized genomes.
Once your parameter file is ready, simply run the following commands (it is recommended you do that in a dedicated directory):

\begin{verbatim}
	aevol_create -f <your_param_file>
	aevol_run -n <number_of_generations>
\end{verbatim}

%$number\_of\_generations$ should be on the order of a few thousand...


\subsection{Experimental setup}
This is where the setup of the campain of experiments is done.
As it would be done in a wet lab experiment, different populations will be allowed to evolve in different conditions to compare the different outcomes. In this example we will let 6 populations evolve independently for 20,000 generations in conditions differing only by the spontaneous rates of chromosomal rearrangements. A ``real'' experiment would of course require several repetitions for each set of parameters, this is \emph{only} an example.

The \verb?aevol_propagate? tool provided in \aevol{} allows for an exact copy of the whole data structure required by aevol with a reset of the current generation number to 0. Followed by a call to \verb?aevol_modify?, it allows us to set up very simply our example in the 2 following steps:

%\begin{enumerate}

\subsubsection{Propagate the experiment}
The \verb?aevol_propagate? tool allows for the creation of fresh copies of an experiment (as it was at a given time). The -i option sets the input directory and the -o option, the output directory. You must provide a distinct output directory for each of the experiments you wish to run.
\begin{verbatim}
	aevol_propagate -i wild_type -o mu_1e-6
	aevol_propagate -i wild_type -o mu_2e-6
	aevol_propagate -i wild_type -o mu_5e-6
	aevol_propagate -i wild_type -o mu_1e-5
	aevol_propagate -i wild_type -o mu_2e-5
	aevol_propagate -i wild_type -o mu_5e-5
\end{verbatim}

\subsubsection{Modify parameters to meet the experiment requirements}
For each of the propagated experiments, create a plain text file (\emph{e.g.} ``foo.in'') containing the parameters to be modified. Parameters that do not appear in this file will remain unchanged. The syntax is the same as for the parameter file used for \verb?aevol_create?. For example, to set all the rearrangement rates to $1\times10^{-6}$, the file ``foo.in'' will consist in the following 4 lines:
\begin{verbatim}
    DUPLICATION_RATE        1e-6
    DELETION_RATE           1e-6
    TRANSLOCATION_RATE      1e-6
    INVERSION_RATE          1e-6
\end{verbatim}
Then run the following:
\begin{verbatim}
	aevol_modify --gener 0 --file foo.in
\end{verbatim}

%\end{enumerate}


\subsection{Run the simulations}
Each of the propagated experiments can be run thus:
\begin{verbatim}
	aevol_run -n <number_of_generations>
\end{verbatim}
Of course, all the runs being completely independent, you can submit these tasks to a cluster of your choice to save time.


\subsection{Analyse the outcome}


\clearemptydoublepage






