PhiPsi Instruction Manual

• Author: Fang Shi
• Website: http://phipsi.top
• Email: shifang@hyit.edu.cn / shifang@ustc.edu.cn
• Updated on March 19, 2026.

---

CONTENTS OF THIS FILE

1. Introduction

2. Installation

3. Usage

4. File formats

5. Keywords manual

6. Contact

<a id="section-1"></a>

1. Introduction.

1.1 Introduction

PhiPsi is a computational solid mechanics program, which involves the eXtended Finite Element Method (XFEM) as well as the Finite Element Method (FEM). The program is written in Fortran. The program is named PhiPsi because $\phi$ and $\psi$ are the basic variables for the level set method which is widely used in the XFEM. On the other hand, $\phi$ and $\psi$ denote the internal friction angle and the dilation angle in the plastic theory.

PhiPsi was initially developed in order to solve problems involving defects such as cracks, voids, and inclusions. The functions of PhiPsi include the following:

• 2D static FEM analysis.
• 3D static FEM analysis.
• 2D static XFEM analysis with defects including cracks, voids and inclusions.
• 3D static XFEM analysis with cracks.
• 2D hydraulic fracturing analysis with initial natural fractures.
• 3D hydraulic fracturing analysis with initial natural fractures.

The data generated by PhiPsi can be post processed using PPView (recommended) or a simple Post-Processor program written in Matlab. Download link: http://phipsi.top/downloads.html.

1.2 Key features of PhiPsi

• Supported analysis type: 2D and 3D static analysis, 2D and 3D hydraulic fracturing analysis.
• Supports up to 1000 fractures, voids, and inclusions.
• Capability to randomly generate initial fractures, voids, and inclusions.
• Handles intersection of 2D and 3D fractures, as well as intersection of fractures with voids or inclusions (2D).
• Employs penalty function method to determine contact status.
• Uses optimized Newton-Raphson scheme to solve nonlinear systems.
• Utilizes sparse matrix storage for the global stiffness matrix K.
• Supports DOFs (degrees of freedom) coupling.
• Provides multiple linear system solvers including LAPACK, SuperLU, MUMPs, Lis, and EBE-PCG.
• Supports both formatted and binary file formats for generated data.
• Includes OpenMP support for parallel computing.
• Cross-platform compatibility: Runs on Windows, Linux, and macOS operating systems.

<a id="section-2"></a>

2. Installation

2.1 Linux (Ubuntu)

2.1.1 Install dependencies

sudo apt update
sudo apt install build-essential
sudo apt install cmake  
sudo apt install zip
sudo apt install lrzsz
sudo apt install mpich
sudo apt install ninja-build

2.1.2 Set directory

#
# Modify phipsi_root according to the location of your folder!!!!
#
phipsi_root=/mnt/x/PhiPsi_Project/GitHub_Prep

2.1.3 Compile lapack

lapack_version=lapack-3.12.1
lapack_root=$phipsi_root/lapack
cd $lapack_root
tar zxvf $lapack_version.tar.gz
cd $lapack_root/$lapack_version
cp $lapack_root/$lapack_version/INSTALL/make.inc.gfortran $lapack_root/$lapack_version/make.inc.gfortran
mv make.inc.gfortran make.inc
make -j$(nproc)
sudo cp *.a /usr/local/lib  
sudo cp *.a /usr/lib
mkdir $phipsi_root/lib
cp $lapack_root/$lapack_version/liblapack.a $phipsi_root/lib/liblapack.a
cp $lapack_root/$lapack_version/librefblas.a $phipsi_root/lib/librefblas.a
make clean

2.1.4 Compile mumps

