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
• 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

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

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

# Set environment variables
export 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

# Load dependencies
spack load cmake mpi hdf5 eigen fftw nlohmann-json

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 processes
cd ../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_LIBRARY_FOR_MICRO_MANAGER	Build Python bindings using Pybind11 (needed)	OFF
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",
"matmodel": "LinearElasticIsotropic",
"strain_type": "small",
"material_properties": {
                         "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 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.

• strain_type: This indicates whether the problem is formulated using infinitesimal (small) strain or finite (large) strain theory.

• 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

"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 at each voxel in the microstructure.

• Additional material model-specific results can be included depending on the problem type and material model.

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