Add CI, update modhdf5, test runner and docs

.github/workflows/ci.yml

@@ -0,0 +1,167 @@
+name: HDF5 Fortran API CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build_serial_HDF5_with_gfortran:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            gfortran \
+            cmake \
+            libhdf5-dev \
+            libhdf5-fortran-102  
+
+      - name: Verify compilers and HDF5
+        run: |
+          gfortran --version
+          cmake --version
+
+      - name: Configure test runner with CMake and run
+        run: |
+          cmake -S ./test/. -B ./build-tests \
+             -DCMAKE_Fortran_COMPILER=gfortran
+          cmake --build ./build-tests 
+          ./build-tests/h5testrunner
+
+
+  build_parallel_HDF5_with_gfortran:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            gfortran \
+            cmake \
+            libopenmpi-dev \
+            libhdf5-openmpi-dev
+
+      - name: Verify compilers and HDF5
+        run: |
+          gfortran --version
+          cmake --version
+          mpif90 --version
+
+      - name: Configure test runner with CMake and run
+        run: |
+          cmake -S ./test/. -B ./build-tests \
+             -DCMAKE_Fortran_COMPILER=mpif90 -DMPI_VERSION=ON
+          cmake --build build-tests 
+          ./build-tests/h5testrunner
+          ./build-tests/h5testrunner_mpi
+          mpirun --allow-run-as-root --oversubscribe \
+                 -np 2 ./build-tests/h5testrunner_mpi
+
+
+  build_serial_HDF5_with_ifx:
+    runs-on: ubuntu-latest
+    container:
+      image: intel/fortran-essentials:latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          apt-get update
+          apt-get install -y \
+            cmake make gcc g++ \
+            libhdf5-dev \
+            wget \
+            gpg
+
+      - name: Install serial HDF5 1.14.6 with IFX
+        shell: bash
+        run: |
+          wget -O hdf5-1.14.6.tar.gz \
+            https://sourceforge.net/projects/hdf5.mirror/files/hdf5_1.14.6/hdf5-1.14.6.tar.gz/download
+          tar -xzf hdf5-1.14.6.tar.gz
+          mkdir -p build-hdf5-ifx
+
+          # configure with ifx
+          cmake -S ./hdf5-1.14.6 -B build-hdf5-ifx \
+              -DCMAKE_Fortran_COMPILER=ifx \
+              -DHDF5_BUILD_FORTRAN=ON \
+              -DCMAKE_INSTALL_PREFIX=$HOME/hdf5-ifx \
+              -DCMAKE_Fortran_FLAGS="-fPIE" \
+              -DCMAKE_POSITION_INDEPENDENT_CODE=ON
+
+          cmake --build build-hdf5-ifx -j
+          cmake --install build-hdf5-ifx
+
+      - name: Build and run tests with ifx
+        shell: bash
+        run: |
+          ifx --version
+
+          cmake -S ./test/. -B build-tests-ifx \
+            -DCMAKE_PREFIX_PATH=$HOME/hdf5-ifx \
+            -DCMAKE_Fortran_COMPILER=ifx
+          cmake --build build-tests-ifx
+          ./build-tests-ifx/h5testrunner
+
+  # hpckit requires more disk space than available on GitHub runner
+  # build_parallel_HDF5_with_ifx:
+  #   runs-on: ubuntu-latest
+  #  container:
+  #    image: intel/fortran-hpckit:latest
+
+  #   steps:
+  #     - uses: actions/checkout@v4
+
+  #     - name: Install system dependencies
+  #       run: |
+  #         sudo apt-get update
+  #         sudo apt-get install -y wget cmake make gcc g++ gpg
+
+  #     - name: Install parallel HDF5 1.14.6 with IFX
+  #       shell: bash
+  #       run: |
+  #         wget -O hdf5-1.14.6.tar.gz \
+  #           https://sourceforge.net/projects/hdf5.mirror/files/hdf5_1.14.6/hdf5-1.14.6.tar.gz/download
+  #         tar -xzf hdf5-1.14.6.tar.gz
+  #         mkdir -p build-hdf5-mpiifx
+
+  #         cmake -S hdf5-1.14.6 -B build-hdf5-mpiifx \
+  #           -DCMAKE_Fortran_COMPILER=mpiifx \
+  #           -DCMAKE_C_COMPILER=mpiicx \
+  #           -DBUILD_SHARED_LIBS=OFF \
+  #           -DHDF5_BUILD_FORTRAN=ON \
+  #           -DHDF5_ENABLE_PARALLEL=ON \
+  #           -DHDF5_ENABLE_Z_LIB_SUPPORT=OFF \
+  #           -DHDF5_ENABLE_SZIP_SUPPORT=OFF \
+  #           -DCMAKE_INSTALL_PREFIX=$HOME/hdf5-mpiifx \
+
+  #         cmake --build build-hdf5-mpiifx -j
+  #         cmake --install build-hdf5-mpiifx
+
+  #     - name: Build and run MPI tests with mpiifx
+  #       shell: bash
+  #       run: |
+  #         mpiifx --version
+
+  #         cmake -S ./test/. -B build-tests-mpiifx \
+  #           -DCMAKE_Fortran_COMPILER=mpiifx \
+  #           -DCMAKE_PREFIX_PATH=$HOME/hdf5-mpiifx \
+  #           -DMPI_VERSION=ON
+  #         cmake --build build-tests-mpiifx
+
+  #         ./build-tests-mpiifx/h5testrunner
+  #         ./build-tests-mpiifx/h5testrunner_mpi
+  #         mpirun --allow-run-as-root --oversubscribe \
+  #           -np 2 ./build-tests-mpiifx/h5testrunner_mpi
+

