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.

Quick start
Build from source
- Installing dependencies
- Building FANS
Python environment for the FANS dashboard
Input file format

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

<details> <summary> Using Pixi (Cross-platform - Easiest for source builds)</summary>

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

</details> <details> <summary>Linux (Debian/Ubuntu)</summary>

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

</details> <details> <summary>macOS</summary>

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

</details> <details> <summary> Using Spack (HPC environments)</summary>

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

</details> <details> <summary>Docker images</summary>

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

</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",
"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

FANS

Install / Use

README