food-opt

food-opt is a global food-systems optimization model built on PyPSA and Snakemake. It explores environmental, nutritional, and economic trade-offs through a configuration-driven mixed integer linear program build by reproducible workflow.

🚧 This project is currently under construction! 🚧

Documentation is kept up to date at a best effort basis. Certain model elements are still missing. Validation of model results has not yet been conducted. Expect frequent breaking changes.

Documentation

Documentation (model design, configuration reference, data provenance, API) lives under docs/; the documentation is built automatically by a Github Action and, for now, can be accessed by clicking the documentation badge at the top of this page.

Quickstart

Prerequisites

1. Install Git and pixi (cross-platform package manager)
2. Ensure ~30 GB of free disk space for datasets

Installation

git clone https://github.com/Sustainable-Solutions-Lab/food-opt.git
cd food-opt
pixi install

Setup (required before first run)

1. API credentials: Copy and configure the secrets file:

   cp config/secrets.yaml.example config/secrets.yaml
   # Edit config/secrets.yaml with your ECMWF Climate Data Store credentials
   # Get credentials at: https://cds.climate.copernicus.eu/user/register

2. Manual downloads: Three datasets require free registration and manual download:

   • IHME GBD mortality rates and relative risks (https://vizhub.healthdata.org/)
   • Global Dietary Database (https://globaldietarydatabase.org/)

   See the Data Sources documentation for detailed instructions. Place files in data/manually_downloaded/.

Run the model

tools/smk -j4 --configfile config/validation.yaml

The first run downloads several gigabytes of global datasets (GAEZ, GADM, land cover, etc.) and may take 30+ minutes.

Solver options

The default environment uses the HiGHS open-source solver. For faster solving with Gurobi (requires license):

pixi install --environment gurobi
tools/smk -e gurobi -j4 --configfile config/validation.yaml

Notes

• tools/smk wraps Snakemake with memory limits and environment configuration
• Results are saved under results/{config_name}/
• The workflow validates configuration and data before running

Repository Layout

• workflow/ – Snakemake rules and scripts, including the top-level workflow/Snakefile.
• config/ – Scenario YAMLs and shared fragments that parameterize the workflow.
• docs/ – Sphinx documentation sources (see docs/README.md for dev tips).
• tools/ – Helper wrappers such as tools/smk for consistent CLI entry points.
• results/ – Generated artifacts grouped by configuration (never hand-edit).

Additional contribution guidance can be found in the documentation; dataset provenance is tracked in data/DATASETS.md.

License

food-opt is licensed under GPL-3.0-or-later; documentation content follows CC-BY-4.0. See LICENSES/ for details.