Fourier-Accelerated Nodal Solver (FANS)

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.

Table of Contents

• Quick start
• Build from source
  • Installing dependencies
  • Building FANS
• Python environment for the FANS dashboard
• Publications using FANS
• Input file format
  • Microstructure definition
  • Problem type and material model
  • Solver settings
  • Macroscale loading conditions
  • Results specification

Quick start

Want to get started immediately?

FANS is available as a precompiled binary on conda-forge. Package managers such as conda, mamba, micromamba, and Pixi can be used to install FANS from the conda-forge channel.

Use Pixi (recommended):

# Install Pixi (if not already installed)
curl -fsSL https://pixi.sh/install.sh | sh
# Install FANS via Pixi
pixi global install fans
# Verify installation
FANS --version

That's it! No dependencies to install, no compilation needed 🚀

To get started immediately, we include ready to use example input files and microstructures you can use as templates to create your own.

---

Build from source

Recommended for: Developers, contributors, HPC users, or those needing custom builds.

FANS requires the following dependencies:

Dependency	Purpose
C++ Compiler	(GCC, Clang, etc.)	C++17 or newer
CMake	Build system	≥ 3.21
MPI	Parallel computing	(OpenMPI, MPICH, Intel MPI)
HDF5	Data I/O	with MPI support
FFTW3	FFT computations	with MPI support
Eigen3	Linear algebra	≥ 3.4
nlohmann-json	JSON parsing	≥ 3.11
spdlog	Logging	≥ 1.17

Installing dependencies

Using Pixi (Cross-platform - Easiest for source builds)

This uses the repository's pixi.toml to define the dev environment.

# Clone the repository
git clone https://github.com/DataAnalyticsEngineering/FANS.git
cd FANS
# Enter development environment (all dependencies pre-installed!)
pixi shell -e dev

Linux (Debian/Ubuntu)

We recommend installing the dependencies using apt:

apt-get install -y \
build-essential \
cmake \
git \
file \
libhdf5-dev \
libhdf5-openmpi-dev \
libopenmpi-dev \
libeigen3-dev \
libfftw3-dev \
libfftw3-mpi-dev \
nlohmann-json3-dev \
libspdlog-dev

macOS

We recommend installing the dependencies using brew:

brew install gnu-time cmake gcc@15
brew install open-mpi --build-from-source --cc=gcc-15
brew install hdf5-mpi --build-from-source --cc=gcc-15
brew install fftw eigen nlohmann-json spdlog
# Set environment variablesexport CC=gcc-15 CXX=g++-15 MPICC=mpicc MPICXX=mpicxx

Using Spack (HPC environments)

Spack is a flexible package manager for building and managing software stacks in high-performance computing environments. Install Spack by following these installation instructions. Once Spack is set up, install the required dependencies:

spack install cmake
spack install mpi
spack install hdf5+cxx+mpi
spack install eigen
spack install fftw+mpi
spack install nlohmann-json
spack install spdlog
# Load dependencies
spack load cmake mpi hdf5 eigen fftw nlohmann-json spdlog

Additionally, optimized FFTW implementations can be used depending on your system's architecture:

• AMD systems: spack install amdfftw+mpi
• Cray systems: spack install cray-fftw+mpi
• Fujitsu systems: spack install fujitsu-fftw+mpi

Docker images

Pre-configured Docker images are available for containerized deployments. See docker/README.md for further details.

Building FANS

# Clone the repository
git clone https://github.com/DataAnalyticsEngineering/FANS.git
cd FANS
# Create build directory
mkdir build &&cd build
# Configure (basic)
cmake ..
# Build
cmake --build . -j
# Run tests with 8 mpi processescd ../test
./run_tests.sh -n 8

Build options:

CMake Option	Description	Default
CMAKE_BUILD_TYPE	Build type: Debug, Release, RelWithDebInfo	NONE
CMAKE_INTERPROCEDURAL_OPTIMIZATION	Enable link-time optimization (LTO)	ON (if supported)
FANS_BUILD_STATIC	Build static library	OFF
CMAKE_INSTALL_PREFIX	Installation directory	System default
FANS_ENABLE_SANITIZERS	Enable runtime sanitizers (AddressSanitizer and LeakSanitizer) for memory debugging	OFF

---

Python environment for the FANS dashboard

FANS includes FANS_Dashboard.ipynb, a comprehensive pipeline for post-processing, visualization, and analysis of simulation results. We recommend setting up a Python virtual environment via Pixi with all required Python dependencies in an isolated environment:

# Install and activate the dashboard environment
pixi shell -e dashboard

The dashboard environment includes:

• Python
• Jupyter notebook (ipykernel)
• MSUtils for FANS-specific utilities
• Testing tools (pytest)
• Code quality tools (pre-commit)

See FANS_Dashboard for further details.

---

Input file format

FANS requires a JSON input file specifying the problem parameters. Example input files can be found in the test/input_files directory. It is recommended to use these files as a reference to create your input file.

Microstructure definition

