Merge branch 'feature.github.actions' into 'master.dev'

[feature.github.actions] Added GitHub workflows for compiling piclas with AppImage and publishing the executable

See merge request piclas/piclas!800

.github/workflows/piclas.desktop

@@ -0,0 +1,8 @@
+[Desktop Entry]
+Type=Application
+Name=piclas
+Exec=piclas
+Comment=PICLas is a flexible particle-based plasma simulation suite.
+Icon=piclas
+Categories=Development;
+Terminal=true

CMakeLists.txt

@@ -266,6 +266,14 @@ FOREACH (_var IN LISTS piclasVars piclasVars2 piclasVars3 piclasVars4)
   ENDIF()
 ENDFOREACH()
 
+# =========================================================================
+# HOPR pre-processor
+# =========================================================================
+OPTION(LIBS_BUILD_HOPR "Build HOPR pre-processor by compiling the source code downloaded from https://github.com/hopr-framework/hopr.git" OFF)
+SET(HOPR_TAG "v1.1.1" CACHE STRING "HOPR version tag for downloading the executable or compiling the source code (from GitHub)")
+SET(HOPR_DOWNLOAD_URL "https://github.com/hopr-framework/hopr/releases/download/${HOPR_TAG}/hopr-linux64.zip")
+OPTION(LIBS_DOWNLOAD_HOPR "Download HOPR pre-processor AppImage executable from ${HOPR_DOWNLOAD_URL}" OFF)
+
 # =========================================================================
 # ADD LIBRARIES
 # =========================================================================
@@ -289,11 +297,6 @@ ELSE()
   ENDFOREACH()
 ENDIF()
 
-# =========================================================================
-# HOPR pre-processor
-# =========================================================================
-OPTION(LIBS_BUILD_HOPR "Build HOPR pre-processor" OFF)
-
 # =========================================================================
 # Userblock
 # =========================================================================

CMakeListsLib.txt

