Docker Tutorial

Estimated time: ~10 minutes

This tutorial verifies your CIMFlow installation and introduces the CLI commands.

Pull the Docker Image

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.

Start Interactive Session

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.

Verify Installation

Check CIMFlow Version

cimflow --version

Expected output:

CIMFlow 0.1.0

View Available Commands

cimflow --help

Output shows the main command groups:

Usage: cimflow [OPTIONS] COMMAND [ARGS]...

  CIMFlow - compile & simulate SRAM-based digital CIM

Options:
  --version             -V  Show CIMFlow version and exit.
  --debug                   Enable debug mode with full tracebacks and detailed error information.
  --install-completion      Install completion for the current shell.
  --show-completion         Show completion for the current shell, to copy it or customize the installation.
  --help                -h  Show this message and exit.

Commands:
  compile   Compiler front-end.
  sim       Simulator commands.
  run       Run compile and simulation pipeline.

Explore Pipeline Commands

cimflow run --help

Shows pipeline execution options:

Commands:
  pipeline    Run full pipeline: compile (CG + OP) → simulate.
  from-file   Run one or more pipelines defined in a JSON file.

Explore Compile Commands

cimflow compile --help

Shows compilation stages:

Commands:
  cg   Compile at computation graph level.
  op   Compile at operator level.

Check Component Versions

Verify the underlying compiler and simulator:

cim-compiler --version
cim-simulator --version

Install Shell Completion

Enable tab completion for faster command entry:

cimflow --install-completion
source ~/.bashrc

After sourcing, you can use Tab to complete commands and flags:

cimflow run pi<TAB>  # completes to "pipeline"
cimflow run pipeline -<TAB>  # shows available flags

Check Example Models

Verify models are available:

ls -lh data/models/

Expected output:

-rw-r--r-- 1 root root  45M resnet18.onnx
-rw-r--r-- 1 root root  14M mobilenetv2.onnx

If models are not present, they will be downloaded automatically on first pipeline run.

Docker Image Variants

Image	Download	Use Case
`cimflow-tutorial:latest`	~3GB	Pre-built, ready to use
`cimflow-tutorial:dev-base`	~1GB	Build from source

Using the Dev Base Image

For development or building from source:

docker pull ghcr.io/buaa-ci-lab/cimflow-tutorial:dev-base

docker run -it --rm \
  -v /path/to/cimflow:/app/cimflow \
  ghcr.io/buaa-ci-lab/cimflow-tutorial:dev-base

docker run -it --rm `
  -v C:\path\to\cimflow:/app/cimflow `
  ghcr.io/buaa-ci-lab/cimflow-tutorial:dev-base

docker run -it --rm -v C:\path\to\cimflow:/app/cimflow ghcr.io/buaa-ci-lab/cimflow-tutorial:dev-base

Inside container

cd /app/cimflow
./install.sh --shallow

Troubleshooting

File Structure

The container working directory structure:

resnet18.onnx

mobilenetv2.onnx

demo0_setup.sh

demo1_quickstart.sh

demo2_stages.sh

demo3_exploration.sh

exploration.json

What You Learned

Docker Setup — Pulled and started the CIMFlow tutorial container
CLI Exploration — Learned the main CIMFlow commands and structure

Docker Tutorial

Permission denied on output directory (Linux/macOS)

Models not found

On this page