FrameIt Quick Start

This page describes the minimal workflow to run FrameIt using its command-line interface (CLI).

If FrameIt is not installed yet, see Installation of FrameIt first.

Prerequisites

  • A working Python environment where FrameIt is installed.

  • A FrameIt configuration file in YAML format (referred to as config.yml below).

Check that the CLI is available

After activating your environment, verify that the frameit command is visible:

frameit -h

If you cannot access the frameit executable (PATH issues on some HPC systems), you can use:

python -m frameit -h

Display environment information

To print the FrameIt version and key dependency versions:

frameit info

Prepare the YAML configuration

  1. Start from an example YAML shipped with the repository (see conf_example.yml), or copy an existing configuration.

  2. Update the following elements according to your case:

    • Input data locations (paths or patterns).

    • Output directory (frameit_output_dir).

    • Requested variables and processing options (tracking, extraction, polar projection, etc.).

Validate the configuration

FrameIt provides a lightweight configuration check that loads the YAML, checks right of writting in the output directory and applies the model preset:

frameit validate path/to/config.yml

If the configuration is valid, the command prints:

OK: configuration loaded successfully

Run FrameIt

Run the pipeline with:

frameit run path/to/config.yml

Logging is initialized automatically and written under the output directory specified in the configuration. At the end of the run, FrameIt prints a runtime summary (timer report) in the logs.

NetCDF exports

By default, the CLI runs NetCDF exports at the end of the pipeline:

  • NetCDF export: enabled by default

  • Polar export: enabled by default

  • Cartesian export: enabled by default

To disable some exports:

# Disable all NetCDF exports
frameit run path/to/config.yml --no-export-netcdf

# Disable only polar exports
frameit run path/to/config.yml --no-export-polar

# Disable only cartesian exports
frameit run path/to/config.yml --no-export-cart

You may also tune compression:

frameit run path/to/config.yml --compress-level N

Where N is the level of compression you want. The default is set to N=1. Note that increasing the level of compression could drastically increase the execution time of FrameIt.

Optional: HDF5 debug environment variable

The CLI removes the HDF5_DEBUG environment variable by default to avoid excessively verbose HDF5 logging. If you want to keep it unchanged:

frameit run path/to/config.yml --no-hdf5-debug-pop

Getting help for subcommands

For command help and available options:

frameit -h
frameit run -h
frameit validate -h
frameit info -h

Exit codes

  • 0: success.

  • Non-zero: an error occurred (details are reported in the FrameIt logs and/or printed to stderr).

Minimal HPC example (Slurm)

A typical Slurm wrapper may look like:

#!/bin/bash
#SBATCH -J frameit
#SBATCH --time=02:00:00
#SBATCH --nodes=1
#SBATCH --ntasks=1

source /path/to/conda.sh
conda activate frameit_env

frameit validate /path/to/config.yml
frameit run /path/to/config.yml

This example is intentionally minimal. Adapt resources and modules according to your HPC environment and workload.