README.md

@@ -1,9 +1,50 @@
 # HDF5_Fortran_API
-A Fortran library which handles the interface to HDF5 library to give simpler I/O proceedures usable within Fortran coding projects
+
+A Fortran library which handles the interface to HDF5 library to give simpler I/O proceedures usable within Fortran coding projects.
+
+The modhdf5.f90 module contains subroutines which interface with the HDF5 library so that you do not need to use it directly in your code. You only need to call upon this module to perform the I/O to the .h5 file. 
+
+You can look at examples of how this module is used within the `./tests/testio.f90` code.
+
+__Author:__ Alyn D. N. James
+
+__Version:__ 0.1.0
+
+## How to use
+
+To add this to your Fortran code, add this module .f90 file to the compilation (cmake, make and so on) and load the public subroutines module in your Fortran code via
+
+```Fortran
+use modhdf5
+```
+
+The .inc files will needed to be in the same directory as the .f90 file, but these will automatically be included during the compilation. (These .inc files are used to reduce the amount of repetative code.)
+
+This module uses macro preprocessors to be compatible with both the serial and parallel HDF5 library. However, to enable the (MPI) parallel HDF5 capabilities in modhdf5, you need to add the -DMPI_modhdf5 flag to the `make` compilation step. This is done within cmake as seen in the `Tests` section below.
+
+## Dependencies
+
+Here is the list of libraries required for the modhdf5 module (with the version it was tested with):
+- HDF5 library  (1.14.6)
+- Fortran 2018+  (gcc 15.1.0 and ifx 2025.3.0)
+- MPI (for parallel enabled version)  (Openmpi 5.0.8)
+
+For the repository, the following additional packages (with the version it was tested with) are needed:
+- cmake (3.22.1)
+
+## Documentation
+
+Within modhdf5, the public subroutines to be used in your code are given at the top of the file. All the global variables are commented, and the inputs and outputs of all of the subroutines are labelled. The subroutines are named to be self-explanatory (some have short doc-strings for clarity).
 
 ## Tests
 
-Compile the test runner (within gnu) with
+This repository uses the [naturalFRUIT v0.7.4](https://cibinjoseph.github.io/naturalFRUIT/index.html) .f90 code for constructing the test runner for testing the functionality of the code base. Credit goes to the developers for `naturalfruit.f90`. 
+
+Please look at the `.github/workflows/ci.yml` to see how modhdf5 has been compiled in different setups.
+
+### Serial Tests
+
+Compile the test runner (within GCC+Openmpi) with
 
 ```
 cmake ../ -DCMAKE_Fortran_COMPILER=mpif90
@@ -20,3 +61,36 @@ run the test suite via
 ```
 ./h5testrunner
 ```
+
+
+### (MPI) Parallel Tests
+
+Compile the test runner (within GCC+Openmpi) with
+
+```
+cmake ../ -DCMAKE_Fortran_COMPILER=mpif90 -DMPI_VERSION=ON
+```
+
+For conda environment, use
+
+```
+cmake ../ -DCMAKE_Fortran_COMPILER=mpif90 -DMPI_VERSION=ON -DCMAKE_PREFIX_PATH=$CONDA_PREFIX
+```
+
+run the test suite via
+
+```
+mpirun -np 2 ./h5testrunner_mpi
+```
+
+## Developer notes
+
+This modhdf5 has been written for HDF5 version 1.x.y. The additional functionality of HDF5 2.x.y has not been included. 
+
+modhdf5 uses polymorphic, assumed-rank variable inputs to keep the interface generic. The variable rank and type are resolved within the read/write subroutines to interface with the HDF5 library Fortran APIs. modhdf5 currently sticks to the standard H5 native types available within the HDF5 library. These are:
+- H5T_NATIVE_INTEGER
+- H5T_NATIVE_REAL
+- H5T_NATIVE_DOUBLE
+- H5T_FORTRAN_S1 (modhdf5 extends this to a custom n-sized character type to handle aribitary sized character variable.)
+
+It is suggested for users to resolve their data types to conform with these native types and add the Fortran data type it was originally to the `fortran_type` attribute (via `fdtype_name` subroutine input/output) so that other users know its origin.