1. Berkeley Lab Avatar Berkeley Lab
  2. CRD-CLaSS
  3. upcxx

Wiki

Clone wiki

upcxx / events / SC20

View History

UPC++ SC20 Virtual Tutorial

The Pagoda project was pleased to present a half-day UPC++ Tutorial at the virtual SC20 conference on November 10th, 2020. The tutorial includes interactive hands-on exercises along with an introduction to the UPC++ library and in-depth case studies of three applications using UPC++. Speakers notably include Professor Katherine Yelick, a highly distinguished lecturer and internationally recognized and decorat ed researcher.

Note this is an older version of a tutorial which was subsequently presented at SC21.

Watching the Video

The on-demand videos provided by SC20 expired in May 2021. However, you can still watch the pre-recorded video segments of the tutorial on YouTube:

Hands-on Tutorial for UPC++, presented at SC20

The YouTube version omits the live Q&A segments that are copyrighted by IEEE/ACM.

Preparation

Setting up UPC++

There are several ways to access a working UPC++ environment:

Installs on the major DOE centers

We maintain public installs of UPC++ at several DOE centers.

See Using UPC++ on NERSC Cori, OLCF Summit, and ALCF Theta

Download and install from source

UPC++ supports a wide range of UNIX-like systems and architectures, ranging from supercomputers to laptops, including Linux, macOS and Windows 10 (via WSL).

Visit the UPC++ download page for links to download and install UPC++ on your own system.

Docker containers with UPC++

We're providing a Linux Docker container for the UPC++ tutorial.

Assuming you have a Linux-compatible Docker environment, you can get a working UPC++ environment with the following command:

docker run -it --rm upcxx/sc20-linux-amd64

The UPC++ commands are upcxx (compiler wrapper) and upcxx-run (run wrapper), and the home directory contains the tutorial exercises and some example codes.

Getting Started with the Library

For training materials to get started using UPC++, see the UPC++ Training Page

Day of Tutorial

  • Tutorial Slides (PDF)
  • The SC20 On-demand stream for the UPC++ Tutorial is no longer available. Please see the YouTube video above.

Setting up the Hands-on Exercises

  1. Install or find a working UPC++ environment (see above)

  2. Download the tutorial content, which includes the starter files for exercises. The tutorial content is available in all of the following places:

  3. Navigate to the exercises directory (possibly tutorials/2020-11/exercises)

  4. The sections below describe each example in more detail

Exercise 0

Exercise 0 just tests you have a working UPC++ environment.

From the exercises directory of the tutorial materials, type this command to build and run hello world:

make run-ex0

This will build and run hello world using the default network backend. Note that on batch scheduled supercomputers this must be run inside a batch session.

You should see output similar to: 

/usr/local/upcxx/bin/upcxx -Wall ex0.cpp  -o ex0
/usr/local/upcxx/bin/upcxx-run -n 4 ./ex0
Hello world from process 1 out of 4 processes
Hello world from process 2 out of 4 processes
Hello world from process 3 out of 4 processes
Hello world from process 0 out of 4 processes

Troubleshooting:

  • make: upcxx: Command not found This means the UPC++ install was not found in your environment. You can either add the UPC++ bin directory to your $PATH variable, or set environment variable to the root of the UPC++ install: export UPCXX_INSTALL=/path/to/upcxx/install/tree

  • Job spawn failures (e.g. ssh: connect to host foo port 22: Connection refused). If you failed to launch a distributed job, the simplest resolution for the purposes of the tutorial exercises is to recompile for the single-node SMP backend, using the command: env UPCXX_NETWORK=smp make clean run-ex0 Assuming this fixes your problem, use a similar command for running the subsequent exercises (replacing run-ex0 with run-ex1, etc.)

Exercise 1

Working source file: ex1.cpp in exercises directory

Make command: make run-ex1 in exercises directory

Exercise 1 slide

Correct Output: Output lines in a correct solution should be ordered by rank. 

output.txt :
Hello from process 0 out of 4
Hello from process 1 out of 4
Hello from process 2 out of 4
Hello from process 3 out of 4

Exercise 2

Working source file: ex2.cpp in exercises directory

Make command: make run-ex2 in exercises directory

Exercise 2 slide

Correct Output: 

Running 1-d Jacobi on 4 procs, iters=100 global_domain_sz=1024
Running jacobi_rget...
  result = 51900  PASSED
Running jacobi_rput...
  result = 51900  PASSED
SUCCESS

Exercise 3

Working source file: ex3.hpp in exercises directory

Make command: make run-ex3 in exercises directory

Exercise 3 slide

Correct Output: 

erase() SUCCESS
update() SUCCESS

Extra Credit: Exercise 4

If you finish early, there is an optional exercise 4 (not explicitly covered during the presentation). This exercise asks you to fill in code for a more advanced version of a distributed hash table that uses RMA to accelerate transfers of large value data (exploiting zero-copy RDMA on systems where that's available).

Working source file: ex4.hpp in exercises directory.

Search for EXERCISE in the file for detailed instructions.

Make command: make run-ex4 in exercises directory

Correct Output: 

Constructing a DistrRMAMap<uint64_t,uint64_t>...
Inserting 100 key/value pairs from each of 4 ranks, with value sizes 8..800000 bytes...
Inserts complete!
Now issuing 100 finds from 4 ranks to verify...
Find complete!
Testing insert collision...
SUCCESS

Thanks for attending the UPC++ Tutorial!!!

Back to UPC++ Home

Updated