# 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](https://rustup.rs/))

### Installation

You can install `mutare` via `cargo`:

```bash
cargo install mutare
```

Or build it from source:

```bash
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:

```toml
[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:

```bash
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):

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

---

## Documentation

Documentation is available via:

```bash
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.

