mutare 0.2.0

A simple tool to simulate and analyze a stochastic agent-based model of adaptation in uncertain environments.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# 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, and its distribution is the parent's one with 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

### Installation

```bash
cargo install mutare
```

Or clone the repository:

```bash
git clone https://github.com/Marco-Mendivil-Carboni/mutare.git
cd mutare
cargo build
```

### Basic Usage

Run `mutare --help` to see available commands. They can be used as follows:

```bash
mutare --sim-dir ./my_sim_dir create # Create a new simulation run
mutare --sim-dir ./my_sim_dir resume --run-idx 0  # Resume run 0
mutare --sim-dir ./my_sim_dir analyze # Analyze all runs
mutare --sim-dir ./my_sim_dir clean # Clean up all simulation runs
```

### Configuration

Each simulation requires a configuration file named `config.msgpack`, located inside the simulation directory.

This file is **not generated by `mutare`**, but instead is expected to be created externally. You can use a Python script to do so like this:

```python
import msgpack

config = {
    "n_env": 2,
    "n_phe": 2,
    "prob_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],
    ],
    "n_agt_init": 1024,
    "std_dev_mut": 0.01,
    "steps_per_save": 4096,
    "saves_per_file": 64,
}

with open("my_sim_dir/config.msgpack", "wb") as f:
    msgpack.dump(config, f)
```

---

## Documentation

Full documentation is available via:

```bash
cargo doc --open
```

---

## 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.