110 add convection term

Makefile

@@ -1,70 +1,118 @@
 ####################################################################
-#   11 Jun 2024                                                    #
+# HeatFlow Build System (MKL + optional PETSc + OpenMP)
 ####################################################################
-#
-SHELL = /bin/sh
-#
-#  The machine (platform) identifier to append to the library names
-#
-PLAT = _linux
-#
-#
-
-
-##########################################
-# CODE DIRECTORIES AND FILES
-##########################################
-mkfile_path := $(abspath $(firstword $(MAKEFILE_LIST)))
-mkfile_dir := $(dir $(mkfile_path))
-BIN_DIR := ./bin
-SRC_DIR := ./src
-BUILD_DIR = ./obj
-
-SRCS := /heatflow/mod_constants.f90 \
-		/heatflow/mod_constructions.f90 \
-		/heatflow/mod_SPtype.f90 \
-		/heatflow/mod_global.f90 \
-		/heatflow/mod_Sparse.f90 \
-		/heatflow/mod_inputs.f90 \
-		/heatflow/mod_material.f90 \
-		/heatflow/mod_hmatrix.f90 \
-		/heatflow/mod_init_evolve.f90 \
-		/heatflow/mod_setup.f90 \
-		/heatflow/mod_boundary.f90 \
-		/heatflow/mod_heating.f90 \
-		/heatflow/mod_cattaneo.f90 \
-		/heatflow/mod_tempdep.f90 \
-		/heatflow/mod_evolve.f90 \
-        /heatflow/mod_output.f90 \
-        heatflow.f90
-OBJS := $(addprefix $(SRC_DIR)/,$(SRCS))
-
-
-FFLAGS = -O3 
-MODULEFLAGS = -J
-FC = gfortran
-
-##########################################
-# LIBRARY SECTION
-##########################################
-MKLROOT?="/usr/local/intel/parallel_studio_xe_2017/compilers_and_libraries_2017/linux/mkl/lib/intel64_lin"
-
-
-NAME = ThermalFlow.x
-programs = $(BIN_DIR)/$(NAME)
-all: $(programs)
-
-$(BIN_DIR):
-	mkdir -p $@
 
-$(BUILD_DIR):
+SHELL        = /bin/sh
+
+# Directories
+SRC_DIR      := ./src
+BUILD_DIR    := ./obj
+BIN_DIR      := ./bin
+
+# Compiler (gfortran with OpenMP for threading)
+FC           := gfortran
+
+# Core count
+NCORES       := $(shell nproc)
+
+# Detect conda environment for BLAS/LAPACK (fallback if no system libs)
+CONDA_PREFIX ?= $(shell conda info --base 2>/dev/null || echo /home/hm556/miniforge3)
+
+# PETSc (system installation)
+PETSC_INC  := -I/usr/share/petsc/3.15/include -I/usr/lib/petscdir/petsc3.15/x86_64-linux-gnu-real/include
+PETSC_LIB  := -L/usr/lib/petscdir/petsc3.15/x86_64-linux-gnu-real/lib -lpetsc -Wl,-rpath,/usr/lib/petscdir/petsc3.15/x86_64-linux-gnu-real/lib
+PETSC_NOTE := (system PETSc 3.15)
+
+# Use OpenBLAS for multi-threaded BLAS/LAPACK (better than reference BLAS/ATLAS)
+BLAS_FLAGS := -lopenblas -lgomp -lpthread -lm
+
+# Flags
+OPTFLAGS    := -O3
+OMPFLAGS    := -fopenmp
+WARNFLAGS   := -Wall
+MODDIR_FLAG := -J$(BUILD_DIR)
+
+FFLAGS      := -cpp $(OPTFLAGS) $(OMPFLAGS) $(WARNFLAGS) $(PETSC_INC) $(MODDIR_FLAG)
+DEBUGFLAGS  := -cpp -O0 -g -fcheck=all -fbacktrace -ffpe-trap=invalid,zero,overflow,underflow -fbounds-check $(PETSC_INC) $(MODDIR_FLAG)
+
+# Program
+NAME    := ThermalFlow.x
+TARGET  := $(BIN_DIR)/$(NAME)
+
+# Sources (module order)
+SRCS := \
+  heatflow/mod_constants.f90 \
+  heatflow/mod_constructions.f90 \
+  heatflow/mod_SPtype.f90 \
+  heatflow/mod_global.f90 \
+  heatflow/mod_Sparse.f90 \
+  heatflow/mod_inputs.f90 \
+  heatflow/mod_material.f90 \
+  heatflow/mod_hmatrix.f90 \
+  heatflow/mod_init_evolve.f90 \
+  heatflow/mod_petsc_solver.f90 \
+  heatflow/mod_boundary.f90 \
+  heatflow/mod_heating.f90 \
+  heatflow/mod_cattaneo.f90 \
+  heatflow/mod_tempdep.f90 \
+  heatflow/mod_evolve.f90 \
+  heatflow/mod_output.f90 \
+  heatflow/mod_setup.f90 \
+  heatflow.f90
+
+OBJS := $(addprefix $(BUILD_DIR)/,$(notdir $(SRCS:.f90=.o)))
+
+.PHONY: all debug clean distclean run help show
+
+all: show $(TARGET)
+
+show:
+	@printf 'Building %s %s\n' '$(NAME)' '$(PETSC_NOTE)'
+
+$(BIN_DIR) $(BUILD_DIR):
 	mkdir -p $@
 
