Skip to content

README.md

Latest commit

 

History

History
134 lines (88 loc) · 4.71 KB

README.md

File metadata and controls

134 lines (88 loc) · 4.71 KB
Raw

License workflow CMAKE GCC compatibility

HeatFlow

by Harry Mclean, Francis Huw Davies, Ned Thaddeus Taylor, and Steven Paul Hepplestone

HeatFlow is Fortran-based a software package for modelling dynamical heat transport in systems using finite difference methods. The software is primarily designed to utilise the Cattaneo method. However, the Fourier method can be used instead.

IMPORTANT NOTICE: Repository Migration to GitHub

Dear users and contributors,

This repository has been to be migrated from the University of Exeter GitLab to GitHub to facilitate community interaction and support. The latest version, updates, and collaboration now take place on this GitHub repository.

GitLab Repository (Archived): https://git.exeter.ac.uk/hepplestone/heatflow-mk2

Why the Migration?

It was decided that this project should be migrated to allow for better community support (i.e. allowing community users to raise issues). All information has been ported over where possible. Releases prior to HeatFlow_CattaneoPaper have had their history modified to remove history of files over 50MB in size.

Requirements

  • Fortran compiler supporting Fortran 2003 standard or later
  • MPI (e.g. OpenMPI) — required
  • PETSc — optional, enables the ilu, lu and gamg solvers (without it only the legacy solver is available)
  • HDF5 — optional, enables HDF5 output (_HDF5Output flag)
  • GNU Make or CMake (fpm can also be used)

On macOS, dependencies are available via Homebrew: brew install open-mpi petsc hdf5-mpi

The software bas been developed and tested using the following Fortran compilers:

  • gfortran -- gcc 13.2.0
  • gfortran -- gcc 14.1.0

Installation

To install HeatFlow, the source must be obtained from the git repository. Use the following commands to get started:

 git clone https://github.com/ExeQuantCode/HeatFlow.git
 cd HeatFlow

make

The simplest way to build is with the provided Makefile. PETSc is detected automatically; if it is not found, a legacy-solver-only version is built:

make

To force a build without PETSc even when it is installed:

make PETSC=0

To build with HDF5 output support:

make USE_HDF5=1

PETSc is detected via pkg-config or PETSC_DIR/PETSC_ARCH on Linux, and via Homebrew on macOS. The executable is written to bin/HeatFlow.

cmake

For cmake installation, start within the repository root directory, run the following commands:

mkdir build
cd build
cmake [-DCMAKE_BUILD_TYPE=Release] [-DHEATFLOW_PETSC=ON] [-DHEATFLOW_HDF5=ON] ..
make install

This will build and install the executable in the following directory:

${HOME}/.local/HeatFlow/bin/HeatFlow

This executable can now be called to run the HeatFlow software package and simulate heat transport. If the ${HOME}/.local/HeatFlow/bin is added to your PATH environment variable, then the program can be called as a terminal command. This can be done with the following command (works on a per-terminal basis, if you want to update it for all, include this in your source shell file):

export PATH="${PATH}:${HOME}/.local/HeatFlow/bin"

fpm

To install using fpm, run the following command in the repository root directory:

fpm build --profile=release

Running

The simulation is controlled by input files (param.in, mat.in, system.in), read by default from ./inputs, with output written to ./outputs (restart files in ./restart). The directories can be selected on the command line — -i/--input-directory, -o/--output-directory, or the --directory alias which maps to <dir>/inputs, <dir>/outputs and <dir>/restart (the output directory is created if it does not exist).

Example command:

OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 mpiexec -n 2 ./bin/HeatFlow -i ./inputs -o ./outputs

or equivalently, with a single run directory:

mpiexec -n 2 ./bin/HeatFlow --directory .

The linear solver is chosen at runtime with the solver keyword in param.in (legacy, ilu, lu or gamg; default ilu). PETSc runtime options (e.g. -ksp_monitor) can be passed on the command line alongside the directory options:

mpiexec -n 2 ./bin/HeatFlow -i ./inputs -o ./outputs -ksp_monitor

Setting _HDF5Output = T in param.in writes the temperature field to outputs/output_<RunName>.h5 (requires a build with HDF5 support).

See docs/USER_MANUAL.md for the full list of input keywords and options.