mumps_version=mumps-5.7.3.0
mumps_root=$phipsi_root/mumps
cd $mumps_root
unzip $mumps_version.zip
cd $mumps_root/$mumps_version
rm -rf CMakeCache.txt
rm -rf CMakeFiles
rm -rf build
cmake -G Ninja -B build -DBUILD_SINGLE=yes -DBUILD_DOUBLE=yes -DBUILD_COMPLEX=no -DBUILD_COMPLEX16=no -DMUMPS_parallel=no -DLAPACK_VENDOR=Netlib -Dscalapack=off
cmake --build build
cp $mumps_root/$mumps_version/build/*.a $phipsi_root/lib/
mkdir $phipsi_root/include
cp $mumps_root/$mumps_version/mumps/5.7.3/include/* $phipsi_root/include/
cp $mumps_root/$mumps_version/mumps/5.7.3/libseq/* $phipsi_root/include/
cmake --build build --target clean

2.1.5 Compile lis

lis_version=lis-2.1.11
lis_root=$phipsi_root/lis
cd $lis_root
unzip $lis_version.zip
cd $lis_root/$lis_version
./configure --enable-fortran --enable-f90 --enable-omp
make
make check
cp $lis_root/$lis_version/src/.libs/*.a $phipsi_root/lib/
cp $lis_root/$lis_version/include/* $phipsi_root/include/

2.1.6 Compile PhiPsi

cd $phipsi_root
rm CMakeCache.txt  
cmake $phipsi_root
make -j$(nproc)
# Copy to the bin directory (optional).
sudo cp phipsi /usr/local/bin/
sudo chmod +x /usr/local/bin/phipsi
#make clean

2.1.7 Run PhiPsi examples

2.1.7.1 Example 1: 2d_fem.kpp

# Step 1: change directory to PhiPsi.
cd $phipsi_root
# Step 2: Modify the keyword "Work Directory" in the keywords file 2d_fem.kpp.
# 
# Step 3: Perform the simulation.
./phipsi -i examples/2d_fem.kpp -n 2

2.1.7.2 Example 2: 2d_xfem.kpp

# Step 1: change directory to PhiPsi.
cd $phipsi_root
# Step 2: Modify the keyword "Work Directory" in the keywords file 2d_xfem.kpp.
# 
# Step 3: Perform the simulation.
./phipsi -i examples/2d_xfem.kpp -n 2

2.1.7.3 Example 3: 2d_xfem_hydraulic_fracturing.kpp

# Step 1: change directory to PhiPsi.
cd $phipsi_root
# Step 2: Modify the keyword "Work Directory" in the keywords file 2d_xfem_hydraulic_fracturing.kpp.
# 
# Step 3: Perform the simulation.
./phipsi -i examples/2d_xfem_hydraulic_fracturing.kpp

2.1.7.4 Example 4: 3d_xfem_block_tension.kpp

# Step 1: change directory to PhiPsi.
cd $phipsi_root
# Step 2: Modify the keyword "Work Directory" in the keywords file 3d_xfem_block_tension.kpp.
# 
# Step 3: Perform the simulation.
./phipsi -i examples/3d_xfem_block_tension.kpp -n 6

2.1.7.5 Example 5: 3d_xfem_hydraulic_fracturing.kpp

# Step 1: change directory to PhiPsi.
cd $phipsi_root
# Step 2: Modify the keyword "Work Directory" in the keywords file 3d_xfem_hydraulic_fracturing.kpp.
# 
# Step 3: Perform the simulation.
./phipsi -i examples/3d_xfem_hydraulic_fracturing.kpp -n 6

2.2 macOS (Apple Silicon)

2.2.1 Install dependencies

# Install Homebrew if you do not have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Update Homebrew
brew update
# Install build tools and scientific libraries
brew install gcc                
brew install open-mpi
brew install suite-sparse
brew install python3
brew install zip lrzsz        
brew install cmake
brew install ninja
# Install f3d to view VTK files generated by PhiPsi
# Usage example: f3d 3D_HF_Nonplanar_CRACK_00009.vtk
brew install f3d

2.2.2 Set directory

# Modify phipsi_root according to the location of your folder!!!!
# Example (adjust if your project is elsewhere):
phipsi_root="/Users/fangshi/PhiPsi_Project/GitHub_Prep"

2.2.3 Compile lapack

lapack_version=lapack-3.12.1
lapack_root="$phipsi_root/lapack"
cd "$lapack_root"
tar zxvf "${lapack_version}.tar.gz"
cd "${lapack_root}/${lapack_version}"
# Use gfortran from Homebrew
cp INSTALL/make.inc.gfortran make.inc
# Compile LAPACK and BLAS (may take several minutes)
make
# Create a local lib directory inside the project
mkdir -p "$phipsi_root/lib"
# Copy compiled static libraries into the project
cp liblapack.a "$phipsi_root/lib/liblapack.a"
cp librefblas.a "$phipsi_root/lib/librefblas.a"

2.2.4 Compile mumps

mumps_version=mumps-5.7.3.0
mumps_root=$phipsi_root/mumps
cd $mumps_root
unzip $mumps_version.zip
cd $mumps_root/$mumps_version
rm -rf CMakeCache.txt
rm -rf CMakeFiles
rm -rf build
cmake -G Ninja -B build -DBUILD_SINGLE=yes -DBUILD_DOUBLE=yes -DBUILD_COMPLEX=no -DBUILD_COMPLEX16=no -DMUMPS_parallel=no -DLAPACK_VENDOR=Netlib -Dscalapack=off
cmake --build build
cp $mumps_root/$mumps_version/build/*.a $phipsi_root/lib/
mkdir $phipsi_root/include
cp $mumps_root/$mumps_version/mumps/5.7.3/include/* $phipsi_root/include/
cp $mumps_root/$mumps_version/mumps/5.7.3/libseq/* $phipsi_root/include/
cmake --build build --target clean

2.2.5 Compile lis

lis_version=lis-2.1.11
lis_root=$phipsi_root/lis
cd $lis_root
unzip $lis_version.zip
cd $lis_root/$lis_version
./configure --enable-fortran --enable-f90 --enable-omp
make
make check
cp $lis_root/$lis_version/src/.libs/*.a $phipsi_root/lib/
cp $lis_root/$lis_version/include/* $phipsi_root/include/

2.2.6 Compile PhiPsi

cd $phipsi_root
# Remove CMakeCache.txt if necessary. 
rm CMakeCache.txt  
cmake $phipsi_root
make
# Copy to the bin directory (optional).
sudo cp phipsi /usr/local/bin/
sudo chmod +x /usr/local/bin/phipsi
#make clean

2.2.7 Run PhiPsi examples

2.2.7.1 Example 1: 2d_fem.kpp

# Step 1: change directory to PhiPsi.
cd $phipsi_root
# Step 2: Modify the keyword "Work Directory" in the keywords file 2d_fem.kpp.
# 
# Step 3: Perform the simulation.
./phipsi -i examples/2d_fem.kpp -n 2

2.2.7.2 Example 2: 2d_xfem.kpp

# Step 1: change directory to PhiPsi.
cd $phipsi_root
# Step 2: Modify the keyword "Work Directory" in the keywords file 2d_xfem.kpp.
# 
# Step 3: Perform the simulation.
./phipsi -i examples/2d_xfem.kpp -n 2

2.2.7.3 Example 3: 2d_xfem_hydraulic_fracturing.kpp

# Step 1: change directory to PhiPsi.
cd $phipsi_root
# Step 2: Modify the keyword "Work Directory" in the keywords file 2d_xfem_hydraulic_fracturing.kpp.
# 
# Step 3: Perform the simulation.
./phipsi -i examples/2d_xfem_hydraulic_fracturing.kpp

2.2.7.4 Example 4: 3d_xfem_block_tension.kpp

# Step 1: change directory to PhiPsi.
cd $phipsi_root
# Step 2: Modify the keyword "Work Directory" in the keywords file 3d_xfem_block_tension.kpp.
# 
# Step 3: Perform the simulation.
./phipsi -i examples/3d_xfem_block_tension.kpp -n 4

2.2.7.5 Example 5: 3d_xfem_hydraulic_fracturing.kpp

# Step 1: change directory to PhiPsi.
cd $phipsi_