Examples

Below are various examples demonstrating Spinner’s capabilities. Each example includes a YAML snippet (embedded with the mkdocs-include plugin) so you can run them directly or adapt them to your needs.

1. Simple Sleep Benchmark

A minimal illustration of how Spinner handles a small parameter sweep. Runs two different sleep_amount values:

metadata:
  description: Sleep check
  version: "1.0"
  runs: 2
  timeout: 5
  retry: 1
  envvars: []

applications:
  sleep_test:
    command: >
        sleep {{sleep_amount}} && printf "I slept {{sleep_amount}}"

benchmarks:
  sleep_test:
    sleep_amount:
      - 1
      - 2

How to run:

spinner run docs/examples/sleep_benchmark.yaml -o output.pkl

This will produce a sleep_results.pkl file containing run metadata and any captured output.

2. Capturing Command Output

Demonstrates capturing and parsing output (in this case, timing info from the time command). Useful for HPC applications that print performance metrics on stdout.

metadata:
  description: shell time capture output
  version: "1.0"
  runs: 5
  timeout: 100
  retry: 10
  envvars: []

applications:
  sleep:
    command: >
      bash -c "time sleep {{amount}}"

    capture:
      - type: matches
        name: real_time
        pattern: "real"
        lambda: >
          lambda x:  (
          float(x.split("m")[0].split("\t")[1]) * 60
          +
          float(x.split("m")[1].split("s")[0])
          )

    plot:
      - title: Real Time vs Sleep arg
        x_axis: amount
        y_axis: real_time
        group_by: amount

      - title: Measure Time vs sleep arg
        x_axis: amount
        y_axis: time
        group_by: amount

benchmarks:
  sleep:
    amount: [1, 2]

How to run:

spinner run docs/examples/capture_output.yaml

Check the resulting dataframe for the extracted timing fields (real_time).

3. Passing Extra Arguments (--extra-args)

Shows how to pass extra parameters at runtime without editing the YAML. This is helpful when HPC scripts need certain parameters (like hosts) populated by the scheduler or environment.

metadata:
  description: Sleep check using --extra-args flag
  version: "1.0"
  runs: 1
  timeout: 10
  retry: 1
  envars: [PATH, USER]

applications:
  sleep_test:
    command:
        sleep {{sleep_ammount + (extra_time | int)}}

benchmarks:
  sleep_test:
    sleep_ammount:
      - 1
      - 2

How to run:

spinner run docs/examples/extra_args.yaml --extra-args "extra_time=4"

Here, extra_time=2 is added on top of sleep_ammount.

4. Timeout Handling

Demonstrates automatic timeout behavior. If a command exceeds the specified timeout, Spinner stops it and records a failure (optionally rerunning if retry is enabled).

metadata:
  description: Timeout test
  version: "1.0"
  runs: 1
  timeout: 5
  retry: False
  envvars: ["PATH"]

applications:
  sleep_test:
    command: >
      sleep {{sleep_amount}} && printf "I slept {{sleep_amount}} # this may not print due to timeout!"

benchmarks:
  sleep_test:
    sleep_amount:
      - 1
      - 200

How to run:

spinner run docs/examples/timeout_test.yaml

Spinner will attempt to run both sleep_amount values; the 200-second sleep will hit the 5-second timeout.

---

Tip: Use the plot directives in your YAML configs to automatically generate charts from the collected data. For more details, see the capture_output.yaml example’s plot section.

Return to the Main Page or learn about Using Spinner with SLURM.