CIMFlow LogoCIMFlow

Examples

Hands-on tutorials for CIMFlow compilation and simulation

This section provides hands-on tutorials for using CIMFlow to compile and simulate deep learning models on CIM hardware. Follow the tutorials in order for the best learning experience.

Tutorial Overview

Docker Tutorial
~10 min
Setup with Docker and verify installation
Quick Start
~3 min
End-to-end pipeline in one command
Step-by-Step
~5 min
Compile and simulate stage by stage
Design Exploration
~8 min
Batch processing for hardware trade-offs

Prerequisites

The Docker image includes all dependencies and example models pre-configured.

Pull the tutorial image
docker pull ghcr.io/buaa-ci-lab/cimflow-tutorial:latest

The download is approximately 3GB. Ensure 15GB or more disk space is available after unpacking.

If running locally, ensure CIMFlow is installed and download example models:

Download models
./scripts/download_models.sh

Local installation requires Ubuntu 22.04+ (see system requirements) and building LLVM/MLIR from source (~20-30 minutes).

Quick Start with Docker

Start an interactive container

docker run -it --rm \
  -v "$(pwd)/output:/app/output" \
  ghcr.io/buaa-ci-lab/cimflow-tutorial:latest
docker run -it --rm `
  -v "${PWD}/output:/app/output" `
  ghcr.io/buaa-ci-lab/cimflow-tutorial:latest
docker run -it --rm -v "%cd%/output:/app/output" ghcr.io/buaa-ci-lab/cimflow-tutorial:latest

This mounts a local output directory to persist results outside the container.

Run the tutorial scripts

Inside the container, execute the demo scripts in order:

./tutorial/demo0_setup.sh       # Verify installation
./tutorial/demo1_quickstart.sh  # End-to-end pipeline
./tutorial/demo2_stages.sh      # Step-by-step compilation
./tutorial/demo3_exploration.sh # Design space exploration

Key Terminology

CG (Compute Graph)
High-level representation of neural network operations
OP (Operator)
Low-level CIM hardware operations
ISA
Instruction Set Architecture executed by the simulator
NoC (Network-on-Chip)
On-chip interconnect for inter-core communication
Macro Group
A group of CIM macro units processing data in parallel
Flit
Flow control unit - basic data transfer unit in the NoC

Hardware Parameters Reference

These parameters configure the CIM architecture for compilation and simulation:

ParameterFlagDescriptionTypical Values
T-tMacro group size (rows per macro)8, 16
K-kMacro group number (macros per core)16, 32
B-bNoC bandwidth (flits per cycle)8, 16
C-cTotal core count in the accelerator64, 128
batch_size--batch-sizeInference batch size1, 2, 4, 8

When parameters are omitted from a command, CIMFlow uses default values. See CLI Reference for all defaults.

Output Metrics

After simulation, CIMFlow reports these performance metrics:

Latency
End-to-end inference time for one batch (ms)
Power
Average power consumption during inference (mW)
Energy
Total energy consumed per batch (pJ)
TOPS
Tera operations per second (throughput)
TOPS/W
Energy efficiency (TOPS per watt)

Get Started

Ready to begin?

Start with the Docker Tutorial to set up your environment, then follow the tutorials in sequence for the complete learning experience.

Docker Tutorial

Setup verification and CLI exploration

Quick Start

Run ResNet-18 through the full pipeline

Step-by-Step

CG compile, OP compile, and simulation stages

Design Exploration

Batch processing for parameter sweeps

Last updated on

Docker Tutorial

Setup and verify CIMFlow with Docker

On this page

Tutorial Overview
Prerequisites
Quick Start with Docker
Start an interactive container
Run the tutorial scripts
Key Terminology
Hardware Parameters Reference
Output Metrics
Get Started