mutare

mutare (Latin for "to change") is a simple tool to simulate and analyze a stochastic agent-based model of adaptation in uncertain environments.

Overview

mutare simulates a stochastic agent-based model of adaptation in uncertain environments with the following characteristics:

• The environment is a discrete variable with n_env possible values and follows a Markov chain defined by the transition rates rates_trans.
• Each agent carries a phenotype, a discrete variable with n_phe possible values, and a phenotypic strategy, a distribution over phenotypes.
• Agents may duplicate or die according to environment and phenotype specific rates (rates_birth and rates_death).
• The offspring's phenotype is sampled from the parent's phenotypic strategy.
• The offspring inherits the parent's phenotypic strategy, but with probability prob_mut it suffers a random mutation and changes completely.
• At every simulation step, the population is capped at its initial size and reinitialized if extinction is reached.
• Each output file contains steps_per_file records, and the state is saved every steps_per_save steps.

From these output files mutare can also compute the following observables:

• The relative change in the number of agents.
• The probability of extinction.
• The probability of each environment.
• The average phenotypic strategy across agents.
• The standard deviation of the phenotypic strategy across agents.

Getting Started

Prerequisites

• Rust (install via rustup)

Installation

You can install mutare via cargo:

cargo install mutare

Or build it from source:

git clone https://github.com/Marco-Mendivil-Carboni/mutare.git
cd mutare
cargo build --release # The release profile is much faster than the dev profile

Basic Usage

Start by creating a simulation directory (e.g. example_sim/) and placing a config file named config.toml inside it.

Here is an example config file:

[model]
n_env = 2
n_phe = 2
rates_trans = [ [ -1.0, 1.0,], [ 1.0, -1.0,],]
rates_birth = [ [ 1.2, 0.0,], [ 0.0, 0.9,],]
rates_death = [ [ 0.0, 1.6,], [ 1.0, 0.0,],]
prob_mut = 0.002

[init]
n_agt = 256
strat_phe = [ 0.5, 0.5,]

[output]
steps_per_file = 65536
steps_per_save = 256

Now you can begin making simulation runs and analyzing them. Here are some examples of common commands:

mutare --sim-dir example_sim/ create # Create new simulation run
mutare --sim-dir example_sim/ resume --run-idx 0  # Resume run 0
mutare --sim-dir example_sim/ analyze # Analyze all runs
mutare --sim-dir example_sim/ clean # Clean up all runs

Run mutare --help to see more detailed help information.

Advanced Usage

The repository also includes some Python utility modules in scripts/utils/ for automating simulation workflows.

Prerequisites

• Python 3.12+

Python Setup

If you want to use these utilities you can set up the Python environment by running the following commands (after having cloned the repository):

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Documentation

Documentation is available via:

cargo doc --no-deps --open # Not generating docs for dependencies saves time

License

This project is licensed under the MIT License.

Contact

For questions or collaboration, reach out to marcomc@ucm.es or open an issue on GitHub.