Matrix Discrete Element Analysis of Geological and Geotechnical Engineering 9789813345232, 9789813345249

Table of contents :
Foreword by Bin Shi
Foreword by Y. T. Feng
Preface
About This Book
Contents
About the Author
1 Principles and Implementation of DEM
1.1 Application and Numerical Calculation Software of DEM
1.2 Basic Principles of DEM
1.2.1 Contact Model of Elements
1.2.2 Connection of Two Different Elements
1.2.3 Time Step Iterative Algorithm
1.3 Damping Harmonic Vibration of Elements
1.3.1 Damping Force of Elements
1.3.2 Equation of the Damping Harmonic Vibration
1.3.3 Relation Between Vibration Period and Element Radius
1.3.4 Differences of the Element Motion
1.3.5 Damping and Optimal Damping Coefficient
1.4 Energy Conversion and Energy Conservation of DEM
1.4.1 Mechanical Energy of Systems
1.4.2 Calculation of Heat
1.4.3 Energy Conservation and External Work
1.5 Calculation Scale and Engineering Application Feasibility of DEM
1.6 Understanding and Solution to the Three Major Issues in DEM
1.6.1 High-Performance Matrix Computing of the Discrete Element Method
1.6.2 Quantitative Modeling Problem of DEM
1.6.3 Multi-field Coupling Method Based on DEM
1.7 Development and Prospect of MatDEM
References
2 The Basic Structure of MatDEM
2.1 The Software Foundation
2.1.1 The Operating Environment and Software Installation
2.1.2 The Windows Program for MatDEM
2.1.3 Operation and Termination of the Software
2.1.4 A Brief Introduction to the Application of the Software
2.1.5 A Brief Introduction to the Help File
2.2 The Program Structure of MatDEM
2.2.1 The Software Folders of MatDEM
2.2.2 The Hierarchical Structure of MatDEM
2.2.3 The Main Classes in MatDEM
2.3 Types of Element in MatDEM
2.3.1 Active Element, Wall Element, and Virtual Element
2.3.2 Fix the Degree of Freedom of Elements
2.3.3 The Rule of Numbering Elements
2.4 The Data Structure of MatDEM
2.4.1 The Property Arrays of Elements
2.4.2 The Neighbor Matrix and Connection Information Matrix
2.4.3 The Data Structure and Operation of Groups
2.5 The Contact Model Between Elements
2.5.1 The Linear Elastic Contact Model
2.5.2 The Hertz Contact Model
2.6 The Elastic Clump
2.6.1 The Principle of the Elastic Clump
2.6.2 Usage of the Elastic Clump
3 Geometric Modeling and Material Setup
3.1 Building a Numerical Simulation Box
3.1.1 Building a Packing Model
3.1.2 Creating an Empty Box
3.2 The Foundation of Modular Modeling
3.2.1 Modeling with a Structure
3.2.2 Filtering
3.2.3 ToolCut and Digital Elevation Model
3.3 Modeling Based on Digital Images
3.3.1 Importing a Binary Image to Cut a Model
3.3.2 Block Modeling by Importing a Color Image
3.4 Material Setting
3.4.1 Overview of Material Setting
3.4.2 Input the Material Properties Directly
3.4.3 Automatic Training of Materials
3.5 Balance Model
3.5.1 Iterative Calculation Function and Standard Balance
3.5.2 Strong Bond Balance
3.5.3 Neighbor Searching and Zero Balance
3.5.4 Standard of Judgment for a Model Balance State
3.6 Setting of Cracks and Joints
3.6.1 Setting Weak Layers and Cracks Through Groups
3.6.2 Using Triangle Faces to Set Cracks and Joints
3.6.3 Using ToolCut to Set Cracks and Joints
3.6.4 Definition and Use of the Connection Filter
4 Load Settings and Numerical Calculations
4.1 The Initialization and Settings of Numerical Calculation
4.1.1 The Initialization of Model Parameters
4.1.2 Setting of Relevant Parameters in Calculation
4.2 Boundary and Load
4.2.1 Boundary Conditions
4.2.2 Stress Load
4.2.3 Displacement Load
4.2.4 Vibration Load
4.2.5 Other Loads
4.3 Time and Settings of Iterative Calculation
4.3.1 Running Time of Iterative Calculation
4.3.2 Radius of Elements and Time of Calculation
4.3.3 Settings for Dynamic Issues
4.3.4 Setting and Simulation Accuracy of Quasi-Static Problems
4.4 Definition and Modification of Simulated Parameters
4.4.1 Creation of Custom Parameters
4.4.2 Modification of Element Properties in a Group
4.4.3 Settings of Time Step, the Radius of Elements, and Stiffness
4.5 Compression, Saving, and Reading of Files
4.5.1 Compression of Files
4.5.2 Saving and Reading of Files
5 Post-processing and System Functions
5.1 Post-processing Window Interface
5.1.1 Main Post-processing Window
5.1.2 Saving the Post-processing Figure
5.1.3 Making GIF Window
5.2 Post-processing Drawing Functions
5.2.1 General Drawing Function d.show
5.2.2 Basic Display Settings
5.2.3 Slice Display and Filter Display
5.2.4 Element Position and Force Display
5.3 Data Processing and Curve Drawing
5.3.1 Drawing Curves with Saved Data
5.3.2 Drawing Curves with MatDEM Automatically Recorded Data
5.3.3 Processing Data and Plotting in MATLAB
5.4 System Functions
5.4.1 GPU Computing Settings and Status Viewing
5.4.2 Definition and Operation of Functions
5.4.3 Batch Processing of Code Files
5.4.4 Random Seed and Stochastic Model
5.4.5 Timing Functions
5.5 Modeling with System Underlying Functions
5.5.1 Underlying Modeling of the Two-Ball Collision Process
5.5.2 Use Graphs to Analyze Collision Processes
6 Basic Application of Geotechnical Engineering
6.1 Pile–Soil Interaction
6.1.1 Packing Model of Particles
6.1.2 Build a Pile-Soil Interaction Model
6.1.3 Numerical Simulation of the Pile Pulling Process
6.2 Tunnel Modeling
6.2.1 Packing Model of Particles
6.2.2 Build a Tunnel Model
6.2.3 Loading and Numerical Simulation
6.3 TBM Cutter Rock Breaking
6.3.1 Packing Model of Particles
6.3.2 Build a Model of TBM Cutter Rock Breaking
6.3.3 Numerical Simulation Process of Rock Breaking with Hob
6.3.4 Improve the Calculation Speed of Rock Breaking with Hob
7 Rock–Soil Body Discrete Element Tests
7.1 Direct Shear and Torsional Shear Tests
7.1.1 Define Test Parameter and Accumulate Sample
7.1.2 Making a Shear Box and Cutting Sample
7.1.3 Putting the Sample into the Shear Box
7.1.4 Material Setting and Numerical Simulation
7.2 True Triaxial Test and Joint Modeling
7.2.1 Build a True Triaxial Test Chamber
7.2.2 Defining Fracture Surface Using Triangle Faces and Polygons
7.2.3 Defining Complex Joint Surfaces Using ToolCut
7.2.4 Applying True Triaxial Stress
8 Modeling of Complex 3D Models
8.1 Defining 3D Surfaces with Digital Elevation
8.1.1 Defining Digital Elevation Model Using Discrete Points
8.1.2 Processing of Digital Elevation Data at the Surface
8.2 Building a Thin Shell Model
8.2.1 Building a Geometric Model
8.2.2 Cutting and Packing Model
8.3 Building a Three-Dimensional Slope Model
8.3.1 Import Material
8.3.2 Set the Material for the Stratum
8.4 Numerical Simulation of Landslide’s Motion Process
8.4.1 Setting of Numerical Simulation Parameters
8.4.2 Iterative Calculations and Simulation Results
9 Numerical Simulations of Dynamic Action
9.1 Meteorite Impact on the Earth
9.1.1 Packing Model of Particles
9.1.2 Building a Meteorite Model
9.1.3 Simulation of Meteorite Impact Process
9.2 Mine Slope Blasting
9.2.1 Slope Model
9.2.2 Setting the Blasting Point and Blasting Energy
9.2.3 Iterative Calculations and Simulation Results
9.3 Seismic Wave Propagation
9.3.1 Establishment of Topography and Stratification
9.3.2 The Generation and Propagation of Seismic Waves
10 Multi-field Coupling Numerical Simulation
10.1 Friction Heat Generated by Landslide Slipping
10.2 Microwave-Assisted Rock Breaking
10.2.1 Building a Clump Packing Model
10.2.2 Grouping and Material Setting of Pyroxene and Feldspar
10.2.3 Numerical Simulation of Pyroxene Thermal Expansion
10.3 Thermal Coupling of Energy Pile
10.3.1 Establish an Energy Pile-Stratum Model
10.3.2 Numerical Simulation of Thermal Coupling Process
10.4 Ground Subsidence and Ground Fissures
10.4.1 Cutting the Stratum Model
10.4.2 Numerical Simulation of the Decline of Water Level
Appendix A Properties of Classes
Appendix Properties of Classes
Properties of objBox Class
Properties of build Class
Properties of model Class
Properties of ToolCut Class
Appendix B Main Functions
Functions of objBox Class
Functions of Build Class
Functions of Model Class
Functions of fs Class
Functions of mfs Class
Functions of ToolCut Class
Appendix C Frequently Asked Questions

Citation preview

Chun Liu

Matrix Discrete Element Analysis of Geological and Geotechnical Engineering

Matrix Discrete Element Analysis of Geological and Geotechnical Engineering

Chun Liu

Matrix Discrete Element Analysis of Geological and Geotechnical Engineering

Chun Liu School of Earth Sciences and Engineering Nanjing University Nanjing, China

ISBN 978-981-33-4523-2 ISBN 978-981-33-4524-9 (eBook) https://doi.org/10.1007/978-981-33-4524-9 Jointly published with Science Press The print edition is not for sale in China (Mainland). Customers from China (Mainland) please order the print book from: Science Press. © Science Press 2021 This work is subject to copyright. All rights are solely and exclusively licensed by the Publisher, whether the whole or part of the material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation, broadcasting, reproduction on microfilms or in any other physical way, and transmission or information storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now known or hereafter developed. The use of general descriptive names, registered names, trademarks, service marks, etc. in this publication does not imply, even in the absence of a specific statement, that such names are exempt from the relevant protective laws and regulations and therefore free for general use. The publishers, the authors, and the editors are safe to assume that the advice and information in this book are believed to be true and accurate at the date of publication. Neither the publishers nor the authors or the editors give a warranty, express or implied, with respect to the material contained herein or for any errors or omissions that may have been made. The publishers remain neutral with regard to jurisdictional claims in published maps and institutional affiliations. This Springer imprint is published by the registered company Springer Nature Singapore Pte Ltd. The registered company address is: 152 Beach Road, #21-01/04 Gateway East, Singapore 189721, Singapore

Foreword by Bin Shi

The book Matrix Discrete Element Analysis of Geological and Geotechnical Engineering by Dr. Chun Liu has now been completed. As his research supervisor, I congratulate him on completing this monograph in such a short period of time after graduation. I am immensely proud of his achievements in the theoretical research and system development of the matrix discrete element computing method, and the applications in geological and geotechnical engineering fields. In 2002, Dr. Chun Liu entered the Department of Geological Engineering, the School of Earth Sciences and Engineering, Nanjing University. At the undergraduate level, he exhibited considerable talent in computer programming and applications. In 2007, he became a postgraduate and remained in the school after graduation. Based on his strengths and in combination with the National Natural Science Foundation of China, we advised him on research topic selection, overseas study, and research conditions and supported him in theoretical research, system development, and engineering applications of the discrete element method. After 10 years of effort, he announced the release of the high-performance discrete element software MatDEM at the Discrete Element Conference led by the Chinese Society of Rock Mechanics and Engineering and Nanjing University in May 2018. Over the past years, MatDEM has been downloaded thousands of times by more than 30 nations and regions. Furthermore, an increasing number of applications have appeared in the fields of geology, geotechnical, water conservancy, agriculture, and physics. MatDEM is highly regarded by peers and has strong development prospects. The core technology of MatDEM is a high-performance matrix discrete element method and a discrete element material auto-training method. The software is based on the author’s original matrix discrete element method, which can handle millions of discrete elements in one computer, and promotes discrete element numerical simulations from sample scales to engineering practices. Moreover, the automatic material training method greatly reduces the difficulty of modeling and contributes to rapid popularization and application of the software. The software, which includes the pre-processing, numerical calculation, post-processing, and secondary development, can establish all types of numerical models and simulate complex large deformation failure and multi-field coupling processes. v

vi

Foreword by Bin Shi

The book systematically introduces the basic theory, calculation methods, and modeling process of MatDEM, along with other examples in the geological and geotechnical engineering, including landslide, land subsidence, pile–soil action, and tunnel excavation. The book provides information on the theory, method, and practice required for the discrete element modeling and numerical simulation of geological and geotechnical engineering. Therefore, it is of vital scientific value and has immense significance in the field of engineering. The successful research and application of MatDEM have greatly improved the core competitiveness in discrete element software. I sincerely hope that Dr. Chun Liu will continue to strive to improve the function and quality of MatDEM to produce a high-performance discrete element software with completely independent intellectual property rights and international competitiveness. This will serve to meet the demands of the industry as well as the progress of science and technology of human beings. Above is the preface.

Nanjing, China

Bin Shi

Foreword by Y. T. Feng

Particles are widespread in the physical world, ranging from tiny powders, fine sands, to grains and railway ballasts, and further to rocks. The contact and interaction of a large number of particles can produce a dynamic system exhibiting very complicated overall behavior. The motion of granular materials is listed by the Science journal as one of the 125 most challenging scientific problems in the human society. Investigating and understanding the behavior of particles have been receiving growing attention both in the academic community and in various industrial sections. The discrete element method has proved to provide a powerful tool to study granular materials in various fields, such as geological hazards, geotechnique, chemical processing, agriculture, and manufacturing, to name a few. However, strong and increasing demands of numerically simulating particular systems are still hampered by substantial computational costs associated with the discrete element method. Common solutions are to adopt high-performing parallel computing technologies including GPGPU. Based on an innovative matrix reformulation of the conventional discrete element method, Dr. Chun Liu has developed a high-performing discrete element software, MatDEM, which can effectively model millions of spherical particles on a desktop computer. This matrix-based discrete element method is a unique and novel variation of the method, and can significantly improve the efficiency of the discrete element simulation by fully utilizing high-performing matrix operations and parallel/GPU computing functionalities. This book, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, first introduces basic principles of the spherical discrete element method, and then describes the procedure of using MatDEM to model many practical applications in geological and geotechnical engineering fields, including landslides, ground settlement, pile–soil interaction, and tunnel excavation. Based on the content introduced in this book, various discrete element models can be constructed quickly, and complex large deformation failure and multi-field coupling processes can be simulated. The publication of this book provides a good reference for the theoretical and engineering application research of the discrete element method with MatDEM. The source code for many engineering application cases are included in this book. This makes it convenient for users to develop their own discrete element vii

viii

Foreword by Y. T. Feng

models within MatDEM. The MatDEM development community is growing rapidly. I am sure that Dr. Chun Liu will continue to work on the theory of the discrete element method and the development of the software, and make great achievements in the scientific research and engineering applications of the discrete element method, through cooperation and exchange with experts in various fields.

Swansea, UK

Y. T. Feng

Preface

Numerous problems in the field of geological and geotechnical engineering involve large deformation failure, strain, water, and temperature multi-field coupling, such as landslide hazards, land subsidence, tunnel excavation, and shale gas hydraulic fracturing. Both experimental and field research can effectively identify these problems but incur high costs over a long period and are difficult to implement. By contrast, computer numerical simulation technology is an efficient and recyclable method that can be used to analyze and understand these problems. For instance, Discrete Element Method (DEM) can build a model using stacked and cemented particles to effectively simulate discontinuity, inhomogeneity, large deformation and failure of rock and soil, and can be widely applied in geological and geotechnical engineering and energy mining. The first paper on the discrete element method was written by Cundall and Strack and published in Geotechnique in 1979. It has been cited more than 10,000 times, making it one of the most cited papers in the geological field. In recent years, the discrete element method has been receiving increasing attention, with the increase of large-scale complex engineering constructions and the improvement of the computing technology. However, to be utilized more effectively in engineering practice, the discrete element method encounters still three difficult problems: ➀ the DEM involves a large amount of calculation; however, there are usually less than 100 thousands elements, which restrict its applications in engineering; ➁ the quantitative modeling of the discrete element method is challenging. It is difficult to directly obtain a model with specific elastic modules and strengths, because the relationship between the macroscopic mechanical properties of the stacked model and the mechanical parameters of the elements is unclear; and ➂ the multi-field coupling of DEM is not perfect and lacks corresponding numerical software. Drawing on previous researches, the author developed high-performance discrete element software MatDEM (Matrix DEM) from scratch. To address the three major problems, a series of work was conducted with the goal of large-scale numerical simulations, the generalization of software, and engineering applications: ➀ regarding the large computation, the software can handle millions of elements, by adopting the original matrix discrete element computing method. This will gradually expand the applications of DEM from the sample scale to the engineering scale; ➁ regarding the ix

x

Preface

difficulties in quantitative modeling, the macro-microscopic conversion formulae of the discrete element model are derived and the automatic training of discrete element materials is realized in the software. The discrete element packing model of specialized mechanical property can be acquired automatically, which largely decreases the difficulty of the discrete element model; ➂ regarding the multi-field coupling problems, the numerical simulation of frictional heat generation and energy conservation is realized in the software. Based on the finite difference method, the numerical simulation of heat conduction and thermal coupling is also realized. Further, the discrete element pore density flow method is proposed to realize the fluid–solid coupling numerical simulation. These methods provide a solid theoretical basis for further complex engineering applications. Based on the general MATLAB language, MatDEM provides powerful secondary development functions and can conveniently establish numerical models for various types of problems. Through cooperation with experts and scholars, we continue to promote the generalization and specialization of the software, which, at present, can simulate most geological and geotechnical problems. With the assistance of experts from various fields, the author has developed more than 20 applied examples, including discrete element tests, dynamic processes, slopes and landslides, geotechnical engineering, and multi-field coupling problems. To improve our support services, we also established the MatDEM website: http://matdem.com. Based on website access data, the software provides support in six languages. With the advice and support of experts, the author has written this Chinese and English textbook “Matrix Discrete Element Analysis of Geological and Geotechnical Engineering.” The Chinese version is published by Science Press and the English version by Springer Press. The book is accompanied by corresponding instructional videos and software, all of which are available on the MatDEM website. The book is divided into two parts, the first of which is the basic volume. Chapter 1 introduces the basic theory, calculation methods, and prospective engineering applications of the DEM. For information on the systematic theory and calculation method of DEM, readers should refer to “Introduction to the Mechanics of Particulate Matter” (Qicheng Sun and Guangqian Wang, Tsinghua University), “Computational Particle Mechanics and Engineering Applications” (Shunying Ji, Dalian University of Technology), and other professional books. For more information on the continuous– discontinuous theory, the contact model, and the macro-micro theory of the discrete element method, readers should refer to the related papers and monographs of Shihai Li, a researcher at the Institute of Mechanics of the Chinese Academy of Sciences, and Mingjing Jiang of Tongji University. Chapters 2–5 introduce the basic structure and functions, the modeling process, and post-processing of MatDEM. The data in the software are object oriented, and all calculation data can be viewed, edited, saved, and imported in the software. In the basic volume, the general modeling process, data structure, the concepts and usage of elements, connections, groups, materials, and loads are introduced thoroughly. Most notably, the MatDEM offers

Preface

xi

a post-processing module that conform to commercial software standards, conveniently produces dozens of graphs, and generates GIF animations of numerical simulations. Readers will therefore quickly learn the basic theory of the discrete element method and the operations of the MatDEM. Part II of the book is the application volume. Chapter 6 explains thoroughly the general procedures involved in the modeling and numerical simulation of DEM through three examples: pile–soil interaction, tunnel modeling, and rock breaking with a tunnel boring machine (TBM) cutter. We advise readers to read this chapter first. Using the direct shear box, torsional shear box test, and true triaxial test as examples, Chap. 7 primarily focuses on building components by functions, combining these components, and demonstrating how to create threedimensional complex cracks and joints. Chapter 8 takes three-dimensional landslide modeling as an example to show how to use digital elevation data to build a complex three-dimensional model. Chapter 9 introduces numerical simulations of dynamic effects, including a meteorite impact on the ground, blasting in a slope, and seismic dynamics. Chapter 10 introduces advanced custom parameters and secondary development functions, realizing the numerical simulations of complex multi-field coupling processes, such as ground subsidence, microwave-assisted rock breaking, and energy pile thermal coupling. Thus, in Chaps. 6–10, 13 application examples are introduced. By modifying and integrating these examples, numerical simulations of various geological and engineering problems can be performed, to assist in the analysis and resolution of various scientific and engineering issues. The theoretical research, system development, and application of DEM have proved to be a very long and hard path. In the process of developing the MatDEM and writing this book, substantial help and guidance were received from numerous experts and scholars. The author is particularly grateful to Profs. Bin Shi of Nanjing University and David D. Pollard of Stanford University. The author began learning DEM and developing a discrete element testing software as a postgraduate at Nanjing University in 2007. During a visit to America from 2010 to 2011, he conducted a basic theoretical study of discrete elements under the supervision of Prof. David D. Pollard. After returning to China, under the guidance and robust support of his supervisor, Prof. Bin Shi, he began the research and development of MatDEM software, and numerical simulations of engineering geological problems, during which the MatDEM gradually became a general discrete element software. The author would also like to thank Profs. Baojun Wang, Hongwei Yin, Chaosheng Tang, and Honghu Zhu, and Assoc. Profs. Wei Zhang, Dan Zhang, and Kai Gu for their valuable guidance and assistance. The theoretical part of the book benefited greatly from the expertise of Prof. Fengshou Zhang and Assoc. Prof. Xin Huang from Tongji University; Chun Feng, Associate Researcher of the Institute of Mechanics of the Chinese Academy of Sciences; Associate Researcher Tao Zhao of Sichuan University; Prof. Xiaoping Zhang of Wuhan University; and Assoc. Prof. Bo Zhou of Huazhong University of Science and Technology. They also provided considerable valuable advice on the functionality and versatility of the software. The application volume of this book benefited

xii

Preface

from the expertise of Profs. Qiang Xu and Xuanmei Fan from Chengdu University of Technology, Qiangong Cheng from Southwest Jiaotong University, Qing Lv from Zhejiang University, Assoc. Prof. Yadong Xue from Tongji University, Dr. Shang Deng from the China Petroleum & Chemical Corporation Petroleum Exploration and Development Research Institute, Assoc. Prof. Fanyu Zhang from Lanzhou University, Prof. Changdong Li from China University of Geosciences, Assoc. Prof. Xiaolei Liu from Ocean University of China, and Assoc. Prof. Zhixiong Chen from Chongqing University. The author would like to thank all these experts for providing strong theoretical supports and ideal practical conditions for the development of MatDEM and its subsequent engineering applications. The author is particularly grateful to academician Yong Chen of Nanjing University, academician Zhisheng An of the Institute of Earth Environment of the Chinese Academy of Sciences, and Prof. Rucheng Wang of Nanjing University for their important help in software development and in the publication of the book. The author would also like to thank Prof. Xiating Feng of Northeastern University; Prof. Jianbing Peng of Chang’n University; Prof. Yonggang Jia of Ocean University of China; Shihai Li, Researcher at the Institute of Mechanics, Chinese Academy of Sciences; Prof. Mingjing Jiang of Tongji University; Prof. Jiaochu Peng of China Institute of Water Resources and Hydropower Research; Guangqi Chen of Kyushu University; Prof. Jianfu Shao from Lille University of Technology, France; Prof. Yufeng Gao from Hohai University; and Prof. Jianjing Zhang from Southwest Jiaotong University, all of whom made valuable suggestions regarding the development of the software. The research content of this book benefited from financial supports from the National Natural Science Foundation of China, which is under the responsibility of Prof. Bin Shi of Nanjing University, “Research on deformation response and catastrophic mechanism of soil structure system based on distributed sensing” (41230636), National Natural Science Foundation—General Program (41977218), National Natural Science Foundation—Sino-German Cooperation Program (41761134089), National Natural Science Foundation—Youth Program (41302216), China Association for Science and Technology—Young Elite Scientist Sponsorship Project (2016QNRC001), Jiangsu Natural Science Foundation Project (BK20170393, BK20130377), National Laboratory for Marine Science and Technology (Qingdao) Open Fund Project (QNLM2016ORP0110), and the Suzhou Science and Technology Project (SYG201614). The research presented in this book has been strongly supported by the School of Earth Sciences and Engineering of Nanjing University; the Advanced Computational Engineering Institute for Earth Environment of Nanjing University; and the Institute of Earth Exploration and Sensing, Nanjing University. The author would also like to thank the Chinese Society of Rock Mechanics and Engineering for their supports in the software training and promotion. Graduate students Xiaoyu Zhang, Yan Qin, Yehuan Huang, and Tiancheng Le were involved in the development and testing of several examples as well as writing some chapters of this book. Specifically, Yan Qin participated in writing Chaps. 3, 5, 6.2, 9.1, and 10.2; Xiaoyu Zhang participated in writing Chaps. 2, 5, and 8; Tiancheng Le participated in writing Chap. 2, Sect. 6.1, and Chap. 7; and

Preface

xiii

Yehuan Huang participated in writing Sect. 9.3 and revised most of the chapters. In the process of writing this book, graduate students Qiang Tang, Chenguang Zhu, Liwei Liang, Yao Zhu, Hui Liu, and Xiaowei Yang also participated in data collation, revision work, and maintained the software website and the WeChat public account. Since the MatDEM was released and opened to public in 2018, hundreds of experts, scholars, and graduate students have participated in the testing and application of the software, which continuously promoted the development of the software. I would like to express my sincere thanks to all of you! Graduate students Yudong Kou, Jichen Li, Guoqing Xia, Yue Wang, Fei Xie, and Liwei Zhang assisted in translating the book from Chinese to English. Tiansheng Zhang, Huan Geng, Bing Yuan, Hongyong Zhang, Xuerui Quan, and Guansheng Fan assisted in the proofreading of the book. Nanjing, China August 2020

Chun Liu

About This Book

The discrete element method can effectively simulate the discontinuity, inhomogeneity, and large deformation damage of rock and soil. It is widely used in both research and industry. Based on the innovative matrix discrete element computing method, the author developed the high-performance discrete element software MatDEM from scratch, which can handle millions of elements in discrete element numerical simulations. This book introduces the basic structure, modeling methods, numerical calculation processes, post-processing, and system functions of MatDEM, which applies the basic principles and algorithm of the discrete element method. It also presents several examples of applications in geological and geotechnical engineering, including basic geotechnical engineering problems, discrete element tests, three-dimensional landslides, and dynamic and multi-field coupling functions. Teaching videos and the relevant software can be accessed on the MATDEM website (http://matdem.com). The book will serve as a useful reference for research and engineering staff, undergraduates, and postgraduates who work in the fields of geology, geotechnical, water conservancy, civil engineering, mining, and physics.

xv

Contents

1

2

Principles and Implementation of DEM . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 Application and Numerical Calculation Software of DEM . . . . . . 1.2 Basic Principles of DEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.1 Contact Model of Elements . . . . . . . . . . . . . . . . . . . . . . . . 1.2.2 Connection of Two Different Elements . . . . . . . . . . . . . . . 1.2.3 Time Step Iterative Algorithm . . . . . . . . . . . . . . . . . . . . . . 1.3 Damping Harmonic Vibration of Elements . . . . . . . . . . . . . . . . . . . 1.3.1 Damping Force of Elements . . . . . . . . . . . . . . . . . . . . . . . . 1.3.2 Equation of the Damping Harmonic Vibration . . . . . . . . 1.3.3 Relation Between Vibration Period and Element Radius . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3.4 Differences of the Element Motion . . . . . . . . . . . . . . . . . . 1.3.5 Damping and Optimal Damping Coefficient . . . . . . . . . . 1.4 Energy Conversion and Energy Conservation of DEM . . . . . . . . . 1.4.1 Mechanical Energy of Systems . . . . . . . . . . . . . . . . . . . . . 1.4.2 Calculation of Heat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.4.3 Energy Conservation and External Work . . . . . . . . . . . . . 1.5 Calculation Scale and Engineering Application Feasibility of DEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6 Understanding and Solution to the Three Major Issues in DEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6.1 High-Performance Matrix Computing of the Discrete Element Method . . . . . . . . . . . . . . . . . . . . . 1.6.2 Quantitative Modeling Problem of DEM . . . . . . . . . . . . . 1.6.3 Multi-field Coupling Method Based on DEM . . . . . . . . . 1.7 Development and Prospect of MatDEM . . . . . . . . . . . . . . . . . . . . . References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Basic Structure of MatDEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 The Software Foundation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.1 The Operating Environment and Software Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1 1 3 3 5 6 6 6 7 8 8 9 11 11 12 15 15 17 17 18 21 22 24 27 27 27 xvii

xviii

Contents

2.1.2 2.1.3 2.1.4

2.2

2.3

2.4

2.5

2.6

3

The Windows Program for MatDEM . . . . . . . . . . . . . . . . Operation and Termination of the Software . . . . . . . . . . . A Brief Introduction to the Application of the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.5 A Brief Introduction to the Help File . . . . . . . . . . . . . . . . The Program Structure of MatDEM . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1 The Software Folders of MatDEM . . . . . . . . . . . . . . . . . . 2.2.2 The Hierarchical Structure of MatDEM . . . . . . . . . . . . . . 2.2.3 The Main Classes in MatDEM . . . . . . . . . . . . . . . . . . . . . . Types of Element in MatDEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3.1 Active Element, Wall Element, and Virtual Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3.2 Fix the Degree of Freedom of Elements . . . . . . . . . . . . . . 2.3.3 The Rule of Numbering Elements . . . . . . . . . . . . . . . . . . . The Data Structure of MatDEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.1 The Property Arrays of Elements . . . . . . . . . . . . . . . . . . . . 2.4.2 The Neighbor Matrix and Connection Information Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.3 The Data Structure and Operation of Groups . . . . . . . . . . The Contact Model Between Elements . . . . . . . . . . . . . . . . . . . . . . 2.5.1 The Linear Elastic Contact Model . . . . . . . . . . . . . . . . . . . 2.5.2 The Hertz Contact Model . . . . . . . . . . . . . . . . . . . . . . . . . . The Elastic Clump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.6.1 The Principle of the Elastic Clump . . . . . . . . . . . . . . . . . . 2.6.2 Usage of the Elastic Clump . . . . . . . . . . . . . . . . . . . . . . . .

Geometric Modeling and Material Setup . . . . . . . . . . . . . . . . . . . . . . . . 3.1 Building a Numerical Simulation Box . . . . . . . . . . . . . . . . . . . . . . . 3.1.1 Building a Packing Model . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2 Creating an Empty Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 The Foundation of Modular Modeling . . . . . . . . . . . . . . . . . . . . . . . 3.2.1 Modeling with a Structure . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.2 Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.3 Tool_Cut and Digital Elevation Model . . . . . . . . . . . . . . . 3.3 Modeling Based on Digital Images . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1 Importing a Binary Image to Cut a Model . . . . . . . . . . . . 3.3.2 Block Modeling by Importing a Color Image . . . . . . . . . 3.4 Material Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.1 Overview of Material Setting . . . . . . . . . . . . . . . . . . . . . . . 3.4.2 Input the Material Properties Directly . . . . . . . . . . . . . . . . 3.4.3 Automatic Training of Materials . . . . . . . . . . . . . . . . . . . . 3.5 Balance Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1 Iterative Calculation Function and Standard Balance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2 Strong Bond Balance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

29 32 34 35 36 36 37 38 41 41 42 43 43 43 44 47 49 49 49 51 51 53 57 57 57 61 62 62 67 69 71 71 73 78 78 79 79 83 83 85

Contents

3.5.3 Neighbor Searching and Zero Balance . . . . . . . . . . . . . . . 3.5.4 Standard of Judgment for a Model Balance State . . . . . . Setting of Cracks and Joints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1 Setting Weak Layers and Cracks Through Groups . . . . . 3.6.2 Using Triangle Faces to Set Cracks and Joints . . . . . . . . . 3.6.3 Using Tool_Cut to Set Cracks and Joints . . . . . . . . . . . . . 3.6.4 Definition and Use of the Connection Filter . . . . . . . . . . .

86 87 88 88 90 90 91

Load Settings and Numerical Calculations . . . . . . . . . . . . . . . . . . . . . . . 4.1 The Initialization and Settings of Numerical Calculation . . . . . . . 4.1.1 The Initialization of Model Parameters . . . . . . . . . . . . . . . 4.1.2 Setting of Relevant Parameters in Calculation . . . . . . . . . 4.2 Boundary and Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.1 Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.2 Stress Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.3 Displacement Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.4 Vibration Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.5 Other Loads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Time and Settings of Iterative Calculation . . . . . . . . . . . . . . . . . . . . 4.3.1 Running Time of Iterative Calculation . . . . . . . . . . . . . . . 4.3.2 Radius of Elements and Time of Calculation . . . . . . . . . . 4.3.3 Settings for Dynamic Issues . . . . . . . . . . . . . . . . . . . . . . . . 4.3.4 Setting and Simulation Accuracy of Quasi-Static Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4 Definition and Modification of Simulated Parameters . . . . . . . . . . 4.4.1 Creation of Custom Parameters . . . . . . . . . . . . . . . . . . . . . 4.4.2 Modification of Element Properties in a Group . . . . . . . . 4.4.3 Settings of Time Step, the Radius of Elements, and Stiffness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.5 Compression, Saving, and Reading of Files . . . . . . . . . . . . . . . . . . 4.5.1 Compression of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.5.2 Saving and Reading of Files . . . . . . . . . . . . . . . . . . . . . . . .

93 93 93 94 94 95 96 98 99 100 101 101 103 105

Post-processing and System Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1 Post-processing Window Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1 Main Post-processing Window . . . . . . . . . . . . . . . . . . . . . . 5.1.2 Saving the Post-processing Figure . . . . . . . . . . . . . . . . . . . 5.1.3 Making GIF Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 Post-processing Drawing Functions . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.1 General Drawing Function d.show . . . . . . . . . . . . . . . . . . 5.2.2 Basic Display Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.3 Slice Display and Filter Display . . . . . . . . . . . . . . . . . . . . . 5.2.4 Element Position and Force Display . . . . . . . . . . . . . . . . . 5.3 Data Processing and Curve Drawing . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1 Drawing Curves with Saved Data . . . . . . . . . . . . . . . . . . .

117 117 117 119 120 122 122 127 128 131 132 132

3.6

4

5

xix

106 108 108 109 111 113 113 114

xx

Contents

5.3.2

5.4

5.5

6

7

Drawing Curves with MatDEM Automatically Recorded Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.3 Processing Data and Plotting in MATLAB . . . . . . . . . . . . System Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1 GPU Computing Settings and Status Viewing . . . . . . . . . 5.4.2 Definition and Operation of Functions . . . . . . . . . . . . . . . 5.4.3 Batch Processing of Code Files . . . . . . . . . . . . . . . . . . . . . 5.4.4 Random Seed and Stochastic Model . . . . . . . . . . . . . . . . . 5.4.5 Timing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modeling with System Underlying Functions . . . . . . . . . . . . . . . . . 5.5.1 Underlying Modeling of the Two-Ball Collision Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.2 Use Graphs to Analyze Collision Processes . . . . . . . . . . .

133 135 136 136 137 139 140 140 141 141 144

Basic Application of Geotechnical Engineering . . . . . . . . . . . . . . . . . . . 6.1 Pile–Soil Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.1 Packing Model of Particles . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.2 Build a Pile-Soil Interaction Model . . . . . . . . . . . . . . . . . . 6.1.3 Numerical Simulation of the Pile Pulling Process . . . . . . 6.2 Tunnel Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.1 Packing Model of Particles . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.2 Build a Tunnel Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.3 Loading and Numerical Simulation . . . . . . . . . . . . . . . . . . 6.3 TBM Cutter Rock Breaking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.1 Packing Model of Particles . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.2 Build a Model of TBM Cutter Rock Breaking . . . . . . . . . 6.3.3 Numerical Simulation Process of Rock Breaking with Hob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.4 Improve the Calculation Speed of Rock Breaking with Hob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

147 147 147 150 155 157 158 158 163 165 165 166

Rock–Soil Body Discrete Element Tests . . . . . . . . . . . . . . . . . . . . . . . . . . 7.1 Direct Shear and Torsional Shear Tests . . . . . . . . . . . . . . . . . . . . . . 7.1.1 Define Test Parameter and Accumulate Sample . . . . . . . 7.1.2 Making a Shear Box and Cutting Sample . . . . . . . . . . . . . 7.1.3 Putting the Sample into the Shear Box . . . . . . . . . . . . . . . 7.1.4 Material Setting and Numerical Simulation . . . . . . . . . . . 7.2 True Triaxial Test and Joint Modeling . . . . . . . . . . . . . . . . . . . . . . . 7.2.1 Build a True Triaxial Test Chamber . . . . . . . . . . . . . . . . . . 7.2.2 Defining Fracture Surface Using Triangle Faces and Polygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2.3 Defining Complex Joint Surfaces Using Tool_Cut . . . . . 7.2.4 Applying True Triaxial Stress . . . . . . . . . . . . . . . . . . . . . . .

175 175 175 176 181 184 187 187

171 174

189 192 196

Contents

8

xxi

Modeling of Complex 3D Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.1 Defining 3D Surfaces with Digital Elevation . . . . . . . . . . . . . . . . . 8.1.1 Defining Digital Elevation Model Using Discrete Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.1.2 Processing of Digital Elevation Data at the Surface . . . . 8.2 Building a Thin Shell Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.1 Building a Geometric Model . . . . . . . . . . . . . . . . . . . . . . . 8.2.2 Cutting and Packing Model . . . . . . . . . . . . . . . . . . . . . . . . 8.3 Building a Three-Dimensional Slope Model . . . . . . . . . . . . . . . . . . 8.3.1 Import Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.3.2 Set the Material for the Stratum . . . . . . . . . . . . . . . . . . . . . 8.4 Numerical Simulation of Landslide’s Motion Process . . . . . . . . . . 8.4.1 Setting of Numerical Simulation Parameters . . . . . . . . . . 8.4.2 Iterative Calculations and Simulation Results . . . . . . . . .

199 201 207 208 210 214 214 214 217 217 218

Numerical Simulations of Dynamic Action . . . . . . . . . . . . . . . . . . . . . . . 9.1 Meteorite Impact on the Earth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.1 Packing Model of Particles . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.2 Building a Meteorite Model . . . . . . . . . . . . . . . . . . . . . . . . 9.1.3 Simulation of Meteorite Impact Process . . . . . . . . . . . . . . 9.2 Mine Slope Blasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.1 Slope Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.2 Setting the Blasting Point and Blasting Energy . . . . . . . . 9.2.3 Iterative Calculations and Simulation Results . . . . . . . . . 9.3 Seismic Wave Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3.1 Establishment of Topography and Stratification . . . . . . . 9.3.2 The Generation and Propagation of Seismic Waves . . . .

221 221 222 222 226 229 229 231 233 235 235 238

10 Multi-field Coupling Numerical Simulation . . . . . . . . . . . . . . . . . . . . . . 10.1 Friction Heat Generated by Landslide Slipping . . . . . . . . . . . . . . . 10.2 Microwave-Assisted Rock Breaking . . . . . . . . . . . . . . . . . . . . . . . . 10.2.1 Building a Clump Packing Model . . . . . . . . . . . . . . . . . . . 10.2.2 Grouping and Material Setting of Pyroxene and Feldspar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.2.3 Numerical Simulation of Pyroxene Thermal Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.3 Thermal Coupling of Energy Pile . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.3.1 Establish an Energy Pile-Stratum Model . . . . . . . . . . . . . 10.3.2 Numerical Simulation of Thermal Coupling Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.4 Ground Subsidence and Ground Fissures . . . . . . . . . . . . . . . . . . . . 10.4.1 Cutting the Stratum Model . . . . . . . . . . . . . . . . . . . . . . . . . 10.4.2 Numerical Simulation of the Decline of Water Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

243 243 245 245

9

199 199

247 251 253 254 257 261 261 262

xxii

Contents

Appendix A: Properties of Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Appendix B: Main Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 Appendix C: Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

About the Author

Dr. Chun Liu graduated from Nanjing University in 2012, and received the “Excellent Doctoral Dissertation Award of Jiangsu Province” in 2013. After the postdoctoral research at Stanford University, he joined Nanjing University as an Associate Professor in 2014. Since 2019, he served as the Vice President of the Institute of Earth Exploration and Sensing of Nanjing University and the Deputy Director of the Youth Committee of Chinese Society of Rock Mechanics and Engineering. He has been engaged in the research in the field of computational engineering geology, and has made rich achievements in the theoretical research and system development of the discrete element method, and its application in engineering. He has developed the high-performance discrete element software MatDEM (http://matdem. com), which has been widely used in geology, geotechnical engineering, energy, chemical industry, and other fields. Until 2020, he has participated in the researches of nine projects of National Natural Science Foundation of China. In 2017, he was selected into the “Young Elite Scientist Sponsorship Program” of the China Association for Science and Technology and the “Six Talent Peaks” high-level talent selection and training funding plan of Jiangsu Province, etc.

xxiii

Chapter 1

Principles and Implementation of DEM

This chapter introduces the basic principle of the discrete element method (DEM), and its applications in researches and engineering practice. Specifically, it includes the application fields and the basic principle of the DEM, the damped simple harmonic vibration of the element, the energy conversion and energy conservation in the discrete element system, etc. The calculation scale of the discrete element method, the feasibility of engineering applications, and the three major problems of application of the discrete element method is discussed. At last, the development history and prospects of the MatDEM are introduced.

1.1 Application and Numerical Calculation Software of DEM The discrete element method (DEM) was first proposed by Cundall and Strack (1979) to study the motion and interaction of elements. In recent years, in line with the development of discrete element theory and the advancement of computer technology, the DEM has been widely used in various fields (Xu et al. 2003), including the simulation of grain accumulation in agriculture (Jia et al. 2014), ore crushing in mining, metallurgy and grain mixing in industrial production, research on the mechanical properties of grain accumulation in solid mechanics (Goldenberg and Goldhirsch 2005), and the formation and evolution of various geological structures (Antonellini and Pollard 1995; Hardy and Finch 2006; Hardy and Finch 2010; Liu et al. 2015). Macroscopically, a rock and soil mass is relatively continuous. Microscopically, it is a structural system consisting of a series of particles, pores, and fissures. Discrete and discontinuous problems at a microscopic level are difficult to solve using conventional continuum mechanics-based methods. The DEM is therefore useful because it builds models by stacking and cementing elements that can naturally simulate the discontinuity and unevenness of a rock and soil mass and thus can be applied to the analysis of various geological and geotechnical engineering problems (Jiao 1999). © The Author(s), under exclusive license to Springer Nature Singapore Pte Ltd. 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9_1

1

2

1 Principles and Implementation of DEM

On a macroscopic scale, the DEM can effectively simulate geological disasters such as landslides or collapses, and provides a reference with which to predict the possibility of disasters and evaluate the possible damage (Jiao et al. 2000; Qu et al. 2016). The DEM can also be used to study the law of seismic wave propagation and the impact of earthquakes (Feng et al. 2012; Shi et al. 2013). By applying specific triaxial stress to rock, DEM accurately simulates the deformation and damage that occurs among rocks under considerable pressure (Li et al. 2018). Furthermore, in complex geological conditions, processes or phenomena that are difficult to study through physical experiments, such as extreme conditions of high temperature, high pressure and fluid, hydraulic fracturing and rock burst processes, can be studied by establishing appropriate discrete element models, and adjusting and validating these through laboratory experiments (Xu et al. 2011; Gu et al. 2016). At both meso- and micro-scales, the DEM is used to simulate test processes employed in rock and soil mechanics. It can therefore quantitatively analyze microstructure and micromechanical mechanisms underlying the macroscopic deformation and failure of rock and soil mass (Li et al. 2003; Li et al. 2004a, b; Jiang et al. 2012; Jiang et al. 2014). Among the questions it addresses are how do the mechanical properties of elastic modulus and strength of rocks relate to microscopic particle gradation, size, distribution, bulk density, cement strength, and crack distribution? Which micromechanical properties of elements are related to macroscopic elastic-plastic and creep properties of soil mass? The major commercial software for discrete elemental numerical analysis worldwide includes PFC (Zhou et al. 2016) and EDEM (Wang et al. 2016). Open-source software includes Yade, Esys-Element, and LIGGGHTS (Kozicki and Donze 2008; Kloss and Goniva 2011). PFC is a numerical calculation software developed by the Itasca Company of the United States. Its original code was written by Professor Cundall, who is the father of DEM. It then developed into PFC2D and PFC3D, which are mainly used in the fields of mining, geotechnical, and earth sciences. EDEM is the flagship product of DEM Solutions in the United Kingdom. It was originally developed and maintained by researchers at the University of Edinburgh. It is mainly used for the simulation analysis of grain processing and production operations in the industrial field. Yade is the most widely used community-driven open-source software and is written in C++ and Python. After more than a decade of development, many excellent discrete element software programs have been designed in China, including 2D-Block, GDEM, SDEM, StreamDEM, and DICE2D. 2D-Block is a two-dimensional discrete element software program developed by Wang et al. (2000) based on Visual C++ 6.0. GDEM is a software jointly developed by the Joint Laboratory of Discontinuous Media Mechanics and Engineering Disasters, Chinese Academy of Sciences and GDEM Technology, Beijing Co., Ltd. Based on the DEM of continuum mechanics, GDEM realizes the entire simulation process from continuous deformation to fracture motion. SDEM was jointly designed and developed by the computational element mechanics team of the Dalian University of Technology and the team at Dizaosoft, Dalian Co., Ltd and can effectively simulate the failure process in brittle materials such as sea ice and rocks (Ji et al. 2012, Ji 2018). StreamDEM is a large-scale commercial software launched by the CISDI Group Co., Ltd and can

1.1 Application and Numerical Calculation Software of DEM

3

be used in metallurgy, mining, and mechanical engineering. DICE2D is an opensource discrete element software program developed by Professor Gaofeng Zhao of Tianjin University. Its original intention was to provide an easy-to-use discrete element source code that would enable graduate students to master the underlying principles and development of the discrete element method in a short time (Zhao 2015). Nanjing University independently developed a high-performance discrete element software program for rock and soil mass, the “MatDEM,” i.e., matrix computing of the discrete element method (Liu et al. 2014). By using an innovative matrix computing of DEM and 3D contact algorithm, MatDEM facilitates the high-performance discrete element numerical simulation of millions of elements, which allows the engineeringscale numerical simulation of the DEM. Based on an original theory, MatDEM realizes the discrete element material automatic modeling and energy conservation calculation of discrete element systems. It integrates pre-processing, calculation, post-processing, and powerful secondary development; provides a complete function interface; and can complete complex multi-field coupling numerical simulations through secondary development. MatDEM has been applied to the simulation of a series of problems such as landslides, rock bursts, impact damage, pile–soil action, tunnel issues, and hydraulic fracturing (Gu et al. 2016; Liu et al. 2017; Suo et al. 2017). By perfecting the simulation of multi-field coupling and fluid–solid coupling, MatDEM provides efficient numerical simulation technological support for largescale engineering construction.

1.2 Basic Principles of DEM The DEM builds a geotechnical model by stacking and cementing a series of elements with specific mechanical properties (Sun et al. 2009; Jiang et al. 2013). Numerical simulation is then performed using a time step iterative algorithm.

1.2.1 Contact Model of Elements As shown in Fig. 1.1a, the DEM constructs a geotechnical model by depositing and cementing a series of elements with specific mechanical properties. In the most basic linear elastic model, it is assumed the elements interact with each other via spring forces. The normal force (Fn ) and normal deformation (X n ) between two elements can be simulated by a normal spring (Mora and Place 1993):

4

1 Principles and Implementation of DEM

Fig. 1.1 Schematic diagram of the linear elastic model

⎧ ⎨ K n X n X n < X b , intact bond (a) Fn = K n X n X n < 0, broken bond (b) ⎩ 0 X n ≥ 0, broken bond (c)

(1.2.1)

where K n is the normal stiffness of the spring, X n is the normal relative displacement (Fig. 1.1b), and X b is the breaking displacement. Initially, elements are interconnected with their adjacent elements and subjected to tensile or compressive spring forces (Eq. 1.2.1). When X n between the two elements exceeds the breaking displacement (X b ), the spring breaks and the inter-element tensile force is no longer existing between them (Eq. 1.2.1c); however, the compressive force may act between them when they return to a compressive status (Eq. 1.2.1b). Shear force (Fs ) and shear deformation (X s ) between elements are simulated by tangential springs (Place and Mora 1999): Fs = K s X s

(1.2.2)

where K s is the shear stiffness and X s is the shear relative displacement. The spring also has a failure criterion in the tangential direction, which is based on the Mohr–Coulomb criterion: Fsmax = Fs0 − μp Fn

(1.2.3)

where Fsmax is the maximum shear force; Fs0 is the inter-element initial shear resistance; and μp is the inter-element coefficient of friction. In the Mohr–Coulomb criterion, the maximum shear resistance between elements is related to the initial shear resistance (Fs0 ). Fs0 is the maximum shear force allowed between elements without applying normal pressure. It is similar to the cohesion found in a rock and

1.2 Basic Principles of DEM

5

soil mass. And as we know, the greater the normal stress, the greater the shear resistance. When the magnitude of the shear force exceeds the maximum shear force determined by Eq. 1.2.3, the tangential connection is broken, and only the sliding friction force (-μp Fn ) acts between the elements. In a numerical simulation, a normal spring and a tangential spring are used to simulate the cementation between elements in the real world, such as iron and calcium cement. Thus, the breakage of normal spring corresponds to the failure of cementation in the real world, and therefore the tangential spring should also be broken, vice versa. In accordance with a linear elastic contact model, the packing model has overall elastic characteristics. Different contact models need to be defined when simulating elastoplastic, creep, and other properties of the material. For example, for elastoplastic materials, each element is defined as approximately elastoplastic. Macromicroscopic research is a very important branch of DEM research. Depending on the macroscopic mechanical properties of the material, a suitable element contact model and corresponding parameters should be applied (e.g., Li et al. 2004a, b; Jiang et al. 2005; Shen et al. 2011; Jiang et al. 2013; Jiang and Shen 2016; Feng et al. 2016; Jiang 2019).

1.2.2 Connection of Two Different Elements The stiffness mentioned previously is the stiffness (K n ) of the connection between elements, and each element has its own stiffness (kn ). When two elements are in contact, the K n denotes the stiffness of two series springs. For two elements with normal stiffness of kn1 and kn2 , the equivalent stiffness (K n ) of their connection is Kn =

kn1 kn2 kn1 + kn2

(1.2.4)

For two elements with shear stiffness ks1 and ks2 , the equivalent shear stiffness (K s ) of the connection is Ks =

ks1 ks2 ks1 + ks2

(1.2.5)

Similarly, each element has its own breaking displacement and friction coefficient, and the mechanical properties of the connection depend on the smaller tensile or shear resistance of the elements. Therefore, if the stiffnesses of two elements are the same, the stiffness (K n , K s ) of the series springs is half that of each element (kn , ks ), whereas the breaking displacement (X b ) of the series connection is twice that of each element (xb ). A numerical calculation therefore incorporates the stiffness and breaking displacement of the element to obtain the mechanical properties of the connection.

6

1 Principles and Implementation of DEM

1.2.3 Time Step Iterative Algorithm Based on obtaining the force of each element, the displacement of the element is calculated using a time step iteration algorithm. The time step dT is usually small (refer to Sect. 1.3.4 for details) and is set to calculate the force, acceleration, velocity, and displacement of elements. Once the current time step calculation is completed, a time step is advanced to implement a new iteration of the DEM. The detailed calculation process is as follows: firstly, calculate the current acceleration of elements via dividing the known resultant force by the mass based on the traditional Newtonian mechanics; then, in the current step time dT, we can obtain the initial velocity of the next time step by adding the current velocity plus the velocity increment (the acceleration multiplied by the time), and then calculate the corresponding element displacement; finally, run a new iterative calculation to realize the dynamic simulation of the DEM. For example, if a small displacement is applied to the upper surface of a cubic discrete element model, the first layer of elements on the upper surface will move downward slightly and push downward the adjacent lower elements. Through time step iterations, stress wave propagation can be generated as the force is transmitted to the bottom side. Therefore, concepts of time and motion, such as those existing in the real world, are present in the numerical simulation of DEM.

1.3 Damping Harmonic Vibration of Elements 1.3.1 Damping Force of Elements In the real world, force is often accompanied by the generation and dissipation of stress waves. For instance, when a 1-meter-height desk is pushed by hand, the surface of the desk is subjected to stress waves, which will propagate downward due to the applied force. Assuming the wave travel down to the ground at a speed of 1000 m/s, it will take 0.001 s for the effect of pushing hand transmit to the ground. This shows that the effect of a new applied force is not generated simultaneously and that stress waves exist during the process. When a stress wave propagates in the medium, its energy gradually dissipates and it is converted into heat due to friction and scattering effect. When stress waves propagate in a geological body, macroscopic faults, fissures and joints, microscopic micro-cracks, and defects will convert mechanical energy into heat. At the same time, the presence of fluid creates resistance to the movement of the elements and accelerates the consumption of wave energy. Actually, the DEM simulates physical processes in the real world. For instance, stress waves are also generated in numerical simulations, and the essence of such waves is the transmission of mechanical energy (mainly kinetic energy and elastic strain energy). Furthermore, the DEM also needs to simulate the process of energy dissipation in the real world, and to avoid the accumulation of stress wave energy

1.3 Damping Harmonic Vibration of Elements

7

in the system. The dissipation of mechanical energy is typically simulated by introducing the damping (i.e., viscosity). There are several ways to define damping, in which the global damping (Fv ) is a simple way to define damping forces (Liu et al. 2013): Fv = −ηx 

(1.3.1)

where x’ is the element velocity at the current moment and η is the viscosity. Therefore, the damping force on the element is equal to the damping coefficient times the velocity, and its direction is opposite to the velocity direction. This definition of damping force is adopted by MatDEM. For other definitions, such as the unbalanced force method, please see relevant literatures. In the DEM, the damping force on the element represents the effect of fluid viscosity in the real world and the energy consumption (such as micro-cracks and defects) of an element on a smaller scale, whereas energy consumption of the element on a larger scale can be realized naturally through the friction between elements. For quasi-static, dynamic, and impact problems, different damping forces should be set in order to obtain accurate results efficiently.

1.3.2 Equation of the Damping Harmonic Vibration In MatDEM, the linear elastic contact model (Sect. 1.2.1) is adopted by default, and global damping (Sect. 1.3.1) is adopted to consume energy. Essentially, the movement of elements in MatDEM can be summarized as the damping harmonic vibration of a spring oscillator. The equation of the vibration motion is mx  + ηx  + kx = 0

(1.3.2)

where m is the element mass, x is the element acceleration, x is the element velocity, and k is the spring stiffness. The equation indicates that the product of the element mass and the acceleration, plus the damping force and the spring force, is equal to zero. This is the equilibrium equation for damping harmonic vibration, which follows the rules of Newtonian physics. The equation has the following analytical solution: αt

x = (c1 cos βt + c2 sin βt)e ,

η , α=− 2m

 β=

k − η2 /(4m) m

(1.3.3)

Finally, the formula for calculating the period (T η ) of the damping harmonic vibration can be obtained as follows:  m 2π = 2π (1.3.4) Tη = β k − η2 /(4m)

8

1 Principles and Implementation of DEM

This formula contains two important clues: ➀ the vibration period is related to element mass, stiffness, and damping coefficient: the vibration period increases with an increasing element mass (or density), a decreasing stiffness, or an increasing damping coefficient; ➁ there is a critical damping (ηc ), which produces an infinite √ period, ηc = 4mk. When the damping coefficient is 0, we get the equation of harmonic vibration  m (1.3.5) T = 2π k

1.3.3 Relation Between Vibration Period and Element Radius Regardless of the shear force between the elements, the vibration period of elements can be defined by normal stiffness. According to the normal stiffness (K n ) formula for the close-packed model (Sect. 1.6.2), the normal stiffness of the element is √ 2Er k= 1 − 2ν

(1.3.6)

where r is the element radius; E is the Young’s modulus of the overall model; and ν is Poisson’s ratio. The larger the element radius, the greater the stiffness. The mass of the element (sphere) is m = 4/3πr3 . Combining formula (1.3.6) and the element vibration period formula gives the following equation:  √ 2 2π(1 − 2ν) ·r T = 2π 3E

(1.3.7)

Thus, when the material is unchanged (i.e., E and ν are constant), the element vibration period is proportional to its radius. Therefore, the smaller the element, the lower the vibration period, and accordingly, the lower the time step of each numerical simulation iteration.

1.3.4 Differences of the Element Motion Figure 1.2 shows the displacement–time curve for one period of the harmonic vibration of an element. The numerical simulation of DEM is based on time step iteration, which assumes the acceleration of the element is constant within a small time step. Therefore, it is necessary to select a time step that is small enough to accurately simulate a harmonic vibration process. For example, in Newtonian equation of motion,

1.3 Damping Harmonic Vibration of Elements

9

Fig. 1.2 Element motion during a vibration period

the displacement is equal to V 0 Δt + 0.5a·Δt 2 , which assumes that the acceleration in the time step is constant. Therefore, the time step and displacement must be sufficiently small to ensure a linear motion in each iteration. For a sinusoidal vibration, the time step is much smaller than the period. In other words, we need a series of small displacement–time segments to approximate the sinusoidal curve shown in Fig. 1.2. If the time step is half the period, the calculation will result in a large error and the discrete element system will even “explode” in a short time. To properly fit a sinusoidal curve, the time step must be lower than 10% of the period. A series of numerical simulation results indicates that when the time step is 2% of the period, usual calculation speed and accuracy can be satisfied; when the time step is 1% of the period, the energy conservation process can be accurately simulated; and when the time step is 0.5% of the period, the simulation results are very accurate.

1.3.5 Damping and Optimal Damping Coefficient The main role of a damping force is to dissipate system energy. Figure 1.3 shows the simulation results for two identical elements vibrating on a fixed boundary (generated by the MatDEM sample code TwoBalls). Figure 1.3b displays the energy curve for simulation results with the critical damping, which allows each element to return to equilibrium as quickly as possible without periodic vibration. For example, when opening a damped spring door and releasing it, the door will accelerate, go back,

10

1 Principles and Implementation of DEM

Fig. 1.3 The damping harmonic vibration process of an element

and then close slowly, with a damping force close to the critical damping. If there is no damping, the spring door will oscillate continuously. Another example is the pointer movement of the ammeter. When measuring current, the ammeter pointer will oscillate around the true value and gradually balance; however, when it is given a proper damping, the ammeter pointer will stop at the equilibrium position quickly. To obtain a stable model rapidly, greater damping coefficient is usually adopted. When the critical damping is adopted for a single element, the energy converges quickly (Fig. 1.3b). However, if 1/10 of the critical damping is adopted (Fig. 1.3c), the kinetic energy will decrease gradually during the fluctuation. In the real world, the dissipation of energy takes a certain amount of time. The effects of explosions, knocking a rock block, and compressing a rock sample are different. Therefore, in the test guidelines, a rock sample must be compressed for approximately 15 min, and a certain time is required to conduct the shear test. When using the discrete element method to simulate a rock compression test, the loading process needs to be differentiated. If the loading is applied from 0 kPa to 1000 kPa, the loading process is divided into 10 steps and the compressive stress is increased by 100 kPa in each step. In each compressive step, a compressive stress wave is first generated on the top surface of the sample. If 100 kPa is applied first and then the load is increased to 200 kPa immediately, the stress wave generated by the previous load has not been dissipated. In this case, the kinetic energy and elastic strain energy will accumulate in the rock sample and consequently change the measured compressive strength and damage phenomenon. The rapid accumulation of energy affects the strength of the rock, the specific effects, which can be studied using the Hopkinson rod test. In the discrete element simulation of quasi-static processes, a greater damping coefficient is usually set so that the system energy of the discrete element model converges quickly. Therefore, when studying the mechanical strength and failure of rock under quasi-static conditions, a damping coefficient greater than the true value is usually adopted to quickly consume the kinetic energy of the discrete element model, thus avoiding the accumulation of kinetic energy and reducing the computational time of the numerical simulation (see Sect. 4.3.4 for details).

1.3 Damping Harmonic Vibration of Elements

11

In numerical simulations of tests, the loading speed can be simulated by adjusting the damping coefficient and the iteration step number. If a displacement is applied to an element with a critical damping coefficient of 1/10, calculated iteratively for 100 times, and a new displacement load added immediately before the stress wave dissipates, the compression process is a fast loading (equivalent to the “quick” in Fig. 1.3c). If a displacement is applied to an element and then runs 1000 times of iterations, the stress wave and kinetic energy will have dissipated and a slow compression or quasi-static effect (equivalent to the “slow” of Fig. 1.3c) can be achieved. Moreover, if critical damping is adopted, quasi-static simulation can be achieved after 100 iterations (Fig. 1.3b) (see Sect. 4.3.4 for details). In case of using the critical damping, the vibration energy of a single element dissipates fastest, i.e., the optimal damping of one element system is the critical damping. Based on the critical damping formula, the optimal damping for multielement systems can be obtained using the following semi-empirical formula (Liu et al. 2017): η=

V

d √ 8mk 1/3

(1.3.8)

where V is the model volume; d is the element diameter; m is the element mass; and k is the element stiffness. Therefore, in a quasi-static issue, the optimal damping coefficient is adopted to rapidly converge the system energy, which equals the critical damping of an element divided by the number of elements in one direction of the model. For example, when the critical damping of an element is divided by 100, the damping coefficient obtained will quickly converge the energy of a block containing 1 million elements with 100 elements in each dimension. We have tested the semiempirical formula of the optimal damping coefficient thousands of times, which produced good results.

1.4 Energy Conversion and Energy Conservation of DEM In the discrete element numerical simulation, mechanical energy is gradually converted into heat under the action of damping force, friction, and fracture. All types of mechanical energy and heat can be accurately calculated in the discrete element system, and the sum of these always remains constant.

1.4.1 Mechanical Energy of Systems Mechanical energy in a discrete element model includes kinetic energy, elastic potential energy, and gravitational potential energy, they may change between each other (Liu et al. 2017).

12

1 Principles and Implementation of DEM

(1) Elastic potential energy Elastic potential energy (Ee) is the sum of the strain energy of normal and shear springs of bonds: E e = 0.5K n X n2 + 0.5K s X s2

(1.4.1)

where K n and K s are the inter-element normal stiffness and shear stiffness, respectively, and X n and X s are the corresponding relative displacements. (2) Gravitational potential energy The gravitational potential energy (Eg ) of an element is E g = mgh

(1.4.2)

where m is element mass, g is the acceleration of gravity, and h is the height above the reference level. Eg can be generally ignored (g = 0) in a micro-scale simulation, as its value is very small. But it must be considered in a large-scale simulation. (3) Kinetic energy Kinetic energy (Ek ) of an element can be expressed as E k = 0.5mv2

(1.4.3)

where m is the element mass and v is the element velocity.

1.4.2 Calculation of Heat The heat generated in the model includes viscous heat, breaking heat, and frictional heat, which correspond to damping, fracture, and friction, respectively. In a discrete element numerical simulation, the dynamic evolution of the discrete element system is simulated by time step iterations, and various kinds of heat are calculated and accumulated in each time step. (1) Viscous heat When elastic wave propagates between elements, mechanical energy will gradually dissipate into heat due to friction, scattering, and other factors. In the DEM, damping is used to weaken the elastic wave of the model and dissipate the kinetic energy in the discrete element system. The damping force (Fd ) acting on the elements is given by the following equation: Fd = −ηv

(1.4.4)

1.4 Energy Conversion and Energy Conservation of DEM

13

where η is damping coefficient and ν is element velocity. Because the time step of the simulation is very small, element velocity in a step is assumed to be constant. Viscous heat can be calculated by formula (1.4.5): Q d = −Fd dx

(1.4.5)

where dx is the displacement of the elements in the current time step. (2) Breaking heat When an intact spring breaks, elastic potential energy will dissipate partially or completely into heat by the damping vibration of the spring, but this process cannot be realized in the DEM. Therefore, it is assumed that the spring of element immediately stops vibrating when the connection is broken and the elastic potential energy is directly converted into heat. Thus, the breaking heat generated is equal to the reduction of elastic potential energy. If the inter-element normal force is tensile, the elastic potential energy of both normal and shear springs reduces to zero when the intact bond breaks, and the reduced Ee,t is the sum of the elastic potential energy of both normal and shear springs: E e,t = 0.5K n X n2 + 0.5K s X s2

(1.4.6)

If the inter-element normal force is compressive, the normal spring force and the corresponding elastic potential energy are unchanged when the intact bond breaks. According to Eq. (1.2.3), the shear force reduced from Fsmax to F’smax , and the reduced Ee,c can be expressed as follows:    2 2 Ks E e,c = 0.5 Fsmax − Fsmax

(1.4.7)

where K s is the inter-element shear stiffness. The breaking heat is the sum of the reduced elastic potential energy when the bonds fail:

E e,t , Fn >0 Qb = (1.4.8) E e,t , Fn ≤ 0 (3) Friction heat Two elements begin sliding relative to one another when the bond is broken, and the magnitude of external force exceeds the maximum shear force of the broken bond. Frictional heat (Qf ) generated during the sliding process is defined as the product of the average sliding friction and the effective sliding distance: Q f = |0.5(Fs1 + Fs2 ) · d S|

(1.4.9)

14

1 Principles and Implementation of DEM

Fig. 1.4 Sliding friction distance between elements

where Fs1 and Fs2 are the sliding friction force at the beginning and the end, respectively, of the current step (i.e., the maximum shear forces of the broken bond) and dS is the effective sliding distance. In a time step, the normal force between elements may change, and according to Eq. (1.2.3), the friction force also changes. Therefore, the average friction force is used in the equation. Note that the sliding distance (dS) in Eq. (1.4.9) is the sliding distance of elements along the friction surface. As shown in Fig. 1.4a, before the connection breaks, the element is locked by static friction at point P. The center of the element is originally located at point O’ (corresponds to a dashed circle), when the shear force (FS0 ) is zero. If an external tangential force (f ) acts on the element, the shear spring will be compressed, and the element center will move to point O (corresponds to a solid line circle). However, the contact point is still locked at point P and the sliding distance (dS) is zero. Figure 1.4b shows the actual sliding distance of elements when sliding friction occurs. The element is originally located at point O1 , which slides to point O2 after a time step. As inter-element normal force increases, the shear force (i.e., the frictional force) increases from Fs1 to Fs2 and the shear spring is compressed. Therefore, deformation of the shear spring should be considered when calculating the sliding distance. In Fig. 1.4b), the effective sliding distance equals the length of P 1 P 2 , which can be calculated using the following formula: d S = d S  − (Fs2 − Fs1 )/K s

(1.4.10)

where dS’ is the relative displacement of two elements along the shearing direction (i.e., O1 O2 in Fig. 1.4) and K s is the inter-element shear stiffness.

1.4 Energy Conversion and Energy Conservation of DEM

15

1.4.3 Energy Conservation and External Work The heat in the model is the sum of viscous heat (Qv ), breaking heat(Qb ), and frictional heat (Qf ), which can be expressed as Q = Qv + Qb + Qf

(1.4.11)

The total energy of a discrete element model is the sum of all forms of mechanical energy and heat (Q): E total = E e + E g + E k + Q

(1.4.12)

According to the law of conservation of energy, the total energy (Etotal ) of an isolated system is constant. When the model deforms under an external force, the increment of the total energy of the model must be equal to the work done by the external force (W e ). Specifically, when a model is compressed, the work of the external force is defined by the formula We = 0.5(F b1 + F b2 )d L

(1.4.13)

where Fb1 and Fb2 are forces applied to the boundary before and after a compressive step; dL is the displacement of the boundary; Fb1 , Fb2 , and dL are vectors; and W e is positive when the boundary force and displacement occur in the same direction.

1.5 Calculation Scale and Engineering Application Feasibility of DEM The basic principle of DEM is derived from molecular dynamics and has similar characteristics to the simulation of molecular dynamics. At the atomic scale, there is only simple and normal gravitation and repulsion between atoms, and there is no shear force (friction). On a larger scale, due to adhesion and meshing, atoms (elements) can withstand shear forces, produce friction, and exhibit various complex mechanical properties. In the DEM, a rock and soil mass are composed of a series of elements. Similarly, the surface of a material cemented by a series of smooth glass spheres has a certain coefficient of friction. This indicates that granular assemblages, such as a rock and soil mass, have different mechanical properties at different scales (Sun et al. 2010). For example, quartz has greater strength, whereas quartz-sandstone deposited and cemented by quartz elements has relatively lower strength. There are also substantial differences in the mechanical properties of different quartz-sandstones. This is due to the different packing patterns of elements, compactness, element gradation, morphology, and the cementation strength, content, and distribution of micro-cracks,

16

1 Principles and Implementation of DEM

all of which have an impact on the mechanical properties of rocks. The DEM can effectively simulate such multi-scale characteristics and is therefore widely used to elucidate the micro-mechanisms underlying the macromechanical properties of rock and soil mass. Through simple cementation and specific accumulation, elements show various mechanical properties such as elasticity, elastic–plastic, and anisotropy. The dilatation and contraction process can also be simulated. Theoretically, if enough simple elements are stacked and cemented in a specific way, various complex deformation and failure processes of a rock and soil mass can be simulated. However, there are still some difficulties in large-scale discrete element numerical simulation. For example, if each element is a millimeter in diameter, the number of elements in a cubic meter of space would be one billion. The number will be even greater on a larger engineering scale. At present, the number of elements in discrete element numerical simulation is still in the order of tens of thousands to several millions. Therefore, numerous numerical simulation studies of discrete elements remain focused on a sample scale. All mediums are discontinuous or have certain structures at some levels of observation. On a macro-scale, there are joints and other structural planes in a rock mass. On a mesoscopic scale, there are micro-cracks between rock particles. Each particle may have tiny cracks and inner pore structures, and nonlinear mechanical characteristics may be formed. On an atomic scale, due to crystal lattice defects, dislocations are generated when forces are applied, which may result in macroscopic creep of the material. Any numerical simulation and analysis method cannot consider all microscopic details. In continuum mechanics methods such as the finite element method (FEM), a rock mass is divided into a series of basic calculation elements by grid division, each of which represents a geotechnical block in a region. The mechanical properties of the block are not necessarily completely elastic due to the composition and structural action of the material on a smaller scale. Therefore, in the FEM, it is necessary to define different constitutive models for basic elements to comprehensively describe and reflect factors on smaller scales and corresponding changes in mechanical properties. For a discrete element numerical simulation on a sample scale, an element can be used to represent a particle of real rock, and the microscopic mechanism of macroscopic deformation and failure of rock can be explored by studying the contact model of elements. For engineering-scale problems, such as a discrete element simulation of a landslide, it is impossible to simulate every particle in the rock. In this case, like the FEM, each discrete element can represent a rock block, to which the corresponding contact model and mechanical properties need to be assigned. Therefore, in a discrete element numerical simulation on a large scale, it is necessary to determine the size of each element and set the corresponding mechanical properties. In the field of geology, DEM has been widely used in the numerical simulation of tectonic evolution processes. On large scales, based on the above considerations, elements are assigned relatively small moduli and strengths. The traditional discrete element numerical simulation of a tectonic evolution is usually qualitative, whereas engineering requires quantitative numerical simulations with greater precision. From the above analysis, it is apparent that more element numbers and

1.5 Calculation Scale and Engineering Application Feasibility of DEM

17

the appropriate mechanical properties of elements are required; in other words, the problem of calculation and quantitative modeling needs to be solved.

1.6 Understanding and Solution to the Three Major Issues in DEM At present, the DEM is mainly used for academic research, while its practical application in geotechnical engineering is relatively rare. To facilitate this, the following three major problems need to be solved: ➀ the amount of calculation required is immense, while the modeling scale and the research field are limited. DEM decomposes rock and soil mass into a series of elements spatially, and performs iterative calculation in time, which is computationally intensive. The number of calculation elements for a three-dimensional numerical simulation is usually limited to tens of thousands, resulting in the sample size being too small to meet the actual engineering requirements. ➁ The macroscopic and microscopic mechanical properties are unclear and the modeling is difficult. The geological model is composed of a large number of discrete elements in the DEM. Furthermore, in the traditional modeling process, it is necessary to determine the appropriate inter-element micromechanical parameters through troublesome calibration and test operations to obtain a numerical model with specific mechanical properties. The complexity of quantitative modeling greatly affects its practical application. ➂ The multi-field and fluid–solid coupling theory is imperfect and the corresponding simulation software is lacking. Modern large-scale engineering construction often involves complex multi-field coupling (hydrothermal) and fluid–solid coupling (solid–liquid gas), such as hydraulic fracturing, tunnel excavation, and so on. Currently, the DEM is not as mature as the FEM in dealing with these problems and lacks the relevant numerical software.

1.6.1 High-Performance Matrix Computing of the Discrete Element Method Recent studies have shown that high-performance computing technology based on a graphics processing unit (GPU) can effectively improve the speed of numerical calculation. It can improve computational efficiency by 10 to 50 times and has been widely used in molecular dynamics, petroleum exploration, computational mechanics, materials science, and artificial intelligence. The GPU is commonly referred to as a graphics card, such as NVIDIA’s discrete graphics card, that contains the CUDA computing core needed for GPU computing. Ordinary graphics cards usually have hundreds of CUDA computing cores, which is equivalent to computing on hundreds of cores simultaneously. For professional Tesla GPUs, such as P100 and V100,

18

1 Principles and Implementation of DEM

there are thousands of calculation cores, which can vastly improve computational efficiency. In view of the immense computational complexity of DEM, the author independently developed the general discrete element simulation software MatDEM (the matrix computing of the discrete element method). The discrete element simulation of millions of elements was realized by adopting the innovative matrix discrete element computing method and a three-dimensional contact algorithm. This enhances the calculation efficiency and the number of elements reach 30 times of those of commercial software, and as a result it can be used in engineering applications. MatDEM integrates pre-processing, calculation, post-processing, and secondary development to facilitate the large-scale discrete element simulation of various geological and engineering problems. It has been applied in researches of compaction bands of sandstone, landslides, and ground subsidence. Figure 1.5a shows the curves of tested speeds of CPU and GPU on an ordinary laptop (ThinkPad T470). This shows that when the number of elements is small, the GPU calculation speed is lower than that of the CPU because most of the calculation time is spent on communication between them. As the number of elements increases, the GPU computing speed increases rapidly. When the number of elements exceeds 10,000, the calculation speed of the GPU is significantly higher than that of the CPU; when the number is 100,000, the calculation speed of the GPU is about 1 million element movements per second, five times that of the CPU. Figure 1.5b shows the speed test results for MatDEM on a professional GPU server. The GPU is P100 with 16 GB of memory and supports MatDEM discrete element simulations of 1.5 million elements. Similarly, when the number of elements exceeds 10,000, the GPU speed is significantly higher than that of the CPU; when the number of elements reaches 1 million, the GPU calculation speed is about 50 times that of the CPU. As shown in Fig. 1.5b, when the number of elements exceeds 1000, the CPU calculation speed is basically unchanged while the GPU speed increases rapidly as the number of elements increases. Therefore, GPU matrix computation is especially suitable for large-scale discrete element simulation.

1.6.2 Quantitative Modeling Problem of DEM The continuum mechanics method describes the mechanical properties of the simulated material by establishing macroscopic constitutive equations. In the FEM, the required numerical model can be obtained by setting the macroscopic mechanical properties (such as Young’s modulus and Poisson’s ratio). However, the DEM is modeled by stacking elements with specific mechanical properties. The macroscopic mechanical properties of the model are affected by the properties of the elements, the accumulation process, and the cementation. This makes the discrete element theory applicable to macroscopic and microscopic studies of rock and soil mass, yet brings difficulties and uncertainties to the quantitative modeling of the discrete element method (Sun et al. 2011). When constructing discrete element materials with

1.6 Understanding and Solution to the Three Major Issues in DEM

19

Fig. 1.5 Calculation speed of CPU and GPU with different numbers of elements

(a) Test results on a laptop

(b) Test results on a GPU sever

specific macromechanical properties, it is necessary to recognize the uncertainty and multiplicity because ➀ discrete element models with specific mechanical properties cannot be obtained directly and ➁ packing and cementing models corresponding to macromechanical properties are usually not unique. The first problem relates to building a packing model of discrete elements with specific mechanical properties. The mechanical properties of the discrete element packing model are affected by the stacking structure and the cementation (or fractures). Discrete element numerical simulations show that the mechanical properties of a group of elements will change after re-stacking and cementing, while the cracks and joints in the rock have a substantial influence on the overall mechanical properties. When the stacking structure is determined and cementation is completed, the

20

1 Principles and Implementation of DEM

mechanical properties of the model are mainly controlled by the contact model and parameters of the elements. In our previous study, we developed macro-microscopic mechanical parameter conversion formulae for a close-packed discrete element model (Liu et al. 2013; Liu et al. 2017). For the linear elastic model, the conversion formulae are applied and the five element mechanical parameters in the model, such as normal stiffness (K n ), shear stiffness (K s ), breaking displacement (X b ), initial shear force (Fs0 ), and friction coefficient (μp ), can be calculated from five macroscopic mechanical properties of the material, including Young’s modulus (E), Poisson’s ratio (ν), compressive strength (C u ), tensile strength (T u ), and internal friction coefficient (μi ). The conversion formulae reveal the relationship between these five conventional macroscopic mechanical properties and the mechanical parameters between elements. Combined with conversion formulae, numerical tests, and automatic calibration, discrete element models with specific mechanical properties can be automatically trained (see Box _Mat Training). The three-dimensional conversion formulae are as follows: √ 2(1 − 5ν)Ed (1.6.1a) Ks = 4(1 + ν)(1 − 2ν) √ 2Ed (1.6.1b) Kn = 4(1 − 2ν) 3K n + K s Xb = √ T ud 2 6 2K n (K n + K s ) √ 1 − 2μp Cu d 2 Fs0 = 6 √ √ −2 2 + 2I , I = [(1 + μ2i )1/2 + μi ]2 μp = 2 + 2I

(1.6.1c)

(1.6.1d)

(1.6.1e)

The second problem relates to the structure of rock and soil mass. In the real world, two rock blocks with different compositions of elements and cementing strengths may have similar mechanical properties. In uniaxial compression and tensile tests of rock, rock samples of the same type may exhibit different failure characteristics, even if the test strength is very close. The DEM is modeled by simulating the natural accumulation and cementation of a rock and soil mass. There are uncertainties and multiple solutions in the rock failure due to the existence of certain structures inside the rock and soil mass. For example, in a real test, the tensile strength of a rock block is T. A model with a tensile strength of T is then obtained by DEM. Then, adding joints or random micro-cracks in the model (reducing the strength), and appropriately increasing the tensile resistance (increasing strength) of the inter-element, may produce a model with the same tensile strength.

1.6 Understanding and Solution to the Three Major Issues in DEM

21

The single quartz and the quartz-sandstone cemented by quartz have different Poisson’s ratios. Furthermore, Poisson’s ratio of the quartz-sandstone is also distributed in a certain range, which suggests that the element accumulation structure has an important influence on Poisson’s ratio of the entire rock. Poisson’s ratio of most rocks and soils is between 0.1 and 0.4. Equation (1.6.1b) shows that because the shear stiffness K s cannot be negative, the input Poisson’s ratio in the formula must be less than or equal to 0.2. The conversion formula is applicable to the 3D close-packed model and the maximum possible Poisson’s ratio is 0.2, while the larger Poisson’s ratio of a rock and soil mass can be realized by a specific stacking structure. Therefore, the DEM is modeled by the accumulation and cementation of elements, thus retaining the structural and complex nature of natural geotechnical bodies. In the macroscopic and microscopic study of rock and soil mass, it is important to carefully consider the accumulation mode, contact model and cementation, and change the factors to explore the microscopic mechanism underlying macroscopic deformation and the failure of rock and soil mass. Such studies are typically experimental and sample scales. For the numerical simulation of larger engineering scales, the primary concern is whether the deformation and failure under specific stress meet the requirements, i.e., whether the packing model has a specific elastic modulus and strength, rather than the intrinsic mechanism of the macroscopic mechanical properties of the rock. Therefore, for issues on the engineering scale, a discrete element model with specific mechanical properties can be established by stacking, cementing, tests and calibration, and then be used to build a quantitative discrete element model.

1.6.3 Multi-field Coupling Method Based on DEM Numerous geotechnical engineering problems involve multi-field coupling and fluid– solid coupling problems, such as hydraulic fracturing, tunnel water inrush, and the landslide instability of reservoir banks, including stress field, temperature field, and seepage field. Conventional seepage field calculations are primarily used for macroscopic continuum media, which simulate seepage through a continuous difference method. However, from a microscopic perspective, rock and soil mass is composed of particles, pores, and the fluids in pores, which constitutes a fluid–solid coupling problem. Given the increasing scale and complexity of engineering constructions, multi-field coupling and fluid–solid coupling have become hotspots and difficulties in geotechnical engineering researches. The application of DEM in multi-field coupling is still relatively rare and the theory is still under development. When using the FEM to study multiple fields, the seepage force and various fields are typically equivalent to the finite element units, each of which is a combination of numerous pores and elements. Applying the same idea to the DEM, a discrete element can be regarded as the combination of several pores and particles, each of which has properties of moisture content and temperature. In this way, the problem of seepage field, temperature field, and other fields can be studied.

22

1 Principles and Implementation of DEM

At present, this idea has been applied to the simulation of soil cracking under multifield action (Zhang et al. 2017). By adding a moisture field, the discrete element unit may have a certain moisture content. When the surface of the soil layer evaporates, the moisture content changes and the seepage is calculated using the finite difference method between the elements. In experiments, we can get the relationship between soil element strength, element radius, and moisture content. The element strength increases, and the radius decreases when the moisture content decreases. Through such a process, it is possible to simulate the evaporation, dehydration, and cracking process of the soil. Then, we may change the relationship between the moisture content and the strength and radius of each element, adjust the inhomogeneity and thickness of the soil layer, and study the influence of various factors on the cracking of the soil. This basic idea can also be applied to the numerical simulation of heat conduction, such as the thermal–mechanical coupling simulation of energy pile and the simulation of microwave assisting rock breaking. In the latter, the rock particles are thermally expanded by microwave irradiation and stress concentration and microcracks are generated near some elements. In the DEM, based on the above theory, the relationship between the radius of elements and the temperature is established, and then the numerical simulation of microwave rock breaking can be realized. In addition, the effective stress principle can be used to calculate the effect of water pressure. By applying the water pressure to each element, we can simulate the effect of water level change on the soil deformation as well as the numerical simulation of land subsidence and ground fissures. Based on the theory presented in Sect. 1.4.3, MatDEM also implements the simulation of heat calculation and energy conservation in discrete element systems (see Chapter 10 for relevant examples). The above sample code files and simulation results can be downloaded from the website http://matdem.com.

1.7 Development and Prospect of MatDEM MatDEM was developed by the author over 11 years. The author began the research into the DEM algorithm during postgraduate study at Nanjing University in 2007, and developed the original theoretical test software based on the C# language. In 2011, based on the idea of matrix computing, the MATLAB language was used to establish a solver of 2D discrete element method. After that, the development of 3D discrete element software began in 2012. In 2013, the high-performance matrix computing of DEM was realized, which greatly improved computing efficiency by dozens of times and the number of computing elements reached millions. The software was officially named MatDEM, which denotes “the fast GPU matrix computing of the discrete element method.” The name of the software is taken from Matrix and DEM.

1.7 Development and Prospect of MatDEM

23

From 2014 to 2016, MatDEM realized a large-scale discrete element heat calculation and energy conservation calculation and established a complete post-processing module at a commercial software level. The computational efficiency of the software doubles each year through ongoing optimization of the core solver. The multi-field coupling simulation is gradually improving and has been applied to the simulation of geological and rock mechanics issues. Since 2017, with the support of the Chinese Society of Rock Mechanics and Engineering, MatDEM has begun to develop generalization and engineering applications. A window program established according to the standards of commercial software and the automatic modeling of discrete element materials has now been realized, which solves one of the most important problems in the application of DEM. On May 4–6, 2018, during the conference jointly hosted by Chinese Society of Rock Mechanics and Engineering and Nanjing University, the MatDEM version 1.0 was officially released. MatDEM has been successfully applied to a range of engineering and geological studies. For example, it has been used to study the mechanism of the formation of wiggly compaction bands in porous sandstone. Different particle sorting has also been found to lead to different yield characteristics and to produce compaction bands with different shapes and directions (Liu et al. 2015). In the study of soil layer compression in land subsidence, the MatDEM has been used to verify the theory and show that negative pore water pressure in the clay layer will promote the compressive strain of the clay layer and exacerbate ground subsidence after the sand layer is drained. MatDEM has also been applied to the analysis of foundation pit stability (Suo et al. 2017), the soil water loss and cracking process simulations (Zhang et al. 2017), sand confined compression test simulations (Qin et al. 2018), and a 3D landslide simulation (Liu et al. 2017). Such applications in researches show that, through MatDEM numerical simulations, it is possible to reproduce physical processes, test theories, analyze and solve scientific problems! Large-scale modern engineering is faced with a large number of multi-field and fluid–solid coupling problems. By integrating the DEM, lattice Boltzmann method, and finite difference method, large deformation damage, multi-field, and multi-phase coupling numerical simulations can be achieved. However, several problems remain, such as difficulties in system development and modeling, and the huge computing cost. The numerical simulation of large deformation damage, multi-field, and multiphase coupling is a worldwide technical problem. However, based on MatDEM, combining the DEM with fluid numerical calculation methods, such as CFD and LBM and then considering the interaction between solid elements and different fluids (gas, water, oil, and so on), the numerical simulation of fluid–solid coupling can be achieved (Guo and Guangchu 2009; Jing et al. 2019). In this way, we can build a virtual physical world in the computer, which is similar to that in the movie “The Matrix,” which can effectively reproduce many physical processes and geological phenomena such as magma intrusion, hydraulic fracturing, and engineering grouting, as well as promote the development of researches in numerous fields.

24

1 Principles and Implementation of DEM

We will continue to optimize the MatDEM computing core and provide standard and open application programming interface, and are pleasured to work with experts in various fields, and to develop an international high-performance discrete element software for the academic community and industry.

References Antonellini, M.A., and D. Pollard. 1995. Distinct element modeling of deformation bands in sandstone. Journal of Structural Geology 17 (8): 1165–1182. Cundall, P.A., and O.D.L. Strack. 1979. A discrete numerical model for granular assemblies. Géotechnique 29 (1): 47–65. Feng Chun, Li Shihai, Wang Jie. 2012. Stability analysis method for bedding rock slopes under seismic load. Chinese Journal of Geotechnical Engineering, 34(4):717–724. Feng, Chun, Li Shihai, and Liu Xiaoyu. 2016. Particle-DEM Based Linked Bar Strain Softening Model and Its Application. Chinese Journal of Theoretical and Applied Mechani 48 (1): 76–85. Goldenberg, C., and I. Goldhirsch. 2005. Friction enhances elasticity in granular solids. Nature 435 (7039): 188–191. Gu Yingfan, Lu, Liu Bing Yi, et al. 2016. Numerical simulation of hydraulic fracturing based on discrete element method. Geological Journal of China Universities 22 (1): 194–199. Guo, Z., and Z. Guangchu. 2009. Theory and applications of lattice boltzmann method. Beijing: Science Press. Hardy S, Finch E. 2006. Discrete element modelling of the influence of cover strength on basementinvolved fault-propagation folding. Tectonophysics, 415(1/2/3/4):225–238. Hardy, S., and E. Finch. 2010. Discrete-element modelling of detachment folding. Basin Research 17 (4): 507–520. Ji, Shunying. 2018. Computational granular mechanics and its engineering applications. Beijing: Science Press. Ji, Shunying, Li Chunhua, and Liu Wei. 2012. A review of advances in sea-ice discrete element models. Chinese Jornal of Polar Research 24 (4): 315–330. Jia, Fuguo, Han Yanlong, Liu Yang, et al. 2014. Simulation prediction method of repose angle for rice particle materials. Transactions of the Chinese Society of Agricultural Engineering 30 (11): 254–260. Jiang, Mingjing, Zhang Fuguang, Sun Yugang, et al. 2012. DEM simulation of mechanical behaviour and bond breakage of different cemented sands. Chinese Journal of Geotechnical Engineering 34 (11): 1969–1976. Jiang, Mingjing, Chen He, and Liu Fang. 2013. Microscopic bond model for rock and preliminary study of numerical simulation method by distinct element method. Chinese Journal of Rock Mechanics and Engineering 32 (1): 15–23. Jiang, Mingjing, Chen, He, Zhang Ning, et al. 2014. Distinct element numerical analysis of crack evolution in rocks containing pre-existing double flaw. Rock and Soil Mechanics,35(11):3259– 3268, 3288. Jiang, Mingjing, and Shen Zhifu. 2016. Three-dimensional microscopic contact model for DEM analyses of bonded assembly. Chinese Journal of Underground Space and Engineering 12 (1): 30–37. Jiang, Mingjing. 2019. New paradigm for modern soil mechanics: Geomechanics from micro to macro. Chinese Journal of Geotechnical Engineering 41 (2): 185–253. Jiao, Y. 1999. Three-dimensional discrete element method and its application. Chinese Journal of Rock Mechanics and Engineering 18 (2): 98.

References

25

Jiao, Yuyong, Ge Xiurun, Liu Quansheng, et al. 2000. Three-dimensional discrete element method and its application in landslide analysis. Chinese Journal of Geotechnical Engineering 22 (1): 104–107. Jing, Lu, Guo Yiyi, and Zhao Tao. 2019. Understanding dynamics of submarine landslide with coupled CFD-DEM. Rock and Soil Mechanics 40 (1): 388–394. Jiang, M.J., H.S. Yu, and D. Harris. 2005. A novel discrete model for granular material incorporating rolling resistance. Computers and Geotechnics 32 (5): 340–357. Kloss, C., and C. Goniva. 2011. LIGGGHTS-open source discrete element simulations of granular materials based on Lammps. Supplemental Proceedings: Materials Fabrication, Properties, Characterization and Modeling 2: 781–788. Kozicki, J., and F.V. Donze. 2008. YADE-OPEN DEM: an opensource software using a discrete element method to simulate granular material. Engineering Computations 26 (7): 786–805. Li, S., D. Dapeng, and Yan Lin. 2003. 3D-DEM numerical simulation for jointed rock under uniaxial press loading. Rock and Soil Mechanics 4: 648–652. Li Shihai, Wang Yuannian. 2004a. Selection study of computational parameters for DEM in geomechanics. Chinese Journal of Rock Mechanics and Engineering 23 (21): 3642–3651. Li Shihai, Wang Yuannian. 2004b. Stochastic model and numerical simulation of uniaxial loading test for rock and soil blending by 3D-DEM. Chinese Journal of Geotechnical Engineering (2): 172–177. Li, Lei, Jiang Mingjing, and Zhang Fuguang. 2018. Quantitative simulation of triaxial test considering residual strength on deep rock using DEM and parameter analysis. Rock and Soil Mechanics 39 (3): 1082–1090. Liu Chun, Shi Bin, Gu Kai, et al. 2014. Development and application of large-scale discrete element simulation system for rock and soil [C]. 2014 National Engineering Geology Academic Conference (Autumn), Taiyuan. Liu Chun, Zhang Xiaoyu, Xu Qiang, et al. 2017. Energy conservation simulation of three dimensional discrete element model: a case study of landslide. Chinese Journal of Underground Space and Engineering, 13(S2):698–704. Liu, C., D. Pollard, and B. Shi. 2013. Analytical solutions and numerical tests of elastic and failure behaviors of close-packed lattice for brittle rocks and crystals. Journal of Geophysical Research Solid Earth 118 (1): 71–82. Liu, C., Pollard, D., Gu, K., et al. 2015. Mechanism of formation of wiggly compaction bands in porous sandstone: 2. Numerical simulation using discrete element method. Journal of Geophysical Research Solid Earth, 120(12):8153–8168. Liu, C., Xu, Q., Shi, B., et al. 2017. Mechanical properties and energy conversion of 3D close-packed lattice model for brittle rocks. Computers & Geosciences, 103(C):12–20. Mora, P., and D. Place. 1993. A lattice solid model for the nonlinear dynamics of earthquakes. International Journal of Modern Physics C 4 (06): 1059–1074. Place, D., and P. Mora. 1999. The lattice solid model to simulate the physics of rocks and earthquakes: incorporation of friction. Journal of Computational Physics 150 (2): 332–372. Qin, Yan, Liu Chun, Zhang Xiaoyu, et al. 2018. Discrete element simulation of sand confined compression test based on MatDEM. Journal of Geomechanics 24 (5): 676–681. Qu, Shengjun, Zhao Jianjun, Ding Xiumei, et al. 2016. Discrete element simulation of rainfall induced shelving bedding landslids. Hydrogeology & Engineering Geology 43 (6): 120–126. Shen, Zhifu, Jiang Mingjing, Zhu Fangyuan, et al. 2011. Influence of the micro parameters of discrete element on the macro parameters of sands. Northwestern Seismological Journal 33 (S1): 160–165. Shi, Chong, Wang Shengnian, and Liu Lin. 2013. Research of avalanche disaster numerical simulation based on granular discrete element method of high-steep slope under seismic loads. Chinese Journal of Rock Mechanics and Engineering 31 (a01): 2798–2805. Sun, Qicheng, and Wang Guangqian. 2009. Introduction to particle mechanics. Beijing: Science Press.

26

1 Principles and Implementation of DEM

Sun, Qicheng, Jin Feng, and Wang Guangqian. 2010. The multiscale structure of dense granular matter. Mechanics in Engineering 32 (1): 10–15. Sun, Qicheng, Cheng Xiaohui, Ji Shunying, et al. 2011. Advances in macro-microscopic mechanics of geomaterials. Advances in Mechanics 41 (3): 351–371. Suo, Wenbin, Liu Chun, Shi Bin, et al. 2017. Analysis of discrete element numerical simulation for deep foundation pit excavation with PCMW retaining structure. Journal of Engineering Geology 25 (4): 920–925. Wang Xue, He Li, Zhou Jian. 2016. EDEM and its application research and latest developments. Scientific Consult Technology·Management, (3):52–54. Wang, Yongjia, Song Wenzhou, and Zhao Yanjuan. 2000. Modern features of the DEM software system 2D-Block. Chinese Journal of Rock Mechanics and Engineering S1: 1057–1060. Xu, S., and Z.H.U. Hehua. 2011. Particle flow simulation of rock burst mechanism for highway tunnel ventilation shaft. Rock and Soil Mechanics 32 (3): 885–890. Xu, Yong, Sun Qicheng, Zhang Ling, et al. 2003. Advances in particle discrete element method. Advances in Mechanics 33 (2): 251–260. Zhang Xiaoyu, Xu, Liu Chun Qiang, et al. 2017. Numerical simulation of drying cracking using multi-field coupling discrete element method. Journal of Engineering Geology 25 (6): 1430–1437. Zhou, Jian, Chi Yong, Chi Weiwei, et al. 2016. The method of particle flow and PFC2D code. Rock and Soil Mechanics 21 (3): 271–274. Zhao G.F. 2015. DICE2D and Cluster, high performance computing and the discrete element model, 113–136. Amsterdam: Elsevier.

Chapter 2

The Basic Structure of MatDEM

In this chapter, we will introduce the basic operations and data structure of MatDEM, as well as the types of elements and contact models, and then introduce the principle and application of an elastic clump. These are the basis for understanding the software, as well as the fundamentals of modeling and numerical simulations.

2.1 The Software Foundation 2.1.1 The Operating Environment and Software Installation (1) Hardware Configuration MatDEM supports CPU and GPU computing and can switch between CPU and GPU calculation at any time while the program is running. When the number of elements is greater than 5000, the computation speed of GPU usually begins to exceed that of CPU. As the number of elements increases, the speed of CPU does not change substantially, while the speed of GPU increases almost linearly. Therefore, the greater the number of elements, the more obvious the computation speed advantage of GPU. When the number of elements reaches 1 million, the maximum computation speed of Tesla P100 can reach 70 times that of a single core CPU. The recommended hardware configuration of MatDEM is as follows. GPU: GPU computing requires an NVIDIA discrete graphics card (containing CUDA core). A common laptop can also run a GPU computing, but its efficiency is only approximately five times better than that of a CPU. A well-equipped desktop computer with a discrete graphics card can improve efficiency by 10 or 20 times. However, if efficiency needs to be improved by dozens of times, a Tesla GPU will be needed. This is a type of a professional computing card produced by NVIDIA, such as Tesla P100 or Tesla V100; Tesla V100 currently has the highest performance. A graphics card with 1 GB of memory can support the calculation of approximately © The Author(s), under exclusive license to Springer Nature Singapore Pte Ltd. 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9_2

27

28

2 The Basic Structure of MatDEM

100,000 three-dimensional elements. Thus, as the Tesla P100 has a graphics card with 16 GB of memory, it can handle up to approximately 1.5 million elements. GPU computing cards constitute most of the cost of GPU workstations and servers. CPU: GPU computing is controlled by a CPU; therefore, CPUs with greater dominant frequency are required. One GPU usually needs two CPU cores; thus, the requirement for the number of CPUs is not critical. For example, a two-way CPU Xeon E5-2637v4 has a relatively better cost performance. CPUs with greater dominant frequency and more cores therefore have better computing performance. Graphics card: The three-dimensional display of simulation results of MatDEM relies on graphics cards. Therefore, if the user wishes to display hundreds of thousands of three-dimensional elements, a better professional graphics card is needed. In terms of servers, a professional graphics card is required. Memory and hard disk: The system memory capacity should ideally be at least twice the GPU memory capacity. If there is only one GPU, the system memory capacity should be three to four times greater. For large-scale computing, a SSD of 1 TB or more capacity is recommended, accompanied by an HHD of 8 TB or more capacity. If an ordinary desktop computer is used, purchasing a game graphics card with a greater memory capacity is recommended. Generally, the configuration of a highperformance game computer is usually sufficient. (2) Software Configuration Operating system: Because MatDEM is programmed in MATLAB language, MatDEM can run on Windows, Linux, UNIX, or Macintosh operating systems. Currently, most MatDEM users use Windows OS; therefore, the Windows version of MatDEM is compiled and maintained. The Linux version of MatDEM is released every year. GPU driver: GPU servers purchased from professional manufacturers usually have the CUDA runtime installed. If users’ personal laptop or desktop computer prompts that the GPU cannot be recognized or used, they need to update the latest driver or consult the manufacturer on the NVIDIA website. If users do not have an NVIDIA discrete graphics card on their computers, they need to turn off the GPU computing function and can use only CPU for calculation. If there is no available GPU, MatDEM will also automatically turn off the GPU computing function. MatDEM Runtime: MatDEM is based on object-oriented programming ideas, programmed in MATLAB language, and packaged as a stand-alone executable file (MatDEM.exe). Therefore, there is no need to install the MATLAB completely. Users only need to install the free MATLAB Runtime (similar to the Java Runtime Environment). For example, MatDEM version 1.32 requires users to install the MATLAB Runtime version R2017a (9.2). The MatDEM version 1.60 requires the MATLAB Runtime version R2019a (9.6). Users can visit the official website of MathWorks and then download and install the MATLAB Runtime.

2.1 The Software Foundation

29

2.1.2 The Windows Program for MatDEM To run the windows program for MatDEM, please open the “MatDEM.exe” in the root directory of the software folder. (1) The MatDEM startup window As shown in Fig. 2.1, the software supports six languages, i.e., Chinese, English, Spanish, German, French, and Japanese. We may choose a different language when clicking the top-right drop-down list. The sub-windows are divided into two parts, A and B, where A is the Development Platform and B is the Apps of MatDEM. The main program in Module A contains a series of example codes for modeling and numerical simulations of various problems. Based on these example codes, users can create the corresponding Windows program (Apps). The Windows programs in Module B are based on example codes in Module A. And in MatDEM 1.32, it includes a numerical simulation box (based on the BoxModel example) and a numerical laboratory (based on the 3AxialNew example). In the MatDEM 1.94 that is shown in Fig. 2.1, the Module B includes several examples of Apps, and the source code of the Apps is provided in the folder “app” of the software. We may run an App, edit the apps list, and set and cancel the default startup app in the Module B. This book will introduce

Fig. 2.1 The MatDEM 1.94 startup window

30

2 The Basic Structure of MatDEM

the development platform of the MatDEM, while the teaching video of the advanced part (the module B) is provided on the website http://matdem.com. The book is based on the MatDEM 1.32, although new features and functions may be provided in new versions, the commands and main functions are uniform. We recommend users to use the latest version of the MatDEM, when they are learning this book. The high-performance computing of this software is based on the matrix discrete element computing method (Matrix DEM), which is the basis and core of the software as well as the origin of the software logo. The middle of the form is the logo for the software. The square grids of the background represent the matrix calculation. Above these grids are the three representative letters, DEM, of the discrete element method. The three letters constitute the simplest tangential spring contact between two discrete elements. The meaning of the whole logo is discrete element software based on high-performance matrix calculation, namely, matrix discrete element method, i.e., MatDEM. (2) The Window for the Main Program Click the “Main Program” button in Module A to open the window for the main program, as shown in Fig. 2.2. In the middle is the command editor and data viewer for browsing and editing commands or checking data during simulations; users may switch between them by clicking the button shown in the figure. Users also can enter and run a command directly in the command editor. Multiple tabs can be opened in both the command editor and the data viewer, enabling users to quickly switch between them. The middle-upper part of the left of the window is the data table area. This will display the variables generated while the program is running. As shown in Fig. 2.2, the data table on the left side contains two common objects, B and d. Clicking variable

Fig. 2.2 The window of the main program

2.1 The Software Foundation

31

d displays the parameters of this object in the data viewer. If the parameter d.mo is clicked, a new tab d.mo will appear and display its internal parameters. On the right is the file management area. This can be double-clicked to load each code file stored under the root directory. The file will then be displayed in the middle of the command editor. If a subfolder is double-clicked, it will open the secondary directory, whereas if a data file is double-clicked, the program will load the data into the workspace. The lower part of the window is the command line and the message output area. Users can enter commands step by step in the command line and then press Enter to execute them. Various information prompts while the program is running will be displayed in the message output area, as shown in Fig. 2.2. There is also an image display area in the lower left corner of the window. By default, this will display all images generated during the running of the program: users can also generate a new window to display the image by using the MATLAB figure function. When users need to save an image or create an animation, they must click the “Postprocessing” button in the lower right corner. The “Mini form” button in the lower right corner of the window can be used to zoom out the window. When clicked, the entire window will be zoomed out to the command line and the message output area. When running several MatDEM programs simultaneously, the windows can be zoomed out to monitor the running of the simulation. (3) Post-processing Module Users may open the post-processing module through the window of the main program or in the startup window, as shown in Fig. 2.3. The post-processing window supports both UI operations and commands. The three drop-down boxes in the top left of the window give three figure types of post-processing, including: ➀ The “Simulation result” to display the calculation data in d.data; ➁ The “Model parameter” to display the parameter data in d.mo; ➂ The “Process curve” to display the recorded data in d.status. GIF animation can also be created in the post-processing window. For details of the corresponding operations and precautions, please see Sect. 5.1. (4) The Materials Window The materials window is shown in Fig. 2.4. It is used to view and edit the macro- and micromechanical parameters of materials. Users can create new materials or import existing “.txt” or “.mat” material files to the software, and edit and convert the macroand micromechanical parameters. In this window, material names are displayed in the list on the left side of the window. Materials in the list can be saved as a “.mat” file for subsequent numerical simulations.

32

2 The Basic Structure of MatDEM

Fig. 2.3 The window of the post-processing

Fig. 2.4 The materials window

2.1.3 Operation and Termination of the Software (1) The Operation of Code First, the main program in the startup window needs to be opened as shown in Fig. 2.2. The secondary development of MatDEM is based on MATLAB language

2.1 The Software Foundation

33

and supports most MATLAB commands after the runtime environment is installed. As mentioned previously, users can directly enter code in the command editor, open a command file written in other software through the “command” column in the menu bar, or double-click the file name in the list on the right side of the window to read in the code. Users can run the code in the command editor by clicking “Run commands” in the window. The command editor of MatDEM is very simple. The use of a professional code editor to write codes, such as MATLAB, Notepad ++, and Ultra Edit, is recommended. MatDEM supports standard MATLAB functions. Users can write a custom function and run the function file via the function f.run. At the same time, MatDEM can also run a command file through the function MatDEMfile. For details, please refer to Sect. 5.4.3. (2) The Termination of the Software In MatDEM1.32, once users start running the code, they cannot close the window or interrupt the execution until the code is completely executed. While in MatDEM 1.60, “Pause,” “Continue,” and “Stop” buttons are provided. MatDEM supports multiple programs running at the same time. Thus, when the main program A is busy, another main program B can be opened to view the intermediate data generated by A. If the results of numerical simulation do not meet users’ expectations, they can force the corresponding process to be terminated in the task manager, and to shut down the program. Whenever users open a new main program window, the program will automatically generate a number that increases and loops from 1 to 99. The number is displayed in the title bar of the software, so that users can find and then terminate the specific process. Note that if the window program is closed directly when the program is running, its thread will still run in the background, occupy computing resources, and can only be terminated in the task manager. (3) The Recovery of Interruption In MatDEM, numerical simulation data can be saved by using the save command. Users may open the data file via the “Data” column in the menu bar or double-click the “.mat” file in the list on the right side of the window. Then, one can modify the code appropriately, and the numerical simulation can be continued on the basis of current data. This is quite important for numerical simulation of large models. For example, in case a simulation may takes 7 days of calculation, and the calculation is being interrupted due to a sudden power outage on the 6th day, we do not have to rerun the whole calculation. Instead, users can simply import the saved intermediate data file and continue the calculation. Another example would be the numerical simulation of a triaxial test, where the sample was not damaged during the first 1 million iterations, but was destroyed during the 1.1 millionth iterations. The load command can then be used to read the data file of the 1 millionth iteration and conduct a higher precision numerical simulation to study the development of the sample from the elastic deformation to the failure.

34

2 The Basic Structure of MatDEM

2.1.4 A Brief Introduction to the Application of the Software (1) The Composition of Example codes A series of example codes have been provided in the root directory of MatDEM. Most of the example codes consist of three “.m” files and roughly correspond to the three major steps of discrete element numerical simulation as follows: ➀ Geometric modeling. First, the elements of the model are generated and deposited under gravity to create an initial geometric model; ➁ Grouping and material setting. In the second step, the model is cut and divided into different parts, which are assigned actual materials. The model then needs to be rebalanced due to the sudden change in the mechanical properties of elements; ➂ Numerical simulation. The operations in the third step includes: initializing the model, recording the initial values of various parameters, resetting the system record information, setting the force and displacement loads, and saving the intermediate data during numerical simulations. The simulation results for the main examples are shown in Fig. 2.5. For details, please refer to the help file of the software or visit our official website: http://matdem. com. In these examples, several large-scale 3D numerical simulations require a GPU server or workstation due to their large computation requirements, such as example 2, “3D Landslide” and example 11, “TBM cutter Rock Breaking.” The remaining examples can be carried out on a laptop. (2) Build New Numerical Models Quickly MatDEM provides a series of example code in the program folder. To build a new model, users may first consider which of the existing examples is the closest to the problem they want to simulate, then make some modifications based on the example code, and also refer to other example codes. When a user is developing their code, backing up code files regularly is recommended. When an exception occurs in a numerical simulation, the user can still retrieve the previous correct code for checking and debugging. At the same time, one can insert a return command in the code to stop the calculation at a specific step. Therefore, data, various images, and curves can be viewed at any time of simulation, so as to evaluate the effect of each command. The secondary development of MatDEM is based on MATLAB language. When the program reports an error, the built-in compiler of MatDEM will provide the location and explanation for the error, based on which users may search for specific reasons for the error on the Internet. Debugging the code is a difficult and lengthy process, and it can sometimes take a long time to think about a seemingly tiny problem. Through this process, users can gradually rationalize the logic, analyze in depth the essence of the problem, solve the problem, and continuously improve the ability and efficiency of numerical simulations.

2.1 The Software Foundation

35

Fig. 2.5 Examples in MatDEM (1. Conventional triaxial test; 2. Three-dimensional landslide 1; 3. Impact of aerolite on the ground; 4. Soft and hard interbed modeling; 5. Automatic material training; 6. Three-dimensional landslide 2; 7. Pile–soil interaction; 8.The granular mass slides on the slope; 9. Rolling stone leaping and impacting backstop; 10. Simulation of structure sandbox; 11. Shield hob breaking rock; 12. Tunnel and rockburst; 13. Building complex models; 14. Microwaveassisted rock breaking; 15. Tunnel and ground subsidence; 16. Direct shear test; 17. True triaxial test; 18. Seismic dynamic action; 19. Ground subsidence and ground fracture; 20. The blasting effect; 21. Soil losing water and cracking; 22. The thermal coupling of energy pile; 23. Modeling with microscopic image; 24. Using image to cut model)

2.1.5 A Brief Introduction to the Help File The help file for MatDEM is an Excel file located under the root directory of MatDEM, i.e., Help.xlsx. All secondary development functions, parameters, and example codes are detailed in the help file. The help file consists of multiple tables. There is a description in the lower left corner of the home page of the help file, as

36

2 The Basic Structure of MatDEM

Fig. 2.6 Description of the MatDEM help file

shown in Fig. 2.6. Users may learn the properties and functions of each class of MatDEM by using the help file. The following is an overview of the major tables in the help file v1.36. (1) The first table (program structure) is equivalent to a directory, which briefly introduces the MatDEM software and its hierarchical structure, the main components of the software, the help file, the example code, the index of each folder in the root directory, and so on. (2) The second table (example code) briefly introduces the main contents, hierarchical structure, and some auxiliary functions of example codes. (3) The third table (post-processing) introduces commands involved in the postprocessing module, most of which are functions of the object d of the class build. (4) The 4th to 14th tables introduce the properties and functions of object classes in MatDEM as well as the usage of static function classes. For details, please refer to Sect. 2.2.3.

2.2 The Program Structure of MatDEM 2.2.1 The Software Folders of MatDEM Users should enter the root directory of MatDEM, where the usage of each subfolder is then displayed as shown in Table 2.1. In addition to the subfolders mentioned above, a series of secondary development example codes are stored in the root directory for reference. These example codes can be stored in any folder. In fact, other than system folders and system files that cannot be deleted, users can add or delete folders or files in the root folder. Generally, they usually only need to clean up files that are no longer used in the data and TempModel folders.

2.2 The Program Structure of MatDEM

37

Table 2.1 The software folders of MatDEM and their usage Folder

Usage

Note

data

Store the data files of simulation

Can be cleared regularly

data\step

Store the temporary files when loading circularly

Can be cleared regularly

fun

Store the user’s custom functions

Don’t delete the .p files!

gif

Store the GIF animations created by post-processing module

Can be cleared regularly

Mats

Store the .txt/.mat files recording the properties of Can create or delete any file materials

Resources

Store the logo of software and the picture when launching

Don’t delete this folder!

slope

Store the digital elevation data files on structural surfaces

Can create or delete any file

TempModel

Store the temporary model generated in each step Can be cleared regularly

XMLdata

Store the basic configuration of program and the localization files

Don’t delete this folder!

2.2.2 The Hierarchical Structure of MatDEM The hierarchical structure of MatDEM is shown in Table 2.2. The bottom layer of the program is based on MATLAB matrix operation functions. MatDEM only calls the most commonly used MATLAB functions and operations in most conditions. Upward is the MatDEM function set (including the basic function set fs and the modeling function set mfs), followed by the MatDEM control center (build), the solver (model), and the record class (modelStatus). Above these is object; the prefix obj- represents objects, where obj_Box is a basic class in the program and obj_3Axial is a laboratory class that will probably be replaced by obj_Box in the future. The top layer is the secondary development code prefixed by user-, which is usually based on MatDEM functions. Among example codes under the root directory of the software, only 3AxialNew is based on the class obj_3Axial; the rest are based Table 2.2 The hierarchical structure of MatDEM Category

Class and code files

Level

The secondary development of MatDEM

Secondary development codes user_*

4(top)

The modeler of MatDEM

Simulation box obj_Box, numerical laboratory obj_3Axial, material class material, cutting tool Tool_Cut

3

The controller and solver of MatDEM

Control center build, solver model, recording class modelStatus

2

The function sets of MatDEM

Basic function set fs, modeling function set mfs

1

The MATLAB functions

Matrix calculation

0(bottom)

38

2 The Basic Structure of MatDEM

Fig. 2.7 The simulation box and the deposited elements (object B of class obj_Box)

on the class obj_Box. Building an instance object B of the class obj_Box will create a default three-dimensional box, as shown in Fig. 2.7. In this box, the initial geometric model can be established by the gravity sediment, compacting sample and reducing gravity operations. The size of the model, the particle size distribution of elements, and the stratification of the model can all be customized, details of which will be provided in subsequent chapters. The hierarchical structure of MatDEM is as described previously. First, a simulation object (such as B) is built by a modeler (such as obj_Box), following which all systems under it are automatically created. Each example code in the root directory of MatDEM usually has only 150 to 300 lines; however, it can still create a variety of different numerical models, and only a small amount of code is needed to build a numerical model by using the functions of the software.

2.2.3 The Main Classes in MatDEM Based on object-oriented programming ideas, MatDEM abstracts objective matter and practical problems into classes. Instantiating a class (such as obj_Box) into an object (such as B) during numerical simulation is easier for users to learn, modify, and maintain, in comparison with process-oriented programming. They can refer to example codes to recognize classes (such as obj_Box), their objects (B), and functions (B. buildInitialModel). The main classes in MatDEM are described as follows. For properties and functions, please refer to Appendices A and B for details.

2.2 The Program Structure of MatDEM

39

(1) The Class of Simulation Box Modeler obj_Box obj_Box is the class of simulation box modeler whose function is to create a rectangular three-dimensional space, in which users can build various models. Most of the example codes are based on this class. In the initial geometric modeling stage, the instance object B, i.e., the simulation box, is usually created using the class obj_Box. The most important property of B is B.d, which is the object created by the class build. The laboratory modeler class obj_3Axial is similar to the class obj_Box; however, because only 3AxialNew uses this class, it will not be described here. (2) The Class of Control Center build Class build is the control center and data center for modifying the model, transferring data, controlling numerical simulation, and displaying simulation results. After creating an object B, and the function B.buildInitialModel of the class is called, the program will then automatically create the object through the class build and save it in B.d. In the example codes, the variable d is usually created using the command d = B.d. The function in the class build can be called directly in the following code by using d.* to perform data processing, control object, pre-processing, post-processing, and other operations. The methods in the class build are the most important and most commonly used methods (i.e., the functions of a class) in MatDEM. For details, please refer to Appendix B. (3) The Class of Solver Model The class model is a discrete element solver and is also the core of MatDEM. It records the current information for all the elements of a discrete element model, including various parameters, interaction with neighboring elements, simulation settings, and so on, as well as basic discrete element calculation functions, such as neighbor searching, iteration calculation, and GPU settings. After creating the data center object d, the object model will be created by d.setModel and saved in d.mo. (4) The Class Recording Simulation Status modelStatus The class modelStatus is mainly used to record the process of simulation and deal with simulation results. The object of this class is automatically created by the program when the object of class model is created and saved in d.status. The properties of this class are primarily used to save various types of information during the simulation. Each time the command d.recordStatus() is run, the program will record the current time (d.status.Ts), boundary forces (such as leftBFs, rightBFs), and system energy (such as kineticEs, elasticEs) in the corresponding properties of d.status. After the numerical simulation is completed, saved data can be operated by the methods of this class (see the help file for details). Changes in boundary forces and system energy during the numerical simulation can then be obtained, and this information can also be displayed through the post-processing function d.show.

40

2 The Basic Structure of MatDEM

(5) The Material Class material The class material is used to record the material information of elements, including macroscopic mechanical properties of materials and microscopic mechanical parameters of elements. When creating an object of class material, the micromechanical properties of elements are obtained according to the macro-parameters of the input material. The micromechanical parameters of elements are usually determined by conversion formulae Sect. 1.6.2. However, microscopic parameters directly obtained from conversion formulae usually make the overall mechanical properties of the model weaker; therefore, material training is necessary. After training, the appropriate ratio can be obtained (mat.rate, where mat is an object of material). When simulating, macro-parameters are multiplied by the rate and then substituted into conversion formulae to obtain the appropriate mechanical parameters of elements (please refer to BoxMatTraining for details). The mechanical properties of the macroscopic material are given in the object of the class material, whereas the microscopic mechanical parameters of elements are obtained according to conversion formulae when the diameter of element is mat.d. It is important to note that in the conversion formulae, K n is the stiffness of two springs that connect with each other in series between two elements, whereas k n in the class material is the stiffness of a single spring between elements. Therefore k n = 2K n and other parameters have a similar rule. For example, for the breaking displacement, x b = 0.5X b . (6) The Class of Model Cutting Tool Tool_Cut The main function of class Tool_Cut is to use Excel to cut the model using polyline data, digital elevation data, polygons, triangle faces, and so on to divide the model into different layers or to generate cracks and joints. For details, please refer to the examples BoxModel, 3DJointStress (Chap. 7), and 3DSlope (Chap. 8). In these examples, the object of Tool_Cut is usually named C. (7) Function Set fs and mfs In MATLAB, a function set is a special class that has methods but no property. Using a function set to group related functions together facilitates their call. In MatDEM, the two most important function sets are the base function set fs and the modeling function set mfs. The function set fs primarily contains the basic functions of the program, including basic drawing functions, basic matrix transformation functions, and parameter calculation functions. Most of the functions are internal functions of the system that are called by other classes or function sets. The function set mfs primarily contains various functions for modeling. Users can also place custom functions in the same folder to create function sets for calling during simulations (please refer to Sect. 5.4.2 for details). For example, they can create a folder tunnelFun that saves tunnel-related functions that can be shared with others.

2.3 Types of Element in MatDEM

41

2.3 Types of Element in MatDEM 2.3.1 Active Element, Wall Element, and Virtual Element There are two basic types of element in MatDEM, namely, active elements (model elements) and wall elements, as shown in Fig. 2.8. During numerical simulation, the software calculates the forces of active elements and moves them (unless they are locked in degrees of freedom); their indexes range from 1 to mNum (Sect. 2.3.3). Regarding wall elements, their forces are not directly calculated and they remain stationary (unless they are moved by command): their indexes range from mNum to 1 ~ aNum - 1. The wall elements are divided into two further types: the first type is preset boundary elements of the program, such as elements on the six boundary surfaces of the simulation box (obj_Box): these are special wall elements and the second type is ordinary wall elements (wall) used to construct objects that do not move in the model. In images generated by the MatDEM post-processing module, wall elements are displayed in green by default. However, it should be noted that green elements are not always wall elements. For example, when the command d.show(‘aR’) is executed, the radii of platen elements are often displayed in green as they are close to the average radius of elements (B.ballR); however, the platen elements are active. The software does not calculate the forces and motions of wall elements; therefore, when a large number of wall elements is added to the model, the amount of calculation of the numerical simulation will not be substantially increased. When adding elements to the model using the function d.addElement, the type of elements added can be declared by the third input parameter, which takes a value between “model” (active element) and “wall” (wall element), whereas the default value is “model.” Once elements are added to the model, the active and wall elements can be redefined by the functions d.defineModelElement and d.defineWallElement. There is also a virtual element that is very special in the model, indexed aNum. It is not an actual element, and there is no force between it and the remaining elements. Fig. 2.8 The two types of basic elements in MatDEM

42

2 The Basic Structure of MatDEM

It will not be displayed when the post-processing command is executed and will only be used as a marker. The high-efficiency discrete element numerical simulation of MatDEM is based on matrix calculation. Because the number of neighbors of each element is inconsistent, constructing a neighbor matrix means vacant positions in the neighbor matrix need to be filled with the number aNum. Thus, the virtual element is introduced, and all the last elements of parameter arrays prefixed with abelong to the virtual element. When calculating the force of an element, MatDEM first calculates the force between the element and all its neighbors. It then judges the indexes of its neighbors, and if it equals aNum, the force between these two elements will be set as 0 to accurately calculate the force between an element and its neighbors. The coordinates of the virtual element always coincide with the element, the number of which is aNum –1 and the radius of which is 1/4 B.ballR.

2.3.2 Fix the Degree of Freedom of Elements The degree of freedom of active elements can be fixed by the function addFixId of class build. The direction of motion of an object can be restricted by fixing the degree of freedom of elements: the corresponding command is d.addFixId(direction, gId), where direction is the direction in which the degree of freedom will be fixed, its value can be “X,” “Y,” or “Z,”; whereas gId is the index array of corresponding elements. Alternatively, modifying the matrices FixXId, FixYId, and FixZId in the object d.mo (created by the class model) can also fix the degree of freedom of elements in a certain direction. For example, in the example BoxPile, the degree of freedom of the pile in the X-direction is locked, which means that the pile in a two-dimensional plane can only move up and down in the Z-direction. In addition, when applying a directional pressure to the model through a platen, the degrees of freedom other than the normal direction of the platen should also be locked by the function B.setPlatenFixId(). This prevents the platen from slipping off the edge of the sample when the pressure is too great. When all the degrees of freedom of an active element are locked, its effect is the same as a wall element, although it is still an active element. The essence of fixing the degree of freedom of elements is to record the fixing information using the parameters FixXId, FixYId, and FixZId in d.mo. Thus, during the equilibrium iteration, these elements will not move in the direction of the degree of freedom. However, they can still be directly moved by the function d.moveGroup or by modifying their coordinates in d.mo. The degree of freedom of elements can be unlocked by the function d.removeFixId.

2.3 Types of Element in MatDEM

43

2.3.3 The Rule of Numbering Elements In MatDEM, the total number of elements is aNum, which is recorded in d.aNum and d.mo.aNum. Each element has a unique index ranging from 1 to aNum. The number of active elements is mNum, recorded in d.mNum and d.mo.mNum, and their indexes range from 1 to mNum, whereas the elements numbered mNum + 1 to aNum - 1 are fixed. The element numbered aNum is the virtual element. Therefore, in MatDEM, the index of an active element is always lower than that of a wall element. If an active element is converted to a wall element by the function d.defineWallElement, for example, re-declaring the elements of a platen as wall elements, their indexes will also change and vice versa. The change of indexes and resulting series of data adjustments are automatically carried out by MatDEM.

2.4 The Data Structure of MatDEM 2.4.1 The Property Arrays of Elements The various property information pertaining elements are mostly recorded in the property array in d (object of class build) and d.mo (object of class model). Furthermore, the property array in d records the initial state of elements, whereas the core calculation module of MatDEM is d.mo, which records the current state of model elements. Many basic properties in d.mo are owned by both active and wall elements, such as three-dimensional coordinates (aX, aY, aZ), element radius (aR), and microscopic mechanical properties (normal stiffness coefficient aKN, tangential stiffness coefficient aKS, critical breaking force aBF, initial shear strength aFS0, and inter-element friction coefficient aMUp). The names of these property arrays all begin with the letter a (all), the lengths of these arrays are all aNum, the row index corresponds to the index of element, and the array values record the property value of the corresponding element, for instance, d.mo.aX(1) records the X-coordinate of the first element. Because wall elements do not move, only the values of active elements are recorded in motion-related property arrays. These include the following: mass of the element (mM), damping (mVis), speed in three directions (mVX, mVY, mVZ), acceleration (mAX, mAY, mAZ), damping force (mVFX, mVFY, mVFZ), and body force (mGX, mGY, mGZ, where mGZ is equivalent to gravity). The names of these property arrays begin with the letter m and the lengths of the arrays are all mNum, indicating that they are parameters unique to active elements. For further details on these parameters, please refer to the property sheets of class build and model in the help file.

44

2 The Basic Structure of MatDEM

2.4.2 The Neighbor Matrix and Connection Information Matrix The neighbor matrix of elements (d.mo.nBall) is an important concept in MatDEM. The neighbor matrix has mNum rows and corresponds with active elements one by one. The indexes of adjacent elements of each active element are recorded row by row. The number of columns in the neighbor matrix ranges from several columns to tens of columns. Figure 2.9 shows the neighbor matrix of a two-dimensional model, which comprises 757 rows and 10 columns. The number of columns in the neighbor matrix is determined by the element that has the most neighbors. Thus, elements of a 3D model have more neighbors and the neighbor matrix usually contains tens of columns. When there are a large number of small diameter elements near a large diameter element, the number of neighbors will increase significantly. The number of columns in the matrix nBall generally increases as the ratio of the maximum to minimum element size increases. To ensure proper calculation cost, the radius ratio of elements in MatDEM should not exceed five, and clump can be used to construct larger particles (see Sect. 2.6 for details). Because the number of neighbors of each element (each row) is inconsistent, in order to construct a neighbor matrix with the same column length, the vacant positions in the neighbor matrix are filled with the index aNum (virtual element). For example, in Fig. 2.9, aNum is 898: the data indicates that the first element has

Fig. 2.9 The neighbor matrix d.mo.nBall (the values represent element indexes)

2.4 The Data Structure of MatDEM

45

nine neighbors (excluding the virtual element 898) and the second element has seven neighbors. The matrix nBall then records relationships between elements, that is, which two elements form a connection. The numerical calculation of MatDEM is based on nBall, through which a series of matrices the same size as nBall can be obtained. These matrices that record the connection relationship as well as the corresponding property value between elements and their neighbors are called connection information matrices, and include the filter matrix and the properties matrix. The filter matrix is a Boolean matrix: taking d.mo.cFilter as an example (Fig. 2.10), cFilter corresponds to the element index in nBall one by one, and indicates whether an element and its neighbor are in a compressive state (if the value is 1 they are compressive). Combining nBall and cFilter we can obtain the compression state of all connections between elements. For example, the first column of the first row of nBall has a value of 2 and the value at the corresponding position of cFilter is 1, indicating that the connection between element 1 and element 2 is currently in a compressive state. Similarly, the matrix bFilter can be used to determine whether elements are cemented with each other. The matrix tFilter can be used to determine whether elements are in tension. These filter matrices record the state of connections between elements.

Fig. 2.10 cFilter, the filter matrix recording the compressive status of connections (1 indicates the connection is in a compressive state)

46

2 The Basic Structure of MatDEM

Fig. 2.11 nFnX, the X-component of the normal spring force between elements

The property matrices are usually numerical matrices (double). Taking d.mo.nFnX as an example (Fig. 2.11), nFnX,which corresponds to the element indexes in nBall one by one, records the X-component of normal spring force between elements. Based on nBall and nFnX, we may calculate the X-component of normal spring force of any connection. For example, the first column of the first row (belongs to element 1) of nBall has a value of 2, and the value at the corresponding position of nFnX is 0.0145, indicating that the element 1 is subjected to a normal spring force of –0.0145 N in the X-direction from element 2. Similarly, the matrix nFsX can be used to obtain the X-component of tangential spring force; nFsX is added to nFnX to obtain the matrix nFX, that is, the X-components of total force acted on elements. After the summation of the matrix nFX in the horizontal direction, the X-components of net force acted on elements can be obtained. Such property matrices include the residual strength coefficient of connection (nBondRate), the connection stiffness matrix (nKNe, nKSe, nIKN, nIKS), the three components of normal spring force (nFnX, nFnY, nFnZ), the three components of tangential spring force (nFsX, nFsY, nFsZ), initial overlap of clump connections (nClump), and so on. These property matrices record the properties of connections between elements. Taking nFnX as an example, its nomenclature is neighboring Force of normal spring in X-direction.

2.4 The Data Structure of MatDEM

47

2.4.3 The Data Structure and Operation of Groups (1) The Data Structure of Groups In MatDEM, we can define a set of element indexes as a group and then perform various operations on this group. Such as the automatically generated boundary groups (e.g., lefB) and platen groups (e.g., topPlaten) when initializing the model. As shown in Fig. 2.12, the element indexes of these groups are recorded in d.GROUP. For example, d.GROUP.lefB records the element indexes of the left boundary, whereas d.GROUP.sample records the element indexes of the sample group. d.GROUP records all groups in the model along with their information, including the following three types of group: (1) Boundary groups, comprising the six default boundaries generated by the modeler (left boundary lefB, right boundary rigB, front boundary froB, back boundary bacB, bottom boundary botB, and top boundary topB). These boundary groups are all composed of wall elements. (2) Ordinary groups, including ➀ the 6 platens automatically generated by the system. When a platen does not exist, its corresponding matrix is empty, that is, [ ]; ➁ when initializing the model, the group sample is generated inside the simulation box; ➂ using the function d.addGroup, we can customize new groups that will be automatically recorded in d.GROUP. Note: the names of custom groups cannot start with “group”. (3) The matrices starting with group- in d.GROUP record information on groups and the elements they contain, including ➀ groupId: records the group numbers to which each element belongs. Every element in the model has a group number, and the length of this array is aNum. The rule for naming the group numbers

Fig. 2.12 The groups in MatDEM

48

2 The Basic Structure of MatDEM

of elements in MatDEM is as follows: the group numbers of elements that do not belong to any specific group are 0; the group numbers of the left, right, front, back, bottom, and top boundary elements are –1 to –6; the group numbers of left, right, front, back, bottom, and top platen elements are 1 to 6; the group numbers of sample elements are 10. When adding elements through the function d.addElement(matId, addObj), if the array addObj.groupId exists in the structure data addObj, the group numbers of the new elements are defined by groupId in the structure; if groupId does not exist, the group numbers are 0. groupId plays an important role in the process of creating clump. For details, please refer to Sect. 2.6.2. ➁ groupProtect: records the group names of protected groups, the elements of which will not be deleted by d.delElement. By default, groupProtect records the names of six boundary groups to prevent the boundary elements from being deleted. The group name of a normal group also can be added to groupProtect by using the function d.protectGroup. ➂ groupMat: records the material numbers of all groups in the model. groupMat is a structure, which is set by the function d.setGroupMat, and the materials of groups are assigned to the model by the function d.groupMat2Model. (2) The Operating Functions of Groups The class build of MatDEM provides a set of operating functions on groups. Table 2.3 shows the major operating functions of groups. For details, please refer to the appendix or the help file in the root directory of MatDEM. By using addGroup(gName, gId, varargin), we can define specified elements as a group, where gName is the group name, gId is an array of element indexes, and varargin is an optional parameter. The user can then input the material number of the group (i.e., the material index in d.Mats). A group is a collection of specific indexes Table 2.3 The major operating functions of groups in MatDEM Function name

Usage

addGroup

Define a new group in the current model

breakGroup

Break connections in a specific group or between two groups

breakGroupOuter

Break connections between a group and the outside elements

connectGroup

Cement connections in a specific group or between two groups

connectGroupOuter Cement connections between a group and the outside elements delGroup

Delete the group with a specific name (will not delete the corresponding elements)

removeGroupForce Ignore all forces between two groups rotateGroup

Rotate the elements of a specific group

minusGroup

Minus two groups that overlap with each other

moveGroup

Move a group, including wall elements and elements with fixed degrees of freedom

protectGroup

Declare a group as protected and record its name in groupProtect

2.4 The Data Structure of MatDEM

49

of elements. When a group is added or deleted, the number of elements in the model does not increase or decrease. When building a complex model, the group subtraction function minusGroup can also be used. The first input parameter of this function is the group to be partially removed (subtracted), the second is the group that will remain completed (subtracting), and the third input parameter is the radius ratio of the second group, as described in Sect. 6.1.2. The group can then be converted into a structure by the function group2Obj, which may be imported later to other models, as shown in Sect. 3.2.1. Filters can also be used to filter out specific elements and then create groups quickly, as described in Sect. 3.2.2.

2.5 The Contact Model Between Elements MatDEM uses the linear elastic contact model by default; however, it still provides an interface to define the normal contact force, that is, the property d.mo.FnCommand of the class model. Users can customize the value of FnCommand to define other nonlinear contact models. Depending on user’s demands, MatDEM will open the interface of the contact model so that users can freely define various contact models, and to realize the definition of complex materials.

2.5.1 The Linear Elastic Contact Model In Sect. 1.2.1, we introduced the basic principles of the linear elastic model. When the contact model in the program is linear elastic, the value of the parameter FnCommand is as follows: FnCommand='nFN0=obj.nKNe.*nIJXn;';

2.5.2 The Hertz Contact Model The normal contact force between the elements can be calculated by the Hertz contact model, when the particle surface is smooth and non-adhesive, the contact surface is extremely small compared to the total surface area, the contact force is perpendicular to the contact surface and only elastic deformation occurs. As shown in Fig. 2.13, the two elements with radii R1 and R2 are in elastic contact and the normal overlap A satisfies the equation:

50

2 The Basic Structure of MatDEM

Fig. 2.13 Sketch map of the Hertz contact model

A = R1 + R2 − |r 1 − r 2 | > 0

(2.5.1)

where r 1 and r 2 are the position vectors of the two elements, respectively. The contact surface is circular and its radius a satisfies the equation:  a=

A

R1 R2 R1 + R2

(2.5.2)

In the discrete element method, Poisson’s ratio ν of an element is 0, and the relationship between the elastic modulus E and the normal stiffness K n of the element is as follows: Kn πR

(2.5.3)

4(R1 + R2 )kn1 kn2 a3 3πR1 R2 (kn1 R2 + K n2 R1 )

(2.5.4)

E= and therefore the normal force F n is Fn =

For the Hertz contact model, please refer to related literatures on particle media mechanics. In the program, the Hertz contact model is defined by modifying the string d.mo.FnCommand. For example, in the file 3AxialNew2, FnCommand is assigned with the following string (note: because the compiler of MatDEM1.32 does not recognize the linefeed symbol, the following code should actually be written on the one line):

2.5 The Contact Model Between Elements

51

d.mo.FnCommand='nFN1=obj.nKNe.*nIJXn; nR=obj.aR(1:m_Num)*nRow; nJR=obj.aR(obj.nBall); Req=nR.*nJR./(nR+nJR); nE=obj.aKN(1:m_Num)*nRow./(pi*nR); nJE=obj.aKN(obj.nBall)./(pi*nJR); Eeq=nE.*nJE./(nE+nJE); nFN2=-4/3*Eeq.*Req.^(1/2).*abs(nIJXn).^(3/2); f=nIJXn＜0; nFN0=nFN1.*(～f)+nFN2.*f;';

2.6 The Elastic Clump 2.6.1 The Principle of the Elastic Clump The basic elements of MatDEM are small balls, which can be made to overlap and form a clump to model non-spherical particles and objects. As shown in Fig. 2.14, in the clump model, the two elements overlap with each other and the overlap is l 0 , the diameter of each element is d, the equilibrium distance is set to d - l0 , and the distance between the two elements is r. The relative displacement between the elements can then be calculated using formula (2.6.1): X n = r − (d − l0 )

(2.6.1)

According to this formula, in the state shown in Fig. 2.14a, the relative displacement X n of the two elements is zero and they are in a state of equilibrium. In Fig. 2.14a, the vertical line segment is the contact surface of the two elements. In Fig. 2.14b, when the distance between the two elements increases, X n increases and tension is generated between the elements. Similarly, when the relative displacement reaches the breaking displacement X b , the connection breaks (Fig. 2.14c) but is followed by re-cementing (see below). When the two elements are pressed against each other, a compressive force is generated (Fig. 2.14d). In fact, the clump model reduces the equilibrium distance between the two elements and subtracts the initial overlap when calculating the relative displacement. In this way, complex models can be built by using the clump model. As shown in Fig. 2.14e, the four elements overlap and reach

52

2 The Basic Structure of MatDEM

Fig. 2.14 Sketch map of the elastic clump

a state of equilibrium. The actual contact is shown in Fig. 2.14f. By overlapping the elements, a clump model with a smooth surface can be established. When a connection is declared as a clump, the amount of overlap between elements corresponding to the connection will be set as the initial overlap amount (i.e., the current spring deformation amount is 0 and there is no interaction between elements) and recorded in the matrix d.mo.nClump. When calculating the force between these two elements, the actual overlap between them is subtracted from the initial overlap. The relative position between clump elements is not fixed, and there is still forces and relative displacements between elements. Therefore, the clump in MatDEM is deformable, which is different from commercial software. The initial overlap is only for the connection between two specific elements. When the connection is broken and the two elements are in contact with others, the initial overlap will no longer exist, and the total volume of the model will be incorrectly increased. Therefore, it is necessary to ensure that the clump connection cannot be broken. During each iteration calculation, if a value in the matrix nClump is not zero, the software will automatically set the value of the corresponding connection in bFilter to 1, which makes it unbreakable (unless the strain is very large, see below). However, the neighbor matrix nBall contains only the indexes of neighbor elements within a certain distance (determined by d.mo.dSide), which is approximately 0.4 times the average element radius by default. If the distance between the two elements connected by the clump exceeds the neighbor range, the clump connection will also

2.6 The Elastic Clump

53

break. The tensile strain of most geotechnical materials cannot reach this level. If users need to simulate materials with particularly great tensile strain, such as rubber bands, they can set a greater initial overlap between elements. For example, in BoxSlopeNet2, the net can be created by the following command: netObj=mfs.denseModel(0.8,@mfs.makeNet,B.sampleL*2,B.sampleL/3*2, cellW,cellH,B.ballR);

Reducing the first input parameter 0.8 (Rrate) will increase the tensile strain of the clump material. Rrate should usually be greater than 0.5 to avoid interaction between clump elements that are far apart. At the same time, the elements will be too crowded when a smaller Rrate (such as 0.1) is used, which may increase the amount of calculation (as the number of column in nBall increases). Elements that make up the clump connection may also be separated, that is, acting at a distance. However, clump elements cannot be too far apart because this would require a greater d.mo.dSide (the search range when searching for neighbors). This function is rarely used and will not be described in detail here.

2.6.2 Usage of the Elastic Clump When creating the initial geometric model (B.buildInitialModel), if B.isClump is set as 1 (the default value is 0), the software will automatically generate a series of clump grains through the command B.createClump(B.distriRate). The greater the distribution rate of B.distriRate, the more irregular the shapes of generated clumps. The example codes in BoxSlope1 ~ 2 demonstrate how to automatically generate clumps. Figure 2.15 shows the clump sediment generated by the example code BoxSlope1. Each clump consists of two to eight basic elements. The system distinguishes different clumps by d.GROUP.groupId. The group numbers of these automatically generated clumps are decremented from –11. When the function d.setClump() is run, elements with a group number –11 will be considered as one clump. Similarly, elements with the same group number such as –12, –13 will be treated as the same clump, respectively, and the initial overlap is stored in d.mo.nClump. Therefore, clump grains can be created automatically. These clump grains all belong to the sample group, which can be converted into a structure by the function d.group2Obj and then imported into a new model. For example, in BoxSlope2, group and structure transformation is implemented with the following code: packBoxObj=d.group2Obj('sample') … boxObjId=d.addElement(1,packBoxObj);

54

2 The Basic Structure of MatDEM

Fig. 2.15 The clumps generated automatically by MatDEM

(a) The structure of clump

(b) groupId in the structure defines different clump grains

Fig. 2.16 The structure of clump and its data structure

After running the function group2Obj, the information on elements in the sample group is converted into the structure packBoxObj. As shown in Fig. 2.16a, the structure includes the coordinates, radius, and groupId of elements, where groupId is decremented from –11 to –406. The first clump in the lower left corner of Fig. 2.15 contains eight basic elements. These correspond to the 1st to 8th group numbers of groupId, all of which are –11 (Fig. 2.16b). Users can write a specific function of clump grains according to their actual demands; generate the coordinates, radius, and group number of elements in the structure; and import the structure into the model to generate clumps with various shapes.

2.6 The Elastic Clump

55

In MatDEM, the operation of a clump is based on the matrix nClump described in Sect. 2.6.1. If a value in the matrix nClump is 0, the corresponding connection will not be considered as a clump connection and it can be broken under a great tensile force. Therefore, if users want to set a clump connection between two elements that are just in contact, they can assign a very small value to the connection property in the nClump. For a more extensive application of clump, please refer to the BoxSlopeNet example.

Chapter 3

Geometric Modeling and Material Setup

As described in Chap. 2, the modeling and numerical simulation in MatDEM can be divided into three steps: packing model of particles, assigning material by groups, and calculating via an iterative method. This chapter will focus on the first two steps and show the corresponding code. It mainly includes packing model of particles, grouping and material setting, balancing models, and joint setting.

3.1 Building a Numerical Simulation Box 3.1.1 Building a Packing Model (1) Building the Initial Model In MatDEM, stacking modeling is the first step. This involves building an initial strata packing model by simulating gravity sedimentation in the real world. The code SlopeNet1 is a simple example to build a 3D packing model: clear; fs.randSeed(1);% build random model B=obj_Box;% build a box object B.name='box';%name of model B.sampleW=1;%width of model,X B.sampleL=1;% length of model,Y B.sampleH=1.2;% height of model,Z B.ballR=1;%mean radius of elements B.distriRate=0.2;

© The Author(s), under exclusive license to Springer Nature Singapore Pte Ltd. 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9_3

57

58

3 Geometric Modeling and Material Setup

First, build a Box Modeler (Object B). It is a cuboid model box equivalent to the container in numerical simulation and the subsequent simulation will be performed in the Model Box. The width, length, and height of the Model Box are defined by sampleW, sampleL, and sampleH (dimensions in X-, Y-, and Z-directions, respectively). When the sampleL is 0, a 2D model is obtained. The initial average radii of the sample element and boundary element are set by ballR. distriRate is the distribution coefficient of the element radius, which is used to control the distribution of element size. Thus, the ratio of maximum element size to minimum element size is (1 + distriRate)2 . B.isSample=1;%input 0 to get an empty box B.isClump=0;%input 1 to get clump particle B.BexpandRate=8;%expand the boundary B.PexpandRate=8;%expand the platen B.type='topPlaten'; B.setType(); B.buildInitialModel();

B.isSample = 1 (or 0) command chooses whether to generate sample elements (strata) in the Model Box. The default value of B.isSample is 1; however, when it is 0, an empty box will be generated, as shown in Sect. 3.1.2. The B.isClump = 1 (or 0) command chooses whether to generate clump grains, as shown in Sect. 3.2.6. B.BexpandRate and B.PexpandRate define the width of the boundaries and pressure platens, respectively, that is, the number of elements extending outward from the boundaries and pressure platens. In a triaxial test, the sample will sometimes expand laterally and push the lateral pressure platen. In this case, elements may leak from the gap between the top-bottom pressure platens and lateral pressure platens. To prevent element leakage, it is necessary to increase the size of the pressure platen; B.BexpandRate and B.PexpandRate can therefore be used to define the number of elements extending outward. The extended boundary model is shown in Fig. 3.1. In this figure, the pressure platen element and boundary element overlap. To avoid high stress caused by overlapping elements, MatDEM eliminates forces between groups by using the following removeGroupForce command: d.removeGroupForce(d.GROUP.lefPlaten,d.GROUP.botPlaten);

When the command B.buildInitialModel() is run, removeGroupForce command will be automatically executed and relevant information will be recorded in d.mo.SET.groupPair. The force between these groups will be eliminated automatically according to information record when calculating the force of elements. This command can also be applied to the modeling process, such as the following code from TBMcutter2:

3.1 Building a Numerical Simulation Box

59

Fig. 3.1 Extended boundary model

d.removeGroupForce(d.GROUP.Hob, [d.GROUP.topB;d.GROUP.rigB]);

The force between the “Hob” and top-right boundary is eliminated by this command. The command B.setType is used to control the type of pressure platens. There are six types of pressure platens in the Model Box, called left, right, front, back, bottom, and top. These platens compact the model, apply stress loading, or act as a buffer when displacement loading is applied to the boundary. So pressure platens can be generated as required when different numerical simulations are performed. As shown in Fig. 3.2, the command B.type = ’topPlaten’ generates the top pressure platen, whereas command B.type = ’TriaxialCompression’ generates all pressure

B.type=’topPlaten’;

(b)B.type=’TriaxialCompression’; (c)B.platenStatus=[0;0;0;0;1;1];

Fig. 3.2 Different pressure platen forms

60

3 Geometric Modeling and Material Setup

platens. The state of the pressure platens is recorded in the B.planenStatus matrix, which has six values corresponding to the left, right, front, back, bottom, and top pressure platens. The corresponding pressure platen will be generated when the value is 1. For example, when B.platenStatus is assigned an array [0; 0; 0; 0; 0; 1; 1], a model with bottom and top pressure platens will be generated (see Fig. 3.2c).This matrix will be modified when the command B.setType is run. Based on the aforementioned settings, the command B.buildInitialModel generates the initial model, as shown in Fig. 3.2. When this command is run, B.setSoftMat is automatically called. The material class is then used to create the material object stored in B.Mats. To speed up the subsequent packing, a soft sphere material is used in the initial packing of the program. (2) Gravity Sedimentation and Compacting Samples B.gravitySediment(); B.compactSample(); mfs.reduceGravity(d,n);

As shown in Fig. 3.2, the elements are arranged on regular grids in initial model. Furthermore, the gravity sedimentation command B.gravitySediment is used to simulate the random packing process in nature. In the process of gravity sedimentation, the elements in a regular arrangement will be assigned a random initial velocity (with zero gravity) and move to a random position. Then gravity will be applied to the elements to make them move down to simulate the process of gravity deposition in nature. The program can automatically and efficiently complete the process of gravity sedimentation because the process of gravity sedimentation has been accurately calculated in MatDEM. The parameter rate can be input to the function gravitySediment to adjust the number of iterations in gravity sedimentation, the default value is 1(see the help file for details). Geotechnical particles may be compacted after gravity sedimentation and become underconsolidated or overconsolidated soils in nature. MatDEM provides function B.compactSample to simulate sample with different stress histories and different compaction degrees, which generates load through the top pressure platen and compacts the model. When the number of compaction times is input, the default pressure is twice the element gravity. When the pressure is input, the sample is compacted by the specified pressure (see the help document for details). (3) Reduction Gravity Chapter 1 showed that when the stiffness of the element is small, the simple harmonic vibration period of the particle and time step to ensure the accuracy of calculation are large. In order to speed up the accumulation of elements and improve the efficiency of calculation, the initial model uses smaller stiffness (similar to rubber balls), and that will produce relatively large element extrusion deformation (elements overlap). In the second step of material assignment, material is assigned larger stiffness, which will lead to a sudden increase of elastic strain energy between elements.

3.1 Building a Numerical Simulation Box

61

If gravity and prestressing are not considered in the second step, gravity can be gradually eliminated at the end of the first step, so that the extrusion deformation between elements tends to zero. The command mfs.reduceGravity (d, n) can reduce gravity, the first input parameter is object d, and the second input parameter controls the reduced gravity coefficient, i.e., 1/(102n ), when n is greater than 4, gravity can be nearly eliminated. When building a model under gravity like landslide or foundation pit, gravity reduction is not necessary. Gravity reduction is mainly to reduce the elastic strain energy produced in the second step of material assignment to build a model rapidly. After establishing the initial model, gravity sedimentation, compaction, and gravity reduction, a stratigraphic accumulation was established.

3.1.2 Creating an Empty Box When B.isSample is 0, no sample element will be generated in the initial model. There is only an empty box as shown in Fig. 3.3, which only contains six boundaries and a bottom pressure platen. Since MatDEM must have active elements, the bottom pressure platen needs to be retained in the empty box. If bottom pressure platen is not needed, it can be deleted after adding new active elements. When an empty box was created, custom component structures can be added to complete the model (see Sect. 3.2 and the SlopNet example for details).

Fig. 3.3 An empty Box Model

62

3 Geometric Modeling and Material Setup

3.2 The Foundation of Modular Modeling 3.2.1 Modeling with a Structure It is difficult to get a model of a specific shape with a simple packing command. So in MatDEM, users may create serval structures and put them together to make a model. First, build a structure of a particular shape by processing the built packing model or using custom functions. Second, import structure data into the model. This section introduces the establishment of different structures and simulates the process of a rolling stone or column sliding down a slope and hitting a net with the SlopeNetNew2 code. (1) Building structures by cutting model MatDEM can build structures by cutting existing packing models. The essence of “cutting” is to build a specific element filter, through which a specific shape of structure (struct data) can be obtained. Run the SlopeNet1 code to obtain a packing model and then run the SlopeNet2 code to cut. The main commands of SlopeNet2 are as follows: sampleObj=B.d.group2Obj('sample'); sampleObj=mfs.moveObj2Origin(sampleObj); sphereObj=mfs.cutSphereObj(sampleObj,0.5); fs.showObj(sphereObj);

The packing model is converted into a structure by using the sampleObj = B.d.group2Obj (‘sample’) command, following which the cutting operation is performed. MatDEM has the basic structure cutting function built into the mfs class, for example, the mfs.cutSphereObj function can cut existing structures and obtain the spherical structure of a rolling stone. Because the mfs.cutSphereObj function is cut around the coordinate origin of the sampleObj, the default coordinate origin of any model built by packing is in the lower left corner of the model. The center of the sampleObj structure therefore needs to be moved to the coordinate origin before cutting. The second input parameter of the mfs.cutSphereObj function is the radius of the sphere. The fs.showObj command enables users to see the sphere, the radius of which is approximately 0.5 m by cutting, as shown in Fig. 3.4a. Figure 3.4b shows data for the structure sphereObj, where X, Y, and Z are the coordinates of elements, R is the element radius, and groupId is its group number, which can be used to define different clumps (Sect. 2.6.2). The sphere contains a total of 1884 elements with radii ranging from 2.51 to 3.61 cm. Users can also build structures manually and import them into the object of d. For example, they can define and display a component of three elements by running the following code. Based on this rule, functions can be defined to generate various structures.

3.2 The Foundation of Modular Modeling

(a) Sphere model;

63

(b) Data of the structure

Fig. 3.4 Structure data for a sphere

P.X=[1;1;1]; P.Y=[1;1;1]; P.Z=[1;1.04;1.08]; P.R=[0.02;0.02;0.02]; fs.showObj(P);

(2) Building structures with built-in functions MatDEM can also use functions to directly build structures, where the shape of the structure is used to calculate the coordinates of elements. A structure with a specific shape can therefore be obtained by combining discrete elements. netObj=mfs.denseModel(0.8,@mfs.makeNet,4,2,0.5,0.3,0.05); fs.showObj(net);

The mfs class contains a series of built-in structure functions, where the mfs.makeNet(4, 2, 0.5, 0.3, 0.05) function can directly build the structure of a net. The width of the net is 4 m and its height is 2 m, the width of the net hole is 0.5 m and its height is 0.3 m, and the radius of the element is 0.05 m. Because the net requires greater elasticity and high strength, the mfs.densemodel function is used to ensure that elements overlap and are dense. The first input parameter of the mfs.denseModel function is the overlap coefficient Rrate of the element. Rrate is used to define the ratio of adjacent element spacing to element diameter in the generation model and has a value of 0.5 when the amount of overlap between elements is 50%. The following input parameters implement a call to the mfs.makeNet function, as a result of which the structure of the retaining net is built as shown in Fig. 3.5. Similarly, the slope can be built using the function mfs.makeBox.

64

3 Geometric Modeling and Material Setup

Fig. 3.5 Structure of the retaining net model

(3) Building structures using custom functions Considering the diversity of modeling requirements, MatDEM supports using custom functions to build structures. The function interpreter f.run in MatDEM allows it to run the standard custom functions of MATLAB. The function of building the structure can be defined by MATLAB language and needs to return the array of coordinates and radii of elements in structures. The following code is a custom function used for building a column (see the “fun” folder of the software): function column=makeColumn(columnR,columnHeight,ballR,Rrate) columnR2=columnR-ballR; columnHeight2=columnHeight-ballR; ballR2=ballR*Rrate; disc=f.run('fun/makeDisc.m',columnR2,ballR2); column=mfs.make3Dfrom2D(disc,columnHeight2,ballR2); column.R(:)=ballR; column.columnR=columnR; column.columnHeight=columnHeight; column.ballR=ballR; end

In line 1, function is the keyword in the custom function of MATLAB, the column is the return value of the function (structure); makeColumn is the name of the function; and columnR, columnHeight, ballR, and Rrate are input parameters that denote the radius of the column, height of the column, radii of elements, and overlap coefficient Rrate, respectively. To achieve the overlap effect of Rrate, this function multiplies the radii of elements by Rrate, generates a closely contacted packing model, and then resets the original radius. Line 5 generates the structure of a disk (single layer) in the XY-plane by running the custom function makeDisc.m (in the “fun” folder);

3.2 The Foundation of Modular Modeling

65

the command in line 6 then moves and copies a two-dimensional disk along the Z-direction to build a column. The custom function makeDisc generates the coordinates and radius of the disk structure based on the radii of elements and radius of the disk. Examples of custom functions provided by the system are saved under the fun folder, and users can then create new folders as needed. Thus, a complex discrete element model can be built by defining a series of custom functions. function disc=makeDisc(discR,ballR) rate=1;%increase the radius of ball circleNum=ceil(discR/(ballR*2/rate)); dCircleR=discR/circleNum; X=0;Y=0;Z=0;R=ballR; for i=1:circleNum circleR=i*dCircleR; circle=mfs.makeCircle(circleR,ballR); X=[X;circle.X]; Y=[Y;circle.Y]; Z=[Z;circle.Z]; R=[R;circle.R]; end disc.X=X;disc.Y=Y;disc.Z=Z;disc.R=R; disc.discR=discR;disc.ballR=ballR; end

In the SlopeNet2 code, the custom makeColumn function is called using the column = f.run(‘fun/makecolumn.m’,0.5, 0.5, B.ballR,0.8) command, which results in a structure named “column” (see Figs. 3.6 and 3.7). Structures can be moved, rotated, and copied once they are established. Different structures can also be combined together to generate a new structure (see Sect. 7.1 and the mfs function set in the appendix for details). (4) Importing the structure into the model This section explains how to import a structure into a model and move it to a predetermined location by using the example of a column structure. First, an empty simulation box is created in the SlopeNet2 code into which structures are then added. column=f.run('fun/makeColumn.m',0.5,0.5,B.ballR,0.8); columnId=d.addElement(1,column); d.addGroup('column',columnId); d.rotateGroup('column','YZ',90);%rotate the group along XZ plane d.moveGroup('column',0.8,2.5,3.25); d.setClump('column');

66

3 Geometric Modeling and Material Setup

Fig. 3.6 SlopeNet model composed of multiple structures

(a) Column model recorded in d.GROUP;

(b) Element connections of the column (20% radius)

Fig. 3.7 A column model and its connections

First, use the function d.addElement to add elements to the model, where the first parameter is the material name (or material number, such as 1) and the second parameter is the name of the structure. Then run the d.addGroup command to set the imported structure as a group, where the first parameter is the group name and the second parameter is the element number (Id array). Next, rotate the model with d.rotateGroup function. The third line of code means that the column group uses its

3.2 The Foundation of Modular Modeling

67

centroid as the origin and rotates 90 degrees in the YZ-plane. Later the d.moveGroup command moves the imported structure to the desired position, where the first parameter is the group name and the last three input parameters are the distances that moves in X-, Y-, and Z-directions. Following this, import the structures established in this section into the model one by one to obtain the SlopeNet model shown in Fig. 3.6. Finally, SlopeNet3 code is run to complete the numerical simulation of a column and a ball hitting the retaining net. Once the structure is imported into the model (defined as a group), the column group (Fig. 3.7a) and its display of bonded connections (Fig. 3.7b) can be obtained using the following command. To display the bonding between elements, the elements need to be smaller. The property d.Rrate defines the radius ratio of displayed elements. Further details on post-processing commands are presented in Sect. 5.2. As shown in Fig. 3.7b, a three-dimensional net structure similar to a finite element model is formed when the model is presented via connections. d.showB=0; d.showFilter('Group',{'column'},'aR'); figure; d.Rrate=0.2; d.showFilter('Group',{'column'},'-aR');

3.2.2 Filtering (1) Definition and use of an element filter Specific elements are often selected in modeling and simulations to perform assignment, movement, and calculation. MatDEM selects specific elements by defining the filter. It is a Boolean array and the length of which is aNum or mNum depending on filtering properties. The value in the array is true (shown as 1) or false (shown as 0): when it is 1, the corresponding element is selected. For example, when the model object d is generated, the following code is run to generate the filter: f1=abs(d.mo.mVZ)＞0.1; f2=(d.mo.aMatId==1); f1Id=find(f1);

The aforementioned command in line 1 filters elements in which the speed of Zdirection is greater than 0.1 m/s and obtains filter f1 of length mNum. The command in line 2 filters elements in which the number of material is 1 and obtains filter f2 of length aNum. After running the code, the filter arrays of f1 and f2 are generated.

68

3 Geometric Modeling and Material Setup

( a) a filter array f1;

(b) Filtered array of element Id

Fig. 3.8 Definition of the element filter array

As shown in Fig. 3.8a, f1 is a Boolean array of 2269 × 1 (mNum is 2269) and f2 is a Boolean array of 5366 × 1 because aNum is 5366. In the array, the line number represents the element number, where the 10th element of f1 is 1, indicating that the Z-direction speed of element 10 is greater than 0.1 m/s. The speed of the 1st to 9th elements is less than 0.1 m/s. The command in line 3 converts filter f1 into the element number array f1Id through MATLAB’s find function (Fig. 3.8b), that is, it obtains an array of line numbers with the value of 1 (true) in f1. Thus, when line 10 of f1 is 1 (true), the first element value of f1Id is 10. Several filter functions are provided in the set of modeling functions mfs, such as getColumnFilter, getWeak-LayerFilter, and so on. Using these functions, elements can be filtered out within a specific area based on the coordinates of model elements. For example, in BoxLayer2, elements in the center area of the model are filtered out using the following code: centerFilter=mfs.getCenterFilter(sX,sY,sZ,r); d.addGroup('Pore',find(centerFilter));

getCenterFilter in line 1 uses coordinates (sX, sY, sZ) of input sample elements and the radius of the circle to filter out the circular area in the center of the model. Line 2 then uses the addGroup function to define these elements as “Pore” group. The surface of the packing model usually fluctuates slightly. Therefore, to obtain a flat surface, surface elements are filtered and cut in the second step of the sample code, as in the examples of BoxCrash2, BoxPile, and TBMcutter. The following code comes from BoxCrash2: mZ=d.mo.aZ(1:d.mNum);%get the Z of elements topLayerFilter=mZ＞max(mZ)*0.5; d.delElement(find(topLayerFilter));

3.2 The Foundation of Modular Modeling

69

Line 1 obtains the Z-coordinates of active elements in which (1:d.mNum) obtains an integer array of 1 to mNum, places this into the aZ array, and filters out the Z-coordinates of the aZ array from the 1st to the mNum element, that is, mZ (for further details on matrix operations and index in MATLAB, see Sect. 5.3.3). Line 2 generates the filter topLayerFilter for the top half of active elements. Line 3 uses the find function to determine how many of the upper half of elements must be deleted and then deletes them with the d.delElement function. In short, the filter array records whether the corresponding element is selected, and the find function obtains the number of the element for further modeling operations. (2) Generating filters with showFilter The post-processing function d.showFilter can obtain a filter based on slice location, group name, material number, and so on, which will then be automatically saved in d.data.showFilter. Further details on the use of this function can be found in Sect. 5.2.2.

3.2.3 Tool_Cut and Digital Elevation Model The modeling of digital elevation requires the use of the cutting tool Tool_Cut. Users import coordinate points and generate curves or surfaces, so this tool can cut and define groups with these curves. In Sects. 9.2.1, 10.1, and 10.4.1, data in the line table is used to cut the model. (1) Modeling with the data of the line table in Excel Two-dimensional modeling of digital elevation can be simply explained using LandSubsidence as an example. In the LandSubsidence2 code, the main cutting code is as follows: C=Tool_Cut(d);%cut the model lSurf=load('slope/LandSubsidence.txt');%load the surface data C.addSurf(lSurf);%add the surfaces to the cut C.setLayer({'sample'},[1,2,3]); gNames={'lefPlaten';'rigPlaten';'botPlaten';'layer1';'layer2'}; d.makeModelByGroups(gNames);%build new model using layer1 and 2

C is the object of Tool_Cut, and data on elevation faces is saved in the LandSubsidence.txt. In the “slope/landslide elevation.xlsx” file, a line chart of this elevation surface is provided where users can view the modified elevation surface and update it to the txt file. C.addSurf allows line data points in the lSurf matrix to be read into the C.Surf array. The data type of the C.surf array is scatteredInterpolant, the structure and significance of which can be found in the scatteredInterpolant command of

70

3 Geometric Modeling and Material Setup

MATLAB. For example, running LandSubsidence1 and 2 codes, the cut-out stratum model is shown in Fig. 3.9b. In the example, the model is divided into two layers with three elevation faces, and layer1 and layer 2 are numbered from bottom to top, where layer1 is defined as wall elements. (2) Building 3D models with digital elevation data MatDEM supports the modeling of digital elevation data, which essentially uses three-dimensional faces (a two-dimensional face is a line) to cut models, define different groups, and perform operations such as the movement and deletion of groups. Using the Tool_Cut tool and modeling of digital elevation, very complex 3D geometry models can be built. The digital elevation data is spatial data that describes

(a) Curves in the Excel;

(b) Generated layers Fig. 3.9 Model defined by excel curves

3.2 The Foundation of Modular Modeling

71

the morphology and characteristics of the surface fluctuation. It is composed of the elevation values of regular grid points on the ground to form a matrix and grid dataset, which includes X- and Y-coordinates and elevation Z. The elevation data collected in situ may be single-column coordinate values that need to be processed to obtain the matrix form required by the Tool_Cut object. For further details on the 3D modeling of digital elevation data, see Chap. 8.

3.3 Modeling Based on Digital Images Through MATLAB language and add-on functions’ development, an external complex geometry model can be imported into MatDEM to build the corresponding discrete element model.

3.3.1 Importing a Binary Image to Cut a Model MatDEM can load an external 2D image to cut the model and obtain a group of the corresponding shape. The aim is to create an element filter based on the black area in the image and then filter and generate the corresponding group of elements. Although it is difficult to select an area of a complex shape in a packing model, this problem is easily solved by importing the image to define the area. (1) Principle of importing image function The built-in mfs.image2regionfilter (fileName,imH,imW) function in MatDEM makes a filter from the image which is then saved in the fun folder. Its input parameters are the name of image fileName, and the resulting height and width of the image matrix imH and imW. For further details on the use of custom functions, see Sect. 5.4.2. function regionFilter=image2RegionFilter(fileName,imH,imW) source=imread(fileName); source=imresize(source,[imH,imW]); sumS=flipud(sum(source,3)); regionFilter=sumS==0; end

The above is the source code of the image2RegionFilter function in the fun folder that returns the regionFilter matrix. The black part of the image is judged to be 1, the rest are judged to be 0, and an image Boolean matrix of imH × imW regionFilter is obtained.

72

3 Geometric Modeling and Material Setup

(2) Principle of filter model elements function After obtaining the regionFilter matrix, the mfs.applyregionFilter (regionFilter, sX, sZ) function is used to filter discrete elements corresponding to the black part of the image. This function is provided in the fun folder, too. function sFilter=applyRegionFilter(regionFilter,sX,sZ) [imH,imW]=size(regionFilter);%get height and width sNum=length(sX); x1=min(sX);x2=max(sX); z1=min(sZ);y2=max(sZ); imBallI=floor((sX-x1)/(x2-x1)*(imW-1))+1; imBallJ=floor((sZ-z1)/(y2-z1)*(imH-1))+1; sFilter=false(sNum,1); for i=1:sNum sFilter(i)=regionFilter(imBallJ(i),imBallI(i)); end end

The input parameters of the function are the image Boolean matrix and the X- and Z-coordinates of sample elements used for filtering. The function first normalizes the X- and Z-coordinates and then multiplies them by imH and imW, respectively, and thus it projects the coordinates of model elements into image coordinates. Finally, according to the filter matrix regionFilter generated by the image, the element is selected at the position where the element coordinate corresponds to true (1) of the filter matrix, following which the element filter sFilter is generated. This records whether elements with coordinates of sX and sZ are in the black area of the image. (3) Example application of importing an image to cut a model Using the two functions described above, the BoxWord example in the software realizes the modeling of “MatDEM”’s letters. First, a “thin sheet” is packed using boxWord1 code (Fig. 3.10a) and “MatDEM”’s letters (Fig. 3.10c) are be cut using the following code. The cutting code of BoxWord2 is as follows, a specific application of which can be seen in Sect. 8.3.2.

3.3 Modeling Based on Digital Images

(a) Original model;

(b) Binary image;

73

(c) The model after cutting

Fig. 3.10 Model defined by a binary image

pictureName='slope/MatDEM.png';%word should be in black color sX=d.mo.aX(1:d.mNum);sZ=d.mo.aZ(1:d.mNum); imH=400;imW=420;%image will be resized to imW*imH %read the image and change the size,image is in black and white color regionFilter=mfs.image2RegionFilter(pictureName,imH,imW);%white is true sFilter=f.run('fun/applyRegionFilter.m',regionFilter,sX,sZ); sId=find(sFilter); sId(sId＞d.mNum)=[]; d.addGroup('word',sId); d.showFilter('Group',{'word'},'aR'); view(0,-15);

3.3.2 Block Modeling by Importing a Color Image (1) Obtaining a grayscale number matrix from a microscopic image The PCAS software (see http://matdem.com for details) can perform a microstructure analysis of rocks and soils. Figure 3.11a shows the original sandstone slice, and PCAS obtains an image of the microstructure (Fig. 3.11b,) where elements are distinguished by different colors. Through secondary development, MatDEM can establish a discrete element model of the microstructure of rocks and soils with the image from PCAS. The example code of BoxMicroParticle shows how to build a corresponding discrete element model. The BoxMicroParticle1 code packs a two-dimensional initial model. In the BoxMicroParticle2 code, the model is cut with a microstructure image before finally obtaining the microstructure model. The first part of this code involves additional matrix operations, the basic purpose of which is to obtain the color value of the pixel

74

3 Geometric Modeling and Material Setup

(a)An original image of thin-section of sandstone;

(b) The micro image after the processing of PCAS

Fig. 3.11 Using PCAS software to identify elements in a sandstone thin section

(RGB), determine the unique color, sort from 1 according to the grayscale value of these colors, and then generate the image corresponding to the grayscale number matrix, as follows: load('TempModel/BoxMicroParticle1.mat'); …%initialize the model %---------------get the gray rank matrix---------------fileName='slope\micro particle.PNG'; source=imread(fileName); source=double(source); imH=size(source,1);imW=size(source,2); RGB=(source(:,:,1)*256+source(:,:,2)*256)+source(:,:,3); RGB=flipud(RGB);%flip data along vertical direction

The first line loads the initial model in the first step using the load function and performs a normal initialization operation. Lines 4 and 5 read the image named “micro particle.PNG” (Fig. 3.11) and save the image data (3D matrix, uint8 format) in source. The data in source is then converted from uint8 (unsigned 8-bit integer) to double (double precision) for image data processing. imH and imW are the height and width (pixels) of the image, respectively. source is a three-dimensional matrix that includes three imH × imW two-dimensional matrices that record the R (red), G (green), and B (blue) information of the image. Finally, the R, G, and B values of the image pixel’s three-dimensional matrix are converted into a numerical matrix RGB to further distinguish blocks of different colors.

3.3 Modeling Based on Digital Images

75

[uColor,iA,iC]=unique(RGB);%find unique color Gray=mean(source,3);%get gray level Gray=flipud(Gray);%flip data along vertical direction uGray=Gray(iA);%unique gray level [v,grayI]=sort(uGray);%sort the groupId according to gray level GrayRank=reshape(grayI(iC),size(Gray));%gray rank matrix

The above code obtains the unique value in the RGB matrix using the unique function and saves it in uColor. iA represents the first position of the value in uColor in RGB and iC represents the position of the value in RGB in uColor (see the help file of MATLAB). Line 2 averages the three RGB values in the source to obtain the gray matrix Gray. Line 4 filters out unique values in the Gray matrix and saves them in uGray. The values in uGray are then sorted in the ascending order by using the sort function to obtain the ordered matrix v and the index grayI of v in uGray. Finally, a matrix grayI(iC) is generated, which is a matrix of n rows and 1 column. The number of elements is the same as Gray (the size is imH × imW ). grayI(iC) is then rearranged into the rank of Gray by the reshape function and saved in GrayRank. GrayRank is as large as the input image, and pixels with the same color in the image appear as the same value in GrayRank. Figure 3.12 presents a screenshot of the GrayRank matrix, where 1 represents the area with the highest gray level (i.e., black); as the value increases, the gray level decreases. The grayscale number of GrayRank matrix is 1, which corresponds to the black spot in the lower left corner of Fig. 3.11.

Fig. 3.12 Grayscale number matrix GrayRank

76

3 Geometric Modeling and Material Setup

(2) Building a model using a grayscale number matrix After the image information is processed, it is necessary to set the same color portion to the same clump according to GrayRank and then delete the black portion (pores): %---------------get the groupId of clump by image---------------sampleId=d.GROUP.sample;%the sample group will be used sampleX=d.mo.aX(sampleId); sampleZ=d.mo.aZ(sampleId); sampleR=d.mo.aR(sampleId); x1=min(sampleX-sampleR);%get the four limits of the model x2=max(sampleX+sampleR); z1=min(sampleZ-sampleR); z2=max(sampleZ+sampleR); sFilter=false(d.mNum,1); sFilter(d.GROUP.sample)=true;%filter of elements

Lines 1 to 4 extract the Id and X- and Z-coordinates of sample elements, whereas while lines 6 to 9, respectively, obtain the maximum and minimum coordinates of X- and Z-directions. Finally, a logical matrix sFilter is built whose length is the total number of elements, where the values of sample elements are 1 and the values of others are 0. dX=(x2-x1)/imW; dZ=(z2-z1)/imH; imageXI=ceil((sampleX-x1)/dX);%get the location of element in image imageZI=ceil((sampleZ-z1)/dZ); startId=min([d.GROUP.groupId;-10])-1; GrayGId=−GrayRank+1+startId; imageIndex=(imageXI-1)*imH+imageZI;%element index in image imageGId=GrayGId(imageIndex);%element groupId in image

The first four lines of the above code project the coordinates of elements into the image coordinate system, where imageXI and imageZI represent the X- and Zcoordinates of model elements on the image, respectively. Because these sandstone elements are to be set to clump, the groupId of clump elements in line 5 is less than or equal to -11 (see Sect. 3.2.6 for an explanation), and the start value of the groupId has to be set to startId (-11 or smaller). Line 6 obtains the image group number matrix GrayGId according to the grayscale number matrix of the image; thus, elements at the image point will be assigned the corresponding group number. imageIndex in line 7 represents the index of each discrete element in the image matrix. Finally, imageGId is the groupId of each element obtained from imageIndex. After obtaining the groupId, elements in the sample will be set as a clump.

3.3 Modeling Based on Digital Images

77

%---------------set the clump by groupId----------------d.GROUP.groupId(sFilter)=imageGId;%assign groupId to the group d.setClump();%set clump for groupId＜=−11 delFilter=d.GROUP.groupId==startId;%groupId of pores is startId d.delElement(find(delFilter));%delete pores

Line 2 sets the groupId of the sample to imageGId, where the group number is determined by the image. These group numbers are all less than or equal to −11. In the d.setClump() command in line 3, elements with a group number less than or equal to −11 will be converted to clump (depending on the requirements, the element group may not be defined as clump). Lines 4 to 5 filter out elements (pores) whose groupId is startId and then delete them to obtain the final microstructure model (Fig. 3.13). As shown in this example, using the secondary development function of MatDEM enables users to define their own functions to build a variety of numerical models.

Fig. 3.13 Microstructure model of discrete elements in MatDEM

78

3 Geometric Modeling and Material Setup

3.4 Material Setting 3.4.1 Overview of Material Setting As described in Sect. 1.6.2, there is an analytical solution between the macroscopic mechanical properties and micromechanical parameters of the regular close-packed discrete element model, that is, the conversion formula. The five micromechanical parameters of the linear elastic contact model, namely, normal stiffness (K n ), tangential stiffness (K s ), breaking displacement (X b ), initial shear force (F s0 ), and friction coefficient (μp ), can be converted by the conversion formula and obtained from the following five macroscopic mechanical properties of the material: Young’s modulus (E), Poisson’s ratio (ν), compressive strength (C u ), tensile strength (T u ), and internal friction coefficient (μi ). The conversion formula is applicable to a compact regular packed model of equal spherical elements. For randomly packed elements, macroscopic mechanical properties are usually smaller than theoretical values. For example, Young’s modulus is usually 20% to 40% of the theoretical value, and the compressive and tensile strength are 10% to 20% of the theoretical values. Similarly, the density of a random packing model will be smaller than that of close-packed ones. MatDEM uses the material(matName, matTxt, ballR) command to generate materials, where matName is the name of the material, matTxt is the property matrix of the material, and ballR is the average radius of each material element, the value of which is usually B.ballR. The E, ν, C u , T u , μi , and density of the material are recorded in the matTxt matrix in sequence. When the material function is run, the micromechanical parameters and mass of elements are automatically generated using the conversion formula and the radii of elements B.ballR. To reduce the difference between the mechanical properties of the random packing model and the set value, the function will automatically multiply the set value by material.rate and then incorporate it into the conversion formula. By default, the rate matrix is [2.7, 0.8, 6, 6.5, 1, 1.19] (because MatDEM does not train the internal friction coefficient, rate(5) is always 1). However, in an actual application, with micromechanical parameters obtained by the conversion formula under the condition of default rate, the mechanical properties of the corresponding packing model may be quite different from the set values. Therefore, to obtain materials with more accurate mechanical properties, automatic training of material is required. The basic principle underlying such training is to directly input material properties to build a random packed block. Automatic uniaxial compression, tensile strength, and compressive strength tests then obtain the actual elastic modulus and strength of the block. The ratio of the measured values to the set values is then used to reset the material.rate until the mechanical properties converge to the set values. Normally, after three sets of training and automatic adjustments, the error between the measured values and the set values can be less than 2%. It should be noted that K n in the conversion formula is the normal stiffness obtained by connecting two element springs in series and is the normal stiffness (k n ) of the elements in material; therefore, K n = k n /2 (see Sect. 1.2.2 for details).

3.4 Material Setting

79

3.4.2 Input the Material Properties Directly In the example file, the second step is usually performed with the assignment of materials. The following code is taken from BoxModel2 (users can also refer to BoxMixMat2). It loads the material data of Soil1 and Soil2, which are assigned to group1 and group2. matTxt=load('Mats\Soil1.txt'); Mats{1,1}=material('Soil1',matTxt,B.ballR); Mats{1,1}.Id=1; matTxt2=load('Mats\Soil2.txt'); Mats{2,1}=material('Soil2',matTxt2,B.ballR); Mats{2,1}.Id=2; d.Mats=Mats; d.setGroupMat('group1','Soil1'); d.setGroupMat('group2','Soil2'); d.groupMat2Model({'group1','group2'},1);

The load command is used to read the text and store it in the matTxt matrix. The corresponding micromechanical parameters are calculated using the material function, directly generating the material, which is then saved in the cell matrix Mats. For example, Mats{1, 1} indicates that the generated material is saved in the first position of the Mats cell matrix while recording the material id Mats{1, 1}.Id = 1. Material 2 is then added and saved in the second position Mats{2, 1}. The d.setGroupMat function is then used to declare the material Id of each group. It is important to note that the setGroupMat command only declares the material Id of the group, it does not actually apply the material to elements. To do this, the d.groupMat2Model function needs to be used. Using the above command sets the materials of group1 and group2. The material Id of the remaining elements will then be set to the default material Id 1.

3.4.3 Automatic Training of Materials (1) Building a packing model for testing MatDEM’s automatic training of materials function is implemented by the MatTraining file:

80

3 Geometric Modeling and Material Setup %---------------set parameters for material training matName='mxRock2'; matFile=['Mats\' matName '.txt'];%material file sampleW=100;sampleL=100;sampleH=200;ballR=10; distriRate=0.2;% interationNum=4;%number of interation,value from 3 to 6 randSeed=2;%change the seed to create a different model saveFileLevel=2;% 1:save important files,0:save one result file, -1:do not save uniaxialStressRate=1;%default value is 1,generally do not have to change it StandardBalanceNum=50;%define the balance number of simulation,1-50

First, the parameters of training are set, where matName is the name of the material to be trained; sampleW, sampleL, and sampleH are the size of the model to be trained; and ballR is the average radius of elements. To obtain a more stable result, the total number of elements needs to be between 6000 and 10000. intervalNum is the time of training, and, in each training period, the code will test the mechanical properties of the model and update the rate of materials; this parameter is therefore generally not less than 4. When this is not the case, the training error is usually less than 1%, which can satisfy most requirements in terms of precision. If a higher accuracy of training is needed, the number of training periods can be increased. saveFileLevel is the record level of information: when the value is 1, the file of the main step in the test is saved in the data folder; when the value is 2, the file of each compression step and tensile step in the test is saved in the data/step folder. StandardBalanceNum denotes each standard balance number, the default value of which is 50. If this value is increased, it will also increase the real-world time corresponding to the numerical simulation and make it tend toward a static process; otherwise, it will tend toward a dynamic process (see Sect. 3.5.1 Standard Balance for details). %--------------build initial model-----------------B=obj_Box;%build a box object B.GPUstatus='auto'; B=mfs.makeUniaxialTestModel0(B,sampleW,sampleL,sampleH,ballR,dis triRate,randSeed); B.name=matName; B.saveFileLevel=saveFileLevel;%save all related files B.SET.uniaxialStressRate=uniaxialStressRate; B.d.SET.StandardBalanceNum=StandardBalanceNum; %-------------assign material to model B=mfs.makeUniaxialTestModel1(B); B.save(1);%save file in 'TempModel',file name end with 'Step-1'

3.4 Material Setting

81

The mfs.makeUniaxialTestModel0 function is then used to build the initial model using the steps described in Sect. 3.1.1. Following this command, users can add code to modify the radius distribution of model elements to study the effects of different grading and packing states on the mechanical properties of the model. The mfs.makeUniaxialTestModel1 function performs the operations of gravity deposition, compacting models, and gravity reduction to build a packing model. The packing model is saved in the TempModel folder using the B.save(1) command and used for subsequent multiple loads and tests. (2) Automatic testing and adjustment of materials

mfs.makeUniaxialTestModel2(B,matFile);%set the material of the model mfs.makeUniaxialTest(B); for i=1:interationNum data=B.d.Mats{1}.calculateRate(); matSet=B.d.Mats{1}.SET;%rate data is recorded in B.SET; B.load(1);%load the saved file in 'TempModel' mfs.makeUniaxialTestModel2(B,matFile,data.newRate);%apply the new rate B.d.Mats{1}.SET=matSet;%assign the material rate data mfs.makeUniaxialTest(B); end B.d.Mats{1}.setTrainedMat(); B.d.Mats{1}.save();

The function of the mfs.makeUniaxialTestModel2 function is to set the material, and involves the following operations: ➀ Set the material to the model using steps described in Sect. 3.4.2; ➁ bond the model; ➂ move the left, right, front, back, and top boundaries of the model to the outside with a displacement 20% of the maximum model size (ensure not to contact the sample), leaving the bottom boundary and top pressure platen for a later uniaxial test; ➃ carry out two standard balances to reduce the kinetic energy of system; ➄ re-bond the model; and ➅ save the model data in the data folder and name it “*-MatUniaxialTestModel2.” By following the aforementioned steps, a packing model of given micromechanical parameters is obtained. The mfs.makeUniaxialTest function performs a series of numerical simulation tests, including the uniaxial compression test, uniaxial tensile test, Young’s modulus, and Poisson’s ratio test; records the mechanical parameter coefficient rate used in the current test and the results in Mats{1}.SET.UniaxialRate and UniaxialPara; and then completes the first test. The new rate (see Sect. 3.4.1) of the material is determined by the calculateRate function in the loops. The material is then set again by the

82

3 Geometric Modeling and Material Setup

Fig. 3.14 Set values of the material E: Young’s modulus; v: Poisson’s ratio; Tu: tensile strength; Cu: compressive strength; Mui: internal friction coefficient

mfs.makeUniaxialTestModel2 function after adjustment, and a new uniaxial test is performed. The rate of each test and measured mechanical parameters are recorded in d.Mats{1}.SET. Following the loop test, the setTrainedMat function selects the rate of measurement with the least error based on recorded mechanical parameters and assigns it to material.rate. It is often the case that the more iterations there are, the smaller the test error. When the training of material is completed, the B.d.Mats{1}.save() command will automatically save the data file for the material in the Mats folder with the file name (matFile).mat. In numerical modeling, this file can be read into the software (load command) and then added to the material matrix d.Mats (see Sect. 8.3 for details). (3) Result data for training materials As shown in Fig. 3.14, the mxRock2 material is obtained through automatic training and recorded in the variable Mat_mxRock2. This variable contains various mechanical and physical properties of the material (for further details, refer to the description of the software’s material window and the help file). The parameter rate records coefficients that need to be multiplied by various mechanical parameters and densities when using the conversion formula. Figure 3.15 shows the data table for Mat_mxRock2.SET, which records the relevant parameters of each test. Figure 3.16 shows the parameter UniaxialParaValue in the SET, which records mechanical parameters obtained from each test.

3.5 Balance Model

83

Fig. 3.15 Material test results recorded in Mat_mxRock2.SET

Fig. 3.16 Seven material test results recorded in UniaxialParaValue

3.5 Balance Model 3.5.1 Iterative Calculation Function and Standard Balance (1) d.balance function The basic iterative calculation function of MatDEM is d.mo.balance(). Each time this function is run, an iterative calculation is performed and the time taken by the numerical simulation advances d.mo.dT. A d.balance function is primarily used to call the d.mo.balance function for iterative calculation. It is widely used in gravity deposition (B.gravitySediment), strong bonded balance (d.balanceBondedModel), and numerical calculations, which is the most important system function. The d.balance function has multiple input forms: d.balance() runs one time iteration, d.balance(balanceNum) runs balanceNum times iterations, and d.balance(balanceNum, balanceTime) represents the iteration of balanceNum ×

84

3 Geometric Modeling and Material Setup

balanceTime times, and records the system state once every balanceNum times (by using d.recordStatus). See Appendix B and help files for specific usage. When the d.balance(balanceNum, balanceTime) command is run, the program displays the completed balanceTime and total balanceTime. (2) Standard balance During numerical modeling, a relatively rough (larger element radius) model is usually built to facilitate testing and improve the model. In the case of high-precision numerical simulation, it is necessary to take a smaller (finer) value of the model element radius. Because the vibration period of the element is proportional to the radius (Sect. 1.3.3), the time step (d.mo.dT ) of the numerical simulation reduced as the element radius reduced. Therefore, when using the d.balance function to iterate a certain number of steps, high-precision iterative calculations correspond less to real-world time. For example, if the average radius of a model is R and the time step is 10−4 s, the corresponding real-world time for 200,000 iterations is 20 s. When the average radius of the element is reduced to 0.5 R and the time step is reduced to 0.5 × 10−4 s, the corresponding real-world time for 200,000 iterations is 10 s. Therefore, when the average element radius of the model reduced, the real-world time corresponding to the same number of iteration steps also proportionally reduced. The change in simulation time will lead to significant changes in the result of numerical simulations. For example, the original numerical simulation of a landslide can complete in 20 s and the landslide may still accelerate in 10 s. To solve the problem of time, MatDEM introduces a standard balance function. This automatically adjusts the number of iterations according to the change in the element radius so that the simulation time for the whole system tends to be uniform. The standard balance function is d.balance(‘Standard’, 1), which means that a standard balance is performed and the actual number of iterations is d.SET. StandardBalanceNum × d.SET.packNum. Of these, d.SET.StandardBalanceNum is 50 by default and generally does not need to be modified, whereas d.SET.packNum is the number of packed elements in the longest dimension of the model and is obtained through automatic calculation of the system. The second input parameter is the standard balance number; when this is 1, it means that the standard balance is performed once. Normally, a standard balance can provide better results. If higher precision is required, users can increase the standard balance number, although the amount of calculation will also be doubled if a simulation result needs to be obtained quickly. The standard balance number can be set to be less than 1; however, the simulation accuracy will decrease. The default time step of the system is approximately 1/50 of the vibration period of elements; therefore, when d.SET.StandardBalanceNum is 50, the real time corresponding to each standard balance is d.SET.packNum times the vibration period. Thus, a standard equilibrium is equivalent to the stress wave passing from one end of the model to the other. If the default damping coefficient of the system is adopted after applying the displacement boundary condition, a standard balance will consume most of the kinetic energy in the system.

3.5 Balance Model

85

3.5.2 Strong Bond Balance After applying the material to the model, it is often necessary to process the model with a strong bond balance. As described earlier, the initial model is packed with “soft” elements, such as rubber balls, and the amount of deformation (overlap) between elements is large. When the mechanical properties of the real rock and soil are set to elements, this is equivalent to suddenly turning the soft ball into a steel ball: the discrete elements of the packing model may then “explode” due to the sharply increasing inter-element stress and elastic potential energy. To balance the force, a strong bond balance function is required to give the connection between elements a great breaking force (d.mo.aBF) and initial shear resistance (d.mo.aFS0); perform an iteration balance that consumes the system’s energy rapidly; and provides a stable packing model. Strong bond balance functions include d.balanceBondedModel0 and d.balanceBondedModel. In the iterative calculation, the d.balanceBondedModel0 function ignores the friction between elements, which means there is no friction between model elements after the balance is completed and a relatively dense packing model is obtained. By contrast, the d.balanceBondedModel function considers friction between elements, and there may be some pre-stress in the packing model. These two functions correspond to different packing environments in the real world, in that a lack of friction between elements is similar to the deposition of sand in water, whereas the presence of friction is similar to the process of drying and packing sand. Different packing methods will have a certain influence on the mechanical properties of rock and soil. Users can therefore perform numerical simulation tests and refer to the existing literature for details. It is important to note that after a strong bond balance, a standard balance is usually required to ensure a stable model. Although various stress and energy curves are shown to be stable after a strong bond balance (Sect. 3.5.4), the model is actually unstable. This is because the strong bond balance increases the strength of the bond to a very large value and performs a balance calculation. During this process, a large number of connections between elements have reached their damage limit while still maintaining a bonded state. When the strong bond state is removed, these connections immediately break and release an enormous amount of energy. Therefore, after a strong bond balance, a standard balance is usually required to consume this energy. To prevent elements on the model surface from jumping, the following code can be used for standard balance calculation to continuously bond and balance the model until the motion of elements reaches a steady state. loopNum=10; rate=0.05; for i=1:loopNum d.mo.bFilter(:)=true; d.balance('Standard',rate); end

86

3 Geometric Modeling and Material Setup

However, when studying the landslide and other problems, if the standard balance is carried out directly, the model is likely to be unstable under the action of gravity and it becomes impossible to build an eligible geometric model. It is then necessary to increase the bond strength of soil layer elements so that the stability coefficient of the slope is larger than 1. Once the model is balanced, the strength is restored in the third step to simulate landslide sliding. The model built by the above code generally involves pre-stress, as many connections are in tensile state. Users may use the function d.removePrestress to remove pre-stress of the model (see the help file).

3.5.3 Neighbor Searching and Zero Balance In each iteration calculation, MatDEM calculates the cumulative displacement of each element since the last neighbor search. When this exceeds a certain value (d.mo.dSide/2), the system will automatically run the d.mo.setNearbyBall function to update the neighbor matrix d.mo.nBall. d.mo.dSide denotes the extended scope of the neighbor search, further details of which can be found in the related literature. The cumulative displacement of active and wall elements is recorded in the d.mo.dis_mXYZ and d.mo.dis_bXYZ arrays, respectively. When the neighbor contact relationship among elements in the model changes, such as when the element is moved during the modeling process, or the element radius is increased (expanded), the neighbor matrix of the element needs to be researched and generated. The d.mo.setNearbyBall() function researches the neighbor contact relationship between elements. This recalculates the neighbor matrix d.mo.nBall and updates data related to the neighbor matrix, such as d.mo.bFilter, and resets the value of the cumulative displacement array to zero. However, it is not necessary to research neighbor elements when the element radius becomes small, because the element does not come into contact with new elements when it shrinks. When the connection relationship between elements and the properties of elements is changed by the modeling operation (such as by breaking of the bond, an increase in the element radius, and an increase in element stiffness), the force state of elements will change. The zero balance function d.mo.zeroBalance() can then be run to obtain the new force state of elements. This function sets the time step to 0, performs an iterative calculation, and obtains new force and contact information for elements; however, because the time step is 0, the element does not move. d.mo.balance() can also be used to calculate the new force state of elements, but the time will be advanced one time step. For example, when elements in the model are expanded due to initial heating, neighbor elements are searched, the zero balance is performed, and the stress field generated by the expansion is obtained through post-processing. For further details, see the breaking rock with microwave and thermo-mechanical coupling of energy pile examples in Chap. 10.

3.5 Balance Model

87

3.5.4 Standard of Judgment for a Model Balance State After the iterative calculation completed, it is necessary to judge whether the model reaches a balanced state, especially after geometric modeling is finished and before the numerical simulation starts (i.e., at the end of the second step code). The stress distribution, the boundary force curves, the energy conversion curves, and the heat generation curves of the model are viewed by the d.show() command, enabling the user to judge whether the model has reached a balanced state. Figure 3.17 shows the image obtained using the d.show() command at the end of the second step of the example BoxModel. Figure 3.17a presents the Z-direction stress distribution. This shows that the stress in the stratum below the slope is large and there is a distinct force chain while the other stress of the stratum is small, which corresponds to physical laws. Figure 3.17c displays a force diagram of the boundary, that is, the normal force of the six boundaries. This shows that the right half of the boundary force curve is horizontal, indicating that there is no stress wave propagated in the model, the boundary force is stable, and the model can be considered balanced. Boundary force is a stricter criterion for balance because the boundary force curve is the most difficult to keep stable relative to other curves. Figure 3.17b, d shows the energy conversion curve and the heat generation curve, respectively. When the model is balanced, these curves should also be horizontal. For

(a) Stress ZZ; (b) Curves of energy conversion; (c) Curves of boundary forces; (d) Energy curves Fig. 3.17 Diagram of model status using the d.show() command

88

3 Geometric Modeling and Material Setup

numerical simulations that require step-by-step loading, such as uniaxial compression, boundary forces and energy curves are stepped. When the curve of each step is horizontal, this indicates that the model has reached stability under the current load. By contrast, when the curve is wavy, it indicates that a stress wave remains in the model and the compression rate of the uniaxial compression test is very fast, which tends to be a dynamic process. The kinetic energy curve is also an important indicator of model balance. In such a model, the kinetic energy tends to be zero. In a uniaxial compression test, the kinetic energy curve will suddenly jump and then fluctuate and decay when the model suddenly breaks. In addition, for models with a free surface (such as the pile–soil interaction model in Chap. 6), the d.show(‘mV’) command needs to be run again to check whether splash of individual elements has occurred. Because the kinetic energy generated by the splash of a single element is very small, it is difficult for this to be clearly reflected in the energy curve. If the speed of individual elements remains large, iterative calculations must be continued. The d.status.dispEnergy() command is used to view the total energy of the current model. The final kinetic energy of the model shown in Fig. 3.17b is 2.1 × 10−13 J, indicating that the entire model is almost completely stationary. In summary, the method for quickly determining whether the model is balanced is to ➀ determine whether each curve is already horizontal; ➁ view the maximum speed of the d.show(‘mV’) image; and ➂ view the total energy value using the d.status.dispEnergy() command. If the model is not balanced, users can add new operations of standard balance or strong bond balance depending on their needs.

3.6 Setting of Cracks and Joints There are a large number of cracks and joints inside natural rock. MatDEM therefore supports the presetting of cracks and joints in the model to simulate a real rock sample.

3.6.1 Setting Weak Layers and Cracks Through Groups To achieve this, some elements in MatDEM are selected, set as a group, and then given a low-strength material to achieve the effect of simulating the weak layer. In the BoxModel2 code, a weak layer can be generated by conducting the following operations: d.setGroupMat('layer2','Soil2'); d.groupMat2Model({'sample','layer2'}); d.show('aMatId');

3.6 Setting of Cracks and Joints

89

The command in the first line defines layer2 as a weak layer of soil; the second line officially assigns material to each layer of soil; and the third line displays the material Id of the model elements. Figure 3.18 displays the material diagram of the model and layer2 in the middle, in which the material Id is 2. d.mo.bFilter(:)=true; d.mo.zeroBalance(); d.breakGroup({'layer2'});

By using the above first and second commands, the model elements are completely bonded. The connection between the elements of layer2 then completely disconnected using the d.breakGroup function, thereby “breaking” the elements of the weak layer. Thus, the diagram of element connection shown in Fig. 3.19a is obtained. The lines in the diagram indicate the intact bonds between elements, whereas blank areas indicate that the element bonds have been disconnected. Similarly, Fig. 3.19b depicts the processing result of the d.breakGroupOuter function. This shows that the connection between the elements of layer2 and other elements has been completely disconnected and crack surfaces generated.

Fig. 3.18 BoxModel2 sets the material for the weak layer

90

3 Geometric Modeling and Material Setup

(a) d.breakGroup command;

(b) d.breakGroupOuter command

Fig. 3.19 Connection diagram after execution of group command

3.6.2 Using Triangle Faces to Set Cracks and Joints MatDEM can use triangle faces to generate joints and cracks. For example, the mfs.setBondByTriangle(d, TriX, TriY, TriZ, ‘break’) command disconnects elements that intersect the triangle face, where TriX, TriY, and TriZ record the vertex coordinates of the spatial triangle face. The string “break” declares that connections need to be disconnected. When the final parameter is “glue,” the corresponding connection is glued; when the final parameter is “no,” no operation is applied to the connections. This function returns the bondFilter matrix, which corresponds to the neighbor matrix nBall, and records the connection with the triangle faces, which can be used for further operations. For example, the strength of this triangular joint face is doubled by the d.mo.nBondRate(bondFilter) = 2 command. The mfs.setBondByPolygon command can also be used to define cracks and joints using polygons as the principle is similar. See Sect. 7.2.2 and Appendix B for further details regarding the use of these commands.

3.6.3 Using Tool_Cut to Set Cracks and Joints The class Tool_Cut is able to cut models based on digital elevation data and provide settings for cracks and joints. Very complex three-dimensional cracks and joint faces can be set using the Tool_Cut tool. For further details on how Tool_Cut sets up cracks and joints, see Sect. 7.2.3.

3.6 Setting of Cracks and Joints

91

3.6.4 Definition and Use of the Connection Filter MatDEM’s neighbor matrix is d.mo.nBall, which records connections between elements. In d.mo, a matrix the same size as nBall is the connection-related matrix, which records information on connections. For example, d.mo.bFilter records whether the connection is bonded; d.mo.cFilter records whether the connection is in a compressed state; d.mo.nClump records the initial overlap between connections; d.nBondRate records the reduction factor for the bonding force between connections; and nFnX records the component of the normal force of connections in the X-direction. A range of information is available using a connection filter (such as bFilter). For example, the coordination number of an element is defined as the sum of the number of bonded connections and the number of compressed connections. The coordination number (coordinationN) of the element is obtained using the following code: CNfilter=d.mo.cFilter|d.mo.bFilter; coordinationN=sum(CNfilter,2);%sum is a Matlab command

MatDEM generates cracks and joints by defining and modifying connection filters. Most functions associated with connections of groups return a filter matrix, such as d.connectGroup and d.breakGroup, which return a Boolean matrix that records connections that are glued or broken. In Sects. 7.2.2 and 7.2.3, the triangle facet and the Tool_Cut tool are used to generate cracks and joints, which are also based on modifying the d.mo.bFilter matrix. The following code is used to find elements with a normal force of compression greater than 10 N: nFn=sqrt(d.mo.nFnX.*d.mo.nFnX+d.mo.nFnY.*d.mo.nFnY+d.mo.nFnZ.*d. mo.nFnZ); nFnFilter=(Fn＞10)&d.mo.cFilter; FnFilter=sum(nFnFilter,2)＞0;

In the above code, the first line obtains the absolute value of the normal force (nFn), based on the X-, Y-, and Z-components of the normal force of element connections; the second line obtains the connection filter matrix with the pressure exceeding 10 N; and the third line sums the filter matrix in the row direction, and then obtains the absolute value of the normal force greater than 10 N for the number of connections. After comparing this with 0, an element filter FnFilter with pressure exceeding 10 N is obtained. If users are familiar with the use of connection filters, they can write complex codes for multi-field coupling simulation. For example, in a multi-field coupling simulation of soil cracking as a result of losing water (SoilCrackNew), the following commands are included:

92

3 Geometric Modeling and Material Setup nWaterDiff=d.mo.SET.aWC(d.mo.nBall)-d.mo.SET.aWC(1:d.mNum)*nRow; nWaterDiff(～cbFilter)=0;

In the above code, the first line obtains the gradient of water content between neighbor and central elements, where the d.mo.SET.aWC(d.mo.nBall) command obtains the water content of neighbor elements and the latter part obtains the water content of central elements. Line 2 sets as 0 the gradient of water content between elements that are not in contact (no migration of moisture), and cbFilter is the union of compressive and bonded connections. These two lines of commands contain a more complex use of the array index, that is, aWC(d.mo.nBall), where aWC is an array of aNum × 1 and d.mo.nBall is a neighbor matrix. This command returns a matrix the same size as the nBall, which records the water content of the neighbor elements of each element. This method is very convenient when calculating the difference in parameters between elements and surrounding neighbor elements. For further details, refer to the code for the iterative calculation of thermal coupling of the energy pile in Chap. 10.

Chapter 4

Load Settings and Numerical Calculations

This chapter focuses on the initialization of model parameters, load settings, the precision of simulation settings, and saving files in numerical simulations. The content described in this chapter primarily corresponds to the third step of the sample code.

4.1 The Initialization and Settings of Numerical Calculation 4.1.1 The Initialization of Model Parameters Prior to the iterative computation process in the third step, the model needs to be initialized: d.getModel(); d.resetStatus(); d.setStandarddT();

The command d.show(‘Displacement’) that shows the displacement field is based on the difference between the element coordinates in d and d.mo. Operations such as balance calculation and moving group in the first two steps of modeling change the element coordinates in d.mo. To ensure that the displacement field is displayed correctly during further numerical simulations, the initial parameters recorded in d need to be reset. Therefore, at the beginning of the third step, the d.getModel() command is usually run so that the parameters in d are consistent with the corresponding parameters in d.mo and the displacement field is initialized. The balance calculation in the modeling process then automatically runs the d.recordStatus() function, which records the system energy, boundary force, and other information in d.status. Prior to formal numerical simulations, the © The Author(s), under exclusive license to Springer Nature Singapore Pte Ltd. 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9_4

93

94

4 Load Settings and Numerical Calculations

d.resetStatus() command needs to be run to clear this modeling history information. This command is equivalent to the d.status=modelStatus(d) command, which generates a new d.status object. Finally, the time step is initialized by running d.setStandarddT() command. This is because some operations during the modeling process may modify the time step d.mo.dT, such as increasing it to enhance the speed of calculation. To avoid the impact of modeling process operations in a formal numerical simulation, initialization of the time step is required (see Sect. 4.4.3 for details).

4.1.2 Setting of Relevant Parameters in Calculation Prior to iterative calculation, the relevant parameters can be set; primarily in the d.mo object (see Table 4.1 for the meaning and default value of the parameters). If there is no special setting, the numerical simulation process is calculated by default, where 0 means ignore (without corresponding calculations) and 1 means consideration (with corresponding calculations).

4.2 Boundary and Load MatDEM creates all the boundaries, pressure platens, and components through basic spherical elements. Different model boundaries are realized by applying displacement, body force, temperature, and heat flow to elements. This section describes how to apply various types of load, such as stress load (triaxial test), displacement load (shear test and breaking rock with hob), vibration load (simulation of seismic effect), and temperature load (thermo-mechanical coupling simulation of energy pile). Table 4.1 Setting of relevant parameters in numerical calculation Parameters

The meaning of parameters

isHeat = 1;

Whether to calculate the heat

isWaterDiff = 0;% Not commonly used

Whether to perform a finite differential calculation

isCrack = 0;

Whether to record the cracks generated

isShear = 1;

Whether to consider inter-element shear force

isRotate = 1;% Not enabled

Whether to consider the rotation of the element

isFailure = 0;% Not commonly used

Whether to consider compression damage of the element

isSmoothB = 0;% Not commonly used

Whether to use smooth boundaries (relevant data recorded in the SET matrix)

isPore = 0;% Not enabled

Whether to calculate the flow-solid coupling of two-dimensional pore density flow method

4.2 Boundary and Load

95

4.2.1 Boundary Conditions In MatDEM, the boundary conditions of the model can be changed by altering the state of boundary or the pressure platen. During initial modeling, MatDEM automatically generates six boundaries and records them in d.GROUP, including lefB, rigB, froB, bacB, botB, and topB. The main function of the boundary is to construct a rectangular enclosed space to prevent overflow of active elements. Boundary elements are fixed wall elements with properties such as coordinates, radius, and stiffness. The coordinates of boundary elements are fixed in iterative calculations; thus, they can be considered as rigid boundaries and produce a certain amount of friction. Displacement loads and vibration loads can be generated when the boundary is moved by the d.moveGroup function. In secondary development we can add properties such as temperature (the example of TunnelHeat) and water content (the example of SoilCrack) to the boundary elements. Depending on the requirements, these six boundary walls can also be set as adiabatic boundaries, water barrier boundaries, and so on. The example of BoxCrash demonstrates numerical simulations of the process of a meteorite hitting Earth, details for which can be found on the software website http://matdem.com. This shows that when a meteorite hits the ground, a huge crater is formed and creates strong seismic waves that spread outward. Reflection occurs when seismic waves contact a fixed bottom boundary (rigid). In the real world, such rigid boundaries and strong reflective waves do not exist underground. Therefore, an absorption boundary needs to be produced through secondary development to absorb stress waves on the boundary. For instance, the perfectly matched layer (PML) can be used to absorb boundary conditions. MatDEM can also achieve stress boundary conditions by applying force to the pressure platen (see Sect. 4.2.2 for details). Figure 4.1 shows the boundaries and Fig. 4.1 The boundaries and pressure platens of the MatDEM simulation box Color represents displacement field

96

4 Load Settings and Numerical Calculations

pressure platens of the MatDEM simulation box.

4.2.2 Stress Load (1) Principle of applying stress load In MatDEM, the application of stress load is realized by applying force to the elements of the pressure platen. Based on the given pressure value, the area of the pressure platen, and the number of elements, force on each element can be calculated (forces in the direction of X, Y, and Z are d.mo.mGX, mGY, and mGZ, respectively) and the application of the stress load can be realized. For instance, in the first step of most examples, the B.compactSample (compactNum, StressZZ) command uses a top pressure platen to generate periodic vibrational pressure. This function applies force to the elements of the pressure platen according to the input stress value (StressZZ), the area of the top pressure platen, and the number of elements, and then realizes the application of the stress load. Figure 4.1 shows the state of a model that has been compacted and packed by the top pressure platen. MatDEM utilizes the 3D stress application function B.setPlatenStress to simulate high geostress conditions. This function creates boundary stress by setting force on the pressure platen (the negative value is pressure and the positive value is tension). The force then acts on the positive direction of the pressure platen, i.e., the right, back, and top pressure platen, while the negative direction of the pressure platen does not apply force. See Sect. 7.2 for an example of how to use this function. Users can also customize the pressure platen and apply force to the element in accordance with the above method, thus achieving specific stress effects. For example, in Sect. 7.1, a circular pressure platen (topPlaten) was customized and specific stresses were applied to the sample: d.mo.mGZ(d.GROUP.topPlaten)=–verticalForce;

Local stress can also be applied using the existing pressure platen in the model. For instance, in the TunnelNew example, the middle part of the top pressure platen is defined as the block group, to which downward force is applied to realize the local stress load on the ground. This occurs as follows:

4.2 Boundary and Load

97

d.addGroup('block',blockId); d.mo.mGZ(blockId)=d.mo.mGZ(blockId)+blockForceZ;

(2) The application of true triaxial stress True triaxial stress is applied by the B.setPlatenStress function, which allows multiple input parameters as follows: (1) When there are two input parameters, the function takes the form of B.setPlatenStress(stressType, stressValue). Depending on the stress value of the setting, the function uses fs.platen2Gravity to apply force on the pressure platen for uniaxial compression and elastic modulus test simulations. The parameter stressType can be StressXX, StressYY, StressZZ, which represent the values of stress in the X-, Y-, and Z-directions, respectively; the parameter stressValue represents the values of stress, the unit of which is Pa. (2) When there are three input parameters, the function takes the form of B.setPlatenStress(stressType, stressValue, border). According to the value and range of the stress setting, this function uses fs.setPlatenStress(d, stressType, stressValue, border) to apply force on the pressure platen. The value of stressType and stressValue is the same as above; the border is the range over which stress is applied on the pressure platen, as explained below. (3) When there are four input parameters, the function takes the form of B.setPlatenStress(StressXX, StressYY, StressZZ, border). According to the value and range of the stress setting, this function uses fs.setPlatenStress(d, stressType, stressValue, border) to apply the body force of three directions on the pressure platen. Regarding the parameter border, during numerical simulation the area of the pressure platen is usually larger than the sample: if force is applied to all pressure platen elements, the elements on the edge of the interface of the sample and pressure platen are subject to greater stress. Therefore, the setPlatenStress function searches the interface within the border of the sample and pressure platen to determine the surface area of the sample. The elements of the pressure platen are then searched within this area and the stress is applied. The default value of the border is five times the element radius (B.ballR*5), which does not generally require modification. In a triaxial test, the command needs to be run continuously when the sample is deformed to apply stress correctly. As shown in Fig. 4.1, the top pressure platen applies a certain amount of pressure on the sample, and only the elements of the pressure platen within the sample range are subjected to the downward force. However, in the triaxial test, the sample may expand in a certain dimension (e.g., applying a tensile force). The boundary and pressure platen therefore need to be larger to prevent particles from leaking out, thus B.BexpandRate and B. PexpandRate should be set. The meaning of these two parameters is explained in more detail in Sect. 3.1.

98

4 Load Settings and Numerical Calculations

However, their role is to increase the width of the boundary and pressure platen, which is essentially the number of elements extended outward of the boundary and pressure platen.

4.2.3 Displacement Load The displacement load is applied using the d.moveGroup function, which forces movement of all elements of a specified group without being affected by lockin degrees of freedom. When the function d.moveBoundary is used to move the boundary, actually the function moveGroup is also used to move the corresponding boundary group. When using the boundary to apply a displacement load to the sample, it is generally necessary to add the corresponding pressure platen to act as a buffer. This avoids the formation of a momentary huge stress between the boundary and the sample that can damage the sample. For example, the boundary may move to extrude the pressure platen, which moves gradually inward under the action of force and passes the displacement load step by step to the sample. In response, the pressure platen converts the transient boundary displacement into a continuous, slowly increasing displacement, thus avoiding sudden and significant stress on the sample. In this case, the displacement and velocity curves of the pressure platen are similar to the sine curve. Similar to stress loads, displacement loads can also be applied to ordinary groups. For example, in the TBMCutter (Fig. 4.2), the hob (Hob group) is rolled over the rock layer with the following command:

(a) The initial state

(b) After rolling

Fig. 4.2 Numerical simulation process of breaking rock with hob

4.2 Boundary and Load

99

d.moveGroup('Hob',dDis(1),dDis(2),dDis(3)); d.rotateGroup('Hob','XZ',-dAngle,hobCx,hobCy,hobCz);

The first command achieves movement of the hob and the second command achieves rotation. The amount of rotation thus corresponds to the amount of movement used to simulate the rolling process. For more detailed information on this example, see the breaking rock with shield and hob in Sect. 6.3. In the BoxShear example, numerical simulation of direct shear and torsional shear tests was performed by moving and rotating the bottom shear box (see Sect. 7.1 for details).

4.2.4 Vibration Load The vibration load is actually a special form of the displacement load; this is also applied by moving the boundary and is buffered by a pressure platen. The simplest vibration load involves applying a sine wave, as described earlier, which forms a sine compression wave when the boundary is moved to extrude the pressure platen. Shear waves can also be generated when the boundary moves in the shear direction. It is important to note that the tensile resistance and initial shear resistance between the boundary and the pressure platen should be strengthened to ensure that the bond between the two will not break. The example of earthquake demonstrates how boundaries can be used to generate seismic waves. d.setGroupMat('layer1','Rock1'); d.setGroupMat('layer2','Soil1'); d.setGroupMat('layer3','Rock1'); d.groupMat2Model({'layer1','layer2','layer3'},2); d.balanceBondedModel0();%balance

the

bonded

model

without

friction %---------define a block on left side of the model to generate wave mX=d.mo.aX(1:d.mNum); leftBlockId=find(mX

0.05*max(mX));%choose element Id of block

d.addGroup('LeftBlock',leftBlockId);%add a new group d.setClump('LeftBlock');%set the block clump d.mo.zeroBalance();

In this example, 1 to 5 lines of code establish the mountain model shown in Fig. 4.3a, in which there is a weak layer (layer2). The displacement of the boundary in this example is large and requires a buffer block with a large area. Therefore, we

100

4 Load Settings and Numerical Calculations

Fig. 4.3 Modeling of vibration load

define the 5% stratum on the left side of the model as the LeftBlock group and set it as an unbreakable clump that serves as a buffer block when the left boundary moves. visRate=0.001; d.mo.mVis=d.mo.mVis*visRate; d.moveBoundary('left',0.01,0,0);

The default damping coefficient of the system is the optimal damping coefficient (Sect. 1.3.5). This is usually larger than the damping coefficient of the actual material and causes the system energy to converge rapidly. In the simulation of a seismic wave (dynamic process), the real damping coefficient of the material needs to be used. In this case, we multiply the default value of the system by 0.001 to reduce the damping coefficient. The left boundary is then moved to the right by 0.01 m, extruding the LeftBlock and generating seismic waves through iterative calculations. The X-directional acceleration field of the model at 0.015 s is shown in Fig. 4.3b. For further details on this example, see Sect. 9.3 on seismic dynamics.

4.2.5 Other Loads MatDEM provides a powerful secondary development function through which multifield coupling numerical simulation can be realized. The example of SoilCrackNew shows the simulation of water loss and cracking of soil under multi-field coupling, where boundary conditions of water content, seepage, and so on can be set. Through secondary development, MatDEM also realizes the boundary conditions of constant temperature. The example of TunnelHeat demonstrates the thermomechanical coupling simulation of an energy pile (Chap. 10). In the simulation process, the temperature of the soil element is 15°C and a constant temperature of

4.2 Boundary and Load

101

Fig. 4.4 Thermo-mechanical coupling simulation of an energy pile where a constant temperature load of 25 °C is applied to the pipe pile

25°C is applied to the inner wall element of the pipe pile (Fig. 4.4), following which thermal conduction simulation and thermodynamic coupling simulation are realized: aTnew(innerTubeId)=innerTubeT;%inner tube temperature

At the same time, the thermal flow of the six boundaries is set to 0 °C, thus the adiabatic boundary is set as follows: nTempFlow(inslatedFilter)=0;

With some improvement, this example can also simulate the boundary conditions of thermal flow.

4.3 Time and Settings of Iterative Calculation 4.3.1 Running Time of Iterative Calculation The discrete element method completes the numerical simulation by iterative calculation, which may take several hours to several days to complete if it is a lot of work. To estimate the calculation time, MatDEM provides prompt functions of iterative time, including d.tic and d.toc, where d.tic records the initial time and the total number of

102

4 Load Settings and Numerical Calculations

cycles, and d.toc displays the current steps and time information. See Sect. 5.4.5 for the principle underlying these two timing functions. The following code is the iterative calculation part of BoxShear3: d.tic(totalCircle*stepNum); for i=1:totalCircle for j=1:stepNum d.toc();%show the note of time d.moveGroup('botBox',dDis,0,0,'mo'); d.balance('Standard',0.1); end d.clearData(1);%clear data in d.mo save([fName num2str(i)'.mat']); d.calculateData(); end

The total cycle times are declared as totalCircle×stepNum by the d.tic command before the cycle. Then display the completed cycle steps/total steps by d.toc in the for loops, as well as the time spent/estimated total time spent. As shown in Fig. 4.5, the second line of the message box prompts that 2866 steps have been performed, and that it has taken 0.6 min, the total number of steps is 20,000 steps, and the total estimated time is 4.3 min. The other information shown in Fig. 4.5 is a running hint to the d.mo.setNearbyBall function. When the displacement of elements exceeds a certain value (d.mo.dSide/2), the d.mo.setNearbyBall function is automatically run by the system to update the Neighbor Matrix d.mo.nBall, which outputs the prompt information shown in the figure. balanceTime, which is the first part of the information, gives the current time of the numerical simulation, i.e., d.mo.totalT. The information in the figure shows that the real-world time for the numerical simulation is 0.0046 s. The “dis_m” of the second part of the information indicates that the displacement of elements in iterative calculations exceeds the value of the setting d.mo.dSide/2 and automatically runs setNearbyBall. If the moving group produces a displacement and setNearbyBall is running, the corresponding prompt is “moveGroup dis_m.” Fig. 4.5 The output information of the message box during the iterative calculation of the cycle

4.3 Time and Settings of Iterative Calculation

103

4.3.2 Radius of Elements and Time of Calculation In the process of modeling, the element with a larger radius is usually used for testing, and this radius is then reduced for high-precision numerical simulation. For threedimensional discrete element models, the number of model elements increases to c3 times and the computation increases c4 times when the radius of the element is reduced to 1/c of the original value. When the radius is reduced by half, the number of elements in the threedimensional model increases eight times. In addition, as shown in Sect. 1.3.3, when the radius of the element is reduced to 1/c of the original value and the vibration period of the element decreases, the time step d.mo.dT of the discrete element numerical simulation also decreases to 1/c of the original value. Therefore, MatDEM introduces the concept of standard balance (Sect. 3.5.1): when the radius of the element changes, the iteration steps are automatically adjusted to ensure that the time of the simulation is identical to real-world time. Therefore, when simulating real-world time, the iteration steps need to be increased to the original c times. Due to the increase in the number of elements, when the radius of the element is reduced to 1/c of the original value, the calculation of the discrete element simulation is increased to c4 times the original value. As described in Sect. 1.6.1, the calculation speed of MatDEM increases rapidly when using the calculation method for the GPU matrix in line with the increase in the number of elements. Numerical simulation of DEM is based on repeated iterative calculation, and the number of iterations per second determines the time of calculation. Figure 4.6 shows the relationship between the number of iterations per second of different GPUs (video card) and the number of elements, including Tesla P100, which is a professional GPU computing card (16 GB video RAM); GTX

Number of iterations per second

120 100 80 60 40 20 0

100

1000

10000

100000

1000000

10000000

Number of elements Tesla P100 (16 GB)

GTX 1080Ti (11 GB)

GT 940M (2 GB)

Fig. 4.6 Number of iterations per second for different GPUs (video card)

104

4 Load Settings and Numerical Calculations

1080Ti, which is a high-performance video card for a desktop computer (11 GB video RAM); and GT 940 M, which is a video card for a laptop (2 GB video RAM). It is important to note that when the number of elements is less than 4000, CPU calculation is faster than GPU calculation and MatDEM will automatically select the CPU for calculation. The professional video card of a Tesla GPU clearly has a faster calculation speed. Thus, when the number of elements increases from 10,000 to 100,000, the number of iterations per second performed is virtually the same. A professional GPU server (Tesla P100 GPU) can simulate 1.5 million 3D elements at most, and there will be a high number of iterations per second (more than 52 times) within 200,000 elements. For a high-performance desktop computer (GTX 1080Ti), there will be a high number of iterations per second (29 or more) within 100,000 elements. For regular laptops (GT 940 M), there will be a higher number of iterations per second (more than 25 times) within 30,000 elements. Table 4.2 gives the optimal interval of element numbers for these video cards, which suggests that the number of computing elements in the test can be calculated more quickly. Table 4.2 also shows the maximum number of simulation elements in each GPU (video card) and the recommended number of elements of high-precision simulation. MatDEM needs approximately 1 GB of video RAM per 100,000 elements of simulation. However, the general recommendation is to use no more than half of the video RAM. Data can be viewed and tested through another MatDEM window during numerical calculations. And there are better iterations per second when approaching the optimal number interval of elements. In Table 4.2, the number of elements refers to the number of active elements, and the size of the calculation for MatDEM is almost unaffected by the number of fixed elements; thus, the total number of elements may exceed the values in the table. As shown in Fig. 4.7, we used the Tesla P100 to achieve a numerical simulation of the sliding process of sand particles with 2.35 million elements (BoxSlope example), which contains 830,000 active elements. The latest Tesla V100 currently supports approximately 3 million elements. Table 4.2 Number of elements simulated by MatDEM when using different video cards Computer (video card)

Video RAM/GB

Maximum number of elements/10,000

Optimal interval of element numbers/10,000

Number of elements with high-precision simulation/10,000

GPU server (Tesla P100)

16

About 150

0.5~20

20~80

High-performance desktop computer (GTX 1080Ti)

11

About 100

0.5~10

10~50

2

About 20

0.5~3

3~10

Regular laptops (GT 940 M)

4.3 Time and Settings of Iterative Calculation

(a) The initial conditions

105

(b) Sliding process

Fig. 4.7 Sliding of sand particles

Based on the above analysis, although the radius of each element decreases (1/c), the calculation will increase in four squares (c4 ) because the speed of the GPU calculation increases with the number of elements. The time of calculation will therefore increase in three squares in the optimal interval of elements. From this information, the total time required can be estimated when the radius of each element is reduced for high-precision analysis. For example, when the radius of each element is reduced by half, the number of elements increases eight times and the time of calculation increases by five to ten times.

4.3.3 Settings for Dynamic Issues In the simulation of dynamic problems, it is usually only necessary to set a load once and complete the numerical simulation through a first-stage cycle iteration with a relatively small amount of calculation. For example, in a simulation of a landslide, the results can be obtained through iterative calculations by applying gravity to all elements. Conversely, in a simulation of seismic waves, after applying a boundary displacement to produce these waves, iterative calculations can be used to calculate the propagation of seismic waves. At this point, the time d.mo.totalT in the numerical simulation is consistent with real-world time. totalT can be several tens of seconds (the example of a 3D Slope) when simulating a large landslide. However, in the simulation of seismic wave action, totalT may only be 0.1 s (the example of an earthquake). Because the optimal damping coefficient (Sect. 1.3.5) adopted by MatDEM is large by default, and the stress wave (seismic wave) plays an important role in these dynamic problems, it is necessary to take a relatively small damping coefficient based on the actual situation and multiply the damping of elements by a smaller coefficient (visRate) to reduce the effect of damping force:

106

4 Load Settings and Numerical Calculations visRate=0.00001; d.mo.mVis=d.mo.mVis*visRate;

In the simulation of dynamic problems where the element moves at a very fast speed, the time step of the simulation d.mo.dT needs to be reduced. This is because, when the speed of an elements is very high, a fast-moving element can move through one element at a time step, causing computational errors and explosion of the model. In the example of a meteorite hitting the ground (BoxClash 3), the following code is used: d.mo.mVZ(discId)=–1000; d.setStandarddT(); d.mo.dT=d.mo.dT*0.05;

Line 1 sets the downward speed of the meteorite element to 1000 m/s. Lines 2 and 3 set the system’s time step to 5% of the standard value. In the example of BoxCrash, when the average radius of the element is 3 m (low-precision model), the default time step is 2×10-4 s and 0.2 m will be moved within a time step. When the time step is reduced to 1×10-5 s, the movement within a time step is 0.01 m. To ensure a more accurate simulation, the fastest moving element does not move more than 1/100 of the minimum radius of the element in a time step.

4.3.4 Setting and Simulation Accuracy of Quasi-Static Problems For simulation of a quasi-static process, such as uniaxial compression test simulation of rock, tectonic evolution process simulation, and other quasi-static process simulations, cyclic iteration is needed to simulate the gradual change of load. (1) Settings of a two-stage cycle In the third step of the numerical simulation, the for loops are generally used to gradually apply pressure or boundary displacement, following which the d.balance function is run to balance the model. To apply the load step by step and save the file, a two-stage cycle is often used, which is as follows:

4.3 Time and Settings of Iterative Calculation

107

dis=0.005;%total displacement dDis=dis/totalCircle/stepNum;%displacement of each step for i=1:totalCircle for j=1:stepNum d.moveGroup('botBox',dDis,0,0,'mo'); d.balance('Standard',balanceNum); end %save data end

The code described above can be found in BoxShear3, the third step of the direct shear test example, which controls the horizontal movement of the bottom shear box and shears the sample. The code runs totalCircle times in the “for” loop, saving the data file once per cycle and generating totalCircle data files. In the secondary cycle, the parameter stepNum defines how many new displacement loads are applied before each recording file. After each displacement load is applied, energy is consumed by the standard balance. The d.balance function actually contains the iterative cycle of the third layer, with the input parameter balanceNum used to define the times of the standard balance. For example, if the number of iterations per standard balance is m (see Sect. 3.5.1 for details), the total number of iterations is N = m×balanceNum×stepNum×totalCircle. The real-world time corresponding to the numerical simulation is d.mo.totalT = d.mo.dT×N. (2) The parameters of the cycle and the accuracy of the simulation In the real world, the stress and strain loads of quasi-static processes are usually applied continuously and slowly. In a numerical simulation of discrete elements, these continuous processes of load change need to be broken down into sufficient load steps to avoid the bounce of intense stress and the accumulation of kinetic energy. In a circular iteration that imposes a load step by step, the total load is usually constant (e.g., dis= 0.005). The parameters that affect numerical simulation include the total load step (stepNum×totalCircle), the standard balance number (balanceNum), and the damping coefficient ratio (visRate). The total load step breaks the application of the total load down into enough steps to make the load change for each sufficiently small. After each step of loading is applied, the kinetic energy generated (stress wave) needs to be consumed through the standard balance, and the time of standard balance defines the time used to balance the kinetic energy. The damping coefficient ratio can be used to adjust the speed of dissipation in stress waves, and in quasi-static problems, the stress wave generated by the applied load needs to be consumed as soon as possible to enable the system’s default optimal damping coefficient to be adopted (see Sect. 1.3.5 for details). Quasi-static problems require every step of iterative computation to be close to a state of equilibrium, which usually requires a huge amount of computation. For example, for small-scale uniaxial compression tests of rock, the small radius and large stiffness of the element means the time step is very small (e.g., 1×10−7 s),

108

4 Load Settings and Numerical Calculations

while the actual test process is usually measured in minutes, which means that the number of iterations reaches billions. For simulation of large-scale structural evolution (such as folding), although the radius of the element and time step (up to a few tenths of a second) are relatively large, the simulation time scale is extremely large (such as thousands of years), and the number of iterations will reach tens of billions. As shown in Sect. 4.3.2, there can be approximately 100 iteration calculations per second for MatDEM and 1 billion iterations will take 115 days to complete. Therefore, DEM reduces the number of iterations by using a larger damping coefficient. Using the optimal damping coefficient, the majority of kinetic energy in the model can be consumed with a standard balance, enabling the model to reach quasi-static conditions. After setting the times of saving files (totalCircle), the number of iteration calculations is controlled by the parameters of stepNum and balanceNum. To ensure reasonable computation time (hours to days), the number of high-precision numerical simulation iterations is usually in the millions. When the total number of iterations is certain, larger stepNum and smaller balanceNum (e.g., 0.1) can be used to maintain the fluctuations of kinetic energy in the system at a low level. For example, in the uniaxial compression test, the sample of rock was compressed to 10 mm, the process of compression was divided into 10 steps (totalCircle), and the data was saved each time the compression reached 1 mm. There are two schemes for setting up stepNum and balanceNum:➀ The 1 mm compression process is decomposed into 100 steps (stepNum) and the time of standard balance is set as 1. ➁ The 1 mm compression process is decomposed into 1000 steps (stepNum) and the time of standard balance is set as 0.1. The calculation involved in these two settings is the same, but the displacement of each step of the latter is 1/10 of the original and the corresponding elastic strain energy is 1/100 of the original. The fluctuation of system energy is smaller and has higher accuracy. Therefore, larger stepNum is helpful in ensuring the simulation of quasi-static processes. How much is therefore appropriate for the steps of the total load? To determine the minimum total load step, we recommend that the amount of force generated by each load application should not exceed the element’s breaking force, i.e., d.mo.aBF. Alternatively, the displacement load cannot exceed the break displacement of the elements (e.g., d.Mats{1}.xb). At the same time, when displacement load is applied, the bounce of stress can be buffered by the pressure platen.

4.4 Definition and Modification of Simulated Parameters 4.4.1 Creation of Custom Parameters MatDEM supports the creation of custom parameters that are used for complex numerical calculations. In the class of build and model, the structure SET is included, i.e., d.SET and d.mo.SET. During modeling and numerical simulation, users can

4.4 Definition and Modification of Simulated Parameters

109

assign custom parameters directly in the SET. For example, in a multi-field coupling numerical simulation, new properties of moisture field and temperature field may need to be defined and the property of the element’s water content d.mo.SET.aWC added. The temperature of the element is recorded with d.mo.SET.aT and the parameters are calculated and updated during the cycle iteration to realize the numerical simulation of complex processes such as this. For the practical application of custom parameters, the example of SoilCrackNew demonstrates soil cracking with water loss and the example of TunnelHeat demonstrates the thermal coupling of energy piles. In TunnelHeat, d.show (‘SETaT’) can be used to display a custom element’s temperature parameter d.mo.SET.aT (see Sect. 5.2.1 for details on the post-processing display of custom parameters).

4.4.2 Modification of Element Properties in a Group In numerical simulations, it is often necessary to set different properties for different elements. For example, in the simulation of a rolling stone hitting the net, global damping is adopted by default in the elements, and the elements of the net can be set with large damping. In the simulation of rock broken with microwaves, some elements need to expand or contract at some point, and the thermal conductivity coefficient and expansion rate of the particular elements need to be set. Modifications of element properties often use a filter, the concept and use of which are explained in Sect. 3.2.2. Such modifications are not complicated and the element properties can be assigned directly after the model is built. The example of BoxLayer (Fig. 4.8) demonstrates how to modify the properties of the specific elements based on the model parameters and group set in BoxLayer2. First, to modify the radius of elements in the “Pore” group, the following code is run on the command line: poreId=d.GROUP.Pore; d.mo.aR(poreId)=d.mo.aR(poreId)*0.5;

In BoxLayer2, filters are used to filter out elements in the middle circular area and define them as “Pore” group. Therefore, the element number poreId of the intermediate pore section is recorded in the member “Pore” of the structure GROUP. The array of aR in the model object records the radius of all elements in the model. If we want to reduce the radius of elements in the pore portion by 50%, we can index them using the array of poreId to find the radius of elements in the pore (d.mo.aR(poreID)) and set them to half of the original. We can see the results through d.show (‘aR’), as shown in Fig. 4.8b. Similarly, to increase damping of the pore elements, the following command can be continually run to enlarge the damping of the pore elements by 100 times:

110

4 Load Settings and Numerical Calculations

(a) Three materials in Boxlayer

(b) Reducing radius of element

Fig. 4.8 Modification of the element’s radius of the Pore group

d.mo.mVis(poreId)=d.mo.mVis(poreId)*100;

The following demonstrates the calculation of the properties of particular elements, i.e., calculation of the external force of the elements in the pore. The command is as follows: poreForceXX=d.mo.nFnX(poreID); poreForceYY=d.mo.nFnY(poreID); poreForceZZ=d.mo.nFnZ(poreID); poreForce=sqrt(poreForceXX.^2+poreForceYY.^2+poreForceZZ.^2);

Through the index of array, the stress of the element in the pore can be obtained in X-, Y-, and Z-directions, respectively. The vectors of stresses in the three directions (the arithmetic square root of the sum of squares) can then be added to obtain the magnitude of the external force applied to each element. Finally, the number of elements bonded to other elements in the pore elements is calculated. The matrix used in this case is the bFilter matrix in the model object, which records whether an element is bonded to its adjacent element. poreC=d.mo.bFilter(poreId,:); poreCNum=sum(poreC,2);

The first line of code extracts the Boolean matrix poreC, which indicates whether the pore elements are bonded. The array of the pore element’s poreId is used as a row

4.4 Definition and Modification of Simulated Parameters

111

index in the bFilter matrix, which means that the row corresponding to the poreId is taken while “:” stands for all columns. The position in the poreC matrix where each row has a value of 1 is an element cemented to its neighbor. Therefore, the total number of which the value in each row is 1 represents the total number of elements bonded with the element. The sum function can then be used to sum the poreC matrix in the row direction to obtain the number of bonded elements of each element, which is recorded in poreCNum. To calculate the coordination number of each element, i.e., the number of elements squeezed against it, a similar method can be applied by filtering and summing the rows of the matrix that record the corresponding information. All data in MatDEM is public and can be viewed and extracted in real time, such as the property and status of any one element. Users therefore need to know how to extract data using matrix operations and process data on this basis. If users want to modify the parameters in the model before starting numerical simulation, they can usually modify the parameters in the model object. If the properties of an element are modified, it is important to update other related data in the model so that the calculation does not go wrong. Therefore, after modifying the element parameters of the model, the following two commands are often used: d.mo.setNearbyBall(); d.mo.zeroBalance();

The setNearbyBall function is used to update the Neighbor Matrix of elements. When an element parameter is modified, such as the radius of an element, a change may occur in the element’s neighbors, and therefore the element’s Neighbor Matrix needs to be recalculated. The zeroBalance function implements zero balance operations (see Sect. 3.5.3 for details) and is used to calculate the current state of the model. After modifying the model parameters, many will change, such as strength and distance between elements, which may lead to broken connections and a sudden increase in force. If the model state is not updated in advance, the calculation of the next time step may be wrong. Therefore, the model state can be updated with the zeroBalance function, which is based on setting the time step dT to 0 for a balance calculation. This enables the model to update to its current state and corrects the corresponding parameters.

4.4.3 Settings of Time Step, the Radius of Elements, and Stiffness (1) Time step and the speed of calculation When material is assigned to the elements of a model each time (d.groupMat2Model function), the d.period parameter is set by the d.applyMaterial function, which

112

4 Load Settings and Numerical Calculations

records the smallest vibration period of active elements of the model. At the same time, the d.setStandarddT function resets the time step d.mo.dT of system, takes the value of d.period’s 1/50, and retains a significant figure. Thus, if period/50 is 0.000185 s, the time step takes 0.0001 s. Therefore, the actual time step takes the minimum vibration cycle’s 1/100 to 1/50 of elements, which can effectively ensure the stability of the system calculations. Care is needed to ensure there are as few rigid elements as possible in the model, otherwise the time step will be reduced which will dramatically increase the iteration steps and calculation time. For example, in Sect. 7.1, we lock the element’s freedom degrees of the direct shear metal box and give the sample element the mechanical properties of soil (lower stiffness). The efficiency of computation can then be significantly improved with the correct simulation (the metal box does not deform). For example, to speed up a packing model and the balance process, the time step can be increased with the following code: d.mo.dT=d.mo.dT*4; d.balance(‘Standard’); d.mo.dT=d.mo.dT/4;

This method is used in the functions B.gravitySediment, d.balanceBondedModel0, and d.balanceBondedModel to increase the speed of numerical simulation. Note that this approach is limited to modeling as well as iterative computational testing. In formal iterative calculations, standard time steps (or smaller) are used to ensure the accuracy of the simulation. (2) The Radius of Elements and the Neighbor Matrix The Neighbor Matrix d.mo.nBall records all the elements that may be in contact with each element. As the radius of elements increases, they may be in contact with elements beyond the Neighbor Matrix. The Neighbor Matrix therefore needs to be updated by running the d.mo.setNearbyBall () command. For example, in the energy pile thermal coupling example of TunnelHeat, the following code simulates the thermal expansion of the elements and updates the Neighbor Matrix: d.mo.aR(1:d.mNum)=d.aR(1:d.mNum).*(1-0.01*(initialT-d.mo.SET.aT (1:d.mNum))./initialT); d.mo.setNearbyBall();%if

elements

are

expanded,the

command

is

required

In practice, the expansion of elements does not create new contacts at every turn and the retrieval function of the neighbor element can be selectively run through further secondary development. For example, based on the above code, recording the increment of radius mdR of the active elements and determining whether the Neighbor Matrix needs to be retrieved significantly reduce the number of times the

4.4 Definition and Modification of Simulated Parameters

113

retrieval function is run, thus increasing the efficiency of calculation. The example code is as follows: if(max(abs(d.mo.dis_mXYZ(:)))+mdR＞0.5*d.mo.dSide) d.mo.setNearbyBall(); end

(3) Stiffness of elements and stiffness matrix The stiffness of each element is recorded in d.mo.aKN and d.mo.aKS, while the stiffness matrix d.nKNe (nearby(n)-normal stiffness(KN) -equivalent (e)) and d.nKSe of the element’s connection are used in the actual calculation of elements with force. The stiffness matrix of each element’s connection can be calculated by aKN and aKS using the formula presented in Sect. 1.2.2. In MatDEM, when the aKN and aKS of the elements are modified, the stiffness matrix of the connection is updated by running the d.mo.setKNKS () command. For example, in SoilCrackNew, if the increase in soil strength is considered when the moisture content decreases, aKN and aKS need to be modified, following which the d.mo.setKNKS () command is run.

4.5 Compression, Saving, and Reading of Files Saving and reading of data are common operations in numerical simulation. This section will introduce operations related to data saving in MatDEM.

4.5.1 Compression of Files The object data of MatDEM include various property information of elements, such as the connection and force information of the elements, the boundary force of the system, and the information on energy conversion. When there are millions of elements in the model and each element records a variety of information, the size of the data will reach hundreds of MB, or even GB, levels. In numerical simulation, data files need to be saved constantly. When the number of elements is large, an immense amount of saving space is required. MatDEM therefore provides the data compression function d.clearData to remove dependent data from the program. In MatDEM objects, a large amount of data can be calculated by other data, for example, the inter-element contact force components nFnX, nFnY, and nFnZ in d.mo, which can be calculated according to the coordinates and radius of the elements. The connected compression state matrix cFilter and the tension state matrix tFilter can also be calculated using these three components. Furthermore, the data in d.data is calculated from the data in d.mo. The d.clearData

114

4 Load Settings and Numerical Calculations

command enables these data to be deleted, reducing the size of the saved file. After compression the file may be only one-third of the original volume, which can save substantial space. The d.calculateData function can then be run to recalculate the non-independent data for post-processing or calculation of the next cycle.

4.5.2 Saving and Reading of Files Data is saved using MATLAB’s save function during numerical calculations at the end of each code file and in the numerical calculation of the third step. The purpose is to save workspace variables to the .mat file (see MATLAB help file for details). The following shows how to use this in the sample code: save(filename,variables)

Without specifying variables, the save function saves all the variables in the workspace. Otherwise, only the variables specified are saved, such as save(‘abc.mat’, ‘d’) which will save the variable d in the abc.mat file. By default, the save function saves the data as a binary file (.mat file) and is named filename. If filename already exists, the new data covers the file. In the sample file, the file name can be defined as the filename = [‘TempModel/’ B.name ‘.mat’], and the data files are saved in the TempModel folder and named after B.name using the save command. For large files (greater than 2 GB), it may be necessary to declare the saved version as ‘-v7.3’ (consult the help file of MATLAB for details). As a general rule the saved MatDEM file will not reach 1 GB (millions of elements) after data compression. save('abc.mat','d','-v7.3')

Before saving the file, it is recommended that the d.mo.setGPU (‘off’) command is run to transfer the data from the GPU to the CPU, otherwise the computer without the GPU will not be able to load the data. The saved data can be reloaded into the program using the load command as follows: load('abc.mat');

For matrix data in MatDEM, this can be selected in the data viewer and Ctrl+C can then be used to copy the data and paste it into other software for further analysis. The following command can also be used to save matrix data in a text file: leftBFs=d.status.leftBFs; save('leftBFs.txt',leftBFs);

4.5 Compression, Saving, and Reading of Files

115

The above command saves the historical data on left boundary force saved in d.status.leftBFs in the leftBFS.txt file. Similarly, the load command can be used to read matrix data from a text file: leftBFs2=load('leftBFs.txt');

The above command reads the matrix data saved in leftBFs.txt into the program and assigns it to the variable leftBFs2. Using MATLAB’s reading and writing file commands (such as fopen and fwrite), a variety of complex data and files can be read and saved, including binary files. For specific methods and examples not included here, users can search in the network regarding how MATLAB reads files.

Chapter 5

Post-processing and System Functions

5.1 Post-processing Window Interface 5.1.1 Main Post-processing Window MatDEM provides a wealth of post-processing features that make it easy to generate a variety of graphics and animations. Figure 5.1 shows the post-processing window. When users enter this window, MatDEM will automatically import the object d of the build class in the main program into the post-processing window. Alternatively, users can also use the “Open data file” at the upper left corner of the post-processing window to import a new data file. The left side of the window contains a series of figures displaying options. In the show type, options for three types composed of dozens of figures are provided, namely, ➀ simulation result, primarily showing data in d.data; ➁ model parameters, primarily showing data in d.mo; and ➂ process curve, primarily showing data in d.status. These figures can be displayed using the d.show(type) command, as described in Sect. 5.2.1. All active elements in MatDEM are limited to a simulation box consisting of six boundaries (Fig. 5.1). The software provides a variety of methods for showing boundaries, including ➀ not show frame and fixed elements; ➁ show frame; ➂ show boundary; and ➃ not show boundary. The specific effects of various showing methods can be found in Sect. 5.2.1. Users can choose to show one to four figures simultaneously in a new window. The corresponding number of figure buttons will then appear below. Four figures are selected in Fig. 5.1. The default is “Stress ZZ,” “Energy curve,” “Boundary force curve,” and “Heat curve.” The “Make figure” button can then be clicked to generate the selected figure. Figure 5.2 shows the four figures for the numerical simulation of damped simple harmonic vibration in Sect. 1.3.5. Based on figures, the state of the numerical simulation can be analyzed. Users can then choose the figure in the show type and click the figure button in the show mode to set the figure type. © The Author(s), under exclusive license to Springer Nature Singapore Pte Ltd. 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9_5

117

118

5 Post-processing and System Functions

Fig. 5.1 MatDEM post-processing window

Fig. 5.2 Four default figures shown in the post-processing of the damped simple harmonic vibration

5.1 Post-processing Window Interface

119

When the number of elements showed reaches several hundred thousand, the show speed of the three-dimensional spherical elements becomes slower. At this point, the upper limit for showing can be set. When the number of elements exceeds the upper limit, the element will be displayed as a point to quickly show the result. The post-processing window can only provide a relatively simple results display. Richer post-processing requires the use of functions such as d.show and d.showFilter (see Sect. 5.2). Users can then enter the command on the command line at the bottom of the window to show the result. When the d.show() command is run, the four default maps shown in Fig. 5.2 are generated.

5.1.2 Saving the Post-processing Figure In the post-processing window, when “Draw and edit in new form” is selected, clicking “Make figure” will display a new window, as shown in Fig. 5.3a, and a figure will be generated. Users can change the size of the window and then set the resolution of the exported figure in “File → Export Settings” (Fig. 5.3b). A resolution above 300 can usually meet the publishing requirements. Table 5.1 shows image formats that can be saved by the post-processing module. The commonly used figure formats are as follows: ➀.fig file is a vector file format of MATLAB. The.fig file can be opened in MATLAB software for further editing and processing and then exported to other file formats; ➁.eps file is a cross-platform vector figure file format and is a commonly used file format for printing and publishing; ➂.png file is a lossless compressed image format and is relatively small. The simulation result figure can usually be saved as a.png file for reporting, presenting, and network sharing; and ➃.tif file is a file format for printing.

Fig. 5.3 Save figure and setup window

120

5 Post-processing and System Functions

Table 5.1 The image formats that can be saved by post-processing Image formats that can be saved

Image format description

MATLAB Figure(*.fig)

Vector file format of MATLAB

Bitmap file(*.bmp)

Common bitmap format, lossless format, large file size

EPS file(*.eps)

Cross-platform standard image format that can be opened and edited using a variety of professional drawing software, available for publishing

Enhanced metafile(*.emf)

Windows extended metafile format, belongs to vector file format

JPEG image(*.jpg)

Common JPEG figure files, lossless compressed format, small file size, not recommended for publishing

Paintbrush 24-bit file(*.pcx)

A format of the image processing software Paintbrush

Portable Bitmap file(*.pbm)

Portable bitmap format for cross-platform image formats

Portable Document Format(*.pdf)

Common PDF files

Portable Network Graphics file(*.png)

Common PNG image files that are lossless compressed formats, larger than JPEG files, and can be used for publishing

Portable Pixmap file(*.ppm)

Portable pixmap format for cross-platform image formats

Scalable Vector Graphics file(*.svg)

Scalable vector graphics based on XML

TIFF image(*.tif)

Common TIFF image files that are lossless compressed formats, larger than JPEG files, and can be used for publishing

TIFF no compression image(*.tif)

Same as above, but not compressed

5.1.3 Making GIF Window A GIF-making module is provided at the top of the post-processing window: users need to select the type of image to be animated in “Show type” on the left and then click the “Files of GIF” button to select the data file for the animation (Fig. 5.4). After setting the file name and size, clicking “Start making GIF” will cause the software to display the corresponding pictures one by one according to the order of files, automatically generate GIF animation files, and save them in the gif folder of the software. This animation window program is based on the secondary development code user_makeGIF, which allows users to create more complex custom GIF animations by modifying the code:

5.1 Post-processing Window Interface

Fig. 5.4 Making GIF interface

clear frames; indexBegin=0;%begin index of data file indexEnd=1;%end index of data file showType='StressZZ'; for showCircle=(indexBegin:indexEnd) load([fName num2str(showCircle)'.mat']);%load the saved file d.calculateData();%calculate the data of the model d.showFilter('SlideY',0.5,1);%cut the model if necessary d.showB=3;%show the frame d.isUI=0; d.show(showType);%show the result set(gcf,'Position',[10,10,1000,600]);%set figure size frames(showCircle+(1-indexBegin))=getframe();%record the figure pause(0.1);%pause 0.1 second close;%close the figure end

121

122

5 Post-processing and System Functions

GIF animations enable the dynamic presentation of numerical simulation results by playing images frame by frame. Making a GIF requires the use of a sequence of saved data files (.mat files), which are usually generated in the third step of the code file. Before running the code, opening a data file that needs to be animated will automatically assign a value to the image file name fName. In the code, indexBegin and indexEnd record the start and end number of the data file sequence; these data files are then loaded through the loop to generate the map and then stored in the frames array. Finally, the function fs.movie2gif is used to convert the image array in frames to an animated GIF, which is then stored in the gif folder of the software. Running the d.isUI = 0 command always shows the generated figure in a new window, whereas the close command closes the window after storing the image. Therefore, when the above code is run, a new figure will pop up and be automatically closed until the full loop calculation is completed and an animated GIF is generated. To change the viewing angle of the animation, the MATLAB function view is used and the system uses the view (16, 30) command to set the default perspective. At the same time, the showCircle parameter can be used to constantly change the angle of view to achieve multiaspect observation. For example, the view(10*showCircle, 30) command can be run in the above code to shoot around the object and generate animation. In addition, the code can use the d.showFilter and d.show functions to cut and show the model, as described in Sect. 5.2.

5.2 Post-processing Drawing Functions 5.2.1 General Drawing Function d.show The function d.show is the most important post-processing function in MatDEM; it corresponds to the functions of options on the left side of the post-processing window. d.show allows variable input parameters (0–4), which are strings. For example, d.show('StressZZ'); d.show('StressXX','StressZZ'); d.show('StressZZ','EnergyCurve','ForceCurve','HeatCurve'); d.show(); d.show('-StressZZ');

The first line command displays the element’s Z-direction stress in the window; the second line command displays the element’s X- and Z-direction stresses (left and right distributions, respectively) in the window; the third line command displays the Z-direction stress in the window as well as the energy curve, the boundary force curve, and the heat curve; the fourth line command and the third line command generate the same figure; the fifth line command generates the Z-direction stress

5.2 Post-processing Drawing Functions

123

figure; and the green line segment is used to draw the connection between elements. When elements are in close contact, you cannot see the connection between them. d.Rrate = 0.5 usually needs to be run to reduce the display radius of the element to half the actual radius. Each time the d.show function generates a figure in a new window, the result can be appended to the current window by running the d.showData function with the same input parameter as d.show; however, only one input parameter is supported. The d.show function has four types of input parameters: simulation results, model parameters, process curves, and custom parameters. These are described as follows. 1. Simulation results Such parameters are recorded in d.data and are calculated by parameters in d.mo. The parameters in d.data are cleared after running each iteration of the d.mo.balance() calculation function. When running the d.show or d.showData function, the program will automatically calculate and set the parameters in d.data (the d.setData function can also be run). Table 5.2 shows parameters for recording simulation results in d.data. If the d.show(‘StressZZ’) command is run, the data in d.data.StressZZ can be displayed.

Table 5.2 Post-processing parameters and parameter meanings based on d.data Parameter name

Parameter meaning

Parameter name

Parameter meaning

StrainXX

Normal strain in the X-direction

groupId

Group number

StrainZZ

Normal strain in the Z-direction

CoordinationNumber

Coordination number

StrainYY

Normal strain in the Y-direction

StressXY

Normal stress in the XY-direction

YDisplacement

Displacement in the Y-direction

StressXZ

Normal stress in the XZ-direction

ZDisplacement

Displacement in the Z-direction

StressYX

normal stress in the YX-direction

Diameter

Diameter

StressYZ

Normal stress in the YZ-direction

Heat

Heat

StressZX

Normal stress in the ZX-direction

ViscosityHeat

Viscosity heat

StressZY

Normal stress in the ZY-direction

BreakingHeat

Breaking heat

FixXId

X-coordinate lock

SlippingHeat

Slipping heat

FixYId

Y-coordinate lock

ElasticEnergy

Elastic energy

FixZId

Z-coordinate lock

KineticEnergy

Kinetic energy

124

5 Post-processing and System Functions

2. Model parameters Such parameters are recorded in d.mo and are usually the current state of the element, such as force, velocity, and acceleration. Table 5.3 shows the element parameters in d.mo. The command d.show(‘aR’) is run to display data in d.mo.aR. The vector in the table (such as mA) consists of three components (such as mAX, mAY, and mAZ). When the number of elements is fewer than 20,000, the arrow line of the vector will be displayed. In this case, a smaller d.Rrate may need to be set so that it is easy to view. 3. Process curves Such parameters are recorded in d.status and used to draw boundary forces, energy curves, heat curves, and cracks during numerical simulation. Each time the d.recordStatus() command is run, MatDEM calculates the total force, system energy, Table 5.3 Post-processing parameters and parameter meanings based on d.mo attributes Parameter name

Parameter meaning

Parameter name

Parameter meaning

aMatId

Material number

mVY

Velocity in the Y-direction

aR

Radius

mVZ

Velocity in the Z-direction

aKN

Normal stiffness coefficient

mA

Acceleration (vector)

aKS

Tangential stiffness coefficient

mAX

Acceleration in the X-direction

aBF

Breaking force

mAY

Acceleration in the Y-direction

aFS0

Shear resistance

mAZ

Acceleration in the Z-direction

aMUp

Coefficient of friction

mVF

Damping force (vector)

aX

X-coordinate

mVFX

Damping force in the X-direction

aY

Y-coordinate

mVFY

Damping force in the Y-direction

aZ

Z-coordinate

mVFZ

Damping force in the Z-direction

mVis

Viscosity coefficient

mG

Physical strength (vector)

mM

Quality

mGX

Physical strength in the X-direction

mV

Velocity (vector)

mGY

Physical strength in the Y-direction

mVX

Velocity in the X direction

mGZ

Physical strength in the Z-direction(gravity)

nBondRate

Connection bonding rate (displayed when the value is other than 1); blue means weakened intensity; red means increased intensity

5.2 Post-processing Drawing Functions

125

and heat for each boundary and appends the result to the corresponding data in d.status while the time (d.mo. totalT) is appended to d.status.Ts. The status data in d.status is generally the same as the number of rows of Ts (the number of rows is n) and records the boundary force and system energy information at the time of Ts. When the function d.show is run, the curve is drawn with Ts as the abscissa value and each state parameter as the ordinate value. The data used for the boundary force curve is recorded in the matrix of leftBFs, rightBFs, and so on. The size of all these matrices is n × 3. For example, leftBFs is the total force of the left boundary element, and each line contains three values, respectively. This records the components of the total force of the left boundary element in X-, Y-, and Z-directions. The data used for the energy curve is recorded in gravityEs (gravitational potential energy), kineticEs (kinetic energy), elasticEs (elastic potential energy), totalEs (system total energy), and heats (heat) in d.status. The first four data matrices are all n × 1 in size, which are arrays, and each records the energy value. The heats is an n × 5 matrix, which will be described in further detail below. The external force work curve can also be displayed in the energy curve. The value of the external force work is recorded in d.status.works. The parameter works defaults to 0; when the data length is greater than 1, it is automatically displayed in the energy curve. After running the d.recordStatus function, the extra command is normally used to record the external force, for example, d.recordStatus(); d.status.works=[d.status.works;obj.status.works(end)+newWork]; d.status.workTIds=[d.status.workTIds;length(obj.status.Ts)];

The second line appends the total work done by the external force to the last line of the “works” array; the third line command appends the time index corresponding to the work to the last line of d.status.workTIds. When the d.show(‘EnergyCuve’) command is used to display the energy curve, d.status.Ts(obj.workTIds) is used as the abscissa value and d.status.works is the ordinate value used to draw the external force work curve. The data used in the heat curve is recorded in the heats of d.status. Columns 1–5 record the system’s damping heat (Viscous), normal spring breaking heat (Normal spring), tangential spring breaking heat (Shear spring), sliding friction heat (Slipping), and heat during compaction failure (Failure), respectively. The heat during compaction failure is only displayed when d.mo.isFailure = 1 (this function is not commonly used). Table 5.4 provides the names and meanings of these input parameters. To display the crack and generate the crack animation, users need to declare d.mo.isCrack = true (or = 1) before the numerical simulation and the relevant information will be saved in d.status.breakId. d.show(‘CrackMoive’) can generate a time axis based on the fracture information, draw new cracks step by step, and demonstrate the

126 Table 5.4 Post-processing parameters and their meanings based on d.status

5 Post-processing and System Functions Parameter name

Parameter meaning

Parameter name

Parameter meaning

ForceCurve

Boundary force curve

Force

Element force

EnergyCurve

Energy curve

WaterForce

Water force (test)

HeatCurve

Heat curve

CrackMovie

Crack movie

–

Element connection

Failure

Compaction failure (test)

Id

Element number

FailureMovie

Compaction failure movie (test)

Crack

Crack distribution

StressCurve

Boundary stress curve (test)

process of crack generation. The d.show(‘–’) command displays cemented connections between elements based on d.mo.bFilter. Figure 5.5 shows the conventional triaxial test microfracture distribution figure obtained by running the d.show(‘Crack’) command (see the 3AxialNew example for details). Fig. 5.5 Microfracture distribution figure obtained by running the d.show(‘Crack’) command

5.2 Post-processing Drawing Functions

127

4. Custom parameter d.data is a structure. In post-processing, new parameters can be placed in d.data and displayed using the d.show command, for example, d.data.diameter=d.mo.aR*2; d.show('diameter');

The above code defines the element diameter and displays the element’s diameter distribution figure using the d.show(‘diameter’) command. MatDEM allows users to add custom parameters for elements in d.mo.SET (see Sect. 4.4.1) and use them for numerical simulation calculations. Custom parameters are often used for multi-field coupling numerical simulations. For example, in the soil drying cracking example SoilCrackNew, a new attribute aWC(d.mo.SET.aWC) is added that represents the element moisture content. In post-processing, the distribution of the element water content can be displayed by d.show(‘SETaWC’), where the input parameter is “SET + variable name.” For custom parameters, users should refer to the energy pile coupling numerical simulation discussed in Chap. 10.

5.2.2 Basic Display Settings MatDEM provides four modes to display the boundary. The boundary refers to the six boundaries preset by the program, which belong to the fixed element (wall element). The display mode of the boundary can be declared by d.showB, and the value is 0–3. The meanings of different values are shown in Table 5.5, and the effect is shown in Fig. 5.6. When the value is 0, only the active element is displayed; the border line and the fixed element are not displayed (Fig. 5.6a). When the value is 1, only the border line (Fig. 5.6b) is displayed to indicate the position of the boundary; the boundary element is not displayed. When the value is 2, the fixed element (boundary) Table 5.5 Post-processing parameters and their meanings based on d.showB Boundary display type

d.showB value

Border line

Boundary element

Normal fixed element

No border or fixed element

0

No

No

No

Only show model border

1

Yes

No

No

Show model boundary

2

No

Yes

Yes

Do not show model boundary

3

Yes

No

Yes

128

5 Post-processing and System Functions

Fig. 5.6 d.showB display results when using different values

is displayed; the border line is not displayed. As shown in Fig. 5.6c, the model has been sliced using d.showFilter; when the value is 3, the border line and the fixed element are displayed; the boundary element is not displayed. The top pressure plate in Fig. 5.6d is defined as a fixed element. When showing multiple figures, the default length and width of the figure is 1000 × 600 pixels. When generating a single figure, the default length and width of the figure is 640 × 480 pixels. The following command can be used to modify the default length and width of a single image: d.SET.figureWidth=800; d.SET.figureHeight=300;

When using the function d.show to display multiple figures (such as running d.show(‘StressXX’, ‘StressZZ’)), the figure will be displayed in a new pop-up window. When displaying a single figure (such as running d.show(‘aR’)), the parameter d.isUI determines whether to draw in the current program window. If the value of d.isUI is 1, the figure will be displayed in the figure box of the original window (the figure display area is in the lower left corner of the main program); if the d.isUI value is 0, the figure will be displayed in a new window.

5.2.3 Slice Display and Filter Display The function d.showFilter(varargin) in MatDEM provides the function of slice display and filter display. This function is based on the Boolean array d.data.showFilter. Its length is the total number of elements aNum. In postprocessing, when the value is true, the element is displayed (displayed as 1); otherwise, it is not displayed. The showFilter function allows a variable number of input parameters (varargin). Table 5.6 shows several parameter types for this function.

5.2 Post-processing Drawing Functions

129

Table 5.6 Function and description of d.showFilter function Type

Function

Description Example

Slide

Cutting at the same time in the X-, Y-, and Z-directions

The second d.showFilter(‘Slide’,0.5,’aR’); parameter (Figure 5.6(a)) is the cutting block ratio

SlideX

Cutting in the X-direction

The second d.showFilter(‘SlideX’,0.2,0.4,’aR’);(Fig. 5.6(b)) and third parameters are the starting position and thickness, and the value is 0–1

SlideY

Cutting in the Y-direction

Ditto

SlideZ

Cutting in the Z-direction

Ditto

Group

Display the elements of the specified group

The second d.showFilter(‘Group’,{‘sample’,’lefB’},’aR’);(Fig. 5.6(c)) parameter is the array of the group name cell

Material Display the elements of the specified material number

The second d.showFilter(‘Material’,1,’aR’); parameter is an array of materials

BallId

Display the elements of the specified number

The second d.showFilter(‘BallId’,[1,50,100],’aR’);(Fig. 5.6(d)) parameter is an array of element numbers

Filter

Specify a new showFilter matrix

The second parameter is the showFilter Boolean matrix

130

5 Post-processing and System Functions

Fig. 5.7 The cutting result of d.showFilter

The first input parameter is the cutting type, including the type of slice, group name, material number, element number, and filter matrix. The middle parameters are those corresponding to the cutting type, which define how to cut and filter. The last parameter is the display parameter name of the string type, the value of which is the same as the value in the function d.show. This parameter is optional. For example, d.showFilter('SlideX',0.2,0.4,'aR');

The first parameter “SlideX” indicates that this command slices the sample in a plane perpendicular to the X-axis; the second parameter is the starting position of the slice; and the third parameter is the thickness of the slice, which takes values from 0 to 1. When the second parameter takes a value of 0 or 0.5, the slice starts from the model at the minimum or intermediate position on the X-axis; the last parameter “aR” shows the radius of the element. Using the command above, the slice shown in Fig. 5.7b can be obtained with a thickness 40% (0.4) of the width of the model. When the last parameter of the showFilter function (such as “aR”) is omitted, only the d.data.showFilter matrix is modified; however, it will not draw a figure. After running the command d.showFilter(‘SlideY’, 0.2, 0.4), the d.show(‘aR’) command needs to be run again to display the result. For example, the following two lines of commands are equivalent: d.showFilter('SlideX',0.2,0.4,'aR'); d.showFilter('SlideX',0.2,0.4);d.showData('aR');

If the d.showFilter function is run multiple times, the effect of each will be superimposed on others; thus, the d.data.showFilter matrix is an intersection operation. The showFilter can be reset in two ways to display all elements: ➀ run the d.showFilter() command (no input parameters) and ➁ run the command d.data.showFilter(:) = true. Both of these commands reset the values in the showFilter matrix to true.

5.2 Post-processing Drawing Functions

131

Note: When displaying borders, the effects of the d.showB property and the d.showFilter function are superimposed on each other.

5.2.4 Element Position and Force Display MatDEM provides the d.showBall(Id) function to show the position, connection, and force state of the element, where Id is the element number. For example, Fig. 5.8a shows the position of the element 1800 in the simulation box after running the command d.showBall(1800). Users can rotate the simulation box to see the threedimensional position of the element. If there is a cemented connection between elements, this will be shown as a green line segment in the figure. Figure 5.8b shows elements in contact with element 1800 and the force of these elements applying on the center element 1800. To distinguish the forces of different elements, the force arrows for the center element are marked on each contact element. Through this command, it is possible to check the force of the element, including normal force, tangential force, and so on. Among these, the element with less force on the central element (less than 10% of the maximum force) will be displayed in yellow (element 2090 in the figure) and the rest will be displayed in blue. This command helps to verify the contact of a particular element in the program.

Fig. 5.8 The element position and force state shown by command d.showBall(1800)

132

5 Post-processing and System Functions

5.3 Data Processing and Curve Drawing 5.3.1 Drawing Curves with Saved Data Taking the uniaxial compression and tensile tests as examples, once the numerical simulation is completed, the stress and strain curve can be drawn using the intermediate process file (which is saved in the data/step folder by default): load('data/step/XXX0.mat'); d.calculateData(); sampleH0=mean(d.mo.aZ(d.GROUP.topPlaten))-mean(d.mo.aZ(d.GROUP.botPlaten)); platenArea0=B.sampleL*B.sampleW; load('data/step/XXX1.mat'); d.calculateData(); sampleH1=mean(d.mo.aZ(d.GROUP.topPlaten))-mean(d.mo.aZ(d.GROUP.botPlaten)); strainZZ1=(sampleH1-sampleH0)/sampleH0; stressZZ1=d.status.bottomBFs(end,3)/platenArea0;

First, the data file XXX0.mat is loaded using the load function, where XXX is the file name, and 0 is the 0th file of the numerical simulation, that is, the initial state before the load is applied. sampleH0 is the initial height of the sample and is calculated by subtracting the average height of the top pressure plate element from the average height of the bottom pressure plate element. platenArea0 is the area of the bottom pressure plate. To calculate the stress and strain of the model after applying the first step load, the load function can be used to load the data file XXX1.mat and calculate the model height sampleH1 at this time. The sampleH0 is then subtracted to give the deformation amount, which is then divided by sampleH0 to obtain the strain strainZZ1 of the sample at the end of the first step. The last element in column 3 of d.status.bottomBFs denotes the normal force of the current lower boundary of the model. When the model is fully balanced, the normal force of the lower boundary can be regarded as the force of the sample. The stress stressZZ1 of the sample can be obtained by dividing it by the area of the bottom pressure plate. The stress and strain of the subsequent loading process can be obtained in the same way. Thus, a series of stress and strain values can be obtained and the stress–strain curve can be plotted using the plot function. Another method is to modify the code of the third step of the numerical simulation to directly calculate the stress and strain of the intermediate process and then save it to the model data, for example, by depositing it into d.TAG.

5.3 Data Processing and Curve Drawing

133

5.3.2 Drawing Curves with MatDEM Automatically Recorded Data Based on the principles described, MatDEM provides the function of recording and plotting stress and strain data automatically for block models (note: this is limited to block models). This function is demonstrated in the CuTestNew example of the uniaxial compression test. CuTestNew is a highly encapsulated code whose first and second step modeling code is consistent with the code of the automated material training example MatTraining. The third step is the code in the function mfs.makeUniaxialCuTest, which implements a uniaxial compression test that automatically records stress–strain data and identifies uniaxial compressive strength. The stress–strain recorded code in the third step is as follows: for i=1:totalCircle for j=1:divNum B.setPlatenStress('StressZZ',stressStep+(stressSteps(i)-stressStep)/divNum*j); d.balance('Standard',balanceRate,'off'); d.status.SET.isWHT=1;%record the WHT in recordStatus d.recordStatus(); end … end d.status.showBoundaryStresses(); d.status.showStrainStress();

The code applies a stress to the sample using B.setPlatenStress for standard balance. The size of the sample is then declared, which needs to be calculated by d.status.SET.isWHT = 1. In the command d.recordStatus, when isWHT is 1, the length, width, and height of the model are calculated and recorded in the d.status.TAG.WHT matrix. At the same time, the length of the current time step record array d.status.Ts is saved to the array d.status.TAG.WHTId, thus recording the time step of this data. Finally, d.status.SET.isWHT is reset to 0. Therefore, each time the model size is recorded, isWHT needs to be set to 1. Once the iterative calculation is complete, the stress in the XX-, YY-, and ZZ-directions can be obtained by the function showBoundaryStresses (Fig. 5.9a). The strain change in each direction when the pressure in the StressZZ direction is increased is obtained by the function showStrainStress (Fig. 5.9b). The drawing function showStrainStress is based on the function fs.getBlockStrainStress. The StressZZ-StrainZZ figure can be obtained by the following code:

134

5 Post-processing and System Functions

Fig. 5.9 Stress–time figure and strain–stress figure

S=fs.getBlockStrainStress(d.status); plot(-S.strainZZ,-S.stressZZ,'k'); xlabel('StrainZZ'); ylabel('StressZZ'); title('StressZZ-StrainZZ Curve during uniaxial compressive test');

The S structure returned by the first line of code contains the sample size array (WHT ), the normal stress in the XX-, YY-, and ZZ-directions, and the rest of the code is then used to draw the curve. The code above can be run to give Fig. 5.10. Fig. 5.10 Stress–strain curve of uniaxial compression test

5.3 Data Processing and Curve Drawing

135

5.3.3 Processing Data and Plotting in MATLAB (1) View data and plots in MATLAB MatDEM uses MATLAB’s data format (.mat file); therefore, MATLAB software can be used to open, view, and edit “.mat" data files. Objects in the MatDEM data file (such as B, d, and d.mo) use the class file of the MatDEM program; therefore, support is required for a related class file to open correctly in MATLAB. A series of MATLAB auxiliary files (.p files) are provided in the fun folder of the software. These can be used to open, view, and edit data files saved by MatDEM in MATLAB and then draw them. When opening data, the current folder must contain the required auxiliary files. If they do not, then the folder where the auxiliary files are located must be added to the MATLAB search path. First, the fun folder is entered in the MATLAB software. As shown in Fig. 5.11, the current folder is fun, which contains a series of .p files as well as custom function files. build.p and model.p are used to display the data in d and d.mo, respectively. When loading data under this folder, users can open the.mat file saved in MatDEM. Users can then use the MATLAB commands to process the data and plot: they can use all the functions in mfs as well as drawing functions such as fs.showObj(). (2) Basic matrix operation of MATLAB The secondary development of MatDEM is based on the MATLAB language, and most of the parameters are matrix (array). In the secondary development code, a large number of MATLAB matrix operations and indexes are involved. The following is only an introduction; for specific details, the matrix operations and operations of MATLAB need to be viewed. There are three main indexing methods for array

Fig. 5.11 View data saved by MatDEM in MATLAB

136

5 Post-processing and System Functions

elements: ➀subscript index. Taking the array A = [−1; −2; −3; −4] of four rows and one column as an example, A(2) indexes the elements with the subscript 2, so the value of A(2) is −2; ➁ array index. MATLAB allows an array to be used as a subscript of another array to select the corresponding array element. If S = [1, 3, 3, 4], then the result of A(S) is [−1; −3; −3; −4]; ➂ Boolean index. Boolean indexes select elements in an array using a Boolean matrix (also known as a logical matrix) whose elements are true (displayed as 1) or false (displayed as 0). If f = [true; false; true; false], then A(f) will return [−1; −3]], this means that of the corresponding position of the array is true, the data is left, if it is false, data is removed, and finally returns a column vector [−1; −3] in a relative order of the original array. In the modeling process, the built-in find function of MATLAB is often used to convert a Boolean array into a numbered array. For example, the return value of find(f) is [1, 3], and find(A> −3) returns [1, 2]. For two-dimensional matrices, the indexing principle is similar. It should be noted that for the two-dimensional matrix M, M(a, b) is the element of the ath row and the bth column of M, whereas B(a,:) is a one-dimensional array of all the data of the ath row, wherein “:” means indexing all rows or columns. Using a Boolean array, such as B(f,:), indexes all the columns of the corresponding row with the corresponding value of 1 in the logical array f (see the MATLAB-related tutorial for specific use).

5.4 System Functions 5.4.1 GPU Computing Settings and Status Viewing (1) GPU computing settings Based on the innovative GPU matrix algorithm and 3D contact algorithm, MatDEM realizes high-performance discrete element numerical calculation. Currently, the program only supports NVIDIA series discrete graphics and NVIDIA Tesla GPU computing cards. The function setGPU in the model class can set the GPU state at the time of calculation. The usage of the function is shown in Table 5.7. Table 5.7 Command of GPU computing settings

Command

Description

d.mo.setGPU(‘on’);

Calculation status is set to GPU calculation

d.mo.setGPU(‘off’);

Calculation status is set to CPU calculation

d.mo.setGPU(‘auto’);

Automatically test CPU and GPU speeds, choose faster

d.mo.setGPU(‘fixed’);

Lock the current calculation state

d.mo.setGPU(‘unfixed’);

Unlock the current calculation state

5.4 System Functions

137

If MatDEM does not detect a usable discrete graphics card or GPU compute card, it will automatically turn off GPU computing. MatDEM only performs GPU optimization on the iterative calculation basic function d.mo.balance() and functions based on this, such as d.balance and d.balanceBondedModel. When performing a noniterative calculation operation, users need to turn off the GPU during the calculation; otherwise, the exception “Cannot convert from gpuArray to double” may occur and a similar error message is displayed in the message prompt box: >Position: mfs.data2D, Line: 1395 >Line: 23, C.addSurf(lSurf); >Error: The following error occurred converting from gpuArray to double: Conversion to double from gpuArray is not possible. @MatDEM2

During initial modeling, the initial GPU state settings can be fixed using the attribute GPUstatus in class object B. B.GPUstatus has four values: “off,” “on,” “auto,” and “fixed”. When the current three meanings are the same as those in the setGPU function and it is set to “fixed,” only the CPU is used for calculation until d.mo.setGPU(‘unfixed’) is encountered. Note: At present, the values in the GPU cannot take matrix substitution operation. For example, for the value matrix A and the index matrix I in the GPU, substituting the calculation A(I) may give an error. At this point, the I = gather (I) command needs to be added to transfer the data I from the GPU to the CPU. More information can be found in MATLAB’s GPU calculations. (2) View GPU usage status A batch processing file Monitor GPU status.bat is provided in the root directory of MatDEM. After double-clicking, this will monitor the GPU and CPU usage in real time. As shown in Fig. 5.12, MatDEM uses the Quadro M520 for GPU computing, which already consumes 289 MB of graphics memory. By monitoring the GPU status, it is possible to understand the memory usage of the GPU graphics card and avoid excessive use of the card that will result in graphics memory overflow and error (out of memory on device). As shown in Fig. 5.12, the Windows Task Manager can also be used to view GPU usage by selecting Performance in the Task Manager and then select NVIDIA discrete graphics to view overall GPU usage information. However, it is not possible to view how much GPU computing capacity each program uses (Fig. 5.13).

5.4.2 Definition and Operation of Functions MatDEM can run standard MATLAB functions. When modeling, a custom function can usually be used to build a variety of basic components and then complex

138

5 Post-processing and System Functions

Fig. 5.12 Monitor GPU usage status with batch processing commands

Fig. 5.13 View GPU usage with Windows Task Manager

5.4 System Functions Table 5.8 Functions of building structure objects

Table 5.9 Functions of filters

139 Function file name

Functions

makeDisc.m

Make a two-dimensional disk structure

makeColumn.m

Make a column structure

makeHob.m

Generate a hob structure

makeRing.m

Generate a two-dimensional ring for tunneling

Function file name

Functions

getColumnFilter.m

Making a cylindrical filter

applyRegionFilter.m

Filter selecting out the elements of the black area

imageRegionFilter.m

Filter selecting the black area of the black and white picture

geometric models through cutting and splicing operations. Several custom function examples are provided in the fun folder, including the following. (1) Functions for establishing various model structure objects (Table 5.8), such as functions starting with make, which return structures containing the X-, Y-, Z-coordinates of the element and the radius R information. (2) Make filters to screen out specific elements to further cut and define the model (Table 5.9). The syntax for using a custom function is f.run(‘xxx.m’,p1,p2,p3,…), where “xxx.m” is the function file name (including the suffix name.m), and p1, p2, p3, etc. are input parameters, the number of which is determined by the called function. Note that when writing a custom function, the last line needs to be end; otherwise, the program will report an error. If the function is not placed in the software root directory, the first parameter of the function name should be appended with the path name. For example, the file user_modelExample uses the makeHob.m function in the fun folder. hob=f.run('fun/makeHob.m',hobR,hobT,cutRate,ballR,Rrate);

5.4.3 Batch Processing of Code Files It should be noted that because MatDEM has a separate compiler interpreter, it is not possible to run code by entering the code file name directly on the command line, such as MATLAB. The code file abc.m can be run via the MatDEMfile(‘abc.m’) command (see specific use in TestAllCodes). For example:

140

5 Post-processing and System Functions MatDEMfile('user_L2Earthquake1.m'); MatDEMfile('user_L2Earthquake2.m'); MatDEMfile('user_L2Earthquake3.m');

5.4.4 Random Seed and Stochastic Model In numerical simulation, it is often necessary to use random numbers to generate variables with different distributions to obtain repeatable results. MatDEM provides a function for fixed random number generation settings: fs.randSeed(seed) where seed is a nonnegative integer. When the value of seed is unchanged, the random number generated each time is constant so that the reproducible simulation result can be obtained. Therefore, before modeling starts, the randSeed function is usually called to determine the seed value of the random number. If the value of the seed is changed, a new random packing model is created.

5.4.5 Timing Functions MatDEM’s build class provides timing functions tic and toc, which are different from tic and toc in MATLAB and do not conflict. Running the d.tic and d.toc functions will update the relevant parameters in d.SET. The meaning of the parameters is as follows: totalCircle

Circle

Time0/min

Time/min

Timecircle

Total number of cycles

Current number of cycles

Initial moment

Current moment

Current timing number

Note The initial and current moments refer to the number of minutes that have elapsed from the first year of the AD to the current moment

The d.tic (totalCircle) command is run to record the starting time of the numerical simulation, that is, time0. The totalCircle is usually the same as the totalCircle in the loop calculation. Thus, after each loop is finished, d.toc() can be used to obtain the current time, after which the program running time is calculated. At the same time, the command displays the calculation step number and calculation time in the message prompt box. Note that the new prompt will only be displayed when the last reminder time has exceeded 12 s (see step 3 of the sample files). The d.recordCalHour(timeName) function is usually seen at the end of the file before saving the data. This saves the time from the completion of the modeling to the current time. The input parameter timeName is the saved time parameter name. The relevant data are recorded in the d.TAG.recordHour parameter, and the unit of time is hour (h). For example, in the file BoxSlope2, there are

5.4 System Functions

141

d.recordCalHour('BoxSlope2Finish');

This records the time after the second step of modeling is completed in d.TAG.recordHour: In addition, if there are other timing requirements, the MATLAB functions tic and toc can be used for custom timing, and the relevant custom functions can be placed in d.SET.

5.5 Modeling with System Underlying Functions To facilitate quick modeling, MatDEM provides the obj_Box simulation box class. This highly encapsulates the process of discrete element pack modeling, including automatic generation of simulation boxes, automatic accumulation, and compaction. In the first step of the sample code, the object B of the class obj_Box is usually used to build the initial model. The object d of the class build is generated, and the second and third steps of modeling and calculation are based on the object d, respectively. In fact, MatDEM’s modeling does not depend on the obj_Box class. This section will demonstrate how to use the system’s underlying functions to perform numerical simulations of the two-ball collision process. This underlying modeling method will also be applied in the SoilCrackNew example.

5.5.1 Underlying Modeling of the Two-Ball Collision Process This section introduces the two-ball collision example TwoBalls. This example shows how to define elements one by one and build a numerical model and is divided into the following three steps. 1. Build structure objects and define materials diameter=20; visRate=0;%Figure 5.5-1 r=diameter/2;%ball radius d=build(); d.name='TwoBalls';

First, define the basic parameters of the simulation and establish the object d of the class build.

142

5 Post-processing and System Functions %-----define struct data of model and boundary----moObj.X=[0;0];moObj.Y=[0;0];moObj.Z=diameter*[1;3]; moObj.R=r*[1;1]; boObj.X=[0;0];boObj.Y=[0;0];boObj.Z=diameter*[0;4]; boObj.R=r*[1;1];

Unlike the conventional method where the obj_Box class is used to pack modeling, the underlying modeling needs to set the initial position of the element. Therefore, the code above establishes the structure moObj of the active element and the structure boObj of the fixed element (boundary element). The function fs.combineObj can be used to add other structures to moObj and boObj. %-----define material----ballMat=material('ball'); ballMat.setMaterial(7e6,0.15,1.5e5,1e6,1,diameter,1500); d.addMaterial(ballMat);

Finally, the properties of the material are set directly using a conventional method. 2. Define basic parameters and materials of elements The second part of the code primarily initializes the parameters in d. %-----initialize d----d.aX=[moObj.X;boObj.X;boObj.X(end)];%add a virtual element d.aY=[moObj.Y;boObj.Y;boObj.Y(end)]; d.aZ=[moObj.Z;boObj.Z;boObj.Z(end)]; d.aR=[moObj.R;boObj.R;boObj.R(end)/4];

First, the element information of moObj and boObj is merged and a dummy element added at the end (for details on dummy elements, see Sect. 2.3.1). This is then assigned to d. Among these, boObj.X (end) is the X-coordinate of the last element of boObj while the rest is the same. Therefore, the dummy element coincides with the last element of the boundary and its radius is one-fourth of this element. The next step is to set the damping coefficient rate (vRate), the number of all elements (aNum), the number of active elements (mNum), the element material number (aMatId), and the gravitational acceleration (g).

5.5 Modeling with System Underlying Functions

143

d.vRate=visRate;%rate of viscosity(0-1) d.aNum=length(d.aR); d.mNum=length(moObj.R); d.aMatId=ones(size(d.aR))*ballMat.Id; d.g=9.8;%gravity acceleration d.setBuild();

Finally, based on this information, basic parameters in the object d are set, such as modeling time, initial size, initial boundary, and element material through the function setBuild. 3. Define boundaries and build calculation models %-----define boundary groups----d.GROUP.lefB=[];d.GROUP.rigB=[]; d.GROUP.froB=[];d.GROUP.bacB=[]; d.GROUP.botB=3;d.GROUP.topB=4; %-----initialize d.mo----d.setModel(); d.mo.isHeat=1;

The third part of the code first defines the boundary element, where the third element is the bottom boundary, the fourth element is the top boundary, and the remaining boundaries are empty. d.setModel() generates the calculation module d.mo according to the above settings; then, the last line declares that the heat of the system will be counted in the iterative calculation. In other examples of the B.buildInitialModel function, the simulation box is built according to the process above to achieve automatic modeling. Using the code above, the discrete element model shown in Fig. 5.14a is constructed, which includes two active elements (middle) and two fixed elements (up and down). The model generated by d.setModel is cemented, that is, the connections of the elements in contact with each other are cemented connections. At the same time, when the second part defines the element coordinates, element 1 and element 3, and element 2 and element 4 are just in contact. Therefore, under the action of gravity, element 1 and element 2 will move downward. Iterative calculations are implemented with the following code and the simulation results are then displayed:

144

5 Post-processing and System Functions

Fig. 5.14 Numerical simulation results of a two-ball collision process

d.balance(1,800); d.showB=2; d.show();

5.5.2 Use Graphs to Analyze Collision Processes This example simulates the process in which element 2 repeatedly hits element 1 under gravity and bounces. Figure 5.14b is the boundary force variation curve, where the curve Bottom represents the force the bottom element is subjected to in the Z-direction. Figure 5.14c is the system energy curve, which primarily includes gravitational potential energy, elastic potential energy, and kinetic energy. Figure 5.14a shows the element positions at times A, B, C, and D in the graph. In the figure, the two elements numbered 3 and 4 are fixed, and the element 1 and element 2 are, respectively, cemented with element 3 and element 4 and are in an equilibrium position. Under the action of gravity, element 1 moves downward and begins to make a simple harmonic vibration. As shown in Fig. 5.14b, the first period of the lower boundary is the sinusoidal shape of the simple harmonic vibration. Element 2 moves downward for a short distance. At time A, the cementation between element 2 and element 4 breaks; element 2 then performs free-fall motion and accelerates continuously, the gravitational potential energy of the system decreases continuously, the kinetic energy continues to increase (Fig. 5.14c), and element 2 makes contact with the lower element 1 at time B. At time C, element 2 reaches the lowest point, the system kinetic energy is close to 0, the gravitational potential energy is the smallest,

5.5 Modeling with System Underlying Functions

145

the elastic potential energy is the largest, and the element begins to rebound. At approximately time D, element 1 and element 2 are no longer in contact, element 2 continues to move upward, and element 1 performs a simple harmonic vibration under the action of a spring force. The force curve of the bottom boundary shows that the vibration amplitude of element 1 increases and the tensile force appears, indicating that element 1 has obtained part of the kinetic energy of element 2 during the collision. The second collision cycle is then entered, where time E is similar to time B and element 2 falls and comes into contact with element 1. Element 1 acquires more kinetic energy and breaks the bond with the bottom element when rebounding at time F. Therefore, the Bottom curve after time F only has a pressure effect. Element 2 continues to move upward and reaches its highest point (maximum gravitational potential energy) at time G. The overall state of the discrete element system can be effectively judged by the boundary force variation curve and the system energy variation curve. At the end of each step of the numerical simulation, the d.show() command is normally used to view these curves and determine whether the discrete element model state and numerical simulation results meet the requirements.

Chapter 6

Basic Application of Geotechnical Engineering

In this chapter, we will introduce three base instances:the interaction of pile and soil, tunnel simulation, and the TBM (Tunnel boring machine) cutter rock breaking numerical simulation model. These instances are all including three regular steps of MatDEM modeling and numerical simulations: ➀ Gravity packing operations to build stratum or blocks; ➁ building model by cutting the stratum, creating or importing the structure defined by users, setting materials and balancing the model; ➂ Set the load and iterative calculation. The three examples from easy to difficult introduce the basic steps of MatDEM discrete element modeling.

6.1 Pile–Soil Interaction The process of compressing and pulling out a pile involves large deformation, failure, and dynamic evolution. Discrete element numerical simulation can effectively simulate this process and provide reference for research and design. MatDEM provides the sample code BoxPile. It demonstrates how to build a simple model of pile–soil interaction, based on which users can build more complex models.

6.1.1 Packing Model of Particles In BoxPile1, the original stratigraphic packing model was established (see Sect. 3.1 for a description of the packing model). Firstly, we need to construct object B that simulates the box class obj_Box and set some parameters, then build the initial model:

© The Author(s), under exclusive license to Springer Nature Singapore Pte Ltd. 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9_6

147

148

6 Basic Application of Geotechnical Engineering B=obj_Box; B.name='BoxPile'; B.GPUstatus='auto'; B.ballR=0.2; B.distriRate=0.25; B.isClump=0; B.isSample=1; B.isShear=0; B.sampleW=20;B.sampleL=0;B.sampleH=20; B.BexpandRate=4;B.PexpandRate=0; B.type='topPlaten';B.setType(); B.buildInitialModel();

The parameter in the model is based on the SI standard. For example, the element of length is meters (m), and the element of density is kilograms per cubic meter (kg/m3 ). In the above code, a two-dimensional soil layer model of 20 m × 20 m (sampleW × sampleH) is established, and extends the model boundary outward by 4 element, to prevent the sample element from leaking. Since sampleL is set to 0, the Y coordinate of all elements in the model is 0, which is a 2D model. See the Sect. 3.1 for details. At the same time, a top pressure plate topPlaten is added via the B.type = ’topPlaten’ command, which is used to compact the packing sample in the first step. In addition, some other parameters can be set, such as isShear (set whether to consider shear force when simulation), isClump (set whether a number of element are combined to form a clump in the simulation), isSample (set whether the initial sample element is generated), and so on. The meanings of these parameters are introduced in help files and here is just a brief introduction. After the initial geometric model is generated, we can adjust the radius of the model element ourselves, then perform gravity deposition and compact the model twice: d=B.d; %Change the element size distribution here,e.g.:d.mo.aR=d.aR*0.9; d.mo.aR=d.aR; B.gravitySediment(); d.mo.aMUp(:)=0; B.compactSample(2); %mfs.reduceGravity(d,1);%reduce the gravity if necessary.

In order to make the elements stack more compact, the coefficient of friction (aMUp) of all element is set 0. If you need to obtain a sample without gravity, the gravity must be gradually reduced by the modeling function mfs.reduceGravity, as described in the Sect. 3.1.1.

6.1 Pile–Soil Interaction

149

Through the above steps, you can build an initial geometric model, and then you can save the data and post-process the display. Before saving, first turn off the GPU calculation to transfer all the data to the CPU, which can avoid errors when opening data in a computer without a GPU. Then run d.clearData(1) to compress the data. After saving the data, run d.calculateData() to retrieve the complete data and use it for post-processing display. %------------return and save result-------------d.status.dispEnergy();%display the energy of the model d.mo.setGPU('off'); d.clearData(1);%clear dependent data d.recordCalHour('BoxPile1Finish'); save(['TempModel/' B.name '1.mat'],'B','d'); save(['TempModel/' B.name '1R' num2str(B.ballR)'-distri'num2str(B. distriRate)'aNum' num2str(d.aNum)'.mat']); d.calculateData(); d.show('aR');

Through the above codes, a two-dimensional layer packing model can be obtained, as shown in Fig. 6.1. It can be seen from the figure that there is a distinct force chain in the model, which is an important phenomenon of the element accumulation model, and is ubiquitous in the granular material. For details, please refer to the relevant data. Fig. 6.1 The initial StressZZ stress field of 2D formation model

150

6 Basic Application of Geotechnical Engineering

6.1.2 Build a Pile-Soil Interaction Model (1) Use a filter to cutting the model The first step is to simulate the accumulation process of the real world and construct an initial packing model. In the second step, the model is cut and material is assigned. In BoxPile2, you first need to load and initialize the data you get in the first step: load('TempModel/BoxPile1.mat'); B.setUIoutput(); d=B.d; d.mo.setGPU('off'); d.calculateData(); d.getModel();

Further, remove the top pressure plate and the top of original formation with the filter topLayerFilter: mZ=d.mo.aZ(1:d.mNum); topLayerFilter=mZ > max(mZ)*0.7; d.delElement(find(topLayerFilter));

The reason of the operation is that the top pressure plate is only used to compact the sample in the first step and can be removed later; The original layer is too close to the top boundary (Fig. 6.1). Therefore, it is necessary to cut off enough space for the pile-drawing process and obtain a flat surface. In MatDEM, the key to deleting a specified element or performing other operations is to obtain the corresponding element id. Usually, first obtain a Boolean matrix that satisfies certain conditions, that is, a filter matrix (such as topLayerFilter). Then, MATLAB’s own function find is called, and the element with the value of 1 (true) in the Boolean matrix is traversed to obtain the required element corresponding number. You can see Sect. 5.3 for definition and use of filters. (2) Build an array of materials After cutting off the top of the layer and the top pressure plate, you need to import and set the material:

6.1 Pile–Soil Interaction

151

matTxt=load('Mats\soil1.txt'); Mats{1,1}=material('Soil1',matTxt,B.ballR); Mats{1,1}.Id=1; matTxt2=load('Mats\StrongRock.txt'); Mats{2,1}=material('StrongRock',matTxt2,B.ballR); Mats{2,1}.Id=2; d.Mats=Mats; d.setGroupMat('sample','Soil1'); d.groupMat2Model({'sample'},1);

In the above code, two materials were imported, Soil1 and StrongRock. The former is the stratum material and the latter is the pile material. At this point, since there is only a sample group in the model except the boundary, it is only necessary to set the material of the sample group and apply it to the model. The material of the sample group is declared as Soil1 by the d.setGroupMat(‘sample’, ‘Soil1’) command. And further assign the material to the element through the d.groupMat2Model function. The first input parameter of the function groupMat2Model is an array of element, and the second parameter is the default material Id. This function can be used to set the corresponding group material in the element array as the material of the previous statement, and the rest group is set as the default material. Run the command groupMat2Model({‘sample’}, 1), the material of the sample group will be set, and the material of the remaining elements will be set to material 1. (3) Use the structure object to build the pile. Subsequently, the structure object of the pile needs to be built and added to the existing formation model: pileW=0.8;pileL=0;pileH=8;ballR=B.ballR; Rrate=0.7;drivingDis=6; sampleId=d.GROUP.sample; sampleTop=max(d.mo.aZ(sampleId)+d.mo.aR(sampleId)); pile1=mfs.denseModel(0.8,@mfs.makeBox,pileW,pileL,pileH,ballR); pile1.Y(:)=0;

In the process of building a pile model, we use the function mfs.denseModel and passed the handle @mfs.makeBox as an input parameter, The return value of this function is a structure object consisting of the X, Y, Z coordinates of several elements and their radius R, which has defined a rectangle with a width of 0.8 m and a height of 8 m. There is a certain amount of overlap between the constituent elements of the rectangle (Fig. 6.2). The amount is defined by the first input parameter Rrate (here 0.8), which is the ratio of the distance from the center of the adjacent element to its diameter. The smaller the Rrate is, the larger the overlap is, the surface of the pile will be smoother, but the amount of calculation will increase accordingly. If we

152

6 Basic Application of Geotechnical Engineering

Fig. 6.2 The second step code established role of piles and soil model (StressZZ)

use mfs.makeBox directly, it will build a rectangular model of which elements are in precise contact with each other (no overlap). Any user can also write codes or functions to build arbitrary geometry, see Sect. 5.5 for details on custom functions. Since in the sample code we have built a 2D pile, we need to make the Y-coordinate of all the elements of this pile 0, which is pile1.Y(:) = 0. (4) Put the pile into the stratum Then put the structure object of the above pile into the model and the mechanical properties of the material StrongRock are given. The specific operations are as follows: pileId1=d.addElement('StrongRock',pile1); d.addGroup('Pile1',pileId1); d.setClump('Pile1'); d.moveGroup('Pile1',(B.sampleW-pileW)/2,0,sampleTop-drivingDis); d.minusGroup('sample','Pile1',0.4); d.addFixId('X',d.GROUP.Pile1);

Firstly, add an element to the model via the function d.addElement. The first parameter in the function is the material name, and the second is the structure object to be added. The return value of the function, pileId1, is the element number after the structure object is added to the model, and declares the pile element as a clump by the function setClump. The reason is that in the previous part of the code, the pile structure object is generated by the function denseModel, and there is a certain amount of overlap between the pile elements, so that the surface of the pile is smooth. When the elements overlap, there will be a huge interaction force. Once the equilibrium iteration model may “explode,” the pile Pile1 is declared as a clump here. After this operation, MatDEM records the amount of overlap between the elements at this time

6.1 Pile–Soil Interaction

153

and records them in the d.mo.nClump matrix. In the iterative calculation, the amount of overlap is subtracted when calculating the interaction force between the elements, and guarantee the force balance of the model. About the character of clump you can see Chap. 2 for details. By default, the bottom left corner of the pile generated by the function denseModel is at the origin, then the pile can be moved to the specified position by the function d.moveGroup. In the sample code, the amount of movement of the pile in the X-direction is (B.sampleW-pileW)/2, which is the difference between the width of the model and the width of the pile. Using this command we can move the pile to the middle of the model. Because this example is a two-dimensional model, the displacement in the Y-direction is 0; and in the Z-direction is the sampleTop-drivingDis, where drivingDis is the depth of the pile to be driven into the stratum. After moving the pile into the soil layer, the pile element overlaps with the stratum element. At this time, the stratum element of the overlapping part needs to be removed by the function d.minusGroup. The first and second parameters of this command are sample and Pile1, that is, the sample is subtracted from Pile1, and the third parameter defines the radius factor Rrate of the Pile1 element. Rrate defines the factor by which the radius of the Pile1 element is to be multiplied. When it is 0.4, the element radius of Pile1 is reduced to 40% of the original, and the overlap is judged with the sample, and the overlapping part of the sample group is removed. By defining Rrate, you can adjust the amount of deleted elements, Rrate must be greater than 0, and not too small (such as less than 0.2). For this example, the modeling process is equivalent to dig the pile hole and then place the pile into the hole. Therefore, when the overlapping elements are removed, sufficient contact between the pile and the soil is not achieved. At this point, there is still a gap between the pile and the soil, so the model needs to be rebalanced. The general idea is to remove the connection between the stratum elements around the pile so that they fill the gap under the action of gravity; after the model is fully balanced, according to the requirements remove the cementation between the stratum element around the pile. They are filled with gaps under the force of gravity; after the model is fully balanced, the formation is re-bonded as required. The pile may tilt during the filling process. Therefore, by confining the X-coordinate of the pile by d.addFixed, the pile remains erected while the pile can still move in the Z-direction. The balanced iteration will be done after the second pile has been added. (5) Add the second pile Follow the steps above to add a second pile to the model:

154

6 Basic Application of Geotechnical Engineering pile2=mfs.denseModel(0.5,@mfs.makeBox,pileH,pileL,pileW,ballR); pile2.Y(:)=0; pile2.X=pile2.X+B.sampleW-pileH/2;pile2.Z=pile2.Z+B.sampleW/2; pileId2=d.addElement('StrongRock',pile2,'wall'); d.addGroup('Pile2',pileId2); d.setClump('Pile2'); d.moveGroup('Pile2',1,0,2); d.rotateGroup('Pile2','XZ',30); d.minusGroup('sample','Pile2',0.5); %d.removeGroupForce(d.GROUP.Pile2,d.GROUP.rigB);

The idea of building the second pile is similar to that of the first pile, but after using the function d.moveGroup to translate the pile, we use the function d.rotateGroup to rotate it so that the pile Pile2 intersects the right boundary rigB. At the same time, when d.addElement is called, the third parameter “wall” is entered. We have declared that the type of element to be added is a fixed wall. If Pile is not declared as “wall” (wall element), since the pile Pile2 intersects the right boundary rigB, the interaction between the two needs to be removed by the function d.removeGroupForce. The code can be commented out by the “%” symbol. Under normal circumstance, the verticality of the pile should meet the construction requirements, and when modeling also avoids intersecting the model with the boundary as much as possible. The current sample code is only used to demonstrate the functions d.rotateGroup, d.addElement, and d.removeGroupForce. After placing the pile into the stratum, the model needs to be rebalanced. The general idea has been introduced before d.mo.bFilter(:)=false; d.mo.zeroBalance(); d.resetStatus(); d.mo.setGPU('auto'); d.balance('Standard',8); d.connectGroup('sample'); d.connectGroup('sample','Pile1'); d.mo.zeroBalance(); d.balance('Standard',2);

In the above code, the command d.connectGroup(‘sample’, ‘Pile1’) is used to connect the two groups of pile and stratum, which is equivalent to cementing the consolidated concrete with the foundation soil during the construction of the bored pile. Then, the modeling process of the pile–soil interaction has been completed, and the data is saved and post-processed. The model obtained in the second step is shown in Fig. 6.2. One pile is vertically buried in the ground layer, while the other pile is lying at an angle of 30° to the horizontal plane and intersects with the right boundary. The pile has been fixed in the simulation. We can see that since the Rrate

6.1 Pile–Soil Interaction

155

of the d.minusGroup is 0.4, the number of soil layers deleted is a few. When the standard balance is reached, part of the surface soil particles leaps due to the large overlap with the pile (Fig. 6.2). At this moment, you can view the speed field of the model through the d.show(‘mV’) command, and use the d.show() command to view the various force and energy curves of the discrete element system. By analyzing these field maps and curves, we know that the system energy is not balanced, and it is still necessary to continue the equilibrium iterative calculation to reduce the kinetic energy in the system. See Sect. 3.5 for specific viewing and analysis methods, or refer to Sect. 7.2.

6.1.3 Numerical Simulation of the Pile Pulling Process (1) Initialization and load setting In BoxPile3, load the data and initialize the model first load('TempModel/BoxPile2.mat'); B.setUIoutput(); d=B.d; d.calculateData(); d.mo.setGPU('off'); d.getModel(); d.status=modelStatus(d);

After that we should carry on some necessary settings before the pulling operation d.mo.bFilter(:)=0; d.mo.isHeat=1; d.mo.setGPU('auto'); d.setStandarddT(); pile1Id=d.GROUP.Pile1; pile1Z=d.mo.aZ(pile1Id); topPileId=pile1Id(pile1Z > max(pile1Z)-B.ballR*0.1); d.addGroup('topPile',topPileId); d.addFixId('Z',d.GROUP.topPile);

In the real world, when we are compressing or pulling out a pile, the force acts on the top of the pile. Therefore, in the above code, the number of the top part of the pile Pile1 is screened out and declared as the group topPile. Further, it is convenient to apply a force to the topPile to simulate the pile-compressing or pile-pulling process. At the same time, the process of stress wave propagation in the pile can also be effectively simulated.

156

6 Basic Application of Geotechnical Engineering

In this step, you also need to lock the Z-coordinate of the topPile group by using the d.addFixId command. This is because during the pile-compressing or pile-pushing process, after each loading, the pile will be subjected to the reaction force or gravity of the formation element. If the degree of freedom of the pile-top element is not locked, the reaction force or gravity generated will cause the pile. The body produces rebound or fallback, affecting the simulation results. To simulate the process of rebounding the pile, delete the command d.addFixId(‘Z’, d.GROUP.topPile). (2) Iterative calculation totalCircle=20; stepNum=100; dis=1; dDis=dis/totalCircle/stepNum; d.tic(totalCircle*stepNum); fName=['data/step/' B.name num2str(B.ballR)'-' num2str (B.distriRate) 'loopNum']; save([fName '0.mat']);

In the iterative calculation, the process of pulling 1 m from the pile is divided into 20 steps (totalCircle), and each step is divided into 100 small steps (stepNum). As described in Chap. 4, increasing the stepNum can improve the accuracy of the simulation results when the total number of calculation is the same. In the actual simulation, it is necessary to increase the stepNum (such as 1000 or more), and the pulling process is slightly divided into smaller displacement steps dDis. In each balance step, the pile will be the pull up for a dDis, and if dDis is too large, the accuracy of the simulation results will be difficult to meet the requirements. for i=1:totalCircle for j=1:stepNum d.toc(); d.moveGroup('topPile',0,0,dDis); d.balance('Standard',0.01); end d.clearData(1); save([fName num2str(i)'.mat']); d.calculateData(); end

In the balance calculation process, the form of the applied load includes the stress load, the displacement load, and a mixture of the two. For example, the application of a stress load can be achieved by a pressure plate (a specific physical force is applied to an element of the pressure plate) and the displacement load can be realized by moving

6.1 Pile–Soil Interaction

(a) Initial stage

157

(b) Near end stage

Fig. 6.3 Numerical simulation results (StressZZ stress field)

a specific group. In the above code, we use the function d.moveGroup. to simulate the process of pile pulling. For every dDis distance, 0.01 times of the Standard Balance operation is performed (d.balance(‘Standard’, 0.01)), because the Z-coordinate of the topPile is locked, the elements below the pile top moves upward under the action of the pulling force. The pile further interacts with the soil around the pile, thus the simulation of the interaction between the pile and the soil around is realized. During the simulation, the data file for each step is continuously saved by the command. After the numerical simulation is completed, the GIF animation of the pulling process can be generated by post-processing or makeGIF code. The results obtained in the third step are shown in Fig. 6.3: Pile1 was pulled up a certain distance, and there was a clear gap between the pile end and the stratum, and Pile2 was always fixed in the simulation, because the elements of it was declared to be fixed in the second step. From the figure we can see that due to the stepwise displacement of the pile top, when the pile pulling speed is very fast, obvious stress waves appear in the pile. BoxPile is one of the simple examples in MatDEM. It mainly shows how to create a structure object with simple geometry through a custom function and add it to the model. At the same time, the examples include the knowledge that have been explained in the basic chapters, such as model packed, filter using, importing, and setting materials, and locking element degrees of freedom. Based on these operations, more complex models can be built based on actual needs.

6.2 Tunnel Modeling For this section, we take the two-dimensional numerical model as an example to explain the establishment of the tunnel model (BoxTunnel). The basic idea of building a tunnel model is to first dig a tunnel with a certain size in the stratum, then build a

158

6 Basic Application of Geotechnical Engineering

tunnel lining model matching the tunnel, then put the lining into the dug tunnel and compacted the soil layer, so that the soil layer is in close contact with the lining, and finally apply pressure on the surface to simulate the real working conditions.

6.2.1 Packing Model of Particles Firstly, build a packing model:

B.name='BoxTunnel'; B.ballR=0.2; B.distriRate=0.2; B.sampleW=50; B.sampleL=0; B.sampleH=50; B.type='topPlaten'; B.setType(); B.buildInitialModel();

We build the model named BoxTunnel, the width B.sampleW and the height B.sampleH are both 50 m, the element average radius B.ballR is 0.2 m, and the element radius dispersion coefficient B.distriRate is 0.2; B.type = ’topPlaten’ declares that the top pressure plate will be generated to compact the model, and the initial packing model will be created by the B.buildInitialModel command. After that, gravity deposition and compaction operations are required to simulate the natural soil layer: B.gravitySediment(); B.compactSample(6);

Because the underground tunnel excavation is to be simulated, the soil is in a tightly compacted state, and compaction is performed six times with B.compactSample(6) to compact the soil layer, and finally the initial modeling data is saved (Fig. 6.4).

6.2.2 Build a Tunnel Model (1) Material set First load the results of the first step and initialize the data, then import the model material:

6.2 Tunnel Modeling

159

Fig. 6.4 Initial formation model

matTxt=load('Mats\StrongRock.txt'); Mats{1,1}=material('StrongRock',matTxt,B.ballR); Mats{1,1}.Id=1; d.Mats=Mats; d.groupMat2Model({'sample'},1);

Use the above code to import the material StrongRock and set its material id to 1. Apply it to the model via the d.groupMat2Model command. Because sometimes there are loads on the top part of the ground when excavating tunnels in the real world, such as buildings in the top part of urban subway tunnels, in order to simulate this effect, we can apply an equivalent load in the numerical simulation:

Use the command B.SET.stressZZ = 10e6 to preset the pressure of 10 MPa. To limit the movement direction of the pressure plate, use the B.setPlatenFixId function to limit the degree of freedom of the board. It only moves in the direction perpendicular to the plane of the board; after initializing the data in d.status, use the fs.setPlatenStress function to apply pressure to the model according to the preset pressure, specifically by changing the body force of the element (d.mo.mGZ) to achieve the application of pressure, during which the program looks for elements within a certain distance of the platen from the platen, and uses the coordinate range

160

6 Basic Application of Geotechnical Engineering

of these elements to determine the element on the platen where stress is to be applied (see Sect. 4.2.2 for details). (2) The mining tunnel First, you need to mine a tunnel in the packing model, use the filter to select and delete the tunnel element: sampleId=d.getGroupId('sample'); sX=d.mo.aX(sampleId);sY=d.mo.aY(sampleId);sZ=d.mo.aZ(sampleId); dipD=0;dipA=90;radius=4;height=30; mX=d.mo.aX(1:d.mNum); mY=d.mo.aY(1:d.mNum); mZ=d.mo.aZ(1:d.mNum); mR=d.mo.aR(1:d.mNum); columnFilter=f.run('fun/getColumnFilter.m',sX,sY,sZ,dipD,dipA, radius,height); d.addGroup('Tunnel',find(columnFilter)); tunnelId=d.getGroupId('Tunnel'); d.delElement(tunnelId);

In the code, sX, sY, and sZ are the X-, Y-, and Z-coordinates of the stacked element in the model, dipD is the preset tunnel inclination, dipA is the tunnel inclination (used to establish the three-dimensional tunnel), radius is the tunnel radius, and height is the tunnel height. Through these position parameters, tunnels of any shape or direction can be made in space. Line 8 of the code use the getColumnFilter.m function (cylinder filter) to filter out a cylindrical region filter columnFilter with a radius of 4 m and a height of 30 m. Since this model is a two-dimensional model, sY is 0, and finally get a circular filter on the 2D model. Next, the element corresponding to the tunnel filter is defined as a tunnel group, and the d.addGroup(‘Tunnel’, find(columnFilter)) command is used, where the find function is used to extract the number of the tunnel element. Finally, delete the element of the tunnel group with the d.delElement(‘TunnelId’) command. Through the above operation, the tunnel is dug in the middle of the packing model (Fig. 6.5). (3) Establish tunnel structure object In order to simulate the real-world construction process, the tunnel lining needs to be added after the tunnel is excavated. Since this example is a two-dimensional model, the tunnel lining is a circular ring and a tubular lining is required in the three-dimensional model (see Sect. 10.3 for details). The artificial tunnel lining is a relatively homogeneous radial structure. In order to make the simulated lining have better isotropic, a custom makeRing function (see the software fun folder for details) is used to build a multi-layer ring. The basic idea is to first create an inner ring, then enlarge the radius of the ring and the radius of the element appropriately. After a certain angle of rotation, it can be spliced on the first ring. At this time, all the

6.2 Tunnel Modeling

161

Fig. 6.5 The excavated tunnel

elements must be guaranteed. The elements in contact are spliced to each other. It is mathematically calculated that the second layer of the ring element has a unique element size (r2) that satisfies the above requirements: ⎧  ⎪ ⎪ t = R12 − r12 ⎪ ⎨ ⎪ ⎪ ⎪ ⎩ r2 =

(t R1 /r1 + r1 ) +



2R1 t + R12

(6.2.1)

R12 /r12 − 1

R1 is the radius of the inner ring; r1 is the radius of the element that makes up the inner ring. The process of using the makeRing function to create a multi-layer ring structure object in a program is as follows: innerR=4;layerNum=3;minBallR=0.16;Rrate=0.8; ringObj=f.run('fun/makeRing.m',innerR,layerNum,minBallR,Rrate); ringObj=mfs.rotate(ringObj,'YZ',90);%rotate the group along XZ plane

The first parameter of the code is the input parameter of the makeRing function. innerR = 4 indicates that the inner diameter of the ring is 4 m, layerNum = 3 indicates that the ring has 3 layers, and minBallR = 0.16 indicates that the inner radius of the inner ring is 0.16 m. Rrate = 0.8 indicates that the element has 20% overlap. In the second line, ringObj, the lining structure object (Fig. 6.6a), is obtained by calling the makeRing function with f.run command. After the ring Obj is established, it is in the XY-plane, but the tunnel model is in the XZ-plane. At this time, the ringObj is rotated

162

6 Basic Application of Geotechnical Engineering

(a) Multilayer ring model

(b) Final tunnel model

Fig. 6.6 Modeling of a tunnel

to the XZ-plane (rotating the structure object instead of the rotation group) using the mfs.rotate(ringObj, ‘YZ’, 90) function. Note that in the 2D model, the Y-coordinate of all elements must be 0. When importing a custom structure object, check to see if the Y-coordinate of the element is 0, or set its coordinate value by ringObj.Y(:) = 0. (4) Put the tunnel lining into the ground ringId=d.addElement(1,ringObj); d.addGroup('ring',ringId);%add a new group d.setClump('ring'); d.moveGroup('ring',(max(mX)+min(mX))/2,0,(max(mZ)+min(mZ))/2); d.minusGroup('sample','ring',0.4);%remove overlap elements from sample d.breakGroup();%break the elements connection in a group B.gravitySediment(0.5);

Add element of the ringObj to the model by using the d.addElement(1, ringObj) command, and set the added element to a group called Ring by using d.addGroup(‘ring’, ringId); when setting the structure object there is overlap between the two element, and in order to prevent the model from exploding because of too much stress, you need to use the setClump (‘ring’) function to set the ring group as clump elements; the center of this object is at the origin of the coordinate system; use the d.moveGroup function to move the ring group to the tunnel of the excavation; since the tunnel and the ring element may overlap, the group subtraction operation is implemented by the d.minusGroup command. The first input parameter is sample, and the second input parameter is ring. At this point, the first object is subtracted

6.2 Tunnel Modeling

163

from the second object. The third input parameter controls how many element are deleted at the contact. The larger the input parameter is, the larger the deleted area is. In the real world, tunnels and linings are in close contact due to soil pressure. After placing the ring into the tunnel, the two model are not in close contact and need to re-deposit the soil. Disconnect the element with the d.breakGroup command (except cluster elements), followed by gravity deposition to compact the model (the standard balance command can also be used here). Finally, complete the tunnel modeling (Fig. 6.6b) and save the calculation data of the second step.

6.2.3 Loading and Numerical Simulation After the tunnel modeling is completed, the real-world load application process is further simulated, and the top pressure plate is used to apply the local stress load. (1) Numerical simulation setup

d.mo.bFilter(:)=true;%glue all bonds d.deleteConnection('boundary');%break all bonds of boundaries d.mo.zeroBalance(); d.mo.isHeat=1; d.mo.isCrack=1; fs.setPlatenStress(d,0,0,B.SET.stressZZ,B.ballR*5); d.mo.setGPU('auto'); d.balance('Standard',1);

First load the calculation data of the second step and then initialize the model. Because the element connections are all broken when the previous layer was deposited, use d.mo.bFilter(:) = true to connect all connections. The boundary and sample elements are also connected to each other, so use the d.deleteConnection function again to disconnect the two. d.mo.isHeat = 1 declares the generation of recorded heat, and d.mo.isCrack = 1 declares the generation of recorded cracks. Since the pressure of 10 MPa is applied to the model in the second step, the same pressure is applied here by the fs. setPlatenStress function, otherwise the model may explode and then the model is balanced. After the initial setting is completed, it is necessary to screen out a part of the top pressure plate to further apply pressure:

164

6 Basic Application of Geotechnical Engineering tp=d.GROUP.topPlaten; blockWidth=8; tpX=d.mo.aX(tp); tpXCenter=(max(tpX)+min(tpX))/2; blockFilter=tpX >(tpXCenter-blockWidth/2)&tpX < (tpXCenter+ blockWidth/2); blockId=tp(blockFilter); d.addGroup('block',blockId); blockForceZ=d.mo.mGZ(blockId);

The first line command obtains the element id tp of the top pressure plate; blockWidth = 8 indicates that the area of the top pressure plate has a center width of 8 m; through the following command, the elements within 4 m outside the center of the top pressure plate are screened out to establish filtering. The blockFilter;tp(blockFilter) command acquires the element id array blockId of the 8 m area in the middle of the pressure plate, and adds a new group block (Fig. 6.6) with the addGroup command; finally, the physical blockForceZ of the new block of the middle block group is obtained. When pressure is applied to the topPlaten, a downward force is actually applied to its element, corresponding to the mGZ matrix. blockForceZ is also applied to the element by the same method. (2) Iterative calculations and simulation results After completing the above settings, the interaction between the tunnel lining and the soil layer is simulated by an iterative cycle simulating the top pressure plate, and the ground stress load is increasing: totalCircle=5; for i=1:totalCircle d.mo.mGZ(blockId)=d.mo.mGZ(blockId)+blockForceZ; d.balance('Standard',1); d.clearData(1); d.mo.setGPU('off'); save([fName num2str(i)'.mat']); d.calculateData(); d.mo.setGPU(gpuStatus); d.toc(); end

In the for loop, the body force in the Z-direction of the block element is gradually increased to simulate the process of increasing ground load. After the loading simulation is completed, the simulation results can be viewed in the post-processing. Use d.show(‘StressZZ ‘) to see the normal stress of the element in the Z-direction (Fig. 6.7). It can be seen from the figure that when the pressure acts downward, the Z-direction stress concentration occurs on both sides of the tunnel ring. A very

6.2 Tunnel Modeling

165

Fig. 6.7 Stress distribution in Z-direction of the model after applying pressure

obvious force chain can also be seen in the figure, which indicates that the pressure in the soil is not uniform.

6.3 TBM Cutter Rock Breaking The full-section tunnel boring machine (TBM) has been widely used in tunnel construction due to its high degree of automation and complete cavity formation. The numerical simulation of the rock-breaking process by disc cutter has become a hot program in recent years. The simplest TBM cutter rock breaking numerical simulation model has been established in the sample code TBMcutter provided by MatDEM. Users can build the rock breaking model under specific working conditions based on the TBM cutter rock-breaking general calculation model.

6.3.1 Packing Model of Particles The original soil layer packing model is built in the TBMcutter1 code. The main modeling code is as follows:

166

6 Basic Application of Geotechnical Engineering B=obj_Box;%build a box object B.GPUstatus='auto';2 width=1.2;length=0.6;height=0.6;ballR=0.005;%width,length,height, radius distriRate=0.2;%define distribution of ball radius, isClump=0; B.ballR=ballR; B.isClump=isClump; B.distriRate=distriRate; B.sampleW=width; B.sampleL=length; B.sampleH=height; B.type='topPlaten'; B.setType(); B.buildInitialModel();

Firstly, set the GPU state to “auto,” and secondly, input part of the model parameter values to create the object B of the simulation box obj_Box, then the simulation box physical parameters were assigned. The parameter setting of the model is based on the SI standard. In the above code, a three-dimensional soil layer model of 1.2 m × 0.6 m × 0.6 m (sampleW × sampleH × sampleH) is established, and a top pressure plate (topPlaten) is generated to compact model. B.gravitySediment(); B.compactSample(2);%input is compaction time mfs.reduceGravity(d,10);

After the assignment of the model parameters, the model is subjected to gravity deposition by running the B.gravitySediment() function, and the model is compacted twice by B.compactSample(2). Run the mfs.reduceGravity(d, 10) function after deposition compaction to eliminate element gravity and finally save the initial modeling data. Figure 6.8 shows the established three-dimensional packing model. The color in the figure indicates the element radius (d.mo.aR).

6.3.2 Build a Model of TBM Cutter Rock Breaking (1) Cutting model load('TempModel/box1.mat'); d=B.d; d.mo.setGPU('off');

6.3 TBM Cutter Rock Breaking

167

Fig. 6.8 Three-dimensional packing model of particles

d.calculateData(); d.getModel();%get xyz from d.mo

This section will cut and assign the material of the stratum soil layer. In the TBMcutter2 code, the above command loads and initializes the data obtained in the first step. mZ=d.mo.aZ(1:d.mNum); topLayerFilter=mZ max(mZ)*0.5; d.delElement(find(topLayerFilter));

The Z-coordinate of all active elements in the model is obtained by the first command above and saved in the mZ matrix. The second command selects the elements whose Z-axis coordinates are located in the top half of the model box and records them in the Boolean matrix topLayerFilter. After using the find command to obtain the element number, use the d.delElement command to delete the selected element from the model, to delete the active element in the top part of the model.

168

6 Basic Application of Geotechnical Engineering

(2) Stratum grouping and material adding First, StrongRock and WeakRock materials are imported for further development of soft-strong inter-bedded rock model building: matTxt=load('Mats\StrongRock.txt'); Mats{1,1}=material('StrongRock',matTxt,B.ballR); Mats{1,1}.Id=1; matTxt2=load('Mats\WeakRock.txt'); Mats{2,1}=material('WeakRock',matTxt2,B.ballR); Mats{2,1}.Id=2; d.Mats=Mats;

For convenience, the material in this example is directly defined by the values in the Notepad file. Materials defined by this method may have large errors (such as 50%) in actual Young’s modulus and strength and set values, and material training is required to obtain a more accurate model. For material training, we will describe it in Sect. 3.3.3. The following part of the code is used for stratum grouping and material adding: dipD=90;dipA=60;strongT=0.1;weakT=0.1; weakFilter=mfs.getWeakLayerFilter(d.mo.aX,d.mo.aY,d.mo.aZ,dipD, dipA,strongT,weakT); sampleId=d.getGroupId('sample'); aWFilter=false(size(weakFilter)); aWFilter(sampleId)=true; sampleWfilter=aWFilter&weakFilter; d.addGroup('WeakLayer',find(sampleWfilter)); B.setPlatenFixId(); d.setGroupMat('WeakLayer','WeakRock'); d.groupMat2Model({'WeakLayer'},1);

The above code generates a rock block with a dip of 90° (dipD = 90), an inclination angle of 60° (dipA = 60), and a soft-strong layer thickness of 0.1 m. The weak layer element filter weakFilter in the rock formation is obtained by getWeakLayerFilter; The d.setGroupMat(‘WeakLayer’, ‘WeakRock’) command is to declare the material of the WeakLayer group as WeakRock; the next is to assign the material to the element through the d.groupMat2Model function. The first input parameter of the function groupMat2Model is an element array defining the group that material needs to be added. The second parameter is the default material. By running this command, the material of the WeakLayer group element will be set according to the previous statement, while the material of the remaining element is set to material 1.

6.3 TBM Cutter Rock Breaking

169

(3) Create and import a hob model hobR=0.216;hobT=0.1;ballR=B.ballR;Rrate=0.7;cutRate=1; hob=mfs.makehob(hobR,hobT,cutRate,ballR,Rrate); hob=mfs.rotate('YZ',hob,90); hob.X=[hob.X;(max(hob.X)+min(hob.X))/2]; hob.Y=[hob.Y;(max(hob.Y)+min(hob.Y))/2]; hob.Z=[hob.Z;(max(hob.Z)+min(hob.Z))/2]; hob.R=[hob.R;mean(hob.R)];

First, declare the geometry parameters of the hob (disc cutter): a radius of 0.216 m (hobR = 0.216), a thickness of 0.1 m (hobT = 0.1), a blade slope of 1 (cutRate = 1), and a cluster model element spacing ratio of 0.7 (Rrate = 0.7). Then, an element will be added to the center of the hob for marking the center point of the hob in the numerical simulation. Figure 6.9a shows an established hob model. hobId=d.addElement(1,hob);%mat Id,obj d.addGroup('Hob',hobId); sampleId=d.GROUP.sample; d.moveGroup('Hob',hobR,(max(d.aY(sampleId))+min(d.aY(sampleId))) /2,0);

Then, the hob structure object will be added to the model using d.addElement and material 1 will be assigned. The index array of the hob in the model is hobId. Line 2 adds the hob to the hob group via the addGroup command; Line 3 gets the number of all sample element; Line 4 later moves the Hob group to the desired position (Fig. 6.9b). Then start balancing the model: d.setClump('hob'); d.removeGroupForce(d.GROUP.hob,[d.GROUP.topB;d.GROUP.rigB]); d.mo.isFix=1; d.mo.FixXId=[d.mo.FixXId;hobId]; d.mo.FixYId=[d.mo.FixYId;hobId]; d.mo.zeroBalance(); d.balanceBondedModel0(); d.mo.bFilter(:)=0; d.balance(‘Standard’); d.balanceBondedModel();

d.setClump(‘Hob’) sets the hob as an elastic clump;then, uses the d.removeGroupForce function to remove the force between the hob and the left and

170

6 Basic Application of Geotechnical Engineering

(a)Disc cutter model (hob)

(b) Numerical simulation of rock breaking with disc cutter (hob) Fig. 6.9 Create and import hob model

6.3 TBM Cutter Rock Breaking

171

right boundary; d.mo.FixXId defines the element that needs to lock the X-direction degrees of freedom (The d.addFixId function can also be used here); then the d.mo. zeroBalance is performed, and the inter-element forces are recalculated; through the following function cementing and balancing model. The numerical model of the rock-breaking process with the hob is shown in Fig. 6.9b.

6.3.3 Numerical Simulation Process of Rock Breaking with Hob

d.mo.mVX(:)=0;d.mo.mVY(:)=0;d.mo.mVZ(:)=0; d.status=modelStatus(d); d.mo.isHeat=1; visRate=0.00001; d.mo.mVis=d.mo.mVis*visRate; d.setStandarddT();

In the TBMcutter3 code, first set the initial state of the numerical model, in the first line of code, the speed of the X-, Y-, and Z-directions of all the element is 0, and initialize the model with the second line of code; The heat change of the model is recorded during the process by the third line of code; lines 4 and 5 set the damping coefficient (mVis) of the active element to a minimum value; and line 6 sets the time step to a standard value. totalCircle=40;stepNum=100;balanceNum=40; disp(['Total real time is ' num2str(d.mo.dT*totalCircle* stepNum* balanceNum)]); fName=['data/step/TBM' num2str(B.ballR)'-' num2str(B. distriRate) 'loopNum']; sampleX=d.mo.aX(d.GROUP.sample); dis=(max(sampleX)-min(sampleX))-hobR*2; Dis=[1,0,-0.1]*dis; dDis=Dis/(totalCircle*stepNum); dDis_L=sqrt(sum(dDis.^2)); dAngle=dDis_L/hobR*180/pi; d.mo.bFilter(:)=true;%bond all elements d.mo.zeroBalance(); save([fName '0.mat']);%return;

The numerical simulation process is divided into 40 steps (totalCircle = 40) and each step is broken down again into 100 small steps (stepNum = 100). The hob is

172

6 Basic Application of Geotechnical Engineering

rolled forward along the surface of the rock in the XZ-plane, the total displacement vector at the center is Dis, and dDis is the displacement of the hob in each loading step. At the same time, the hob also rotates and scrolls, and its angular velocity around the geometric center is dAngle. Finally, cement the model, save the simulation initial data, and enter the iterative calculation: gpuStatus=d.mo.setGPU('auto'); d.tic(totalCircle*stepNum); for i=1:totalCircle d.mo.setGPU(gpuStatus); for j=1:stepNum d.moveGroup('hob',dDis(1),dDis(2),dDis(3)); hobId=d.GROUP.hob; hobCx=gather(d.mo.aX(hobId(end))); hobCy=gather(d.mo.aY(hobId(end))); hobCz=gather(d.mo.aZ(hobId(end))); d.rotateGroup('hob','XZ',-dAngle,hobCx,hobCy,hobCz); d.balance(balanceNum); d.recordStatus(); d.toc();%show the note of time end d.clearData(1);%clear data before saving save([fName num2str(i)'.mat']); d.calculateData(); end

The above code is a regular load iteration process. First set the GPU state to “auto” and use the d.tic() command to record the simulation initial time and total load steps. Use two layers of loops, set the GPU in the outer loop, compress and save the file. Moving and rotating the hob in the inner loop, since the last element of the hob structure object is at its center position, the rotation center of the d.rotateGroup is the last element of the hob group. Note that MatDEM only performs GPU calculation optimization on the iterative calculation function. When running operation commands such as d.rotateGroup, you need to use the gather command to convert the coordinates in d.mo into CPU data. Otherwise, an error may occur. In the balance calculation, the d.balance(balanceNum) command is used, and the Standard Balance command d.balance(‘Standard’) can also be used. Figure 6.10a, b show the state of the numerical model at 0.059 s and 0.096 s, respectively, where the element color represents its stiffness and the warm color element has a higher stiffness. In order to quickly complete the numerical simulation, the hob in this example moves at a faster speed of 7.9 m/s, causing rapid destruction of the element connection and a large number of element splashes (Fig. 6.11a). It should be noted that in each loading step, the hob moves downward and rightward and rotates by a certain amount. In order to obtain a more accurate simulation result,

6.3 TBM Cutter Rock Breaking

(a) 0.059s

173

(b) 0.096s

Fig. 6.10 Numerical simulation process diagram

Fig. 6.11 Diagram of numerical simulation results

the amount of movement per step needs to be smaller than the breaking displacement between the element (see Sect. 4.3.4 for details). At the moment when the load is applied at each step, the hob edge is subjected to a large pressure, and after the balance calculation, the pressure of the hob edge is rapidly reduced. After the numerical simulation is completed, run the d.show() command to obtain the stress map, energy conversion curve, boundary force curve, and heat generation curve as shown in Fig. 6.11. Comparing Figs. 6.10 and 6.11, it can be seen that

174

6 Basic Application of Geotechnical Engineering

when the hob cuts a high stiffness rock, the bottom boundary is subjected to larger pressure. Correspondingly, the energy and heat curves also show a stepwise change. When the hob approaches the right boundary, the force on the right boundary also increases rapidly.

6.3.4 Improve the Calculation Speed of Rock Breaking with Hob The numerical simulation of the hob rock breaking involves a huge amount of calculation. When the deformation and damage of the hob are not considered, the calculation method can be reduced by the following method. This method is also used in the direct shear and torsion shear examples (Sect. 7.1). (1) Set the hob as a fixed element The numerical iterative calculation of MatDEM is based on the d.mo.nBall matrix, which only calculates the force between the active element and its neighbors, and then the force and motion of the active element are obtained without calculating the force and motion of the fixed element. The computing time is mainly affected by the number of active elements and is hardly affected by the number of fixed elements (Sect. 2.3.1). The hob is usually much stiffer than the rock being cut. When the deformation and damage of the hob itself are not considered, the hob element can be set as a fixed element to reduce the number of active elements and speed up the calculation. (2) Reduce the stiffness of the hob element As can be seen from Sect. 4.4.3, the time of the discrete element simulation depends on the element with the smallest period. When the hob element is a fixed element (not movable during calculation), it can be considered to be rigid. At this time, the rigidity of the hob element can be reduced to have a similar rigidity to the rock element, so that the time step can be increased, and the calculation is completed using fewer iterations, which significantly increases the calculation speed.

Chapter 7

Rock–Soil Body Discrete Element Tests

MatDEM can be used to build various geometric models and can simulate various indoor soil and rock mechanics tests through a combination of models and loading. This chapter uses direct shear tests, torsional shear tests, and true triaxial tests to explain how to build a discrete element test simulator. It also focuses on how to build several objects and create various cracks and joints.

7.1 Direct Shear and Torsional Shear Tests Examples of direct shear (torsional shear) tests include BoxShear 0–4 code files, which are used for (1) accumulating soil samples; (2) making a direct shear (torsional shear) test box and the sample inside; (3) assigning materials to the samples; and (4) numerical simulation of a direct shear (torsional shear). The process of building a BoxShear model is relatively complex. The basic idea is to make discrete element samples and shear boxes based on the real test process. This involves cutting cylindrical samples and putting them into shear boxes, and then applying vertical pressure on the samples to perform direct shear or torsional shear operations. The following example implements most of the functions of the obj_3AxisTester class. It demonstrates how to build complex models through the secondary development of MatDEM.

7.1.1 Define Test Parameter and Accumulate Sample In the sample code BoxShear0, a soil sample block without initial gravity is built through gravity accumulation, compaction, and gravity reduction. To cut a suitably sized cutting-ring soil specimen, the original soil sample block needs to be set larger than the cutting ring. The main code is as follows: © The Author(s), under exclusive license to Springer Nature Singapore Pte Ltd. 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9_7

175

176

7 Rock–Soil Body Discrete Element Test …%Clean the workspace and choose a random seed. B=obj_Box; …%Define B.name,GPUstatus,ballR,distriRate,isClump and so on. B.SET.shearType='torsional';%May change it to 'shear'. B.SET.sampleR=0.0309; B.SET.sampleH=0.02; if strcmp(B.SET.shearType,'torsional') B.SET.sampleR=0.0309; B.SET.sampleH=0.06; end B.sampleW=B.SET.sampleR*2.2; B.sampleL=B.SET.sampleR*2.2; B.sampleH=B.SET.sampleH*1.5; B.type='topPlaten'; B.setType(); B.buildInitialModel(); …%Gravity sediment,compact sample and reduce gravity. ...%Gravity sediment,compact sample and reduce gravity.

Unlike other examples of the accumulation modeling process, this example uses the B.SET property to record simulation information. Both B.SET and B.TAG are structure arrays (struct data) and can be used to record simulation-related information. The former array is usually used to record settings and parameter information relating to the simulation, whereas the latter array is mainly used to record output and view information. This example supports direct shear and torsional shear test simulations, and the simulation type can be defined by the parameter B.SET.shearType. Both direct shear and torsional shear samples are cylinders with corresponding heights of 2 cm and 6 cm, respectively, and both have a radius of 3.09 cm. Depending on the required size of the cylindrical sample, a slightly larger initial block sample is made that is convenient for subsequent cutting. The accumulation of block samples can then be obtained by gravity deposition, compaction, and data saving operations. Figure 7.1 presents the packing model generated by the BoxShear0 code. Figure 7.1a is the soil sample block, whereas B.SET.shearType is “shear” (direct shear test), and Fig. 7.1b is the sample, whereas B.SET.shearType is “torsional” (torsional shear test).

7.1.2 Making a Shear Box and Cutting Sample The direct shear (torsional shear) test box is cylindrical and made up of a top and bottom shear box and top pressure plate. Several independent components need to be built and then assembled. The block sample generated from the first step also needs to be cut according to the size of the shear box to obtain the cylindrical sample. The shear boxes of direct shear and torsional shear tests are similar, and most of the corresponding modeling codes are the same.

7.1 Direct Shear and Torsional Shear Tests

(a) direct shear test

177

(b) torsional shear test

Fig. 7.1 Block sample based on BoxShear0

(1) Definition of shear box parameters In the code BoxShear1, the data for the block sample first need to be loaded. The model information recorded in B.SET then needs to be read, and some parameters are set. load('TempModel/BoxShear0.mat'); sampleR=B.SET.sampleR; sampleH=B.SET.sampleH; ballR=B.ballR; Rrate=0.7; tubeR=sampleR+ballR; ringWidth=0.005; innerWidth=sampleR*0.9;%Used for torsional shear. innerHeight=sampleH/6;%Used for torsional shear. boxSampleId=d.getGroupId('sample'); sX=d.mo.aX(boxSampleId);

In the code above, sampleR is the radius of the sample and sampleH is the height, which can be read from the structure array B.SET. The radius of the confined circular tube of the shear box tubeR can be obtained from line 6, which is equal to the sample radius sampleR plus the element radius ballR. The width of the outer ring of the shear box (Fig. 7.2) is defined by ringWidth. Because the shear box is made up of only

178

7 Rock–Soil Body Discrete Element Test

(a) direct shear box

(b) torsional shear box

Fig. 7.2 Section of shear box

one layer of elements, during the direct shear test, when the top and bottom boxes have relative displacement, the element will leak out from the gap between the two boxes. Therefore, a ring is added between the top and bottom shear boxes to prevent such leakage. botTubeH is the height of the bottom confined circular tube, and the parameter Rrate defines the overlap between shear box elements. In this example, Rrate = 0.7, which means that the distance between adjacent elements of the shear box is 70% of their diameter. A relatively compact and smooth container can be built by defining the overlap. The smaller the Rrate, the larger the overlap of the elements and the smoother the surface of the shear box. However, the number of elements will increase as will the computation. Declaring the parameter BoxType as “wall” defines all the elements constituting the shear box (except the top pressure plate) as wall elements, which can significantly reduce the amount of calculation required. If the shear box needs to be viewed in the post-processing window, the item “Show boundary” needs to be changed to “Show frame 2” or enter the command d.showB = 3 to display custom wall elements; however, this does not show the boundary wall elements generated automatically by the system. The parameters innerWidth and innerHeight are used to define the size of the friction plate of the torsional shear box, which will be introduced in the torsional shear test section. (2) Making a cylindrical sample The following code can be used to cut out cylindrical samples as shown in Fig. 7.3 (example of a direct shear test).

7.1 Direct Shear and Torsional Shear Tests

179

Fig. 7.3 A cylindrical sample (example of the direct shear test)

boxSampleId=d.getGroupId('sample'); sX=d.mo.aX(boxSampleId); sY=d.mo.aY(boxSampleId); sZ=d.mo.aZ(boxSampleId); dipD=0;dipA=0; radius=sampleR-ballR;height=sampleH-ballR; columnFilter=f.run('fun/getColumnFilter.m',sX,sY,sZ,dipD,dipA, radius+B.ballR,height); d.addGroup('column',find(columnFilter)); sampleObj=d.group2Obj('column'); sampleObj=mfs.moveObj2Origin(sampleObj);

The code above uses one of the modeling functions, the mfs.getColumnFilter function, to cut the cylinder sample. This function is also provided in the fun file, which can then be used by the f.run function to obtain the element filter matrix of the cylinder, denoted as columnFilter. Users can also write a filter of an arbitrary shape to cut samples. The definition and use of filters are described in Chap. 3. Additionally, the d.addGroup function is used to declare it as a column group, which is converted into a structure array sampleObj (including unit coordinates and radius information) by the d.group2Obj function. This is then moved from the center of the sample to the origin for subsequent use. (3) Making a sample shear box The shear box is composed of top and bottom parts, each of which is composed of a lateral circular tube, bottom plate, and outer ring. The following code separately creates the various parts of the shear box, building a complex 3D model by moving, aligning, and merging. The following code in Box Shear1 is used to generate the bottom shear box:

180

7 Rock–Soil Body Discrete Element Test botTubeObj=mfs.denseModel(Rrate,@mfs.makeTube,tubeR+(1-Rrate)* ballR*2,botTubeH,ballR); discObj=mfs.denseModel(Rrate,@mfs.makeDisc,sampleR+(1-Rrate)* ballR*1,ballR); botTubeObj=mfs.moveObj2Origin(botTubeObj); discObj=mfs.moveObj2Origin(discObj); [botTubeObj,botDiscObj]=mfs.alignObj('bottom',botTubeObj,discObj); botBoxObj=mfs.combineObj(botTubeObj,botDiscObj); botBoxObj=mfs.align2Value('bottom',botBoxObj,0); botBoxTopZ=mfs.getObjEdge('top',botBoxObj); botRingObj=mfs.makeRing2(tubeR+ballR-ballR*(1-Rrate)*2,tubeR+ ballR+ringWidth,ballR,Rrate); botRingObj=mfs.align2Value('top',botRingObj,botBoxTopZ); botBoxObj=mfs.combineObj(botBoxObj,botRingObj);

The denseModel function in line 1 is used to generate a model with a certain amount of overlap. The first input parameter, Rrate, defines the ratio of the distance to the diameter of two adjacent elements of the model; the second parameter is the function that generates the component structure and uses the built-in mfs.makeTube function; the other parameters are the input parameters of makeTube. As the denseModel function runs, the makeTube function is called and the makeTube ballR parameter is replaced with ballR times Rrate. The makeTube function returns the tube structure array botTubeObj, and the ballR array in botTubeObj is reset to ballR. Finally, a smooth tube model in which the elements are overlapping is generated. Similarly, in line 2, the denseModel function is used to call makeDisc to generate discObj, which is the disk structure on the bottom of the shear box. The input of (1 − Rrate) * ballR * 1 in the parameter list is to make the bottom plate overlap with the tube wall to ensure the inner surface of the entire model is equally smooth. The information on elements X, Y, Z and R is contained in the structure data of the circular tube and bottom plate. By default, the origin of the coordinate axis of the structure returned from the modeling function is usually in the center or left bottom of the structure. It is necessary to align the bottom plate to the bottom of the tube: lines 3 and 4 move the center of both the tube and the bottom plate to the origin and line 5 aligns the bottom of the two structures using the mfs.alignObj function. Finally, the function mfs.combineObj combines the tube and the bottom plate to generate the object botBoxObj and aligns its z-coordinate of bottom side with Z = 0. Similarly, the outer ring object botRingObj is generated and then spliced to the botBoxObj to generate the bottom shear box. topTubeObj=mfs.align2Value('bottom',botTubeObj,botBoxTopZ); [topTubeObj,topPlatenObj]=mfs.alignObj('top',topTubeObj,botDiscObj); topTubeBotZ=mfs.getObjEdge('bottom',topTubeObj); topRingObj=mfs.align2Value('bottom',botRingObj,topTubeBotZ); topTubeRingObj=mfs.combineObj(topTubeObj,topRingObj);

The parts of the top shear box can be generated by copying the parts of the bottom shear box and then combining them. However, the top shear box is only combined

7.1 Direct Shear and Torsional Shear Tests

181

Fig. 7.4 Friction plate at the bottom of the shear box for the torsional shear test (sample elements have been added)

from topTubeObj (the confined tube) and topRingObj (the circle), while topPlatenObj (the roof) will be used to exert normal loads instead of combining with the top shear box. (4) Adding friction plates to the torsional shear test box To increase the force between the shear box and sample for a torsional shear test, several friction plates are added in the bottom shear box using the following code: if strcmp(B.SET.shearType,'torsional') planeObj=mfs.makeBox(innerWidth,innerHeight,ballR,ballR); planeObj=mfs.rotate(planeObj,'YZ',90); planeObj=mfs.move(planeObj,sampleR-innerWidth,0,ballR*2); planeObj=mfs.rotateCopy(planeObj,60,6); botBoxObj=mfs.combineObj(botBoxObj,planeObj); end

The friction plate made by the function mfs.makeBox is flat by default; therefore, it needs to be rotated and moved to the desired angle through the functions mfs.rotate and mfs.move. After making the first friction plate, the plate is rotated around the designated center of rotation and copied by the function mfs.rotateCopy. In the sample code, a new plate is copied for every 60 degrees of rotation. Six plates can be obtained overall and added to the base of the bottom shear box. Figure 7.4 shows the bottom section of this box in the torsional shear test. This shows six friction plates arranged in the shape of “*”.

7.1.3 Putting the Sample into the Shear Box The discrete element model of the sample and the shear box is built using the code of BoxShear0–1 and stored in the structure array. Finally, an empty box is built and the components then are combined to complete the model of the shear test.

182

7 Rock–Soil Body Discrete Element Test B=obj_Box; …%Define B.name,GPUstatus,ballR,distriRate,isClump and so on. B.sampleW=(sampleR+ringWidth)*2.5; B.sampleL=(sampleR+ringWidth)*2.5; B.sampleH=sampleH+5*B.ballR; B.BexpandRate=2; B.PexpandRate=0; B.isSample=0;%Won't generate sample when building initial model. B.type='botPlaten';B.setType(); B.buildInitialModel(); d=B.d; …

Because the simulation box must have active elements, the code above declares B.isSample = 0 and B.type = ‘botPlaten’ to establish a simulation box with a bottom pressure plate only. The pressure plate can be removed after adding the sample. The cylindrical specimen, the bottom shear box, the top shear box, and the top pressure plate are then imported into the empty box. botBoxId=d.addElement(1,botBoxObj,boxType); d.addGroup('botBox',botBoxId); d.setClump('botBox'); topTubeRingId=d.addElement(1,topTubeRingObj,boxType); d.addGroup('topTubeRing',topTubeRingId); d.setClump('topTubeRing'); topPlatenId=d.addElement(1,topPlatenObj); d.addGroup('topPlaten',topPlatenId); d.setClump('topPlaten');

The code above firstly imports the structure of the bottom shear box, botBox, and the top shear box, topTubeRing, into the box model and defines these elements as a specific group which it declares as a cluster clump. In Sect. 7.1.2, boxType= ‘all’ has already been declared so the function addElement on the first and fourth line will set both the top and bottom shear boxes as “wall” elements while the command setClump on the third and the sixth line will not work. If boxType = ‘model’, both the top and bottom shear box are active elements, and setClump needs to be used to eliminate the initial force between active elements. In line 7, the top pressure plate is imported into the box and is set as an active element by default. The top pressure plate will be used to exert pressure on the sample.

7.1 Direct Shear and Torsional Shear Tests

183

d.addGroup('shearBox',[d.GROUP.botBox;d.GROUP.topTubeRing;d.GROUP.topPlaten]); d.delElement('botPlaten'); d.moveGroup('shearBox',B.sampleW/2,B.sampleL/2,0); boxSampleId=d.addElement(1,sampleObj); d.addGroup('sample',boxSampleId); boxZ=d.mo.aZ(d.GROUP.shearBox); d.moveGroup('sample',B.sampleW/2,B.sampleL/2,mean(boxZ)); d.minusGroup('sample','shearBox',0.5); d.removeGroupForce(d.GROUP.topTubeRing,d.GROUP.topPlaten); …%Fix element coordinates,gravity sedimentation,etc.

For the convenience of operation, the top and bottom shear boxes and pressure boards are defined as the shear boxes group (shearBox) and moved to the center of the simulation box in line 1 (above). The sample (sampleObj) is then added to the model and placed in the shear box. However, there is usually a certain amount of overlap between the sample and the shear box; thus, the function d.minusGroup is needed to eliminate the overlap. Because there is a certain overlap between topPlaten, the top pressure plate, and topTubeRing (the confined tube), the interaction between them is eliminated by the command d.removeGroupForce. In addition, although the top pressure plate element is movable, it is limited to a normal direction (Z-direction), which means the freedom of the top pressure plate in the X- and Y-directions needs to be locked by the command d.addFixId. Subsequently, gravity deposition is required and the sample needs to be compacted, after which the data can be saved. The specific code is shown in BoxShear1. By running this modeling code, the shear box model and sample of the direct shear test shown in Fig. 7.5a can be obtained.

(a) direct shear test Fig. 7.5 Initial geometric model section of test box and sample

(b) torsional shear test

184

7 Rock–Soil Body Discrete Element Test

7.1.4 Material Setting and Numerical Simulation Sections 7.1.2 and 7.1.3 correspond to the BoxShear1 code. The following material settings and numerical simulations correspond to the BoxShear2 and BoxShear3 codes, respectively. Direct shear and torsional shear tests share the code files BoxShear0–2 in geometric modeling and material assignment. However, in the third step, when shear loads are applied, the codes BoxShear3 and BoxShearTorsional3 are used separately because of their different loading modes. The general principle behind the two codes is the same: totalCircle and stepNum are used as cyclic variables, and displacement or rotation conditions are applied step by step through the for loop to complete the numerical simulation of direct or torsional shear tests. (1) Material setting In the BoxShear2 code, the import and setup of materials is a regular operation (refer to Chap. 3 or other examples for further clarification). matTxt=load('Mats\Soil1.txt'); Mats{1,1}=material('Soil1',matTxt,B.ballR); Mats{1,1}.Id=1; d.Mats=Mats; d.setGroupMat('sample','Soil1'); d.groupMat2Model({'sample'},1);

The material for the numerical simulation usually needs to be set up according to the real test: the material comprising the top and bottom shear box is usually brass, which requires brass material (Mats\Brass.txt); the top pressure plate takes the mechanical property of sandstone (Mats\Sandstone.txt), and the sample is assigned the mechanical property of soil (Mats\Soil1.txt). In this example, because both the top and bottom shear boxes are wall elements or locked moving elements, the entire shape of the shear box is rigid. Therefore, in the sample code above, only soil samples are added, and all elements will be assigned the same soil material. Because this example primarily studies the shear deformation of soil samples, the material that supports the rigid shear box will not affect the nature of its rigid boundary. At the same time, due to the small element stiffness of soil materials, the calculation speed is significantly increased (see Sect. 1.3.3 for details). If the deformation of the sample box needs to be simulated, the shear box should be set as active elements and brass material should be added. (2) Numerical simulation of the direct shear test The sample code of BoxShear3 simulates the direct shear test. Based on the test process, the bottom shear box is moved slowly and horizontally to complete the direct shear test. The main simulation code is as follows:

7.1 Direct Shear and Torsional Shear Tests

185

for i=1:totalCircle for j=1:stepNum d.toc();%show the note of time d.moveGroup('botBox',dDis,0,0,'mo'); d.balance('Standard',0.1); end d.clearData(1);%clear data in d.mo save([fName num2str(i)'.mat']); d.calculateData(); end

Through the for loop, the total displacement is decomposed into several loading steps, each of which is dDis. For example, the total shear displacement is 5 mm, which is decomposed into 20 cyclic steps (totalCircle, i.e., recording 20 files), and each cyclic step is decomposed into 10 or more loading steps (stepNum). Thus, the shearing process is decomposed into 200 loading steps, each of which uses the command d.moveGroup to move the bottom shear box horizontally by 0.025 mm and create a standard balance. In practice, users usually need to set up at least 2000 loading steps to simulate a shear process accurately. It should be noted that this example simulates the real test process. When shear displacement is applied, only the rigid bottom shear box is moved; the sample in the box is not moved. When the bottom shear box moves, its elements push the sample elements and, through iterative calculations, the sample elements in the bottom shear box move. The top shear box remains fixed and the sample gradually undergoes shear deformation and failure, thus realizing the numerical simulation of the direct shear test. The displacement field of the simulation results for the sample code is shown in Fig. 7.6. For each step of loading, the command d.balance (‘Standard’, 0.1) is used to balance the model, during which the sample gradually moves and deforms. The Fig. 7.6 Simulation results for the direct shear test (displacement field)

186

7 Rock–Soil Body Discrete Element Test

effect of the shear rate can be simulated by adjusting the second coefficient of the function d.balance (‘Standard’,1). A standard equilibrium will consume most of the energy generated by the displacement load, whereas the 0.1 times standard balance usually corresponds to a very fast shear process whereby the last shear displacement has not yet been fully finished and new displacement is applied. As shown in Fig. 7.6, the displacement on the left side of the sample in the bottom shear box is noticeably larger due to the faster shear speed, and there is a gap between the sample and the right side of the bottom shear box. Section 4.3 provides further details on the functions and parameters of the above commands. (3) Numerical simulation of the torsional shear test The sample code BoxShearTorsional3 simulates the torsional shear test. The main code is as follows: for i=1:totalCircle for j=1:stepNum d.toc();%show the note of time d.rotateGroup('botBox','XY',dAngle,B.sampleW/2,B.samp leL/2,0,'mo'); d.balance('Standard',0.1); end d.clearData(1);%clear data in d.mo save([fName num2str(i)'.mat']); d.calculateData(); end

The basic process of the torsional shear test is the same as that of the direct shear test: firstly, the rotation angle dAngle of each step is defined; the bottom box is then rotated using the command d.rotateGroup function. The input parameter “XY” determines that the rotation plane is the XY-plane, the parameter dAngle is the rotation angle, and the rotation center is the positive center of the sample (B.sampleW/2, B.sampleL/2, 0). The final input parameter “mo” declares that the coordinates of the elements in d.mo are rotated without changing the initial coordinates of the elements in “d”. In MatDEM, the relative rotation angle dθ is not a built-in post-processing parameter. If users need to quantitatively study the sample angular displacement in a torsional shear test, they can calculate the element angular displacement “mdA” by code and assign it to d.mo.SET.mdA. The post-processing command d.show (‘SETmdA’) draws the element angular velocity map. The simulation results are shown in Fig. 7.7. The torsional shear speed of this example is very fast, and there is also a gap between the friction plate at the base of the bottom shear box and the sample elements. Thus far, shear test modeling and numerical simulation have been conducted using MatDEM. The difficulty of the example focuses on modeling. Using the modeling function set mfs and the custom functions, the objects of each part required for numerical simulation are built and combined into a complete model. Via splicing a

7.1 Direct Shear and Torsional Shear Tests

187

Fig. 7.7 Simulation results for the torsional shear test

complex model into several small parts, building them separately, and then combining them into one object, we are able to build very complex discrete element models. The code for this example is relatively complex and the user can add a “return” command where appropriate during the learning and revision process to check and understand the modeling process.

7.2 True Triaxial Test and Joint Modeling True triaxial tests under high stress are very difficult; however, discrete element numerical simulation provides a simple and efficient test method. The sample code 3DJointStress demonstrates how to build a triaxial test simulator and perform numerical simulations of rock deformation and failure under high-pressure conditions. The first and second steps of this example focus on accumulating a rock mass by conventional methods; the third step demonstrates how to add complex joints and cracks to the block and apply true triaxial pressure.

7.2.1 Build a True Triaxial Test Chamber (1) Accumulating sample In the code file 3DJointStress1, most of the code is regular steps in geometric modeling. Users simply need to declare the input parameter as “3DJointStress,” and when the function setType is called, the six pressure plates will be set (up and down, left and right, front and back). When constructing a true triaxial test chamber, the user needs to set two parameters, BexpandRate and PexpandRate: these define the number of elements extending outward from the boundary or pressure plate and are normally determined according to the model size and the element radius:

188

7 Rock–Soil Body Discrete Element Test B.BexpandRate=B.sampleW*0.1/B.ballR; B.PexpandRate=B.sampleW*0.1/B.ballR;

When these two parameters are not set (i.e., the default value is 0), the program automatically creates a cuboid model. The pressure plates on the boundaries of the model will enclose the sample elements inside, and to prevent them from leaking out. However, in a true triaxial test, the sample may expand laterally and push the pressure plate outward, at which point the element may overflow from the gap between the pressure plates. To prevent this, the pressure plates and boundaries need to be extended outward. Figure 7.8a shows the initial model before gravity deposition where the sample elements are still arranged in a grid and the pressure plate and boundary are both outwardly extended in a “#” shape. (2) Setting the pressure plates B.SET.stressXX=-6e6; B.SET.stressYY=-6e6; B.SET.stressZZ=-10e6; B.setPlatenFixId(); d.resetStatus(); B.setPlatenStress(B.SET.stressXX,B.SET.stressYY,B.SET.stressZZ,B. ballR*5);

After the initial geometric model is established, the material of the model needs to be set. The confining pressure σ 3 can then be applied to the model through six

Fig. 7.8 The “#” shaped boundaries and pressure plates

7.2 True Triaxial Test and Joint Modeling

189

pressure plates to consolidate the sample. The code above records the stress of the pressure plate in B.SET. However, to ensure that the pressure plate applies relatively uniform stress to the sample and is prevented from slipping off the side when the sample is not flat, the freedom of the pressure plate element is locked by the function B.setPlatenFixId (Sect. 3.1.1). This ensures that the edge element of the pressure plate can only move along the initial normal direction of the pressure plate. For example, the X- and Y-coordinates of the edges of the top and bottom pressure plates are locked but can still move in the Z-direction. Unlike the direct shear (torsional shear) test in Sect. 7.1, the true triaxial test in MatDEM uses a rectangular pressure plate, which means the function B.setPlatenStress can be called directly to set the triaxial pressure (Sect. 4.4.2). To create a pressure effect, this command applies body forces only to the pressure plate elements that may be in contact with the sample elements. In Fig. 7.8b, the dark blue element is the portion where the top pressure plate has not been applied with body force because it is not in contact with the sample. At this point, the construction of the true triaxial test chamber has been completed.

7.2.2 Defining Fracture Surface Using Triangle Faces and Polygons In the third code file of the example, 3DJointStress3, several methods for adding complex joints to the model are demonstrated. It should be noted that after the material is set, the model needs to be rebalanced if there is a sudden change in the mechanical properties of the elements. Therefore, joints and cracks should be assigned to the model after the balancing operation at the end of the second step (second code file), or before the new load is applied at the beginning of the third step. Generally, it is convenient to perform the joint definition operation at the beginning of the third step. In the 3DSlope example, a crack in the rock is also set in the top part of the landslide. However, the difference in this example is that the program defines the rock mass above the sliding belt as a group, then cements the elements in the group and breaks the cement between the elements inside and outside, thereby generating the crack surface and the rock mass that slides down. Although this method is simple and convenient, it is difficult to set a local, non-penetrating crack. This section employs a series of triangular faces to define a spatial surface that can be set up with quite complex fracture faces. (1) Triangular surface definition function The sample code 3DJointStress3 demonstrates how to use triangular face vertex coordinates to generate fracture faces:

190

7 Rock–Soil Body Discrete Element Test TriX=[0.01,0.08,0.02];TriY=[0.05,0.1,0.05];TriZ=[0,0.05,0.1]; bondFilter=mfs.setBondByTriangle(d,TriX,TriY,TriZ,type); d.mo.zeroBalance(); d.showFilter('Group',{'sample'}); d.show('Crack');

The first line of the code defines the X-, Y-, and Z-coordinates of the three vertices of the triangle. The first item of the three parameters (matrix) defines the first triangle; the function mfs.setBondByTriangle then generates a triangle face in the model object “d” based on the coordinates of the three points, and returns a Boolean matrix of connections that is in contact with the triangular face (i.e., the connection filter bondFilter; see Sect. 3.6.2 Connection Filter Definition). In this filter, the connections cut by the triangle face have a value of true (1) and the rest is false (0). The parameter type defines the operation in the function, which can be declared as cementing (“glue”) or generating cracks (“break”), and the program will then glue or break the connections (modify d.mo.bFilter). Entering other strings will not do anything other than return the filter matrix of connections bondFilter for further use. Running the command above, the micro-cracks are obtained and shown in Fig. 7.9a. The following code demonstrates how to use the connection filter to obtain the relevant elements:

(a) Micro cracks cut by atriangle face

(b) Elements that contacted with the triangle face

Fig. 7.9 Fracture surface and contacted elements defined by the triangular surface

7.2 True Triaxial Test and Joint Modeling

191

bondFilter=bondFilter&(d.mo.cFilter|d.mo.bFilter); connectFilter=sum(bondFilter,2)＞0; connectId=find(connectFilter); d.addGroup('JointLayer',connectId);%add a new group figure; d.showFilter('Group','JointLayer','aR');

Firstly, the Boolean matrix of compressive connections, cFilter, and the Boolean matrix of bonded connections, bFilter, are combined to obtain a matrix of contacted filter. The second line obtains the element filter in contact with the triangular face. The find command is used to obtain the indexes of elements (connectId) in contact with the triangle. Then, these elements are defined as the “JointLayer” group. Figure 7.9b shows the elements in contact with the triangular face. Using triangular faces to define the fracture face is the most basic method for making joints. The polygon definition function and Tool_Cut tool introduced below also are defined based on the basic function. (2) Polygon definition function Based on the triangular surface function above, in MatDEM, the joint surface can be defined by a spatial polygon and the corresponding function is setBondByPolygon. The relevant sample code is as follows: TriX=[0.09,0.09,0.1,0.01];TriY=[0,0.1,0,0.1];TriZ=[0,0,0.1,0.1]; bondFilter=mfs.setBondByPolygon(d,TriX,TriY,TriZ,'glue'); d.mo.nBondRate(bondFilter)=2;%make strong joint

The meaning of the input parameter of this function is similar to the function setBondByTriangle. This function also requires the X-, Y-, and Z-coordinates of the spatial points, although the number can be greater than three. The function automatically decomposes the spatial polygon composed of multiple points into several triangles, and then breaks or glues the model connections by the basic function setBondByTriangle. The function setBondByPolygon combines four coordinate points in an orderly manner to form different triangular faces. These triangular faces start with the first vertex and generate adjacent triangular faces in the order of 1–2–3, 1–3–4. The third input parameter of this command is “glue,” which glues the joint face. Similarly, this function also returns the connection filter bondFilter, which records the element connections that intersect these triangles. The strength coefficient matrix of connections nBondRate is defined in d.mo, and its function is to control the strength of the connections between the elements. In the MatDEM, the strength of the joint can be changed by modifying the value of the matrix. When the value is >1, the connection strength increases; if it is lower, it decreases. When calculating the failure of an inter-element connection in the MatDEM, the inter-element tensile force and initial shear force matrix are multiplied by nBondRate to increase or decrease the connection strength according to the value of nBondRate. The third line above uses the connection filter to set the strength

192

7 Rock–Soil Body Discrete Element Test

Fig. 7.10 Connection strength coefficient diagram

coefficient of the joint and the strength of this joint surface is then set to twice of the original value (see the right joint surface in Fig. 7.10). Generally, the joint strength may decrease, and a value max(S_top.Z(:))-dZ*topRate; topAddH=100; topZ=S_top.Z(topFilter); dTopZ=topAddH*(topZ-min(topZ))/(dZ*topRate); S_top.Z(topFilter)=S_top.Z(topFilter)+dTopZ; S_top0=mfs.moveMeshGrid(S_top,-r*2*topPackNum);

After S0 is moved upward by about 100 m and adjusted, the top surface S_top of the top mold plate is obtained. S_top is then moved downward by about 50 m to obtain the bottom surface S_top0 of the top mold plate. The parameter topPackNum determines the thickness of the top mold plate. The surfPackNum2 determines the additional thickness of the soil layer on the top surface of the slope to ensure that a sufficiently thick stratum model is established for the subsequent operation of cutting stratum. When using obj_Box to pack the model, the height will be lower than the simulation box. Similarly, when modeling with a thin shell mold, the top portion may lack elements due to gravity deposition, resulting in incomplete modeling. To avoid this problem, it is necessary to move the high part of the top mold upward to place more elements in subsequent operations. Lines 2–8 of the above code are used to increase the height of the surface with high terrain in the top surface S_top and will not be described in detail. Finally, the surface of the landslide source area is defined, that is, the initial crack surface S_source:

8.1 Defining 3D Surfaces with Digital Elevation

207

S_source=S0; S_source.Z=S.Z2; sourceFilter=mfs.image2RegionFilter('slope/slopesource.png',imH,imW); S_source.Z(～sourceFilter)=max(S_source.Z(:))+100; S_source.Z(sourceFilter)=S_source.Z(sourceFilter)-10; … save('slope/slopeSurface2.mat','S_bot','S_top','S_top0','S0','S1 ','S2','S_source','r');

In the first and second lines of code, S_source is constructed and its Z-coordinate is the slope elevation after sliding. The image2RegionFilter function is then to obtain the filter sourceFilter of the landslide source area from the image slopesource. The soil layer in this area is a source of landslide, and only the stratum will have an initial crack. The terrain height of the nonslip source area in S_source is set to the highest point plus 100 m. In the subsequent operation, the landslide source stratum area can be directly cut out using S0 and S_source subjected to the above process. Thus far, we have completed construction of the seven surfaces of elevation data required for modeling (Fig. 8.5), from bottom to top, these are S_bot, S1, S2, S0, S_top0, S_top, and S_source. The specific meanings are presented in Table 8.1, and the corresponding diagram is plotted in Fig. 8.5. Finally, the data is saved to the slope folder and named slopeSurface2. V=S_top0; surface(V.X,V.Y,V.Z,30*ones(size(V.X))); colorbar; fs.general3Dset();

In this file, the surface function is used to view the surface data of the construction and is a built-in function of MATLAB (please see the help file of MATLAB for details). Additionally, the function fs.general3Dset can be used for 3D rendering.

8.2 Building a Thin Shell Model Based on the construction of digital elevation data at various surfaces, this section shows how to construct a mold of a thin shell model and build the model with the packing elements. The code file used is 3DSlope1. First, sample elements are generated at a regular position in the simulation box; the top mold plate and the bottom mold plate are then defined by the surface elevation data, which form a closed container with the surrounding boundary; finally, the internal elements are packed.

208

8 Modeling of Complex 3D Models

8.2.1 Building a Geometric Model First, the surface data slopeSurface2.mat is imported and the Box object is built. Some initial parameters are then set; however, because this process is consistent with other modeling examples, these steps will not be repeated here. It should be noted that the model size set in this example is the same as that in the digital elevation file: 2800 m × 1500 m × 1800 m. …%set initial parameters B.platenStatus(:)=0;%no platen in the model B.buildModel(); B.createSample();%create balls in the box B.sample.R=B.sample.R*2^(1/12); %Radius deviation between close packing and cube packing is 2^(1/6)

In the thin shell model, it is not necessary to use a pressure platen to pack the model so the first line sets the values in the platenStatus array to all zeros. The function buildModel is then used to generate the model box boundary elements, following which the function createSample is used to generate the sample elements in the model box. The model generated by the function createSample is arranged in the shape of a cube. When it is closely packed, the volume of the packing model is reduced so the model packed by the obj_Box object does not usually fill the entire simulation box. In this example, to obtain a complete packing model, the element radius needs to be slightly increased to ensure that the elements just fill the entire mold. To account for the difference between the volumes of tightly packed and cubically packed elements, 1 the element radius is multiplied by the factor 2 12 . The following code imports the top and bottom surfaces into the model: S_Bbot=S_bot; S_Bbot.Z=S_Bbot.Z-ballR*4; S_Btop=S_top;%top limit of boundary S_Btop.Z=S_Btop.Z+500; B.addSurf(S_bot);%add the bottom surface B.addSurf(S_top);%add the top surface B.addSurf(S_Bbot);%add the bot surface of boundary B.addSurf(S_Btop);%add the top surface of boundary

This example uses a custom mold where, to reduce the amount of calculation, the boundary wall automatically generated by obj_Box is also cut. Lines 1–4 determine the range of selected boundary elements. S_Bbot defines the bottom surface of the boundary elements, which are 4 element radii lower than the bottom mold plate; S_Btop defines the top surface of the boundary elements, which is 500 m higher than the top mold plate to prevent the elements from flying out of the model. The function B.addSurf is then to import these four layers into B and save them in the

8.2 Building a Thin Shell Model

209

B.surf array in order, where S_bot is numbered 1, S_top is numbered 2, and so on. After importing surface data, the program interpolates values to the data through MATLAB’s interpolation function scatteredInterpolant and generates an object F of the scatteredInterpolant class, which is then recorded in B.surf . These surfaces can then be used to cut the model: B.cutGroup({'sample','botB','topB'},1,2); B.cutGroup({'lefB','rigB','froB','bacB'},3,4); B.finishModel();%built the geometric model B.setSoftMat();%set soft balls to increase the speed of computing B.d=B.exportModel();%tranform B.d.mo.isShear=0; d=B.d;

Lines 1 and 2 use the function B.cutGroup to cut the sample elements and boundary. The first input parameter is the name of the group to be cut (such as sample), whereas the second and third parameters are the number of the bottom and top surface to be cut. Line 3 uses the function B.finishModel to integrate information on boundaries and sample elements; it then uses the setSoftMat function to set the default flexible material. Finally, the model object d is exported. Figure 8.6 shows the initial geometric model obtained by the above operation.

Fig. 8.6 Initial geometric model and cut boundary wall

210

8 Modeling of Complex 3D Models

8.2.2 Cutting and Packing Model (1) The model can be cut using Tool_Cut

C=Tool_Cut(d);%use the tool to cut sample and get layers C.addSurf(S_bot); C.addSurf(S1); C.addSurf(S2); C.addSurf(S0); C.addSurf(S_top0); C.addSurf(S_top); C.addSurf(S_source); C.setLayer({'sample'},[1,2,3,4,5,6]); gNames={'layer1';'layer2';'layer3';'layer4';'layer5'}; d.makeModelByGroups(gNames);%make the model by using the layers

The above code uses the Tool_Cut object C to layer and cut the model. The steps are as follows. In the first step, an object C of type Tool_Cut is generated with an input parameter d. In the second step, the surface elevation data is imported into C using the function C.addSurf . The principle of this function is the same as that of the B.addSurf function. The layer data is converted into objects of the scatteredInterpolant class and saved in the C.Surf array in turn. Lines 2–8 import the seven surfaces defined in Sect. 8.1.2 from bottom to top into C. In the third step, the function C.setLayer is run, and the surfaces in the C.surf are used to cut the elements of the specified group (which can be multiple groups), as a result of which a series of new groups are generated. The first parameter in this function is a cell array (such as {‘sample’}), which specifies the group to be cut; the second parameter is the array of surface numbers for the cut operation. The function C.setLayer cuts each of the specified group elements in turn according to the input surface number and generates a new group. If the surface array is [1, 2], then surface 1 is the bottom boundary and surface 2 is the top boundary, and a new group layer1 is cut out. If multiple surface numbers are entered, such as [1, 2, 3, 4, 5, 6] in this example, then [1, 2], [2, 3], [3, 4], [4, 5], and [5, 6]; the five groups of surfaces are cut in sequence to obtain five stratums between adjacent surfaces. Note that when cutting the stratum, the numbers need to be arranged from low to high according to the surface; otherwise an empty group will be obtained. After cutting is completed, the element number data for each group will be saved in the array d.GROUP, prefixed with a layer and named layer1, layer2, and so on in the order of cutting. The parameter C.layerNum defines the current number of stratum and its initial value is 0. This parameter is incremented each time a new stratum group is obtained by cutting. Through the line 9 command, the sample group is cut using

8.2 Building a Thin Shell Model

211

Fig. 8.7 Surfaces and stratums of discrete element model

the surfaces of numbers 1 to 6, 5 groups are generated in d.GROUP, and layer1, layer2,…, layer5 are sequential from bottom to top where layer1 is the bottom mold plate; layer2 is the main landslide stratum; layer3 is the ancient landslide body; layer4 is the additional slope layer; and layer5 is the top mold plate. In the fourth step, the function d.makeModelByGroups is run to build a new model with the specified group. The last line of code uses the specified five groups to build a new model and removes the extra elements to build a thin shell model. However, protected groups such as boundaries are not deleted (see Sect. 2.4.3 for details). Figure 8.7 shows a section of the thin shell model with six surfaces and five stratums. The meanings of these six surfaces are explained in Table 8.1. The five stratums from bottom to top are thin shell bottom mold plate, rock layer of main slope, gravel layer of ancient landslide, additional slope layer, and thin shell top mold plate. (2) To set a thin shell mold plate:

d.defineWallElement('layer1'); d.mo.aR(d.GROUP.layer1)=B.ballR*1.3; mo=d.mo; mo.isFix=1;%fix coordinates; gId_top=d.getGroupId('layer5');%get element Id of group mo.FixXId=gId_top;%fix X coordinate mo.FixYId=gId_top; mo.FixZId=gId_top;

After cutting the model, the top and bottom mold plate elements are all active elements. To further pack the elements, the coordinates of the mold plate elements need to be fixed. There are two ways to fix the coordinates; one is to set the elements

212

8 Modeling of Complex 3D Models

as the fixed elements and the other is to lock all the freedom degrees of the elements. To demonstrate these two functions, the above code uses the first and second methods for the bottom mold plate (layer1) and the top mold plate (layer5), respectively. The first line command declares the bottom mold plate elements as fixed elements (i.e., the wall elements) using the function defineWallElement. The second line command multiplies the radius of the elements in layer1 by 1.3 so that the elements overlap, thereby preventing smaller elements of the overlying stratum from falling out of the gap. Lines 4–8 fix the layer5 elements by locking the coordinates. The element whose freedom degree is locked is still the active element, and it will occupy computing resources. In general, to speed up the calculation, it is, therefore, recommended that the mold plate be set as the fixed elements in the first method. With the second method, the freedom degree can be unlocked at any time and the motion of elements can be restored. nBall=d.mo.nBall; bcFilter=sum(nBall＞d.mNum&nBall～=d.aNum,2)＞0; gFilter=zeros(size(bcFilter)); gFilter(gId_top)=1; mo.aR(gId_top)=B.ballR; mo.aR(gFilter&(～bcFilter))=B.ballR*1.3; d.setClump('layer5');

Similarly, it is necessary to increase the element radius of the top mold plate layer5 to prevent elements with a smaller radius from leaking out. The elements of the top mold plate are the active elements. To avoid huge stress between the top mold plate and the boundary, the radius of the elements in contact with the boundary need to remain unchanged. Lines 1–5 of the above code filter the elements inside the top mold plate and set the radius to 1.3 times the average radius. Of these, the first line obtains the neighbor matrix nBall; the second line obtains the connection filter of boundary elements bcFilter; the third to fourth lines generate a filter and record the top mold plate; the fifth line sets the element radius of the top mold plate to the average radius of the model; in the sixth line, the radius of the elements (without contact with the boundary) is set to 1.3 times the average radius and the filter conditions are the top mold plate (gFilter) and the non-boundary connection elements (~bcFilter). Because the elements of layer5 are the active elements, after these overlap the seventh line needs to run the function d.setClump again, which declares layer5 as a clump and removes the inter-element force generated by the increase in the element radius. Through the above steps, the setting of the top and bottom mold plates of the thin shell model is completed.

8.2 Building a Thin Shell Model

213

B.uniformGRate=1;%using uniform g in B.gravitySediment B.gravitySediment(0.5); d.mo.FixZId=[]; %unfix all Z coordinates d.mo.dT=d.mo.dT*4; d.balance('Standard'); d.mo.dT=d.mo.dT/4; …% save result

The operation of gravity deposition of model elements is then performed. Prior to the deposition, the first line first sets the acceleration of the gravity deposition to g. Once the gravity deposition is completed, a large range of stress concentration (such as excessive elements) may occur as the elements of the top and bottom mold plates are fixed. Therefore, it is necessary to move the top mold plate and release the stress by iterative calculation. Line 3 sets d.mo.FixZId to null, unlocking the freedom degree of the elements’ Z-direction in layer5. Because gravity deposition does not require high accuracy calculation, calculation of the stress balance can be accelerated by increasing the time step. Lines 4–6 increase the time step to 4 times and perform a standard balance, which will restore the time step. Finally, a balanced thin shell model is obtained, and the file is saved to complete the modeling process for the first step. Figure 8.8 shows the established layered thin shell model in which different colors represent different layers.

Fig. 8.8 Sectional diagram of packed thin shell model

214

8 Modeling of Complex 3D Models

8.3 Building a Three-Dimensional Slope Model Based on the previous geometric model, in the 3DSlope2 file, the stratum is re-divided and the actual rock material is given to the model. To increase the speed of iterative calculation, the elements outside the landslide area are set as fixed elements. Finally, the model is balanced and the final 3D slope model is built.

8.3.1 Import Material

load('Mats\Mat_mxRock2.mat');%load a trained material Mats{1,1}=Mat_mxRock2; Mats{1,1}.Id=1; matTxt2=load('Mats\mxSoil.txt');%load a un-trained material file Mats{2,1}=material('mxSoil',matTxt2,B.ballR); Mats{2,1}.Id=2; d.Mats=Mats;

In this example, two methods are used to create two materials, mxRock and mxSoil. The first material is set in lines 1–3. First, the trained material file is imported, which contains the Mat_mxRock2 material object assigned to the first material. Lines 4–6 import the material file mxSoil.txt to generate the material directly which is assigned to the second position of the cell array Mats. The imported material is placed in the cell array Mats and directly imported into the model by the d.Mats = Mats command.

8.3.2 Set the Material for the Stratum (1) Cut stratums and assign materials During the process of packing a model, elements in each layer generate displacement by the effect of gravity. Therefore, before setting up the material, users need to delete the original defined group and re-layer the model. d.addGroup('slopeBottom',d.GROUP.layer1); d.protectGroup('slopeBottom','on'); d.delGroup({'layer1';'layer2';'layer3';'layer4';'layer5'}); C.layerNum=0; C.setLayer({'sample'},[2,3,4,5]);

8.3 Building a Three-Dimensional Slope Model

215

The elements of the bottom mold plate layer1 of the thin shell are the fixed elements that do not generate displacement; thus, it is not necessary to re-divide the stratums. The first and second line commands rename the bottom mold plate “slopeBottom” and add a protection label to prevent its elements from being accidentally deleted. Lines 3 and 4 delete all previously cut groups using the function d.delGroup and reset the C.layerNum to 0. Note that only the groups are deleted, not the elements of the group. The function C.setLayer is then run, using the 2nd–5th layers to re-divide the stratum and obtain the new layer1, layer2, and layer3, which correspond to the rock layer of the main slope, the gravel layer of the ancient landslide, and the additional slope layer, respectively, in Fig. 8.8. After the material is set, the elements will also generate displacement, so an additional slope layer needs to be retained. These three layers can be used to build the model (remove other active elements) and assign the material to the elements of these layers: gNames={'layer1';'layer2';'layer3'}; d.makeModelByGroups(gNames); d.setGroupMat('layer2','mxSoil'); d.groupMat2Model(gNames,1);

Lines 1 and 2 build the model using layer1, layer2, and layer3; line 3 sets the material of layer2 (the gravel layer of the ancient landslide) to mxSoil; finally, the material of the group is assigned to the elements. After the new material is assigned, the stress between the elements changes due to the change in stiffness, and iterative calculation is needed to rebalance the model. To speed up calculation of the numerical simulation, the rock mass elements that do not move and are outside the landslide area are set as the fixed elements: sX=d.mo.aX(1:d.mNum); sY=d.mo.aY(1:d.mNum); imH=302;imW=561;%height and width of image regionFilter=mfs.image2RegionFilter('slope/slopepack.png',imH,imW); sFilter=mfs.applyRegionFilter(regionFilter,sX,sY); sFilter=～sFilter; sId=find(sFilter); sId(sId＞d.mNum)=[]; d.addGroup('slopeWall',sId); d.defineWallElement('slopeWall'); d.protectGroup('slopeWall','on');

216

8 Modeling of Complex 3D Models

Lines 1 and 2 obtain the coordinates sX and sY of the active elements; imH and imW of line 3 are the height and width of the digital elevation matrix in code 3Slope0; because these are not saved, they are re-assigned; lines 4 and 5 import the image of the landslide area (the landslide area is shown in black) and the function used is described in detail in Sect. 3.3.1; lines 6–9 filter out the elements of the landslide area and define them as the slopeWall group; the final two lines set the elements of this group as fixed elements and add protection against accidental deletion. d.balanceBondedModel0(0.5); d.mo.mVis=d.mo.mVis*5; d.balanceBondedModel(0.5);%bond all elements and balance the model d.mo.setGPU('off');

After the setup is complete, a strong bond balance is used to relieve stress. First, a strong bond balance without friction is performed 0.5 times, at which point the stress is quickly balanced and the elements move quickly to a new position. The damping coefficient of elements is then increased by 5 times and a strong bond balance with friction is performed 0.5 times so that the vibration energy of the elements is quickly consumed and a balanced model is obtained. Because default damping of the system is inversely proportional to the number of elements in a single dimension, the default damping may be too small for a thin-layer model, where the damping coefficient is increased by 5 times and a balance is achieved once again to quickly consume the kinetic energy of the system. (2) Cut the stratum and assign the material again

d.delGroup({'layer1';'layer2';'layer3'}); C.layerNum=0; C.setLayer({'sample'},[1,3,4]);%set layers by surfaces C.setLayer({'sample'},[7,4]); gNames={'layer1';'layer2';'layer3'}; d.makeModelByGroups(gNames); d.setGroupMat('layer2','mxSoil'); d.groupMat2Model(gNames,1); d.mo.zeroBalance();

As the material is set and the model is balanced, the position of the element changes, and the stratum needs to be cut and set once more. The above code is the same as in the previous operation, therefore it will not be introduced line by line. The third line establishes the layer1 and the layer2, which represent the rock layer of main slope elements (including the thin shell bottom mold plate and the rock layer of the main slope) and the gravel layer elements of the ancient landslide, respectively. The fourth line command generates the block group layer3 of the slip source by cutting

8.3 Building a Three-Dimensional Slope Model

217

Fig. 8.9 Final three-dimensional slope model

the S_source layer (layer number is 7, Fig. 8.5) and the S0 layer (layer number is 4). It then uses the new layer1 to layer3 to build the final 3D slope model (Fig. 8.9). Finally, a strong bond balance is performed to complete the construction of the three-dimensional slope model.

8.4 Numerical Simulation of Landslide’s Motion Process In the code 3DSlope3, the initial crack of the slip source is set, the effect of gravity is applied, and numerical simulation of the three-dimensional landslide is completed by iterative calculation.

8.4.1 Setting of Numerical Simulation Parameters

…%initialize model status d.breakGroupOuter({'layer3'});%break the outer connection of the group d.breakGroup({'layer3'});%break the connection of the group visRate=0.00001; d.mo.mVis=d.mo.mVis*visRate; d.setStandarddT(); …%initialize model status

218

8 Modeling of Complex 3D Models

The beginning of the code of the third step is similar to other codes and will, therefore, not be introduced. The above lines 2 and 3 command disconnect the inner and outer connections and the intra-group connections of layer3 (i.e., the slip source). Because this simulation is a dynamic problem, lines 4 and 5 set the element damping to a smaller value; while line 6 d.setStandarddT sets the time step d.mo.dT to the standard value.

8.4.2 Iterative Calculations and Simulation Results After the setting of parameters is completed, iterative calculation of the landslide’s motion process is performed through the for loops: totalCircle=50; for i=1:totalCircle d.balance('Standard'); d.clearData(1); d.mo.setGPU('off'); save([fName num2str(i) '.mat']); d.calculateData(); d.mo.setGPU(gpuStatus); d.toc();%show the note of time; end …% save results

The landslide slides under the effect of gravity, and no displacement or stress load needs to be applied in the simulation. Therefore, it is only necessary to set a single layer of circulation for numerical calculation. The totalCircle is set to 50, which saves 50 intermediate files. The scale of this three-dimensional example reaches the level of kilometers, and the number of model elements is large. When the average radius of the element is 5 m, the discrete element model contains about 403,000 elements; therefore, the calculation is performed using Tesla P100 GPU. The time step of the numerical simulation is 2×10−4 s, and the calculation takes 15 h, which corresponds to 116.5 s in the real world. If a laptop is used for calculations, the element radius can be set to 10 m. Through numerical simulation, the displacement contour diagram of the landslide’s final packing state is obtained, as shown in Fig. 8.10.

8.4 Numerical Simulation of Landslide’s Motion Process

Fig. 8.10 Displacement field of the final packing state of the landslide

219

Chapter 9

Numerical Simulations of Dynamic Action

This chapter introduces the numerical simulations of dynamic action. Three examples are presented herein: the simulation of meteorite impact on the ground, mine slope blasting, and seismic dynamics. The initial conditions or loads only need to be set once for these simulations. For instance, in the meteorite example, the initial velocity only needs to be set in the meteorite part, whereas in the seismic dynamics’ example, only the initial displacement of the left boundary has to be set to generate the stress wave. Consequently, the computational cost of these numerical simulations are relatively small. In this chapter, all examples use two-dimensional models that can be carried out on a laptop and require tens of minutes to hours. If users want to generate a three-dimensional model, the value of parameter B.sampleL has to be >0; however, a high-performance desktop computer or GPU server is required to complete the simulation.

9.1 Meteorite Impact on the Earth This section presents a discrete element simulation of impact action through a twodimensional numerical simulation of a meteorite impact on the Earth (BoxCrash). The basic procedure for a meteorite impact simulation is to first build a packing model as the ground, build a round meteorite model at a certain distance above the ground, give this an initial velocity, and then let it hit the ground. By modifying the example code a bit, many physical processes can be simulated. For instance, reducing the size of the model and increasing the stiffness and cementing force of meteorite elements (or using clump) can simulate the process of a bullet breaking through a cement slab. Alternatively, by cutting the model and defining new components, the model can be changed to a Hopkinson rod test simulator.

© The Author(s), under exclusive license to Springer Nature Singapore Pte Ltd. 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9_9

221

222

9 Numerical Simulations of Dynamic Action

9.1.1 Packing Model of Particles In the BoxCrash1 code, the basic accumulation layer is built: … B.name='BoxCrash'; B.ballR=0.5; B.distriRate=0.2; B.sampleW=500; B.sampleL=0; B.sampleH=300; B.BexpandRate=4; B.type='topPlaten'; B.setType(); B.buildInitialModel();

The model is then named BoxCrash. The width of the model is set to be 500 m and the height to be 400 m, the radius of the model element is set to be 0.5 m (1.5–2 m is acceptable for low-precision simulation), and the dispersion coefficient is set to be 0.2. The model boundary is extended by four additional elements. The B.type = ‘topPlaten’ command is then used to generate a top plate to compact the model. Finally, the B.buildInitialModel command is executed to build the initial packing model. Following the construction of the initial packing model, operations such as deposition and compaction are required: … B.gravitySediment(); d.mo.aMUp(:)=0; B.compactSample(2);%input is compaction time …

Gravity sediment is performed using the B.gravitySediment command. To speed up compaction, the friction between model elements is set to 0 by the d.mo.aMUp (:) =0 command. The B.compactSample (2) command is then used to perform the second compaction. Finally, the current modeling data is saved. The packing model is shown in Fig. 9.1 and contains 153,000 elements.

9.1.2 Building a Meteorite Model The basic procedures for building a meteorite model using BoxCrash2 code are as follows: first, select all elements in one circular area of the packing model; second,

9.1 Meteorite Impact on the Earth

223

Fig. 9.1 Packing model

add these elements as a group and export them as a meteorite structure; finally, add the elements of the meteorite structure to the model. (1) Flattening the accumulation layer using a filter The second step involves loading the packing model built in the first step. To obtain a flat surface and retain a certain space above the ground, a filter is used to remove elements in the upper half of the packing model. The code is as follows: mZ=d.mo.aZ(1:d.mNum); topLayerFilter=mZ＞max(mZ)*0.5; d.delElement(find(topLayerFilter));

The Z-coordinate (mZ) of all active elements in the model can be obtained using the first line command. The second line command filters out active elements located in the upper half of the packing model and records them in the Boolean matrix topLayerFilter. The find function is then used to locate the corresponding element number of the above elements, following which the d.delElement command is used to delete the selected elements from the model. Finally, the packing model shown in Fig. 9.2 is obtained, which contains approximately 75,000 active elements. (2) Setting the material Two kinds of different materials then need to be set and loaded in the model for the meteorite and the stratum:

224

9 Numerical Simulations of Dynamic Action

Fig. 9.2 Packing model after the upper half of the model is deleted

… matTxt=load('Mats\WeakRock.txt'); Mats{1,1}=material('WeakRock',matTxt,B.ballR); Mats{1,1}.Id=1; matTxt2=load('Mats\StrongRock.txt'); Mats{2,1}=material('StrongRock',matTxt2,B.ballR); Mats{2,1}.Id=2; d.Mats=Mats; d.groupMat2Model({'sample'},1); …

Material 1 is WeakRock and is used as the material for the packing model; Material 2 is StrongRock and is used as the material for the meteorite model. The properties of the two loaded materials are shown in Table 9.1. It is important to note that the material properties are directly inputted here, and there are errors between the tested mechanical properties of the model and the set values (see Sect. 3.4 for details). Finally, the Table 9.1 Mechanical properties of WeakRock and StrongRock materials The Material name WeakRock

Young’s Poisson’s Uniaxial Uniaxial Coefficient Density/(kg/m3 ) modulus/GPa ratio tensile compression of internal strength/MPa strength/MPa friction 5

StrongRock 10

0.2

2

20

0.6

2600

0.15

10

100

0.6

2850

9.1 Meteorite Impact on the Earth

225

material of the packing model element is set by the d.groupMat2Model({‘sample’}, 1) command. (3) Building meteorite structures A circular area in the packing model is then selected to build a meteorite structure: sampleId=d.GROUP.sample; sX=d.aX(sampleId);sZ=d.aZ(sampleId);sR=d.aR(sampleId); discCX=mean(sX);discCZ=mean(sZ); discR=20; discFilter=(d.aX-discCX).^2+(d.aZ-discCZ).^2＜discR^2; d.addGroup('Disc0',find(discFilter)); discObj=d.group2Obj('Disc0');

The first line command obtains the Id of the sample element (layer) and stores it in the sampleId matrix. sX in the second line represents the X-coordinate of the stratum element, sZ represents the Z-coordinate, and aR represents the radius. discCX (X-coordinate of disk center) in the third line is the average of the X-coordinates of all stratum elements and discCZ is the average of Z-coordinates: the coordinates (discCX, discCZ), therefore, represent the center point of the rectangular stratum. The discR in the fourth line is the radius of the selected circular area and signifies that the radius of the meteorite is 20 m. In the fifth line, a circular area with a center of (discCX, discCZ) and a radius of 20 m is selected, following which a filter matrix discFilter is established. Finally, the element selected by discFilter is added to the Disc0 group through the addGroup command: this converts the Disc0 group into the discObj structure (Fig. 9.3) by using the group2Obj command for further use. (4) Import the meteorite structure into the model The meteorite structure is then imported into the model: discId=d.addElement('StrongRock',discObj); d.addGroup('Disc',discId); disZ=max(sZ+sR)-min(discObj.Z-discObj.R); d.moveGroup('Disc',0,0,disZ); d.balanceBondedModel0();

Line 1 adds discObj into the model by using the addElement command. The material is StrongRock and the element Id is discId. Line 2 adds the discId to the Disc group by using the addGroup command. The parameter disZ in line 3 denotes the distance over which the Disc group needs to move in the Z-direction. Line 4 moves the Disc group slightly above the ground using the moveGroup command. Finally, the model is balanced, the final version of which is shown in Fig. 9.4. The modeling data for the second step are then saved using the save command.

226

9 Numerical Simulations of Dynamic Action

Fig. 9.3 Meteorite structure

Fig. 9.4 Packing and meteorite model

9.1.3 Simulation of Meteorite Impact Process BoxCrash3 first loads the calculation data obtained in the second step. It then initializes the model and sets relevant simulation parameters.

9.1 Meteorite Impact on the Earth

227

d.mo.isHeat=1; visRate=0.0001; d.mo.mVis=d.mo.mVis*visRate; discId=d.GROUP.Disc; d.mo.mVZ(discId)=-1000; d.setStandarddT(); d.mo.dT=d.mo.dT*0.05;

d.mo.isHeat = 1 records heat generation during the simulation. In the numerical simulation of dynamic action, the damping coefficient has to be small enough to match the actual situation (see Sect. 4.3.3 for an explanation). In the current example, d.mo.mVis is set to be 1/10000 of the optimal damping. Meanwhile, the speed of the meteorite element is set to be −1000 m/s using d.mo.mVZ(discId) = −1000 command: thus, the meteorite element hits the ground at a speed of 1 km/s. Finally, the calculation time step is appropriately reduced (see Sect. 4.3.3 for an explanation) and set to 1/20 of the standard time step. Once simulation parameters are set, the numerical calculation of the impact is performed by the for loop: totalCircle=40; for i=1:totalCircle d.mo.setGPU(gpuStatus); d.balance('Standard',0.4); d.mo.setGPU('off'); d.clearData(1); save([fName num2str(i) '.mat']); d.calculateData(); end

totalCircle = 40 denotes 40 loops and saves 40 intermediate process files: 0.4 times the standard balance is performed per cycle calculation. When the GPU is closed and the data is compressed, the calculation data is saved using the save command. Following the calculation, various field diagrams and animations of the impact process can be obtained through postprocessing. GIF animations of the numerical simulations of the fine model are available at http://matdem.com. Figure 9.5 shows the change in stress distribution StressZZ over a period of 0.42 s. The model contains 410,000 elements that provide a fine representation of the generation and propagation of stress waves. The figure shows that when the meteorite touches the ground, immense stress is generated. The stress wave then spreads and is reflected when it meets the lower boundary. At the same time, an enormous crater is formed on the ground. Figure 9.6a and b show the heat distribution of the elements at the initial impact time and 0.21 s, respectively. As shown, most of the heat is generated at the interface between the meteorite and the ground. The temperature can then be obtained by

228

9 Numerical Simulations of Dynamic Action

Fig. 9.5 Impact process diagram (StressZZ)

(a) Initial impact moment;

(b) 0.21 second.

Fig. 9.6 Heat distribution during the simulation

the heat generated. The temperature and pressure at which the meteorite hits the ground are then studied in conjunction with Fig. 9.5. By changing parameters, the influence that the angle and velocity of the meteorite impacting the ground on the crater morphology and stress wave characteristics can be studied. In this case, the lower boundary is fixed so that reflected waves are generated. An adsorption boundary then needs to be created to properly perform further numerical simulations.

9.2 Mine Slope Blasting

229

9.2 Mine Slope Blasting The mine slope blasting simulation is based on the BoxModel code, which was originally used for 2D and 3D numerical simulations of landslides. The BoxModel code is divided into three steps. BoxModel1 is the general accumulation modeling process; BoxModel2 uses an Excel chart to define the stratum that contains a weak interlayer and cuts the slope surface, and BoxModel3 applies gravity to the model to simulate the heat generation process within the landslide (see Sect. 10.1 for details). The BoxModel1 and BoxModel2 codes need to be run sequentially to generate a slope, following which the Model3Explosive code is used to implement the numerical simulation of the mine slope blasting process. The basic principles of blasting simulation are to identify elements in a certain area and set them as a blasting point; then, increase the radii of these elements and allow them to overlap to create enormous pressure and elastic strain energy. In the numerical simulation, the elements of the blasting point move rapidly outward under internal pressure. These elements release the strain energy so that the blasting action can be simulated.

9.2.1 Slope Model BoxModel1 is identical to the first step of most examples and thus requires no further explanation. In this section, the 2D packing model obtained in the first step (B.sampleL = 0) will be used directly. After loading the packing model data generated in the first step, the main model code involving BoxModel2 is as the following two parts: (1) Importing data and cutting the model C=Tool_Cut(d);%cut the model lSurf=load('slope/layer surface.txt');%load the surface data C.addSurf(lSurf);%add the surfaces to the cut C.setLayer({'sample'},[1,2,3,4]); gNames={'lefPlaten';'rigPlaten';'botPlaten';'layer1';'layer2'; 'layer3'}; d.makeModelByGroups(gNames);

First, the discrete element accumulation obtained by BoxModel1 is used to construct the slope surface. This is primarily achieved using the Tool_Cut object C and addSurf command to read elevation data in the notepad document. To view the layer conveniently, these data are recorded in the BoxModel data table entitled “Landslide Elevation.xls”, as shown in Table 9.2. The corresponding Excel line chart is shown in Fig. 9.7a. After elevation data is set in Excel, and it is copied to

230

9 Numerical Simulations of Dynamic Action

Table 9.2 Elevation data used to generate the line chart in Excel Line number

Surface 0

Coordinates

x

y

z

Surface 1 x

y

z

x

y

z

x

y

z

Elevation data

1

0

0

1

0

29

1

0

33

1

0

43

4

0

0

4

0

26

4

0

30

1

0

42

7

0

0

7

0

22

7

0

26

7

0

42

10

0

0

10

0

16

10

0

20

10

0

39

⦙

⦙

⦙

⦙

⦙

⦙

⦙

⦙

⦙

⦙

⦙

⦙

(a) Elevation data in excel table;

Surface 2

Surface 3

(b) A slope model generated by th line chart diagram based on elevation data.

Fig. 9.7 Slope model generated by Excel line chart data

the Notepad document for easy reading. In Fig. 9.7a, only the elevation between 0 and 80 m is defined. As shown in Fig. 9.7b, MatDEM automatically extends outward according to existing elevation data and divides the stratum of 80–100 m. (2) Setting material and balancing the model

%----------set material of model matTxt=load('Mats\Soil1.txt'); Mats{1,1}=material('Soil1',matTxt,B.ballR); Mats{1,1}.Id=1; matTxt2=load('Mats\Soil2.txt'); Mats{2,1}=material('Soil2',matTxt2,B.ballR); Mats{2,1}.Id=2;

9.2 Mine Slope Blasting

231

Table 9.3 Mechanical properties of Soil1 and Soil2 Material Young’s Poisson’s Uniaxial Uniaxial Coefficient Density/(kg/m3 ) name modulus/MPa ratio tensile compression of internal strength/kPa strength/kPa friction Soil1

20

0.14

20

200

0.8

1900

Soil2

10

0.18

2

20

0.6

2000

d.Mats=Mats; %---------assign material to layers and balance the model d.setGroupMat('layer2','Soil2'); d.groupMat2Model({'sample','layer2'}); d.balanceBondedModel();

The aforementioned code sets two materials, Soil1 and Soil2, whose mechanical properties and densities are recorded in the Notepad document under the Mats folder. The material object is directly generated by defining material properties and yields the material array Mats. As shown in Table 9.3, the strength of Soil2 is only 1/10 that of Soil1, and the internal friction coefficient is smaller; it is, therefore, regarded as the weak layer. Because the default material number of the element is 1, users simply need to set the weak layer material (layer2) as Soil2 and use the groupMat2Model command to assign material properties to the elements. Finally, the model is balanced and the discrete element model shown in Fig. 9.7b is obtained, in which layer2 is the weak layer.

9.2.2 Setting the Blasting Point and Blasting Energy

… B.name=[B.name 'Exploision']; d.mo.aBF=d.mo.aBF*10; d.mo.aFS0=d.mo.aFS0*10;

The default mechanical properties of model materials in the second step are weak; therefore, to ensure the slope is stable, the third step increases the breaking force (aBF) and initial shearing force (aFS0) of elements by ten times. The following code not only defines the location and radius of the blasting point in the slope but also searches for the corresponding element number bombId and defines it as the Bomb1 group.

232

9 Numerical Simulations of Dynamic Action centerX=15;centerZ=20; bombR=2; dX=d.mo.aX-centerX; dZ=d.mo.aZ-centerZ; bombId=find((dX.*dX+dZ.*dZ)＜bombR.*bombR);%get the Id of bomb d.addGroup('Bomb1',bombId);%add a new group d.mo.zeroBalance(); d.recordStatus();

The following command sets the group number of the blasting point element to 1 and uses the d.show function to display the position of the blasting point (Fig. 9.8a). It then calculates the average Stress and records it in d.data.Stress. Finally, the d.show(‘Stress’) command is run to obtain the average stress value, as shown in Fig. 9.8b. d.setData(); d.data.groupId(d.GROUP.Bomb1)=1; d.show('groupId'); d.data.Stress=(abs(d.data.StressXX)+abs(d.data.StressZZ)); d.show('Stress');

In this simulation, blasting energy is generated by increasing the radii of blasting elements. In the following code, the element radii are increased by 40% and the new system state is recorded. Figure 9.8b depicts the StressZZ distribution at this time. As shown, the stress at the blasting point is extremely large. To calculate the blasting energy, the original elastic strain energy is recorded by oldKe, whereas the elastic strain energy after increasing the radii of elements is recorded by newKe. Thus,we acquire the elastic strain energy which raises varying with the increase in the radii of blasting point elements.

Fig. 9.8 Schematic diagram of the blasting point element. a Group number; b Average stress

9.2 Mine Slope Blasting

233

oldKe=d.status.elasticEs(end);%record the original energy bombExpandRate=1.4; d.mo.aR(bombId)=d.mo.aR(bombId)*bombExpandRate; d.mo.zeroBalance(); d.recordStatus(); newKe=d.status.elasticEs(end); dKe=newKe-oldKe;%calculate the energy increment fs.disp(['Energy of the bomb is'num2str(dKe)'J','～='num2str (dKe/4.2e6)'kg TNT']);

The final command converts energy into TNT equivalents to quantify blasting energy. This shows that the simulated blasting energy is equal to 4.3 kg of TNT explosive. Energy of the bomb is 17973262.3911J ～=4.2793 kg TNT

It should be noted that, in this example, a larger blasting point radius is used to show the position of the blasting point more clearly. In practical applications, a small region radius can be set and the blasting energy can be amplified by increasing the stiffness of blasting point elements. Energy can also be increased by applying a large initial velocity to the element.

9.2.3 Iterative Calculations and Simulation Results The beginning of the third step involves regular loading and initialization, for which no further explanation is required. Because this example is one of dynamic actions, it is necessary to set the damping coefficient (d.mo.mVis) of the active element so that it is small enough to simulate air resistance. The d.mo.setGPU(‘auto’) command is then run to test the speed of the GPU and CPU, the faster of which is used for subsequent calculations. visRate=0.00001; d.mo.mVis=d.mo.mVis*visRate; gpuStatus=d.mo.setGPU('auto');

After setting up the model, the following code is used to implement iterative calculations and save data files. The time step of the numerical simulation is 3 × 10−4 s. The simulation is divided into 20 cycles, and 0.1 times the standard balance is performed per cycle. This example simulates 5 s in the real world. Figure 9.9a

234

9 Numerical Simulations of Dynamic Action

(a) 0.1s;

(b) 0.5s

Fig. 9.9 Element velocity field distribution

presents a velocity field diagram of elements at 0.1 s. This clearly shows that the stress wave propagates outward around the blasting point and forms a large element velocity field (40 m/s) on the slope. Figure 9.9b shows the element velocity field at 0.5 s, with several surface elements splashing into the air. totalCircle=20; d.tic(totalCircle); fName=['data/step/'B.name num2str(B.ballR)'-'num2str(B. distriRate)'loopNum']; save([fName '0.mat']); for i=1:totalCircle d.mo.setGPU(gpuStatus); d.balance('Standard',0.1); d.clearData(1); save([fName num2str(i)'.mat']); d.calculateData(); d.toc();%show the note of time end d.show('mV');

Figures 9.10a and b show the velocity field distribution and bond of the elements at 2 s. There are clear radial cracks in the slope body around the blasting point. Surface elements begin to slide down quickly under the action of blasting kinetic energy and gravity.

9.3 Seismic Wave Propagation

(a) Element velocity field at 2 s;

235

(b) The diagram of element bonds

Fig. 9.10 Numerical simulation results at 2 s

9.3 Seismic Wave Propagation In this section, the Earthquake example is used to introduce the generation of seismic waves in a discrete element numerical simulation. The basic steps of the simulation are as follows: first, to create the stratum accumulation model and cut it to generate the topographic and soft soil layer; second, to create a buffer block near the left boundary; and finally, to move the boundary to generate seismic waves.

9.3.1 Establishment of Topography and Stratification In Earthquake 1, the model box is set as 0 × 200 × 160 m to ensure that the model is a two-dimensional model box; the average radius of elements is 0.2 m, and the distribution coefficient is 0.2. The remaining steps are the same as in other examples; thus, no further description is required. The code of Earthquake 2 is divided into two parts: (1) Setting the Material The packing model established in the first step is loaded, the model status is initialized, and then import the materials.

236

9 Numerical Simulations of Dynamic Action

Table 9.4 Mechanical properties of Soil1and Rock1 Material Young’s Poisson’s Uniaxial Uniaxial Internal Density Name Modulus/MPa ratio tensile compressive frictioncoefficient kg/m3 strength/kPa strength/kPa Soil1

20

14

20

200

0.8

1900

Rock1

77.1 × 103

18

17.3 × 103

216 × 103

0.5

2850

… matTxt=load('Mats\Soil3.txt');%material of soil Mats{1,1}=material('Soil1',matTxt,B.ballR); Mats{1,1}.Id=1; matTxt2=load('Mats\Rock1.txt'); Mats{2,1}=material('Rock1',matTxt2,B.ballR);%material of rock Mats{2,1}.Id=2; d.Mats=Mats; …

Two types of materials are introduced at this stage, the properties of which are listed in Table 9.4. The first is Soil1, the material number of which is 1: this is used as the soft soil layer material in the mountain model. The second is Rock1, the material number of which is 2: this is used as the rock material in the mountain model. The cell arrays of Mats containing these two materials are then assigned to d.Mats. (2) Creating the Mountain Model To cut the stratum established in the first step, Object C of Tool_Cut class is created: C=Tool_Cut(d);%cut the model lSurf=load('slope/Earthquake.txt');%load the surface data C.addSurf(lSurf);%add the surfaces to the cut C.setLayer({'sample'},[1,2,3,4]);%set layers according geometrical data gNames={'lefPlaten';'rigPlaten';'botPlaten';'layer1';'layer2';'l ayer3'}; d.makeModelByGroups(gNames);%build new model d.setGroupMat('layer1','Rock1'); d.setGroupMat('layer2','Soil1'); d.setGroupMat('layer3','Rock1'); d.groupMat2Model({'layer1','layer2','layer3'},2); d.balanceBondedModel0();

The elevation data in Earthquake.txt are then loaded by the second line command and stored in lSurf . Data include elevation information on the top and bottom of

9.3 Seismic Wave Propagation

237

Fig. 9.11 a A polyline table defined in the Elevation.xls; b Stratigraphic model generated from polyline table data

the mountain and every middle layer. These data are recorded in the BoxEarthquake worksheet entitled “Elevation.xls,” the corresponding excel line chart of which is shown in Fig. 9.11a. In the third line, addSurf is used to import elevation data into the model cutting tool C. Because there are four layers of stratum interface elevation data, three strata will be generated when using setLayer to cut the sample group. These layers will automatically be named as “layer1”, “layer2”, and “layer3” from the bottom to the top. Subsequently, the cell array gName is created, which contains the group names needed to create a new model. The makeModelByGroups (gNames) command is then used to create a new model and comprises the following steps: Lines 7–9 use setGroupMat to declare the materials for each group (stratum); groupMat2Model is used to assign material to the specified group; the remaining group is assigned material number 2; and finally, the model is built. Using strong cementation equilibrium (balanceBondedModel0 function) generates a mountain model, as shown in Fig. 9.11b. The mountain model consists of 121,000 units. (3) Creating Buffers In this simulation, displacement loading is used to generate seismic waves. Because the displacement change is completed instantaneously in the discrete element numerical simulation, the rock mass will also be destroyed instantaneously when a large displacement is applied. Therefore, to avoid such an occurrence, it is necessary to define the block area near the left boundary as a buffer zone (LeftBlock group in Fig. 9.11b) and generate seismic waves effectively. The code is as follows:

238

9 Numerical Simulations of Dynamic Action mX=d.mo.aX(1:d.mNum); leftBlockId=find(mX =matContents(1))&clumpFilter;

The command above filters out elements belonging to the clump particles and generates the filter for feldspar (mat1Filter) and pyroxene (mat2Filter). The clumpFilter = groupId 1; tunnelId=find(columnFilter&zFilter); d.delElement(tunnelId);

To dig holes in the stratum, you need to run the custom function getColumnFilter under the fun folder. This function is used in both the example BoxTunnel and BoxTunnelNew. The code above uses this function to generate a filter matrix of the cylinder area in the middle of the stratum according to the set parameters of the cylindrical cutting. It then deletes the corresponding elements in the model.

10.3 Thermal Coupling of Energy Pile

257

tubeId=d.addElement(1,tubeObj);%add a slope boundary d.addGroup('ringTube',tubeId);%add a new group d.setClump('ringTube');%set the pile clump d.moveGroup('ringTube',(max(mX)+min(mX))/2,(max(mY)+min(mY))/2,1); d.minusGroup('sample','ringTube',0.4);%remove overlap elements from sample innerTubeId=find(d.mo.aR==minBallR); d.addGroup('innerTube',innerTubeId);%add a new group

The code above imports the structure object of the pipe pile into the model and defines it as a group; because the elements of the pile overlap, the pile needs to be declared as a clump and moved to the hole in the center of the model. At this point, the minusGroup function is used to delete part of the stratum elements that are in contact with the pile (see Sect. 6.1.2 for details on this command). To apply the temperature load easily in the third step, the element inside the energy pile is declared as the innerTube group. d.addFixId('X', d.GROUP.ringTube); d.addFixId('Y', d.GROUP.ringTube); d.addFixId('Z', d.GROUP.ringTube); d.balanceBondedModel0();%bond the elements and balance the model d.breakGroup();%break all connections d.balance('Standard');%balance the model

To prevent the pile from moving and tilting in the next balance calculation, the d.addFixId function is used to lock the degrees of freedom of the pile element in the X-, Y-, and Z-direction. The strong cementation balance function is then run to balance the sudden change in stress caused by material transformation. All the elements are then disconnected so that the elements in the stratum accumulate again under gravity and through the close contact with the pipe pile, generating the energy pile–stratum interaction model shown in Fig. 10.8.

10.3.2 Numerical Simulation of Thermal Coupling Process (1) Parameter Initialization In this example, the basic idea for realizing the thermal coupling of the energy pile is as follows: apply a constant temperature load to the inner layer of the pile; determine the change in the temperature of the element according to the temperature difference and the temperature coefficient between the contact elements; based on the relationship between the element expansion rate and temperature, determine the radius of the element and achieve thermal coupling simulation through the equilibrium iterative calculation.

258

10 Multi-field Coupling Numerical Simulation

There is no temperature attribute of the element in d.mo. It is, therefore, necessary to add an element temperature parameter aT in the structure d.mo.SET to record the temperature of all the elements in the model: innerTubeId=d.GROUP.innerTube; d.mo.SET.aT=ones(d.aNum,1)*15;%initial temperature is 15 degrees initialT=d.mo.SET.aT(1:d.mNum); %record the initial temperatures innerTubeT=25;%temperature of innerTube group d.mo.SET.aT(d.mNum+1:d.aNum)=-1000;%boundary is insulated mdR0=zeros(d.mNum,1);%deviation of radius of active elements

The command above initializes the temperature of all elements to 15 °C, and records the temperature of the active element with initialT; it then sets the temperature (innerTubeT) of the inner element of the energy pile to a higher value, such as 25 °C. Thus, the temperature difference between the energy pile and the stratum is formed; the temperature of the boundary element is set to −1000 °C. In the iterative calculation, the boundary is set as the adiabatic boundary according to a temperature value that cannot exist. If the boundary temperature is constant, it is set to another temperature. mdR0 records the radius increase in the active element when the last neighbor is retrieved, which will be specified in the following subsection. (2) Thermal Conduction Calculation The thermal conduction calculation and the thermal coupling calculation are realized by a conventional two-layer for loop, in which the data file is saved in the outer loop and the numerical calculation is performed in the inner loop. The following is the thermal conduction calculation part of the code in the inner loop: d.mo.SET.aT(innerTubeId)=innerTubeT;%assign temperture nRow=ones(1,size(d.mo.nBall,2)); NBall=gather(d.mo.nBall); nTempDiff=d.mo.SET.aT(NBall)-d.mo.SET.aT(1:d.mNum)*nRow;

The first line of the code above sets the temperature of the inner element of the energy pile to 25 °C. Line 3 uses the gather function to put the data in d.mo.nBall into the CPU. In the numerical calculation, the matrix data in d.mo may be GPU data, the matrix substitution operation of GPU data is very slow (such as aT(d.mo.nBall)), and it is easy to make mistakes, therefore the gather command is used to get the data in d.mo. When using custom parameters and multi-field coupling numerical simulation, special attention should be paid to the use of GPU data to avoid a sharp drop in calculation speed and error reporting. The Line 4 command obtains a matrix nTempDiff the same size as its neighbor matrix nBall, which records the temperature difference between all active elements and their neighbors. This example shows how to use MatDEM for multi-field coupling studies. For convenience, the thermal conduction calculation is simplified: when two elements undergo heat exchange, the amount of temperature change (nTempFlow) is equal

10.3 Thermal Coupling of Energy Pile

259

to the product of the “coefficient of thermal conductivity” (0.02 in this example) and the difference of temperature between the two elements. The following code demonstrates how to perform a thermal conduction simulation: nThermalC=0.02;%Coefficient of thermal conductivity cbFilter=gather(d.mo.cFilter|d.mo.bFilter); nBoundaryFilter=(d.mo.SET.aT(NBall)==-1000); inslatedFilter=( ∼ cbFilter|nBoundaryFilter); nTempFlow=nTempDiff.*nThermalC; nTempFlow(inslatedFilter)=0; mTempFlow=sum(nTempFlow,2); d.mo.SET.aT(1:d.mNum)=d.mo.SET.aT(1:d.mNum)+mTempFlow;

The “coefficient of thermal conductivity” between the connections nThermalC is set to 0.02. cbFilter defines the connection of elements with force, and only heat is transmitted in these connections. The third line selects the boundary connection filter nBoundaryFilter, these connections are adiabatic. Lines 4 and 5 calculate the “temperature conduction quantity” between the elements. The matrix nTempFlow is summed in the row direction to obtain the temperature change (mTempFlow) of the active element in one heat exchange, the temperature of each active element before the heat exchange is then recorded in initialT and the temperature after heat exchange is calculated according to mTempFlow. It should be noted that nThermalC is a dimensionless parameter and the actual coefficient of thermal conductivity is dimensioned as m2 /s, which is proportional to the contact area and inversely proportional to time. There is a need to improve this part of the code to achieve an accurate and detailed numerical simulation of thermal conduction. Figure 10.9 shows the simulation of thermal conduction, with heat being conducted from the pile to the soil layer.

(a) Temperature field Fig. 10.9 Thermal coupling simulation of energy piles

(b) Displacement field

260

10 Multi-field Coupling Numerical Simulation

(3) Thermal Coupling Calculation In the calculation of thermal conduction, it is necessary to calculate the radius of the element according to the temperature to make it expand or shrink: expandRate=0.001;%expanded by 0.1% per mdR=d.mo.aR(1:d.mNum).*(d.mo.SET.aT(1:d.mNum)-initialT) *expandRate; d.mo.aR(1:d.mNum)=d.aR(1:d.mNum)+mdR;

The code above implements the effect of the element temperature on its radius. expandRate defines the “thermal expansion rate,” which is uniformly set to 0.001 in this example, thus the element radius increases by 0.1% for every 1 °C increase by temperature. In actual simulations, the expansion properties of each element need to be set according to the nature of the material. The line 2 command calculates the expansion amount mdR1 of the element radius versus the initial radius (d.aR) according to the current temperature and the initial temperature of the element. The line 3 command will obtain the element radius at that time and realize the effect of temperature on the element radius. In Sect. 10.2.3, when the element expands it may come into contact with the new element. So the d.mo.setNearbyBall function, therefore, needs to be run to update the neighbor matrix. In this example, to reduce the calculation (reducing the number of neighbor retrievals) when the element expands, an initial determination is made as to whether the element is likely to be in contact with the new element and the neighbor matrix is updated when it meets the condition. The following code implements this function: maxDis=gather(max(max(abs(d.mo.dis_mXYZ),[],2)+(mdR1-mdR0))); if(maxDis > 0.5*d.mo.dSide) fs.disp(['balanceTime' num2str(d.mo.totalT) '- > expand- > setNearbyBall']); d.mo.setNearbyBall(); mdR0(:)=mdR1; end

In the code above, the maximum displacement maxDis of the element in a certain coordinate direction (including the surface displacement caused by the expansion) is obtained by the line 1 command, wherein mdR1-mdR0 obtains the increase in the element radius since the last neighbor retrieval. When maxDis > 0.5*d.mo.dSide (see Sect. 3.5.3), run the neighbor retrieval function d.mo.setNearbyBall. The code above can be replaced by using d.mo.setNearbyball, although the amount of calculation will increase. Finally, iterative calculations are performed and the simulation state recorded: d.mo.balance(); d.recordStatus();

10.3 Thermal Coupling of Energy Pile

261

The core of this sample code is the custom parameter d.mo.SET.aT, which is used to record the temperature of the element and calculate the change in element temperature in the numerical iteration calculation. When users perform secondary development of other multi-field couplings, the custom parameters can also be recorded in the structure d.mo.SET. The sample code SoilCrackNew also uses a series of custom parameters to achieve numerical simulation of soil dehydrating and cracking processes. The basic principle is extremely close to this example and can be referred to each other, therefore they will not be described here.

10.4 Ground Subsidence and Ground Fissures 10.4.1 Cutting the Stratum Model Ground subsidence and ground fissures can be caused by over-exploited groundwater. When the groundwater level drops, according to the principle of effective stress, the total stress is constant. If the pore water pressure decreases, the effective stress will increase and the ground will settle. However, the thickness of the aquifer is usually non-uniform, causing differential settlement. When the differential settlement exceeds the limit that the soil can withstand, the ground fissure will be generated locally. In MatDEM, the example code for land subsidence and ground fissure is LandSubsidence 1-3. LandSubsidence1 establishes the initial stratigraphic packing model. LandSubsidence2 reads the elevation data file from the outside and then uses the model cutting tool Tool_Cut to cut the stratum into the undulant upper and lower layers, respectively. It then sets the material properties of the sand layer and the bedrock, wherein the bedrock element is set as a fixed element (Fig. 10.10). The first and second steps are common steps. For details, please refer to the related chapters.

Fig. 10.10 Numerical model of sand layer and bedrock

262

10 Multi-field Coupling Numerical Simulation

The third step simulates the deformation and cracking of the sand layer when the groundwater level drops significantly. For sand, silt, etc., which exhibit weak surface activity, the pore water pressure in saturated soil is equivalent to the upward buoyancy of the soil particles. Therefore, when simulating the buoyancy of groundwater, the Z-direction body force of the element below the water level is given by d.mo.mGZ minus the corresponding buoyancy. The relevant code is as follows: mGZ0=d.mo.mGZ; waterDensity=1e3; mR=d.mo.aR(1:d.mNum); mVolumn=4/3*pi*mR.^3; mBuoyancy=waterDensity*9.8*mVolumn; waterTable1=60; waterTable2=30;

In the code above, mGZ0 is the body force (i.e., gravity) of the element in the Z-direction under waterless conditions; waterDensity is the density of water; and the 3–5 lines of code calculate the buoyancy of each active element when below groundwater level. This is recorded in the matrix mBuoyancy; waterTable1 is the highest water level at the beginning and waterTable2 is the final lowest water level. During the simulation, waterTable is reduced from waterTable1 to waterTable2 several times.

10.4.2 Numerical Simulation of the Decline of Water Level There is no groundwater in the model established in the second step, therefore the model should be rebalanced after the introduction of groundwater in the third step: mZ=d.mo.aZ(1:d.mNum); waterFilter=mZ < waterTable1; d.mo.mGZ=mGZ0+mBuoyancy.*waterFilter; d.balanceBondedModel0(); d.mo.bFilter(:)=true; d.balance('Standard',3);

The waterFilter is the filter matrix with the same dimension as d.mo.mGZ. If the Z-coordinate of an element is smaller than the waterTable, its corresponding value in the waterFilter is 1, otherwise it is 0. In the next line 3 command, mBuoyancy and waterFilter are multiplied to obtain the buoyancy of each active element (0 above the groundwater level), and mGZ0 then add to obtain the current body force of each active element. It is important to note that, in MatDEM, the Z-axis is oriented vertically upward, therefore users need to pay attention to the sign when calculating the body force.

10.4 Ground Subsidence and Ground Fissures

263

The model is then initialized and the numerical simulation sets up: d.getModel(); d.resetStatus(); d.mo.isCrack=1; d.mo.isHeat=1; d.setStandarddT();

The numerical calculation code for ground subsidence and ground fissure in this example is as follows: totalCircle=(waterTable1-waterTable2)/5; for i=1:totalCircle waterTable=waterTable1-5*i; waterFilter=mZ < waterTable; d.mo.mGZ=mGZ0+mBuoyancy.*waterFilter; d.balance('Standard',3); end

Because the decline in groundwater level is a continuous process, it is necessary to simulate the gradual decline through the for loop, calculate the body forces of all stratum elements in the Z-direction at this time, and then rebalance the model. The simulation results are shown in Fig. 10.11. When the water level declines, the thick part of the sand layer settles further. Due to the fluctuation of the bedrock, large differential settlement occurs and a ground fissure is generated. For more accurate simulations, the loop variables totalCircle and stepNum can be set for a double for loop (see Sect. 4.3 for the values of two variables).

Fig. 10.11 Ground subsidence and ground fissures (color represents Z-direction displacement)

Appendix A

Properties of Classes

Appendix Properties of Classes Properties of obj_Box Class obj_Box is a box of simulation, which constructs various models in a rectangular area, almost all of the secondary development is based on the Box model. The following input parameters “varargin” indicate the number of input parameters is variable.

Name of properties Type of data

Introduction

Lang

Char

Language of software

randomSeed

Double

Random seed, the default value is 1

distriRate

Double

The dispersion coefficient of element diameter, and the ratio of maximum diameter to minimum diameter is (1+rate)2 , the default is 0.25

GPUstatus

Char

Initial status of GPU, it can be “off,” “on,” “auto,” and “fixed” (locked for CPU calculation), the default value is “auto”

isUI

Logic

Whether to run in the window program, set 0 or 1, the default value is 1. when it is 0, the d.show command will draw a picture in the new window

edit_output

–

Message field object, system parameters, do not modify

uniformGRate

Logic

It can be 1 or 0, to determine whether uniform g is used for gravity deposition, the default value is 0

Surf

Struct

Polygons for splitting models, refer to the example of user_BoxModel

Name

Char

The name of the model (continued)

© Science Press 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9

265

266

Appendix A: Properties of Classes

(continued) Name of properties Type of data

Introduction

Type

Char

Type of model, it can be “none,” “botPlaten,” “topPlaten,” “General Slope,” “Triaxial Compression,” and the default value is “topPlaten.” When the function B.setType() is called, the value of B.platenStatus is determined according to the type and used to generate the corresponding pressure platen

isClump

Logic

Define whether the model elements are clump elements

d

Build class

Object of build class

g

Double

Gravitational acceleration, the default value is -9.8m/s2

TAG

Struct

Recorded the information of simulation for recording and outputting information, and it can be used to save all kinds of output data

SET

Struct

Record the setup information of the numerical simulation, and save custom parameters in secondary development

is2D

Logic

Whether it is a two-dimensional model, the default value is 0, i.e., it is not a two-dimensional model

GROUP

Struct

Record all groups, and the name of group cannot begin with group

Mo

Struct

Structure of model elements, including pressure platen

Bo

Struct

Structure of boundary elements

Mats

Cell array

Cell array of material

ballR

Double

Average radius of elements

modelH_rate

Double

The increase ratio of the model boundary, because the height of sample after gravity deposition will be lower than the height of boundary, it is necessary to increase the height of the post-deposition model in line with expectations. The default value is 1, which means no increase

X

Array of aNum×1

X-coordinate array of the elements when elements are initially generated

Y

Array of aNum×1

Y-coordinate array of the elements when elements are initially generated

Z

Array of aNum×1

Z-coordinate array of the elements when elements are initially generated

R

Array of aNum×1

Radius array of the elements when elements are initially generated

isShear

Logic

Whether the shear force between elements is taken into account in the initial calculation of deposition, the default value is 0 (continued)

Appendix A: Properties of Classes

267

(continued) Name of properties Type of data

Introduction

isSample

Logic

Whether the sample element is generated at the initial modeling, the default value is 0, and when it is 0, only the boundary and bottom pressure platen are generated(i.e. empty box)

Sample W

Double

The inner width of the model box (X-direction)

Sample L

Double

The inner length of the model box (Y-direction)

Sample H

Double

The inner height of the model box (Z-direction)

Sample

Struct

Structure of sample elements excluding the pressure platens

boundaryRrate

Double

The overlap rate of the boundary elements, i.e., the ratio of the spacing between the two elements to their diameter

platenStatus

Logic array of 1×6 Corresponding to six pressure platens [left, right, front, back, bottom, top] successively. When the value is 1, the corresponding pressure plate exists, otherwise, it does not exist, and the default value is [0, 0, 0, 0, 0, 1]

lefPlaten

Struct

The structure of the left pressure platen contains information of XYZR

rigPlaten

Struct

The structure of the right pressure platen contains information of XYZR

froPlaten

Struct

The structure of the front pressure platen contains information of XYZR

bacPlaten

Struct

The structure of the back pressure platen contains information of XYZR

botPlaten

Struct

The structure of the bottom pressure platen contains information of XYZR

topPlaten

Struct

The structure of the top pressure platen contains information of XYZR

lefB

Struct

The structure of the left boundary contains information of XYZR

rigB

Struct

The structure of the right boundary contains information of XYZR

froB

Struct

The structure of the front boundary contains information of XYZR

bacB

Struct

The structure of the back boundary contains information of XYZR

botB

Struct

The structure of the bottom boundary contains information of XYZR

topB

Struct

The structure of the top boundary contains information of XYZR (continued)

268

Appendix A: Properties of Classes

(continued) Name of properties Type of data

Introduction

groupId

Array of aNum×1

Ids of the groups to which each element belongs, ids of 6 boundary are from -1 to -6, and ids of 6 pressure platens are from 1 to 6

aMatId

Array of aNum×1

Ids of materials in each element

compactNum

double

The number of compaction times after building a deposition model, the default value is 0

PexpandRate

Logic

The number of extension elements of the pressure platen, the default value is 1

BexpandRate

Logic

The number of extension elements of the boundary, the default value is 2

fixPlaten

Logic

Whether to lock the freedom degrees of the pressure platens so that the pressure platens only move in their normal directions, the default value is 1

saveFileLevel

Double

The importance level of saving a file, 0 means that the file is not saved, 1 means that the primary file is saved, and 2 means that all files are saved, the default value is 1

Properties of build Class Properties of build class, which mainly record the state information of the model at the beginning, as well as the data used for post-processing, such as data in d.data. Name of properties Type of data

Introduction

Name

Char

Name of model

TAG

Struct

Record the information of simulation for recording and outputting information, and it can be used to save all kinds of output data

SET

Struct

Record the setup information of the numerical simulation, and save custom parameters in secondary development

GROUP

Struct

The defined groups are recorded, and the name of the group cannot begin with group

is2D

Logic

Whether it is a two-dimensional model, the default value is 0(false), indicating that 3D calculation is performed

Data

Struct

Dataset of model result, and partial dataset of post-processing command, such as displacement field, stress field, and custom post-processing parameters can be added (see post-processing instructions) (continued)

Appendix A: Properties of Classes

269

(continued) Name of properties Type of data

Introduction

mo

Model class

Object of model class, module of calculation

Status

modelStatus class

Object of modelStatus class, status of model

Mats

Cell array

Cell array of materials

vRate

Double

The ratio of the damping coefficient, i.e., the coefficient of the critical damping to be multiplied (see description of the damping coefficient)

g

Double

Acceleration of gravity, the default value is − 9.8 m/s2

isUI

Logic

Whether to run in the window program, the default value is 1, when 0 is set, the show command will draw an image in the new window

edit_output

–

Object of prompt message, system parameters, do not modify

aNum

Double

Number of all elements in the model

mNum

Double

Number of active elements in the model

aMatId

Array of aNum×1

Material id of all elements

aX

Array of aNum×1

X-coordinates of all elements

aY

Array of aNum×1

Y-coordinates of all elements

aZ

Array of aNum×1

Z-coordinates of all elements

aR

Array of aNum×1

Radius of all elements

aKN

Array of aNum×1

Normal stiffness coefficient of all elements

aKS

Array of aNum×1

Shear stiffness coefficient of all elements

Continued table

aBF

Array of aNum×1

Breaking force of all elements

aFS0

Array of aNum×1

Initial shear strength of all elements

aMUp

Array of aNum×1

Friction coefficient of all elements

mVis

Array of aNum×1

Viscosity damping coefficient of active elements

mM

Array of aNum×1

Mass of active elements

Period

double

Minimum period of simple harmonic vibration of elements

dbXYZ

Array of (aNum-mNum)×1 Boundary displacement of the elements in newStep function

saveHour

Double

Interval time of saving data files

Step

Double

Current simulation steps for iterative calculation, See step 3 of example

totalStep

Double

Total steps of simulation (continued)

270

Appendix A: Properties of Classes

(continued) Name of properties Type of data

Introduction

isNote

Whether to display the simulation prompt, the default value is 1 (true)

Logic

note

Char

Content of prompt

Rrate

Double

When the d.show command is executed, the radius coefficient of elements shown is 1 by default. The radius of elements shown will be half of the actual value when the default value is 0.5

showB

Double

Display the boundary mode, and the range of value is [0, 1, 2, 3], see post-processing for details

showBallLimit

Double

The default value is 10 million, and elements are shown as a point when beyond this value

Properties of model Class The model class, the solver, is the core of the MatDEM program and includes the most basic finding of neighbor element, iterative calculations, GPU settings, etc. Name of properties

Type of data

Introduction

TAG

Struct

Record the information of simulation for recording and outputting information, and it can be used to save all kinds of output data

SET

Struct

Record the setup information of the numerical simulation, and save custom parameters in secondary development

status

Object of modelStatus class

The information of model status in d.status is usually initialized by the command d.status or d.resetStatus

FnCommand

Char

The calculation formula of normal contact force between elements, the default value is ‘nFN0=obj. nKNe.* nIJXn;’

aNum

Double

Number of all elements

aMatId

Array of aNum×1

Material id of all elements

aX;aY;aZ;aR;

Array of aNum×1

X-, Y-, Z-coordinates and radius of all elements (continued)

Appendix A: Properties of Classes

271

(continued) Name of properties

Type of data

Introduction

aKN;aKS;

Array of aNum×1

Normal stiffness coefficient and shear stiffness coefficient of all elements

aBF

Array of aNum×1

Breaking force of all elements

aFS0

Array of aNum×1

Initial shear strength of all elements

aMUp

Array of aNum×1

Friction coefficient of all elements

mNum

Double

Number of active elements

mVis

Array of mNum×1

Viscosity of active elements

mM

Array of mNum×1

Mass of active elements

mVX;mVY;mVZ;

Array of mNum×1

Velocity of active elements in the X-, Y-,Z-direction

mAX;mAY;mAZ;

Array of mNum×1

Acceleration of active elements in the X-,Y-,Z-direction

mVFX;mVFY;mVFZ;

Array of mNum×1

Viscous force of all elements in the X-, Y-, Z-direction

g

Double

Gravitational acceleration

mGX;mGY;mGZ;

array of mNum×1

Body force of the element in the X-,Y-, Z-direction

aHeat

Array of (mNum+1)×5

From left to right is viscosity heat, normal breaking heat, shear breaking heat, slipping heat and breaking heat (undisclosed) of a element, and it’s the heat of all boundary elements in the last line

dSide

Double

Length of grid edge when search neighbor matrix

dis_mXYZ

Array of mNum×3

Displacement of the model elements after last search of neighbor elements

dis_bXYZ

Array of mNum×3

Displacement of the boundary elements after last search of neighbor elements

nBall

Matrix of mNum×n, and n is the Neighbor matrix maximum number of neighbors

bFilter

Logic matrix

A filter with the same length and width as the nBall matrix in the bonding state of the connection (same below)

cFilter

Logic matrix

A filter for compressive state of the connection

tFilter

Logic matrix

A filter of tension (continued)

272

Appendix A: Properties of Classes

(continued) Name of properties

Type of data

Introduction

Logic matrix

Residual strength coefficient

Continued table nBondRate

nKNe;nKSe;nIKN;nIKS; Logic matrix

Stiffness coefficient between a element and neighbor elements

nFnX;nFnY;nFnZ;

Logic matrix

Normal force between a element and neighbor elements

nFsX;nFsY;nFsZ;

Logic matrix

Shear force between a element and neighbor elements

nClump

Matrix which dimension is same Clump overlap between a as nBall element and neighbor elements, it is clump connection when it is not zero

dT;totalT;

Double

Current time interval and total time, both default values are 0

isGPU

Logic

Whether to use GPU calculation, the default value is 0

isHeat

Logic

Whether to calculate heat, the default value is 0

isClump

Logic

Whether there is clump, the default value is 0

isFix

Logic

Whether the freedom degree is locked, after locking the freedom degree of the active elements, it is similar to the fixed wall elements, the default value is 0

FixXId;FixYId;FixZId;

Array of n rows and 1 column (0≤n≤aNum)

Lock the element ids of the X-,Y-, and Z-coordinates

isWaterDiff

Logic

Whether to perform finite difference calculation

isCrack

Logic

Whether to count crack generated, the default value is 0, i.e., not count

isShear

Logic

Whether to consider the shear force between elements, the default value is 1, i.e., consider

isSmoothB

Logic

Whether a smooth boundary is used, the default value is 0, i.e., not consider

Appendix A: Properties of Classes

273

Properties of Tool_Cut Class Used to save the digital elevation surface and take advantage of two or more surfaces to cut the model, as well as to generate joints and cracks. Name of properties

Type of data

Introduction

d

Build class

Object of build class

layerNum

Double

Number of layers used for cutting

TriangleX

Matrix of n×3

Coordinates for a triangle on a single row

SurfTri

Cell array

Triangular data

Surf

Cell array

Surface data

TriangleY TriangleZ

Appendix B

Main Functions

Functions of obj_Box Class obj_Box class is a simulation box that packs model and builds various geometric models in a rectangular area of a box. Objects of obj_Box class are usually named B, and almost all secondary development examples are based on obj-Box object. The following input parameter “varargin” indicates the number of variable input parameters. Name

calculateBlockDensity()

Function

Calculate the density of the model sample

Input

None

Output

Value of model density

Example

Used in training of material

Name

compactSample(compactNum, varargin)

Function Use top platen to compact sample Input

compactNum: compaction times varargin: pressure of compaction, When there is no input, the pressure of compaction is twice the gravity of all model elements

Output

None

Example B.compactSample(2, 10e-6)

Name

cutGroup(gNames, surfId1, surfId2)

Function Cut the group with two surfaces to remove the remaining elements from the model Input

gNames: The group name of being cut; surfId1:The Id of the surface; surfId2: The Id of the surface (continued)

© Science Press 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9

275

276

Appendix B: Main Functions

(continued) Name

cutGroup(gNames, surfId1, surfId2)

Output

None

Example B.cutGroup({‘sample’, ‘botB’, ‘t opB’}, 1, 2), see example of 3DSlope1 for details

Name

gravitySediment(varargin)

Function Let the elements move randomly and accumulate under gravity to build packing model Input

varargin: Variable input parameters: when a parameter rate is input, the deposition time ratio is determined; when there is no input parameter, the default value of rate is 1

Output

None

Example B.gravitySediment()

Name

removeInterPlatenBoundaryForce()

Function Remove the force between the pressure platen and the perpendicular boundary of the pressure platen Input

None

Output

None

Example B.removeInterPlatenBoundaryForce(), used to build triaxial stress model of system

Name

removeInterPlatenForce()

Function

Remove the force between each pressure platen

Input

None

Output

None

Example

B.removeInterPlatenForce(), used to build triaxial stress model of system

Name

setGPU(varargin)

Function Set up computing mode of GPU Input

varargin: Have the same input parameters as the model.setGPU, and use B.gpuStatus automatically as input parameters when no input parameters are available

Output

None

Example B.setGPU(‘off’)

Name

setUIoutput(varargin)

Function Set to display messages in the message output area, run this command after the new file is loaded (continued)

Appendix B: Main Functions

277

(continued) Name

setUIoutput(varargin)

Input

varargin: When there are no input parameters, the message box in the window is automatically found, and when the message box handle is entered, the message box is used to display the message

Output

None

Example B.setUIoutput()

Name

setPlatenFixId()

Function Set the degree of freedom of each pressure platen’s edge elements so that it can only move in the normal direction of the pressure platen, and prevent the pressure platen from sliding from the side Input

None

Output

None

Example B.setPlatenFixId(), see example of BoxLayer2 for details

Functions of Build Class The build class is used to modify the model, data relay, control numerical simulation, and display results. Objects of build class are usually named d, most important commands are in the form of d.* In secondary development, These functions are the most important and commonly used functions of MatDEM. Name

addElement(matId, addObj, varargin)

Function

Use the structure (contains information of X, Y, Z, R) to add elements

Input

matId: Id of material; addObj: structure varargin: type of element, and it can be “model”(active element) or “wall” (fixed element), and the default value is model when it’s omited

Output

None

Example

d.addElement(1, ring), see example of BoxSlopeNet2 for details

Name

addFixId(direction, gId)

Function

Add elements locked degrees of freedom (locking coordinates)

Input

direction: Direction of locking, it can be: “X”, “Y”, “Z” gId: Id array of elements

Output

None

Example

d.addFixId(‘X’, [fixId; d.GROUP.topPlaten]), see example of BoxShear1for details

278

Appendix B: Main Functions

Name

addGroup(gName, gId, varargin)

Function

Define a new group in the current model

Grammar

addGroup(gName, gId, matId)

Input

gName: The name of group; gId: Id array of group varargin: Id of material, the default value is 1 when there is no input

Output

None

Example

d.addGroup(‘topPlaten’, topPlatenId), see example of BoxShear1 for details

Name

addMaterial(newMat)

Function

Add a new material to the d.Mats

Input

newMat: Material object of material class

Output

None

Example

d.addMaterial(Soil)

Name

balance(varargin)

Function Function of balancing iteration calculation, which is the most important function of system Input

balance(): 1 times of balance operation balance(Num): Num times of balance operation balance(Num, Time): balanceNum*balanceTime times of standard balance operation, and record the status every balanceNum times balance(‘Standard’): 1 times of standard balance operation balance(‘Standard’, R): R times of balance operation is performed, R>0 balance(‘Standard’, R, ‘off’): R times of standard balance operation is performed, but no prompts of the iteration process are displayed

Output

None

Example d.balance(‘Standard’, 1, ‘off’)

Name

balanceBondedModel(varargin)

Function

Strong bond balance of friction between elements is considered, usually used after the material is assigned. Give great tensile resistance and initial shear resistance (non-breakable) to inter-element connections and perform calculation of standard balance

Input

varargin: When there is an input parameter, that is the times of standard balance; When there is no input parameter, the times of standard balance is 1

Output

None

Example

d.balanceBondedModel(3), see example of 3DSlope2s for details

Appendix B: Main Functions

279

Name

balanceBondedModel0(varargin)

Function

Strong bond balance of friction between elements is unconsidering (compaction is more adequate), usually used after the material is assigned. Give great tensile resistance and initial shear resistance (non-breakable) to inter-element connections and perform calculation of standard balance

Input

varargin: When there is an input parameter, that is the times of standard balance; When there is no input parameter, the times of standard balance is 1

Output

None

Example

d.balanceBondedModel0(3), see example of BoxTBMCutter2 for details

Name

balanceForce(Amax, num)

Function Balance the forces in the model, and make acceleration of elements (corresponding to an unbalanced force) less than a certain value. This function is not commonly used Input

Amax:Maximum acceleration num: Times of balance

Output

None

Example d.balanceForce(0.1, 100)

Name

breakGroup(varargin)

Function

Disconnect a connection within a specified group or between two groups

Input

varargin: When there are no input parameters, disconnect the connections of all elements; When there is an input parameters, it is a cell arrary, such as {‘sampel’, ‘layer1’, ‘layer2’} which disconnects the intra-group connections; When there are two input parameters, disconnect the connections between two groups

Output

Connection filter matrix for disconnecting bonding

Example

d.breakGroup(), see example of BoxTunnelNew2 for details

Name

breakGroupOuter(varargin)

Function

Disconnect the outgoing connection of the specified group

Input

varargin: When there are no input parameters, disconnect all out-of-group connections; When there is an input parameter, which is a cell array, such as {‘sampel’, ‘layer1’, ‘layer2’}, disconnect the outward connection of these groups; When there are multiple input parameters, enter the group name (string) of multiple groups, break the outward connection of these groups

Output

Matrix of connection filter for disconnecting bonding

Example

d.breakGroupOuter()

280

Appendix B: Main Functions

Name

calculateData()

Function

Non-independent data are obtained by calculation and used after loading data

Input

None

Output

None

Example

d.calculateData()

Name

clearData(varargin)

Function

Clean up non-independent data to keep the saved data files smaller

Input

Input value of varargin can be 1 or 2. Group information will be cleared when 2 is taken, and the default value is 1 when there are no input parameters

Output

None

Example

d.clearData()

Name

connectGroup(varargin)

Function

Bond connections specified between elements within a group, or between groups of two groups

Input

When there is an input parameter, the connection between the elements within the group is bonded; When there are two input parameters, the connection between the elements of the two groups is bonded

Output

None

Example

d.connectGroup(‘sample’), see example of BoxLayer2 for details

Functions of Model Class The model class is the solver which is the core of MatDEM program calculation. It contains the most basic neighborhood search, iterative balance, GPU Settings, etc. Objects of model class are usually named mo and assigned to d.mo. Name

balance()

Function

Perform a calculation of balance iteration, and move the time forward by d.mo.dT

Input

None

Output

None

Example

d.mo.balance()

Appendix B: Main Functions Name

281

setGPU(type)

Function Set status of GPU Input

type can be: ‘on’: Set the computation status to GPU computation ‘off’: Set the computation status to CPU computation ‘auto’: Test speed of CPU and GPU, and select faster one to calculate ‘fixed’: Lock the current calculation status, the above ‘on’ and ‘off’ functions will not be used ‘unfixed’: Unlock the current calculation status and restore the above ‘on’ and ‘off’ functions

Output

None

Example d.mo.setGPU(‘on’)

Name

setModel()

Function

Set model

Input

None

Output

None

Example

d.mo.setModel()

Name

setKNKS()

Function

Sets the stiffness between the elements and the neighbors, which needs to be used after changing the stiffness of the elements

Input

None

Output

None

Example

d.mo.setKNKS()

Name

setNearbyBall()

Function

Function to serch three-dimensional neighbor elements

Input

None

Output

None

Example

d.mo.setNearbyBall(), see example of BoxMixMat3 for details

Name

zeroBalance()

Function Zero balance, recalculate the force state of elements in the current model, but does not make a iteration of time step, usually used after the model is modified Input

None

Output

None

Example d.mo.zeroBalance(), see example of BoxMixMat3 for details

282

Appendix B: Main Functions

Functions of fs Class fs(functions) class is the basic function of the program, including basic drawing function, basic matrix transformation, calculation of parameters, most of which are internal functions of the system. Name

disp(note)

Function

Display the results in the message box

Input

note: Message string that needs to be displayed

Output

Prompt information of string

Example

fs.disp(‘message’)

Name

save(path, name, value)

Function

Save data to .mat file

Input

path:Save path; name: Name of Variable; value: Value of variable

Output

.mat file

Example

fs.save(‘pile.mat’, ‘pile’, d.mo)

Name

showObj(obj)

Function

Display the structure of the model, which contains the X, Y, Z and R information of the elements

Input

obj: Structure data

Output

Display figure of structure

Example

fs.showObj(pile)

Name

setPlatenStress(d, StressXX, StressYY, StressZZ, border)

Function

Set the pressure on the pressure platen, only set the body force on the contact elements within the border, force for the right,back and top stress platen

Input

d: Object of build StressXX、YY、ZZ: the normal pressure of X, Y and Z direction border: The distance of applying stress

Output

None

Example

fs.setPlatenStress(d, 0, 0, B.SET.stressZZ, B.ballR*5), see example of BoxTunnelNew2 for details

Appendix B: Main Functions

283

Functions of mfs Class mfs(modeling functions) class is mainly used for modeling of structure. Name

applyRegionFilter(regionFilter, sX, sY)

Function The matrix generated by image2RegionFilter is applied to filter the elements and the elements filtration matrix is obtained Input

regionFilter: Returned value of image2RegionFilter sX, sY: x, y coordinates of the elements(both of them are single-column matrix)

Output

Filter matrix of elements

Example mfs.applyRegionFilter(regionFilter, sX, sY), see examples of BoxWord2 and 3DSlope2 for details

Name

alignObj(type, varargin)

Function

Align multiple structure models along one side

Input

type: String, it can be ‘left’, ‘right’, ‘front’, ‘back’, ‘bottom’, ‘top’, ‘Xcenter’, ‘Ycenter’ and ‘Zcenter’; varargin: parameters of multiple structures

Output

Return syllable multiple structures in sequence

Example

[obj1, obj2]=mfs.alignObj(‘left’, obj1, obj2), see examples of BoxShear1 for details

Name

combineObj(varargin)

Function

Merge multiple structures into one structure

Input

varargin: parameters of multiple structures

Output

The merged structure

Example

botBoxObj=mfs.combineObj(botBoxObj, botRingObj), see examples of BoxShear1 for details

Name

cutBoxObj(sampleObj, width, length, height)

Function

The block with specific length, width, and height is cut from the sample object with the origin as the center

Input

sampleObj: Sample structure; width,length,height:Width, length and height of cutting sample

Output

Block structure obtained by cutting

Example

obj=mfs.cutBoxObj(sampleObj, 1, 1, 1)

284 Name

Appendix B: Main Functions divideObj(obj, pX, pY, pZ)

Function Cutting the structure with a triangular surface defined by three vertices to generate two structures Input

obj: The name of structure pX, pY, pZ: Both of them are matrix of 3×1, representing the coordinates of the three vertices of a triangle

Output

Two new structures of cutting

Example [obj1, obj2]=mfs.divideObj(obj, pX, pY, pZ)

Name

denseModel(Rrate, F, varargin)

Function

Dense and overlap structure objects

Input

Rrate: Ratio of elements spacing to diameter F: Function for generating structures varargin: Input parameters for F

Output

The structure after dense

Example

botTubeObj=mfs.denseModel(Rrate, @mfs.makeTube, tubeR+(1-Rrate)*ballR*2, botTubeH, ballR), see example of BoxShear1 for details

Name

filterObj(obj, f)

Function

Use filters to select elements in the structure to generate a new structure

Input

obj: Parameters of structure f: Boolean matrix of the filter (selected if value is 1)

Output

New structure by filtering

Example

sphereObj=mfs.filterObj(sampleObj, sphereFilter)

Name

getObjCenter(obj)

Function

Get the center of the object

Input

obj: Name of object

Output

Structure that includes X, Y, and Z coordinate information of center

Example

objCenter=mfs.getObjCenter(sampleobj)

Name

getObjFrame(obj)

Function

Obtain the boundary of the structure in six directions, as well as width, length, and height

Input

obj: Name of object

Output

The boundary of the structure in six directions, as well as width, length and height

Example

frame=mfs.getObjFrame(obj)

Appendix B: Main Functions

285

Name

image2RegionFilter(fileName, imH, imW)

Function

Generate matrix of filter according to the information of image

Input

filename: Name of image (Black and white images) imH, imW: Height and width of the image(iamge size needs to match model size)

Output

Boolean matrix of block

Example

regionFilter=mfs.image2RegionFilter(‘slope/slopepack.png’, imH, imW), see example of BoxWord and 3DSlope2 for details

Name

intervalObj(obj, dx, dy, dz, num)

Function

Generate repeatedly num obj along the interval of dx, dy and dz

Input

obj: Name of structure dX, dY, dZ: Interval of structures generated num: Number of structures generated

Output

Obtain structure by copy

Example

obj=mfs.intervalObj(pile, 1, 0, 0, 5)

Name

move(obj, varargin)

Function Move structure Input

obj: Name of structure varargin: When there is an input parameter, it’s an array containing X-, Y-, and Z-coordinates; When there are three input parameters, it’s coordinates of X, Y, and Z

Output

Structure after moving

Example obj=mfs.move(obj, 1, 1, 1)

Name

moveObj2Origin(obj)

Function

Move the center of the object to the origin

Input

obj: Name of structure

Output

Structure after moving

Example

botTubeObj=mfs.moveObj2Origin(botTubeObj), see example of BoxShear1 for details

Name

makeLine(dir, length, ballR)

Function

Generate a line in a certain direction along the X,Y,Z

Input

dir:direction, it can be ‘X’, ‘Y’ and ‘Z’ length: Length ballR: The radius of the elements

Output

Line structure

Example

Line=mfs.makeLine(‘X’, 5, 0.1)

286

Appendix B: Main Functions

Name

makeBox(boxW, boxL, boxH, ballR)

Function

Make a block structure

Input

boxW: The width of the elements boxL: The length of the elements boxH: The height of the elements ballR: The radius of the elements

Output

Block structure

Example

boxObj=mfs.makeBox(1, 1, 1, 0.2)

Name

make3Dfrom2D(obj2D, height, ballR)

Function

Stretch a two-dimensional object into three dimensions

Input

obj2D: Two-dimensional structure height: The height of the three-dimensional structure pulled ballR: The radius of the elements

Output

Three-dimensional structure

Example

tubeObj=mfs.make3Dfrom2D(circleObj, 5, 0.1)

Name

Obj2Build(obj, varargin)

Function

Transform a structure into a build object

Input

obj: The name of structure varargin: Optional parameters that define the mNum in the build

Output

build object

Example

d=Obj2Build(obj, 1000)

Name

rotateCopy(obj, dAngle, num, varargin)

Function Input

obj: The name of structure dAngle: Angle of rotation num: Number of copies varargin: Plane of totation can be ‘XY’, ‘YZ’ and ‘XZ’, when there are no input parameters, the structure is rotated and copied in the ‘XY’-plane by default

Output

Obtain structure by copy

Example

planeObj=mfs.rotateCopy(planeObj, 60, 6), see example of BoxShear1 by details

Name

rotate(obj, type, angle)

Function

Turn the structure to a certain angle in a specific direction (In a two-dimensional model, rotate and then run d.mo.aY(:)=0 to prevent floating-point error errors) (continued)

Appendix B: Main Functions

287

(continued) Name

rotate(obj, type, angle)

Input

obj: Stucture type: Direction which can be ‘XY’, ‘YZ’ and ‘XZ’ angle: Angle of rotation

Output

Structure after rotating

Example

obj=mfs.rotate(obj1, ‘XZ’, 30), see example of BoxSlopeNet2 by details

Name

setBondByPolygon(d, PX, PY, PZ, type)

Function Cut or bond models using polygon surfaces defined by multiple vertices Input

d: Object of build pX, pY, pZ: Vertex coordinates of a spatial polygon, all of which are matrix of n×1 type: ‘glue’, Bond elements; ‘break’: Break connection; ‘no’: Don’t change the connection

Output

Correspond to the connection filter matrix of nBall

Example d.setBondByPolygon(d, PX, PY, PZ, ‘break’), see example of Box3DJointStress3 for details

Name

setBondByTriangle(d, pX, pY, pZ, type)

Function Cut or bond a model with a triangular surface Input

d: Object of build pX, pY, pZ: Vertex coordinates of spatial triangles, such as three matrix of 3×1 type: ‘glue’, Bond elements; ‘break’: Break connection; ‘no’: Don’t change the connection

Output

Correspond to the connection filter matrix of nBall

Example d.setBondByTriangle(d, pX, pY, pZ, ‘break’), see example of Box3DJointStress3 for details

Functions of Tool_Cut Class Used to save the digital elevation surface and take advantage of two or more surfaces to cut the model, as well as to generate joints and cracks. Name

addSurf(para)

Function

According to the coordinate of discrete points generate surface (triangular mesh), see command of Matlab ‘scatteredInterpolant’

Input

para: Support two types of data input: 1. Enter a structure that includes XYZ information; 2. Enter the matrix of XYZ information [X,Y,Z], or [X,Y,Z,X,Y,Z …], which can be two-dimensional or three-dimensional data. If it is two-dimensional data, it needs to be on the XZ plane. (continued)

288

Appendix B: Main Functions

(continued) Name

addSurf(para)

Output

None

Example

C.addSurf(lSurf), see example of BoxModel2 for details

Name

delSurf(surfIds)

Function

Delete surface

Input

surfIds: Ids of surface

Output

None

Example

C.delSurf(1)

Name

getTriangle(Id)

Function

Transfer the triangular face in SurfTri to TriangleX, TriangleY, Triangle Z

Input

Id: Id of SurfTri

Output

None

Example

C.getTriangle(1), see example of Box3DjointStress3 for details

Name

getSurfTri(Id, rate)

Function

Generate triangular surfaces based on discrete points in Surf and record them in SurfTri

Input

Id: Id of Surf rate: rate

Output

None

Example

C.getSurfTri(1, 1), see example of Box3DJointStress3 for details

Name

setTriangle(PX, PY, PZ)

Function

Assign data of X, Y, and Z coordinate to the object’s TriangleX, TriangleY and TriangleZ

Input

PX、PY、PZ: Coordinate data of X, Y and Z

Output

None

Example

C.setTriangle(TriX2, TriY2, TriZ2), see example of Box3DJointStress3 for details

Name

setLayer(gNameCells, surfIds)

Function

Use layers to cut the specified group

Input

gNameCells: Name of group surfIds: Ids of surfaces

Output

None

Example

C.setLayer({‘sample’}, [1, 2, 3, 4]), see example of BoxModel2 for details

Appendix B: Main Functions Name

showTriangle()

Function

Display triangles in TriangleX, Y and Z

Input

None

Output

Image of triangular plane

Example

C.showTriangle(), see example of Box3DJointStress3 for details

Name

Tool_Cut(d)

Function

Initialize the cut object

Input

d: object of build

Output

None

Example

C=Tool_Cut(d), see example of BoxModel2 for details

289

Appendix C

Frequently Asked Questions

1. Q: Errors in the modeling process: I cannot convert from gpuArray to double. Why? A: The error occurred because the GPU was not closed during a noniterative calculation operation. The GPU needed shut down before the error of code occurred, and the command d.mo.setGPU (‘off’) needed run. 2. Q: How can the motion of the model be accelerated? A: We recommend increasing the default standard time step d.mo.dT so that the time step exceeds the standard time step by no more than 4 times. The following command can be used: d.mo.dT=d.mo.dT*4;

3. Q: Why does the structure "explode" during the balance process after it is imported into the model? A: When structural modeling is used and the structure is imported into the model, there will be considerable stress between elements if the amount of overlap between elements is excessively large. This causes the structure model to explode. Therefore, after adding structures, it is often necessary to use the setClump command to make them cluster elements. 4. Q: Why do the elements "explode" and fly out of the boundary after balancing the model? A: There are several possibilities, which are as follows: (1) After material setup in the second step is completed, the stiffness of elements typically increases. This leads to a dramatic increase in the force between elements, which requires the balanceBondedModel (or balanceBondedModel0) command to be used for forced bonding balance and to prevent elements flying away because of excessive interaction forces. If gravity is © Science Press 2021 C. Liu, Matrix Discrete Element Analysis of Geological and Geotechnical Engineering, https://doi.org/10.1007/978-981-33-4524-9

291

292

Appendix C: Frequently Asked Questions

not taken into account, the reduceGravity command should be used after building a packing model to reduce the action of gravity. This reduces the aforesaid mutation of stress. (2) During model loading, when the pressure is too high or the stiffness of the element is too small, the elements deform excessively, causing them to be completely "flattened" and fly through and out of the boundary. (3) In a two-dimensional model, the front and back boundaries are canceled and the Y-coordinates of all elements must be 0. If a large number of elements fly out of the four boundaries, you need to check whether the Y-coordinate of the elements is 0, especially after importing the structure, to confirm all the Y-coordinates of the new plus elements are 0. You are recommended to add the d.mo.aY (:)=0 command before iterative calculations so that all the Y coordinates of elements are 0. 5. Q: What is the difference between the micromechanical parameters of materials recorded in d.Mats and the micromechanical parameters recorded in d.mo? A: The micromechanical parameters of material relate to the radius of elements (see the conversion formula in Chap. 1 and Sect. 3.4.1) and the d.Mats records the parameters of elements when the specified diameter of each element is established (e.g., Mats{1}.d). Conversely, d.mo records the microparameters of each element and is used for actual calculation. 6. Q: Can the window interface of MatDEM be modified? A: All window components in MatDEM can be modified. First, enter clc and the data bar will display handles, including all the window controls. Next, use the set command of MATLAB to modify various parameters of the window; for example, the set (handles.figure1, ‘Name’, ‘My MatDEM’) command modifies the name on the upper left of the window. In this way, you can add buttons or new windows in MatDEM by yourself. Specific help files and examples will be provided in later versions of MatDEM. 7. Q: When the return of loop statement is run in a secondary development function, why does it sometimes go wrong? A: The return statement, which cannot be run in the for, if, while, and switch statements of secondary development functions, will be automatically changed to break. You can achieve the return effect through the if-else statement. For example: a=55; if a＞100 return; end fs.disp('a is ＜=100');

An error currently occurs in MatDEM, which can be changed to the following form:

Appendix C: Frequently Asked Questions

293

a=55; if a＜=100 fs.disp('a is ＜=100'); end

8. Q: Why can’t the program define Poisson’s ratio of material so that it is greater than 0.2? A: The basic conversion formula allows a maximum Poisson’s ratio of 0.2 in the initial settings for materials in MatDEM. For rocks and materials (such as rubber), a high Poisson’s ratio is typically derived from its specific structure and needs to be formed through specific packing (see Sect. 1.6.1 for details). When the Poisson’s ratio of material is directly set to 0.2, the actual ratio will be larger. Therefore, the default coefficient corresponding to Poisson’s ratio of material is 0.8 (see Sect. 3.4 for details). 9. Q: Why can’t I view the saved data in post-processing after loading it into the software? A: In iterative calculations, the d.clearData function is typically used to compress the data before saving the file. When loading the data into the software, you need to use d.calculateData to recalculate the data. If the original data are saved in the GPU, you also need to use the d.mo.setGPU (‘off’) command. 10. Q: When the d.delElement command is used continuously, why does it go wrong? A: This is because the d.delElement command deletes the specified numbered elements and creates a new object of d. At this point, the element number in d has changed and you need to regain the deleted element number. If you want to delete more than one group at a time, you can combine these group numbers into arrays and put them into the d.delElement function. 11. Q: Why does the following error occur when saving large files? ＞Position:f.runFileCommandCells, Line:225 ＞Line of code:33, save(['TempModel/' B.name '1.mat'],'B','d'); ＞Error: There was an error closing the file D:\MatDEM1.32-2\Temp Model\BoxStruct1.mat The file may be corrupted.

A: When the number of elements reaches millions, the saved .mat file may reach the GB level because the default save command only supports files under 2GB. You, therefore, need to declare that the version of the saved file is v7.3, which uses the save (‘abc.mat’, ‘v7.3’) command. You can also use the d.clearData(1) command to compress the data before you save the file.

294

Appendix C: Frequently Asked Questions

12. Q: Why can’t I use MATLAB’s length function? A: You can run the length function of MATLAB to obtain the length of the matrix in MatDEM. MATLAB’s function is covered by the newly defined parameters when running the code. Thus, when length = 100 is defined, the matrix length can no longer be obtained by running the length function and may result in an error. For more questions, please visit http://matdem.com and join the online MatDEM discussion group.