-$(programs) : $(OBJS) | $(BIN_DIR) $(BUILD_DIR)
-	$(FC) -O3 -fopenmp $(MODULEFLAGS) $(BUILD_DIR) $(OBJS) -o $@
+# Compile module sources
+$(BUILD_DIR)/%.o: $(SRC_DIR)/heatflow/%.f90 | $(BUILD_DIR)
+	$(FC) $(FFLAGS) -c $< -o $@
+
+# Main program
+$(BUILD_DIR)/heatflow.o: $(SRC_DIR)/heatflow.f90 | $(BUILD_DIR)
+	$(FC) $(FFLAGS) -c $< -o $@
+
+# Link (single definition)
+$(TARGET): $(BIN_DIR) $(OBJS)
+	$(FC) $(OPTFLAGS) $(OMPFLAGS) $(OBJS) -o $@ $(BLAS_FLAGS) $(PETSC_LIB)
 
-debug :  $(OBJS)
-	$(FC) -O0 -Wall -g -ffpe-trap=invalid,zero,overflow,underflow -fbacktrace -fcheck=all -fbounds-check  $(MODULEFLAGS) $(BUILD_DIR) $(OBJS) -o $(programs)
+debug: FFLAGS = $(DEBUGFLAGS)
+debug: clean show $(TARGET)
 
