Command Line Overview

The CHAMPS+ engine is a binary command-line application. At its core, it ingests a simulation definition file (.sdf) and produces a series of output files based on the simulation parameters. While the .sdf file controls the physics and discretization, the command-line arguments control the execution environment, logging, and hardware allocation.

Basic Usage

The simplest way to run CHAMPS+ is to provide the input file as an argument. The engine automatically detects the input file by looking for the first argument with the .sdf extension. With no sdf file specified, the engine will default to reading input.sdf

./champs+ input.sdf

Arguments & Flags

Below is a summary of the available command-line flags.

Input & Licensing

• Input File (.sdf) The first argument ending in .sdf is treated as the primary simulation input file.
• -license [path] Specifies a custom path to the license file. If not provided, the engine defaults to loading $CHAMPS_DATA/license.

Hardware & Execution

• -dev [spec] Specifies which GPU devices to use (e.g., all, 0, 0,1,2, per-rank).

• See Device Selection for the full list of specifiers.

• -heap [bytes] Sets the preallocated CUDA heap size in bytes.

• Note: This is primarily for internal debugging and is rarely needed for standard production runs.

Logging & Output

• -log [path] Generates an additional log file at the specified location, capturing the output that is sent to stdout/stderr.
• -verbose Enables verbose logging mode, printing additional diagnostic messages and internal status updates to the console and log file.

Examples

Run a simulation on a specific GPU with verbose logging: ./champs+ input.sdf -dev 0 -verbose

Run a simulation and save the log to a file: ./champs+ input.sdf -log run_output.log

Run with a custom license file: ./champs+ input.sdf -license /path/to/custom/license.lic