minimodal 0.1.0

A simple tool to compile and run CUDA kernels on local GPUs or Modal cloud infrastructure

minimodal

A simple command-line tool to compile and run CUDA kernels on local GPUs or Modal cloud infrastructure.

Features:

• Automatic GPU detection and architecture mapping
• Seamless fallback to Modal cloud GPUs when local GPU isn't available
• Support for include directories and custom nvcc flags
• Works with Modal GPU naming convention (A10G, H100, B200, etc.)

Installation

uv pip install minimodal

Or install from source:

cd minimodal
uv pip install -e .

Usage

Basic usage (defaults to A10G):

minimodal v1.cu

With a specific GPU:

minimodal v1.cu --gpu H100

With include directories:

minimodal v1.cu --gpu B200 -I ./includes

With execution arguments:

minimodal v1.cu --gpu A100 --exec-args "--N 2097152 --warmup 5"

With custom nvcc flags:

minimodal kernel.cu --gpu H100 -I ./includes --nvcc-flags "-O3 --ptxas-options=-v"

Supported GPUs

The tool automatically detects GPU architecture for common GPU models:

• H100 / H800 → sm_90
• A100 / A800 → sm_80
• A10G → sm_86
• B200 / B100 → sm_100a
• RTX4090 → sm_89
• RTX3090 / RTX3080 → sm_86
• V100 → sm_70
• T4 → sm_75

You can also specify the architecture directly using --arch:

minimodal kernel.cu --arch 100a

Options

• --gpu, -g: GPU name (e.g., A10G, H100, B200, A100) or architecture (e.g., 100a, 90). Default: A10G
• --include-dir, -I: Include directory. Can be specified multiple times.
• --exec-args: Arguments to pass to the compiled CUDA executable.
• --arch: Override architecture. If not specified, inferred from --gpu.
• --output, -o: Output executable path. If not specified, uses temporary file.
• --keep-binary: Keep the compiled binary after execution.
• --nvcc-flags: Additional flags to pass to nvcc (e.g., '-O3 --ptxas-options=-v').

Requirements

• CUDA toolkit with nvcc compiler
• NVIDIA GPU drivers
• nvidia-smi command-line tool

Examples

Compile and run a CUDA kernel (defaults to A10G):

minimodal v1.cu

Compile and run on a specific GPU:

minimodal v1.cu --gpu H100

Compile with multiple include directories:

minimodal kernel.cu --gpu B200 -I ./includes -I ./headers

Run with custom arguments:

minimodal benchmark.cu --gpu A100 --exec-args "--size 4096 --iterations 100"

Development

To develop locally:

git clone <repository-url>
cd minimodal
uv pip install -e .

Publishing to PyPI

# Build distribution
uv build

# Upload to PyPI
uv pip install twine
twine upload dist/*

License

MIT