Chapel Tutorial

1.1. About this Tutorial

This tutorial is designed to quickly get you started programming in Chapel, and is meant to serve as an introductory guide to the language. We begin with a discussion of the basic and serial parts of Chapel before moving on to the parallel aspects. It is written to be accessible to a broad audience, so we do not assume background other than familiarity with a programming language such as Java or C. More advanced tutorials written by the Chapel group are available here. They have also written a "quick reference sheet" which summarizes Chapel syntax in a single page.

This tutorial is based on those, plus help and recources from others including Kyle Burke, Brad Chamberlain, Rahul Ghangas, and the Chapel development team.

The authors of this tutorial are Tegan Doherty, Johnathan Ebbers, Austin Finley, Maxwell Galloway-Carson, Michael Graf, Sung Joo Lee, Matt Lichty, Andrei Papancea, Casey Samoore. Its creation was partially supported by National Science Foundation's "Transforming Undergraduate Education in Science, Technology, Engineering and Mathematics (TUES)" program under Award No. DUE-1044299, The Baker-Velde Student Award Research Award, and the Andrew W. Mellon Foundation. It is currently being maintained by David Bunde. Please let us know what you think of the tutorial so that we can continue to improve it.

1.2. About Chapel

Chapel is a parallel programming language developed by Cray. Its syntax is fairly similar to other imperative programming languages such as C or Java. It includes support for popular programming styles such as object-oriented programming and type-generic programming (think Java generics or C++ templates), but the main attraction is that it allows the programmer to easily express different kinds of parallelism in a portable way. It does this by giving the programmer both high-level abstractions such as reductions as well as supporting a low-level approach based on locks and threads. The high-level abstractions essentially automate common forms of parallel programming, allowing the programmer to be more productive and eliminating potential mistakes. Providing the low-level approach gives the programmer more control (if desired) and allows them to "get their hands dirty" when doing so is necessary for performance.

1.3. Installation and Configuration

Instructions for installing Chapel are here.

1.4. Hello World!

Let's begin with writing one of the simplest programs in any language, "Hello World!", a program which prints this message to the screen. To write this program in Chapel, type the following line into a new file named hello.chpl:

1.5. Input and Output

Basic output in Chapel is rather simple. The two main procedures for output (Chapel's functions/methods) to use are write and writeln. The difference is that writeln will append a newline character to the end of all of the text output. These functions are similar to Java's System.out.print and System.out.println commands. Here's an example of a short program that prints a line of text containing two variables:

var word: string;
word = stdin.read(string);
writeln(word);

1.6. Variables

Chapel supports several simple variable types and a somewhat different way of defining and initializing them. For this introduction, there are four basic types that you should know:

bool

1.7. Declaration Modifiers

var: Required to declare an ordinary variable that can be altered after initialization.

const: Used to declare a variable that is constant -- that cannot be altered after initialization.

config: Config variables must be declared (and initialized) at the beginning of the module (similar to Java's class, and will be discussed later on) containing the main method, outside of any methods themselves. Defining a variable as a config essentially allows you to change the default value of the variable at runtime when calling your chapel program via the command line – for example

1. [config] var/const identifier = value;
2. [config] var/const identifier: type;
3. [config] var/const identifier: type = value;
4. [config] var/const identifier: type = value:type;

1.8. If-Else

Conditionals in Chapel (i.e. if-else statements) have a very similar syntax to the ones in C or Java. The only difference is that you need to use the then keyword if you omit braces:

1.9. Arrays

Creating arrays in Chapel is quite different from that of C or Java. The two examples below demonstrate it:

To facilitate array operations, Chapel automatically promotes standard scalar operators and functions to perform element-wise operations on arrays of numbers.

1.10. Range

A range expression is a unique expression to Chapel that takes the form of [low]..[high], and represents a sequence of numbers. 1..4 represents 1, 2, 3, and 4, for example. Note that if the first number in the range is greater than the second (e.g. 6..2), the range is empty. If low or high is unspecified, then the range is unbounded in that direction (e.g. the range, 5.. results in a range of numbers starting with 5, and continuing on for infinity. A range with an infinite bound, however, cannot be used in as a conditional, such as in a for loop, unless it is intersected with at least one other range. An example of a range intersection is:

1.11. For Loops

In Chapel for loops have the following syntax:

If the loop body is a single statement, you can omit the parentheses by following the iterable expression with the keyword do as in the following:

config var n: int = 10;
var A: [0..n] int;
var x: int = 1;

//Notice how "a" is an element of the array A and that you can store values in the array by assigning them to "a"
for a in A {
    x *= 2;
    a = x;
}

for i in 0..n {
    writeln(A(i));
}

1.12. While Loops, Do-While Loops

While loops and do-while loops share the same syntax as in C or Java. Check out the example below:

1.13. Records and Classes

Chapel's implementation of structures comes in two flavors: records and classes. The distinction is that records are value-based and classes are reference-based – in other words, an assignment of a record literally copies the record (much like an assignment of a structure in C), whereas an assignment of a class copies a reference to the class object (as in pointers to structures in C, or object references in Java). An example of a record is:

Now that you have a better grasp of Chapel you should be ready to learn the parallel features of it, permitting you to write scalable parallel programs. Chapel's main forms of parallelization are done via tasks and threads. The most common methods of parellelizing code in Chapel are to use a combination of forall and coforall loops, and the begin and cobegin statements. Let's take a look!

2.1. Forall and Coforall

Forall loops are a simple and easy way to run similar tasks in parallel using a for loop. When a forall loop runs, it creates a thread for each core of the processor. After the threads have finished they are joined together to form the result. Note that threads are created at the beginning of the first iteration through the loop.

2.2. Begin and Cobegin

The other forms of asynchronous parallelization in Chapel are the begin and cobegin statements. By using a begin statement on a process you create a different thread for each statement.

2.3. Sync and Atomic Variables

To prevent race conditions on variable updates, you can use sync variables. These variables can store a value as normal, but they also have two states: empty and full. When a sync variable is full it will stop any other thread to use it until it is turned empty. A sync variable is set to full when it is given a value and it is set to empty whenever it is assigned to another sync variable.

For example, we can fix the broken forall loop in section 2.1 by making the sum into a sync variable:

Sync variables can also be used as a lock in the style of other languages, though it is much slower. For example, here is another way to fix this summation example:

2.4. Sync Statements

sync can also be applied to a statement or block of code. When used this way, it will join together all begin statements started within that statement or code block. This can prevent potential race conditions that would occur if the program did not wait for begin statements to finish. It can be used to create a construct similar to cobegin, as the following segnment of code demonstrates:

2.5. Reduce

Reduce is an operator that combines a set of values to produce a single value. Reduce is useful because in parallel computation it is almost always necessary at some point to compare or combine results produced by different threads. The syntax for reduce is:

var D: domain(1) = 1..10;
var A: [D] int = (-5,6,-2012,-75,2012,48,-700,65,100,0);

var minVal = min reduce A;
var secMin = min reduce ([i in D] if A[i] > minVal then A[i]);

writeln("The minimum is ",minVal," and the second minimum is ",secMin,".");

2.6. Custom Reductions

A custom reduction is powerful tool that allows you to reduce an iterable expression with a custom operator other than the default ones (see above). To build a custom operator you need to write a class that has the following structure:

2.7. Scan

A scan embodies the logic that performs a sequential operation in parts and carries along the intermediate results. Loop iterations appear to be sequential because they accumulate information in order as they iterate, but on closer inspection, they can often be solved using a scan, which admits more parallelism. The syntax for scan is:

3.1. Operators

Operators in Chapel are virtually identical to those in C or Java. There are, however, a couple of exceptions:

cast:

exponentiation:

exponentiation:

3.2. Range Operators

Within the context of arrays, it is important to introduce one more thing about ranges. In order to allow flexibility within control structures such as for loops, Chapel has range operators, which allow you to create patterns for iterating through the range. For example:

for i in 1..10 by 2 {
    write(i,", ");
}

writeln();

for i in 1..10 by -1 {
    write(i,", ");
}

3.3. Tuples

Tuples are variables that contain groups of numbers, such as ordered pairs. This is best explained by the following example:

3.4. Domains

A domain is a range of indicies that can be dynamically resized. The example below shows you how to create a domain with a range of 1 to some int variable s:

var s: int = 10;
var D: domain(1) = 1..s;
var A: [D] int;

for i in 1..s {
    A[i] = i;
}

writeln(A);

D = 1..s*2;

for i in 1..s {
    A[i+10] = 11-i;
}

writeln(A);

3.5. Select

Select works similar to a switch statement in C or Java. The only difference is the wording: select instead of switch, when instead of case, and otherwise instead of default. The following is an example of a select statement in its proper Chapel syntax:

config var x:int;

select(x){
    when 1 {
        writeln("You chose 1.");
    }
    when 2 {
        writeln("You chose 2.");
    }
    otherwise {
        writeln("You did not chose 1 or 2.");
    }
}

3.6. Procedures

Procedures are Chapel's version of functions/methods. Procedures are declared with the keyword proc, followed by the name of the procedure. Some key things to note about Chapel's procedures are that argument and return types can be omitted, allowing for generic programming. Also, procedure parameters can have default values specified so that the procedure can be called without passing any arguments. The scope of this tutorial does not cover omission of argument types, which is known as generic programming. Example of syntax for procedures that do not use arguments:

3.7. Modules

A module is a construct that works much like a package does in Java. To access the procedures and variables in another class, you need to include its code at the beginning of the module with the keyword use, followed by the name of the module to use. If the module is not a Chapel standard or included in the same directory, a path to that module file will have to be specified (enclosed in quotes).

Chapel contains some library modules to make programming easier, much in the same way that Java and C have libraries. One obvious example is the Math module. This module does not need to be declared because it is a default module in all versions of Chapel. A complete listing of the procedures provided by this module can be found here Some helpful procedures are: