# Installation

## Requirements

| Dependency | Version | Notes |
|---|---|---|
| Python | ≥ 3.11 | |
| Julia | ≥ 1.10 | Install from [julialang.org](https://julialang.org/downloads/) |
| KinBiont.jl | ≥ 1.2 | Managed automatically by pykinbiont |

## Install pykinbiont

```bash
git clone https://github.com/pinheiroGroup/pykinbiont
cd pykinbiont
uv sync          # or: pip install -e .
```

## Two modes of operation

### Mode 1 — Managed environment (default)

juliacall creates and manages its own isolated Julia environment and downloads
KinBiont automatically. No local clone of KinBiont.jl is required.

```{admonition} First run
:class: warning

The first Python import after installation downloads Julia dependencies (~200 MB)
and precompiles the package (~3–5 minutes). Subsequent imports are fast because
Julia caches the compiled image.
```

```python
import pykinbiont   # triggers Julia startup on first import
```

### Mode 2 — Local KinBiont.jl development clone

If you are developing KinBiont.jl locally or need a specific unreleased version:

**Step 1** — Add PythonCall to your KinBiont.jl Julia project (one-time):

```bash
julia --project=/path/to/KinBiont.jl -e 'using Pkg; Pkg.add("PythonCall")'
```

**Step 2** — Tell pykinbiont where to find it (one-time, persisted to disk):

```python
import pykinbiont
pykinbiont.configure("/path/to/KinBiont.jl")
```

From then on, `import pykinbiont` automatically loads your local clone.

```{admonition} Kernel restart required
:class: note

`configure()` writes to juliapkg's environment file. You must restart the
Python process (or Jupyter kernel) once after calling `configure()` for the
change to take effect.
```

## Verify the installation

```python
import pykinbiont
import numpy as np

# Build a tiny synthetic dataset
times  = np.linspace(0, 10, 20)
curves = np.vstack([0.01 * np.exp(0.5 * times)] * 2)
data   = pykinbiont.GrowthData(curves=curves, times=times, labels=["A", "B"])

from pykinbiont import ModelSpec, LogLinModel, FitOptions, fit
spec    = pykinbiont.ModelSpec(models=[pykinbiont.LogLinModel()], params=[[]])
results = pykinbiont.fit(data, spec)
print(results.to_dataframe()[["label", "best_model"]])
```

Expected output:

```
  label best_model
0     A    log_lin
1     B    log_lin
```