Develop

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "wikipage/source/" directory with Sphinx
+sphinx:
+   configuration: wikipage/source/conf.py
+
+# Python requirements for building documentation
+python:
+   install:
+   - requirements: wikipage/requirements.txt
+

CMakeLists.txt

@@ -1,12 +1,65 @@
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.18)
 
-# Define compilaton mode
-option(MODE_release "ON: release mode; OFF: debug mode" OFF) 
+# ============================================================================
+# FLUXOS-OVERLAND CMake Configuration
+# Hybrid MPI+OpenMP parallelization for HPC clusters
+# Optional CUDA GPU acceleration
+# ============================================================================
+#
+# Build Options:
+#   -DMODE_release=ON     Enable release mode with optimizations (default: OFF)
+#   -DUSE_MPI=ON          Enable MPI for distributed computing (default: OFF)
+#   -DUSE_CUDA=ON         Enable CUDA GPU acceleration (default: OFF)
+#   -DUSE_TRIMESH=ON      Enable triangular mesh support (default: OFF)
+#   -DUSE_OPENWQ=ON       Enable OpenWQ water quality coupling (default: OFF)
+#
+# Build Examples:
+#   cmake -DMODE_release=ON ..                              # OpenMP only (single node)
+#   cmake -DMODE_release=ON -DUSE_MPI=ON ..                 # MPI+OpenMP (multi-node HPC)
+#   cmake -DMODE_release=ON -DUSE_CUDA=ON ..                # OpenMP+CUDA (single GPU)
+#   cmake -DMODE_release=ON -DUSE_TRIMESH=ON ..             # OpenMP + triangular mesh
+#   cmake -DMODE_release=ON -DUSE_TRIMESH=ON -DUSE_CUDA=ON ..  # Triangular + CUDA
+#
+# ============================================================================
+# Scalability Guidelines
+# ============================================================================
+#
+#   Domain Size         Recommended Configuration
+#   ---------------     --------------------------------------------------
+#   < 1000 x 1000       OpenMP only (single node)
+#   1000 - 5000²        4-16 MPI processes
+#   5000 - 10000²       16-64 MPI processes
+#   > 10000²            64+ MPI processes
+#
+# For hybrid MPI+OpenMP, use 2-4 OpenMP threads per MPI process.
+# Example for 64 cores: 16 MPI processes x 4 OpenMP threads
+#
+# ============================================================================
+
+# Define compilation mode
+option(MODE_release "ON: release mode; OFF: debug mode" OFF)
+
+# Define MPI option for HPC clusters
+option(USE_MPI "ON: Enable MPI for distributed computing; OFF: Single node only" OFF)
+
+# Define CUDA option for GPU acceleration
+option(USE_CUDA "ON: Enable CUDA GPU acceleration; OFF: CPU only" OFF)
+
+# Define triangular mesh option
+option(USE_TRIMESH "ON: Enable unstructured triangular mesh support; OFF: Regular mesh only" OFF)
+
+# Define OpenWQ water quality coupling option
+option(USE_OPENWQ "ON: Enable OpenWQ water quality coupling; OFF: Standalone hydro" OFF)
 
 # Set compilation mode flags
 IF(MODE_release MATCHES ON)
         MESSAGE(STATUS "compilation model : release")
-        set(CMAKE_CXX_FLAGS "-O3")
+        # Aggressive optimization flags for maximum performance
+        # Note: Using -fno-finite-math-only to maintain IEEE compliance for JSON library
+        set(CMAKE_CXX_FLAGS "-O3 -march=native -mtune=native -funroll-loops -ftree-vectorize -fno-math-errno")
+        # Enable link-time optimization for cross-file inlining
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -flto")
+        set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -flto")
         set(FLUXOS_EXEC_name "fluxos")
 ELSE(MODE_release MATCHES OFF)
         MESSAGE(STATUS "compilation model : debug")
@@ -26,13 +79,107 @@ IF (UNIX)
 
 	file(GLOB SOURCES "src/fluxos/*.cpp")
 
