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.
• When the strategy mutates, if std_dev_mut is set, a random vector with that standard deviation is added; otherwise, it changes completely.
• At every simulation step, the population is capped at its initial size (n_agents) and reinitialized if extinction is reached.
• Initially, if strat_phe is set, all agents will share that same strategy; otherwise, they will each have a random strategy.

During the simulation, every steps_per_save steps, the following observables are computed and saved:

• Current simulation time
• Time until the next event
• Number of agents in the simulation
• Instantaneous population growth rate
• Number of extinctions so far
• Average phenotypic strategy
• Standard deviation of the phenotypic strategy
• Distribution of phenotypes

Every steps_per_file steps, the simulation is stopped and a new output file is written to disk.

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.8,],]
rates_death = [ [ 0.0, 1.0,], [ 1.0, 0.0,],]
prob_mut = 0.001

[init]
n_agents = 100
strat_phe = [ 0.5, 0.5,]

[output]
steps_per_file = 65536
steps_per_save = 256
hist_bins = 16

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

mutare --sim-dir example_sim/ --run-idx 0 create # Create run 0
mutare --sim-dir example_sim/ --run-idx 0 resume # Resume run 0
mutare --sim-dir example_sim/ --run-idx 0 analyze # Analyze run 0

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.