PhiPsi Instruction Manual

Author: Fang Shi
Website: http://phipsi.top
Email: shifang@hyit.edu.cn / shifang@ustc.edu.cn
Updated on December 8, 2025.

CONTENTS OF THIS FILE

1. Introduction

2. Installation

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 and compiled using the GNU Fortran compiler. 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$ donate the internal friction angle and the dilation angle in the plastic theory.

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

2D static FEM analysis with elastic materials.
3D static FEM analysis with elastic materials.
2D static XFEM analysis with elastic materials, arbitrary number and kinds of defects including cracks, voids and inclusions.
3D static XFEM analysis with elastic materials and crack.
2D hydraulic fracturing analysis with elastic materials and initial natural fracture.
3D hydraulic fracturing analysis with elastic materials and initial natural fracture.

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, 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.

2. Installation

2.1 Linux (Ubuntu)

2.1.1 Install software

sudo apt update
sudo apt upgrade
# Install build tools and scientific libraries
sudo apt install build-essential
sudo apt-get install cmake  
sudo apt-get install zip
sudo apt-get install lrzsz
sudo apt-get install mpich
sudo apt-get install ninja-build
# Install f3d to view VTK files generated by PhiPsi
# Usage example: f3d 3D_HF_Nonplanar_CRACK_00009.vtk
sudo apt-get install f3d
# Install Python (optional).
sudo apt-get install python3-tk
sudo apt install python3-pip
python3 -m pip install colorama --break-system-packages
python3 -m pip install textfile --break-system-packages
python3 -m pip install py-cpuinfo --break-system-packages
python3 -m pip install psutil --break-system-packages
python3 -m pip install PySimpleGUI --break-system-packages
python3 -m pip install numpy --break-system-packages

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 software

# 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="$HOME/PhiPsi_Project/GitHub_Prep"
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 6

2.2.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.3 Windows

2.3.1 Install MSYS2

Download and install MSYS2. https://www.msys2.org/
Open MSYS2 MINGW64 and run the following commands:

pacman -Syu
pacman -S mingw-w64-x86_64-gcc
pacman -S mingw-w64-x86_64-gcc-fortran
pacman -S base-devel
pacman -S mingw-w64-x86_64-msmpi
pacman -S mingw-w64-x86_64-lapack
pacman -S mingw-w64-x86_64-openblas
pacman -S mingw-w64-x86_64-ninja
pacman -S mingw-w64-x86_64-cmake
export PATH=C:/msys64/mingw64/bin:$PATH
export C_INCLUDE_PATH=C:/msys64/mingw64/include:$C_INCLUDE_PATH
export CPLUS_INCLUDE_PATH=C:/msys64/mingw64/include:$CPLUS_INCLUDE_PATH
export LIBRARY_PATH=C:/msys64/mingw64/lib:$LIBRARY_PATH

2.3.2 Set directory

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

2.3.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 INSTALL/make.inc.gfortran make.inc
make -j$(nproc)
mkdir -p "$phipsi_root/lib"
cp liblapack.a "$phipsi_root/lib/liblapack.a"
cp librefblas.a "$phipsi_root/lib/librefblas.a"
make clean

2.3.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.3.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.3.6 Compile PhiPsi

cd $phipsi_root
rm -rf CMakeCache.txt CMakeFiles/ Makefile *.ninja .ninja_deps .ninja_log
cmake $phipsi_root
ninja
# ninja clean

2.3.7 Run PhiPsi examples

2.3.7.1 Example 1: 2d_fem.kpp

# Step 1: open Windows Terminal, change directory to phipsi.exe, for example:
cd 'X:\PhiPsi_Project\GitHub_Prep'
# Step 2: Modify the keyword "Work Directory" in the keywords file 2d_fem.kpp.
# 
# Step 3: Perform the simulation, for example:
./phipsi.exe -i "X:\PhiPsi_Project\examples\2d_fem.kpp" -n 2

2.3.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.exe -i "X:\PhiPsi_Project\examples\2d_xfem.kpp" -n 2

Additional examples are not shown here.

3. Usage

3.1 How does PhiPsi work?

There are two options to use PhiPsi.

3.1.1 OPTION 1 -- Use ANSYS (or Abaqus, etc) and Matlab for pre-processing and post-processing, respectively.