-OMP: $(programs)
-	./util/DShell/omp_exec.sh
+run: $(TARGET)
+	OMP_NUM_THREADS=$(NCORES) \
+	OPENBLAS_NUM_THREADS=$(NCORES) \
+	OMP_PROC_BIND=spread \
+	OMP_PLACES=cores \
+	$< $(RUN_ARGS)
+
+clean:
+	@echo "[CLEAN] objects and modules"
+	@rm -f $(BUILD_DIR)/*.o $(BUILD_DIR)/*.mod
+
+distclean: clean
+	@echo "[CLEAN] executable"
+	@rm -f $(TARGET)
+
+help:
+	@echo "Targets:"
+	@echo "  make / make all    - build optimized"
+	@echo "  make debug         - debug build"
+	@echo "  make run           - run with all cores"
+	@echo "  make clean         - remove objects/modules"
+	@echo "  make distclean     - remove executable"
+	@echo "Variables:"
+	@echo "  RUN_ARGS='-ksp_type cg -pc_type gamg -ksp_rtol 1e-8 -ksp_monitor'"
+	@echo "Parallel build: make -j$(NCORES)"
+
+####################################################################
+# End
+####################################################################

docs/USER_MANUAL.md

@@ -0,0 +1,140 @@
+# HeatFlow User Manual
+
+This manual provides a concise guide to configuring and running simulations using the **HeatFlow** software. The software simulates heat transport using finite difference methods, primarily focusing on the Cattaneo (hyperbolic heat equation) and Fourier models.
+
+## Input Files
+
+The simulation is controlled by three main input files located in the `inputs/` directory:
+1.  **`param.in`**: Simulation parameters (time steps, flags, boundary conditions).
+2.  **`mat.in`**: Material properties.
+3.  **`system.in`**: Geometry and grid definition.
+
+### 1. `param.in` (Simulation Parameters)
+
+This file uses a `KEYWORD = VALUE` format. Comments can be added using `!`.
+
+#### General Settings
+| Keyword | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `_RunName` | String | `default` | Name of the simulation run. |
+| `IVERB` | Integer | `1` | Verbosity level (higher = more output). |
+| `ntime` | Integer | `10` | Total number of time steps. |
+| `time_step` | Double | `1.0` | Time step size. |
+| `freq` | Double | `1.0` | Frequency of the heater. |
+| `icattaneo` | Integer | `1` | Switch for Cattaneo term (`1` = On, `0` = Off/Fourier). |
+| `isteady` | Integer | `0` | Steady state switch (`1` = Steady state, `0` = Transient). |
+| `heattime` | Integer | `0` | Number of steps for which heating is applied (case 2). |
+| `TempDepProp`| Integer | `0` | Flag for temperature dependent properties. |
+
+#### Boundary & Conditions
+| Keyword | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `iboundary` | Integer | `1` | Boundary condition type. |
+| `Periodic` | String | `''` | Periodic boundaries. Contains 'x', 'y', or 'z' (e.g., `'xy'`). |
+| `kappaBound` | Double | `0.0` | Global boundary thermal conductivity (sets all planes). |
+| `kappaBoundx1`...`z2` | Double | `0.0` | Specific boundary conductivity (e.g., `kappaBoundx1` for x=1 plane). |
+| `T_System` | Double | `300.0` | Initial system temperature. |
+| `T_Bath` | Double | - | Global bath temperature (sets all boundaries boundaries). |
+| `T_Bathx1`...`z2` | Double | `T_Bath` | Specific boundary temperatures. |
+| `T_BathCG` | Double | `0.0` | Constant gradient bath temperature. |
+| `CG_dir` | String | `' '` | Direction for constant gradient (e.g., `'+x'`, `'-y'`). |
+| `T_BathCC` | Logical| `F` | Scale constant gradient with DeltaT. |
+| `BR` | Double | `1.0` | Bath Ratio (scaling factor). |
+
+#### Power
+| Keyword | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `power_in` | Double | `0.0` | Power input for the heater. |
+
+#### Flags (Logical)
+All flags default to `.False.`. Set to `.True.` (or `T`) to enable.
+- `_Check_Sparse_Full`: Check if simulation is sparse or full.
+- `_Check_Stability`: Perform stability check.
+- `_Check_Steady_State`: Check for steady state convergence.
+- `_WriteToTxt`: Enable writing output to text files.
+- `_Percentage_Completion`: Show progress % in output.
+- `_Test_Run`: Flag for test runs.
+- `_InputTempDis`: Load initial temperature distribution from file.
+- `_FullRestart`: Perform a full restart.
+
+#### Output Control
+Defines the region of the grid to write to output.
+| Keyword | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `write_every` | Integer | `1` | Write output every N steps. |
+| `start_ix`, `end_ix` | Integer | `1`..`Nx` | X-range for output. |
+| `start_iy`, `end_iy` | Integer | `1`..`Ny` | Y-range for output. |
+| `start_iz`, `end_iz` | Integer | `1`..`Nz` | Z-range for output. |
+
+---
+
+### 2. `mat.in` (Material Properties)
+
+Defines the physical properties for each material index used in the system. The file ends with a line containing `0`.
+
+**Format:**
+```
+<Material_Index>
+keyword = value
+...
+0
+```
+
+| Keyword | Description |
+| :--- | :--- |
+| `heat_capacity` | Specific heat capacity. |
+| `kappa` | Thermal conductivity. |
+| `rho` | Density. |
+| `tau` | Relaxation time (for Cattaneo). |
+| `em` | Emissivity / Parameter (usage depends on physics context). |
+| `vel` | Velocity vector (3 components, e.g., `vel = 1.0 0.0 0.0`). |
+
+**Example:**
+```
+1
+heat_capacity = 4200
+kappa = 0.541
+rho = 997
+tau = 1e-12
+vel = 0.0 0.0 0.0
+0
+```
+
+---
+
+### 3. `system.in` (Geometry/Mesh)
+
+Defines the simulation grid and the material distribution.
+
+**Structure:**
+1.  **Grid Dimensions**: `nx ny nz`
+2.  **Physical Dimensions**: `Lx Ly Lz`
+3.  **Grid Data**: A list of `MaterialID:HeaterID` for every cell.
+
+The file is read in the order: Z-planes, then Y-rows, then X-columns.
+Each line in the file (after header) corresponds to one row (X-direction).
+
+**Example:**
+```
+10 10 1
+0.01 0.01 0.001
+
+! Z=1, Y=1 Row
+1:0 1:0 1:0 1:0 1:0 1:0 1:0 1:0 1:0 1:0
+! Z=1, Y=2 Row
+1:0 1:0 ...
+```
+- `1:0` means Material ID 1, Heater ID 0 (no heater).
+- `1:1` means Material ID 1, Heater ID 1 (active heater).
+
+## Execution
+
+Ensure the `inputs/` directory exists with the three required files. Run the executable from the directory containing `inputs/`.
+
+```bash
+./ThermalFlow.x
+```
+or via `fpm`:
+```bash
+fpm run --profile release
+```

src/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:conda",
+    "python-envs.defaultPackageManager": "ms-python.python:conda",
+    "python-envs.pythonProjects": []
+}

src/heatflow.f90

@@ -28,11 +28,18 @@ program HEATFLOW_V0_3
   use evolution, only: simulate
   use setup, only: set_global_variables
   use INITIAL, only: initial_evolve
+  use petsc_solver, only: petsc_init, petsc_finalize
 
   implicit none
    real(real12) :: cpustart, cpuend, cpustart2, progress
    integer(int12) :: itime
 
+   !-------------------------------------------------------------!
+   ! Initialize PETSc FIRST (before any other operations)       !
+   !-------------------------------------------------------------!
+   CALL petsc_init()
+   !^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^!
+
    !-------------------------------------------------------------!
    ! calculate the time to run full simulation                   !
    !-------------------------------------------------------------!
@@ -64,6 +71,7 @@ program HEATFLOW_V0_3
    !-------------------------------------------------------------!
    ! run simulation for 'ntime' time steps                       !
    !-------------------------------------------------------------!
+
    do itime=1,ntime 
 
       if (iverb.eq.0) then
@@ -79,21 +87,24 @@ program HEATFLOW_V0_3
       ! CALL initial_evolve to set systems initial Temperature conditions      
       if (itime .eq. 1) CALL initial_evolve                      
 
-      ! run the time evolution                                   
+      ! run the time evolution  
       CALL simulate(itime)
+
 
 
       ! Write results                           
       CALL data_write(itime) 
       if (IVERB.ge.3) CALL final_print                           
 
-   end do                                                        
+   end do  
+   CALL petsc_finalize()
+
    !^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^!
 
    !-------------------------------------------------------------!
    ! calculate end time and print to user                        !
    !-------------------------------------------------------------!
-   CALL cpu_time(cpuend)                                          
+   CALL cpu_time(cpuend)
    write(*,'(A,F12.6)') ' time=', cpuend-cpustart                 
    !^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^!