---

name: workflows description: "Compose and validate Earth2Studio deterministic and prognostic-plus-diagnostic inference workflows with coordinate-aware inputs, outputs, devices, checkpoints, and offline protocol checks." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Earth2Studio workflows

Use this skill when a task needs a concrete Earth2Studio inference pipeline built from a prognostic model, a data source, an IO backend, and optionally a coordinate-compatible diagnostic model. It owns the deterministic and prognostic-plus-diagnostic paths exposed by earth2studio.run; it does not own ensemble orchestration, data-only retrieval, detailed backend selection, or remote serving.

Decide the path

1. Clarify initialization times, forecast horizon, variables, spatial domain, output format, and CPU/GPU constraints. Use ISO-8601 strings, datetime, or np.datetime64 values for time.
2. Select a prognostic class whose input_coords() can be supplied by the selected DataSource or ForecastSource. Inspect its output_coords() to learn the model step and output variables; do not assume all models use the same grid or lead time.
3. Add a diagnostic only when a derived field is required. Its input_coords() must be mappable from each prognostic output, and its output_coords() determines the variables written by run.diagnostic.
4. Select an IO object and initialize it outside the workflow. The run function mutates and returns the same IO object. See API reference for the narrow IO contract and supported public backend names.
5. Calculate nsteps from the model's advertised lead-time increment. A run writes the initial state plus nsteps forecast steps, so the lead-time axis has nsteps + 1 entries.

Load components

For a packaged model, use the class's public loading pair; the package handle is lightweight, while load_model may access remote or cached assets:

from earth2studio.models.px import <PrognosticClass>

prognostic = <PrognosticClass>.load_model(
    <PrognosticClass>.load_default_package()
)

Use the analogous pair from earth2studio.models.dx for a diagnostic. Model classes can require targeted optional extras and model-specific hardware; do not recommend an extra until the chosen class's installation notes are known. A network-free smoke path uses Persistence, Identity, Random, and ZarrBackend; it checks protocol and coordinate behavior without model weights. See workflow recipes.

Run deterministic inference

Construct data and io, inspect prognostic.input_coords(), then call:

from earth2studio import run

result = run.deterministic(
    time=["2024-01-01T00:00:00"],
    nsteps=8,
    prognostic=prognostic,
    data=data,
    io=io,
    output_coords=output_coords,  # omit or use OrderedDict({}) for all output
    device=device,                # None selects CUDA when available, else CPU
    verbose=True,
    checkpoint=checkpoint,         # optional checkpoint manager/session
)

run.deterministic fetches the prognostic initial-condition variables and lead times, maps them to the model grid, iterates from the initial state, applies output_coords at each step, and calls io.write. It returns io, not a new result wrapper. Use a small nsteps and verbose=False for a smoke run.

Run diagnostic inference

Keep the same initial-condition and prognostic setup, load a diagnostic, and call run.diagnostic(time, nsteps, prognostic, diagnostic, data, io, ...). The workflow maps each prognostic step to diagnostic.input_coords(), invokes the diagnostic, then maps to output_coords before writing. Its output is the diagnostic result; it does not retain the prognostic fields in the output backend. If both are required, compose a custom workflow rather than assuming this built-in path stores both.

Coordinate and horizon checks

Before a live run:

• Compare data variables with prognostic.input_coords()["variable"].
• Read the model's lead_time increment and use an integer nsteps.
• Preserve coordinate key order: keys describe tensor dimensions. Common keys are batch, time, lead_time, variable, lat, and lon.
• Keep output_coords a subset of produced dimensions. Variable restrictions must name produced variables; spatial restrictions may select or nearest-map numeric 1-D coordinates. Empty arrays are used by model protocols for free dimensions; do not use empty output overrides unless the backend contract explicitly permits them.
• For a diagnostic, check every required diagnostic dimension and variable can be mapped from the prognostic output. Exact grid handshakes may still be required by a model even where the workflow can numerically map coordinates.
• Run the bundled offline checker before spending network or GPU resources: python path/to/check_workflow_config.py --config workflow.json.

See workflows for runnable CPU mock examples and troubleshooting for recovery by failure class.

Boundaries and omissions

This sub-skill intentionally omits run.ensemble and perturbation/batch-size orchestration, a catalog of IO backend options, custom model implementation, full data-source selection, serving clients, and model-weight download procedures. It names public interfaces and targeted-extra constraints but does not claim exhaustive model, data, or backend coverage. Use the sibling skill for deterministic forecast selection when the task is only model/data/horizon recommendation; use data-fetch or installation guidance for those concerns.

Handoff checks

Report the selected workflow, model/data/diagnostic classes, initialization times, nsteps and implied lead-time horizon, output coordinate restriction, device, IO backend, whether weights/data are downloaded, and the validation performed. Preserve unresolved coordinate, optional-extra, credential, and hardware limits instead of presenting a smoke test as a scientific forecast.

• API and signatures
• Workflow recipes and validation
• Predictable failures
• Offline configuration checker