110 add convection term

CHANGELOG

@@ -12,6 +12,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 ### Security
 
+##[2.0.0] - 2026-03-26
+## Added
+-Add Petsc solver
+-Add new constant gradient boundary conditions
+-Add new compressed output flag
+
+
+
+
 ##[1.0.0] - 2025-07-28
 ## Added
 -Additional boundary conditions

Makefile

@@ -1,70 +1,172 @@
 ####################################################################
-#   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 (prefer system MPI wrapper for PETSc builds, allow user override)
+SYSTEM_PATH := PATH=/usr/bin:/bin
+ifeq ($(origin FC), default)
+ifneq ($(wildcard /usr/bin/mpifort),)
+FC := env $(SYSTEM_PATH) /usr/bin/mpifort
+else ifneq ($(wildcard /usr/bin/gfortran),)
+FC := env $(SYSTEM_PATH) /usr/bin/gfortran
+else
+FC := gfortran
+endif
+endif
+
+# 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 (discover dynamically when possible)
+ifneq ($(wildcard /usr/bin/pkg-config),)
+PKG_CONFIG := env $(SYSTEM_PATH) /usr/bin/pkg-config
+else
+PKG_CONFIG := pkg-config
+endif
+PETSC_PKG_CFLAGS := $(shell $(PKG_CONFIG) --cflags petsc 2>/dev/null || $(PKG_CONFIG) --cflags PETSc 2>/dev/null)
+PETSC_PKG_LIBS   := $(shell $(PKG_CONFIG) --libs petsc 2>/dev/null || $(PKG_CONFIG) --libs PETSc 2>/dev/null)
+
+ifdef PETSC_DIR
+PETSC_DIR_INC := -I$(PETSC_DIR)/include
+ifdef PETSC_ARCH
+PETSC_DIR_INC += -I$(PETSC_DIR)/$(PETSC_ARCH)/include
+PETSC_DIR_LIB := -L$(PETSC_DIR)/$(PETSC_ARCH)/lib -Wl,-rpath,$(PETSC_DIR)/$(PETSC_ARCH)/lib
+endif
+endif
+
+ifeq ($(strip $(PETSC_PKG_CFLAGS)),)
+PETSC_INC  := $(PETSC_DIR_INC)
+PETSC_LIB  := $(PETSC_DIR_LIB) -lpetsc
+PETSC_NOTE := (PETSc from PETSC_DIR/PETSC_ARCH)
+else
+PETSC_INC  := $(PETSC_PKG_CFLAGS)
+PETSC_LIB  := $(PETSC_PKG_LIBS)
+PETSC_NOTE := (PETSc via pkg-config)
+endif
+
+ifeq ($(strip $(PETSC_INC)),)
+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 := (legacy PETSc 3.15 fallback)
+endif
+
+# BLAS/LAPACK backend
+OPENBLAS_LIBS := $(shell $(PKG_CONFIG) --libs openblas 2>/dev/null)
+CONDA_BLAS_LIB := $(firstword $(wildcard $(CONDA_PREFIX)/lib/libblas.so.3 $(CONDA_PREFIX)/lib/libblas.so))
+CONDA_LAPACK_LIB := $(firstword $(wildcard $(CONDA_PREFIX)/lib/liblapack.so.3 $(CONDA_PREFIX)/lib/liblapack.so))
+ifeq ($(strip $(OPENBLAS_LIBS)),)
+ifneq ($(strip $(CONDA_BLAS_LIB)$(CONDA_LAPACK_LIB)),)
+BLAS_FLAGS := -Wl,--disable-new-dtags -Wl,-rpath,$(CONDA_PREFIX)/lib -Wl,--no-as-needed $(CONDA_BLAS_LIB) $(CONDA_LAPACK_LIB) -Wl,--as-needed -lpthread -lm
+BLAS_NOTE := (OpenBLAS from CONDA_PREFIX)
+else
+BLAS_FLAGS := -lblas -llapack -lpthread -lm
+BLAS_NOTE := (system BLAS/LAPACK fallback)
+endif
+else
+BLAS_FLAGS := $(OPENBLAS_LIBS) -lpthread -lm
+BLAS_NOTE := (OpenBLAS via pkg-config)
+endif
+
+# 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)))
+
+.NOTPARALLEL:
+
+.PHONY: all debug clean distclean run help show
+
+all: show $(TARGET)
+
+show:
+	@printf 'Building %s %s %s\n' '$(NAME)' '$(PETSC_NOTE)' '$(BLAS_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 $@
 
-debug :  $(OBJS)
-	$(FC) -O0 -Wall -g -ffpe-trap=invalid,zero,overflow,underflow -fbacktrace -fcheck=all -fbounds-check  $(MODULEFLAGS) $(BUILD_DIR) $(OBJS) -o $(programs)
+# Link (single definition)
+$(TARGET): $(BIN_DIR) $(OBJS)
+	$(FC) $(OPTFLAGS) $(OMPFLAGS) $(OBJS) -o $@ $(BLAS_FLAGS) $(PETSC_LIB)
 
-OMP: $(programs)
-	./util/DShell/omp_exec.sh
+debug: FFLAGS = $(DEBUGFLAGS)
+debug: clean show $(TARGET)
+
+run: $(TARGET)
+	mpiexec -n $(NCORES) \
+	OMP_NUM_THREADS=1 \
+	OPENBLAS_NUM_THREADS=1 \
+	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 distributed across all cores via MPI"
+	@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
+```