Quick Start

This guide assumes you have already installed IOWarp. It walks you through activating your environment, the default configuration, starting the Chimaera runtime, and running a Context Exploration Engine (CEE) example.

1. Activate Your Environment

Conda

conda activate iowarp

Spack

spack load iowarp

Docker

If you are using Docker, the environment is already set up inside the container. Exec into a running container:

docker exec -it iowarp bash

Pip

No activation needed -- the chimaera CLI and Python modules are available once the package is installed in your Python environment.

Verify the environment is active:

chimaera --help

2. Default Configuration

During installation a default configuration file is placed at:

~/.chimaera/chimaera.yaml

This file is only created if it does not already exist, so your customisations are never overwritten.

The runtime resolves its configuration in this order:

Priority	Source
1	CHI_SERVER_CONF environment variable
2	~/.chimaera/chimaera.yaml
3	Built-in defaults

The default configuration starts 4 worker threads on port 9413 and composes three modules automatically:

Module	Purpose
chimaera_bdev	512 MB RAM block device
wrp_cte_core	Context Transfer Engine with a 512 MB RAM cache
wrp_cae_core	Context Assimilation Engine

3. Start the Runtime

# Start in the background
chimaera runtime start &

# Verify it is running
chimaera monitor --once

# When done
chimaera runtime stop

4. Context Exploration Engine Example

The Context Exploration Engine (CEE) lets you assimilate data into IOWarp, query for it by name or regex, retrieve it, and clean up -- all from Python.

Save the following as cee_quickstart.py:

#!/usr/bin/env python3
"""IOWarp CEE Quickstart -- assimilate, query, retrieve, destroy."""

import os
import tempfile

import wrp_cee as cee

# -- 1. Create a sample file -------------------------------------------
data = b"Hello from IOWarp! " * 50_000          # ~950 KB
tmp = tempfile.NamedTemporaryFile(delete=False, suffix=".bin")
tmp.write(data)
tmp.close()
print(f"Created test file: {tmp.name} ({len(data):,} bytes)")

# -- 2. Initialise the CEE interface -----------------------------------
#    ContextInterface connects to the running Chimaera runtime.
iface = cee.ContextInterface()

# -- 3. Bundle (assimilate) the file -----------------------------------
tag = "quickstart_demo"
ctx = cee.AssimilationCtx(
    src=f"file::{tmp.name}",       # source: local file  (note :: not ://)
    dst=f"iowarp::{tag}",          # destination tag in IOWarp
    format="binary",               # raw binary ingest
)
rc = iface.context_bundle([ctx])
assert rc == 0, f"context_bundle failed (rc={rc})"
print(f"Assimilated file into tag '{tag}'")

# -- 4. Query for blobs in the tag -------------------------------------
blobs = iface.context_query(tag, ".*", 0)   # regex ".*" matches all blobs
print(f"Found {len(blobs)} blob(s): {blobs}")

# -- 5. Retrieve the data back -----------------------------------------
packed = iface.context_retrieve(tag, ".*", 0)
if packed:
    print(f"Retrieved {len(packed[0]):,} bytes")

# -- 6. Destroy the tag ------------------------------------------------
iface.context_destroy([tag])
print(f"Destroyed tag '{tag}'")

# -- Cleanup ------------------------------------------------------------
os.unlink(tmp.name)
print("Done!")

Run it (make sure the runtime is still running in the background):

python3 cee_quickstart.py

Expected output:

Created test file: /tmp/tmpXXXXXXXX.bin (950,000 bytes)
Assimilated file into tag 'quickstart_demo'
Found 2 blob(s): ['chunk_0', 'description']
Retrieved 950,029 bytes
Destroyed tag 'quickstart_demo'
Done!

5. Key Environment Variables

Variable	Description
CHI_SERVER_CONF	Path to YAML configuration file (highest priority)
CHI_IPC_MODE	Transport: SHM (shared memory), TCP (default), IPC (Unix socket)
CHI_PORT	Override the RPC port (default: 9413). Takes priority over YAML config.
CHI_SERVER_ADDR	Override the server address clients connect to (default: 127.0.0.1).
HSHM_LOG_LEVEL	Logging verbosity: debug, info, warning, error, fatal

Next Steps

• Edit ~/.chimaera/chimaera.yaml to tune thread counts, storage tiers, or add file-backed block devices
• Configuration Reference -- full parameter documentation
• HPC Deployment -- multi-node cluster setup
• CLIO Kit -- MCP servers for AI-powered scientific computing
• SDK Reference -- component APIs and development guides

Support

• Open an issue on the GitHub repository
• Join the Zulip Chat
• Visit the IOWarp website
• Email: grc@illinoistech.edu