+	# OpenWQ water quality coupling
+	# Always compile the OpenWQ hydrolink bridge file.
+	# When USE_OPENWQ=OFF, stub implementations are used.
+	# When USE_OPENWQ=ON, the full OpenWQ library must be available.
+	file(GLOB OPENWQ_SOURCES "src/openwq/*.cpp")
+	IF(USE_OPENWQ MATCHES ON)
+		MESSAGE(STATUS "OpenWQ support: ENABLED")
+		add_definitions(-DUSE_OPENWQ)
+	ELSE()
+		MESSAGE(STATUS "OpenWQ support: DISABLED (use -DUSE_OPENWQ=ON to enable)")
+	ENDIF()
+
 	set(CMAKE_CXX_STANDARD 17)
-	
+
 	# Packages
 	find_package(Armadillo REQUIRED)
 	FIND_PACKAGE(HDF5 REQUIRED)
 	find_package(OpenMP)
 
+	# MPI support for HPC clusters
+	IF(USE_MPI MATCHES ON)
+		find_package(MPI REQUIRED)
+		MESSAGE(STATUS "MPI support : ENABLED")
+		MESSAGE(STATUS "MPI C compiler: ${MPI_C_COMPILER}")
+		MESSAGE(STATUS "MPI CXX compiler: ${MPI_CXX_COMPILER}")
+		add_definitions(-DUSE_MPI)
+		# Use modern imported targets when available (CMake 3.9+),
+		# fall back to legacy variables for older CMake
+		if(TARGET MPI::MPI_CXX)
+			# Modern CMake: imported target handles includes, flags, and libraries
+			MESSAGE(STATUS "MPI: using imported target MPI::MPI_CXX")
+		else()
+			set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${MPI_CXX_COMPILE_FLAGS}")
+			set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${MPI_CXX_LINK_FLAGS}")
+		endif()
+		# Update executable name to indicate MPI version
+		IF(MODE_release MATCHES ON)
+			set(FLUXOS_EXEC_name "fluxos_mpi")
+		ELSE()
+			set(FLUXOS_EXEC_name "fluxos_mpi_debug")
+		ENDIF()
+	ELSE()
+		MESSAGE(STATUS "MPI support : DISABLED (use -DUSE_MPI=ON to enable)")
+	ENDIF()
+
+	# CUDA GPU acceleration support
+	IF(USE_CUDA MATCHES ON)
+		enable_language(CUDA)
+		find_package(CUDAToolkit REQUIRED)
+		MESSAGE(STATUS "CUDA support : ENABLED")
+		MESSAGE(STATUS "CUDA compiler: ${CMAKE_CUDA_COMPILER}")
+		MESSAGE(STATUS "CUDA toolkit : ${CUDAToolkit_VERSION}")
+		add_definitions(-DUSE_CUDA)
+
+		# Set CUDA architectures (user can override with -DCMAKE_CUDA_ARCHITECTURES=xx)
+		if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+			set(CMAKE_CUDA_ARCHITECTURES 70 75 80 86 89 90)
+		endif()
+
+		set(CMAKE_CUDA_STANDARD 17)
+
+		# CUDA compile flags
+		IF(MODE_release MATCHES ON)
+			set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -O3 --use_fast_math --expt-relaxed-constexpr")
+		ELSE()
+			set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -g -G --expt-relaxed-constexpr")
+		ENDIF()
+
+		# Collect CUDA source files
+		file(GLOB CUDA_SOURCES "src/fluxos/*.cu")
+
+		# Update executable name
+		IF(MODE_release MATCHES ON)
+			set(FLUXOS_EXEC_name "fluxos_cuda")
+		ELSE()
+			set(FLUXOS_EXEC_name "fluxos_cuda_debug")
+		ENDIF()
+	ELSE()
+		MESSAGE(STATUS "CUDA support : DISABLED (use -DUSE_CUDA=ON to enable)")
+		set(CUDA_SOURCES "")
+	ENDIF()
+
+	# Triangular mesh support
+	IF(USE_TRIMESH MATCHES ON)
+		MESSAGE(STATUS "TriMesh support: ENABLED")
+		add_definitions(-DUSE_TRIMESH)
+
+		# Collect triangular mesh C++ sources
+		file(GLOB TRIMESH_SOURCES "src/fluxos/trimesh/*.cpp")
+
+		# Collect triangular mesh CUDA sources if CUDA is enabled
+		IF(USE_CUDA MATCHES ON)
+			file(GLOB TRIMESH_CUDA_SOURCES "src/fluxos/trimesh/*.cu")
+		ELSE()
+			set(TRIMESH_CUDA_SOURCES "")
+		ENDIF()
+	ELSE()
+		MESSAGE(STATUS "TriMesh support: DISABLED (use -DUSE_TRIMESH=ON to enable)")
+		set(TRIMESH_SOURCES "")
+		set(TRIMESH_CUDA_SOURCES "")
+	ENDIF()
 
 	set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${OpenMP_CXX_FLAGS}")
 
