Skip to content

Recipe Guide

Earth2Studio recipes are reference solutions that focus on solving specific use cases. Recipes provide more complex implementations that may require deeper domain knowledge and familiarity with the codebase.

Warning

Earth2Studio recipes are in beta and can change dramatically or be moved.

What is a Recipe?

While examples demonstrate how to use features, recipes focus on how to solve specific problems. Recipes are not intended to be turnkey solutions with every potential option; rather, they are reference or boilerplate projects for different common use cases.

Here's how examples differ:

  • Self-contained Jupytext format
  • Focus on demonstrating specific features
  • Include graphical output for Sphinx Gallery
  • Required to be part of earth2studio + docs dep group
  • Single GPU, A100 (40G) max resource requirement
  • Run in less than 10 minutes

Recipes

  • Require multiple support files
  • Focus on providing complete solutions
  • Configuration YAMLs and JSONs
  • Pythonic interaction through main.py
  • Requirements provided in pyproject.toml
  • May require more specific hardware or system dependencies

Refer to Examples for more information on creating an example.

Recipe Structure

The recipe template defines what a recipe should contain and look like, including folders, README sections, and support files. Recipes have the following structure:

recipes/
 |- recipe-name/
    cfg/
    |- config.yaml # Configuration files
    src/
    |- *.py # Support files
    test/
    |- test.py # Test files
    main.py # Main interaction script
    README.md # Recipe documentation
    recipe-requirements.txt # Exported requirements
    pyproject.toml # Project configuration

Recipe Guidelines

  1. Code Standards

    • Must follow all pre-commit standards and code practices.
    • Must include end-to-end tests validating functionality.
    • No images, data files, or other file formats are allowed in the repo; link to assets that are hosted externally instead. Earth2Studio has a HuggingFace assets dataset that can be used.
    • Implementation or re-implementation of components that exist in Earth2Studio package is not encouraged. Upstreaming is a priority.

  2. Testing

    • Should include end-to-end tests with expected results to verify functionality.
    • Not included in the main pytest suite.
    • Tested following major release cycles.

  3. Ownership

    • Must have designated owners (listed as authors in pyproject.toml).
    • Owners are responsible for fixing bugs and updates.
    • Recipes can and may be removed based on their use or relevance.

  4. Dependencies

    • Must use shipped versions of Earth2Studio (not the main branch).
    • Dependencies are managed through pyproject.toml using uv.
    • A requirements.txt should also be provided for pip install.

  5. Documentation

    • Clear README.md explaining purpose and usage.
    • Can include Jupytext notebooks for interactive documentation.
    • Should reference related examples when applicable.
    • Links to the recipes should be added to the recipe index.
    • Recipes can provide related plotting functionality.

Creating a New Recipe

To create a new recipe, you can use the template provided in the recipes directory:

cp -r recipes/template recipes/my_new_recipe
cd recipes/my_new_recipe

Update the pyproject.toml to reflect the correct metadata:

[project]
name = "newrecipe"
version = "0.1.0"
description = "My New Recipe"
readme = "README.md"
requires-python = ">=3.10"
authors = [
  { name="My Name", email = "optional@example.com" },
]

Inside the recipe dependencies can be added or removed using uv. For example:

uv sync
uv add cartopy

# Update the recipe-requirements.txt
uv export --format requirements-txt --no-hashes >> recipe-requirements.txt

Because recipes are more extensive, expect a longer review timeline. Making iterative updates expanding functionality is preferred.