FerroX

FerroX is a massively parallel, 3D phase-field simulation framework for modeling ferroelectric materials based scalable logic devices. We self-consistently solve the time-dependent Ginzburg Landau (TDGL) equation for ferroelectric polarization, Poisson’s equation for electric potential, and semiconductor charge equation for carrier densities in semiconductor regions. The algorithm is implemented using Exascale Computing Project software framework, AMReX, which provides effective scalability on manycore and GPU-based supercomputing architectures. The code can be used for simulations of ferroelectric domain-wall induced negative capacitance (NC) effect in Metal-Ferroelectric-Insulator-Metal (MFIM) and Metal-Ferroelectric-Insulator-Semiconductor-Metal (MFISM) devices.

Our community is here to help. Please report installation problems in case you should get stuck.

Installation

Quick Start

Prerequisites: Git, C++ compiler, CUDA toolkit (for GPU builds)

Build Commands:

git clone https://github.com/AMReX-Codes/amrex.git
git clone https://github.com/AMReX-Microelectronics/FerroX.git
cd FerroX/Exec && make -j 4

Detailed Installation Process

Prerequisites and Dependencies

FerroX requires a modern C++ compiler, Git version control, and optional dependencies like CUDA toolkit for GPU acceleration and SUNDIALS for advanced time integration. The AMReX library is required and can be obtained automatically through CMake or manually cloned.

Obtaining the Source Code

Download the AMReX repository at the same directory level as where you plan to install FerroX:

git clone https://github.com/AMReX-Codes/amrex.git
git clone https://github.com/AMReX-Microelectronics/FerroX.git

Understanding the Build System

FerroX supports two build systems: GNU Make for quick builds and CMake for advanced configuration. GNU Make is simpler but offers fewer options, while CMake provides comprehensive dependency management and cross-platform support.

Standard Build Process

Navigate to the FerroX/Exec directory and build using your preferred method:

GNU Make (GPU default):

cd FerroX/Exec
make -j 4

CMake (basic):

cd FerroX
cmake -S . -B build
cmake --build build -j 4

Build Verification

After successful compilation, verify the installation by running a test simulation from the Examples directory.

For detailed instructions on setting up and running FerroX simulations, see Run FerroX.

Advanced Build Options

Alternative Build Systems

GNU Make Options:

# CPU build
make -j 4 USE_CUDA=FALSE

# CPU build with SUNDIALS
make -j 4 USE_CUDA=FALSE USE_SUNDIALS=TRUE

For SUNDIALS support with GNU Make, first follow the SUNDIALS installation steps as described here.

CMake with External Dependencies:

# Use external AMReX installation
cmake -S . -B build \
  -DFerroX_amrex_internal=OFF \
  -DAMReX_DIR=/path/to/amrex/lib/cmake/AMReX

Performance Optimizations

GPU Acceleration:

cmake -S . -B build -DFerroX_COMPUTE=CUDA
cmake --build build -j 4

CPU Optimizations:

cmake -S . -B build \
  -DFerroX_COMPUTE=OMP \
  -DFerroX_SIMD=ON

Physics Module Configuration

Embedded Boundaries and Time-Dependent Features:

cmake -S . -B build \
  -DFerroX_EB=ON \
  -DFerroX_TIME_DEPENDENT=ON

SUNDIALS Integration:

For SUNDIALS library integration, first follow the SUNDIALS installation steps as described here.

cmake -S . -B build \
  -DFerroX_SUNDIALS=ON \
  -DFerroX_sundials_src=/path/to/sundials/source

Debug and Development Options

Debug Build with Verbose Output:

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DFerroX_PRINT_HIGH=ON \
  -DFerroX_PRINT_MEDIUM=ON

Core Configuration Options:

-DFerroX_COMPUTE=NOACC/OMP/CUDA/SYCL/HIP - Computing backend (default: OMP)
-DFerroX_PRECISION=SINGLE/DOUBLE - Floating point precision (default: DOUBLE)
-DFerroX_EB=ON/OFF - Embedded boundary support (default: OFF)
-DFerroX_TIME_DEPENDENT=ON/OFF - Time-dependent simulations (default: OFF)
-DFerroX_SUNDIALS=ON/OFF - SUNDIALS ODE solver support (default: OFF)
-DFerroX_MPI=ON/OFF - Multi-node support (default: ON)
-DFerroX_SIMD=ON/OFF - CPU SIMD acceleration (default: OFF)

Debug Print Options:

-DFerroX_PRINT_HIGH=ON/OFF - High level debug printing (default: OFF)
-DFerroX_PRINT_MEDIUM=ON/OFF - Medium level debug printing (default: OFF)
-DFerroX_PRINT_LOW=ON/OFF - Low level debug printing (default: OFF)
-DFerroX_PRINT_NAME=ON/OFF - Function name debug printing (default: OFF)

Platform-Specific Configurations

AMReX Source Management:

# Use local AMReX source
cmake -S . -B build -DFerroX_amrex_src=/path/to/amrex/source

# Use custom AMReX repository/branch
cmake -S . -B build \
  -DFerroX_amrex_repo=https://github.com/user/amrex.git \
  -DFerroX_amrex_branch=my_branch

# Test with specific AMReX pull request
cmake -S . -B build -DFerroX_amrex_pr=1234

SUNDIALS External Integration:

# Use external SUNDIALS installation
cmake -S . -B build \
  -DFerroX_SUNDIALS=ON \
  -DFerroX_sundials_internal=OFF \
  -DSUNDIALS_DIR=/path/to/sundials/lib/cmake/sundials

HPC System Configuration:

For high-performance computing systems, ensure appropriate modules are loaded. For example, on Perlmutter:

module load cudatoolkit