update README and add more resources

Author: Guillaume-Helbecque

.gitignore

@@ -30,3 +30,6 @@
 *.exe
 *.out
 *.app
+
+# Chapel install
+*chapel-2.2.0MC

6-pgas-chapel/demo/hello_datapar.chpl

@@ -0,0 +1,30 @@
+// Data-parallel hello world
+
+/* This program uses Chapel's data parallel features to create a
+   parallel hello world program that utilizes multiple cores on a
+   single `locale` (compute node).
+ */
+
+
+//
+// The following `configuration constant` indicates the number of
+// messages to print out.  The default can be overridden on the
+// command-line (e.g., ``./hello --numMessages=1000000``).
+//
+config const numMessages = 30;
+
+//
+// Next, we use a data-parallel `forall-loop` to iterate over a
+// `range` representing the number of messages to print.  By default,
+// forall-loops will typically be executed cooperatively by a number
+// of tasks proportional to the hardware parallelism on which the loop
+// is running. Ranges like ``1..numMessages`` are always local to the
+// current task's locale, so this forall-loop will execute using the
+// number of local processing units or cores.
+//
+// Because the messages are printed within a parallel loop, they may
+// be displayed in any order.  The `writeln()` procedure protects
+// against finer-grained interleaving of the messages themselves.
+//
+forall msg in 1..numMessages do
+  writeln("Hello, world! (from iteration ", msg, " of ", numMessages, ")");

6-pgas-chapel/demo/hello_module.chpl

@@ -0,0 +1,47 @@
+// "Production-grade" hello world
+
+/* This program is conceptually very similar to :ref:`hello.chpl
+   <primers-hello>`, but it uses a more structured programming style,
+   explicitly defining a module, a configuration constant, and a
+   main() procedure.
+ */
+
+//
+// The following statement declares a module named 'Hello'.  If a
+// source file contains no module declarations, the filename minus its
+// ``.chpl`` extension serves as the module name for the code it
+// contains.  Thus, 'hello' would be the automatic module name for the
+// previous :ref:`hello.chpl <primers-hello>` example.
+//
+module Hello {
+
+//
+// This next statement declares a `configuration constant` named
+// `message`.  The type is inferred to be a string since the
+// initializing expression is a string literal.  Users may override
+// the default values of configuration constants and variables on the
+// executable's command-line.  For example, we could change the
+// default message for a given run using the command line: ``./hello
+// --message="hiya!"``.
+//
+  config const message = "Hello, world!";
+
+
+// Any top-level code in a module is executed as part of the module's
+// initialization when the program begins executing.  Thus, in the
+// previous one-line :ref:`hello.chpl <primers-hello>`, the presence
+// of a `writeln()` at the file scope formed the implicit `hello`
+// module's initialization and would be executed at program startup.
+// Since there was no explicit `main()` function or any other
+// top-level code, that's all that the program would do.
+
+
+//
+// In this program, we define an entry point for the program by
+// defining a procedure named `main()`.  This will be invoked after
+// this module and all the modules it uses are initialized.
+//
+  proc main() {
+    writeln(message);
+  }
+}

6-pgas-chapel/demo/hello_simple.chpl

@@ -0,0 +1,2 @@
+// Simple hello world
+writeln("Hello, world!");    // print 'Hello, world!' to the console

6-pgas-chapel/demo/hello_taskpar.chpl

@@ -0,0 +1,35 @@
+// Task-parallel hello world
+
+/* This program uses Chapel's `task parallel` features to express an
+   explicitly concurrent hello world program that utilizes multiple
+   cores on a single `locale` (compute node).
+ */
+
+
+//
+// First, we specify the number of tasks to create via a `config
+// const`.  By default, set it to the runtime's estimation of maximum
+// parallelism that the current locale ('`here`') is capable of
+// executing (``.maxTaskPar``).
+//
+config const numTasks = here.maxTaskPar;
+
+
+//
+// Next, we create the specified number tasks using a `coforall-loop`.
+// This is a parallel loop form that will create a distinct task per
+// iteration.
+//
+// This coforall-loop is iterating over the `range` ``0..#numTasks``
+// which represents the first `numTasks` integers starting at 0
+// (equivalent to ``0..numTasks-1``).  The result will be `numTasks`
+// iterations, each of which will be executed as a distinct parallel
+// task.
+//
+// Each iteration prints out a message that is unique based on its
+// value of `tid`.  Due to the task parallelism, the messages may be
+// printed in any order.  However, the `writeln()` procedure will
+// prevent finer-grained interleaving of the messages themselves.
+//
+coforall tid in 0..#numTasks do
+  writeln("Hello, world! (from task ", tid, " of ", numTasks, ")");

6-pgas-chapel/introduction.pdf renamed to 6-pgas-chapel/exercises/introduction.pdf