@@ -42,22 +189,52 @@ IF (UNIX)
 
 	# Create Results folder if non-existant
 	file(MAKE_DIRECTORY Results)
-	
+
 	add_executable(${FLUXOS_EXEC_name}
-			${SOURCES})
-
+			${SOURCES}
+			${OPENWQ_SOURCES}
+			${CUDA_SOURCES}
+			${TRIMESH_SOURCES}
+			${TRIMESH_CUDA_SOURCES})
+
 	target_include_directories(
 		${FLUXOS_EXEC_name} PUBLIC
 		${HDF5_INCLUDE_DIRS}
 		${ARMADILLO_INCLUDE_DIR})
 
+	# Add MPI include directories if enabled (legacy path)
+	IF(USE_MPI MATCHES ON AND NOT TARGET MPI::MPI_CXX)
+		target_include_directories(
+			${FLUXOS_EXEC_name} PUBLIC
+			${MPI_CXX_INCLUDE_DIRS})
+	ENDIF()
+
 	target_link_libraries(
 		${FLUXOS_EXEC_name}
 		${HDF5_C_LIBRARY_hdf5}
-		${ARMADILLO_LIBRARIES})
+		${ARMADILLO_LIBRARIES}
+		OpenMP::OpenMP_CXX)
+
+	# Add MPI libraries if enabled
+	IF(USE_MPI MATCHES ON)
+		if(TARGET MPI::MPI_CXX)
+			target_link_libraries(${FLUXOS_EXEC_name} MPI::MPI_CXX)
+		else()
+			target_link_libraries(${FLUXOS_EXEC_name} ${MPI_CXX_LIBRARIES})
+		endif()
+	ENDIF()
 
+	# Add CUDA libraries if enabled
+	IF(USE_CUDA MATCHES ON)
+		target_link_libraries(
+			${FLUXOS_EXEC_name}
+			CUDA::cudart)
+		set_target_properties(${FLUXOS_EXEC_name} PROPERTIES
+			CUDA_SEPARABLE_COMPILATION ON)
+	ENDIF()
 
-ELSE()	
+
+ELSE()
 	MESSAGE(STATUS "curent platform : windows")
 	project(fluxos)
 	file(GLOB SOURCES "src/*.cpp")
@@ -68,12 +245,32 @@ ELSE()
 
 	# Packages
 	find_package(OpenMP)
+
+	# MPI support for Windows HPC
+	IF(USE_MPI MATCHES ON)
+		find_package(MPI REQUIRED)
+		MESSAGE(STATUS "MPI support : ENABLED")
+		add_definitions(-DUSE_MPI)
+		set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${MPI_CXX_COMPILE_FLAGS}")
+	ELSE()
+		MESSAGE(STATUS "MPI support : DISABLED")
+	ENDIF()
+
 	set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${OpenMP_CXX_FLAGS}")
 	set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/Results)
 	add_executable(${FLUXOS_EXEC_name}, ${SOURCES})
 	target_include_directories(
-		${FLUXOS_EXEC_name} PUBLIC 
-		${HDF5_INCLUDE_DIRS}  
+		${FLUXOS_EXEC_name} PUBLIC
+		${HDF5_INCLUDE_DIRS}
 		"/usr/include/")
 
+	IF(USE_MPI MATCHES ON)
+		target_include_directories(
+			${FLUXOS_EXEC_name} PUBLIC
+			${MPI_CXX_INCLUDE_DIRS})
+		target_link_libraries(
+			${FLUXOS_EXEC_name}
+			${MPI_CXX_LIBRARIES})
+	ENDIF()
+
 ENDIF()

README.md

