Improve traditional installation guide (#22)

* Add build toolchain and recommended utilities to installation guide * fix mardown linter problems, and remove minimal installation section * Rework large parts of the README * Further improvements to the README * Update Changelog * Revert "Update Changelog" This reverts commit cb6888c. * fix: Unix file utility is not part of GNU * Refer to FANS_Dashboard explicitly Co-authored-by: Sanath Keshav <sanathkeshav.mysore@gmail.com> --------- Co-authored-by: Ishaan Desai <ishaandesai@gmail.com> Co-authored-by: Sanath Keshav <sanathkeshav.mysore@gmail.com>
DataAnalyticsEngineering · Sep 20, 2024 · 528e517 · 528e517
1 parent 28782a0
commit 528e517
Showing 1 changed file with 49 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -4,51 +4,63 @@ Fourier Accelerated Nodal Solvers (FANS) is an FFT-based homogenization solver d
 
 <img src="docs/images/FANS_example.png" alt="Example Image" width="400" height="300">
 
-## Table of Contents
+## Table of contents
 
-- [Installation](#installation)
-- [Input File Format](#input-file-format)
+- [Dependencies](#dependencies)
+- [Building](#building)
+- [Installing](#installing)
+- [Input file format](#input-file-format)
 - [Examples](#examples)
-- [Acknowledgements](#acknowledgements)
-- [Contributors](#contributors)
 
-## Installation
+## Dependencies
 
-### Prerequisites
+FANS has the following dependencies:
 
-Before proceeding with the installation, ensure that your system has the necessary dependencies. The prerequisites of FANS can be installed using Spack for a streamlined setup on high-performance computing systems, or through traditional package management for personal use.
-
-### Traditional Installation
-
-If you're setting up FANS on a personal computer or in a non-HPC environment, follow these instructions:
-
-Please ensure you have the following dependencies installed on your system:
-
-- CMake (version 3.0 or higher)
+- A C++ compiler (e.g. GCC)
+- CMake (version 3.0 or higher) (+ Unix file utility for creating .deb packages)
+- Git (for cloning this repo)
 - MPI (mpicc and mpic++)
 - HDF5 with parallel support
 - Eigen3
 - FFTW3 with MPI support
 
-Specifically, to run FANS, you at least need the following packages:
+### Installing dependencies
+
+We recommend installing the dependencies using a package manager. For example, using `apt`, the following commands are run:
 
 ```bash
-openmpi-bin libc6 libfftw3-double3 libfftw3-mpi3 libgcc-s1 libgomp1 libhdf5-103 libopenmpi3 libstdc++6
+apt-get install \
+    libhdf5-dev \
+    libopenmpi-dev \
+    libeigen3-dev \
+    libfftw3-dev \
+    libfftw3-mpi-dev
 ```
 
-To build fans, you additionally need these packages:
+Also, we recommend to set up a Python virtual environment for the `FANS_Dashboard`:
 
 ```bash
-libhdf5-dev libopenmpi-dev libeigen3-dev libfftw3-dev libfftw3-mpi-dev
+apt-get install \
+    time \
+    htop \
+    python3 \
+    python3-pip \
+    python3-venv \
+    python-is-python3 \
+    python3-dev
+
+python -m venv ~/venvs/FANS
+source ~/venvs/FANS/bin/activate
+python -m pip install h5py lxml
 ```
 
-If for some reason you are unable to install these packages directly on your host machine, have a look at the [set of Docker images](docker/) to create and work with FANS within an isolated environment.
+We also provide a [set of Docker images](docker/) to work with FANS within an isolated environment.
 
-### Spack Installation (Recommended for Clusters/Supercomputers)
+### Installing dependencies using Spack
 
-Spack is a package manager designed for high-performance computing environments. It simplifies the installation of complex software stacks, making it ideal for setting up FANS on large clusters or supercomputers.
+Spack is a package manager designed for high-performance computing environments. It simplifies the installation of complex software stacks, making it ideal for setting up FANS on remote systems.
 
-1. **Install Spack**: If you don’t have Spack installed, you can set it up with the following commands:
+1. **Install Spack**: If Spack is not installed, set it up with the following commands:
 
     ```bash
     git clone https://github.com/spack/spack.git
@@ -66,15 +78,15 @@ Spack is a package manager designed for high-performance computing environments.
     spack install fftw +mpi
     ```
 
-    You can also use alternative and optimized FFTW implementations depending on your system's architecture like amdfftw (For AMD systems) or cray-fftw (For Cray systems) or fujitsu-fftw (For Fujitsu systems).
+    Alternatively, optimized FFTW implementations can be used depending on your system's architecture, for example `amdfftw` (For AMD systems) or `cray-fftw` (For Cray systems) or `fujitsu-fftw` (For Fujitsu systems).
 
 3. **Load Dependencies** Once dependencies are installed, you can load them before building:
 
     ```bash
     spack load cmake mpi hdf5 eigen fftw
     ```
 
-### Building the Project
+## Building
 
 1. Clone the repository:
 
@@ -83,40 +95,40 @@ Spack is a package manager designed for high-performance computing environments.
     cd FANS
     ```
 
-2. Configure the project using CMake:
+2. Configure the build using CMake:
 
     ```bash
     mkdir build
     cd build
     cmake ..
     ```
 
-3. Compile the project:
+3. Compile:
 
     ```bash
     cmake --build . -j
     ```
 
-The compilation will symlink the generated `FANS` binary into the `test/` directory for convenience.
+The compilation symlinks the generated `FANS` binary into the `test/` directory for convenience.
 
-### Build Options
+### Configuring a build
 
-This project supports the following CMake build options:
+The following CMake configuration options exist:
 
 - `CMAKE_BUILD_TYPE`: Sets the build type. Common values are Debug, Release, RelWithDebInfo, and MinSizeRel.
 
 - `FANS_BUILD_STATIC`: Build static library instead of shared library.
   - Default: OFF
   - Usage: `-DFANS_BUILD_STATIC=ON`
 
-- `CMAKE_INTERPROCEDURAL_OPTIMIZATION`: Enable interprocedural optimization (IPO) for all targets.
+- `CMAKE_INTERPROCEDURAL_OPTIMIZATION`: Enable inter-procedural optimization (IPO) for all targets.
   - Default: ON (if supported)
   - Usage: `-DCMAKE_INTERPROCEDURAL_OPTIMIZATION=OFF`
   - Note: When you run the configure step for the first time, IPO support is automatically checked and enabled if available. A status message will indicate whether IPO is activated or not supported.
 
-### Installing the Project
+## Installing
 
-After compiling, you can install FANS (system-wide) using the following options:
+Install FANS (system-wide) using the following options:
 
 1. Using CMake (sudo required if --prefix is omitted):
 
@@ -134,8 +146,7 @@ After compiling, you can install FANS (system-wide) using the following options:
 
 ## Input File Format
 
-To run the FANS solver, you need to provide a JSON input file specifying the problem parameters.
-Example input files can be found in the [`test/input_files`](test/input_files)  directory. You can use these files as a reference to create your own input file. The input file is in JSON format and contains several fields to define the problem settings...
+FANS requires a JSON input file specifying the problem parameters. Example input files can be found in the [`test/input_files`](test/input_files) directory. It is recommended to use these files as a reference to create your own input file.
 
 ### Microstructure Definition
 
@@ -218,9 +229,9 @@ In the case of path/time-dependent loading as shown, for example as in plasticit
 
 - Additional material model specific results can be included depending on the problem type and material model.
 
-### Examples
+## Examples
 
-If you would like to run some example tests, you can execute the [`run_tests.sh`](test/run_tests.sh) file. For example to run a linear elastic mechanical homogenization problem for a 6 othonormal load cases on a microstructure image of size `32 x 32 x 32` with a single spherical inclusion,
+Execute the [`run_tests.sh`](test/run_tests.sh) file to run tests, which are also examples. For example, to run a linear elastic mechanical homogenization problem for a 6 othonormal load cases on a microstructure image of size `32 x 32 x 32` with a single spherical inclusion,
 
 ```bash
 mpiexec -n 2 ./FANS input_files/test_LinearElastic.json test_results.h5