@@ -1,6 +1,6 @@
 /*
  * Author: Guillaume HELBECQUE (Université du Luxembourg)
- * Date: 25/10/2024
+ * Date: 26/10/2024
  *
  * Description:
  * This sequential program computes a Mandelbrot set of given size and
@@ -92,7 +92,9 @@ proc main() {
   compute(im);
   timer.stop();
 
-  writeln("Serial computational time [s]: ", timer.elapsed());
+  writeln("Computation of Manderbrot set with ", N, " iterations and ",
+    height, " x ", width, " resolutions");
+  writeln("Elapsed time [s]: ", timer.elapsed());
 
   save_image(im);
 

6-pgas-chapel/mandelbrot_seq.chpl renamed to 6-pgas-chapel/exercises/mandelbrot.chpl

@@ -0,0 +1,145 @@
+/*
+ * Author: Guillaume HELBECQUE (Université du Luxembourg)
+ * Date: 26/10/2024
+ *
+ * Description:
+ * Sequential backtracking to solve instances of the N-Queens problem in Chapel.
+ * It serves as a basis for parallel implementations.
+ */
+
+use Time;
+
+param INITIAL_CAPACITY = 1024;
+param MAX_QUEENS = 20;
+
+config const N = 14;
+
+// pool implementation
+record SinglePool {
+  type eltType;
+  var dom: domain(1);
+  var elements: [dom] eltType;
+  var capacity: int;
+  var front: int;
+  var size: int;
+
+  proc init(type eltType) {
+    this.eltType = eltType;
+    this.dom = {0..#INITIAL_CAPACITY};
+    this.capacity = INITIAL_CAPACITY;
+  }
+
+  // Insertion to the end of the deque
+  proc ref pushBack(node: eltType) {
+    if (this.front + this.size >= this.capacity) {
+      this.capacity *= 2;
+      this.dom = {0..#this.capacity};
+    }
+
+    this.elements[this.front + this.size] = node;
+    this.size += 1;
+  }
+
+  // Removal from the end of the deque
+  proc ref popBack() {
+    if (this.size > 0) {
+      this.size -= 1;
+      return this.elements[this.front + this.size];
+    }
+
+    var default: eltType;
+    return default;
+  }
+}
+
+// N-Queens node
+record Node {
+  var depth: uint(8);
+  var board: MAX_QUEENS*uint(8);
+
+  proc init() {};
+
+  proc init(const N: int) {
+    init this;
+    for i in 0..#N do this.board[i] = i:uint(8);
+  }
+
+  proc init(other: Node) {
+    this.depth = other.depth;
+    this.board = other.board;
+  }
+}
+
+// check if placing a queen is safe (i.e., check if all the queens already placed share
+// a same diagonal)
+proc isSafe(const board, const row, const col)
+{
+  for i in 0..#row {
+    if (board[i] == col - (row - i) || board[i] == col + (row - i)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+// evaluate a given node (i.e., check its board configuration) and branch it if it is valid
+// (i.e., generate its child nodes.)
+proc evaluate_and_branch(const parent: Node, ref tree_loc: uint, ref num_sol: uint, ref pool: SinglePool(Node))
+{
+  const depth = parent.depth;
+
+  // if the given node is a leaf, then update counter and do nothing
+  if (depth == N) {
+    num_sol += 1;
+  }
+  // if the given node is not a leaf, then update counter and evaluate/branch it
+  else {
+    for j in depth..(N-1) {
+      if isSafe(parent.board, depth, parent.board[j]) {
+        var child = new Node(parent);
+        child.board[depth] <=> child.board[j]; // swap
+        child.depth += 1;
+        pool.pushBack(child);
+        tree_loc += 1;
+      }
+    }
+  }
+}
+
+proc main()
+{
+  writeln("Sequential resolution of the ", N, "-Queens instance in Chapel");
+
+  // initialization of the root node (the board configuration where no queen is placed)
+  var root = new Node(N);
+
+  // initialization of the pool of nodes (stack -> DFS exploration order)
+  var pool = new SinglePool(Node);
+  pool.pushBack(root);
+
+  // statistics to check correctness (number of nodes explored and number of solutions found)
+  var exploredTree: uint = 0;
+  var exploredSol: uint = 0;
+
+  // beginning of the Depth-First tree-Search
+  var timer: stopwatch;
+  timer.start();
+
+  while pool.size != 0 {
+    // get a node from the pool
+    var parent = pool.popBack();
+
+    // check the board configuration of the node and branch it if it is valid
+    evaluate_and_branch(parent, exploredTree, exploredSol, pool);
+  }
+
+  timer.stop();
+
+  // outputs
+  writeln("\nSize of the explored tree: ", exploredTree);
+  writeln("Number of explored solutions: ", exploredSol);
+  writeln("Elapsed time: ", timer.elapsed(), " [s]");
+
+  return 0;
+}

6-pgas-chapel/exercises/nqueens.chpl

@@ -139,3 +139,26 @@ Suppose you have a shared resources (e.g. a web page) among many readers (e.g. t
 ### Project Big Graph
 
 The project description is [available here](https://github.com/ptal/parallel-and-grid-computing-uni.lu/tree/main/5-openmp/project/README.md).
+
+## Partitioned Global Address Space (Chapel)
+
+### Mandelbrot set computation (`6-pgas-chapel/mandelbrot_seq.chpl`)
+
+1. Install Chapel on your system using the provided script (it can take some minutes). Command:
+```
+cd 6-pgas-chapel/
+source chapel_install.sh
+```
+2. Read the introductory file [available here](https://github.com/ptal/parallel-and-grid-computing-uni.lu/tree/main/6-pgas-chapel/exercises/introduction.pdf).
+3. Implement a parallel approach where each thread computes a block made of
+contiguous lines of the global image. What do you observe in terms of speed-up compared to the sequential version?
+4. The goal is to improve the load balancing between threads. Implement a variant of the previous algorithm where each processor computes a block made of alternated lines. More precisely, we will assume that the *k*-th thread (*0 <= k < n*) takes in charge the lines indexed by *k + i n*.
+
+*Hints:*
+- *The number of threads `n` can be set in command-line using `CHPL_RT_NUM_THREADS_PER_LOCALE=n`;*
+- *Compile using the `--fast` optimization flag: `chpl --fast foo.chpl`;*
+- *You can verify that two images are similar using the output of `diff image1 image2`.*
+
+### [Optional⭐] N-Queens
+
+* `6-pgas-chapel/exercises/nqueens.chpl`: Parallelize the N-queens code seen in a previous course using Chapel.