Getting Started

Get IOWarp running in 5 minutes.

Docker (Recommended)

The fastest way to get started with IOWarp is using Docker Compose. This method handles all dependencies and provides a consistent environment across different systems.

Isometric terminal showing CLIO installation: pip install, kit install, and status commands

docker-compose.yml

services:
  iowarp-runtime:
    image: iowarp/iowarp:latest
    container_name: iowarp-runtime
    volumes:
      - ./wrp_conf.yaml:/etc/iowarp/wrp_conf.yaml:ro
    ports:
      - "5555:5555"
    shm_size: 8g
    mem_limit: 8g
    ipc: shareable
    stdin_open: true
    tty: true
    restart: "no"

Run Command

clio deploy --mode docker

The -d flag runs the container in detached mode. Use docker-compose logs -f to view runtime logs.

Important Configuration Notes

• shm_size: 8g — Required for Hermes shared memory IPC. Increase if you need larger shared memory allocations.
• ipc: shareable — Enables inter-process communication between containers.
• Port 5555 — Default ZeroMQ port for IOWarp runtime communication. Change in wrp_conf.yaml if needed.

Configuration

IOWarp uses a YAML configuration file (wrp_conf.yaml) to define runtime modules, storage tiers, and system parameters.

wrp_conf.yaml Example

compose:
  - mod_name: wrp_cte_core
    pool_name: wrp_cte
    pool_query: local
    pool_id: 512.0
    storage:
      - path: "ram::cte_ram_tier1"
        bdev_type: "ram"
        capacity_limit: "16GB"
        score: 0.0

compose Section

mod_name: Name of the runtime module to load (e.g., wrp_cte_core)
pool_name: Memory pool identifier for this module
pool_query: Pool query type (local, remote)
pool_id: Unique pool identifier (float)

storage Section

path: Storage path identifier. Format: tier_name::storage_name
bdev_type: Block device type: ram, nvme, file, async
capacity_limit: Maximum storage capacity (e.g., 16GB, 1TB)
score: Placement score (0.0 = highest priority, higher = lower priority)

Storage Tier Explanation

IOWarp uses a hierarchical storage model with multiple tiers. The score parameter determines placement priority:

• score: 0.0 — Critical tier (GPU HBM, fastest RAM)
• score: 1.0-10.0 — Working tier (NVMe SSDs)
• score: 10.0-100.0 — Reference tier (Parallel File System)
• score: 100.0+ — Archive tier (Tape, Cloud)

Spack Installation

For HPC environments and native installations, IOWarp is available via Spack. This method provides optimized builds for your specific system architecture.

Installation Commands

spack install iowarp
spack load iowarp

Spack Variants

Customize your IOWarp installation with Spack variants:

# With CUDA support for GPU operations
spack install iowarp +cuda

# With MPI support for multi-node deployments
spack install iowarp +mpi

# With specific compiler
spack install iowarp %gcc@12

After installation, start the runtime with: clio deploy

Running Benchmarks

IOWarp includes comprehensive benchmarks to test performance and verify your installation. The benchmark suite covers various I/O patterns and storage tiers.

Basic Benchmark Run

cd demos/benchmark
docker-compose up

Custom Benchmark Parameters

TEST_CASE=Get IO_SIZE=4m IO_COUNT=1000 docker-compose up

Benchmark Parameters

Parameter	Description	Default
`TEST_CASE`	Benchmark test case: `Get`, `Put`, `PartialGet`, `PartialPut`	`Get`
`NUM_PROCS`	Number of parallel processes	`1`
`DEPTH`	Queue depth for async operations	`1`
`IO_SIZE`	Size of each I/O operation (e.g., `4m`, `1g`)	`1m`
`IO_COUNT`	Number of I/O operations to perform	`100`

Example Benchmark Scenarios

Large sequential reads:

TEST_CASE=Get IO_SIZE=1g IO_COUNT=10 docker-compose up

Small random writes:

TEST_CASE=Put IO_SIZE=64k IO_COUNT=10000 NUM_PROCS=4 docker-compose up

Partial I/O operations:

TEST_CASE=PartialGet IO_SIZE=4m IO_COUNT=1000 DEPTH=8 docker-compose up