Rework existing README

README.md

@@ -1,23 +1,24 @@
-# Fourier Accelerated Nodal Solvers (FANS)
+# Fourier-Accelerated Nodal Solvers (FANS)
 
-Fourier Accelerated Nodal Solvers (FANS) is an FFT-based homogenization solver designed to handle microscale multiphysics problems. This repository contains a C++ implementation of FANS, built using CMake and MPI for parallel computations.
+Fourier-Accelerated Nodal Solver (FANS) is an FFT-based homogenization solver for microscale multiphysics problems. FANS is written in C++, built using CMake, and it has MPI parallelization.
 
-<img src="docs/images/FANS_example.png" alt="Example Image" width="400" height="300">
+<p align="center">
+  <img src="docs/images/FANS_example.png" alt="Example Image" width="400" height="300">
+</p>
 
 ## Table of contents
 
 - [Dependencies](#dependencies)
 - [Building](#building)
 - [Installing](#installing)
 - [Input File Format](#input-file-format)
-- [Examples](#examples)
 
 ## Dependencies
 
 FANS has the following dependencies:
 
-- A C++ compiler (e.g. GCC)
-- CMake (version 3.0 or higher) (+ Unix file utility for creating .deb packages)
+- A C++ compiler (e.g. GCC, Clang, etc.)
+- CMake (version 3.21 or higher)
 - Git (for cloning this repo)
 - MPI (mpicc and mpic++)
 - HDF5 with MPI support
@@ -26,55 +27,49 @@ FANS has the following dependencies:
 
 ### Installing dependencies
 
-We recommend installing the dependencies using a package manager. For example, using `apt`, the following commands are run:
+- On Debian based systems, we recommend installing the dependencies using using `apt`,
 
-```bash
-apt-get install \
-    libhdf5-dev \
-    libopenmpi-dev \
-    libeigen3-dev \
-    libfftw3-dev \
-    libfftw3-mpi-dev
-```
+  ```bash
+  apt-get install \
+      libhdf5-dev \
+      libopenmpi-dev \
+      libeigen3-dev \
+      libfftw3-dev \
+      libfftw3-mpi-dev
+  ```
 
-On macOS, you can obtain the dependencies using `brew` and set the environment variables:
+- On macOS, you can obtain the dependencies using `brew` and set the environment variables:
 
-```zsh
-brew install gnu-time cmake gcc@14
-brew install open-mpi --build-from-source --cc=gcc-14
-brew install hdf5-mpi --build-from-source --cc=gcc-14
-brew install fftw eigen
+  ```zsh
+  brew install gnu-time cmake gcc@14
+  brew install open-mpi --build-from-source --cc=gcc-14
+  brew install hdf5-mpi --build-from-source --cc=gcc-14
+  brew install fftw eigen
 
-export CC=gcc-14 CXX=g++-14 MPICC=mpicc MPICXX=mpicxx
-```
+  export CC=gcc-14 CXX=g++-14 MPICC=mpicc MPICXX=mpicxx
+  ```
 
 ### Setting up a Python environment
 
 Also, we recommend to set up a Python virtual environment for the [`FANS_Dashboard.ipynb`](FANS_Dashboard/FANS_Dashboard.ipynb) via [pixi](https://pixi.sh/) with all required Python dependencies in an isolated environment:
 
 ```bash
-# Install pixi if you don't have it already
+# Install pixi if not done already
 curl -fsSL https://pixi.sh/install.sh | sh
 
 # Create and activate the environment
 pixi shell
 ```
 
-We also provide a [set of Docker images](docker/) to work with FANS within an isolated environment.
+We also provide a set of Docker images. For further information, please refer to the [Docker README](docker/README.md).
 
 ### 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 remote systems.
+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 HPC systems.
 
-1. **Install Spack**: If Spack is not installed, set it up with the following commands:
-
-    ```bash
-    git clone https://github.com/spack/spack.git
-    cd spack
-    . ./share/spack/setup-env.sh
-    ```
+1. **Install Spack** by following these [installation instructions](https://spack.readthedocs.io/en/latest/getting_started.html).
 
-2. **Install Dependencies**: Once Spack is set up, you can install the required dependencies:
+2. **Install Dependencies**: Once Spack is set up, install the required dependencies:
 
     ```bash
     spack install cmake
@@ -84,9 +79,9 @@ Spack is a package manager designed for high-performance computing environments.
     spack install fftw +mpi
     ```
 
-    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).
+    Additionally, 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:
+3. **Load Dependencies** Once dependencies are installed, load them before building:
 
     ```bash
     spack load cmake mpi hdf5 eigen fftw
@@ -122,14 +117,13 @@ The compilation symlinks the generated `FANS` binary into the `test/` directory
 The following CMake configuration options exist:
 
 - `CMAKE_BUILD_TYPE`: Sets the build type. Common values are Debug, Release, RelWithDebInfo, and MinSizeRel.
+  - Default: NONE
 
 - `FANS_BUILD_STATIC`: Build static library instead of shared library.
   - Default: OFF
-  - Usage: `-DFANS_BUILD_STATIC=ON`
 
 - `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
@@ -142,21 +136,13 @@ Install FANS (system-wide) using the following options:
     cmake --install . [--prefix <install-dir>]
     ```
 
-2. Using .deb packages (only debian based distros; sudo required):
-
-    ```bash
-    cpack -G "DEB"
-    apt install packages/fans_<version>_<architecture>.deb
-    apt install packages/fans-dev_<version>_<architecture>.deb
-    ```
-
 ### Install using Conda
 
 [![Anaconda-Server Badge](https://anaconda.org/conda-forge/fans/badges/version.svg)](https://anaconda.org/conda-forge/fans)
 [![Anaconda-Server Badge](https://anaconda.org/conda-forge/fans/badges/platforms.svg)](https://anaconda.org/conda-forge/fans)
 [![Anaconda-Server Badge](https://anaconda.org/conda-forge/fans/badges/downloads.svg)](https://anaconda.org/conda-forge/fans)
 
-FANS is also available as a conda-package on [conda-forge](https://anaconda.org/conda-forge/fans). No dependencies have to be manually installed for it to work.
+FANS is also available as a conda-package on [conda-forge/fans](https://anaconda.org/conda-forge/fans). No dependencies have to be manually installed for it to work.
 It can be installed via
 
 ```bash
@@ -173,10 +159,10 @@ FANS requires a JSON input file specifying the problem parameters. Example input
 
 ```json
 "microstructure": {
-        "filepath": "microstructures/sphere32.h5",
-        "datasetname": "/sphere/32x32x32/ms",
-        "L": [1.0, 1.0, 1.0]
-    }
+                    "filepath": "microstructures/sphere32.h5",
+                    "datasetname": "/sphere/32x32x32/ms",
+                    "L": [1.0, 1.0, 1.0]
+                  }
 ```
 
 - `filepath`: This specifies the path to the HDF5 file that contains the microstructure data.
@@ -188,24 +174,34 @@ FANS requires a JSON input file specifying the problem parameters. Example input
 ```json
 "matmodel": "LinearElasticIsotropic",
 "material_properties": {
-    "bulk_modulus": [62.5000, 222.222],
-    "shear_modulus": [28.8462, 166.6667]
-}
+                         "bulk_modulus": [62.5000, 222.222],
+                         "shear_modulus": [28.8462, 166.6667]
+                       }
 ```
 
-- `problem_type`: This defines the type of physical problem you are solving. Common options include "thermal" problems and "mechanical" problems.
-- `matmodel`: This specifies the material model to be used in the simulation. Examples include `LinearThermalIsotropic` for isotropic linear thermal problems, `LinearElasticIsotropic` for isotropic linear elastic mechanical problems, `PseudoPlasticLinearHardening`/`PseudoPlasticNonLinearHardening` for plasticity mimicking model with linear/nonlinear hardening, and `J2ViscoPlastic_LinearIsotropicHardening`/`J2ViscoPlastic_NonLinearIsotropicHardening` for rate dependent J2 plasticity model with linear/nonlinear isotropic hardening.
+- `problem_type`: This defines the type of physical problem you are solving. Common options include `thermal` problems and `mechanical` problems.
+- `matmodel`: This specifies the material model to be used in the simulation. Examples include
+
+  - `LinearThermalIsotropic` for linear isotropic conductive material model
+  - `LinearThermalTriclinic` for linear triclinic conductive material model
+  - `GBDiffusion` for diffusion model with transversely isotropic grain boundary and isotropic bulk for polycrystalline materials
+
+  - `LinearElasticIsotropic` for linear isotropic elastic material model
+  - `LinearElasticTriclinic` for linear triclinic elastic material model
+  - `PseudoPlasticLinearHardening` / `PseudoPlasticNonLinearHardening` for plasticity mimicking model with linear/nonlinear hardening
+  - `J2ViscoPlastic_LinearIsotropicHardening` / `J2ViscoPlastic_NonLinearIsotropicHardening` for rate independent / dependent J2 plasticity model with kinematic and linear/nonlinear isotropic hardening.
+
 - `material_properties`: This provides the necessary material parameters for the chosen material model. For thermal problems, you might specify `conductivity`, while mechanical problems might require `bulk_modulus`, `shear_modulus`, and more properties for advanced material models. These properties can be defined as arrays to represent multiple phases within the microstructure.
 
 ### Solver Settings
 
 ```json
 "method": "cg",
 "error_parameters":{
-    "measure": "Linfinity",
-    "type": "absolute",
-    "tolerance": 1e-10
-},
+                     "measure": "Linfinity",
+                     "type": "absolute",
+                     "tolerance": 1e-10
+                   },
 "n_it": 100,
 ```
 
@@ -236,16 +232,29 @@ FANS requires a JSON input file specifying the problem parameters. Example input
 ```
 
 - `macroscale_loading`: This defines the external loading applied to the microstructure. It is an array of arrays, where each sub-array represents a loading condition applied to the system. The format of the loading array depends on the problem type:
-- For `thermal` problems, the array typically has 3 components, representing the temperature gradients in the x, y, and z directions.
-- For `mechanical` problems, the array must have 6 components, corresponding to the components of the strain tensor in Mandel notation (e.g., [[ε_11, ε_22, ε_33, √2 ε_12, √2 ε_13, √2 ε_23]]).
+- For `thermal` problems, the array typically has 3 components, representing the temperature gradients in the $x$, $y$, and $z$ directions.
+- For `mechanical` problems, the array must have 6 components, corresponding to the components of the strain tensor in Mandel notation (e.g., $[\varepsilon_{11},\; \varepsilon_{22},\; \varepsilon_{33},\; \sqrt{2}\varepsilon_{12},\; \sqrt{2}\varepsilon_{13},\; \sqrt{2}\varepsilon_{23}]$).
 
 In the case of path/time-dependent loading as shown, for example as in plasticity problems, the `macroscale_loading` array can include multiple steps with corresponding loading conditions.
 
+FANS also supports mixed boundary conditions, where some components can be strain-controlled while others are stress-controlled:
+
+```json
+"macroscale_loading":   [{
+                           "strain_indices" : [2,3,4,5],
+                           "stress_indices" : [0,1],
+                           "strain" : [[0.005 , 0.0, 0.0, 0.0],
+                                       [0.010 , 0.0, 0.0, 0.0]],
+                           "stress" : [[0.0, 0.0],
+                                       [0.0, 0.0]]
+                          }]
+```
+
 ### Results Specification
 
 ```json
 "results": ["stress_average", "strain_average", "absolute_error", "phase_stress_average", "phase_strain_average",
-            "microstructure", "displacement", "stress", "strain"]
+            "microstructure", "displacement", "displacement_fluctuation", "stress", "strain"]
 ```
 
 - `results`: This array lists the quantities that should be stored into the results HDF5 file during the simulation. Each string in the array corresponds to a specific result:
@@ -254,22 +263,15 @@ In the case of path/time-dependent loading as shown, for example as in plasticit
   - `absolute_error`: The L-infinity error of finite element nodal residual at each iteration.
   - `phase_stress_average` and `phase_strain_average`: Volume averaged- homogenized stress and strain for each phase within the microstructure.
   - `microstructure`: The original microstructure data.
-  - `displacement`: The displacement fluctuation field (for mechanical problems) and temperature fluctuation field (for thermal problems).
+  - `displacement`: The displacement field (for mechanical problems) and temperature field (for thermal problems) at each voxel in the microstructure.
+  - `displacement_fluctuation`: The periodic displacement fluctuation field (for mechanical problems) and periodic temperature fluctuation field (for thermal problems at each voxel in the microstructure).
   - `stress` and `strain`: The stress and strain fields at each voxel in the microstructure.
 
 - Additional material model specific results can be included depending on the problem type and material model.
 
-## Examples
-
-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
-```
-
 ## Acknowledgements
 
-Funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under Germany’s Excellence Strategy - EXC 2075 – 390740016. Contributions by Felix Fritzen are funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) within the Heisenberg program - DFG-FR2702/8 - 406068690; DFG-FR2702/10 - 517847245 and through NFDI-MatWerk - NFDI 38/1 - 460247524. We acknowledge the support by the Stuttgart Center for Simulation Science (SimTech).
+Funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under Germany’s Excellence Strategy - EXC 2075 – 390740016. Contributions by Felix Fritzen are funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) within the Heisenberg program - DFG-FR2702/8 - 406068690; DFG-FR2702/10 - 517847245 and through NFDI-MatWerk - NFDI 38/1 - 460247524. We acknowledge the support by the Stuttgart Center for Simulation Science ([SimTech](https://www.simtech.uni-stuttgart.de/)).
 
 ## Contributors
 
@@ -278,3 +280,4 @@ Funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) unde
 - [Ishaan Desai](https://github.com/IshaanDesai)
 - [Moritz Sigg](https://github.com/siggmo)
 - [Claudius Haag](https://github.com/claudiushaag)
+- [Felix Fritzen](https://github.com/EMMAOpenSource)

docker/README.md

@@ -5,7 +5,7 @@ We provide a set of docker images for different use cases on our [Dockerhub prof
 - **fans-ci**: Contains the minimum tools to build FANS (including dev packages of dependencies with the required headers), but does not include FANS itself. Meant for a CI workflow.
 - **fans-dev**: Based upon fans-ci, but offers a non-root user (`fans`) and handling of UID and GID to not mess up permissions when volume mounting into the container. Meant as an quick to setup build environment for FANS.
 
-Both images are built for linux/amd64 and linux/arm64 as well as for the three most recent Ubuntu LTS versions (jammy and noble). The Ubuntu version can be selected through tags, e.g. `fans-dev:jammy`; `noble` is equivalent to the `latest` tag. The architecture is selected automatically depending on your host platform.
+Both images are built for linux/amd64 and linux/arm64 as well as for the two most recent Ubuntu LTS versions (jammy and noble). The Ubuntu version can be selected through tags, e.g. `fans-dev:jammy`; `noble` is equivalent to the `latest` tag. The architecture is selected automatically depending on your host platform.
 
 ## Set up a Container
 

test/README.md

@@ -44,6 +44,7 @@ For a 3D microstructure image of resolution `32 x 32 x 32` with a single spheric
 - Small strain mechanical homogenization problem with linear elasticity - `test_LinearElastic.json`
 - Small strain mechanical homogenization problem with nonlinear pseudoplasticity - `test_PseudoPlastic.json`
 - Small strain mechanical homogenization problem with Von-Mises plasticity - `test_J2Plasticity.json`
+- Small strain mechanical homogenization problem with linear pseudoplasticity and mixed stress-strain control boundary conditions - `test_MixedBCs.json`
 
 Each test case has corresponding input JSON files in the `input_files/` directory. Tests can be run individually as example problems. For instance,