diff --git a/docs.it4i/salomon/software/numerical-languages/opencoarrays.md b/docs.it4i/salomon/software/numerical-languages/opencoarrays.md new file mode 100644 index 0000000000000000000000000000000000000000..901a8020ae6d3fc117b1f1181c12c2fcc9c0f721 --- /dev/null +++ b/docs.it4i/salomon/software/numerical-languages/opencoarrays.md @@ -0,0 +1,127 @@ +# OpenCoarrays + +## Introduction + +Coarray Fortran (CAF) is an extension of Fortran language and offers a simple interface for parallel processing and memory sharing. +The advantage is that only small changes are required to convert existing Fortran code to support a robust and potentially efficient parallelism. + +A CAF program is interpreted as if it was replicated a number of times and all copies were executed asynchronously. +The number of copies is decided at execution time. Each copy (called *image*) has its own private variables. +The variable syntax of Fortran language is extended with indexes in square brackets (called *co-dimension*), which represents a reference to data distributed across images. + +By default, the CAF is using Message Passing Interface (MPI) for lower-level communication, so there are some similarities with MPI. + +Read more on <http://www.opencoarrays.org/> + +## Coarray Basics + +### Indexing of coarray images + +Indexing of individual images can be shown on the simple *Hello World* program: + +```fortran + program hello_world + implicit none + print *, 'Hello world from image ', this_image() , 'of', num_images() + end program hello_world +``` +* num_images() - returns the number of all images +* this_image() - returns the image index - numbered from 1 to num_images() + +### Co-dimension variables declaration + +Coarray variables can be declared with the **codimension[*]** attribute or by adding trailing index **[*]** after the variable name. +Notice, the ***** character always has to be in the square brackets. + +```fortran + integer, codimension[*] :: scalar + integer :: scalar[*] + real, dimension(64), codimension[*] :: vector + real :: vector(64)[*] +``` + +### Images synchronization + +Because each image is running on its own, the image synchronization is needed to ensure, that all altered data are distributed to all images. +Synchronization can be done across all images or only between selected images. Be aware, that selective synchronization can lead to the race condition problems like deadlock. + +Example program: + +```fortran + program synchronization_test + implicit none + integer :: i ! Local variable + integer :: numbers[*] ! Scalar coarray + + ! Genereate random number on image 1 + if (this_image() == 1) then + numbers = floor(rand(1) * 1000) + ! Distribute information to other images + do i = 2, num_images() + numbers[i] = numbers + end do + end if + + sync all ! Barrier to synchronize all images + + print *, 'The random number is', numbers + end program synchronization_test +``` + +* sync all - Synchronize all images between each other +* sync images(*) - Synchronize this image to all other +* sync images(*index*) - Synchronize this image to image with *index* + +!!! note + **number** is the local variable while **number[*index*]** accesses the variable in a specific image. + **number[this_image()]** is the same as **number**. + +## Compile and run + +Currently, version 1.8.10 compiled with OpenMPI 1.10.7 library is installed on Cluster. The OpenCoarrays module can be load as follows: + +```console +$ ml OpenCoarrays/1.8.10-GCC-6.3.0-2.27 +``` + +### Compile CAF program + +The preferred method for compiling a CAF program is by invoking the *caf* compiler wrapper. +The above mentioned *Hello World* program can be compiled as follows: + +```console +$ caf hello_world.f90 -o hello_world.x +``` + +!!! warning + The input file extension has to be **.f90** or **.F90** to be interpreted as *Fortran 90*. + If the input file extension is **.f** or **.F** the source code will be interpreted as *Fortran 77*. + +Another method for compiling is by invoking the *mpif90* compiler wrapper directly: + +```console +$ mpif90 hello_world.f90 -o hello_world.x -fcoarray=lib -lcaf_mpi +``` + + +### Run CAF program + +A CAF program can be run by invoking the *cafrun* wrapper or directly by the *mpiexec*: + +```console +$ cafrun -np 4 ./hello_world.x + Hello world from image 1 of 4 + Hello world from image 2 of 4 + Hello world from image 3 of 4 + Hello world from image 4 of 4 + +$ mpiexec -np 4 ./synchronization_test.x + The random number is 242 + The random number is 242 + The random number is 242 + The random number is 242 +``` + +where **-np 4** is number of images to run. The parameters of **cafrun** and **mpiexec** are the same. + +For more information about running CAF program please follow [Running OpenMPI](../mpi/Running_OpenMPI.md) diff --git a/mkdocs.yml b/mkdocs.yml index 6343f24ef87fba59fb68a03e7cc1314f34973122..4ab7eb725f617721bb6155a34fc358e9a7ce3e2e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -117,7 +117,8 @@ pages: - Introduction: salomon/software/numerical-languages/introduction.md - Matlab: salomon/software/numerical-languages/matlab.md - Octave: salomon/software/numerical-languages/octave.md - - R: salomon/software/numerical-languages/r.md + - R: salomon/software/numerical-languages/r.md + - OpenCoarrays: salomon/software/numerical-languages/opencoarrays.md - Operating System: salomon/software/operating-system.md - ParaView: salomon/software/paraview.md - Anselm Software: