Coarrays: images and this_image

A coarray is a variable that exists once per image, where an image is one process of the same program. Each image sees its own copy directly and every other copy through a bracket, and the compiler turns the brackets into whatever the machine needs: threads, shared memory or messages. This lesson declares one, asks how many images there are, writes to another image and reads it back, and reads the error a build without the flag gives.

A coarray

real :: a[*] is a scalar coarray with one codimension: every image has its own a, and the [*] says that the set of copies is indexed by image number. A plain reference a is the local copy; a[3] is the copy on image three. The bracket is called a cosubscript and the pair of brackets is a codimension.

The file co.f90:

program coarray_basics implicit none real :: a[*] a = 1.0 print '(a,i0)', 'num_images = ', num_images() print '(a,i0)', 'this_image = ', this_image() print '(a,i0)', 'lcobound = ', lcobound(a) print '(a,i0)', 'ucobound = ', ucobound(a) print '(a,f6.1)', 'local a = ', a a[1] = 2.0 print '(a,f6.1)', 'after a[1] = ', a a = 3.0 sync all print '(a,f6.1)', 'remote read= ', a[1] end program coarray_basics

gfortran -Wall -Wextra -std=f2018 -fcoarray=single co.f90 -o co
./co

num_images = 1
this_image = 1
lcobound = 1
ucobound = 1
local a = 1.0
after a[1] = 2.0
remote read= 3.0

Images and THIS_IMAGE

num_images() is how many processes the program was started with, and this_image() is which one is running. Both are intrinsic functions that every image calls, and the whole point of a coarray program is that the same source text runs on all of them: the code does not know how many images there are until it asks.

This run has one image, because that is what -fcoarray=single builds: the coarray syntax is compiled into ordinary local variables and every remote reference becomes a local one. A program written for eight images runs unchanged on one, which is what makes a coarray program testable on a laptop and is why this course can show one at all.

The -fcoarray flag

Coarrays are not enabled by default, and the flag chooses the implementation. -fcoarray=single is the one this image can build: one image, no library, no communication. -fcoarray=lib compiles the communication calls into a program that needs the OpenCoarrays runtime to link, and that runtime is not in this image: lesson 101 shows the real link error rather than pretending a parallel run happened here.

A program that uses coarrays therefore has a build line of its own, and the flag is part of the program's definition rather than a tuning option. A makefile that compiles the whole project with one command has to know which files are the coarray ones.

A remote reference

a[1] = 2.0 writes into the copy on image one, and with one image that is the local copy, which is why the next line reads 2.0. With two images the same statement on image two would write into the memory of image one, and the program would need a sync all before image one could count on seeing it. The sync all in the program is there for that reason even though it has nothing to do here.

Remote assignment is a put: the statement sends the value and, without a synchronisation, promises nothing about when the other image sees it. The three ways to order the two sides are sync all, sync images and the atomic subroutines, and the next lesson takes them apart. A coarray program without synchronisation is a data race with extra syntax.

Cobounds

lcobound(a) and ucobound(a) are the bounds of the codimension, and with one image both are one. A coarray may have more than one codimension, real :: grid[3, *], which gives a two-dimensional set of copies indexed by an image grid, and then the two enquiries take a dimension argument like their ordinary counterparts.

The bounds are a property of the run, not of the declaration: [*] means "as many as there are images", and a program that hard-codes eight images works on eight and fails on sixteen. The enquiry is one call, and it is how a program computes a block size before it starts.

Without the flag

The same file built with the flags every other lesson uses is refused at the declaration:

gfortran -Wall -Wextra -std=f2018 co.f90 -o co_plain

co.f90:3:13:

3 | real :: a[*]
| 1
Fatal Error: Coarrays disabled at (1), use '-fcoarray=' to enable
compilation terminated.

The message names the flag and the place, and it is a fatal error rather than a warning because the code cannot be compiled as ordinary Fortran: the cosubscript has no meaning without the runtime. This is the reason the build command of this lesson is not the one of the other lessons.

What one image can prove

A single image proves that the program compiles, that the local parts of the algorithm work and that the synchronisation statements are legal. It does not prove that the program is correct: the races of a coarray program appear only with two images, and this image cannot build that. Everything this page shows is the syntax and the local half, and the pages that follow say the same thing about each of their examples.

That is an honest limit of this container, not of the language. The same source built with OpenCoarrays on a machine that has it runs on as many images as the caller starts, and the code needs no change. A reader who wants a real run installs the library and runs cafrun -n 4 ./co; this page will not show that output because it was not produced here.

Exercises

  1. Add a second coarray integer :: b[*] and print b[1] before it is ever assigned. What does a reader learn from the value, if anything?
  2. Replace a[1] with a[2] and build with -fcoarray=single. What happens, and why?
  3. Declare real :: grid[2, *] and print lcobound(grid, 1) and ucobound(grid, 1). What are they with one image?
  4. Build the program with -fcoarray=lib and read the link error. Which library is missing?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is a coarray?

    Answer

    A variable that exists once per image, reached through cosubscripts

    Every image has its own copy and [n] names another copy.

  2. What does a[1] = 2.0 do?

    Answer

    Writes into the copy of a on image one

    The cosubscript names the image.

  3. What does the [*] in real :: a[*] mean?

    Answer

    One codimension, as large as the number of images

    The star defers the size of the codimension to the run.

  4. What does -fcoarray=single build?

    Answer

    One image with the coarray syntax compiled to local variables

    It is the mode this image can run.

  5. What does num_images() return?

    Answer

    The number of images the program runs on

    this_image() is the caller's number.

  6. Why is a sync all needed after a remote write?

    Answer

    Without it nothing orders the write against the other image's read

    A put promises nothing about when it is visible.

  7. What are lcobound and ucobound with one image?

    Answer

    Both one

    The codimension has one element on one image.

  8. What does gfortran report for a coarray built without -fcoarray?

    Answer

    Fatal Error: coarrays disabled, use -fcoarray= to enable

    The cosubscript has no meaning without a runtime.

  9. What does a run on one image NOT prove?

    Answer

    That the synchronisation is correct; races need two images

    The parallel half of the behaviour is not exercised.

  10. Which command runs a coarray program on four images once OpenCoarrays is installed?

    Answer

    cafrun -n 4 ./co

    cafrun is the launcher of OpenCoarrays; it was not run here.

The programs on this page were built with GNU Fortran (Alpine 15.2.0) 15.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev