charm4py-tutorial2026

Materials for the 2026 Charm4Py Tutorial at IPDPS, including examples and slides.

Many programming models have been developed to implement scalable parallel programs. Charm++ is built around the concept of distributed migratable objects, called chares. This empowers an introspective and adaptive runtime system (aRTS) to support automatic overlap of communication and computation, dynamic load balancing, energy optimization, fault tolerance, and resource elasticity. These signature adaptive capabilities distinguish Charm++ from MPI, the predominant parallel programming model.

Charm4Py is an implementation of the Charm++ programming model that makes these adaptive capabilities available to parallel Python programmers. Charm4Py programs use Python classes to implement chare objects; Charm++ features such as dynamic load balancing and asynchronous communication are made available to Charm4Py programs by linking it with the Charm++ aRTS under the hood. Charm4Py can thus be thought of as Distributed Adaptive Python, a parallel programming model with distributed adaptivity features that is compatible with existing Python conventions, and allows the use of existing popular Python libraries.

This tutorial aims to teach effective parallel programming using Charm4Py. Attendees will start with basic knowledge of Python, and by the end of the tutorial are expected to be able to code sophisticated parallel applications that can run on clusters, supercomputers, and cloud-based resources scalably and adaptively.

Presenters

Laxmikant Kale, Ritvik Rao, Maya Taylor, and Aditya Bhosale (University of Illinois Urbana-Champaign)

Tutorial Offerings

• Session 1: Monday, May 25 @ 8:30am-12:00pm
• Session 2: Tuesday, May 26 @ 8:30am-12:00pm

Updated conference schedule here.

Running the container in VS Code (recommended)

You'll need Docker Desktop and the Dev Containers extension for VS Code.

1. Clone this repository and open the folder in VS Code.
2. When VS Code prompts "Reopen in Container", click it (or run Dev Containers: Reopen in Container from the command palette).
3. First time only, VS Code pulls the tutorial image (~2 GB) — give it a few minutes. After that, opens in seconds.
4. You'll land in a terminal inside the container at /workspaces/charm4py-tutorial2026/, with the exercises and slides right there. Edits you make to the exercises are saved to your laptop.

Running in GitHub Codespaces (no local install)

If you don't want to install anything locally, you can open the tutorial in a GitHub Codespace (free tier covers 60 hours/month, just needs a GitHub account).

1. Open this repository on GitHub.
2. Click the green Code button → Codespaces tab → Create codespace on main.
3. The codespace builds in the cloud using the same dev container as the local VS Code workflow, then opens in your browser (or in your desktop VS Code if you prefer).

Everything in the tutorial folder lives in the codespace, so trace files generated by python3-prj stay there. To view them with Projections on your laptop, download them via the file explorer (right-click → Download).

Note: On Codespaces (and some restricted Docker setups), python3 -m charmrun.start +pN script.py fails with setarch: ... Operation not permitted. Use mpirun -n N python3 script.py instead — same effect in this container.

Running the container from the terminal

If you'd rather skip VS Code, you only need Docker.

docker pull adityapb/charm4py-tutorial:latest
cd path/to/charm4py-tutorial2026
docker run --rm -it \
    -v "$(pwd):/workspaces/charm4py-tutorial2026" \
    -w /workspaces/charm4py-tutorial2026 \
    adityapb/charm4py-tutorial:latest

The -v bind-mount means edits inside the container (and any trace files you generate) show up on your laptop in the same folder.

Profiling with Projections

The container includes python3-prj, a second charm4py build with Projections tracing enabled. Use it in place of python3 to record traces — no extra flags needed.

Run from inside the tutorial folder so trace files land on your laptop (the folder is shared between the container and your host). Then install the Projections viewer on your laptop (needs Java 8+) and open the .sts file to explore.

Tutorial Schedule

Module	Description	Exercises
Introduction	Overview of the Charm4Py programming model with basic examples. Attendees will install the Charm4Py Docker container.	Ex1
Chare Arrays	Learn about Chare arrays and associated communication primatives, including broadcasts, reductions, and channels.	Ex2, Ex3
Advanced Features	Discussion of load balancing and GPU integration in Charm4Py.
Profiling and Visualization	Learn how to profile Charm4Py programs with projections and how to use the liveViz visualization tool.	Ex4, Ex5