@@ -1,4 +1,6 @@
-# FLUXOS-OVERLAND
+<img src="uevora_logo.png" alt="Universidade de Évora" width="350">
+
+# FLUXOS
 ## Table of Contents
 * [Introduction](#introduction)
 * [Branches](#branches)
@@ -9,15 +11,15 @@
 * [Working Example](#working-example)
 
 ## Introduction
-* Soure code for the FLUXOS-OVERLAND model. The original code (named as FLUXOS) was written in Fortran and consisted of the coupling of 2dmb, +QeS2, MODFLOW and MT3DMS.
+* Soure code for the FLUXOS model. The original code (named as FLUXOS) was written in Fortran and consisted of the coupling of 2dmb, +QeS2, MODFLOW and MT3DMS.
 
 * [Documentation (ReadTheDocs)](https://fluxos-cpp.readthedocs.io)
 
-* Modifications (from FLUXOS to FLUXOS-OVERLAND):
+* Modifications:
 	* Converted to C++
-	* Uses: Armadillo template-based C++ library for linear algebra 
+	* Uses: Armadillo template-based C++ library for linear algebra
 	* Removed: MODFLOW and MT3DMS (currently there is no baseflow)
-	* WINTRA algorithm was integrated for calculation of runoff-soil interactions and nutrient release ([paper](https://onlinelibrary.wiley.com/doi/full/10.1002/hyp.11346)) 
+	* WINTRA algorithm was integrated for calculation of runoff-soil interactions and nutrient release ([paper](https://onlinelibrary.wiley.com/doi/full/10.1002/hyp.11346))
 
 * Reading material:
 	* Theoretical background (original FLUXOS):
@@ -27,13 +29,13 @@
 		* [STC paper](https://www.sciencedirect.com/science/article/pii/S0169772216300948?via%3Dihub)
 		* [JCH paper](https://www.sciencedirect.com/science/article/pii/S0169772216300948?via%3Dihub)
 		* [JAWRA](https://onlinelibrary.wiley.com/doi/full/10.1111/1752-1688.12316)
-	* FLUXOS-OVERLAND
+	* FLUXOS
 		* [Poster](https://www.researchgate.net/publication/333324452_Hydrodynamic_modelling_of_snowmelt_flooding_events_and_nutrient_transport_in_the_Canadian_Prairies_using_the_FLUXOS_model?channel=doi&linkId=5ce70f0a458515712ebda98b&showFulltext=true)
 
 ## Branches
 ### Active
 <!-- * main: All changes made in adesolver and adesolver_wintra have been merged into main -->
-* main: primary branch with latest verified updates to the working code 
+* main: primary branch with latest verified updates to the working code
 * development: used to verify updates from feature branches before merging with main
 * supporting_scripts: feature branch for development of supporting Python and MATLAB scripts
 ### To be Archived
@@ -50,7 +52,7 @@ $ git branch -u origin/main main
 
 ## Compiling
 * CMake: [CMakeLists.txt](CMakeLists.txt) is provided
-* Library dependencies: Armadillo 
+* Library dependencies: Armadillo
 * CMake minimum version: 3.10
 
 <!-- ## Execution (and input files and folder needed) -->
@@ -65,8 +67,8 @@ $ git branch -u origin/main main
 
 <!-- ## Visualization of results (stored inside "Results" folder) -->
 ## Visualization
-* Output stored in "Results" folder may be visualized using [VisIt](https://wci.llnl.gov/simulation/computer-codes/visit/): 
- 
+* Output stored in "Results" folder may be visualized using [VisIt](https://wci.llnl.gov/simulation/computer-codes/visit/):
+
 [![alt text](https://wci.llnl.gov/sites/wci/files/visit-home.jpg "VisIt")](https://wci.llnl.gov/simulation/computer-codes/visit/)
 
 <!-- ## Supporting scripts (post-processing) -->
@@ -77,5 +79,3 @@ $ git branch -u origin/main main
 ## Working Example
 * See ["Working_example"](Working_example) folder
 * Updates coming soon!
-
-

bin/Qmelt_synthetic.fluxos

@@ -0,0 +1,13 @@
+0,0,0
+0,0,0
+900,500.0,0
+1800,1000.0,0
+2700,1000.0,0
+3600,500.0,0
+4500,0,0
+5400,0,0
+7200,0,0
+10800,0,0
+14400,0,0
+18000,0,0
+21600,0,0