"microstructure": {
"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.
• datasetname: This is the path within the HDF5 file to the specific dataset that represents the microstructure.
• L: Microstructure length defines the physical dimensions of the microstructure in the $x$, $y$, and $z$ directions.

Problem type and material model

"problem_type": "mechanical",
"strain_type": "small",
"materials": [
{
"phases": [0],
"matmodel": "PseudoPlasticLinearHardening",
"material_properties": {
"bulk_modulus": [62.5000],
"shear_modulus": [28.8462],
"yield_stress": [0.1],
"hardening_parameter": [0.0]
}
},
{
"phases": [1],
"matmodel": "LinearElasticIsotropic",
"material_properties": {
"bulk_modulus": [222.222],
"shear_modulus": [166.6667]
}
}
]

• problem_type: This defines the type of physical problem you are solving. Options include thermal problems and mechanical problems.
• strain_type: This indicates whether the problem is formulated using infinitesimal (small) strain or finite (large) strain theory.
• materials: An array of material groups, where each group assigns one or more phases to a specific material model. Each material group contains:

  • phases: An array of phase IDs (material labels) from the microstructure that use this material model.

  • matmodel: The constitutive model for this material group. Available models 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.

    • SaintVenantKirchhoff for the hyperelastic Saint Venant-Kirchhoff material model.

    • CompressibleNeoHookean for the compressible Neo-Hookean material model.

    • FiniteStrainJ2Plasticity for rate-independent finite-strain J2 plasticity with linear isotropic hardening.

  • material_properties: Material parameters specific to the chosen model. Properties are defined as arrays, where each element corresponds to one of the phases listed in the phases array.

Solver settings

"FE_type": "HEX8",
"method": "cg",
"error_parameters":{
"measure": "Linfinity",
"type": "absolute",
"tolerance": 1e-10
},
"n_it": 100,

• FE_type: This specifies the type of finite element to be used. Common options include:
  • HEX8: Standard trilinear hexahedral elements with full integration (8 Gauss points). Suitable for most problems but may exhibit volumetric locking for nearly incompressible materials (Poisson's ratio ~ 0.5).
  • BBAR: B-bar elements with selective reduced integration to mitigate volumetric locking. Recommended for materials with high Poisson's ratios (0.4 to 0.5).
  • HEX8R: Reduced integration elements with a single Gauss point at the element center. Use with caution—these may produce less accurate field results and can cause local material issues such as negative Jacobian ($J < 0$), leading to nonphysical solutions (hourglassing).
• method: This indicates the numerical method to be used for solving the system of equations. cg stands for the Conjugate Gradient method, and fp stands for the Fixed Point method.
• error_parameters: This section defines the error parameters for the solver. Error control is applied to the finite element nodal residual of the problem.
  • measure: Specifies the norm used to measure the error. Options include Linfinity, L1, or L2.
  • type: Defines the type of error measurement. Options are absolute or relative.
  • tolerance: Sets the tolerance level for the solver, defining the convergence criterion based on the chosen error measure. The solver iterates until the solution meets this tolerance.
• n_it: Specifies the maximum number of iterations allowed for the FANS solver.

Macroscale loading conditions

"macroscale_loading": [
[
[0.004, -0.002, -0.002, 0, 0, 0],
[0.008, -0.004, -0.004, 0, 0, 0],
[0.012, -0.006, -0.006, 0, 0, 0],
[0.016, -0.008, -0.008, 0, 0, 0],
],
[
[0, 0, 0, 0.002, 0, 0],
[0, 0, 0, 0.004, 0, 0],
[0, 0, 0, 0.006, 0, 0],
[0, 0, 0, 0.008, 0, 0],
]
],

• macroscale_loading: This defines the external loading applied to the microstructure. It is an array of arrays, where each sub-array represents a load path applied to the system. The format of the load path depends on the problem type:
  • For thermal problems, the array typically has 3 components, representing the macroscale temperature gradients in the $x$, $y$, and $z$ directions.
  • For small strain mechanical problems, the array must have 6 components, corresponding to the macroscale strain tensor in Mandel notation: $[\varepsilon_{11},\ \varepsilon_{22},\ \varepsilon_{33},\ \sqrt{2},\varepsilon_{12},\ \sqrt{2},\varepsilon_{13},\ \sqrt{2},\varepsilon_{23}]$.
  • For large strain mechanical problems, the array must have 9 components, corresponding to the macroscale deformation gradient tensor: $[F_{11},\ F_{12},\ F_{13},\ F_{21},\ F_{22},\ F_{23},\ F_{31},\ F_{32},\ F_{33}]$.

In the case of path/time-dependent loading, as shown, for example, 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:

"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

"results": ["stress_average", "strain_average", "absolute_error", "phase_stress_average", "phase_strain_average",
"microstructure", "displacement", "displacement_fluctuation", "stress", "strain"]

• results: This array lists the quantities that should be stored in the results HDF5 file during the simulation. Each string in the array corresponds to a specific result:

  • stress_average and strain_average: Volume averaged- homogenized stress and strain over the entire microstructure.
  • absolute_error: The L-infinity error of the 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 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 (element-averaged) at each voxel in the microstructure.
  • stress_gp and strain_gp: The stress and strain fields at all Gauss points within each element.

• Additional material model-specific results can be included depending on the problem type and material model. For plasticity models, internal variables such as plastic_strain, isotropic_hardening_variable, etc., are available. Append _gp to these field names (e.g., plastic_strain_gp) to output data at all Gauss points.

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 of the Stuttgart Center for Simulation Science (SimTech).

Contributors

• Sanath Keshav
• Florian Rieg
• Ishaan Desai
• Moritz Sigg
• Claudius Haag
• Felix Fritzen