Metadata-Version: 2.4
Name: cuckoo-sim
Version: 0.1.1
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib

# cuckoo-sim

Agent-based simulation of cuckoo brood parasitism — modeling the co-evolutionary arms race between cuckoo parasites and their reed warbler host species. Tracks population dynamics, egg-laying strategies, and host detection abilities over many generations.

## Installation

```bash
pip install cuckoo-sim
```

Or install from source in editable mode:

```bash
git clone <repo-url>
cd Data_And_Script/Model_Script
pip install -e .
```

## Quick Start

### GUI

```bash
cuckoo-gui
```

Opens a Tkinter interface with two tabs:
- **Configure & Run** — set input CSVs, population parameters, spatial grid, and run simulations
- **Results** — plot population time series, trait evolution, and spatial maps

### CLI

```bash
cuckoo-sim -c path/to/Cuckoo/ -r path/to/Reeds/ -o path/to/OUT/ \
  -c1 Cuckoo_12.csv -r1 ReedsBird_1.csv -q a -N 300 -M 10
```

Key arguments:

| Flag | Description | Default |
|------|-------------|---------|
| `-N` | Number of simulated years | 300 |
| `-M` | Number of iterations | 10 |
| `-P` | Crowding penalty coefficient | 0.9 |
| `-D` | Detection cost on breeding | 0.15 |
| `-pm` | Penalty mode (`exponential` / `logistic`) | `exponential` |
| `-gw`, `-gh` | Spatial grid width/height | 200 |
| `-s1`..`-s4` | Sigma values for trait variation | 0.02 / 1.0 |

### Python API

```python
from cuckoo_sim import SimConfig, run_simulation, aggregate_time_series

config = SimConfig(
    cuckoo_file="path/to/Cuckoo_12.csv",
    reeds_file="path/to/ReedsBird_1.csv",
    years=100,
    iterations=5,
    grid_width=100,
    grid_height=100,
)

results = run_simulation(config)
agg = aggregate_time_series(results)

for species, data in agg.items():
    print(f"{species}: final mean pop = {data['Total']['mean'][-1]:.0f}")
```

## Dependencies

Python 3.6+, numpy, scipy, matplotlib, tkinter.
