Getting started

Two entry points

CoCoNet exposes the same simulation through:

Command-line interface (CLI) — for files, flags, and environment variables (terminals, Docker, shell scripts, simple CI). Use the coconet command or python -m coconet.
Python library — for programmatic control from other Python code. Install the PyPI distribution coconet-python; import coconet unchanged.

See CLI and Python API for full detail.

Requirements

Python 3.11+
Dependencies (see pyproject.toml): NumPy 2.2+, pandas 2.2+, PyYAML 6+, threadpoolctl 3.5+

Install

From PyPI (library + CLI)

The published package is coconet-python. After a normal install you get both the import package coconet and the coconet console script:

pip install coconet-python
coconet --help

python -c "from coconet import load_coconet_config, run_coconet; print('ok')"

From a git checkout (development)

From the repository root:

uv sync
uv run coconet --parameter-file legacy/I_2p6.csv --output-file output.csv

With a YAML config:

uv run coconet --config config/example.yaml --output-file output.csv

Editable / local install without uv:

pip install .
coconet --config config/example.yaml --output-file output.csv

Optional profiling dependencies (CPU profiles via pyinstrument):

uv sync --extra profile
# or: pip install "coconet-python[profile]"

First run (CLI)

# After pip install coconet-python, from a checkout or copy of inputs:
coconet --parameter-file legacy/I_2p6.csv --output-file output.csv

or with YAML:

coconet --config config/example.yaml --output-file output.csv

First run (library)

from coconet import load_coconet_config, run_coconet

cfg = load_coconet_config(
    config_file="config/example.yaml",
    output_file="output.csv",
)
run_coconet(cfg, configure_logs=True)

Use configure_logs=True when your application does not already configure the standard logging module; set it False and configure logging yourself for tighter integration with frameworks.

Environment overrides

Any CoconetConfig field can be overridden with the COCONET_ prefix (case-insensitive suffix matching the field name). This applies to both the CLI (before/during config load) and the library (load_coconet_config / CoconetConfig.from_file).

export COCONET_ENSEMBLE_RUNS=2
export COCONET_END_YEAR=1990
coconet --parameter-file legacy/I_2p6.csv

See Configuration for precedence.

Repository layout

Path	Purpose
`coconet/`	Package: `config.py`, `model.py`, `api.py` (library entry), `cli.py` (CLI), `netlogo.py`, `logging_utils.py`, `__main__.py`
`config/`	Example YAML (e.g. `example.yaml`)
`legacy/`	Original NetLogo model, reef and coastline CSVs, scenario parameter files
`documentation/`	This Jekyll documentation site
`viz/`	Optional React viewer for exploring `output.csv`
`gen-charts/`	Optional Node tooling to render charts from output

Typical workflow

Choose parameter file (legacy CSV) and/or YAML for scenario settings.
Point reefs and coastline inputs at CSVs (defaults often use legacy/ in a checkout).
Run the CLI (coconet / python -m coconet) or build config in Python with load_coconet_config and call run_coconet (library).
Consume output.csv (and optionally priority_reef_benefit.csv in search mode).

Details: Inputs and outputs, CLI, Python API.