@@ -480,7 +480,7 @@ IF(LIBS_BUILD_HOPR)
     # Let CMake take care of download, configure and build
     EXTERNALPROJECT_ADD(HOPR
     GIT_REPOSITORY ${HOPR_DOWNLOAD}
-    GIT_TAG v1.1.1
+    GIT_TAG ${HOPR_TAG}
     GIT_PROGRESS FALSE
     ${${GITSHALLOW}}
     PREFIX ${LIBS_HOPR_DIR}
@@ -504,6 +504,38 @@ IF(LIBS_BUILD_HOPR)
   ENDIF()
 ENDIF()
 
+# Download the HOPR executable directly and place it in the bin folder
+IF(LIBS_DOWNLOAD_HOPR)
+  MESSAGE(STATUS "HOPR executable download from: ${HOPR_DOWNLOAD_URL}")
+  IF(NOT EXISTS "${CMAKE_CURRENT_BINARY_DIR}/bin/hopr")
+    MESSAGE(STATUS "HOPR executable not found in: ${CMAKE_CURRENT_BINARY_DIR}/bin/hopr. HOPR will be downloaded/extracted.")
+    # Check if .zip file has already been downloaded
+    FILE(GLOB HOPR_ZIP_FILE ${CMAKE_CURRENT_BINARY_DIR}/hopr-*.zip)
+    IF(NOT EXISTS "${HOPR_ZIP_FILE}")
+      EXECUTE_PROCESS(COMMAND curl -L -O ${HOPR_DOWNLOAD_URL})
+      FILE(GLOB HOPR_ZIP_FILE ${CMAKE_CURRENT_BINARY_DIR}/hopr-*.zip)
+    ENDIF()
+    # Check if AppImage has already been extracted
+    FILE(GLOB HOPR_APP_FILE ${CMAKE_CURRENT_BINARY_DIR}/hopr-*.AppImage)
+    IF(NOT EXISTS "${HOPR_APP_FILE}")
+      IF(NOT EXISTS "${HOPR_ZIP_FILE}")
+        MESSAGE(WARNING "FAILED to download hopr .zip file from ${HOPR_DOWNLOAD_URL}")
+      ELSE()
+        EXECUTE_PROCESS(COMMAND unzip ${HOPR_ZIP_FILE})
+        FILE(GLOB HOPR_APP_FILE ${CMAKE_CURRENT_BINARY_DIR}/hopr-*.AppImage)
+      ENDIF()
+    ENDIF()
+    # Check if AppImage file exists and create symbolic link into ./bin
+    IF(NOT EXISTS "${HOPR_APP_FILE}")
+      MESSAGE(WARNING "FAILED to extract hopr .zip file")
+    ELSE()
+      EXECUTE_PROCESS(COMMAND ln -s ${HOPR_APP_FILE} bin/hopr)
+    ENDIF()
+  ELSE()
+    MESSAGE(STATUS "HOPR executable already exists under ${CMAKE_CURRENT_BINARY_DIR}/bin/hopr")
+  ENDIF()
+ENDIF()
+
 #  # =========================================================================
 #  # PAPI library
 #  # =========================================================================

CMakeListsMachine.txt

@@ -86,82 +86,92 @@ INCLUDE(GNUInstallDirs)
 # =========================================================================
 # Set machine-specific definitions and settings
 # =========================================================================
+# Revert to default via -DPICLAS_INSTRUCTION= once this value has been changed via, e.g., -DPICLAS_INSTRUCTION=-mtune=generic
+IF(NOT DEFINED PICLAS_INSTRUCTION)
+  SET(PICLAS_INSTRUCTION "")
+ENDIF()
+
 # HLRS HAWK / SuperMUC
-IF ("${CMAKE_HOSTNAME}" MATCHES "login")
-  MARK_AS_ADVANCED(FORCE C_PATH CXX_PATH Fortran_PATH)
+IF("${PICLAS_INSTRUCTION}" STREQUAL "")
+  IF ("${CMAKE_HOSTNAME}" MATCHES "login")
+    MARK_AS_ADVANCED(FORCE C_PATH CXX_PATH Fortran_PATH)
 
-  # HAWK and SuperMUC name their login nodes identically, so use the Fully Qualified Domain Name (FQDN) to identify
-  CMAKE_HOST_SYSTEM_INFORMATION(RESULT FQDN QUERY FQDN)
-  MARK_AS_ADVANCED(FORCE FQDN)
-  # HLRS HAWK
-  IF (FQDN MATCHES "hawk.hww.hlrs.de")
-    MESSAGE(STATUS "Compiling on Hawk")
-    # Overwrite compiler target architecture
-    IF (CMAKE_Fortran_COMPILER_ID MATCHES "GNU" OR CMAKE_Fortran_COMPILER_ID MATCHES "Flang")
-      SET(PICLAS_INSTRUCTION "-march=znver2")
-    ELSEIF (CMAKE_Fortran_COMPILER_ID MATCHES "Intel")
-      SET(PICLAS_INSTRUCTION "-xCORE-AVX2")
+    # HAWK and SuperMUC name their login nodes identically, so use the Fully Qualified Domain Name (FQDN) to identify
+    CMAKE_HOST_SYSTEM_INFORMATION(RESULT FQDN QUERY FQDN)
+    MARK_AS_ADVANCED(FORCE FQDN)
+    # HLRS HAWK
+    IF (FQDN MATCHES "hawk.hww.hlrs.de")
+      MESSAGE(STATUS "Compiling on Hawk")
+      # Overwrite compiler target architecture
+      IF (CMAKE_Fortran_COMPILER_ID MATCHES "GNU" OR CMAKE_Fortran_COMPILER_ID MATCHES "Flang")
+        SET(PICLAS_INSTRUCTION "-march=znver2")
+      ELSEIF (CMAKE_Fortran_COMPILER_ID MATCHES "Intel")
+        SET(PICLAS_INSTRUCTION "-xCORE-AVX2")
+      ENDIF()
+      # Use AMD Optimized Lapack/BLAS
+      # SET(BLA_VENDOR "FLAME")
+    # SuperMUC
+    ELSEIF (FQDN MATCHES "sng.lrz.de")
+      MESSAGE(STATUS "Compiling on SuperMUC")
+      # Overwrite compiler target architecture
+      IF (CMAKE_Fortran_COMPILER_ID MATCHES "GNU" OR CMAKE_Fortran_COMPILER_ID MATCHES "Flang")
+        SET(PICLAS_INSTRUCTION "-march=skylake-avx512")
+      ELSEIF (CMAKE_Fortran_COMPILER_ID MATCHES "Intel")
+        SET(PICLAS_INSTRUCTION "-xSKYLAKE-AVX512")
+        # Explicitely enable usage of AVX512 registers
+        SET (CMAKE_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} -qopt-zmm-usage=high")
+      ENDIF()
     ENDIF()
-    # Use AMD Optimized Lapack/BLAS
-    # SET(BLA_VENDOR "FLAME")
-  # SuperMUC
-  ELSEIF (FQDN MATCHES "sng.lrz.de")
-    MESSAGE(STATUS "Compiling on SuperMUC")
+    # Set LUSTRE definition to account for filesystem and MPI implementation
+    ADD_DEFINITIONS(-DLUSTRE)
+
+  # IAG Prandtl
+  ELSEIF("${CMAKE_HOSTNAME}" MATCHES "^prandtl")
+    MESSAGE(STATUS "Compiling on Prandtl")
+    MARK_AS_ADVANCED(FORCE C_PATH CXX_PATH Fortran_PATH)
+    SET(PICLAS_INSTRUCTION "-march=native")
+    # Set LUSTRE definition to account for filesystem
+    ADD_DEFINITIONS(-DLUSTRE)
+
+  # IAG Grafik01/Grafik02
+  ELSEIF ("${CMAKE_HOSTNAME}" MATCHES "^grafik0")
+    MESSAGE(STATUS "Compiling on ${CMAKE_HOSTNAME}")
+    MARK_AS_ADVANCED(FORCE C_PATH CXX_PATH Fortran_PATH)
+    SET(PICLAS_INSTRUCTION "-march=native")
+
+  ELSEIF ("${CMAKE_HOSTNAME}" MATCHES "^ilahead1")
+    MESSAGE(STATUS "Compiling on ILA cluster")
+    MARK_AS_ADVANCED(FORCE C_PATH CXX_PATH Fortran_PATH)
     # Overwrite compiler target architecture
     IF (CMAKE_Fortran_COMPILER_ID MATCHES "GNU" OR CMAKE_Fortran_COMPILER_ID MATCHES "Flang")
-      SET(PICLAS_INSTRUCTION "-march=skylake-avx512")
+      SET(PICLAS_INSTRUCTION "-march=core-avx2")
     ELSEIF (CMAKE_Fortran_COMPILER_ID MATCHES "Intel")
-      SET(PICLAS_INSTRUCTION "-xSKYLAKE-AVX512")
-      # Explicitely enable usage of AVX512 registers
-      SET (CMAKE_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} -qopt-zmm-usage=high")
+      SET(PICLAS_INSTRUCTION "-xCORE-AVX2")
     ENDIF()
-  ENDIF()
-  # Set LUSTRE definition to account for filesystem and MPI implementation
-  ADD_DEFINITIONS(-DLUSTRE)
-
-# IAG Prandtl
-ELSEIF("${CMAKE_HOSTNAME}" MATCHES "^prandtl")
-  MESSAGE(STATUS "Compiling on Prandtl")
-  MARK_AS_ADVANCED(FORCE C_PATH CXX_PATH Fortran_PATH)
-  SET(PICLAS_INSTRUCTION "-march=native")
-  # Set LUSTRE definition to account for filesystem
-  ADD_DEFINITIONS(-DLUSTRE)
-
-# IAG Grafik01/Grafik02
-ELSEIF ("${CMAKE_HOSTNAME}" MATCHES "^grafik0")
-  MESSAGE(STATUS "Compiling on ${CMAKE_HOSTNAME}")
-  MARK_AS_ADVANCED(FORCE C_PATH CXX_PATH Fortran_PATH)
-  SET(PICLAS_INSTRUCTION "-march=native")
-
-ELSEIF ("${CMAKE_HOSTNAME}" MATCHES "^ilahead1")
-  MESSAGE(STATUS "Compiling on ILA cluster")
-  MARK_AS_ADVANCED(FORCE C_PATH CXX_PATH Fortran_PATH)
-  # Overwrite compiler target architecture
-  IF (CMAKE_Fortran_COMPILER_ID MATCHES "GNU" OR CMAKE_Fortran_COMPILER_ID MATCHES "Flang")
-    SET(PICLAS_INSTRUCTION "-march=core-avx2")
-  ELSEIF (CMAKE_Fortran_COMPILER_ID MATCHES "Intel")
-    SET(PICLAS_INSTRUCTION "-xCORE-AVX2")
-  ENDIF()
-  # Work around MPI-IO issue 4446 on machines mounting storage via NFS
-  ADD_DEFINITIONS(-DNFS)
-
-ELSEIF ("${CMAKE_HOSTNAME}" MATCHES "^xenon")
-  MESSAGE(STATUS "Compiling on ILA student cluster")
-  MARK_AS_ADVANCED(FORCE C_PATH CXX_PATH Fortran_PATH)
-  SET(PICLAS_INSTRUCTION "-march=native")
-  # Work around MPI-IO issue 4446 on machines mountng storage via NFS
-  ADD_DEFINITIONS(-DNFS)
+    # Work around MPI-IO issue 4446 on machines mounting storage via NFS
+    ADD_DEFINITIONS(-DNFS)
 
-ELSE()
-  MESSAGE(STATUS "Compiling on a generic machine")
-  # Set compiler target architecture
-  IF (CMAKE_Fortran_COMPILER_ID MATCHES "GNU" OR CMAKE_Fortran_COMPILER_ID MATCHES "Flang" )
+  ELSEIF ("${CMAKE_HOSTNAME}" MATCHES "^xenon")
+    MESSAGE(STATUS "Compiling on ILA student cluster")
+    MARK_AS_ADVANCED(FORCE C_PATH CXX_PATH Fortran_PATH)
     SET(PICLAS_INSTRUCTION "-march=native")
-  ELSEIF (CMAKE_Fortran_COMPILER_ID MATCHES "Intel")
-    SET(PICLAS_INSTRUCTION "-xHost")
+    # Work around MPI-IO issue 4446 on machines mountng storage via NFS
+    ADD_DEFINITIONS(-DNFS)
+
+  ELSE()
+    MESSAGE(STATUS "Compiling on a generic machine")
+    # Set compiler target architecture
+    IF (CMAKE_Fortran_COMPILER_ID MATCHES "GNU" OR CMAKE_Fortran_COMPILER_ID MATCHES "Flang" )
+      SET(PICLAS_INSTRUCTION "-march=native")
+      #SET(PICLAS_INSTRUCTION "-mtune=generic")
+    ELSEIF (CMAKE_Fortran_COMPILER_ID MATCHES "Intel")
+      SET(PICLAS_INSTRUCTION "-xHost")
+    ENDIF()
   ENDIF()
 ENDIF()
 
+MESSAGE(STATUS "Compiling Nitro/Release/Profile with [${CMAKE_Fortran_COMPILER_ID}] (v${CMAKE_Fortran_COMPILER_VERSION}) fortran compiler using PICLAS_INSTRUCTION [${PICLAS_INSTRUCTION}] instructions.")
+
 # =========================================================================
 # CHECK SUPPORT FOR VARIOUS FORTRAN (2003,2008) FEATURES
 # =========================================================================
@@ -188,8 +198,6 @@ IF(NOT Fortran2003Check)
   MESSAGE(FATAL_ERROR "Failed to compile basic Fortran2003 programm! Please ensure your compiler is up-to-date!")
 ENDIF()
 
-MESSAGE(STATUS "Compiling with [${CMAKE_Fortran_COMPILER_ID}] (v${CMAKE_Fortran_COMPILER_VERSION}) fortran compiler using [${PICLAS_INSTRUCTION}] instruction")
-
 # =========================================================================
 # COMPILER FLAGS
 # =========================================================================

README.md

@@ -11,6 +11,8 @@ support the project by citing our publications given in [REFERENCE.md](REFERENCE
 
 The documentation of PICLas can be found in the [User Guide](https://piclas.readthedocs.io/), where the installation procedure is
 described in [Chapter 2](https://piclas.readthedocs.io/en/latest/userguide/installation.html).
+Pre-compiled executables (that only require pre-installed MPI for parallel execution) for Linux can directly be downloaded as
+AppImage containers from the [PICLas release tag assets](https://github.com/piclas-framework/piclas/releases).
 
 ## Regression Testing
 

docs/documentation/developerguide/appimage.md

@@ -0,0 +1,93 @@
+# Building the AppImage Executable
+
+## piclas
+
+Navigate to the piclas repository and create a build directory
+
+    mkdir build && cd build
+
+and compile piclas using the following cmake flags
+
+    cmake .. -DCMAKE_INSTALL_PREFIX=/usr
+
+and then
+
+    make install DESTDIR=AppDir
+
+or when using Ninja run
+
+    DESTDIR=AppDir ninja install
+
+Then create an AppImage (and subsequent paths) directory in the build folder
+
+    mkdir -p AppDir/usr/share/icons/
+
+and copy the piclas logo into the icons directory
+
+    cp ../docs/logo.png AppDir/usr/share/icons/piclas.png
+
+A desktop file should already exist in the top-level directory containing
+
+    [Desktop Entry]
+    Type=Application
+    Name=piclas
+    Exec=piclas
+    Comment=PICLas is a flexible particle-based plasma simulation suite.
+    Icon=piclas
+    Categories=Development;
+    Terminal=true
+
+Next, download the AppImage executable
+
+    curl -L -O https://github.com/linuxdeploy/linuxdeploy/releases/download/continuous/linuxdeploy-x86_64.AppImage
+
+and make it executable
+
+    chmod +x linuxdeploy-x86_64.AppImage
+
+Then run
+
+    ./linuxdeploy-x86_64.AppImage --appdir AppDir --output appimage --desktop-file=../.github/workflows/piclas.desktop
+
+The executable should be created in the top-level directory, e.g.,
+
+    piclas-ad6830c7a-x86_64.AppImage
+
+## piclas2vtk and other tools
+
+Other tools such as `piclas2vtk` and `superB` etc. are also included in the AppImage container and can be extracted via
+
+    ./piclas-ad6830c7a-x86_64.AppImage --appimage-extract
+
+The tools are located under `./squashfs-root/usr/bin/`.
+To make on those tools the main application of the AppImage, remove the AppDir folder
+
+    rm -rf AppDir
+
+and then
+
+    make install DESTDIR=AppDir
+
+or when using Ninja run
+
+    DESTDIR=AppDir ninja install
+
+and change the following settings, e.g., for `piclas2vtk`
+
+    PROG='piclas2vtk'
+    cp ../.github/workflows/piclas.desktop ${PROG}.desktop
+    mkdir -p AppDir/usr/share/icons/
+    cp ../docs/logo.png AppDir/usr/share/icons/${PROG}.png
+    sed -i -e "s/Name=.*/Name=${PROG}/" ${PROG}.desktop
+    sed -i -e "s/Exec=.*/Exec=${PROG}/" ${PROG}.desktop
+    sed -i -e "s/Icon=.*/Icon=${PROG}/" ${PROG}.desktop
+    ./linuxdeploy-x86_64.AppImage --appdir AppDir --output appimage --desktop-file=${PROG}.desktop
+
+This should create
+
+    piclas2vtk-ad6830c7a-x86_64.AppImage
+
+## Troubleshooting
+
+If problems occur when executing the AppImage, check the [troubleshooting]( https://docs.appimage.org/user-guide/troubleshooting/index.html)
+section for possible fixes.

docs/documentation/developerguide/index.md

@@ -21,15 +21,16 @@ unittest.md
 compiler.md
 tools.md
 performance.md
+appimage.md
 examples.md
 ```
 
-This guide is organized to guide the first implementation steps as well as provide a complete overview of 
+This guide is organized to guide the first implementation steps as well as provide a complete overview of
 the simulation code's features from a developer's point of view.
 
 * The first Chapter {ref}`developerguide/git_workflow:GitLab Workflow` shall give an overview over the development workflow within
   the Gitlab environment, and the necessary steps to create a release, deploy updates to the Collaborative Numerics Group and GitHub.
-* The second Chapter {ref}`developerguide/styleguide:Style Guide` describes the rules and guidelines regarding code development 
+* The second Chapter {ref}`developerguide/styleguide:Style Guide` describes the rules and guidelines regarding code development
   such as how the header of functions and subroutines look like.
 * Chapter {ref}`developerguide/building_guide:Documentation` describes how to build the html/pdf files
   locally before committing changes to the repository and pointers on writing documentation.
@@ -44,5 +45,6 @@ the simulation code's features from a developer's point of view.
 * Chapter {ref}`developerguide/tools:Developer Tools` gives an overview over the tools and scripts for developers.
 * Chapter {ref}`developerguide/performance:Performance Analysis` describes different tools that can be utilized for measuring the
   computational performance
+* Chapter {ref}`developerguide/appimage:Building the AppImage Executable` described how an AppImage executable of HOPR is created.
 * Chapter {ref}`developerguide/examples:Markdown Examples` gives a short overview of how to include code, equations, figures, tables
   etc. in the user and developer guides in Markdown.