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 random variable with n_env possible states and follows a Markov chain with configurable transition probabilities (prob_env).
• Each agent carries a phenotype, a discrete variable with n_phe possible states, and a probability distribution over phenotypes.
• At every simulation step, agents may replicate or decease according to environment and phenotype specific probabilities (prob_rep and prob_dec).
• The offspring's phenotype is sampled from the parent's distribution.
• The offspring inherits the parent's distribution, but with probability prob_mut this distribution suffers a slight mutation (modulated by std_dev_mut).
• The simulation state is saved every steps_per_save steps, and saves_per_file states are stored in each trajectory file.

From these trajectories mutare can compute metrics such as:

• The probability of finding the system in each environment.
• The average probability distribution over phenotypes across agents.
• The net change in the number of agents per step.

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
prob_trans_env = [ [ 0.99, 0.01,], [ 0.01, 0.99,],]
prob_rep = [ [ 0.04, 0.0,], [ 0.0, 0.03,],]
prob_dec = [ [ 0.0, 0.02,], [ 0.02, 0.0,],]
prob_mut = 0.06
std_dev_mut = 0.06

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

[output]
steps_per_save = 1024
saves_per_file = 64

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

mutare --sim-dir example_sim/ create # Create a 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 simulation runs

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

Advanced Usage

The repository also includes Python scripts (in the scripts/ folder) for orchestrating multiple simulations automatically.

Prerequisites

• Python 3.12+

Python Setup

If you want to use these scripts 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.