Couple Command

The couple command allows you to run multiple coupled inference tasks that exchange data during execution. This is useful for running coupled model systems (e.g., atmosphere-ocean coupling) or ensemble systems where different model components need to communicate.

Description

The couple command coordinates multiple inference tasks that run simultaneously and exchange data through a specified transport mechanism. Each task can be configured independently while sharing common settings like date and lead time.

The command reads a coupling configuration file that defines:

Individual tasks and their configurations
Transport mechanism for data exchange between tasks
Coupling relationships specifying which tasks exchange what data
Global settings applied to all tasks

Couple tasks based on a configuration file.

usage: anemoi-inference couple [-h] [--defaults DEFAULTS]
                               config [overrides ...]

Positional Arguments

config: Path to config file. Can be omitted to pass config with overrides and defaults.
overrides: Overrides as key=value

Named Arguments

--defaults: Sources of default values.

Configuration

The coupling configuration file should have the following structure:

# Optional description
description: "Atmosphere-Ocean Coupled Run"

# Global settings applied to all tasks
date: 2025-01-01T00
lead_time: 240

# Transport mechanism
transport:
  threads: ~  # or 'processes', 'mpi', etc.

# Individual tasks
tasks:
  atmosphere:
    checkpoint: /path/to/atmos.ckpt
    input:
      grib: /path/to/atmos_ic.grib
    output:
      grib: /path/to/atmos_output.grib

  ocean:
    checkpoint: /path/to/ocean.ckpt
    input:
      grib: /path/to/ocean_ic.grib
    output:
      grib: /path/to/ocean_output.grib

# Coupling specifications
couplings:
  - from: atmosphere
    to: ocean
    variables: [sst, sss]  # Variables to exchange

  - from: ocean
    to: atmosphere
    variables: [u10, v10]

Transport Options

The transport mechanism controls how tasks communicate:

Transport	Description
`threads`	Run tasks in separate threads (lowest overhead, shared memory)
`processes`	Run tasks in separate processes (isolated memory)
`mpi`	Use MPI for inter-process communication (for HPC systems)

Examples

Basic Coupled Run

anemoi-inference couple coupled_config.yaml

With Overrides

anemoi-inference couple coupled_config.yaml date=2025-01-15T00 lead_time=120

Using Defaults

anemoi-inference couple --defaults base_config.yaml coupled_config.yaml