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) 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 bda5ba6..f36adec 100644 --- a/README.md +++ b/README.md @@ -1,168 +1,227 @@ -# 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. +

+ Example Image +

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

-## Table of contents +# Fourier-Accelerated Nodal Solver (FANS) -- [Dependencies](#dependencies) -- [Building](#building) -- [Installing](#installing) -- [Input File Format](#input-file-format) +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. -## Dependencies +## Table of Contents -FANS has the following dependencies: +- [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) + - [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) -- 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) +## Quick start -### Installing dependencies +**Want to get started immediately?** + +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. + +Use [Pixi](https://pixi.sh) (recommended): + +```bash +# Install Pixi (if not already installed) +curl -fsSL https://pixi.sh/install.sh | sh -- On Debian-based systems, we recommend installing the dependencies using `apt`, +# Install FANS via Pixi +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: +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 +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. - export CC=gcc-15 CXX=g++-15 MPICC=mpicc MPICXX=mpicxx - ``` +--- -### Setting up a Python environment +## Build from source -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: +**Recommended for:** Developers, contributors, HPC users, or those needing custom builds. -```bash -# Install Pixi if not done already, -curl -fsSL https://pixi.sh/install.sh | sh +FANS requires the following dependencies: -# Install FANS using pixi -pixi global install FANS +| 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 | -# Create and activate the environment -pixi shell -e dashboard +### Installing 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 +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`: -1. **Install Spack** by following these [installation instructions](https://spack.readthedocs.io/en/latest/getting_started.html). +```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 +``` -2. **Install Dependencies**: Once Spack is set up, install the required dependencies: +
- ```bash - spack install cmake - spack install mpi - spack install hdf5 +cxx +mpi - spack install eigen - spack install fftw +mpi - spack install nlohmann-json - ``` +
+macOS - 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). +We recommend installing the dependencies using [`brew`](https://brew.sh): -3. **Load Dependencies** Once dependencies are installed, load them before building: +```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 - ```bash - spack load cmake mpi hdf5 eigen fftw nlohmann-json - ``` +# Set environment variables +export CC=gcc-15 CXX=g++-15 MPICC=mpicc MPICXX=mpicxx +``` -## Building +
-1. Clone the repository: +
+ Using Spack (HPC environments) - ```bash - git clone https://github.com/DataAnalyticsEngineering/FANS.git - cd FANS - ``` +[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: -2. Configure the build using CMake: +```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 +``` + +Additionally, optimized FFTW implementations can be used depending on your system's architecture: - ```bash - mkdir build - cd build - cmake .. - ``` +- AMD systems: `spack install amdfftw+mpi` +- Cray systems: `spack install cray-fftw+mpi` +- Fujitsu systems: `spack install fujitsu-fftw+mpi` -3. Compile: +
- ```bash - cmake --build . -j - ``` +
+Docker images -The compilation symlinks the generated `FANS` binary into the `test/` directory for convenience. +Pre-configured Docker images are available for containerized deployments. See [`docker/README.md`](docker/README.md) for further details. -### Configuring a build +
-The following CMake configuration options exist: +### Building FANS -- `CMAKE_BUILD_TYPE`: Sets the build type. Common values are Debug, Release, RelWithDebInfo, and MinSizeRel. - - Default: NONE +```bash +# Clone the repository +git clone https://github.com/DataAnalyticsEngineering/FANS.git +cd FANS -- `FANS_BUILD_STATIC`: Build static library instead of shared library. - - Default: OFF +# Create build directory +mkdir build && cd build -- `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. +# Configure (basic) +cmake .. -## Installing +# Build +cmake --build . -j -Install FANS (system-wide) using the following options: +# Run tests with 8 mpi processes +cd ../test +./run_tests.sh -n 8 +``` -1. Using CMake (sudo required if --prefix is omitted): +**Build options:** - ```bash - cmake --install . [--prefix ] - ``` +| 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` | -### 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) +## 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](https://pixi.sh/) with all required Python dependencies in an isolated environment: ```bash -conda install conda-forge::fans +# Install and activate the dashboard environment +pixi shell -e dashboard ``` -exposing the executable `FANS`. +The `dashboard` environment includes: + +- Python +- 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 +## 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": { @@ -176,7 +235,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", @@ -205,7 +264,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", @@ -221,7 +280,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`. @@ -229,7 +288,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": [ @@ -249,9 +308,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 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. @@ -268,7 +327,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",