Merge pull request #174 from BerkeleyLab/doc-ifx

Documentation: Add ifx build/test instructions to README.md

Author: rouson

.github/workflows/CI.yml

@@ -12,10 +12,10 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Install fpm
-      uses: fortran-lang/setup-fpm@v4
+      uses: fortran-lang/setup-fpm@v7
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
 

.github/workflows/deploy-docs.yml

@@ -13,7 +13,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Install Dependencies Ubuntu
       run: |

.github/workflows/draft-pdf.yml

@@ -15,22 +15,46 @@ Prerequisites
 Downloading, Building, and Testing
 ---------------------------------
 
-### Single-image (serial) execution
+### GNU Compiler Collection (GCC) `gfortran` Compiler
+
+#### Single-image (serial) execution
 With `gfortran` installed, download, build, run and test Matcha in a single image by entering the following commands in a `bash`-like shell:
 ```
 git clone https://github.com/rouson/matcha
 cd matcha
 fpm test
 ```
 
-### Multi-image (parallel) execution
+#### Multi-image (parallel) execution
 With `gfortran` and OpenCoarrays installed, build, test, and run Matcha in multiple images by entering the following commands in a `bash`-like shell:
 ```
 fpm test --compiler caf --runner "cafrun -n 2"
 fpm run --compiler caf --runner "cafrun -n 2"
 ```
 Change '2' above to the number of images that you would like to launch in parallel.
 
+### Intel OneAPI `ifx` Compiler
+#### Multi-image (parallel) execution
+The unit test suite uses small grids to minimize runtime, which limits the scalability of the test suite only.
+Hence, the test suite is _not_ designed for execution in a large number of images.
+All tests pass when running the test suite in 1-4 images: 
+```
+export FOR_COARRAY_NUM_IMAGES=4
+fpm test --compiler ifx --profile release --flag "-heap-arrays -coarray"
+```
+
+#### Single-image (serial) execution
+Same as multi-image execution except `FOR_COARRAY_NUM_IMAGES=1`.
+
+#### Automatic GPU-based acceleration: _Experimental_
+The following command is listed here for reference while we investigate what appear to be platform-specific compiler issues causing a crashe when automatic GPU-based acceleration is enabled with the required coarray features:
+```
+fpm test \
+  --compiler ifx \
+  --profile release \
+  --flag "-heap-arrays -coarray -fopenmp-target-do-concurrent -qopenmp -fopenmp-targets=spir64"
+```
+
 ## Documentation
 Please visit the [Matcha Github Pages](https://berkeleylab.github.io/matcha) site to see HTML Documentation generated with ford.