The input files of PhiPsi include a keywords file and other data files contain the node coordinates ( *.node), element-node information ( *.elem), boundary conditions ( *.boux and *.bouy), and external forces ( *.focx and *.focy). The keywords file ( *.kpp) defines information such as the work directory, analysis type, coordinates of initial cracks. The data files can be generated automatically by run the macro file called Ansys2PhiPsi_2D.mac for 2D problems (or Ansys2PhiPsi_3D.mac for 3D problems) once the model is created in ANSYS. Certainly, you can define the data files by using other software such as Abaqus (A useful tool to convert Abaqus inp model file to PhiPsi input files can be found from http://www.phipsi.top/source/Abaqus2PhiPsi_Matlab.rar) or just generate it manually.

Once PhiPsi starts, it will check all the input files firstly. After the analysis, the output files will be saved to the working directory. A Matlab-based program (all the source codes are available for download, see "The source codes of the Post-Processor written in Matlab" on page http://phipsi.top/downloads.html) is offered for post-processing. A tutorial (a pdf file) is available on the downloads page (see "The tutorial" on page http://phipsi.top/downloads.html).

This document describes only OPTION 1.

3.1.2 OPTION 2 -- Use PPView (recommended)

Alternatively, you can also perform an analysis using PPView ( A Visualization Tool for PhiPsi). It can be used to import Abaqus inp file, view the model defined in the PhiPsi keywords file (*.kpp), edit PhiPsi keywords file, perform a PhiPsi simulation, and view the simulation result files generated by PhiPsi. The PPView Help Manual can be found from here (PPView Help Manual). You can download PPView for Windows, macOS, or Linux from here.

3.2 How to run PhiPsi with specified keywords file (*.kpp)?

Open terminal, use cd command to change directory to the folder which contains the compiled PhiPsi, then your can run PhiPsi by typing a command line as follows:

./phipsi -i /mnt/x/PhiPsi_Project/GitHub_Prep/3d_xfem_hydraulic_fracturing.kpp -n 6
# phipsi.exe -i X:\PhiPsi_Project\GitHub_Prep\3d_xfem_hydraulic_fracturing.kpp -n 6

where -i specifies the file path of the keywords file (*.kpp), and -n specify the number of threads for the OpenMP parallel simulation.

4. File formats.

4.1 *.kpp file

Keywords file of PhiPsi, composed of Keywords that begins with character "*", see Section 5 for details on PhiPsi Keywords manual. The lines beginning with character "%" are comment lines. For example:

% Working directory.
*Work_Directory
X:\PhiPsi Work\FEM

% Filename of input files.
*Filename
FEM

% Analysis type (Quasi-static).
*Key_Analysis_Type
1

% Plane stress.
*Key_Type_2D
1

% Linear system solver (SuperLU).
*Key_SLOE
9

% Number of propagation steps.
*Num_Substeps
1

% Material(1-E,2-v,3-density,4-thick,5-St,6-KIc,7-Sc,8-20(blank))
*Material_Para_1
70.0e9,0.3,2700.0,1.0,1.0e6,1.0e6,100.0e6,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0

% Play sound (using python2.7).
*Key_Play_Sounds
1

4.2 Input files

Generally, 6 files are necessary for a 2D simulation, i.e., *.node file, *.elem file, *.boux file, *.bouy file, *.focx file, and *.focy file. And 8 files are necessary for a 3D simulation, i.e., *.node file, *.elem file, *.boux file, *.bouy file, *.bouz file, *.focx file, *.focy file, and *.focz file.

4.2.1 *.node

This file defines coordinates of each node. The number of rows in this file is the same as the number of nodes. For 2D problems, this file should be presented in the format ($x$, $y$), for example:

  0.50000000E-01   0.00000000E+00
 -0.40000000E-01   0.30000000E-01
  0.49610478E-01   0.62290027E-02
  0.48447981E-01   0.12360952E-01
  0.46530622E-01   0.18300307E-01
  0.43888275E-01   0.23954527E-01
  0.40562109E-01   0.29235514E-01
  0.36603951E-01   0.34060986E-01
  0.32075470E-01   0.38355759E-01
  0.27047226E-01   0.42052914E-01
 ......

For 3D problems, this file should be presented in the format ($x$, $y$, $z$), for example:

  0.00000000E+00   0.00000000E+00   0.00000000E+00
  0.50000000E+01   0.00000000E+00   0.00000000E+00
  0.10000000E+01   0.00000000E+00   0.00000000E+00
  0.20000000E+01   0.00000000E+00   0.00000000E+00
  0.30000000E+01   0.00000000E+00   0.00000000E+00
  0.40000000E+01   0.00000000E+00   0.00000000E+00
  0.50000000E+01   0.50000000E+01   0.00000000E+00
  0.50000000E+01   0.10000000E+01   0.00000000E+00
  0.50000000E+01   0.20000000E+01   0.00000000E+00
  0.50000000E+01   0.30000000E+01   0.00000000E+00
  ......

4.2.2 *.elem

This file defines the 4 nodes of each quadrilateral element. The number of rows in this file is the same as the number of elements. For 2D problems, this file should be presented in the format ($node_1$, $node_2$, $node_3$, $node_4$ , Material_Number). For example:

 1       3      81      62       1
 3       4     100      81       1
 4       5     119     100       1
 5       6     138     119       1
 6       7     157     138       1
 7       8     176     157       2
 8       9     195     176       2
 9      10     214     195       2
10      11     233     214       2
11      12     252     233       2
......

For 3D problems, this file defines the 8 nodes of each quadrilateral element, and the format is ($node_1$, $node_2$, $node_3$, $node_4$, $node_5$, $node_6$, $node_7$, $node_8$, Material_Number). For example:

  1       3      21      20      50      51     153     121       1
  2       4      25      21      51      55     169     153       1
  3       5      29      25      55      59     185     169       1
  4       6      33      29      59      63     201     185       1
  5       2       8      33      63      38      76     201       1
  1      21      22      19     121     153     157     125       2
  2      25      26      22     153     169     173     157       2
  3      29      30      26     169     185     189     173       2
  4      33      34      30     185     201     205     189       2
  5       8       9      34     201      76      80     205       2
 ......

4.2.3 .boux, .bouy, *.bouz

These three files contain information about boundary conditions, define nodes whose degrees of freedom are constrained in $x$, $y$, and $z$ directions, respectively. For example, the following lines presented in *.bouy file indicates that $y$ degrees of freedom of nodes 50, 92, 97, 98, 99 are constrained:

It should be noted that *.bouz is only available for 3D problems.

4.2.4 .focx, .focy, *.focz

These three files contain information about external forces, define nodes with force applied in $x$, $y$, and $z$ directions, respectivly. For exampe, the following lines presented in *.focx file indicates that nodes 487 to 489 are under the action of force at 4.5 KN in $x$ direction:

	487   0.45000000E+04
	488   0.45000000E+04
	489   0.45000000E+04

It should be noted that *.focz is only available for 3D problems.

4.2.5 .buxn, .buyn, *.buzn

These three files contain information about non-zero boundary conditions, define nodes whose degrees of freedom are constrained at a non-zero value in $x$, $y$, and $z$ directions, respectively. For example, the following lines presented in *.buxn file indicates that degrees of freedom in the $x$ direction of nodes 2, 17, 18 are constrained at 0.01:

  1    0.10000000E-01
  2    0.10000000E-01
  3    0.10000000E-01

It should be noted that *.buzn is only available for 3D problems.

4.2.6 *.fbvl

This file is necessary for field problems and defines field values of specified nodes. This file should be presented in the format (node_number, field_value), for example:

 1  -0.30000000E+02
 2  -0.30000000E+02
 3  -0.30000000E+02
 4  -0.30000000E+02
 5  -0.30000000E+02
 6  -0.30000000E+02
 7  -0.30000000E+02
 8  -0.30000000E+02
 9  -0.30000000E+02
10  -0.30000000E+02
......

4.2.7 *.fbqn

This file is necessary for field problem and defines flux of specified nodes. This file should be presented in the format (node_number, flux), for example

1    1.00000000E+00
2    1.00000000E+00
3    1.00000000E+00
4    1.00000000E+00
......

4.2.8 *.eqac

This file defines earthquake acceleration values for earthquake analysis (when keyword *Key_EQ = 1), for example:

-7.5598
-5.3088
-3.3145
-1.4194
 0.2725
 0.9968
 1.0547
 1.0481
......

4.3 Output files

The following output files are generated by PhiPsi after performing the analysis, and are stored in the folder defined by the keywords *Work_Directory.

4.3.1 *.post

This file stores some key information of the analysis. For example:

Analysis type | Crack-tip type | Data format | Key_H_Value | Key_Hole_Value | Ave_Elem_L
        1            1               1              -1               0          1.00000

4.3.2 *.disn_i

This file stores dispalcements of nodes generated at load step $i$. For 2D problems, the file format is (node_number, $u_x$, $u_y$), for example:

......
34, -0.467926263384E-05,  0.419542374087E-06
35, -0.469104701689E-05,  0.617977716660E-06
36, -0.470546275930E-05,  0.802658990736E-06
37, -0.472032630946E-05,  0.968760298709E-06
38, -0.473268608950E-05,  0.111127141917E-05
......

For 3D problems, the file format is (node_number $u_x$ $u_y$ $u_z$), for example:

......
3780  0.737379554187E-04 -0.763808664114E-03  0.662900115050E-02
3781  0.708322234178E-04 -0.697596785199E-03  0.716042769529E-02
3782  0.678586850598E-04 -0.638530077174E-03  0.767755784595E-02
3783  0.642688033432E-04 -0.575506959266E-03  0.818137849393E-02
3784  0.594566432214E-04 -0.499317330865E-03  0.867348144814E-02
......

4.3.3 *.disg_i

This file stores dispalcements of Gauss points generated at load step $i$. For 2D problems, the file format is (Gauss_point_number, $u_x$, $u_y$), for example:

......
 6 -0.681966248546E-07  0.174855529000E-06
 7 -0.104263194381E-06  0.478694416204E-07
 8 -0.103208726099E-06  0.178651188257E-06
 9 -0.131780383643E-06  0.488623631234E-07
10 -0.130645195650E-06  0.182356821755E-06
......

4.3.4 *.disp_i

This file stores displacements of nodes generated at load step $i$. For 2D problems, the file format is ($u_x$ of node $i$; $u_y$ of node $i$; $u_x$ of node $i+1$; $u_y$ of node $i+1$). For example, if the following lines are line 7 to 10, then $u_x$ of node 4 is -0.466896194407E-05, $u_y$ of node 4 is 0, $u_x$ of node 5 is -0.566032590142E-07, and $u_y$ of node 5 is 0.

-0.466896194407E-05
 0.000000000000E+00
-0.566032590142E-07
 0.000000000000E+00
......

For 3D problems, the file format is ($u_x$ of node $i$; $u_y$ of node $i$; $u_z$ of node $i$; $u_x$ of node $i+1$; $u_y$ of node $i+1$; $u_z$ of node $i+1$). For example, if the following lines are line 4 to 9, then $u_x$ of node 2 is 0.210057007761E-02, $u_y$ of node 2 is 0.837429251589E-04, $u_z$ of node 2 is 0.192054550639E-04, $u_x$ of node 3 is 0.129365417926E-03, $u_y$ of node 3 is 0.199100066146E-03, and $u_z$ of node 3 is 0.550890425222E-03.

0.210057007761E-02
0.837429251589E-04
0.192054550639E-04
0.129365417926E-03
0.199100066146E-03
0.550890425222E-03
......

4.3.5 *.sifs_i

This file stores stress intensity factors of each tip of each crack at load step $i$. File format is ($K_I$ of Tip 1 of Crack $i$, $K_{II}$ of Tip 1 of Crack $i$, $K_I$ of Tip 2 of Crack $i$, $K_{II}$ of Tip 2 of Crack $i$). For example, the following lines presents stress intensity factors of 4 cracks:

0.260374752174E+06  0.467185152343E+06  0.122785020115E+06  0.389981389457E+06
0.323802318295E+05 -0.117843181408E+06 -0.770509388350E+05 -0.193638531237E+06
0.372632001601E+06 -0.147258816863E+06  0.365137977201E+06 -0.138715162319E+06

4.3.6 *.strn_i

This file stores stress of nodes generated at load step $i$. File format for 2D problems is (node_number, $σ_{xx}$, $σ_{yy}$, $σ_{xy}$, $σ_{vm}$), for example:

1 -0.357641123386E+05  0.659542676662E+07  0.138064598368E+05  0.607064386061E+07
2 -0.370598733137E+05  0.640285157136E+07 -0.320217935736E+05  0.589529626923E+07
3 -0.916837723784E+05  0.662868252994E+07  0.187424259637E+05  0.614161688903E+07
4 -0.228102575626E+06  0.684666995390E+07  0.229913659892E+05  0.644075924405E+07
5 -0.440568565847E+06  0.721385450541E+07  0.267455435160E+05  0.693352411155E+07
......

File format for 3D problems is ($σ_{xx}$, $σ_{yy}$, $σ_{zz}$, $σ_{xy}$, $σ_{yz}$, $σ_{xz}$,), for example:

0.103380715181E+08  0.103380715181E+08  0.241221668755E+08  0.000000000000E+00  0.432472930636E+07  0.422517735880E+07
0.103535393533E+08  0.103535393533E+08  0.241582584911E+08  0.000000000000E+00  0.433712819417E+07 -0.423710224234E+07
0.822115304470E+07  0.822115304470E+07  0.191826904376E+08  0.000000000000E+00  0.426738252654E+07  0.254198239071E+07
0.781867402679E+07  0.781867402679E+07  0.182435727292E+08  0.000000000000E+00  0.428511509043E+07  0.174077141830E+07
0.757832787209E+07  0.757832787209E+07  0.176827650349E+08  0.000000000000E+00  0.424329974171E+07  0.123470458056E+07
......

4.3.7 *.strg_i

This file stores stress of Gauss points generated at load step $i$. File format for 2D problems is (Gauss_point_number, $σ_{xx}$, $σ_{yy}$, $σ_{xy}$, $σ_{vm}$), for example:

1 -0.303647984890E+05  0.660675866845E+07  0.187790033225E+05  0.607717203635E+07
2 -0.228860071512E+05  0.660862836628E+07  0.295144633963E+05  0.607361759517E+07
3 -0.230923900636E+05  0.663584830215E+07  0.216287846946E+05  0.609861381279E+07
4 -0.156135987259E+05  0.663771799998E+07  0.323642447683E+05  0.609507689516E+07
5 -0.143636979631E+06  0.666896756246E+07  0.406114230194E+05  0.621657686172E+07
......

4.3.8 *.gcor_i

This file stores coordinates of Gauss points generated at load step $i$. File format for 2D problems is (Gauss_point_number_number, $x$, $y$), for example:

1  0.147927405784E-03  0.145579351958E-03
2  0.147927405784E-03  0.543309538042E-03
3  0.552072594216E-03  0.145579351958E-03
4  0.552072594216E-03  0.543309538042E-03
5  0.847927405784E-03  0.145579351958E-03
......

4.3.9 .crax_i, .cray_i, *.craz_i

These file store $x$, $y$, and $z$ coordinates of points of cracks generated at load step $i$. File format is (coordinate of point 1 of crack $i$, coordinate of point 2 of crack $i$, coordinate of point 3 of crack $i$, ...). In the following cray_i example, line 3 indicates that crack 3 has 4 points, and their $y$ coodinates are 0.883063441879E-02, 0.915860471085E-02, 0.939531592630E-02, and 0.97E-02, respectively.

0.343000000000E-01  0.433000000000E-01
0.433000000000E-01  0.343000000000E-01
0.883063441879E-02  0.915860471085E-02  0.939531592630E-02  0.970000000000E-02
0.430000000000E-02  0.133000000000E-01
0.133000000000E-01  0.430000000000E-02

4.3.10 *.hftm

This file store information about load step, substep, and step time, for example:

imf   |   ifra   | total_ter|   time
1         1         1           5.56323
1         1         2           4.23361
1         1         3           4.25468
1         1         4           4.26472
1         1         5           4.26440
1         1         6           4.26432
1         2         7           9.97560
1         2         8           6.28206
1         2         9           6.19229
1         2        10           6.19146
1         2        11           6.19146
1         3        12          13.03537
1         3        13           9.67422
1         3        14           9.78424
1         3        15           9.79946
1         3        16           9.79838

4.3.11 *_i.vtk

This vtk file stores the results of nodes and elements at load step $i$, and can be post-processed using ParaView (https://www.paraview.org/) or simply using F3D (https://f3d.app/; Usage: press H to show control options, and press S to switch between results). For example:

# vtk DataFile Version 4.0
X:\PhiPsi_Work\exa_3D_block_tension\exa_3D_block_tension  - results from increment 0001
ASCII
DATASET UNSTRUCTURED_GRID

POINTS 5832 double
    0.000000    0.000000    0.000000
   17.000000    0.000000    0.000000
    1.000000    0.000000    0.000000
    2.000000    0.000000    0.000000
    3.000000    0.000000    0.000000
......

CELLS 4913 44217
         8         0         2        68        67       373       374      1736      1224
         8         2         3        84        68       374       390      1992      1736
         8         3         4       100        84       390       406      2248      1992
......

CELL_TYPES      4913
 12
 12
 12
......

SCALARS Element_ID int
LOOKUP_TABLE default
       1
       2
       3
       4
       5	
......

POINT_DATA      5832
VECTORS Displacement double
 -0.131954990094E-02  0.141597199813E-02  0.836084920257E-02
 -0.528204104886E-03  0.532349419725E-03  0.833877259072E-03
 -0.737678990062E-03  0.749632729946E-03  0.138138742438E-02
......

SCALARS stress_xx double
LOOKUP_TABLE default
  0.962069787688E+07
  0.962166068159E+07
  0.756335159397E+07
......

SCALARS stress_yy double
LOOKUP_TABLE default
  0.000000000000E+00
  0.000000000000E+00
  0.000000000000E+00  
......

SCALARS Node_Number integer
LOOKUP_TABLE default
       1
       2
       3
       4
       5
......  

SCALARS Enriched_Node_Type int
LOOKUP_TABLE default
0
0
0
0
......

4.3.12 *_CRACK_i.vtk

This vtk file stores the results of cracks at load step $i$, and can be post-processed using ParaView (https://www.paraview.org/) or simply using F3D (https://f3d.app/; Usage: press H to show control options, and press S to switch between results). For example:

# vtk DataFile Version 4.0
X:\PhiPsi_Work\exa_3D_block_tension\exa_3D_block_tension  - results from increment 0005
ASCII
DATASET UNSTRUCTURED_GRID

POINTS 137 double
    6.500000    6.500000   10.999900
    7.500000    6.500000   10.999900
    8.500000    6.500000   10.999900
    9.500000    6.500000   10.999900
   10.500000    6.500000   10.999900
......

CELLS 245 980
         3         0         1         5
         3         1         6         5
         3         1         2         6
         3         2         7         6
......

CELL_TYPES       245
  5
  5
  5
  5
......

CELL_DATA       245

SCALARS Crack_ID int
LOOKUP_TABLE default
       1
       1
       1
       1
......

SCALARS Crack_Element_ID int
LOOKUP_TABLE default
       1
       2
       3
......

POINT_DATA       137

SCALARS Crack_Node_Number integer
LOOKUP_TABLE default
       1
       2
       3
       4
       5
......

SCALARS Crack_Node_Aperture double
LOOKUP_TABLE default
  0.291586464535E-02
  0.309378576419E-02
  0.230428233873E-02
  0.306511996250E-02
......

5. Keywords manual.

The keyword manual of PhiPsi can be found here: http://phipsi.top/phipsi_keywords_manual.html

6. Contact

Author Information

Name: Fang Shi
Affiliation: Faculty of Mechanical & Material Engineering, Huai'an University, China
Website: http://phipsi.top
Email: shifang@hyit.edu.cn

For more details about the author, please visit: http://phipsi.top/author.html

Citation

If PhiPsi is helpful to your research, please cite the following papers:

Shi F., Lin C. Modeling fluid-driven propagation of 3D complex crossing fractures with the extended finite element method. Computers and Geotechnics, 2024, 172, 106482.
Shi F., Wang D., Li H. An XFEM-based approach for 3D hydraulic fracturing simulation considering crack front segmentation. Journal of Petroleum Science and Engineering, 2022, 214, 110518.
Shi F., Wang D., Yang Q. An XFEM-based numerical strategy to model three-dimensional fracture propagation regarding crack front segmentation. Theoretical and Applied Fracture Mechanics, 2022, 118, 103250.
Shi F., Liu J. A fully coupled hydromechanical XFEM model for the simulation of 3D non-planar fluid-driven fracture propagation. Computers and Geotechnics, 2021, 132, 103971.
Shi F., Wang X.L., Liu C., Liu H., Wu H.A. An XFEM-based method with reduction technique for modeling hydraulic fracture propagation in formations containing frictional natural fractures. Engineering Fracture Mechanics, 2017, 173, 64-90.

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
examples		examples
lapack		lapack
lis		lis
mumps		mumps
src		src
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
Readme.md		Readme.md

Folders and files

Latest commit

History

Repository files navigation

PhiPsi Instruction Manual

CONTENTS OF THIS FILE

1. Introduction.

1.1 Introduction

1.2 Key features of PhiPsi

2. Installation

2.1 Linux (Ubuntu)

2.1.1 Install software

2.1.2 Set directory

2.1.3 Compile lapack

2.1.4 Compile mumps

2.1.5 Compile lis

2.1.6 Compile PhiPsi

2.1.7 Run PhiPsi examples

2.1.7.1 Example 1: 2d_fem.kpp

2.1.7.2 Example 2: 2d_xfem.kpp

2.1.7.3 Example 3: 2d_xfem_hydraulic_fracturing.kpp

2.1.7.4 Example 4: 3d_xfem_block_tension.kpp

2.1.7.5 Example 5: 3d_xfem_hydraulic_fracturing.kpp

2.2 macOS (Apple Silicon)

2.2.1 Install software

2.2.2 Set directory

2.2.3 Compile lapack

2.2.4 Compile mumps

2.2.5 Compile lis

2.2.6 Compile PhiPsi

2.2.7 Run PhiPsi examples

2.2.7.1 Example 1: 2d_fem.kpp

2.2.7.2 Example 2: 2d_xfem.kpp

2.2.7.3 Example 3: 2d_xfem_hydraulic_fracturing.kpp

2.2.7.4 Example 4: 3d_xfem_block_tension.kpp

2.2.7.5 Example 5: 3d_xfem_hydraulic_fracturing.kpp

2.3 Windows

2.3.1 Install MSYS2

2.3.2 Set directory

2.3.3 Compile lapack

2.3.4 Compile mumps

2.3.5 Compile lis

2.3.6 Compile PhiPsi

2.3.7 Run PhiPsi examples

2.3.7.1 Example 1: 2d_fem.kpp

2.3.7.2 Example 2: 2d_xfem.kpp

3. Usage

3.1 How does PhiPsi work?

3.1.1 OPTION 1 -- Use ANSYS (or Abaqus, etc) and Matlab for pre-processing and post-processing, respectively.

3.1.2 OPTION 2 -- Use PPView (recommended)

3.2 How to run PhiPsi with specified keywords file (*.kpp)?

4. File formats.

4.1 *.kpp file

4.2 Input files

4.2.1 *.node

4.2.2 *.elem

4.2.3 *.boux, *.bouy, *.bouz

4.2.4 *.focx, *.focy, *.focz

4.2.5 *.buxn, *.buyn, *.buzn

4.2.6 *.fbvl

4.2.7 *.fbqn

4.2.8 *.eqac

4.3 Output files

4.3.1 *.post

4.3.2 *.disn_i

4.3.3 *.disg_i

4.3.4 *.disp_i

4.3.5 *.sifs_i

4.3.6 *.strn_i

4.3.7 *.strg_i

4.3.8 *.gcor_i

4.3.9 *.crax_i, *.cray_i, *.craz_i

4.3.10 *.hftm

4.3.11 *_i.vtk

4.3.12 *_CRACK_i.vtk

5. Keywords manual.

6. Contact

Author Information

Citation

About

4.2.3 .boux, .bouy, *.bouz

4.2.4 .focx, .focy, *.focz

4.2.5 .buxn, .buyn, *.buzn

4.3.9 .crax_i, .cray_i, *.craz_i

Packages