From 9101df29932e5e6a4ebf57fef85c8ed77ef202cf Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Fri, 31 Oct 2025 10:46:13 +0100 Subject: [PATCH 01/13] add some cool badges --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index bda5ba6..560f0e2 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,11 @@ +[![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) +[![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://prefix.dev/channels/conda-forge/packages/fans) +![Last commit](https://img.shields.io/github/last-commit/DataAnalyticsEngineering/FANS) +![License](https://img.shields.io/github/license/DataAnalyticsEngineering/FANS) +![Stars](https://img.shields.io/github/stars/DataAnalyticsEngineering/FANS?style=social) + # Fourier-Accelerated Nodal Solvers (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. @@ -145,10 +153,6 @@ Install FANS (system-wide) using the following options: ### 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/fans](https://anaconda.org/conda-forge/fans). No dependencies have to be manually installed for it to work. It can be installed via From d59a196ed08531b83df22617f3fd6ff755819e1d Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Fri, 31 Oct 2025 14:10:08 +0100 Subject: [PATCH 02/13] comprehensive readme revamp --- FANS_Dashboard/FANS_Dashboard.ipynb | 22 +-- README.md | 243 ++++++++++++++++------------ 2 files changed, 145 insertions(+), 120 deletions(-) diff --git a/FANS_Dashboard/FANS_Dashboard.ipynb b/FANS_Dashboard/FANS_Dashboard.ipynb index 6a77c7a..18e4471 100644 --- a/FANS_Dashboard/FANS_Dashboard.ipynb +++ b/FANS_Dashboard/FANS_Dashboard.ipynb @@ -20,22 +20,6 @@ "9. [Summary](#summary)" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Prerequisites\n", - "To start using the FANS Dashboard, ensure that the necessary Python packages and modules are installed. The required imports in your Jupyter Notebook should include:\n", - "- `numpy`\n", - "- `h5py`\n", - "- `plotly`\n", - "- `collections`\n", - "- `argparse`\n", - "- `lxml`\n", - "- `re`\n", - "- `nbformat`" - ] - }, { "cell_type": "markdown", "metadata": {}, @@ -98,7 +82,7 @@ "outputs": [], "source": [ "# Example usage\n", - "file_path = '../test/test_results.h5'\n", + "file_path = '../test/output/test_J2Plasticity.h5'\n", "\n", "# Extract hierarchy information from the file\n", "hierarchy = identify_hierarchy(file_path)\n", @@ -323,7 +307,7 @@ ], "metadata": { "kernelspec": { - "display_name": "default", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -337,7 +321,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.13.3" + "version": "3.13.7" } }, "nbformat": 4, diff --git a/README.md b/README.md index 560f0e2..9532cd2 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ -[![Anaconda-Server Badge](https://anaconda.org/conda-forge/fans/badges/version.svg)](https://anaconda.org/conda-forge/fans) +[![GitHub Release](https://img.shields.io/github/v/release/DataAnalyticsEngineering/FANS?label=Release&color=004191)](https://prefix.dev/channels/conda-forge/packages/fans) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/fans/badges/platforms.svg)](https://anaconda.org/conda-forge/fans) +[![Build and test pixi-build](https://github.com/DataAnalyticsEngineering/FANS/workflows/Build%20and%20test%20pixi-build/badge.svg)](https://github.com/DataAnalyticsEngineering/FANS/actions) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/fans/badges/downloads.svg)](https://anaconda.org/conda-forge/fans) [![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://prefix.dev/channels/conda-forge/packages/fans) ![Last commit](https://img.shields.io/github/last-commit/DataAnalyticsEngineering/FANS) -![License](https://img.shields.io/github/license/DataAnalyticsEngineering/FANS) -![Stars](https://img.shields.io/github/stars/DataAnalyticsEngineering/FANS?style=social) +[![License](https://img.shields.io/github/license/DataAnalyticsEngineering/FANS)](https://github.com/DataAnalyticsEngineering/FANS/blob/main/LICENSE) +[![Stars](https://img.shields.io/github/stars/DataAnalyticsEngineering/FANS?style=social)](https://github.com/DataAnalyticsEngineering/FANS/stargazers) # Fourier-Accelerated Nodal Solvers (FANS) @@ -14,153 +15,193 @@ Fourier-Accelerated Nodal Solver (FANS) is an FFT-based homogenization solver fo Example Image

-## Table of contents +## Table of Contents -- [Dependencies](#dependencies) -- [Building](#building) -- [Installing](#installing) +- [Quick start](#quick-start) +- [Build from Source](#build-from-source) + - [Installing dependencies](#installing-dependencies) + - [Building FANS](#building-fans) +- [Python Environment for the FANS Dashboard](#python-environment-for-the-fans-dashboard) - [Input File Format](#input-file-format) -## Dependencies +## Quick Start -FANS has the following dependencies: +**Want to get started immediately?** Use [Pixi](https://pixi.sh): -- 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 -- Eigen3 -- FFTW3 with MPI support -- nlohmann-json (for JSON input parsing) +```bash +# Install Pixi if not done already +curl -fsSL https://pixi.sh/install.sh | bash +``` -### Installing dependencies +Install and Use FANS: -- On Debian-based systems, we recommend installing the dependencies using `apt`, +```bash +# Install FANS +pixi global install fans - ```bash - apt-get install \ - libhdf5-dev \ - libhdf5-openmpi-dev \ - libopenmpi-dev \ - libeigen3-dev \ - libfftw3-dev \ - libfftw3-mpi-dev \ - nlohmann-json3-dev - ``` +# Verify installation +FANS --version +``` -- On macOS, you can obtain the dependencies using `brew` and set the environment variables: +FANS is available as a precompiled binary on [conda-forge](https://anaconda.org/conda-forge/fans). That's it! No dependencies to install, no compilation needed. πŸš€ - ```zsh - 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 +--- - export CC=gcc-15 CXX=g++-15 MPICC=mpicc MPICXX=mpicxx - ``` +## Build from Source -### Setting up a Python environment +**Best for:** Developers, contributors, HPC users, or those needing custom builds. -Also, we recommend setting 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: +FANS requires the following dependencies: -```bash -# Install Pixi if not done already, -curl -fsSL https://pixi.sh/install.sh | sh +| 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 | -# Install FANS using pixi -pixi global install FANS +### Installing Dependencies -# Create and activate the environment -pixi shell -e dashboard +
+ + Using Pixi (Cross-platform - Easiest for source builds) + +```bash +# Clone the repository +git clone https://github.com/DataAnalyticsEngineering/FANS.git +cd FANS + +# Enter development environment (all dependencies pre-installed!) +pixi shell -e dev ``` -We also provide a set of Docker images. For further information, please refer to the [Docker README](docker/README.md). +
-### Installing dependencies using Spack +
+Linux (Debian/Ubuntu) -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. +We recommend installing the dependencies using `apt`: + +```bash +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 +``` -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, install the required dependencies: +
+macOS - ```bash - spack install cmake - spack install mpi - spack install hdf5 +cxx +mpi - spack install eigen - spack install fftw +mpi - spack install nlohmann-json - ``` +We recommend installing the dependencies using [`brew`](https://brew.sh): - 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). +```bash +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 -3. **Load Dependencies** Once dependencies are installed, load them before building: +# Set environment variables +export CC=gcc-15 CXX=g++-15 MPICC=mpicc MPICXX=mpicxx +``` - ```bash - spack load cmake mpi hdf5 eigen fftw nlohmann-json - ``` +
-## Building +
+ Using Spack (HPC environments) -1. Clone the repository: +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. +**Install Spack** by following these [installation instructions](https://spack.readthedocs.io/en/latest/getting_started.html). Once Spack is set up, install the required dependencies: - ```bash - git clone https://github.com/DataAnalyticsEngineering/FANS.git - cd FANS - ``` +```bash +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 +``` -2. Configure the build using CMake: +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` - ```bash - mkdir build - cd build - cmake .. - ``` +
-3. Compile: +
+Docker images - ```bash - cmake --build . -j - ``` +Pre-configured Docker images are available for containerized deployments. See [`docker/README.md`](docker/README.md) for further details. -The compilation symlinks the generated `FANS` binary into the `test/` directory for convenience. +
-### Configuring a build +### Building FANS -The following CMake configuration options exist: +```bash +# Clone the repository +git clone https://github.com/DataAnalyticsEngineering/FANS.git +cd FANS -- `CMAKE_BUILD_TYPE`: Sets the build type. Common values are Debug, Release, RelWithDebInfo, and MinSizeRel. - - Default: NONE +# Create build directory +mkdir build && cd build -- `FANS_BUILD_STATIC`: Build static library instead of shared library. - - Default: OFF +# Configure (basic) +cmake .. -- `CMAKE_INTERPROCEDURAL_OPTIMIZATION`: Enable inter-procedural optimization (IPO) for all targets. - - Default: ON (if supported) - - 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. +# Build +cmake --build . -j -## Installing +# Run tests with 8 mpi processes +cd ../test +./run_tests.sh -n 8 +``` -Install FANS (system-wide) using the following options: +**Build Options:** -1. Using CMake (sudo required if --prefix is omitted): +| 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 | - ```bash - cmake --install . [--prefix ] - ``` +--- -### Install using Conda +## Python Environment for the FANS Dashboard -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 +FANS includes [`FANS_Dashboard.ipynb`](FANS_Dashboard/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: ```bash -conda install conda-forge::fans +# Install the dashboard environment +pixi shell -e dashboard ``` -exposing the executable `FANS`. +The `dashboard` environment includes: +- Python β‰₯ 3.14 +- Jupyter notebook (`ipykernel`) +- [MSUtils](https://github.com/DataAnalyticsEngineering/MSUtils) for FANS-specific utilities +- Testing tools (`pytest`) +- Code quality tools (`pre-commit`) + +See [`FANS_Dashboard`](FANS_Dashboard/) for further details. + +--- ## Input File Format From 627c615b37df82e5ca7d542858ad03f227fa56b9 Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Fri, 31 Oct 2025 14:23:45 +0100 Subject: [PATCH 03/13] few white spaces --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9532cd2..1b5f5b8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +

+ Example Image +

+ [![GitHub Release](https://img.shields.io/github/v/release/DataAnalyticsEngineering/FANS?label=Release&color=004191)](https://prefix.dev/channels/conda-forge/packages/fans) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/fans/badges/platforms.svg)](https://anaconda.org/conda-forge/fans) [![Build and test pixi-build](https://github.com/DataAnalyticsEngineering/FANS/workflows/Build%20and%20test%20pixi-build/badge.svg)](https://github.com/DataAnalyticsEngineering/FANS/actions) @@ -11,10 +15,6 @@ 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. -

- Example Image -

- ## Table of Contents - [Quick start](#quick-start) @@ -138,6 +138,7 @@ 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` @@ -193,6 +194,7 @@ pixi shell -e dashboard ``` The `dashboard` environment includes: + - Python β‰₯ 3.14 - Jupyter notebook (`ipykernel`) - [MSUtils](https://github.com/DataAnalyticsEngineering/MSUtils) for FANS-specific utilities From d31ed7d17abf06a3f9c1e7db42088913d31ef370 Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Fri, 31 Oct 2025 14:26:42 +0100 Subject: [PATCH 04/13] set MD041 to false in lint check --- .github/workflows/run-checks.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/run-checks.yml b/.github/workflows/run-checks.yml index 9e239ed..67c4f93 100644 --- a/.github/workflows/run-checks.yml +++ b/.github/workflows/run-checks.yml @@ -20,7 +20,8 @@ jobs: { "MD013": false, "MD033": false, - "MD034": false + "MD034": false, + "MD041": false } EOF - name: Lint markdown files (markdownlint) From 4a22258327c79132e8b6ec445d9fa61348e2efc9 Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Fri, 31 Oct 2025 15:30:10 +0100 Subject: [PATCH 05/13] some changes form review --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1b5f5b8..d6879e9 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Fourier-Accelerated Nodal Solver (FANS) is an FFT-based homogenization solver fo curl -fsSL https://pixi.sh/install.sh | bash ``` -Install and Use FANS: +Install and use FANS: ```bash # Install FANS @@ -49,7 +49,7 @@ FANS is available as a precompiled binary on [conda-forge](https://anaconda.org/ ## Build from Source -**Best for:** Developers, contributors, HPC users, or those needing custom builds. +**Recommended for:** Developers, contributors, HPC users, or those needing custom builds. FANS requires the following dependencies: @@ -189,13 +189,13 @@ cd ../test FANS includes [`FANS_Dashboard.ipynb`](FANS_Dashboard/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: ```bash -# Install the dashboard environment +# Install and activate the dashboard environment pixi shell -e dashboard ``` The `dashboard` environment includes: -- Python β‰₯ 3.14 +- Python - Jupyter notebook (`ipykernel`) - [MSUtils](https://github.com/DataAnalyticsEngineering/MSUtils) for FANS-specific utilities - Testing tools (`pytest`) From 1fbd581e1d4721d9b7ea323004f07adb35a67971 Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Fri, 31 Oct 2025 15:31:53 +0100 Subject: [PATCH 06/13] pixi install command sh --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d6879e9..c433fda 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Fourier-Accelerated Nodal Solver (FANS) is an FFT-based homogenization solver fo ```bash # Install Pixi if not done already -curl -fsSL https://pixi.sh/install.sh | bash +curl -fsSL https://pixi.sh/install.sh | sh ``` Install and use FANS: From 1435f2e32bdf69f78ffff05e4d2a3e042f0220d8 Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Fri, 31 Oct 2025 15:41:55 +0100 Subject: [PATCH 07/13] add FANS_LIBRARY_FOR_MICRO_MANAGER option --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index c433fda..4a14eee 100644 --- a/README.md +++ b/README.md @@ -181,6 +181,7 @@ cd ../test | `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` | --- From 1677a973c76aa190b8829c05e6c30a0b4d7ac16c Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Fri, 31 Oct 2025 16:11:45 +0100 Subject: [PATCH 08/13] make logo a bit smaller --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4a14eee..64e2ac8 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- Example Image + Example Image

[![GitHub Release](https://img.shields.io/github/v/release/DataAnalyticsEngineering/FANS?label=Release&color=004191)](https://prefix.dev/channels/conda-forge/packages/fans) From 4d02496857a650f523686905252163ba1140e996 Mon Sep 17 00:00:00 2001 From: Sanath Keshav Date: Fri, 31 Oct 2025 16:50:18 +0100 Subject: [PATCH 09/13] Update README.md Co-authored-by: Claudius Haag <62202036+claudiushaag@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 64e2ac8..c77b072 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ [![License](https://img.shields.io/github/license/DataAnalyticsEngineering/FANS)](https://github.com/DataAnalyticsEngineering/FANS/blob/main/LICENSE) [![Stars](https://img.shields.io/github/stars/DataAnalyticsEngineering/FANS?style=social)](https://github.com/DataAnalyticsEngineering/FANS/stargazers) -# Fourier-Accelerated Nodal Solvers (FANS) +# 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. From 73bd6aa6e296e3e3b9a2d64afd101141aab04010 Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Sat, 1 Nov 2025 14:11:37 +0100 Subject: [PATCH 10/13] minor changes --- README.md | 44 +++++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index c77b072..9c4d393 100644 --- a/README.md +++ b/README.md @@ -18,13 +18,18 @@ Fourier-Accelerated Nodal Solver (FANS) is an FFT-based homogenization solver fo ## Table of Contents - [Quick start](#quick-start) -- [Build from Source](#build-from-source) +- [Build from source](#build-from-source) - [Installing dependencies](#installing-dependencies) - [Building FANS](#building-fans) -- [Python Environment for the FANS Dashboard](#python-environment-for-the-fans-dashboard) -- [Input File Format](#input-file-format) +- [Python environment for the FANS dashboard](#python-environment-for-the-fans-dashboard) +- [Input file format](#input-file-format) + - [Microstructure definition](#microstructure-definition) + - [Problem type and material model](#problem-type-and-material-model) + - [Solver settings](#solver-settings) + - [Macroscale loading conditions](#macroscale-loading-conditions) + - [Results specification](#results-specification) -## Quick Start +## Quick start πŸš€ **Want to get started immediately?** Use [Pixi](https://pixi.sh): @@ -47,7 +52,7 @@ FANS is available as a precompiled binary on [conda-forge](https://anaconda.org/ --- -## Build from Source +## Build from source **Recommended for:** Developers, contributors, HPC users, or those needing custom builds. @@ -63,7 +68,7 @@ FANS requires the following dependencies: | **Eigen3** | Linear algebra | β‰₯ 3.4 | | **nlohmann-json** | JSON parsing | β‰₯ 3.11 | -### Installing Dependencies +### Installing dependencies
@@ -173,7 +178,7 @@ cd ../test ./run_tests.sh -n 8 ``` -**Build Options:** +**Build options:** | CMake Option | Description | Default | |--------------|-------------|---------| @@ -182,12 +187,13 @@ cd ../test | `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 +## Python environment for the FANS dashboard -FANS includes [`FANS_Dashboard.ipynb`](FANS_Dashboard/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: +FANS includes [`FANS_Dashboard.ipynb`](FANS_Dashboard/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](https://pixi.sh/) with all required Python dependencies in an isolated environment: ```bash # Install and activate the dashboard environment @@ -206,11 +212,11 @@ See [`FANS_Dashboard`](FANS_Dashboard/) for further details. --- -## Input File Format +## Input file format 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 input file. -### Microstructure Definition +### Microstructure definition ```json "microstructure": { @@ -224,7 +230,7 @@ FANS requires a JSON input file specifying the problem parameters. Example input - `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 and material model ```json "problem_type": "mechanical", @@ -253,7 +259,7 @@ FANS requires a JSON input file specifying the problem parameters. Example input - `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 +### Solver settings ```json "FE_type": "HEX8", @@ -269,7 +275,7 @@ FANS requires a JSON input file specifying the problem parameters. Example input - `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 as they may lead to hourglassing and less accurate results. + - `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`. @@ -277,7 +283,7 @@ FANS requires a JSON input file specifying the problem parameters. Example input - `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 conditions ```json "macroscale_loading": [ @@ -297,9 +303,9 @@ 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 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 temperature gradients in the $x$, $y$, and $z$ directions. - - For `small` strain `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}]$). - - For `large` strain `mechanical` problems, the array must have 9 components, corresponding to the deformation gradient tensor components (e.g., $[F_{11}, F_{12}, F_{13}, F_{21}, F_{22}, F_{23}, F_{31}, F_{32}, F_{33}]$). + - 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 components of the macroscale strain tensor in Mandel notation (e.g., $[\overline{\varepsilon}_{11}, \overline{\varepsilon}_{22}, \overline{\varepsilon}_{33}, \sqrt{2}\,\overline{\varepsilon}_{12}, \sqrt{2}\,\overline{\varepsilon}_{13}, \sqrt{2}\,\overline{\varepsilon}_{23}]$). + - For `large` strain `mechanical` problems, the array must have 9 components, corresponding to the macroscale deformation gradient tensor components (e.g., $[\overline{F}_{11}, \overline{F}_{12}, \overline{F}_{13}, \overline{F}_{21}, \overline{F}_{22}, \overline{F}_{23}, \overline{F}_{31}, \overline{F}_{32}, \overline{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. @@ -316,7 +322,7 @@ FANS also supports mixed boundary conditions, where some components can be strai }] ``` -### Results Specification +### Results specification ```json "results": ["stress_average", "strain_average", "absolute_error", "phase_stress_average", "phase_strain_average", From 051d26afb2eaa13e3b1f73642c6ad3777fc600b8 Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Sat, 1 Nov 2025 14:16:15 +0100 Subject: [PATCH 11/13] fix link --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9c4d393..52e7fcc 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ Fourier-Accelerated Nodal Solver (FANS) is an FFT-based homogenization solver fo - [Macroscale loading conditions](#macroscale-loading-conditions) - [Results specification](#results-specification) -## Quick start πŸš€ +## Quick start **Want to get started immediately?** Use [Pixi](https://pixi.sh): @@ -48,7 +48,7 @@ pixi global install fans FANS --version ``` -FANS is available as a precompiled binary on [conda-forge](https://anaconda.org/conda-forge/fans). That's it! No dependencies to install, no compilation needed. πŸš€ +FANS is available as a precompiled binary on [conda-forge](https://anaconda.org/conda-forge/fans). That's it! No dependencies to install, no compilation needed πŸš€ --- From f8b58e71f6d6b950aeaf829e52b17afddf180bd4 Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Sun, 2 Nov 2025 09:44:26 +0100 Subject: [PATCH 12/13] center the badges --- README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 52e7fcc..22062b9 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,16 @@ Example Image

-[![GitHub Release](https://img.shields.io/github/v/release/DataAnalyticsEngineering/FANS?label=Release&color=004191)](https://prefix.dev/channels/conda-forge/packages/fans) -[![Anaconda-Server Badge](https://anaconda.org/conda-forge/fans/badges/platforms.svg)](https://anaconda.org/conda-forge/fans) -[![Build and test pixi-build](https://github.com/DataAnalyticsEngineering/FANS/workflows/Build%20and%20test%20pixi-build/badge.svg)](https://github.com/DataAnalyticsEngineering/FANS/actions) -[![Anaconda-Server Badge](https://anaconda.org/conda-forge/fans/badges/downloads.svg)](https://anaconda.org/conda-forge/fans) -[![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://prefix.dev/channels/conda-forge/packages/fans) -![Last commit](https://img.shields.io/github/last-commit/DataAnalyticsEngineering/FANS) -[![License](https://img.shields.io/github/license/DataAnalyticsEngineering/FANS)](https://github.com/DataAnalyticsEngineering/FANS/blob/main/LICENSE) -[![Stars](https://img.shields.io/github/stars/DataAnalyticsEngineering/FANS?style=social)](https://github.com/DataAnalyticsEngineering/FANS/stargazers) +

+ GitHub Release + Anaconda-Server Badge + Build and test pixi-build + Anaconda-Server Badge + Pixi Badge + Last commit + License + Stars +

# Fourier-Accelerated Nodal Solver (FANS) From c8837da8aa3b5ae1018eaf79e294f8221bc9c49c Mon Sep 17 00:00:00 2001 From: sanathkeshav Date: Mon, 3 Nov 2025 13:41:06 +0100 Subject: [PATCH 13/13] small changes --- README.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 22062b9..f36adec 100644 --- a/README.md +++ b/README.md @@ -33,24 +33,26 @@ Fourier-Accelerated Nodal Solver (FANS) is an FFT-based homogenization solver fo ## Quick start -**Want to get started immediately?** Use [Pixi](https://pixi.sh): +**Want to get started immediately?** -```bash -# Install Pixi if not done already -curl -fsSL https://pixi.sh/install.sh | sh -``` +FANS is available as a precompiled binary on [conda-forge](https://anaconda.org/conda-forge/fans). Package managers such as [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html), [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html), [micromamba](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html), and [Pixi](https://pixi.sh) can also be used to install FANS from the conda-forge channel. -Install and use FANS: +Use [Pixi](https://pixi.sh) (recommended): ```bash -# Install FANS +# 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 ``` -FANS is available as a precompiled binary on [conda-forge](https://anaconda.org/conda-forge/fans). That's it! No dependencies to install, no compilation needed πŸš€ +That's it! No dependencies to install, no compilation needed πŸš€ + +To get started immediately, we include ready to use example [input files](test/input_files/) and [microstructures](test/microstructures/) you can use as templates to create your own. --- @@ -76,6 +78,8 @@ FANS requires the following dependencies: Using Pixi (Cross-platform - Easiest for source builds) +This uses the repository's [pixi.toml](pixi.toml) to define the `dev` environment. + ```bash # Clone the repository git clone https://github.com/DataAnalyticsEngineering/FANS.git @@ -129,8 +133,7 @@ export CC=gcc-15 CXX=g++-15 MPICC=mpicc MPICXX=mpicxx
Using Spack (HPC environments) -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. -**Install Spack** by following these [installation instructions](https://spack.readthedocs.io/en/latest/getting_started.html). Once Spack is set up, install the required dependencies: +[Spack](https://spack.readthedocs.io/en/latest/) is a flexible package manager for building and managing software stacks in high-performance computing environments. Install Spack by following these [installation instructions](https://spack.readthedocs.io/en/latest/getting_started.html). Once Spack is set up, install the required dependencies: ```bash spack install cmake @@ -306,8 +309,8 @@ 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 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 components of the macroscale strain tensor in Mandel notation (e.g., $[\overline{\varepsilon}_{11}, \overline{\varepsilon}_{22}, \overline{\varepsilon}_{33}, \sqrt{2}\,\overline{\varepsilon}_{12}, \sqrt{2}\,\overline{\varepsilon}_{13}, \sqrt{2}\,\overline{\varepsilon}_{23}]$). - - For `large` strain `mechanical` problems, the array must have 9 components, corresponding to the macroscale deformation gradient tensor components (e.g., $[\overline{F}_{11}, \overline{F}_{12}, \overline{F}_{13}, \overline{F}_{21}, \overline{F}_{22}, \overline{F}_{23}, \overline{F}_{31}, \overline{F}_{32}, \overline{F}_{33}]$). + - 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.