Manual Of 3DEC (V4.10)

Manual_of_3DEC_(V4.10)

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 1668

DownloadManual Of 3DEC (V4.10)
Open PDF In BrowserView PDF
3 Dimensional Distinct Element Code

Manual
1

Vol.1 User's Guide
Vol.2 Command Reference
Vol.3 Fish in 3DEC
Vol.4 Theory & Background
Vol.5 Optional Features
Vol.6 Verification Problems and Example Applications

2

3DEC
3 Dimensional Distinct Element Code
User’s Guide

©2007
Itasca Consulting Group, Inc.
Mill Place
111 Third Avenue South, Suite 450
Minneapolis, Minnesota 55401 USA

3

Phone:
Fax:
E-Mail:
Web:

(1) 612-371-4711
(1) 612·371·4717
software@itascacg.com
www.itascacg.com

First Edition December 1998
First Revision May 1999
Second Revision September 1999
Second Edition January 2003
First Revision August 2005
Third Edition December 2007*

* Please see the errata page in the \Manuals\3DEC410 folder.

4

Terms - 1

Terms and Conditions for Licensing 3DEC
YOU SHOULD READ THE FOLLOWING TERMS AND CONDITIONS CAREFULLY
BEFORE USING THE 3DEC PROGRAM. INSTALLATION OF THE 3DEC PROGRAM
ONTO YOUR COMPUTER INDICATES YOUR ACCEPTANCE OF THESE TERMS AND
CONDITIONS. IF YOU DO NOT AGREE WITH THEM, YOU SHOULD RETURN THE
PACKAGE PROMPTLY AND YOUR MONEY WILL BE REFUNDED.
This program is provided by Itasca Consulting Group, Inc. Title to the media on which the program
is recorded and to the documentation in support thereof is transferred to the customer, but title to the
program is retained by Itasca. You assume responsibility for the selection of the program to achieve
your intended results and for the installation of the program, the use of and the results obtained
from the program.
LICENSE
1. All Itasca codes (with the exception of demonstration versions) are software-locked and
require a hardware key to operate the code.
2. You may copy the program for backup only in support of such use.
3. You may not use, copy, modify or transfer the program, or any copy, in whole or part,
except as expressly provided in this document.
4. You may not sell, sub-license, rent or lease this program.
5. Licenses are not transferable.
TERMS
The license is effective until terminated. You may terminate it any time by destroying the program
together with any backup copies and returning the hardware lock. It will also terminate if you fail to
comply with any term or condition of this agreement. You agree upon such termination to destroy
the program together with any backup copies, modifications and/or merged portions in any form
and return the hardware lock to Itasca.
WARRANTY
Itasca will correct any errors in the code at no charge for twelve (12) months after the purchase date
of the code. Notification of a suspected error must be made in writing, with a complete listing of
the input and output files and description of the error. If, in the judgment of Itasca, the code does
contain an error, Itasca will (at its option) correct or replace the copy at no cost to the user or refund
the initial purchase price of the code.

3DEC Version 4.1
5

Terms - 2

User’s Guide

LIMITATION OF LIABILITY
Itasca assumes no liability whatsoever with respect to any use of 3DEC or any portion thereof, or
with respect to any damages or losses that may result from such use, including (without limitation)
loss of time, money or goodwill that may arise from the use of 3DEC (including any modifications or
updates that may follow). In no event shall Itasca be responsible for any indirect, special, incidental
or consequential damages arising from use of 3DEC.
CODE SUPPORT
Itasca will provide email and telephone support, at no charge, to assist the code owner in the
installation of the code on the owner’s computer system. Additionally, general assistance may be
provided to aid the owner in understanding the capabilities of the various features of the program.
However, no-cost assistance is not provided for help in applying Itasca Software to specific userdefined problems.
Technical support covering modeling questions, applications, definitions, interpretation of results,
design guidelines, etc. can be purchased on an as-needed basis. For users who need substantial
amounts of assistance, consulting support is available. In all instances, the user is encouraged to
send the problem description to Itasca by fax or electronic mail in order to minimize the amount of
time spent trying to define the problem.
Itasca reserves the right to determine what qualifies as no-cost assistance and what requires payment.
See Section 6 in the User’s Guide for details.

3DEC Version 4.1
6

User’s Guide

1

PRECIS
This volume is the user’s guide to 3DEC. This guide contains general information on the operation
of 3DEC for engineering mechanics computation.
Section 1 gives an introduction to the capabilities and applications of 3DEC. An overview of the
new features in the latest version of 3DEC is also provided.
The first-time user should consult Section 2 for an introduction to the operation of 3DEC. The
installation and operation procedures are given, along with a simple tutorial to guide the new user
through a 3DEC analysis.
Section 3 provides general guidance in the use of 3DEC in problem solving for static mechanical
analysis for geotechnical engineering.
An introduction to the built-in programming language, FISH, is given in Section 4. This includes
a tutorial on the use of the FISH language. Note that no programming experience is assumed.
3DEC contains a graphical interface to assist with model creation and presentation of results. The
graphical interface is described in 3DEC ’s help menu.
Various items of interest to 3DEC users are contained in Section 6, including a 3DEC runtime benchmark on several different types of computers, and procedures for reporting errors and requesting
technical assistance.
Section 7 contains a bibliography of published papers describing some applications of 3DEC in
different fields of engineering.
The 3DEC Manual consists of six documents. The following volumes, which comprise the 3DEC
Manual, are available. (The titles in parentheses below are the names used to refer to the volumes
in the text.)
USER’S GUIDE — (User’s Guide) — an introduction to 3DEC and its capabilities
COMMAND REFERENCE — (Command Reference) — descriptions of all 3DEC commands
FISH in 3DEC — (FISH volume) — a complete guide to FISH as applied in 3DEC
THEORY AND BACKGROUND — (Theory and Background) — thorough discussions of the
built-in features in 3DEC
OPTIONAL FEATURES — (Optional Features) — detailed descriptions of the optional features:
thermal analysis, dynamic analysis, the surface support (liner) model and user-defined constitutive
models
VERIFICATION PROBLEMS (Verifications volume) and EXAMPLE APPLICATIONS (Examples volume) — a collection of verification problems and example applications

3DEC Version 4.1
7

2

3DEC Version 4.1
8

User’s Guide

User’s Guide

Contents - 1

TABLE OF CONTENTS
1 INTRODUCTION
1.1
1.2
1.3

1.4

1.5
1.6
1.7
1.8
1.9

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comparison with Other Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.1 Basic Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.2 Optional Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Summary of Updates from Version 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.1 Important Changes to 3DEC that will Affect the Execution of Old Data
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2 Redesigned User Interface with Accelerated Interactive Graphics . . . . .
1.4.3 Built-in Text Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4 Optional User-Defined Joint Constitutive Models . . . . . . . . . . . . . . . . . . .
1.4.5 Nodal Mixed Discretization (NMD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6 Reduced Memory Requirement for 32-Bit Double Precision Version . .
1.4.7 64-bit Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8 Factor-of-Safety Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9 New Solve Command (SOLVE elastic) Added . . . . . . . . . . . . . . . . . . . . . . .
1.4.10 Improvements to the User-Defined Model Interface . . . . . . . . . . . . . . . . .
1.4.11 Improvements to Structural Element Liner Logic . . . . . . . . . . . . . . . . . . .
1.4.12 Improved FISH Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.13 Licensing Options for Stand-Alone (Per Machine) or Network Operation
1.4.14 New PGEN Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.15 Compiled HTML Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.16 Range Structure and Keywords Have Been Changed . . . . . . . . . . . . . . . .
1.4.17 Numerical Thermal Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.18 New radial Keyword for the TUNNEL Command . . . . . . . . . . . . . . . . . . . .
Fields of Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Guide to the 3DEC Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Itasca Consulting Group, Inc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-1
1-4
1-6
1-6
1-8
1-9
1-9
1 - 10
1 - 10
1 - 10
1 - 11
1 - 11
1 - 11
1 - 11
1 - 11
1 - 11
1 - 12
1 - 12
1 - 12
1 - 12
1 - 12
1 - 13
1 - 13
1 - 13
1 - 14
1 - 15
1 - 19
1 - 20
1 - 21

3DEC Version 4.1
9

Contents - 2

User’s Guide

2 GETTING STARTED
Installation and Start-up Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.1 Installation of 3DEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.2 System Requirements for Windows 2000/XP/Vista . . . . . . . . . . . . . . . . . .
2.1.3 Windows Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.4 Utility Software and Graphics Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.5 Version Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.6 Start-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.7 Program Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.8 Running 3DEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.9 Installation Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 A Simple Tutorial — Use of Common Commands . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Nomenclature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 The 3DEC Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6 Mechanics of Using 3DEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.1 Model Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.2 Assigning Material Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.2.1 Block Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.2.2 Joint Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.3 Applying Boundary and Initial Conditions . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.4 Stepping to Initial Equilibrium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.5 Performing Alterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.6 Saving/Restoring Problem State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.7 Summary of Commands for Simple Analyses . . . . . . . . . . . . . . . . . . . . . .
2.7 Sign Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.8 Systems of Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.9 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1

2-2
2-2
2-2
2-3
2-4
2-4
2-5
2-5
2-5
2-6
2-9
2 - 16
2 - 19
2 - 22
2 - 24
2 - 26
2 - 29
2 - 29
2 - 32
2 - 33
2 - 35
2 - 37
2 - 40
2 - 42
2 - 44
2 - 46
2 - 47
2 - 49

3 PROBLEM SOLVING WITH 3DEC
3.1

General Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 Step 1: Define the Objectives for the Model Analysis . . . . . . . . . . . . . . .
3.1.2 Step 2: Create a Conceptual Picture of the Physical System . . . . . . . . . .
3.1.3 Step 3: Construct and Run Simple Idealized Models . . . . . . . . . . . . . . . .
3.1.4 Step 4: Assemble Problem-Specific Data . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.5 Step 5: Prepare a Series of Detailed Model Runs . . . . . . . . . . . . . . . . . . .
3.1.6 Step 6: Perform the Model Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.7 Step 7: Present Results for Interpretation . . . . . . . . . . . . . . . . . . . . . . . . . .

3DEC Version 4.1
10

3-2
3-3
3-3
3-4
3-4
3-4
3-5
3-5

User’s Guide

3.2

3.3

3.4

3.5

3.6
3.7

Contents - 3

Model Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Fitting the 3DEC Model to a Problem Region . . . . . . . . . . . . . . . . . . . . . .
3.2.2 Joint Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 Creating Internal Boundary Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3.1 Tunnel Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3.2 POLY cube . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.4 Selecting the Coordinate System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5 Orientation of Geologic Features to the Model Axes . . . . . . . . . . . . . . . .
3.2.6 Choice of Model Scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.7 Incorporation of Discontinuities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selection of Deformable versus Rigid Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 Poisson’s Effect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Zoning for Deformable Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1 Stress Boundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1.1 Applied Stress Gradient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1.2 Changing Boundary Stresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1.3 Checking the Boundary Condition . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1.4 Cautions and Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.2 Displacement Boundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.3 Real Boundaries — Choosing the Right Type . . . . . . . . . . . . . . . . . . . . . . .
3.4.4 Artificial Boundaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.4.1 Symmetry Planes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.4.2 Boundary Truncation — Location of the Far-Field Boundary .
Initial Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1 Uniform Stresses in an Unjointed Medium: No Gravity . . . . . . . . . . . . .
3.5.2 Stresses with Gradients in an Unjointed Medium: Uniform Material . .
3.5.3 Stresses with Gradients in a Nonuniform Material . . . . . . . . . . . . . . . . . .
3.5.4 Compaction within a Model with Nonuniform Zoning . . . . . . . . . . . . . . .
3.5.5 Initial Stresses following a Model Change . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.6 Stresses in a Jointed Medium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.7 Determination of the In-situ Stress State . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.8 Transferring Field Stresses to Model Stresses . . . . . . . . . . . . . . . . . . . . . . .
3.5.9 Topographical Stresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loading and Sequential Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Choice of Constitutive Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.1 Deformable-Block Material Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.2 Joint Material Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.3 Selection of an Appropriate Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-6
3-6
3 - 11
3 - 17
3 - 18
3 - 19
3 - 22
3 - 23
3 - 24
3 - 24
3 - 27
3 - 27
3 - 32
3 - 33
3 - 33
3 - 34
3 - 35
3 - 36
3 - 36
3 - 39
3 - 39
3 - 40
3 - 40
3 - 40
3 - 43
3 - 43
3 - 44
3 - 46
3 - 47
3 - 50
3 - 51
3 - 53
3 - 55
3 - 57
3 - 58
3 - 80
3 - 80
3 - 82
3 - 83

3DEC Version 4.1
11

Contents - 4

User’s Guide

Material Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.1 Block Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.1.1 Mass Density . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.1.2 Intrinsic Deformability Properties . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.1.3 Intrinsic Strength Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.1.4 Post-Failure Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.1.5 Extrapolation to Field-Scale Properties . . . . . . . . . . . . . . . . . . . . .
3.8.2 Joint Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9 Tips and Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.10 Interpretation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.10.1 Unbalanced Force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.10.2 Block/Gridpoint Velocities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.10.3 Plastic Indicators for Block Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.10.4 Histories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.10.5 Factor of Safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.11 Modeling Methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.11.1 Modeling of Data-Limited Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.11.2 Modeling of Chaotic Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.11.3 Localization, Physical Instability and Path-Dependence . . . . . . . . . . . . .
3.12 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.8

3 - 90
3 - 90
3 - 90
3 - 90
3 - 91
3 - 93
3 - 100
3 - 104
3 - 106
3 - 112
3 - 112
3 - 112
3 - 113
3 - 114
3 - 114
3 - 117
3 - 117
3 - 117
3 - 119
3 - 121

4 FISH BEGINNER’S GUIDE
4.1
4.2

Introduction and Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1
Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 2

5 GRAPHICAL INTERFACE
6 MISCELLANEOUS
6.1
6.2

6.3

3DEC Runtime Benchmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.1 Reporting via the Internet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.2 Reporting via Fax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Technical Support Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7 BIBLIOGRAPHY

3DEC Version 4.1
12

6-1
6-4
6-4
6-4
6-4

User’s Guide

Contents - 5

TABLES
Table 2.1
Table 2.2
Table 2.3
Table 2.4
Table 2.5
Table 3.1
Table 3.2
Table 3.3
Table 3.4
Table 3.5
Table 3.6
Table 4.1
Table 6.1

Maximum number of 3DEC blocks in available RAM . . . . . . . . . . . . . . . . . . . . .
Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Boundary condition command summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic commands for simple analyses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Systems of units — mechanical parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recommended steps for numerical analysis in geomechanics . . . . . . . . . . . . . . .
3DEC block constitutive models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3DEC joint constitutive models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selected elastic constants (laboratory-scale) for rocks (adapted from Goodman
1980) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selected strength properties (laboratory-scale) for rocks (adapted from Goodman 1980) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Typical values for Hoek-Brown rock-mass strength parameters
(adapted from Hoek and Brown (1988)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Commands that directly refer to FISH names . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3DEC runtime calculation rates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-4
2 - 23
2 - 33
2 - 43
2 - 46
3-3
3 - 81
3 - 83
3 - 91
3 - 92
3 - 103
4-4
6-1

3DEC Version 4.1
13

Contents - 6

User’s Guide

FIGURES
Figure 2.1
Figure 2.2
Figure 2.3
Figure 2.4
Figure 2.5
Figure 2.6
Figure 2.7
Figure 2.8
Figure 2.9
Figure 2.10
Figure 2.11
Figure 2.12
Figure 2.13
Figure 2.14
Figure 2.15
Figure 2.16
Figure 2.17
Figure 3.1
Figure 3.2
Figure 3.3
Figure 3.4
Figure 3.5

Figure 3.6
Figure 3.7
Figure 3.8
Figure 3.9
Figure 3.10
Figure 3.11
Figure 3.12
Figure 3.13
Figure 3.14
Figure 3.15
Figure 3.16

PostScript plot from “TEST3.DAT” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3DEC model of a rock slope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
History of z-velocity for initial rock slope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rock slope failure in progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Vertical cross-section through wedge showing displacement vectors . . . . . . .
Example of a 3DEC model (not to scale) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3DEC model block divided into two blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General solution procedure for static analysis in geomechanics . . . . . . . . . . . .
Block model with three intersecting joint planes . . . . . . . . . . . . . . . . . . . . . . . . .
Tunnel in jointed rock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tunnel in jointed rock — excavation and joint structure . . . . . . . . . . . . . . . . . .
Maximum unbalanced force history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
z-displacement history at (.3, 0, .3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sliding wedge in tunnel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
z-displacement history at (.3, −0.1, .3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
z-displacement history at (.3, −0.1, .3) — wedge is stable . . . . . . . . . . . . . . . .
Sign convention for positive stress components . . . . . . . . . . . . . . . . . . . . . . . . . .
Spectrum of modeling situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cubic model created with the POLY face command . . . . . . . . . . . . . . . . . . . . . .
An octahedral-shaped prism generated with the POLY prism command . . . . .
Tunnel model created with the POLY tunnel command . . . . . . . . . . . . . . . . . . . .
Terms describing the attitude of an inclined plane:
dip angle, α, is positive measured downward from the horizontal (xy) plane;
dip direction, β, is positive measured clockwise from north (y) . . . . . . . . .
Model created with the JSET and HIDE commands . . . . . . . . . . . . . . . . . . . . . . .
Concave block created with the JOIN command . . . . . . . . . . . . . . . . . . . . . . . . .
Rock slope containing continuous and noncontinuous joints . . . . . . . . . . . . . .
Tunnel created with TUNNEL command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Elements of the POLY cube command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Resultant geometry from example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Orientation of 3DEC model axes (x,y,z) relative to north-east-vertical reference
axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stereonet plot of fault relative to model axes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stereonet plot of pole to fault and model reference axes relative to problem
north-east axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Model for Poisson’s effect in rock with vertical and horizontal jointing . . . .
Poisson’s effect for vertically jointed rock
(ν = 0.3 for intact rock) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3DEC Version 4.1
14

2-8
2 - 11
2 - 13
2 - 15
2 - 15
2 - 16
2 - 20
2 - 25
2 - 27
2 - 28
2 - 29
2 - 36
2 - 37
2 - 39
2 - 39
2 - 42
2 - 44
3-2
3-8
3-9
3 - 11
3 - 12
3 - 14
3 - 15
3 - 16
3 - 19
3 - 20
3 - 22
3 - 23
3 - 26
3 - 26
3 - 28
3 - 29

User’s Guide

Figure 3.17
Figure 3.18
Figure 3.19
Figure 3.20
Figure 3.21
Figure 3.22
Figure 3.23
Figure 3.24
Figure 3.25
Figure 3.26
Figure 3.27
Figure 3.28
Figure 3.29
Figure 3.30
Figure 3.31
Figure 3.32
Figure 3.33
Figure 3.34
Figure 3.35
Figure 3.36
Figure 3.37
Figure 3.38
Figure 3.39
Figure 3.40
Figure 3.41
Figure 3.42
Figure 3.43
Figure 3.44
Figure 3.45
Figure 3.46
Figure 3.47
Figure 3.48
Figure 3.49

Contents - 7

Model for Poisson’s effect in rock with joints dipping at angle θ from the
horizontal and with spacing S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Poisson’s effect for jointed rock at various joint angles (blocks are rigid) . . .
Poisson’s effect for rock with two equally spaced joint sets
with θ = 45◦ (blocks are deformable with ν = 0.2) . . . . . . . . . . . . . . . . . . . .
Uplift when material is removed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mixing stress and velocity boundary conditions . . . . . . . . . . . . . . . . . . . . . . . . .
Models used to transfer stress boundary conditions . . . . . . . . . . . . . . . . . . . . . .
Nonuniform stresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Uniform stresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Slip of a confined joint; plot shows shear stress contours . . . . . . . . . . . . . . . . .
3DEC model of tunnel region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displacement histories at top of model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
z-displacement history at tunnel roof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Close-up view of wedge in roof (surrounding blocks hidden) . . . . . . . . . . . . .
Cable bolts positioned around tunnel excavation . . . . . . . . . . . . . . . . . . . . . . . . .
z-displacement history at tunnel roof — reinforcement element support . . . .
z-displacement history at tunnel roof — cable support . . . . . . . . . . . . . . . . . . . .
Axial forces in reinforcement elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Axial forces in cable elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Thick concrete liner support — liner blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
z-displacement history at tunnel roof — tunnel liner added after tractions reduced by 50% . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Thick concrete liner support — prism-shaped liner blocks . . . . . . . . . . . . . . . .
Thick concrete liner support — mixed-discretization zoning in liner blocks .
z-displacement history at tunnel roof — support by prism-shaped liner blocks
Principal stress distribution in top section of liner . . . . . . . . . . . . . . . . . . . . . . . .
Direct shear test model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Average shear stress versus shear displacement
— Coulomb slip model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Average normal displacement versus shear displacement
— Coulomb slip model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Average shear stress versus shear displacement
— Coulomb slip model with peak and residual strength . . . . . . . . . . . . . . .
Average normal displacement versus shear displacement
— Coulomb slip model with peak and residual strength . . . . . . . . . . . . . . .
Idealized relation for dilation angle, ψ, from triaxial test results (Vermeer and
de Borst 1984) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
σzz -stress versus zz-strain for tension test with cons 2 model . . . . . . . . . . . . .
σzz -stress versus zz-strain for tension test with cons 6 model and tensilesoftening table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xx-strain versus zz-strain for tension test with cons 2 model . . . . . . . . . . . . . .

3 - 30
3 - 30
3 - 31
3 - 37
3 - 38
3 - 41
3 - 49
3 - 50
3 - 53
3 - 62
3 - 64
3 - 65
3 - 66
3 - 67
3 - 70
3 - 70
3 - 71
3 - 71
3 - 74
3 - 75
3 - 78
3 - 78
3 - 79
3 - 79
3 - 84
3 - 87
3 - 87
3 - 88
3 - 89
3 - 93
3 - 97
3 - 98
3 - 99

3DEC Version 4.1
15

Contents - 8

Figure 3.50
Figure 3.51
Figure 3.52

User’s Guide

xx-strain versus zz-strain for tension test with cons 6 model and tensilesoftening table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 99
Plot of shear failure in model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 116
A small portion of a jointed rock mass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 118

3DEC Version 4.1
16

User’s Guide

Contents - 9

EXAMPLES
Example 2.1
Example 2.2
Example 2.3
Example 2.4
Example 2.5
Example 2.6
Example 2.7
Example 2.8
Example 2.9
Example 3.1
Example 3.2
Example 3.3
Example 3.4
Example 3.5
Example 3.6
Example 3.7
Example 3.8
Example 3.9
Example 3.10
Example 3.11
Example 3.12
Example 3.13
Example 3.14
Example 3.15
Example 3.16
Example 3.17
Example 3.18
Example 3.19
Example 3.20
Example 3.21
Example 3.22
Example 3.23
Example 3.24
Example 3.25
Example 3.26

3DEC output from “TEST1.DAT” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3DEC model block divided into two blocks . . . . . . . . . . . . . . . . . . . . . . . . . . .
Block model with three intersecting joint planes . . . . . . . . . . . . . . . . . . . . . . .
Tunnel in jointed rock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning material models and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying boundary and initial conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stepping to initial equilibrium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reduce the strength of the joints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stabilize roof block with a cable bolt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A cube generated with the POLY face command . . . . . . . . . . . . . . . . . . . . . . . .
A cube generated with the POLY brick command . . . . . . . . . . . . . . . . . . . . . . .
An octahedral-shaped prism generated with the POLY prism command . . .
A tunnel model generated with the POLY tunnel command . . . . . . . . . . . . . .
Creation of a noncontinuous vertical joint . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rock slope containing continuous and noncontinuous joints . . . . . . . . . . . . .
Tunnel created with the TUNNEL command . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data file which generates a model using POLY cube command . . . . . . . . . . .
Uplift when material is removed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mixing stress and velocity boundary conditions . . . . . . . . . . . . . . . . . . . . . . . .
Initial and boundary stresses in equilibrium . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initial stress state with gravitational gradient . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initial stress gradient in a nonuniform material . . . . . . . . . . . . . . . . . . . . . . . . .
Nonuniform stress initialized in a model with nonuniform zoning . . . . . . . .
Initial stresses following a model change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Slip of a confined joint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stability analysis of an underground excavation — initial model . . . . . . . . .
Stability analysis of an underground excavation — initial equilibrium stress
state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stability analysis of an underground excavation — unsupported tunnel . . .
Stability analysis of an underground excavation — local reinforcement support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stability analysis of an underground excavation — fully grouted cable support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stability analysis of an underground excavation — reduce tunnel tractions
by 50% and install liner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stability analysis of an underground excavation — liner with m-d zoning .
Direct shear test with Coulomb slip model . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tension test on tensile-softening material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Factor-of-safety calculation for a simple joint model . . . . . . . . . . . . . . . . . . .

2-7
2 - 19
2 - 26
2 - 27
2 - 32
2 - 34
2 - 36
2 - 38
2 - 41
3-7
3-8
3-9
3 - 10
3 - 13
3 - 16
3 - 18
3 - 21
3 - 36
3 - 37
3 - 44
3 - 45
3 - 46
3 - 47
3 - 51
3 - 52
3 - 59
3 - 62
3 - 64
3 - 67
3 - 68
3 - 72
3 - 75
3 - 84
3 - 95
3 - 115

3DEC Version 4.1
17

Contents - 10

Example 4.1
Example 4.2
Example 4.3
Example 4.4
Example 4.5
Example 4.6
Example 4.7
Example 4.8
Example 4.9
Example 4.10
Example 4.11
Example 4.12
Example 6.1

User’s Guide

Defining a FISH function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SETting variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Test your understanding of function and variable names . . . . . . . . . . . . . . . .
Capturing the history of a FISH variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FISH functions to calculate bulk and shear moduli . . . . . . . . . . . . . . . . . . . . .
Using symbolic variables in 3DEC input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlled loop in FISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying a nonlinear initial distribution of moduli . . . . . . . . . . . . . . . . . . . . .
Splitting lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Variable types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Action of the IF ELSE ENDIF construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Benchmark data file — “TIMING.DAT” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3DEC Version 4.1
18

4-2
4-3
4-3
4-4
4-4
4-6
4-6
4-7
4-8
4-9
4-9
4 - 11
6-2

INTRODUCTION

1-1

1 INTRODUCTION
1.1 Overview
3DEC is a three-dimensional numerical program based on the distinct element method for discontinuum modeling. The basis for this program is the extensively tested numerical formulation used
by the two-dimensional version, UDEC (Itasca 2004). 3DEC simulates the response of discontinuous media (such as a jointed rock mass) subjected to either static or dynamic loading. The
discontinuous medium is represented as an assemblage of discrete blocks. The discontinuities
are treated as boundary conditions between blocks; large displacements along discontinuities and
rotations of blocks are allowed. Individual blocks behave as either rigid or deformable material.
Deformable blocks are subdivided into a mesh of finite difference elements, and each element responds according to a prescribed linear or nonlinear stress-strain law. The relative motion of the
discontinuities is also governed by linear or nonlinear force-displacement relations for movement in
both the normal and shear directions. 3DEC has several built-in material behavior models, for both
the intact blocks and the discontinuities, that permit the simulation of response representative of
discontinuous geologic, or similar, materials. 3DEC is based on a Lagrangian calculation scheme
that is well-suited to model the large movements and deformations of a blocky system.
The distinguishing features of 3DEC are summarized:
• The rock mass is modeled as a 3D assemblage of rigid or deformable blocks.
• Discontinuities are regarded as distinct boundary interactions between these
blocks; joint behavior is prescribed for these interactions.
• Continuous and discontinuous joint patterns can be generated on a statistical
basis. A joint structure can be built into the model directly from the geologic
mapping.
• 3DEC employs an explicit in-time solution algorithm that accommodates both
large displacement and rotation, and permits time-domain calculations.
• The graphics facility permits interactive manipulation of 3D objects. In the
graphics screen mode, the user can “move” into the model and make regions
invisible, which allows for better viewing. This allows the user to build the
model for a geotechnical analysis, and instantly view the 3D representation.
This greatly facilitates the generation of 3D models and interpretation of results.
3DEC also contains the powerful built-in programming language FISH (short for FLACish; FISH
was originally developed for our two-dimensional, finite-difference continuum program, FLAC).
With FISH, you can write your own functions to extend 3DEC ’s usefulness. FISH offers a unique
capability to 3DEC users who wish to tailor analyses to suit specific needs.

3DEC Version 4.1
19

1-2

User’s Guide

With the exception of the graphics mode, 3DEC is a command-driven (rather than menu-driven)
computer program. Although a menu-driven program is easier to learn for the first time, the
command-driven structure in 3DEC offers several advantages when applied in engineering studies:
1. The input “language” is based upon recognizable word commands that allow
you to identify the application of each command easily and in a logical fashion
(e.g., the BOUNDARY command applies boundary conditions to the model).
2. Engineering simulations usually consist of a lengthy sequence of operations —
e.g., establish in-situ stress, apply loads, excavate tunnel, install support, etc.
A series of input commands (from a file or from the keyboard) corresponds
closely with the physical sequence that it represents.
3. A 3DEC data file can easily be modified with a text editor. Several data files
can be linked to run a number of 3DEC analyses in sequence. This is ideal for
performing parameter sensitivity studies.
4. The word-oriented input files provide an excellent means by which to keep a
documented record of the analyses performed for an engineering study. Often,
it is convenient to include these files as an appendix to the engineering report,
for the purpose of quality assurance.
5. The command-driven structure allows you to develop pre- and post-processing
programs to manipulate 3DEC input/output as desired. For example, you may
wish to write a joint-generation function to create a special joint structure for a
series of 3DEC simulations. This can readily be accomplished with the FISH
programming language, and incorporated directly in the input data file.
The formulation and development of the distinct element method embodied in 3DEC has progressed
for a period of over 35 years, beginning with the initial presentation by Cundall (1971). In 1988,
Dr. Cundall and Itasca staff adapted 3DEC specifically to perform engineering calculations on a
PC. The software is designed for high-speed computation of models containing several thousand
blocks. With the advancements in floating-point operation speed, and the ability to install additional
RAM at low cost, increasingly larger problems can be solved with 3DEC.
For example, 3DEC can solve a model containing up to 3300 rigid blocks (or 2900 deformable
blocks with 24 degrees of freedom per block) on a microcomputer using 32 MB RAM. The solution
speed for a model of this size is roughly 600 calculation steps per minute (or 480 calculation steps
per minute for a 3000 deformable block model) on a 3.0 GHz Pentium Xeon 5160 microcomputer.*
The calculation speed is essentially a linear function of the number of blocks in a model, and the
number of blocks is a linear function of the available RAM on the computer (see Table 2.1 in
Section 2.1.3).
For typical models, consisting of roughly 2000 rigid blocks (or 1000 deformable blocks) or fewer,
the explicit solution scheme in 3DEC requires approximately 2000 to 4000 steps to reach a solved
* See Section 6 for a comparison of 3DEC runtimes on various computer systems.

3DEC Version 4.1
20

INTRODUCTION

1-3

state.* For example, a 1000 deformable-block model run on the Pentium computer described
above would require roughly 3 minutes to perform 4000 calculation steps. Consequently, typical
engineering problems involving several hundred blocks and multiple solution stages can be solved
with 3DEC on a microcomputer in a matter of minutes or hours.
A comparison of 3DEC to other numerical methods, a description of general features and new
updates in 3DEC Version 4.1, and a discussion of fields of application are provided in the following
sections. If you wish to try 3DEC right away, the program installation instructions and a simple
tutorial are provided in Section 2.2.

* This will vary depending on the amount of relative motion that occurs between blocks. The explicit
solution scheme is explained in Section 1.2.2 in Theory and Background.

3DEC Version 4.1
21

1-4

User’s Guide

1.2 Comparison with Other Methods
Some common questions asked about 3DEC are: Is 3DEC a distinct element or discrete element
program? What is the difference, and what is 3DEC ’s relation to other programs? We provide a
definition here which we hope will clarify these matters.
Many finite element, boundary element and Lagrangian finite difference programs have interface elements or “slide lines” that enable them to model a discontinuous material to some extent. However,
their formulation is usually restricted in one or more of the following ways: first, the logic may break
down when many intersecting interfaces are used; second, there may not be an automatic scheme
for recognizing new contacts; and third, the formulation may be limited to small displacements
and/or rotation. Such programs are usually adapted from existing continuum programs.
The name discrete element method applies to a computer program only if it:
(a) allows finite displacements and rotations of discrete bodies, including complete
detachment; and
(b) recognizes new contacts automatically as the calculation progresses.
Without the first attribute, a program cannot reproduce some important mechanisms in a discontinuous medium; without the second, the program is limited to small numbers of bodies for which the
interactions are known in advance. The term distinct element method was coined by Cundall and
Strack (1979) to refer to the particular discrete-element scheme that uses deformable contacts and
an explicit, time-domain solution of the original equations of motion (not the transformed, modal
equations).
There are four main classes of computer programs that conform to the proposed definition of
a discrete element method. (The classes and representative programs are discussed further in
Section 1.1.1 in Theory and Background.)
1. Distinct Element Programs — These programs use explicit time-marching to
solve the equations of motion directly. Bodies may be rigid or deformable
(by subdivision into elements); contacts are deformable. 3DEC falls into this
category.
2. Modal Methods — The method is similar to the distinct element method in the
case of rigid bodies, but, for deformable bodies, modal superposition is used.
3. Discontinuous Deformation Analysis — Contacts are rigid, and bodies may
be rigid or deformable. The condition of no-interpenetration is achieved by an
iteration scheme; the body deformability comes from superposition of strain
modes.
4. Momentum-Exchange Methods — Both the contacts and the bodies are rigid:
momentum is exchanged between two contacting bodies during an instantaneous collision. Frictional sliding can be represented.

3DEC Version 4.1
22

INTRODUCTION

1-5

There are several published schemes that appear to resemble discrete element methods, but which
are different in character, or are lacking one or more essential ingredients. For example, many
publications are concerned with the stability of one or more rigid bodies, using the limit equilibrium
method (Hoek (1973); Warburton (1981); Goodman and Shi (1985); Lin and Fairhurst (1988)). This
method computes the static force equilibrium of the bodies, and does not address the changes in
force distribution that accompany displacements of the bodies.

3DEC Version 4.1
23

1-6

User’s Guide

1.3 General Features
1.3.1 Basic Features
3DEC is primarily intended for analysis in rock engineering projects, ranging from studies of the
progressive failure of rock slopes to evaluations of the influence of rock joints, faults, bedding
planes, etc. on underground excavations and rock foundations. 3DEC is ideally suited to study
potential modes of failure directly related to the presence of discontinuous features.
The program can best be used when the geologic structure is fairly well-defined (for example, from
observation or geologic mapping). Both a manual and automatic joint generator are built into 3DEC
to create individual, and sets of, discontinuities which represent jointed structure in a rock mass. A
wide variety of joint patterns can be generated in the model. There are also two tunnel generators
to set up models with long, regularly shaped excavations.
A pre-processor program (PGEN) is provided for reading AutoCad DXF files of section views of
a body that can be manipulated to provide a 3DEC data file to generate polyhedra which define a
model’s block structure. This program is particularly useful for defining complex excavations or
geologic shapes.
Different representations of joint material behavior are available. The basic model is the Coulomb
slip criteria, which assigns elastic stiffness, frictional, cohesive and tensile strengths, and dilation
characteristics to a joint. A modification to this model is the inclusion of displacement weakening
as a result of loss in cohesive and tensile strength at the onset of shear failure. A more complex
model (the continuously yielding joint model) is also available, and simulates continuous weakening
behavior as a function of accumulated plastic shear displacement. Joint models and properties can
be assigned separately to individual, or sets of, discontinuities in a 3DEC model. Note that the
geometric roughness of a joint is represented via the joint material model, even though the plot of
discontinuities shows the joint as a planar segment.
Blocks in 3DEC can be either rigid or deformable. There are five built-in (19 with the userdefined/extended models option (UDM)) material models for deformable blocks, ranging from the
“null” block material (which represents holes (excavations)), to the shear yielding models (which
include strain-hardening/softening behavior and represent nonlinear, irreversible shear failure).
Thus, blocks can be used to simulate backfill and soil materials, as well as intact rock. (Purchasers
of the UDM option may write their own models.) An effective stress analysis can be performed by
assigning a pore-pressure distribution that acts on both the blocks and the contacts.
The automatic zone generator in 3DEC allows the user to divide deformable blocks into finitedifference tetrahedral zones. A single command allows the user to specify as fine a discretization
as needed, and to vary the discretization throughout the model. Thus, a fine tetrahedral mesh can
be prescribed for blocks in the region of interest, and a coarser mesh can be used for blocks farther
out. 3DEC also has “inner/outer region” coupling, and automatic radially graded mesh generation
within polyhedra for modeling “infinite domain” problems. For block plasticity analysis, a special
zone generator can be used to create “mixed-discretization” blocks, for improved accuracy when

3DEC Version 4.1
24

INTRODUCTION

1-7

modeling plastic collapse. The user may also use high-order tetrahedral elements or nodal mixed
discretization for plasticity problems.
The explicit solution algorithm in 3DEC permits either static or dynamic analysis. Static analysis
is the default solution mode. Dynamic analysis is provided as an optional feature, and is discussed
in Section 1.3.2.
Both stress (force) and fixed-displacement (zero velocity) boundary conditions are available for
static analysis. Boundary conditions may be different at different locations.
3DEC includes the ability to model steady-state or transient-fracture fluid flow. The flow logic
includes a system of flow planes, flow pipes and flow knots.
Structural element logic is implemented to simulate rock reinforcement. Reinforcement includes
point-anchored and fully grouted cables and bolts. An optional surface support/liner model is also
available and is described in Section 1.3.2.
3DEC contains a powerful built-in programming language, FISH, that enables the user to define new
variables and functions. FISH is a compiler: programs entered via a 3DEC data file are translated
into a list of instructions stored in 3DEC ’s memory space; these are executed whenever a FISH
function is invoked. FISH permits:
• user-prescribed property variations in the block structure (e.g., nonlinear increase in modulus with depth);
• plotting and printing of user-defined variables (custom-designed
plots);
• implementation of special joint generators;
• servo-control of numerical tests;
• specification of unusual boundary conditions with variations in time
and space; and
• automation of parameter studies.
Interactive manipulation of screen images is built directly into 3DEC. This allows the user to
generate shaded perspective views, wire-frames, vectors, tensors, contours, time histories, etc. The
history plots are especially helpful in ascertaining when an equilibrium state or failure state has been
reached. 3DEC also has the facility to create two-dimensional “windows” through the 3D model.
On these windows, output can be presented in the form of principal stress plots, stress contour plots,
relative shear plots and vector plots. All plots can be created in screen mode by single keystrokes
that move and rotate the 3D model, orient the window and produce the required output (vectors,
contours, etc.). The output can then be directed to a hardcopy device for incorporation into reports.

3DEC Version 4.1
25

1-8

User’s Guide

1.3.2 Optional Features
Four optional features (dynamic analysis, thermal analysis, user-defined models (UDM) and modeling surface support) are available as separate modules that can be included in 3DEC at an additional
cost per module.
Dynamic analysis can be performed with 3DEC, using the optional dynamic calculation module.
User-specified velocity or stress waves can be input directly to the model either as an exterior
boundary condition or an interior excitation to the model. A library of simple dynamic wave forms
is also available for input. 3DEC contains absorbing boundary conditions to simulate the effect
of an infinite elastic medium surrounding the model. The dynamic analysis option is described in
Section 2 in Optional Features.
There is a limited thermal analysis option available as a special module in 3DEC. This model
simulates the transient conduction of heat in materials and the subsequent development of thermally
induced stresses. Heat sources can be added and can be made to decay exponentially with time.
The thermal option is described in Section 1 in Optional Features.
The user-defined model (UDM) option provides the capability for the user to write their own block
material models. The models are compiled as a DLL and are linked when requested by the user. As
part of the UDM option, an additional 14 block constitutive models are available. These include 8
viscous models, two non-isotropic elastic models and 4 plasticity models.
A surface-support model is available to simulate structures such as concrete linings, shotcrete and
other forms of tunnel support, and stabilizing lining for open cuts or natural slopes. The optional
surface-support model is described in Section 3 in Optional Features.

3DEC Version 4.1
26

INTRODUCTION

1-9

1.4 Summary of Updates from Version 3.0
3DEC 4.10 contains several improvements. The new features are summarized in the following
sections. Please note that, due to these changes, existing data files created for 3.00 may not operate
correctly in 3DEC 4.10. Data files that contain memory addressees or indices must be modified.
3DEC 4.10 will not restart save files from 3DEC 3.00.
1.4.1 Important Changes to 3DEC that will Affect the Execution of Old Data Files
• The default axis system is now a right-handed coordinate system. To use old
data files that were created using a left-handed coordinate system, use the
CONFIG lh command.
• Use of the SET command with FISH variables, and calling FISH functions,
now requires the FISH name to be preceded by ’@’. This is part of the
enhanced FISH debugging. This also eliminates the interference of FISH
names with command keywords. To run old data files, disable this feature
with the command SET fish safe off.
• The tensile failure behavior of the built-in Mohr constitutive model (jcons =
2) has been changed. This change was made to make the model consistent
with the external DLL models. The tensile strength no longer drops to zero
after the tensile limit has been reached. The tensile stress is maintained at the
tensile strength. See Section 3.8.1.4 for details.
• FISH now has type-checking. This will result in fewer errors when accessing
3DEC data structures. However, it may interfere with the syntax of old FISH
files. The type-checking can be partially disabled with the command SET fish
int con on.
• FISH now follows the C++ convention of requiring that variables be defined
prior to their use. This is intended to help with typographical errors. The
default setting of this feature is off, but it is highly recommended that it be
turned on with the SET fish autocreate on command.
• A memory setting on the command line needs to have the keyword memory in
front of it. For example,
3dec410 gui memory 1000

where 1000 is the number of MB allocated.
• The PLOT command has been changed. Each plot item has its own set of
modifiable attributes. Multiple plot items can be combined in one view (i.e.,
excavations in solid, and the rest of the model in wireframe). Keywords which
control view parameters (i.e., orientation and center) must be specified as
separate commands. For example:

3DEC Version 4.1
27

1 - 10

User’s Guide

PLOT BLOCK
PLOT SET DIP 90 DD 180

• The STRUCT liner command now requires a keyword (radial or face).
• The PRINT command has been changed to LIST. If the amount of output from
the LIST command is large, it will be redirected to a separate scrollable list
window that will remain until the user deletes it.
• The LABEL hist n command has been replaced with HIST label n ‘label’.
• The LABEL table n command has been replaced with TABLE 1 name ‘label’.
• The INSITU command keyword for pore pressure gradient has been changed
from pgrad to grad, and must follow the PP command.
1.4.2 Redesigned User Interface with Accelerated Interactive Graphics
The new 3DEC interface features faster, OpenGL-based model rendering for rapid rotation and
translation of model views. The interface provides menu-based access to tools for plotting, and
interactive tools for view manipulation and range definition. Complete menu-driven access to all
3DEC file-handling operations is provided. All plot items can be selected with separately defined
properties. This allows the construction of very complex plots. New tools such as cut planes,
slices and cutouts, along with transparency, allow the creation of views inside the model. Expanded
surface stress and displacement contours have been added.
1.4.3 Built-in Text Editor
The new user interface includes a built-in data file editor with syntax highlighting, data file command
error-checking and one-click execution. This enables the user to develop data files inside of 3DEC
and have them checked for command errors without actually running them. This reduces the time
needed to write input files.
1.4.4 Optional User-Defined Joint Constitutive Models
This optional feature allows the user to create joint constitutive models that are compiled as DLL
files and are linked into 3DEC during execution. This feature is included in the User Defined
Models (UDM) option, and has been implemented in a fashion similar to the way user-defined zone
constitutive models are implemented. The models are designed to accept the current normal and
shear stresses, along with an incremental normal and shear displacement, as inputs, and return new
values of the normal and shear stress. See Section 5 in Optional Features.

3DEC Version 4.1
28

INTRODUCTION

1 - 11

1.4.5 Nodal Mixed Discretization (NMD)
The new Nodal Mixed Discretization (NMD) technique provides more accurate solutions for plasticity analyses with models composed of linear tetrahedral zones, overcoming the over-stiff behavior
observed during plastic flow with this type of zone. This provides accuracy of plasticity calculations
similar to those for mixed discretization, but without the geometric constraints of hexahedral blocks.
Give the SET nodal on command to use NMD. See Section 1.2.3 in Theory and Background.
1.4.6 Reduced Memory Requirement for 32-Bit Double Precision Version
In the previous version of 3DEC, the double precision version required 3 times the memory of the
same model in single precision. This requirement has been reduced to twice the amount of memory
required by the single precision version.
1.4.7 64-bit Version
Version 4.1 includes a version (in addition to the 32-bit version) that is operable on a 64-bit processor
computer running the Windows XP X64 or Windows Vista 64-bit operating system. The 64-bit
version will allow a virtually unlimited model size (17 billion GB of addressable memory). The
64-bit version is functionally equivalent to the 32-bit double precision version. Models developed
in the 64-bit version will require twice the memory of the 32-bit single precision version.
1.4.8 Factor-of-Safety Calculation
The new command SOLVE fos provides the option to solve a model to determine the factor of safety
against general failure or collapse. The technique uses an automated, iterative strength-reduction
method to determine the factor of safety. The command allows selection of the properties that are
used in the strength reduction process. See Section 3.10.5.
1.4.9 New Solve Command (SOLVE elastic) Added
This allows the initial equilibration of stresses in a model, without allowing the stress transients to
cause plastic yielding.
1.4.10 Improvements to the User-Defined Model Interface
All DLL models stored in the “plugins” directory are automatically loaded at runtime. This makes
the restoration of save files easier. Strict controls have been implemented to avoid confusion between
DLL model versions. See Section 5 in Optional Features.

3DEC Version 4.1
29

1 - 12

User’s Guide

1.4.11 Improvements to Structural Element Liner Logic
New logic which simplifies the task of defining locations for structural element liners has been
added. New surface-region marking can be used to paint the surfaces that are to be included in
the liner. The liner elements are then placed on the zone faces that are included in the specified
surface-region range. Lining of tunnels including intersections is easily accommodated. New FISH
and plotting functions allow the printing and plotting of maximum fiber, membrane stresses and
maximum moments. See the STRUCTURE command in Section 1 in the Command Reference.
1.4.12 Improved FISH Language
Revisions to the FISH language include a new debugging capability, the ability to optionally disable
safe mode if debugging is unnecessary, the ability to pass arguments to FISH functions, the ability
to create local variables in a function, and the ability to dynamically create and destroy FISH arrays.
In addition, user-defined FISH intrinsics can be created as C++ DLLs. New syntax controls that
prevent conflict between FISH variables and functions and 3DEC command keywords have been
implemented. See Section 2 in the FISH volume.
1.4.13 Licensing Options for Stand-Alone (Per Machine) or Network Operation
In addition to the standard per-machine license, the new network key facility allows a single hardware
key to be installed on a central (server) computer for a network. 3DEC is run from any computer
on the network, depending on the number of licenses available from the key. Network keys require
a special licensing arrangement and installation.
1.4.14 New PGEN Interface
A new graphical interface has been added to the PGEN utility. This new interface allows the user
to import 3D surface information from DXF files, and use those surfaces as a template to build a
3DEC model. The interface allows the slicing of a 3D surface into polygons that are then used
to create a 3DEC model. The user has full control over the level of detail included in the model
generation process. See Section 5 in Theory and Background.
1.4.15 Compiled HTML Help
The entire Command Reference and FISH in 3DEC volumes are included as an HTML help file
for ease of reference.

3DEC Version 4.1
30

INTRODUCTION

1 - 13

1.4.16 Range Structure and Keywords Have Been Changed
The range keyword is now placed at the end of a command line; it must precede the range description.
Unions, intersections and Boolean logic are now supported. Please review Section 1.1.3 in the
Command Reference for details, because some of the range elements have been changed (e.g.,
sphere, cylinder, annulus, plane, etc.).
1.4.17 Numerical Thermal Calculations
This supplements the previous analytic formulation that assumed a continuous homogeneous mass.
The new formulation permits thermal, mechanical and fluid coupling. Convective heat transfer
through fluid flow is supported. See Section 1 in Optional Features.
1.4.18 New radial Keyword for the TUNNEL Command
The new radial keyword for the TUNNEL command uses a new method to cut tunnel shapes. These
shapes will be cut radially rather than tangentially. The resulting blocks are easier to cut and zone.

3DEC Version 4.1
31

1 - 14

User’s Guide

1.5 Fields of Application
3DEC was originally developed to perform stability analysis of jointed rock slopes. The discontinuum formulation for rigid blocks and the explicit time-marching solution of the full equations
of motion (including inertial terms) facilitate the analysis of progressive, large-scale movements of
slopes in blocky rock.
3DEC has been applied most often in studies related to mining engineering. Both static and dynamic
analyses for deep underground mine openings have been performed. Fault-slip induced failure
around excavations is one example of an analysis conducted with 3DEC. Blasting effects have
been studied by applying dynamic stress or velocity waves at model boundaries. Research in the
area of fault-slip induced seismicity has also been conducted by use of the continuously yielding joint
model. Structural elements have been employed to simulate various rock reinforcement systems
such as grouted rockbolting.
3DEC has also been applied in the fields of underground construction and deep underground storage
of high-level radioactive waste. Through the use of the optional thermal model, 3DEC has been
used to simulate effects of thermal loading in connection with buried nuclear waste.
3DEC has been used to a limited extent as a computational design tool. However, the program is
better-suited to investigate potential failure mechanisms associated with the response of a jointed
rock mass. The nature of a jointed rock mass is that it is a “data-limited” system — i.e., the internal
structure and stress state are, in large part, unknown and unknowable. Thus, it is impossible, in
principle, to make a complete model of a rock mass system. Nevertheless, an understanding of
the response of underground openings in jointed rock can be achieved at a phenomenological level
using 3DEC. This methodology seeks to improve the engineering understanding of the relative
impact of various phenomena on the rock mechanics design. In this way, the engineer can anticipate potential problem areas by identifying mechanisms that may lead to unacceptable states of
deformation/loading (or failure) of the underground opening. The paper by Starfield and Cundall
(1988) is recommended as a guide for using 3DEC in rock engineering projects.
Section 7 presents a bibliography of published reports on the application of 3DEC in the fields of
mining and underground engineering. Additionally, 3DEC has the potential for application in other
fields of engineering, as discussed below and listed in Section 7.
3DEC has the potential for application in studies related to earthquake engineering. For example,
the program may be used to provide explanations of phenomena related to fault movement.
3DEC is particularly well-suited to simulate blocky structures, such as stone masonry arches.
Example studies are the assessment of safety conditions of old masonry bridges (see Lemos 1997
in Section 7) and the seismic behavior of stone masonry arches (see Lemos 1995 in Section 7).
3DEC has also been used to simulate the behavior of a concrete arch dam constructed on a jointed
rock foundation (see Lemos 1996 in Section 7) and the stability condition of underground power
stations (see Dasgupta and Lorig 1995, and Dasgupta et al., 1995 in Section 7).

3DEC Version 4.1
32

INTRODUCTION

1 - 15

1.6 Guide to the 3DEC Manual
The 3DEC Version 4.1 manual consists of six documents. This document (the User’s Guide)
is the main guide to using 3DEC, and contains descriptions of the features and capabilities of
the program, along with recommendations on the best use of 3DEC for problem solving. The
remaining documents cover various aspects of 3DEC, including theoretical background information,
verification testing and example applications. The complete manual is available in electronic format
on the Itasca software CD-ROM (viewed with Acrobat Reader), as well as in paper format.
The organization of the six documents, and brief summaries of the contents of each section, follows.
Please note that if you are viewing the manual in the Acrobat Reader, double-clicking on a section
number given below will immediately open that section for viewing.
User’s Guide
Section 1

Introduction
This section introduces you to 3DEC and its capabilities and features. An overview
of the new features in the latest version of 3DEC is also provided.

Section 2

Getting Started
If you are just beginning to use 3DEC, or are only an occasional user, we recommend that you read Section 2. This section provides instructions on installation and
operation of the program, as well as a simple tutorial to guide the new user through
a 3DEC analysis.

Section 3

Problem Solving with 3DEC
Section 3 is a guide to practical problem solving. Turn to this section once you are
familiar with the program operation. Each step in a 3DEC analysis is discussed in
detail, and advice is given on the most effective procedures to follow when creating,
solving and interpreting a 3DEC model simulation.

Section 4

FISH Beginner’s Guide
Section 4 provides the new user with an introduction to the FISH programming
language in 3DEC. This includes a tutorial on the use of the FISH language. FISH
is described in detail in Section 2 in the FISH volume.

Section 5

Graphical Interface
3DEC contains a graphical interface to facilitate both model creation and presentation
of results. The 3DEC help menu describes the features of this interface.

Section 6

Miscellaneous
Various information is contained in Section 6, including the 3DEC runtime benchmark and procedures for reporting errors and requesting technical support.

3DEC Version 4.1
33

1 - 16

Section 7

User’s Guide

Bibliography
Section 7 contains a bibliography of published papers that describe some uses of
3DEC.

Command Reference
Section 1

Command Reference
All of the commands that can be entered in the command-driven mode in 3DEC are
described in Section 1 in the Command Reference.

FISH in 3DEC
Section 1

FISH Beginner’s Guide
Section 1 in the FISH volume provides the new user with an introduction to the
FISH programming language in 3DEC. This includes a tutorial on the use of the
FISH language.

Section 2

FISH Reference
Section 2 in the FISH volume contains a detailed reference to the FISH language.
All FISH statements, variables and functions are explained, and examples are given.

Section 3

Library of FISH Functions
A library of common and general-purpose FISH functions is given in Section 3 in
the FISH volume. These functions can assist with various aspects of 3DEC model
generation and solution.

Section 4

Program Guide
Section 4 in the FISH volume contains a program guide to 3DEC ’s linked-list data
structure. This is provided so that advanced users have more direct access to 3DEC
variables.

3DEC Version 4.1
34

INTRODUCTION

1 - 17

Theory and Background
Section 1

Background — The 3D Distinct Element Method
The theoretical formulation for 3DEC is described in detail in Section 1 in Theory
and Background.

Section 2

Block Constitutive Models
The theoretical formulation and implementation of the various block constitutive
models are described in Section 2 in Theory and Background.

Section 3

Continuously Yielding Joint Model
Section 3 in Theory and Background describes the formulation for the continuously
yielding joint model. A simulation of a direct shear test with the model is also given.

Section 4

Structural Elements
Section 4 in Theory and Background describes the structural-element reinforcement models available in 3DEC.

Section 5

Polygon Generator
The pre-processor program PGEN, which assists with the creation of complex models, is described in Section 5 in Theory and Background.

Section 6

Joint Fluid Flow
Section 6 in Theory and Background describes the implementation of joint fluid
flow in 3DEC.

Optional Features
Section 1

Thermal Option
Section 1 in Optional Features describes the thermal model option, and presents
several verification problems that illustrate its application both with and without
interaction with mechanical stress.

Section 2

Dynamic Analysis
The dynamic analysis option is described, and considerations for running a dynamic
model are provided, in Section 2 in Optional Features. Several verification examples are also included in this section.

Section 3

Structural Liners and Finite Element Blocks
A surface support model option is provided to simulate tunnel lining and slope
stabilizing lining. Section 3 in Optional Features describes the surface support
model.

3DEC Version 4.1
35

1 - 18

Section 4

User’s Guide

User-Defined and Extended Constitutive Models
Section 4 in Optional Features contains theoretical descriptions of several material
constitutive models, and the instructions needed to write new models that can be
used by 3DEC.

Section 5

User-Defined Joint Constitutive Models
Section 5 in Optional Features includes the instructions needed to write new joint
constitutive models that can be used by 3DEC.

Verification Problems and Example Applications
This volume is divided into two sections. The first section contains a collection of
3DEC verification problems. These are tests in which a 3DEC solution is compared
directly to an analytical (i.e., closed-form) solution. See Table 1 in the Verification
and Examples volume for a list of the verification problems.
The second section contains example applications of 3DEC that demonstrate the
various classes of problems to which 3DEC may be applied. See Table 2 in the
Verification and Examples volume for a list of the example applications.

3DEC Version 4.1
36

INTRODUCTION

1 - 19

1.7 Itasca Consulting Group, Inc.
Itasca Consulting Group Inc. is more than a developer and distributor of engineering software.
Itasca is a consulting and research firm comprised of a specialized team of civil, geotechnical and
mining engineers with an established record in solving problems in the areas of:
Civil Engineering
Mining Engineering and Energy Resource Recovery
Nuclear Waste Isolation and Underground Space
Defense Research
Software Engineering
Groundwater Analysis and Dewatering
Itasca was established in 1981 to provide advanced rock mechanics services to the mining industry.
Today, Itasca is a multidisciplinary geotechnical firm with 70 professionals in offices worldwide.
The corporate headquarters for Itasca is located in Minneapolis, Minnesota. Worldwide offices of
Itasca are operated as subsidiaries of HCItasca Inc.: Hydrologic Consultants Inc. (Denver, Colorado); Itasca Geomekanik AB (Stockholm, Sweden); Itasca Consultants S.A.S. (Ecully, France);
Itasca Consultants GmbH (Gelsenkirchen, Germany); Itasca Consultores S.L. (Llanera, Spain);
Itasca S.A. (Santiago, Chile); Itasca Africa Ltd. (Johannesburg, South Africa); Itasca Consulting
Canada Inc. (Sudbury, Canada); Itasca Consulting China Ltd. (Wuhan, China); Itasca Consulting
Group Inc. (Japan); Itasca Australia Ltd. (Houston, Texas); and Itasca Australia Ltd. (Melbourne,
Australia).
Itasca’s staff members are internationally recognized for their accomplishments in geological, mining and civil engineering projects. Itasca staff consists of geological, mining, hydrological and
civil engineers who provide a range of comprehensive services such as (1) computational analysis in support of geo-engineering designs, (2) design and performance of field experiments and
demonstrations, (3) laboratory characterization of rock properties, (4) data acquisition, analysis
and system identification, (5) groundwater modeling, and (6) short courses and instruction in the
geomechanics application of computational methods. If you should need assistance in any of these
areas, we would be glad to offer our services.
Itasca Consulting Group is a subsidiary of HCItasca Inc. HCItasca was formed in 1999 with
the merger of Hydrologic Consultants Inc. (HCI) of Denver, Colorado with Itasca Consulting
Group Inc. of Minneapolis, Minnesota. HCI adds advanced groundwater modeling and dewatering
expertise to Itasca.

3DEC Version 4.1
37

1 - 20

User’s Guide

1.8 User Support
We believe that the support Itasca provides to code users is a major reason for the popularity of
our software. We encourage you to contact us when you have a modeling question. We provide
a timely response via telephone, electronic mail or fax. General assistance in the installation of
3DEC on your computer, plus answers to questions concerning capabilities of the various features
of the code, are provided free of charge. Technical assistance for specific user-defined problems
can be purchased on an as-needed basis.
If you have a question, or desire technical support, please contact us at:
Itasca Consulting Group, Inc.
Mill Place
111 Third Avenue South, Suite 450
Minneapolis, Minnesota 55401 USA
Phone:
Fax:
Email:
Web:

(+1) 612-371-4711
(+1) 612·371·4717
software@itascacg.com
www.itascacg.com

We also have a worldwide network of code agents who provide local technical support. Details
may be obtained from Itasca.

3DEC Version 4.1
38

INTRODUCTION

1 - 21

1.9 References
Cundall, P. A. “A Computer Model for Simulating Progressive Large Scale Movements in Blocky
Rock Systems,” in Proceedings of the Symposium of the International Society for Rock Mechanics
(Nancy, France, 1971), Vol. 1, Paper No. II-8, 1971.
Cundall, P. A., and O. D. L. Strack. “A Discrete Numerical Model for Granular Assemblies,”
Geotechnique, 29, 47-65 (1979).
Goodman, R. E., and G.-H. Shi. Block Theory and Its Application to Rock Engineering. New
Jersey: Prentice Hall, 1985.
Hoek, E. “Methods for the Rapid Assessment of the Stability of Three-Dimensional Rock Slopes,”
Quarterly J. Eng. Geol., 6, 3 (1973).
Itasca Consulting Group, Inc. UDEC (Universal Distinct Element Code), Version 4.0. Minneapolis: ICG, 2004.
Lin, D., and C. Fairhurst. “Static Analysis of the Stability of Three-Dimensional Blocky Systems
around Excavations in Rock,” Int. J. Rock Mech. Min. Sci. & Geomech. Abstr., 25(3), 138-147
(1988).
Starfield, A. M., and P. A. Cundall. “Towards a Methodology for Rock Mechanics Modelling,” Int.
J. Rock Mech. Min. Sci. & Geomech. Abstr., 25, 99-106 (1988).
Warburton, P. M. “Vector Stability Analysis of an Arbitrary Polyhedral Rock Block with any
Number of Free Faces,” Int. J. Rock Mech. Min. Sci. & Geomech. Abstr., 18, 415-427 (1981).

3DEC Version 4.1
39

1 - 22

3DEC Version 4.1
40

User’s Guide

GETTING STARTED

2-1

2 GETTING STARTED
This section provides the first-time user with an introduction to 3DEC. If you are familiar with the
program but only use it occasionally, you may find this section (in particular, Section 2.6) helpful in
refreshing your memory on the mechanics of running 3DEC. Getting Started provides instructions
for program installation and start-up on your computer. It also outlines the recommended procedure
for applying 3DEC to problems in geo-engineering, and includes simple examples that demonstrate
each step of this procedure. More complete information on problem solving is provided in Section 3.
3DEC is a command-driven code. This is an important distinction, especially if you are used to
using menu-driven software. As explained previously in Section 1.1, the command-driven structure
allows 3DEC to be a very versatile tool for use in engineering analysis. However, this structure can
present difficulties for new, or occasional, users. Command lines must be entered as input to 3DEC,
either interactively via the keyboard or from a remote data file, in order for the code to operate.
There are over 40 main commands and nearly 400 command modifiers (called keywords) which are
recognized by 3DEC.
To the new user, it may seem an insurmountable task to wade through all of the commands to select
those necessary for a desired analysis. This difficulty is not as formidable as it first appears if the
user recognizes that only a very few commands are actually needed to perform simple analyses. As
the user becomes more comfortable with 3DEC and uses the code regularly, more commands can
be applied and more complex analyses performed. In this section, we provide a primer on the few
basic commands the new (or occasional) user needs to perform simple 3DEC calculations.
This section contains the following information. A step-by-step procedure to install, load and test
the operation of 3DEC on your computer is given in Section 2.1. This is followed by a tutorial
example (Section 2.2) which demonstrates the use of common input commands to execute a 3DEC
model. There are a few things that you will need to know before creating and running your own
3DEC model (i.e., you need to know the 3DEC terminology). The nomenclature used for this
program is described in Section 2.3. The definition of a 3DEC finite-difference grid is given in
Section 2.4. You should also know the syntax for the 3DEC input language when running in
command-driven mode; an overview is provided in Section 2.5. The mechanics of running a 3DEC
model are described in separate steps; in Section 2.6, each step is discussed separately and simple
examples are provided. The sign conventions and systems of units used in the program appear
in Sections 2.7 and 2.8, respectively. The different types of files used and created by 3DEC are
described in Section 2.9.

3DEC Version 4.1
41

2-2

User’s Guide

2.1 Installation and Start-up Procedures
2.1.1 Installation of 3DEC
The 3DEC package, which includes a Windows 2000/XP-console version (see Section 2.1.3 for a
description), is installed in Windows from a CD-ROM using standard Windows procedures. The
code installation, including the executables, utilities, data files and manual, requires approximately
24 MB of disk space.
A default installation of 3DEC from the CD-ROM will install the program, its example files and
the complete 3DEC manual. The Adobe Acrobat Reader is necessary for viewing the manual; an
installation for the Reader is also included on the CD-ROM for users who wish to install it.
To begin installation, insert the CD-ROM into the appropriate drive. If the autorun feature for the CD
drive is enabled, a menu providing options for using the CD will appear automatically. If this menu
does not appear, at the command line ( START –> RUN in Windows) type “[cd drive]:\start.exe”
to access the CD-ROM menu. The option to install 3DEC may be selected from this menu.
The installation program will guide you through installation. When the installation is finished, a
file named “INSTNOTE.PDF” will be found in the program sub-folder (“3DEC410”) that resides
in the main installation folder. (This is the folder that is specified during the installation process as
the location to which files will be copied; by default, this is “\ITASCA.”) The “INSTNOTE.PDF”
file provides a listing of the directory structure that is created on installation, and a description of the
actions that have been performed as part of the installation. This information may be used, in the
unlikely event it is necessary or desirable, to either manually install or manually uninstall 3DEC.
The recommended method for uninstalling 3DEC is to use the Windows “Add/Remove Programs”
applet ( START –> SETTINGS –> CONTROL PANEL –> ADD/REMOVE PROGRAMS ). Please note that references made in the
3DEC manual to files presume the default directory structure described in “INSTNOTE.PDF”; all
data files described in the manual are contained in these folders.
The first time you load 3DEC, you will be asked to enter a customer title. This title will appear
on graphics screen plots and hardcopy plots. The title can be changed by using the SET cust1
command.
After installing the software, connect the 3DEC hardware key to the LPT1 or USB port on the
computer before using the code.
The executable file for 3DEC is “3DEC.EXE,” which is stored in the “\ITASCA\3DEC410” directory.
2.1.2 System Requirements for Windows 2000/XP/Vista
3DEC for Windows 2000/XP/Vista is available as 32-bit and 64-bit Windows applications. Any
computer capable of running Windows 2000/XP/Vista is suitable for use with this version of 3DEC.
The executable file is “3DEC410 gui.exe.”

3DEC Version 4.1
42

GETTING STARTED

2-3

2.1.3 Windows Version
Plots can be sent directly to Windows native printers (using the PLOT hardcopy command). Plots
can also be sent to a bitmap file with the PLOT bitmap command. See Section 2.1.4 for details.
The Windows version of 3DEC is compiled with the Intel Fortran compiler. The Windows executable program will operate under Windows 2000, WinXP or Vista.
Multitasking — You may find yourself switching constantly between your favorite text editor and
3DEC while developing a model. Task-switching or multitasking software helps considerably in
this process. Multitasking with the Windows version of 3DEC operates in the same manner as
other native Windows applications. There is no difficulty with task switching even with a 3DEC
plot displayed. Please note that you cannot edit and save a data file while it is open in 3DEC. Type
 to close the data file in 3DEC.
Memory Allocation — Automatic memory-allocation logic has been implemented in 3DEC. When
loaded, 3DEC will automatically attempt to allocate 100 MB of RAM.
You can change the memory allocation for 3DEC by typing the following when loading 3DEC from
a DOS shell or Windows shortcut:
3dec memory

m

m is the amount of RAM, in MB, that will be made available for a 3DEC model. For example, if
you wish to allocate 600 MB for a model, type
3dec memory 600

After loading 3DEC, type
list mem

for a listing of the total memory available, and the amount (and percentage) of memory currently
used for the model.
If the amount of memory requested is more than that available, Windows will swap memory onto the
hard drive. This will slow execution considerably, and is not recommended. As a guide, Table 2.1
summarizes the approximate maximum numbers of rigid or deformable blocks that can be created
for different sizes of available RAM.

3DEC Version 4.1
43

2-4

User’s Guide

Table 2.1

Maximum number of 3DEC blocks in available RAM

Available RAM
(MB)

Maximum number of
rigid blocks

Maximum number of
deformable blocks∗

100
200
300
600

10,000
20,000
30,000
60,000

9,000
18,000
27,000
54,000

* Assumes 24 translational degrees-of-freedom per block.
Maximum number of blocks will be reduced for more degrees-of-freedom.

2.1.4 Utility Software and Graphics Devices
Several types of utility software and graphics devices that can be of great help while operating
3DEC are available.
Editors — A text editor is used to create 3DEC input data files. Any text editor that produces
standard ASCII text files may be used. Care must be taken if more “advanced” word-processing
software (e.g., WordPerfect, Word) is used: this software typically encodes format descriptions into
the standard output format; these descriptions are not recognized by 3DEC and will cause an error.
3DEC input files must be in standard ASCII format.
Graphic Output — 3DEC supports all Windows-compatible printers. Also, black-and-white or color
output may be written to a file that can be read by some graphics programs, such as CorelDraw. In
addition, a PNG-format screen dump can be imported into other applications.
Screen Capture — Graphics software can assist in the production/presentation of 3DEC results.
3DEC ’s MOVIE command allows graphics images to be stored and later displayed in series. A
movie viewer is contained in the “\ITASCA\Utility” directory.
2.1.5 Version Identification
The version number of 3DEC follows a simple numbering system that identifies the level of updates
in the program. There are three numerical identifiers in the version number — that is,
Version I.JK

where:
I

is an integer starting with 1 that identifies a major release of the code;

J

is an integer that is incremented whenever a modification is made that requires
a major change to the code structure for a supplemental upgrade release of
3DEC; and

3DEC Version 4.1
44

GETTING STARTED

K

2-5

is an integer that is incremented when minor modifications are officially released as an update to the current version.

In addition to the version number, sub-version numbers are also used to identify minor changes
to 3DEC that have been made since the official version was released. Users may access the latest
sub-version of the current version of 3DEC on our web site at http://www.itascacg.com. (Contact
Itasca for further information.) However, 3DEC with a sub-version number greater than that of
the officially released version should be used with caution, because not all features have been fully
tested.
By typing the command
list version

the complete version number, including the sub-version number, can be obtained.
2.1.6 Start-up
The default installation procedure creates an “Itasca Codes” group with icons for 3DEC. The
necessary drivers for the hardware key are installed. The 3DEC hardware key should be attached
to the LPT1 or USB port on your computer after the software installation is complete.
To load 3DEC, simply click the appropriate icon in the Itasca Codes group. Use the Properties
option in Windows to identify a working directory. In fact, create as many icons as needed to
identify a number of individual project directories. Double-click the appropriate icon.
2.1.7 Program Initialization
On start-up, the command line argument “call file” can be included. This will call a data file to be
executed automatically.
2.1.8 Running 3DEC
3DEC can either be run interactively or from an input data file in command-driven mode. If you wish
to run the code interactively, just begin typing in commands. 3DEC will execute each command as
the  key is pressed. If an error arises, an error message will be written to the screen.
As an alternative, an input data file may be created using a text editor (see Section 2.1.4). This file
contains a set of commands just as they would be entered in the interactive mode. Although the data
file may have any name, a common identifying extension (e.g., “.DAT”) will help to distinguish it
from other 3DEC files (see Section 2.9).

3DEC Version 4.1
45

2-6

User’s Guide

The data file can be read into 3DEC by typing the command
call

file.dat

on the command line, in which “FILE.DAT” is the user-assigned name for the data file. You will
see the data entries scroll up the screen as 3DEC reads each line.
2.1.9 Installation Tests
Three simple data files (“TEST1.DAT,” “TEST2.DAT” and “TEST3.DAT”) are included in the
“\Tutorial\Beginner” directory so that you can test that 3DEC is installed properly on your computer. These files test the calculation kernel, the graphics screen plotting and the hardcopy plotting
facilities for your computer. In order to run the third test, a Windows-compatible printer must be
installed as your default printer.
To run these tests, click on START –> PROGRAMS –>
start-up heading will appear on your screen.

ITASCA

–>

3DEC410

. The code will load, and the 3DEC

Now click on FILE –> CALL and select the “\program files\Itasca\data\tutorial\beginner” directory
and click “TEST1.DAT.”
Several data entries should scroll up the screen, and a simple model will be executed for 1000
calculation steps. Example 2.1 contains the results of a successful “TEST1.DAT” run. The output
in this figure summarizes information on the model.
Now run the file “TEST2.DAT.”
A screen plot of this model should appear. The plot is a block plot of the model showing the top
block sliding down the fixed bottom block.
If a Windows-compatible printer is installed, run the file “TEST3.DAT,” and the plot shown in
Figure 2.1 should be sent to your printer. If you do not have a printer connected, type
quit

to stop the installation testing.

3DEC Version 4.1
46

GETTING STARTED

2-7

Example 2.1 3DEC output from “TEST1.DAT”
>pri max
No.
No.
No.
No.
No.

Cycles = 2000
MFREE
of blocks (total)
of blocks (visible)
of vertices
of zones

block vol.
block mass
zone vol.
zone mass
zone stress s11
s22
s33
s12
s13
s23
grid-point x-vel
y-vel
z-vel
fx
fy
fz
x-dis
y-dis
z-dis
No. of contacts
No. of sub-contacts

= 27571
2
2
154
399

min
2.887E+02
5.774E+05
6.659E-01
1.332E+03
min
-2.210E+04
-1.273E+05
-2.104E+04
-4.905E+03
-1.111E+04
-4.386E+03

MTOP =

max
7.113E+02
1.423E+06
6.841E+00
1.368E+04
max
2.365E+04
0.000E+00
1.896E+04
3.180E+04
8.867E+03
5.525E+03
5.424E-01
3.139E-01
1.488E-03
1.613E+05
1.302E+06
2.333E+03
2.862E-01
1.753E-01
8.237E-04

1250000

ISMAX = 249999

average
5.000E+02
1.000E+06
2.506E+00
5.013E+03
average
-1.479E+03
-4.358E+04
-5.028E+00
8.059E+03
1.665E+01
1.671E+01
3.478E-01
2.011E-01
3.512E-04
2.956E+04
1.299E+05
2.786E+02
1.833E-01
1.118E-01
1.929E-04

total
1.000E+03
2.000E+06
1.000E+03
2.000E+06
s.dev.
7.536E+03
3.975E+04
6.906E+03
8.208E+03
1.704E+03
1.449E+03

1
58

If you are not able to reproduce the results of any or all of these three tests, you should review the
system requirements and installation steps in Sections 2.1 through 2.1.7. If you are still having
difficulty, we recommend that you contact Itasca and describe the problem you have encountered
and the type of computer you are using (see Section 6.2 for error-reporting procedures).

3DEC Version 4.1
47

2-8

User’s Guide

Figure 2.1

3DEC Version 4.1
48

PostScript plot from “TEST3.DAT”

GETTING STARTED

2-9

2.2 A Simple Tutorial — Use of Common Commands
This section is provided for the new user who wishes to begin experimenting with 3DEC right away.
A simple example is presented to help you learn some of the basic aspects of solving problems with
3DEC.
The example is a three-dimensional model of a sedimentary rock slope. This is a cut slope in rock
with steeply dipping foliation planes, and is based on an actual problem described by Starfield and
Cundall (1988). A rotational failure was found to occur with simultaneous sliding along both the
foliation planes and the shallow-dipping fracture planes. The rotational failure mode was identified
by two-dimensional distinct element analysis as the principal mechanism for the slope collapse.
The three-dimensional model contains two intersecting discontinuities in the slope, forming a
wedge. We will evaluate the stability of the slope for different values of joint friction. (The data
file, “TUT.DAT” (included in the “\Tutorial\Beginner” directory), contains all of the commands
we are about to enter interactively.)
We run this problem interactively (i.e., by typing the commands from the keyboard, pressing
 at the end of each command line, and seeing the results directly). To begin, load 3DEC
by double-clicking on “3DEC.BAT” in the “\Tutorial\Beginner” directory. Your computer will
load the program and display the initial heading followed by the interactive prompt 3dec>.
We begin by specifying a single polyhedral block using the POLY brick command.* Type
poly brick

(0,80)

(-30,80)

(0,50)

and press  to continue. This command creates a brick-shaped polyhedron which extends
from coordinates 0 to 80 units in the x-direction, from −30 to 80 units in the y-direction, and from
0 units to 50 units in the z-direction. To see the polyhedron, type
plot block

A perspective view of the polyhedron will appear on the screen. The model is viewed from a viewing
plane that is defined as being oriented parallel to and coincident with the graphics screen. The model
view is defined in terms of the position of the viewing plane relative to the model reference axes.
The model axes are a right-handed set (x,y,z) oriented, by default, as x (east), y (North) and z
(vertical). The default view of the model is from the viewing plane oriented parallel to the xz-plane
of the model, with the centroid of the model positioned at the center of the screen. The model can
be moved and rotated by clicking-and-dragging with the mouse. Right-click to drag the model.
The user should click on 3DEC ’s help menu for a full description of the facilities available in the
graphical interface.
The polyhedron is now split into separate polyhedra by using the JSET command. First, we create
boundary blocks that will confine the slope blocks. Enter the commands
* See the command reference list in Section 1.2 in the Command Reference for further details. Note
that command words can be abbreviated (see Section 2.5).

3DEC Version 4.1
49

2 - 10

jset
jset

User’s Guide

dip 90
dip 90

dd 180
dd 180

origin 0,0,0
origin 0,50,0

These commands create two joint planes through the model at locations defined by a dip angle (dip),
a dip direction (dd) and a location on the plane (origin). The dip angle and dip direction are oriented
relative to the model axes. (See Section 3.2.2 for further information on locating joint planes in
the model.) The bounding blocks are then hidden from view before we introduce joint planes that
represent the actual joint structure in the slope. (Note that blocks hidden from view will not be cut
by the JSET command.) To hide the bounding blocks, type
hide range y -30,0
hide range y 50,80
mark region 1

Blocks located in the range −30 < y < 0 and in the range 50 < y < 80 will be hidden from
view. The visible blocks are assigned a region number. Region numbers facilitate the application
of commands to a group of blocks within a specific region.
We now create the shallow-dipping fracture planes with the commands
jset
jset

dip 2.5
dip 2.5

dd 235
dd 315

or 30,0,12.5
or 35,0,30

and the high angle foliation planes with the command
jset dip 76

dd 270

spacing 4

num 5

or 38,0,12.5

The last command contains two additional keywords that allow us to generate a set of joints automatically. The spacing keyword specifies an average spacing between joint planes, and the num
keyword defines the number of joints in the joint set.
We now hide the slope blocks and create a horizontal joint plane that is the base of the slope
excavation:
hide range x 30,80 y 0,50
jset dip 0 dd 0 or 0,0,10
hide range z 0,10
mark region 2

z

0,50

We assign region number 2 to the blocks within the excavation region. Finally, we hide the blocks
surrounding the slope blocks and create the joint planes that define the wedge in the slope:
seek
hide range region 0
hide range z 0,10
hide range x 55,80
hide range x 0,30
jset dip 70 dd 200 or 0,35,0
jset dip 60 dd 330 or 50,15,50

3DEC Version 4.1
50

GETTING STARTED

2 - 11

We can view the slope and joint planes by hiding the boundary blocks and the blocks representing
the excavation:
seek
hide region 0 2

We view the slope oriented at a selected perspective view defined by a dip angle and dip direction
relative to the viewing plane; we also magnify the view by a factor of 2:
plot set [dip 70

dd

210

mag 2]

axes block colorby material

Figure 2.2 shows the model at this view:

Figure 2.2

3DEC model of a rock slope

3DEC Version 4.1
51

2 - 12

User’s Guide

Next, the boundary blocks are immobilized and gravity is activated by typing
seek
fix range z 0 10
fix range x 55 80
fix region 0
hide region 0
delete region 2
gravity 0 0 -10
seek

The FIX commands fix the current velocity (i.e., zero) of all blocks within the specified ranges. The
GRAVITY command assigns a gravitational acceleration in the negative z-direction. In this case we
specify a value of 10 m/sec2 .
Material properties are assigned to a property number for the blocks and joints by typing
prop mat=1 dens=2000
prop jmat=1 kn=1e9 ks=1e9 f=89.
prop jmat=2 kn=1e9 ks=1e9 f=0.0

For this problem, the mass density of all blocks is specified to be 2,000 units (kg/m3 , in this case).
Note that the mass density, not the unit weight of the block material, is assigned. For this exercise,
the blocks are assumed to be rigid; block deformability is neglected.
Two different material numbers are assigned to joints in the model. Both material numbers have the
same contact normal (kn) and shear (ks) stiffness, equal to 1.0 × 109 (here, Pa/m). Joint material
1 has a friction angle equal to 89◦ , and joint material 2 has a friction angle equal to 0◦ . Joint
material 2 is assigned to the joint contacts between the slope blocks and the boundary blocks with
the command
change dip 90 dd 180 jmat=2

This provides a frictionless boundary along the vertical joint planes of the boundary blocks.
At this point, the problem is ready to be executed. As will be seen later, it is often helpful to judge
behavior (e.g., equilibrium, stability, instability) by observing the motion of specified points in the
rock mass. In this problem, we monitor the z-velocity of a point at the location x = 30, y = 30, z =
30. The command used to record this motion is
hist

zvel

(30,30,30) type 1

Following execution of this command, the program returns information about the selected monitoring point (30,30,30). The keyword type instructs the program to print the value (in this case, the
z-velocity of point (30,30,30)) on the screen at specified intervals.
Five hundred calculation cycles are executed by typing
step

500

3DEC Version 4.1
52

GETTING STARTED

2 - 13

During execution, the current cycle count, the calculation time, the maximum out-of-balance force,
the z-velocity of the block vertex closest to point (30,30,30), and the clock time are printed on the
screen every 10 cycles. Inspection of these values indicates that equilibrium has been obtained.
(The velocity and out-of-balance force approach zero.) A graphical representation of this behavior
is obtained by typing
plot

hist 1

To give hardcopy plots a heading, type
title
new title>ROCK SLOPE STABILITY

Next, type
plot hardcopy

to create a hardcopy plot of the z-velocity history (see Figure 2.3).

Figure 2.3

History of z-velocity for initial rock slope

It is often helpful to save this initial state so that it can be restarted at any time (for example, to
perform parameter studies). To save the current state (in a file called “SLOPE.SAV”), type
save

slope.sav

3DEC Version 4.1
53

2 - 14

User’s Guide

The behavior of the slope can be studied by reducing the friction of the joints. We reduce the friction
angle to 6◦ with the command
prop jmat=1 f=6.0

Next, the calculation process continues; the problem state after 2000 additional cycles (2500 cycles
total) is shown in Figure 2.4. This figure was obtained following execution of the following
commands:
cycle 2000
hide reg 0
title
new title> ROCK SLOPE STABILITY -- WEDGE FAILURE
plot dip 70 dd 210 mag 2

The figure shows the failure mode that develops in the slope. The failure mode combines rotational
failure along the foliation planes and rotational failure of the wedge. The wedge failure dominates
the failure, as shown by the block plot in Figure 2.4. The rotational mechanism contributes to
the collapse. This can be seen in a vertical cross-section plot taken through the model. Enter the
commands
plot
plot
plot
plot
plot

clear
set orien (90,180,0) center (38,25,35) mag 1.5
cut add plane origin (0,25,0) name Plane normal (0,1,0)
add displacement colorby on plane onplane on front off behind off
add block fill off plane onp on front off behind off

to view a vertical section through the wedge (see Figure 2.5). Note that cross-sectional plots can be
oriented at any angle through the model, and various parameters can be presented on these sections.
From this point, you may wish to play with the various features of 3DEC in an attempt to stabilize
the slope. Try restarting the previous file you created by entering
rest slope.sav

Try using the structural element logic described in Section 4 in Theory and Background to model
rock anchors or tiebacks to support the slope. (An example illustrating support for this slope is
given in Section 4.2.1.7 in Theory and Background.)
To exit 3DEC, type
quit

This ends the initial tutorial. In the following sections, we will present other features of 3DEC.
We recommend that you read the rest of Getting Started for a beginner’s guide to the mechanics of
using 3DEC. As you become more familiar with the code, turn to Section 3 for additional details
on problem solving with 3DEC.

3DEC Version 4.1
54

GETTING STARTED

2 - 15

Figure 2.4

Rock slope failure in progress

Figure 2.5

Vertical cross-section through wedge showing displacement vectors

3DEC Version 4.1
55

2 - 16

User’s Guide

2.3 Nomenclature
The nomenclature used in 3DEC is similar, for the most part, to that used in continuum stress
analysis programs. In addition though, special terminology is used to describe the discontinuum
features in a 3DEC model. The basic definitions are given here for clarification. Figure 2.6 is
provided to illustrate 3DEC terminology:

fault discontinuity

joint discontinuity

cable

block

in-situ
horizontal
boundary
stress
zone

gridpoint
interior boundary
(excavation)

roller bottom boundary

Figure 2.6

Example of a 3DEC model (not to scale)

3DEC MODEL — The 3DEC model is created by the user to simulate a physical problem. When referring to a 3DEC model, we imply a sequence of 3DEC commands (see Section 1 in the Command
Reference) that define the problem conditions for numerical solution.
BLOCK — The block is the fundamental geometric entity for the distinct element calculation. The
3DEC model is created by either “cutting” a single block into many smaller blocks, or creating
separate blocks and joining them together. Each block is an independent entity that may be detached
from other blocks, or may interact with other blocks via surface forces. Another term for block is
polyhedron.

3DEC Version 4.1
56

GETTING STARTED

2 - 17

CONTACT — Each block is connected to adjacent blocks via point contacts. A contact may be
considered a boundary condition that applies external forces to each block.
SUB-CONTACT — Each contact is divided into sub-contacts for both rigid and deformable blocks.
Interaction forces between blocks are applied at sub-contacts.
DISCONTINUITY — A discontinuity is a geologic feature that separates a physical mass into distinct parts. Discontinuities, for example, include joints, faults and fractures, and other discontinuous
features in a rock mass.
To be represented in 3DEC, a discontinuity must have a trace length scale that is approximately of
the same order as the engineering structure being analyzed. A discontinuity in 3DEC is defined by
at least one contact between blocks.
ZONE — Deformable blocks are composed of tetrahedral finite-difference zones. Mechanical
changes (e.g., stress/strain) are calculated within each zone. Mixed-discretization (m-d) zones are
special zones that are composed of two overlays of five tetrahedral sub-zones. m-d zones provide
accurate solutions for block plasticity analysis.
GRIDPOINT — Gridpoints are associated with the corners of the tetrahedral finite-difference zones
(or sub-zones of m-d zones). There are always four gridpoints associated with each zone. A set
of x-, y-, z-coordinates is assigned to each gridpoint, thus specifying the exact location of the
finite-difference zones. Other terms for gridpoint are nodal point and node.
MODEL BOUNDARY — The model boundary is the periphery of the 3DEC model. Internal
boundaries (i.e., holes within the model) are also model boundaries.
BOUNDARY CONDITION — A boundary condition is the prescription of a constraint or controlled
condition along a model boundary (e.g., a fixed displacement or force for mechanical problems).
INITIAL CONDITIONS — This is the state of all variables in the model (e.g., stresses) prior to
any loading change or disturbance (e.g., excavation).
NULL BLOCK — Null blocks are blocks that represent voids (i.e., no material present) within the
model. Null blocks can be made “real” later in an analysis — for example, to simulate backfilling.
(Once a block is deleted from a model, it cannot be restored.)
BLOCK CONSTITUTIVE MODEL — The block constitutive (or material) model represents the
deformation and strength behavior prescribed to the zones of deformable blocks in a 3DEC model.
Several constitutive models are available in 3DEC to simulate different types of behavior commonly
associated with geologic materials.
JOINT CONSTITUTIVE MODEL — The joint constitutive model represents the normal and shear
interaction between blocks at their contact (sub-contact) points. The joint model includes normal

3DEC Version 4.1
57

2 - 18

User’s Guide

and shear elastic stiffness components, and limiting shear and tensile strength components. The
basic joint model is the Coulomb-slip model.
STRUCTURAL ELEMENT — Structural elements are one-dimensional elements that represent the
interaction of structures (such as rock bolts or cable bolts) with a rock mass. Material nonlinearity
is possible with structural elements. Geometric nonlinearity occurs as a result of the large-strain
formulation.
STEP — Because 3DEC is an explicit code, the solution to a problem requires a number of computational steps. During computational stepping, the information associated with the phenomenon
under investigation is propagated across the blocks in the model. A certain number of steps is
required to arrive at an equilibrium (or steady-flow) state for a static solution. Typical problems are
solved within 2000 to 4000 steps, although large, complex problems can require tens of thousands
of steps to reach a steady state. When using the dynamic analysis option, STEP or CYCLE refers to
the actual timestep for the dynamic problem. Other terms for step are timestep and cycle.
STATIC SOLUTION — A static or quasi-static solution is reached in 3DEC when the rate of change
of kinetic energy in a model approaches a negligible value. This is accomplished by damping the
equations of motion. At the static solution stage, the model will either be at a state of force
equilibrium or a state of steady flow of material if a portion (or all) of the model is unstable (i.e.,
fails) under the applied loading conditions. This is the default calculation mode in 3DEC, and can
also be invoked with the DAMP auto or DAMP local command.
UNBALANCED FORCE — The unbalanced force indicates when a mechanical equilibrium state
(or the onset of joint slip or plastic flow) is reached for a static analysis. A model is in exact
equilibrium if the net nodal force vector at each block centroid or gridpoint is zero. The maximum
nodal force vector is monitored in 3DEC, and printed to the screen when the STEP or CYCLE
command is invoked. The maximum nodal force vector is also called the “unbalanced” or “outof-balance” force. The maximum unbalanced force will never exactly reach zero for a numerical
analysis; the model is considered to be in equilibrium when the maximum unbalanced force is small
compared to the representative forces in the problem. If the unbalanced force approaches a constant
nonzero value, this probably indicates that joint slip or block failure and plastic flow are occurring
within the model.
DYNAMIC SOLUTION — For a dynamic solution, the full dynamic equations of motion (including
inertial terms) are solved; the generation and dissipation of kinetic energy directly affect the solution.
Dynamic solutions are required for problems involving high frequency and short duration loads
(e.g., seismic or explosive loading). The dynamic calculation is an optional module to 3DEC (see
Section 2 in Optional Features).

3DEC Version 4.1
58

GETTING STARTED

2 - 19

2.4 The 3DEC Model
For most geomechanics analyses, the creation of a 3DEC model begins with a single block of a size
that spans the physical region being analyzed.* The model features are then introduced by cutting
this block into smaller blocks whose boundaries represent both the geologic structure (e.g., faults,
bedding planes, joint structure) and engineered structures (such as underground excavations and
tunnels).
All blocks in the model are defined by the x-, y-, z-coordinates of their vertices and centroid.
Contacts between blocks, as well as gridpoints within deformable blocks, are also defined by
their coordinate positions. Model generation involves cutting the model block along planes whose
positions are defined by an orientation (dip and dip direction) and one location on the plane.
All entities of the 3DEC model (i.e., blocks, vertices, contacts, gridpoints and zones) are identified
uniquely by an address number in the main data array, allocated automatically by 3DEC. These
numbers may also be used to refer to a particular entity. The numbering system is not sequential
for each entity, so the user must identify the number via a plot or printout.†
For example, Figure 2.7 illustrates a 3DEC model block of the following dimensions: 10 units (for
example, meters) in the x-direction, 10 units in the y-direction and 10 units in the z-direction. The
model block is divided into two blocks, separated by a horizontal discontinuity located through the
center of the block.
The model shown in Figure 2.7 was created with the commands listed in Example 2.2.
Example 2.2 3DEC model block divided into two blocks
new
poly brick 0,10 0,10 0,10
pl bl
pl reset
jset origin 5 5 5
prop jmat 1 jkn 1.33e7 jks 1.33e7 fric 20.0
prop mat 1 dens 2000
plot block colorby mat
plot set dip 70 dd 210
cyc 1

* The 3DEC model can also be generated by creating separate blocks and joining them together. This
can be useful for building multiple blocky structures, such as masonry walls or arch bridges (e.g.,
see Section 3 in the Examples volume).
† In general, address numbers should be avoided, if possible, when referring to particular entities
in limiting the range of application of a command. Address numbers will likely change with
different versions of 3DEC. Other optional range phases, as listed in Section 1.1.3 in the Command
Reference, should be used whenever possible.

3DEC Version 4.1
59

2 - 20

User’s Guide

ret

Figure 2.7

3DEC model block divided into two blocks

The two blocks have block numbers 218 and 1078. The blocks are connected by one contact located
at the center of the adjacent faces of the two blocks. The contact number is 1739. This information
can be obtained with the commands
list block
list contact

Upon cycling, contacts are automatically decomposed into sub-contacts at which mechanical interactions between blocks are calculated. Sub-contacts are created by triangulating interacting block
faces. For rigid blocks, each triangular section of the face is associated with a vertex on the face.
In this example, we issue the command
cycle 1

to create the sub-contacts. Eight sub-contacts are created; associated with each of the four vertices
defining the two contacting faces. The sub-contact numbers can be viewed with the command
list contact location

The two blocks may be made deformable by creating finite-difference zones in each block. The
blocks in Example 2.2 are made deformable by adding the command
gen edge 20

3DEC Version 4.1
60

GETTING STARTED

2 - 21

The two blocks are each subdivided into six zones, with each zone defined by four gridpoints. The
zone and gridpoint numbers, and the gridpoint coordinates, are printed with the command
list zone location

Note that if we take one cycle, eight sub-contacts are created (as before for the rigid blocks), but
the sub-contact numbers are different because their addresses are created after those for the zones
and gridpoints.
The address numbers also act as pointers to storage locations of all state variables in the model.
Data associated with each entity in the model is stored with that entity number. For example,
block forces, velocities and displacements for rigid blocks are stored with each block number.
For deformable blocks, vector quantities (e.g., forces, velocities, displacements) for a block are
stored with gridpoint numbers, while scalar and tensor quantities (e.g., stresses, material property
numbers) are stored with zone numbers. Contact data (such as contact force, velocity and flow
rates) is stored at sub-contact numbers. FISH can be used to access 3DEC data via the address
numbers. See Section 4 in the FISH volume for lists of the variables that can be accessed.

3DEC Version 4.1
61

2 - 22

User’s Guide

2.5 Command Syntax
All input commands* to 3DEC are word-oriented and consist of a primary command word followed
by one or more keyword and value, as required. Some commands accept switches (i.e., keywords
that modify the action of the command). Each command has the following format:

COMMAND keyword value . . .  . . .
Here, optional parameters are denoted by < >, while the ellipses ( . . . ) indicate that an arbitrary
number of such parameters may be given. The commands are typed literally on the command line.
You will note that only the first few letters are in bold type. The program requires that these letters,
at a minimum, be typed to recognize the command; command input is not case-sensitive. The entire
word for a command or keyword may be entered if the user so desires.
Many of the keywords are followed by a series of values which provide the numeric input required
by the keyword. The decimal point may be omitted from a real value, but may not appear in an
integer value.
Commands, keywords and numeric values may be separated by any number of spaces, or by any
of the following delimiters:
( )
,
=
A semicolon ( ; ) may be used to precede comments; anything that follows a semicolon on an input
line is ignored. It is useful to include comments in data files, and it is strongly recommended. Not
only is the input documented in this way, the comments are echoed to the output as well, providing
the opportunity for quality assurance in your analysis.
A single input line, including comments, may contain up to 80 characters.
If more than 80 characters are required to describe a particular command sequence, then an ampersand (&) can be given at the end of an input line to denote that the next line will be a continuation
of that line. A total of 1024 characters per command sequence are allowed. Please note that the
typographical conventions listed in Table 2.2 are used throughout this manual.
* The commands and their meanings are presented in Section 1 in the Command Reference.

3DEC Version 4.1
62

GETTING STARTED

Table 2.2

2 - 23

Typographical conventions

Type style

Used for

BOLD
bold
bold

3DEC commands and FISH statements
3DEC keywords and FISH internal variables and functions
user-defined FISH variables and functions
menu items and buttons with the hot-keys underlined
place-holders for variables
button with the hot-key underlined
type the key between < > (here, ) on the keyboard
hold down the first key while pressing the second
(here,  and the  key)

Initial Caps

var
Press Me




3DEC Version 4.1
63

2 - 24

User’s Guide

2.6 Mechanics of Using 3DEC
3DEC is based on a command-driven format. Word commands control the operation of the program.
This section provides an introduction to the basic commands a new user needs to perform simple
3DEC calculations. If you have not done so already, run the tutorial problem in Section 2.2 for an
example of command-driven analysis with 3DEC.
In order to set up a model to run a simulation with 3DEC, three fundamental components of a
problem must be specified:
(1) a distinct-element model that matches the problem geometry;
(2) constitutive behavior and material properties; and
(3) boundary and initial conditions.
The model block defines the geometry of the problem. The constitutive behavior and associated
material properties dictate the type of response the model will display upon disturbance (e.g.,
deformational response due to excavation). Boundary and initial conditions define the in-situ state
(i.e., the condition before a change or disturbance in problem state is introduced).
After these conditions are defined in 3DEC, an alteration is made (e.g., excavate material or change
boundary conditions), and the resulting response of the model is calculated. The actual solution of
the problem is different for an explicit-solution program like 3DEC than for conventional implicitsolution programs. (See the background discussion in Section 1.2.2 in Theory and Background.)
3DEC uses an explicit time-marching method to solve the algebraic equations. The solution is
reached after a series of computational steps. In 3DEC, the number of steps required to reach a
solution is controlled manually by the user. The user ultimately must determine whether the number
of steps is sufficient to reach the solved state. See Section 2.6.4 for ways in which this is done.
The general solution procedure for an explicit static* analysis with 3DEC is illustrated in Figure 2.8.
This procedure is convenient because it represents the sequence of processes that occur in the
physical environment. The basic 3DEC commands needed to perform simple analyses with this
solution procedure are described below.

* Dynamic analysis with 3DEC is discussed in Section 2 in Optional Features.

3DEC Version 4.1
64

GETTING STARTED

2 - 25

MODEL SETUP
(1) Generate model block, cut block to create problem
geometry
(2) Define constitutive behavior and material properties
(3) Specify boundary and initial conditions

Step to equilibrium state

Examine the Model Response

PERFORM ALTERATIONS
For Example:
Excavate material
Change boundary conditions

Step to solution

Examine the Model Response

REPEAT FOR ADDITIONAL ALTERATIONS

Figure 2.8

General solution procedure for static analysis in geomechanics

3DEC Version 4.1
65

2 - 26

User’s Guide

2.6.1 Model Generation
The 3DEC model is usually created by cutting the original 3DEC block into smaller blocks that
represent boundaries of physical features in the problem. The simplest block to create is brickshaped and is generated with the command
poly brick

xl, xu

yl, yu

zl, zu

where (xl, xu), (yl, yu) and (zl, zu) are the lower- and upper-coordinate limits of the brick in the x-,
y- and z-directions.
The primary command used to create geologic structure (e.g., joints) is
jset

The JSET command can either create individual joints or invoke an automatic joint set generator
to create a set of joints defined by characteristic parameters (i.e., dip angle, dip direction, spacing,
spatial location and persistence).
The following example illustrates block-cutting with the JSET command. The complete description
for this command is given in Section 1 in the Command Reference. Joint generation is explained
in more detail in Section 3.2.2.
Example 2.3 Block model with three intersecting joint planes
new
poly brick -1 1 -1 1 -1 1
plot block colorby mat
pl reset
plot set dip 70 dd 200
jset dip 65 dd 270 origin 0.3, 0.0, 0.0
jset dip 40 dd 230 origin 0.0, -0.3, 0.0
jset dip 50 dd 320 origin 0.0, 0.3, 0.0
ret

The three JSET commands define three joint planes through the model. The joints are located by
their dip direction, dd, dip angle, dip, and a single point on the plane, origin. See Figure 3.5 in
Section 3.2.2 for the definition of the orientations for dip direction and dip angle relative to the
3DEC model axes.
By typing the command
plot set dip 70 dd 200

a plot of the model blocks oriented relative to the model reference axes is shown in the graphics
mode:

3DEC Version 4.1
66

GETTING STARTED

Figure 2.9

2 - 27

Block model with three intersecting joint planes

Shapes of engineered structures must also be cut in the 3DEC block, and these must be created
before model execution begins. The JSET command can also be used to create shapes in a model.
Boundaries of excavations are created as joint planes.
An additional command, TUNNEL, is provided specifically to create tunnel shapes. The TUNNEL
command creates a tunnel whose boundary is formed by planar segments that connect the two end
faces of the tunnel, designated face A and face B. For example, a square-shaped tunnel can be
created in the Example 2.3 model by adding the commands in Example 2.4:
Example 2.4 Tunnel in jointed rock
tunnel

a (-.3,-1.5,-.3) (-.3,-1.5,.3) (.3,-1.5,.3) (.3,-1.5,-.3)
b (-.3, 1.5,-.3) (-.3, 1.5,.3) (.3, 1.5,.3) (.3, 1.5,-.3)
remove range x -0.3,0.3 y -1.5,1.5 z -0.3,0.3
plot excavate joint
ret

&

Four vertices define each tunnel face; the vertices for each face must be entered in the same order,
to form connecting planes between the faces. The REMOVE command is used to delete the blocks
within the tunnel region. The resulting model is shown in Figure 2.10. The excavation blocks and
the joint structure can also be plotted separately with the command (see Figure 2.11)
plot exc

joint

3DEC Version 4.1
67

2 - 28

User’s Guide

Note that only the joints created by the JSET command are plotted in Figure 2.11. The “fictitious”
joints created when the tunnel excavation was made with the TUNNEL command are not shown.
These joints lock the adjoining blocks together so that they behave as one block. Joining blocks via
fictitious joints can also be accomplished with the JOIN command. See Section 3.2.2 for details.

Figure 2.10 Tunnel in jointed rock

3DEC Version 4.1
68

GETTING STARTED

2 - 29

Figure 2.11 Tunnel in jointed rock — excavation and joint structure

2.6.2 Assigning Material Models
2.6.2.1 Block Models
Once all block-cutting is complete, material behavior models must be assigned for all of the blocks
and discontinuities in the model. By default, all blocks are rigid. In most analyses, blocks should be
made deformable. Only for cases in which stress levels are very low, or the intact material possesses
high strength and low deformability, can the rigid block assumption be applied (for example, see
the slope failure tutorial in Section 2.2).
Blocks are made deformable with the command
gen edge v

or
gen quad ndiv i1

i2

i3

The GEN (or GENERATE) command invokes an automatic mesh generator that fills each block with
tetrahedral-shaped finite difference zones. The command GEN edge v will work for blocks of any
arbitrary shape. The value v defines the average edge length of the tetrahedral zones (i.e., the smaller
the value for v, the higher the density of zones in a block). Care should be taken, though, to not
create zones that have a high aspect ratio; a practical limit on aspect ratio is approximately 1:5 for
reasonable solution accuracy.

3DEC Version 4.1
69

2 - 30

User’s Guide

The command GEN quad ndiv i1 i2 i3 should be used if blocks are prescribed a plastic material model.
This type of zoning provides a more accurate solution for plasticity problems (see Section 1.2.2.5
in Theory and Background for a description of this type of zoning). The GEN quad command,
however, may not work for all block shapes; if not, the GEN edge command should be used for the
remaining blocks.
There are five built-in material models for deformable blocks in 3DEC; these are described in
Section 2 in Theory and Background. Three models are sufficient for most analyses the new user
will do. These are assigned by the commands
excavate
; null model
change cons=1; elastic model
change cons=2; Mohr-Coulomb model

The EXCAVATE command simulates the excavation or removal of material that will be replaced at
a later stage in the analysis. Blocks within the region that is excavated can be changed back into
elastic or elastic-plastic material with the FILL command. For example, if the excavation for the
tunnel model of Example 2.4 is to be filled at a later stage, the EXCAVATE command should be used
in place of the REMOVE command. If a block is deleted with the REMOVE or DELETE command, it
cannot be restored at a later stage.
The CHANGE command changes the material model assigned to a deformable block. Blocks changed
to cons=1 are assigned isotropic, elastic material behavior, while blocks changed to cons=2 are
assigned Mohr-Coulomb plasticity behavior. By default, all deformable blocks are assigned cons=1.
The models are described briefly in Table 3.2 in Section 3.7.1.
The blocks changed to cons=1 and cons=2 must have material properties assigned via the PROPERTY
mat command. Note that properties are not assigned to specific blocks, but rather to a material
number. Properties may be assigned to as many as 50 material numbers. The material numbers are
then assigned to blocks with the CHANGE mat command.
For the elastic model, the required properties are:
(1) density;
(2) bulk modulus; and
(3) shear modulus.

3DEC Version 4.1
70

GETTING STARTED

2 - 31

NOTE: Bulk modulus, K, and shear modulus, G, are related to Young’s modulus, E, and Poisson’s
ratio, ν, by:

K =

E
3(1 − 2ν)

(2.1)

G =

E
2(1 + ν)

(2.2)

or:
E =

9KG
3K + G

(2.3)

ν =

3K − 2G
2(3K + G)

(2.4)

For the Mohr-Coulomb plasticity model, the required properties are:
(1) density;
(2) bulk modulus;
(3) shear modulus;
(4) friction angle;
(5) cohesion;
(6) dilation angle; and
(7) tensile strength.
If any of these properties is not assigned, its value is set to zero by default.
For both the elastic and Mohr-Coulomb models, density, bulk modulus and shear modulus must be
assigned positive values in order for 3DEC to execute.

3DEC Version 4.1
71

2 - 32

User’s Guide

2.6.2.2 Joint Models
In addition to block material models, a material model must also be assigned to all discontinuities
(i.e., contacts) in the model. There are two built-in constitutive models for discontinuities (summarized in Table 3.3 in Section 3.7.2). The model sufficient for most analyses is the (elastic-perfectly
plastic) Coulomb slip model, which is assigned to discontinuities with the command
change jcons=1

By default, all discontinuities are assigned jcons=1.
The material models for discontinuities also have material properties assigned with the PROPERTY
jmat command. As with blocks, properties are not assigned directly to the discontinuities, but to
material numbers. The material numbers are then assigned to the discontinuities with the CHANGE
jmat command.
For the Coulomb slip model, the required properties are:
(1) normal stiffness;
(2) shear stiffness;
(3) friction angle;
(4) cohesion;
(5) dilation angle; and
(6) tensile strength.
If any of these properties is not assigned, its value is set to zero by default. Normal and shear
stiffnesses must be assigned positive values in order for 3DEC to execute. Example 2.5 demonstrates
the application of block and joint material models to the tunnel example:
Example 2.5 Assigning material models and properties
gen edge 1.0
prop mat=1 dens 2000 bulk 1.5e9 g .6e9
prop jmat=1 jkn 1e9 jks 1e9 coh 1e9 ten 1e9
ret

The commands in Example 2.5 are entered to assign a mass density of 2000 kg/m3 , bulk and shear
moduli of 1.5 GPa and 0.6 GPa to the deformable blocks, normal and shear stiffnesses of 1.0 GPa/m,
and cohesion and tensile strength of 1.0 GPa to the joints. Note that we assign a high cohesion and
tensile strength to the joints to prevent any slip or separation from occurring when we bring the
model to an initial force-equilibrium state.

3DEC Version 4.1
72

GETTING STARTED

2 - 33

2.6.3 Applying Boundary and Initial Conditions
Boundary and initial conditions must not be applied until after all block-cutting is complete and
the mesh for deformable blocks is generated. Mechanical boundary conditions are generally applied with the BOUNDARY command. This command is used to specify force, stress and velocity
(displacement) boundary conditions. Boundary forces and stresses can be applied to both rigid and
deformable blocks, but boundary velocities can only be applied to deformable blocks. (See the
commands FIX, FREE and APPLY to apply boundary conditions to rigid blocks.) Table 2.3 provides
a summary of the boundary condition commands and their effects. Refer to Section 1.3 in the
Command Reference for a complete listing of keywords to these commands.
Table 2.3 Boundary condition command summary
Command
BOUNDARY

Effect
stress
xload
yload
zload
xvel
yvel
zvel

FIX
FREE
APPLY

total stress applied to rigid or deformable blocks
load applied in x-direction to rigid or deformable blocks
load applied in y-direction to rigid or deformable blocks
load applied in z-direction to rigid or deformable blocks
x-velocity applied to deformable blocks
y-velocity applied to deformable blocks
z-velocity applied to deformable blocks
velocities fixed for rigid or deformable blocks
velocities freed for rigid or deformable blocks

xvel
yvel

x-velocity applied to rigid blocks
y-velocity applied to rigid blocks

zvel

z-velocity applied to rigid blocks

The commands BOUNDARY xload, yload and zload apply x-, y- and z-components of force at
boundary vertices. The command BOUNDARY stress specifies components of the total stress tensor
applied at the boundary. The commands BOUNDARY xvel, yvel and zvel fix the x-, y- and zcomponents of velocity at selected boundary gridpoints.
Note that by using the BOUNDARY command, a condition or constraint is imposed that will not
change (unless specifically changed by the user).
Initial stress conditions can be specified for all zone stresses in deformable blocks, and all normal
and shear stresses along joints between rigid blocks or deformable blocks. The INSITU command
is used to initialize stresses. By using this command, initial values are assigned to stresses; these
can change while the computation proceeds.
The initial stress state can also include the effect of gravity. This is invoked with the command

3DEC Version 4.1
73

2 - 34

gravity

User’s Guide

gx

gy

gz

The first value is the gravitational acceleration component in the x-direction, the second value is
that in the y-direction and the third is that in the z-direction. Gravity can be omitted from a model if
the stress variation due to gravity is small across the model compared to the in-situ stresses. Gravity
is often applied to help identify loose blocks around an opening. This is demonstrated below. If
stresses due to gravity are the same magnitude as the in-situ stresses, then a stress gradient should
be applied with the INSITU command to speed convergence to the initial equilibrium.
Boundary and initial conditions can be applied to the tunnel model, for example, with the commands
listed in Example 2.6:
Example 2.6 Applying boundary and initial conditions
bound stress 0.0,0.0,-1.0e6 0.0,0.0,0.0 range z 0.9,1.1
bound xvel 0.0 range x -1.1,-0.9
bound xvel 0.0 range x 0.9,1.1
bound yvel 0.0 range y -1.1,-0.9
bound yvel 0.0 range y 0.9,1.1
bound zvel 0.0 range z -1.1,-0.9
grav 0,0,-10.0
insitu stress -0.5e6 -0.5e6 -1.0e6 0.0 0.0 0.0
ret

A stress boundary of 1.0 MPa is applied in the vertical direction to the top boundary. Roller boundary
conditions are assigned to the lateral boundaries, and the bottom boundary is fixed from movement
in the z-direction. A gravitational acceleration of 10 m/sec2 acts in the negative z-direction. A
zero-velocity boundary along the bottom boundary is particularly important when gravity is acting:
it prevents the model from moving. Note that stress boundaries affect all degrees of freedom. Thus,
stress boundary conditions should always be applied before velocity boundary conditions at the
same boundary corners; otherwise, the prescribed velocity constraint will be lost. Also, note that
x-, y- and z-coordinate ranges are specified for each of the four BOUNDARY commands. Care
should be taken to ensure that the boundary affected by the BOUNDARY command falls completely
within the range.

3DEC Version 4.1
74

GETTING STARTED

2 - 35

Type
list bound

to check boundary conditions.
The INSITU command initializes all stresses in the z-direction to −1.0 MPa, and to −0.5 MPa in
the x- and y-directions.
2.6.4 Stepping to Initial Equilibrium
The 3DEC model must be at an initial force-equilibrium state before alterations can be performed.
The boundary conditions and initial conditions may be assigned such that the model is exactly at
equilibrium initially. However, often it is necessary to calculate the initial equilibrium state under
the given boundary and initial conditions, particularly for problems with complex geometries or
multiple materials. This is done by using either the STEP or CYCLE command. With the STEP
command, the user specifies a number of calculation steps to perform in order to bring the model to
equilibrium. The model is in equilibrium when the net nodal force vector at each centroid of rigid
blocks, or gridpoint of deformable blocks, is zero (see Section 1.2.2.5 in Theory and Background).
The maximum nodal force vector (called the maximum “out-of-balance” or “unbalanced” force) is
monitored in 3DEC, and printed to the screen when the STEP command is invoked. In this way, the
user can assess when equilibrium has been reached.
For a numerical analysis, the out-of-balance force will never reach exactly zero. It is sufficient,
though, to say that the model is in equilibrium when the maximum unbalanced force is small
compared to the total applied forces in the problem. For example, if the maximum unbalanced
force is initially 1 MN and drops to approximately 100 N, then the model can be considered at
equilibrium, within 0.01% of the initial maximum unbalanced force.
This is an important aspect of numerical problem-solving with 3DEC. The user must decide when
the model has reached equilibrium. There are several features built into 3DEC to assist with this
decision. The history of the maximum unbalanced force may be recorded with the command
hist

unbal

Additionally, the history of selected variables (e.g., velocity or displacement at a gridpoint) may be
recorded. The following commands are examples:
hist
hist

xvel 5,5,5
zdisp 0,0,11

The first history records x-velocity at a gridpoint location closest to (x = 5, y = 5, z = 5), while the
second records z-displacement at a location closest to (x = 0, y = 0, z = 11) in the model. After
running several hundred (or thousand) calculation steps, a history of these records may be plotted
to indicate the equilibrium condition.
By default, 3DEC performs a static analysis by applying a mechanical damping algorithm known
as adaptive global (or auto) damping. This algorithm is described in Section 1.2.3.2 in Theory and

3DEC Version 4.1
75

2 - 36

User’s Guide

Background. The data file in Example 2.7 illustrates the process to reach an initial equilibrium
state:
Example 2.7 Stepping to initial equilibrium
hist unbal
hist zdis 0.3,0,0.3
hist ty 1
pl hist 1
step 500
save tun0.sav
ret

The initial unbalanced force is approximately 0.2 MN. After 500 steps, this force has dropped to
around 5 N. By plotting the two histories, it can be seen that the maximum unbalanced force has
approached zero, while the displacement has approached a constant magnitude of approximately
4.3 × 10−4 m. Type
plot hist 1
plot hist 2

to view these plots. The number following PLOT hist corresponds to the order in which the histories
are entered in the data file. Figures 2.12 and 2.13 show the unbalanced force and displacement
history plots, respectively.

Figure 2.12 Maximum unbalanced force history

3DEC Version 4.1
76

GETTING STARTED

2 - 37

Figure 2.13 z-displacement history at (.3, 0, .3)
In an analysis, it is very important that the model be at equilibrium before alterations are made.
Several histories should be recorded throughout a model to ensure that a large force imbalance does
not exist. If more steps than are needed to reach equilibrium are taken, the analysis is not adversely
affected. However, the analysis will be affected if an insufficient number of steps is taken.
A 3DEC calculation can be interrupted at any time during stepping by pressing . Often,
it is convenient to use the STEP command with a high step number, and periodically interrupt the
stepping, check the histories and resume stepping until the equilibrium condition is reached.
2.6.5 Performing Alterations
3DEC allows model conditions to be changed at any point in the solution process. These changes
may be:
• excavation of material;
• addition or deletion of boundary loads or stresses;
• fix or free velocities of boundary corners; or
• change of material model or properties for blocks or discontinuities.
Excavation is performed with the DELETE, REMOVE or EXCAVATE command. Loads and stresses
are applied with the BOUNDARY xload, yload, zload or stress command. Boundary vertices are fixed

3DEC Version 4.1
77

2 - 38

User’s Guide

with the BOUNDARY xvel, yvel or zvel command. The constraint at boundaries is removed with
BOUNDARY xfree, yfree or zfree. Material models for deformable blocks and discontinuities are
changed with the CHANGE command, while properties are changed with the PROPERTY command.
It should be evident that several commands can be repeated to perform various model alterations.
For example, continue Example 2.7 from the initial equilibrium stage using the commands in
Example 2.8:
Example 2.8 Reduce the strength of the joints
rest tun0.sav
; reduce friction along joints
prop jmat 1 fric 6.0 coh 0.0 ten 0.0
;
reset time hist disp
hist unbal
hist zdisp 0.3,-0.1,.3
hist ty 2
hide range x -0.4,0.5 y -1,-.5 z 0.3,0.8
plot block disp line color cyan
cycle 5000
save tun1.sav
ret

The three joints and the excavation in this model form an isolated wedge in the roof of the excavation.
The wedge is potentially unstable, and can slide along the joint plane dipping at 65◦ . In Example 2.8
we reduce the strength of the joint structure in the model by setting the cohesion and tensile strength
to zero, and the friction angle to 6◦ .*
The failure after an additional 5000 cycles is shown by the block plot in Figure 2.14. The wedge
in the roof of the excavation has become detached from the surrounding blocks and is falling into
the excavation. Blocks in front of the unstable wedge are hidden for better viewing of the wedge.
(Hidden blocks are still present for mechanical calculations.) The instability is also indicated by
the z-displacement history plot in Figure 2.15. The history at location (0.3, −0.1, 0.3) corresponds
to one vertex on the wedge. Note that we reset the time, history records and displacement in the
model in Example 2.8, so that only the change in displacement due to the drop in joint strength is
monitored.

* Alternatively, we could start the analysis with the tunnel blocks still in place and the joint strength
set to a low value, and solve for an initial equilibrium state. Then, we could excavate the tunnel
and monitor the response.

3DEC Version 4.1
78

GETTING STARTED

2 - 39

Figure 2.14 Sliding wedge in tunnel

Figure 2.15 z-displacement history at (.3, −0.1, .3)

3DEC Version 4.1
79

2 - 40

User’s Guide

2.6.6 Saving/Restoring Problem State
Two other commands, SAVE and RESTORE, are helpful when performing analyses in stages. At the
end of one stage (e.g., initial equilibrium), the model state can be saved by typing
save

file.sav

where file.sav is a user-specified filename. The extension “.SAV” identifies this file as a saved file
(see Section 2.9). This file can be restored at a later time by typing
rest

file.sav

and the model state at the point at which the model was saved will be restored. It is not necessary
to build the model from the beginning every time a change is made. Merely save the model before
the change, and restore it whenever a new change is to be analyzed. For example, in the previous
example, the state should be saved after the initial equilibrium stage. Then, different methods can
be evaluated to stabilize the falling block.
For example, we inserted
save tun0.sav

after the STEP 500 command at the end of the data file for Example 2.7. Now we try stabilizing the
block with cable reinforcement, using the commands in Example 2.9. A single cable is installed
through the wedge and into the surrounding rock. See Section 4 in Theory and Background and
Section 1 in the Command Reference for descriptions of the STRUCT cable command and cable
parameters assigned with the PROPERTY command.

3DEC Version 4.1
80

GETTING STARTED

2 - 41

Example 2.9 Stabilize roof block with a cable bolt
rest tun0.sav
; reduce friction along joints
prop jmat 1 fric 6.0 coh 0.0 ten 0.0
;
; add cable support
struct cable 0.3 0.0 0.3
0.7 0.0 0.7
prop 1 seg 4
struct prop 1 area 5e-4 e 1e9 yield 1e6 kbond 15e8 sbond 1e9
;
reset time hist disp
hist unbal
hist zdisp 0.3,-0.1,0.3
hist ty 2
hide range x -0.4,0.5 y -1,-.5 z 0.3,0.8
plot block disp line color cyan
plot add hist 2 xaxis label ’Step’ yaxis label ’Z-Displacement’
cycle 5000
save tun2.sav
ret

After the run is completed, the saved file, “TUN2.SAV,” can be restored and evaluated to study
the effect of cable reinforcement. A history of z-displacement shows that the wedge has stopped
moving after 4.3 × 10−3 m of vertical displacement.
The file “TUN0.SAV” can be restored again, and different cable locations, orientations and properties investigated. Several files can be linked together, with RESTORE tun0.sav beginning each
section, and a different filename saved after execution. Each save file can then be evaluated separately after the entire run is completed.

3DEC Version 4.1
81

2 - 42

User’s Guide

Figure 2.16 z-displacement history at (.3, −0.1, .3) — wedge is stable

2.6.7 Summary of Commands for Simple Analyses
The major command words described in this section are summarized in Table 2.4. These are
all that are needed to begin performing simple analyses with 3DEC. Start by running simple
tests with these commands (e.g., direct shear tests on single joints, or simple excavation stability
analyses). It may be helpful to review the detailed description of these commands in Section 1.3 in
the Command Reference. Then try adding more complexity to the model. Before running very
detailed simulations though, we recommend that you read Section 3, which provides guidance on
problem solving in general.

3DEC Version 4.1
82

GETTING STARTED

2 - 43

Table 2.4

Basic commands for simple analyses

Function

Command

Block Model Creation
Block Cutting

POLY
JSET
TUNNEL

Material Model & Properties for
Blocks and Joints

GEN
CHANGE
PROPERTY

Boundary/Initial Conditions

BOUNDARY
INSITU

Initial Equilibrium (with gravity)

GRAVITY
STEP

Perform Alterations

DELETE
CHANGE
PROPERTY
BOUNDARY
STRUCTURE cable

Monitor Model Response

HISTORY
PLOT

Save/Restore Problem State

SAVE
RESTORE

3DEC Version 4.1
83

2 - 44

User’s Guide

2.7 Sign Conventions
The following sign conventions are used in 3DEC, and must be kept in mind when entering input
or evaluating results.
BLOCK MOTION — Positive motion is in the positive coordinate axes directions.
DIRECT STRESS — Positive stresses indicate tension; negative stresses indicate compression.
SHEAR STRESS — With reference to Figure 2.17, a positive shear stress points in the positive
direction of the coordinate axis of the second subscript if it acts on a surface with an outward
normal in the positive direction. Conversely, if the outward normal of the surface is in the negative
direction, then the positive shear stress points in the negative direction of the coordinate axis of
the second subscript. The shear stresses shown in Figure 2.17 are all positive. The stress tensor is
symmetric (i.e., complementary shear stresses are equal).
z

σzz
σzx

σzy

σxy
σyy

σyx

σxz

σxz

σxx

σyz
σyx

σyy

σxy

σyz
σxx

y

σzx
σzy

σzz

x

Figure 2.17 Sign convention for positive stress components

DIRECT STRAIN — Positive strain indicates extension; negative strain indicates compression.
SHEAR STRAIN — Shear strain follows the convention of shear stress (see above).

3DEC Version 4.1
84

GETTING STARTED

2 - 45

PORE PRESSURE — Fluid pore pressure is positive in compression.
DIP, DIP DIRECTION — Dip and dip direction assume that the x-direction corresponds to “East,”
the y-direction corresponds to “North,” and the z-direction corresponds to “Up.” The dip angle is
measured in the negative z-direction from the global xy-plane. The dip direction angle is measured
in the global xy-plane, clockwise from the positive y-axis. The x-, y- and z-components of vector
quantities (such as forces, displacements and velocities) are positive when pointing in the directions
of the positive x-, y- and z-coordinate space.

3DEC Version 4.1
85

2 - 46

User’s Guide

2.8 Systems of Units
3DEC accepts any consistent set of engineering units. Examples of consistent sets of units for basic
parameters are shown in Table 2.5. The user should apply great care when converting from one
system of units to another. An excellent reference on the subject of units and conversion between
the Imperial and SI systems can be found in the Journal of Petroleum Technology (December 1977).
No conversions are performed in 3DEC except for friction and dilation angles, which are entered
in degrees.
Table 2.5

Systems of units — mechanical parameters
SI

Length
Density
Force
Stress
Gravity

where:

m
kg / m3
N
Pa
m / sec2

1 bar
1 atm
1 slug
1 snail
1 gravity

=
=
=
=
=

m
103 kg / m3
kN
kPa
m / sec2

m
106 kg / m3
MN
MPa
m / sec2

Imperial
cm
106 g / cm3
Mdynes
bar
cm / s2

ft
slugs / ft3
lbf
lbf / ft2
ft / sec2

in
snails / in3
lbf
psi
in / sec2

106 dynes / cm2 = 105 N / m2 = 105 Pa;
1.013 bars = 14.7 psi = 2116 lbf / ft2 = 1.01325 × 105 Pa;
1 lbf − s2 / ft = 14.59 kg;
1 lbf − s2 / in; and
9.81 m / s2 = 981 cm / s2 = 32.17 ft / s2 .

When selecting a system of units, care should be taken to avoid calculations that approach the precision limits of the computer hardware. For Pentium-based computers, the range is approximately
10−35 to 1035 in single precision. If numbers exceed these limits, it is likely that the program will
crash or, at least, produce artifacts in the model that may be difficult to identify or detect.

3DEC Version 4.1
86

GETTING STARTED

2 - 47

2.9 Files
There are several types of files that are either used or created by 3DEC. The files are distinguished
by their extensions and are described below.
INITIALIZATION FILE
“3DEC.INI” — This is a formatted ASCII file, created by the user, that 3DEC will automatically
access upon start-up or when a NEW command is issued. 3DEC searches for the file “3DEC.INI”
in the directory in which the code is executed, and, if not found, in the “\ITASCA\System” folder.
The file may contain any valid 3DEC command(s) (see Section 1 in the Command Reference).
Although this file does not need to exist (i.e., no errors will result if it is absent), it is normally
used to change default options in 3DEC to those preferred by the individual user each time a new
analysis is run (see Section 2.1.7).
DATA FILES
The user has a choice of running 3DEC interactively (i.e., entering 3DEC commands while in the
3DEC environment) or via a data file (also called a “batch file”). The data file is a formatted ASCII
text file created by the user which contains the set of 3DEC commands that represents the problem
being analyzed. In general, creating data files is the most efficient way to use 3DEC. To use data
files with 3DEC, see the CALL command in Section 1 in the Command Reference. Data files can
have any file name and any extension. It is recommended that a common extension (e.g., “.DAT”
for 3DEC input commands, and “.FIS” for FISH function statements) be used to distinguish these
files from other types of files. Important note: The end of each line in a text file must be terminated
by a carriage return. If it is not, the line will not be processed. It is a good idea to put in a “ret”
line, or comment, as the last line of a data file in order to avoid this.
SAVE FILES
“3DEC.SAV” — This file is created by 3DEC at the user’s request when issuing the command SAVE.
The default file name is “3DEC.SAV,” which will appear in the default directory when exiting 3DEC.
The user may specify a different filename by issuing the command SAVE filename, where filename is
a user-specified filename. “3DEC.SAV” is a binary file containing the values of all state variables
and user-defined conditions. The primary reason for creating save files is to allow one to investigate
the effect of parameter variations without having to rerun a problem completely. A save file can be
restored, and the analysis continued at a subsequent time (see the RESTORE command in Section 1
in the Command Reference). Normally it is good practice to create several save files during a
3DEC run.
LOG FILES
“3DEC.LOG” — This file is created by 3DEC at the user’s request when issuing the command
SET log on. It is a formatted ASCII file. The default name of the file is “3DEC.LOG,” which will
appear in the default directory after exiting 3DEC. The user may specify a different file name by
issuing the command SET log filename, where filename is a user-supplied file name. The command

3DEC Version 4.1
87

2 - 48

User’s Guide

may be issued interactively or be part of a data file. Subsequent to the SET log on command, all text
appearing on the screen will be copied to the log file. The log file is useful in providing a record of
the 3DEC work session; it also provides a document for quality-assurance purposes.
HISTORY FILES
“3DEC.HIS” — This file is created by 3DEC at the user’s request when issuing the command
HISTORY write n, where n is a history number (see the HISTORY command in Section 1 in the
Command Reference). It is a formatted ASCII file. The default name of the file is “3DEC.HIS,”
which will appear in the default directory after exiting 3DEC. The user may specify a different file
name by issuing the command SET hisfile filename. The user-supplied filename takes the place of
“3DEC.HIS.” The command may be issued interactively or be part of a data file. A record of the
history values is written to the file, which can be examined using any text editor that can access
formatted ASCII files. Alternatively, the file may be processed by a commercial graph-plotting or
spreadsheet package.
TABLE FILES
“3DEC.TAB” — This file is created by 3DEC at the user’s request when issuing the command
TABLE n write dx, where n is the table number and dx specifies the abscissa spacing for the data
points (see the TABLE command in Section 1 in the Command Reference). It is a formatted ASCII
file. The default name of the file is “3DEC.TAB,” which will appear in the default directory after
exiting 3DEC. The user may specify a different file name by adding the filename to the end of the
TABLE n write dx command. The file will consist of a single column of y-data at an even spacing
of dx. If dx = 0, the data will be the actual x,y pairs in table n.
PLOT FILES
Plot files are created at the user’s request by issuing the command PLOT bitmap filename in the
command mode, after first creating the plot. A PNG-format file will be created with the userspecified filename when the command is issued.
MOVIE FILES
“3DEC.DCX” — This file is created by 3DEC at the user’s request when issuing the command
MOVIE on. Its purpose is to capture graphics images for playback on the computer monitor as a
movie at a later time. Note that this feature will only work with VGA graphics. The default file
name is “3DEC.DCX,” which will appear in the default directory when exiting 3DEC. The user
may specify a different file name by issuing the command MOVIE file filename, where filename takes
the place of “3DEC.DCX.” A DCX file format is used for the movie file. See the MOVIE command
in Section 1 in the Command Reference. Note that the DCX format is limited to 1024 frames.

3DEC Version 4.1
88

GETTING STARTED

2 - 49

2.10 References
Journal of Petroleum Technology. “The SI Metric System of Units and SPE’s Tentative Metric
Standard,” 1575-1616 (December, 1977).

3DEC Version 4.1
89

2 - 50

3DEC Version 4.1
90

User’s Guide

PROBLEM SOLVING WITH 3DEC

3-1

3 PROBLEM SOLVING WITH 3DEC
This section provides guidance in the use of 3DEC in problem solving for rock mechanics engineering.* In Section 3.1, an outline of the steps recommended for performing a geomechanics analysis
is given, followed in Sections 3.2 through 3.10 by an examination of specific aspects that must be
considered in any model creation and solution. These include:
• model generation (Section 3.2);
• choice of rigid or deformable block analysis (Section 3.3);
• boundary and initial conditions (Sections 3.4 and 3.5);
• loading and sequential modeling (Section 3.6);
• choice of block and joint constitutive models and material properties
(Sections 3.7 and 3.8);
• ways to improve modeling efficiency (Section 3.9); and
• interpretation of results (Section 3.10).
Finally, the philosophy of modeling in the field of geomechanics is examined in Section 3.11; the
novice modeler in this field may wish to consult this section first. The methodology of modeling in
geomechanics can be significantly different from that in other engineering fields (such as structural
engineering). It is important to keep this in mind when performing any geomechanics analysis.

* Problem solving for coupled mechanical-thermal analysis is described in Section 1 in Optional
Features, and problem solving for dynamic analysis is discussed in Section 2 in Optional Features.

3DEC Version 4.1
91

3-2

User’s Guide

3.1 General Approach
The modeling of geo-engineering processes involves special considerations and a design philosophy
different from that followed for design with fabricated materials. Analyses and designs for structures
and excavations in or on rocks and soils must be achieved with relatively little site-specific data,
and an awareness that deformability and strength properties may vary considerably. It is impossible
to obtain complete field data at a rock or soil site. For example, information on stresses, properties
and discontinuities can only be partially known, at best.
Since the input data necessary for design predictions is limited, a numerical model in geomechanics
should be used primarily to understand the dominant mechanisms affecting the behavior of the
system. Once the behavior of the system is understood, it is then appropriate to develop simple
calculations for a design process.
This approach is oriented toward geotechnical engineering, in which there is invariably a lack of
good data; but in other applications, it may be possible to use 3DEC directly in design if sufficient
data, as well as an understanding of material behavior, is available. The results produced in a 3DEC
analysis will be accurate when the program is supplied with appropriate data. Modelers should
recognize that there is a continuous spectrum of situations, as illustrated in Figure 3.1:

Typical
situation

Data

Approach

Figure 3.1

Simple geology;
$$$ spent on site
investigation

Complicated geology;
inaccessible;
no testing budget

COMPLETE

NONE

Investigation of
mechanisms

Bracket field behavior
by parameter studies

Predictive
(direct use in design)

Spectrum of modeling situations

3DEC may be used either in a fully predictive mode (right-hand side of Figure 3.1) or as a “numerical
laboratory” to test ideas (left-hand side). It is the field situation and budget, rather than the program,
that determine the types of use. If enough data of a high quality is available, 3DEC can give good
predictions.
Since most 3DEC applications will be for situations in which little data is available, this section
discusses the recommended approach for treating a numerical model as if it were a laboratory test.
The model should never be considered as a “black box” that accepts data input at one end and
produces a prediction of behavior at the other. The numerical “sample” must be prepared carefully,
and several samples tested, to gain an understanding of the problem. Table 3.1 lists the steps
recommended to perform a successful numerical experiment; each step is discussed separately.

3DEC Version 4.1
92

PROBLEM SOLVING WITH 3DEC

Table 3.1

3-3

Recommended steps for numerical analysis in geomechanics

Step 1

Define the objectives for the model analysis

Step 2

Create a conceptual picture of the physical system

Step 3

Construct and run simple idealized models

Step 4

Assemble problem-specific data

Step 5

Prepare a series of detailed model runs

Step 6

Perform the model calculations

Step 7

Present results for interpretation

3.1.1 Step 1: Define the Objectives for the Model Analysis
The level of detail to be included in a model often depends on the purpose of the analysis. For
example, if the objective is to decide between two conflicting mechanisms that are proposed to
explain the behavior of a system, then a crude model may be constructed, provided that it allows
the mechanisms to occur. It is tempting to include complexity in a model just because it exists in
reality. However, complicating features should be omitted if they are likely to have little influence
on the response of the model, or if they are irrelevant to the model’s purpose. Start with a global
view and add refinement as (and if) necessary.
3.1.2 Step 2: Create a Conceptual Picture of the Physical System
It is important to have a conceptual picture of the problem to provide an initial estimate of the expected behavior under the imposed conditions. Several questions should be asked when preparing
this picture. For example: Is it anticipated that the system could become unstable? Is the predominant mechanical response linear or nonlinear? Are there well-defined discontinuities that may
affect the behavior, or does the material behave essentially as a continuum? Is there an influence
from groundwater interaction? Is the system bounded by physical structures, or do its boundaries
extend to infinity? Is there any geometric symmetry in the physical structure of the system?
These considerations will dictate the gross characteristics of the numerical model, such as the
design of the model geometry, the types of material models, the boundary conditions, and the initial
equilibrium state for the analysis. They will determine if a three-dimensional model is required,
or whether a two-dimensional model can be used to take advantage of geometric conditions in the
physical system.

3DEC Version 4.1
93

3-4

User’s Guide

3.1.3 Step 3: Construct and Run Simple Idealized Models
When idealizing a physical system for numerical analysis, it is more efficient to construct and run
simple test models first, before building the detailed model. Simple models should be created at
the earliest possible stage in a project to generate data and add to understanding. The results can
provide further insight into the conceptual picture of the system; Step 2 may need to be repeated
after simple models are run.
Simple models can reveal shortcomings that can be remedied before any significant effort is invested
in the analysis. For example, do the selected material models sufficiently represent the expected
behavior? Are the boundary conditions influencing the model response? The results from the
simple models can also help guide the plan for data collection by identifying which parameters
have the most influence on the analysis.
3.1.4 Step 4: Assemble Problem-Specific Data
The types of data required for a model analysis include:
• details of the geometry (e.g., profile of underground openings, surface topography, dam
profile, rock/soil structure);
• locations of geologic structure (e.g., faults, bedding planes, joint sets);
• material behavior (e.g., elastic/plastic properties, post-failure behavior);
• initial conditions (e.g., in-situ state of stress, pore pressures, saturation); and
• external loading (e.g., explosive loading, pressurized cavern).
Since, typically, there are large uncertainties associated with specific conditions (in particular, state
of stress, deformability and strength properties), a reasonable range of parameters must be selected
for the investigation. The results from the simple model runs (in Step 3) can often prove helpful in
determining this range, and in providing insight for the design of laboratory and field experiments
to collect the needed data.
3.1.5 Step 5: Prepare a Series of Detailed Model Runs
Most often, the numerical analysis will involve a series of computer simulations that include the
different mechanisms under investigation, and span the range of parameters derived from the assembled database. When preparing a set of model runs for calculation, several aspects, such as the
following, should be considered:
1. How much time is required to perform each model calculation? It can be difficult to obtain
sufficient information to arrive at a useful conclusion if model runtimes are excessive.
Consideration should be given to performing parameter variations on multiple computers
to shorten the total computation time.

3DEC Version 4.1
94

PROBLEM SOLVING WITH 3DEC

3-5

2. The state of the model should be saved at several intermediate stages so that the entire run
does not have to be repeated for each parameter variation. For example, if the analysis
involves several loading/unloading stages, the user should be able to return to any stage,
change a parameter and continue the analysis from that stage. Consideration should be
given to the amount of disk space required for save files.
3. Are there a sufficient number of monitoring locations in the model to provide for a clear
interpretation of model results, and for comparison with physical data? It is helpful
to locate several points in the model at which a record of the change of a parameter
(such as displacement, velocity or stress) can be monitored during the calculation. Also,
the maximum unbalanced force in the model should always be monitored to check the
equilibrium or failure state at each stage of an analysis.
3.1.6 Step 6: Perform the Model Calculations
It is best to first make one or two model runs, split into separate sections, before launching a series of
complete runs. The runs should be checked at each stage to ensure that the response is as expected.
Once there is assurance that the model is performing correctly, several data files can be linked
together to run a complete calculation sequence. At any time during a sequence of runs, it should
be possible to interrupt the calculation, view the results and then continue or modify the model as
appropriate.
3.1.7 Step 7: Present Results for Interpretation
The final stage of problem solving is the presentation of the results for a clear interpretation of
the analysis. This is best accomplished by displaying the results graphically, either directly on
the computer screen or as output to a hardcopy plotting device. The graphical output should be
presented in a format that can be directly compared to field measurements and observations. Plots
should clearly identify regions of interest from the analysis, such as locations of calculated stress
concentrations or areas of stable movement versus unstable movement in the model. The numeric
values of any variable in the model should also be readily available for more detailed interpretation
by the modeler.
We recommend that these seven steps be followed to solve geo-engineering problems efficiently.
The following sections describe the application of 3DEC to meet the specific aspects of each of the
steps in this modeling approach.

3DEC Version 4.1
95

3-6

User’s Guide

3.2 Model Generation
One of the main tasks when performing a 3DEC analysis is building a numerical representation
of the real-world situation. All 3DEC models will have an outer boundary to which boundary
conditions will be applied. In addition, most models will have features such as joints, faults,
cracks, excavations or material property interfaces. Quite often, the features to be modeled are not
continuous through the entire model. The complex shapes which result from the intersections of
noncontinuous planes in space are difficult to create and visualize. The purpose of this section is
to give some guidance for using a systematic approach to model building.
The first rule is keep the model simple. Usually, a numerical model is being developed because the
real-life situation is too complex to understand. There is a tendency to attempt to include every
possible feature in a numerical model. This results in a 3DEC model that is also too complex
to understand. The goal of the modeler should be to understand the mechanisms, properties and
parameters that determine the model’s behavior. The time required to calculate a solution also
increases with increasing complexity. Therefore, it is to the modeler’s advantage to start with
a model that only includes the minimum of features. The complexity of the model can then be
increased by adding features one at a time and noting the effect. By using this approach, the
modeler has the best chance of gaining understanding of the parameters that are critical to the
real-life situation.
3DEC is different from conventional numerical programs in the way the model geometry is created.
A 3DEC model can be created in two ways: (1) by splitting a polyhedron into separate polyhedra;
and (2) by creating separate polyhedra and joining them together. For most geomechanics analyses,
a single block is created first, with a size that encompasses the physical region being analyzed.
Then, this block is cut into smaller blocks whose boundaries represent both geologic features and
engineered structures in the model. This cutting process is termed collectively as joint generation;
however, “joints” represent both physically real geologic structures and boundaries of man-made
structures or materials that will be removed or changed during the subsequent stages of the 3DEC
analysis. In this latter case, the joints are fictitious entities and their presence should not influence
model results. The representation of fictitious joints is discussed in Section 3.2.3.
3.2.1 Fitting the 3DEC Model to a Problem Region
The 3DEC model geometry must represent the physical problem to an extent sufficient to capture
the dominant mechanisms related to the geologic structure in the region of interest. The following
aspects must be considered:
1. In how much detail should the geologic structure (e.g., faults, joints, bedding
planes, etc.) be represented?
2. How will the location of the model boundaries influence model results?
3. If deformable blocks are used, what density of zoning is required for accurate
solution in the region of interest?
All three aspects determine the size of the 3DEC model that is practical for analysis.

3DEC Version 4.1
96

PROBLEM SOLVING WITH 3DEC

3-7

As mentioned above, there are two different starting points in building 3DEC models. The first
method is to describe a simple starting shape and slice it up to create the desired geometrical
features. The second involves defining complex polyhedral shapes and putting them together to
form the continuous mass. Both of these approaches make use of the POLY command.
There are five forms of the POLY command available in 3DEC:
POLY face
POLY brick
POLY cube
POLY prism
POLY tunnel
By using the POLY face command, polyhedra of virtually any shape can be defined. Each face is
defined by a list of vertex coordinates. The list must be entered in counterclockwise order, looking
at the face from outside the polyhedra. All points on a face must be coplanar, and the resulting
polyhedra created by the face commands must be convex. Continuation lines are allowed, but the
coordinates for each vertex may not be split between lines. All faces required to close the polyhedra
must be specified. A simple example of using the POLY face command to generate a cube (1 unit
on each side) is:
Example 3.1 A cube generated with the POLY face command
new
poly &
face 0,0,0
face 0,0,0
face 0,0,0
face 1,1,1
face 1,1,1
face 1,1,1
pl bl
pl reset
pl set dip
ret

1,0,0
0,0,1
0,1,0
1,1,0
1,0,1
0,1,1

1,1,0
1,0,1
0,1,1
1,0,0
0,0,1
0,1,0

0,1,0
1,0,0
0,0,1
1,0,1
0,1,1
1,1,0

&
&
&
&
&

60 dd 210

The model created with the example is shown in Figure 3.2. In this case, a simple regular rightangled solid is produced. The command can also be used to create complex shapes. Because of the
large amount of input required, the POLY face command is often best used in conjunction with the
external pre-processor program PGEN — see Section 5 in Theory and Background for examples.

3DEC Version 4.1
97

3-8

User’s Guide

Figure 3.2

Cubic model created with the POLY face command

The POLY brick command provides a simpler alternative to the POLY face command when the
problem region is a regular six-sided “brick-shaped” region. The parameters for the brick keyword
are the x-, y-, and z-limits of the solid (i.e., the region extends from coordinates xl to xu in the
x-direction, from coordinates yl to yu in the y-direction, and from coordinates zl to zu in the
z-direction). For example, to create the same model generated in Figure 3.2, the command is:
Example 3.2 A cube generated with the POLY brick command
new
poly brick 0,1 0,1 0,1
pl bl
pl reset
pl set dip 60 dd 210
ret

POLY cube is a tool for generating irregularly shaped boundaries. These boundaries may represent
geologic contacts or the borders of excavations. This is intended as an alternative to the PGEN
program. The advantage of POLY cube over the PGEN program is that the resulting shapes are
easier to zone and can be zoned as mixed discretization zones for plasticity. The disadvantage is
that the shapes can be complex in only two dimensions. Using PGEN, they can be zoned in three
dimensions. See Section 3.2.3.2 for an example of the complex use of this tool.

3DEC Version 4.1
98

PROBLEM SOLVING WITH 3DEC

3-9

The POLY prism command is an extension of the POLY brick command to create prism-shaped
polyhedra. The two parallel faces of the prism are defined by an arbitrary number of vertices. The
opposing vertices on each face are then automatically connected to form the prism. The first face
(face a) is defined by vertices entered in either a clockwise or counterclockwise order. The opposite
face (face b) must have its vertices entered in the same order as the corresponding vertices for face
a. Faces a and b must be planar and convex. The prism shown in Figure 3.3 is created by the
commands listed in Example 3.3:
Example 3.3 An octahedral-shaped prism generated with the POLY prism command
new
poly prism &
a (0.0,0.0,0.0 ) (-0.5,0.0,0.87)
(1.0,0.0,2.74) ( 1.5,0.0,1.87)
b (0.0,4.0,0.0 ) (-0.5,4.0,0.87)
(1.0,4.0,2.74) ( 1.5,4.0,1.87)
pl bl
pl reset
pl set dip 60 dd 200
ret

Figure 3.3

(-0.5,0.0,1.87)
( 1.5,0.0,0.87)
(-0.5,4.0,1.87)
( 1.5,4.0,0.87)

(0.0,0.0,2.74) &
(1.0,0.0, 0.0) &
(0.0,4.0,2.74) &
(1.0,4.0, 0.0)

An octahedral-shaped prism generated with the POLY prism command

3DEC Version 4.1
99

3 - 10

User’s Guide

The POLY tunnel command is specifically designed to generate a circular-shaped tunnel model.
This command works by constructing the model with individual blocks. This is in contrast to the
TUNNEL command (discussed in Section 3.2.3), which cuts an arbitrarily shaped tunnel out of an
existing block. The blocks created by the POLY tunnel command are all six-sided with low aspect
ratios, and are intended for use with the GEN quad command. (This command is recommended
for deformable-block plasticity analysis — see Section 3.3.) The user needs only to specify the
orientation, dimensions and number of blocks to be used for the tunnel. Additional jointing can be
added with the JSET command, if desired. For example, to create a tunnel model with the following
dimensions:
radius

2.0 m

length

20.0 m

outside boundary

3.0 r

dip

horizontal

heading

south

blocks in each octant

1

annular blocks

2

blocks along the axis

3

use the POLY tunnel command as given in Example 3.4.
Example 3.4 A tunnel model generated with the POLY tunnel command
new
poly tunnel rad=2 leng=-10,10 ratr=3.0 dip=0 dd=0 nr=2 nt=1 nx=3
pl bl
pl reset
delete range x -2,2 y -10,10 z -2,2
ret

The model with the tunnel deleted is shown in Figure 3.4.

3DEC Version 4.1
100

PROBLEM SOLVING WITH 3DEC

Figure 3.4

3 - 11

Tunnel model created with the POLY tunnel command

3.2.2 Joint Generation
The JSET command is used to make additional cuts in the solids created with the POLY command,
to define joints, faults, and holes or excavations. The JSET command can be used to make single
cuts or multiple parallel cuts. Statistical parameters may be used to vary orientation, spacing and
persistence to match logged jointing data.
The JSET command is first demonstrated in this section for making single cuts. Some planning
should be done to optimize the sequence in which joints are created. Joints which define the
geometry of excavations are usually cut first (see Section 3.2.3), followed by the minor joints or
joint sets. Through-going faults are usually defined last.
The primary keywords for the JSET command are dip, dd (dip direction) and origin. Unless other
keywords are used, the JSET command will create a single plane cutting through the model in the
orientation specified. The origin point may be any point on the plane. Figure 3.5 shows how the
orientations for dip and dip direction relate to the coordinate axes in 3DEC. The dip range is from
0 to 90◦ ; the dip direction range is from 0 to 360◦ .

3DEC Version 4.1
101

3 - 12

User’s Guide

Up (z)
North (y)
= Dip direction

S tr

ik e

lin e

= Dip

East (x)
Joint plane
Figure 3.5

Terms describing the attitude of an inclined plane:
dip angle, α, is positive measured downward from the horizontal
(xy) plane; dip direction, β, is positive measured clockwise from
north (y)

Control of the continuity of cuts made using the JSET command is accomplished with the HIDE and
SEEK commands. The JSET command will only cut blocks that are currently visible.

3DEC Version 4.1
102

PROBLEM SOLVING WITH 3DEC

3 - 13

Example 3.5 illustrates the creation of a noncontinuous joint:
Example 3.5 Creation of a noncontinuous vertical joint
new
poly brick 0,1 0,1 0,1
; create a block
pl block
pl reset
jset dip 0 dd 0 origin 0,0,.5
; make a horizontal cut
hide dip 0 dd 0 origin 0,0,.5 below ; hide the bottom block
jset dip 90 dd 90 origin .5,0,0
; vertical cut through top block only
seek
; make all blocks visible
ret

Figure 3.6 shows the full model and the joint structure plot for this example. Note that the vertical
joint does not penetrate the bottom block. 3DEC automatically assigns a joint ID number = 2 to
the horizontal joint and a joint ID number = 3 to the vertical joint. If desired, the joint ID number
can be controlled with the JSET command. For example,
jset dip 0 dd 0 or 0,.5,0

id = 1000

will create a horizontal joint with an ID number of 1000.
The ID numbers for joint faces and contacts are given sequentially as they are created. Therefore,
if two faults that intersect are defined, the edge to edge contacts at the line of intersection will have
the joint IDs of the second fault defined. This order becomes important if different properties are
to be assigned to the different faults. Property numbers of the face-to-face contacts that comprise
most of the area of joints can be assigned using the CHANGE command, in which the particular
joint to be changed is identified using either its joint ID number or orientation. The difficulty
comes in assigning property numbers to the edge-to-edge contacts that are created at joint and fault
intersections. It is easy to assign property numbers to edge-to-edge contacts by use of the joint ID
number; it is difficult to assign property numbers to edge-to-edge contacts by orientation, because
they have a different orientation than either of the two intersecting planes that created them. There
is a PLOT option that allows plotting of joint material properties (the joint material item in the
options menu). This plot is useful for checking that the edge-to-edge contacts are assigned the
correct properties.

3DEC Version 4.1
103

3 - 14

User’s Guide

(a) full-solid view

(b) joint-structure view
Figure 3.6

3DEC Version 4.1
104

Model created with the JSET and HIDE commands

PROBLEM SOLVING WITH 3DEC

3 - 15

Concave blocks can be made by using the JOIN command. The blocks that have been joined are
still convex, but the join logic locks the interface between them. For example, add the following
commands at the end of Example 3.5:
hide (0.5,1.0) (0,1) (0.5,1.0)
join on

Figure 3.7 shows the concave block that is created. Note that only visible blocks can be joined.

Figure 3.7

Concave block created with the JOIN command

Joined blocks are plotted in the same color on the graphics screen. Also, contacts between joined
blocks are identified as master-slave (m-s) contacts. Type LIST contact to check the contact type.
Note that “slaved” blocks will be automatically joined if they are connected to the same “master”
block. For example, if block A and block B are joined, and block A and block C are joined, then
block B will be joined automatically to block C.
The JSET command can also be used to generate a set of joints automatically, based on physically
measured parameters (i.e., joint dip, dip direction, spacing and persistence). By hiding selected
blocks, a set of noncontinuous joints can be generated. In Example 3.6, a jointed rock slope
containing both shallow and deeply dipping joint sets is created. Two noncontinuous fractures are
also created to define a rock wedge in the slope (see Figure 3.8).

3DEC Version 4.1
105

3 - 16

User’s Guide

Example 3.6 Rock slope containing continuous and noncontinuous joints
new
poly brick 0 80 -30 80 0 50
pl block
pl reset
plot set dip 70 dd 210
; shallow-dipping fracture planes (continuous)
jset dip 2.45 dd 235 org 30 0 12.5
jset dip 2.45 dd 315 org 35 0 30
; high angle foliation planes (continuous)
jset dip 76 dd 270 spac 16 num 3 org 30,0,12.5
; intersecting discontinuities (non-continuous)
hide range x 0,80 y 0,50 z 0,10
hide range x 55,80 y 0,50 z 0,50
jset dip 70 dd 200 org 0 35 0
jset dip 60 dd 330 org 50 15 50
seek
hide range x 0,30 y -30,80 z 13,50
ret

Figure 3.8

3DEC Version 4.1
106

Rock slope containing continuous and noncontinuous joints

PROBLEM SOLVING WITH 3DEC

3 - 17

Bear in mind that joints are displayed as straight-line segments in the 3DEC model; many segments
may be required to fit an irregular joint structure. The modeler must decide the level at which the
3DEC joint geometry will match the physical jointing pattern. The effect of geometric irregularity
on the response of a joint can also be taken into account via the joint material model (e.g., by varying
properties along the joint).
One final point concerning joint generation: When using continuum programs, it is usually appropriate to take advantage of symmetry conditions with excavation shapes, in order to reduce the
size of the model. Symmetry conditions cannot be imposed as easily with discontinuum programs,
because the presence of discontinuous features precludes symmetry except for special cases. For
example, it is not possible to impose a vertical plane of symmetry through the model shown in
Figure 3.8, because the joints in the model are not aligned with the vertical axis.
3.2.3 Creating Internal Boundary Shapes
When fitting the 3DEC model to the problem region, polyhedral boundaries must also be defined
to coincide with boundary shapes of the physical problem. These may be internal boundaries
representing excavations or holes, or external boundaries representing, for example, man-made
structures such as earth dams, or natural features such as mountain slopes. If the physical problem
has a complicated boundary, it is important to assess whether simplification will have any effect
on the questions that need to be answered (i.e., whether a simpler geometry will be sufficient to
reproduce the important mechanisms).
All physical boundaries to be represented in the model simulation (including regions that will be
added, or excavations created at a later stage in the simulation) must be defined before the solution
process begins. Shapes of structures that will be added later in a sequential analysis must be
defined and then “removed” (via the EXCAVATE command). Excavated blocks are added with the
FILL command. Note that only deformable blocks can be excavated and filled.
The creation of boundary shapes is performed with the following commands:
JSET
TUNNEL
POLY cube
Each command cuts the polyhedra into one or more segments that are fitted together in the desired
shape. The JSET commands create planar joint segments as discussed above in Section 3.2.2. The
TUNNEL command cuts a shape into the blocks. The POLY cube command creates a volume of
cubed blocks, and cuts a boundary.

3DEC Version 4.1
107

3 - 18

User’s Guide

3.2.3.1 Tunnel Command
The TUNNEL command creates a tunnel whose boundary is formed by planar segments that connect
two faces (designated as face A and face B). The shape of the tunnel face is prescribed by an arbitrary
number of vertices with coordinates (x1,y1,z1), (x2,y2,z2), (x3,y3,z3), etc. The same number of
vertices must exist on both faces; the faces may be positioned either inside or outside of the model.
Example 3.7 presents a simple example for the creation of a horseshoe-shaped tunnel. The command
REMOVE is used to delete the tunnel region (defined as region 1). The DELETE command may also
be used; with the REMOVE command, the deleted region can still be viewed in plot mode, if desired.
The resulting tunnel is shown in Figure 3.9.
Example 3.7 Tunnel created with the TUNNEL command
new
poly brick -1.5,1.5 -1.5,1.5 -1.5,1.5
pl bl colorby material
pl reset
pl set dip 70 dd 200
tunnel radial region 1 &
a (-0.30,-1.5,0.00) (-0.3,-1.5,0.40)
(-0.15,-1.5,0.52) ( 0.0,-1.5,0.55)
( 0.25,-1.5,0.47) ( 0.3,-1.5,0.40)
b (-0.30, 1.5,0.00) (-0.3, 1.5,0.40)
(-0.15, 1.5,0.52) ( 0.0, 1.5,0.55)
( 0.25, 1.5,0.47) ( 0.3, 1.5,0.40)
remove region 1
ret

3DEC Version 4.1
108

(-0.25,-1.5,0.47)
( 0.15,-1.5,0.52)
( 0.30,-1.5,0.00)
(-0.25, 1.5,0.47)
( 0.15, 1.5,0.52)
( 0.30, 1.5,0.00)

&
&
&
&
&

PROBLEM SOLVING WITH 3DEC

Figure 3.9

3 - 19

Tunnel created with TUNNEL command

Usually, the model will be brought to an equilibrium state before the tunnel is excavated. The
user must be careful that the fictitious joints along the tunnel boundary do not influence model
response during the initial equilibrium calculation. If the TUNNEL command is used, the blocks are
automatically joined at the fictitious joints. If JSET commands are used to create fictitious joints,
then it is recommended that the JOIN command be used to join the blocks separated by the fictitious
joint. Use the LIST contact command to identify whether the contact is a master-slave (m-s) contact
between joined blocks.
3.2.3.2 POLY cube
POLY cube is a tool for generating irregularly shaped boundaries. These boundaries may represent
geologic contacts or the borders of excavations. This is intended as an alternative to the PGEN
program. The advantage of POLY cube over the PGEN program is that the resulting shapes are
easier to zone, and can be zoned as mixed discretization zones for plasticity. The disadvantage is
that the shapes can be complex in only two dimensions. Using PGEN, the shapes can be complex
in three dimensions.
The POLY cube process is relatively simple. The user specifies information about the size and
orientation of the shape to be created. 3DEC then generates an area of six-sided polyhedra (cubes)
which occupies this area. The orientation of the region can be along any line in space, and can be
rotated about that line. After the cubes are created, 3DEC uses the coordinates specified in a data
file (normally “overlay.txt”) to cut the geometry out of the cubes. Each cube is cut only once by
the boundary, so the resolution of the shape is defined by the size of the cubes.

3DEC Version 4.1
109

3 - 20

User’s Guide

The orientation of the cube area is defined by the dip, ddirection, top and rotate keywords that define
a control plane (see Figure 3.10). All blocks are created behind this control plane. The size and
shape of the cubes are defined by the number and spacing keywords. An outer box can be created as
a zoning transition with the box keyword. The IDs of the jointing are controlled by the id keyword.
The region numbers can be set by the inside and outside keywords.
The file that controls the cutting of the boundary shape is a simple text file of x,y,z coordinates. A
DXF file may also be used, but the coordinates in the DXF file must define a contiguous polygon.
The PGEN program may be used to edit the DXF file to connect discontinuous segments.

top point
rotate

nz

ny
y x z

nx
spacing
control plane
defined by dip and
dip direction

Figure 3.10 Elements of the POLY cube command
This simple example demonstrates the construction of a 500-cube area that is cut by the polygon
stored in “overlay.txt.”

3DEC Version 4.1
110

PROBLEM SOLVING WITH 3DEC

3 - 21

Example 3.8 Data file which generates a model using POLY cube command
new
;
; example of use of poly cube command
;
config LH
poly br 0 100 0 40 0 100
plot block colorby reg
pl reset
poly cube dip 90 dd 180 num 10 5 10 spac 4 8 4 top
seek
hide reg 1
ret

50 0 50

The cutting geometry is controlled by the data points in the file “overlay.txt”:
31 31
31 41
37 51
41 61
51 69
63 61
63 51
47 43
; end

0
0
0
0
0
0
0
0
of segment

3DEC Version 4.1
111

3 - 22

User’s Guide

Figure 3.11 Resultant geometry from example

3.2.4 Selecting the Coordinate System
As shown in Figure 3.5, the reference axes for 3DEC are a left-handed set (x,y,z), oriented by
default as x (east), y (north) and z (vertical). In generating a 3DEC model of a given region, the
following conditions may require reorientation for input into the model:
(1) geometry of the problem structures (e.g., mine layout, tunnel locations, etc.);
(2) geometry of the geologic features (e.g., faults and joint sets); and
(3) orientation of the in-situ stress field.
In the ideal situation, the problem geometries would align with the 3DEC reference axes. In general
though, this is not the case, and one or two of the problem geometries will require transformation
to the 3DEC model reference frame.
Typically, it is best to orient the 3DEC model axes to align with the geometry of the problem
structures (e.g., the mine grid or centerline of a tunnel). For graphic presentation, it is best to
position the origin of the model axes at the center of the structure for which the analysis is intended.
In this case, the geologic features may require reorientation from global to local problem axes (see
Section 3.2.5, below), and the field principal stresses may require transformation for application to
the model boundary. The recommended procedure to execute this transformation is discussed in
Section 3.5.8.

3DEC Version 4.1
112

PROBLEM SOLVING WITH 3DEC

3 - 23

For reasons of numerical precision, it is best to truncate coordinates to some convenient number.
For example, if the units for a model are from x = 15,423 to 15,443, it is best to truncate the
coordinates by 15,400 so that the model coordinates range from 23 to 43.
3.2.5 Orientation of Geologic Features to the Model Axes
If the problem axes do not align with the model axes (i.e., positive z-axis (vertical), x-axis (east)
and y-axis (north)), then the orientation of geologic features will have to be transformed from the
problem axes to the model axes. This can be accomplished by using a stereonet.
The reorientation of structural features to the model reference axes is demonstrated for the case
of a single fault that crosses a mine raise. The raise is oriented with an axis dip of 84◦ and dip
direction of 125◦ , and the fault is oriented 11◦ / 148◦ . The 3DEC model axes are located with the
z-axis directed down the raise, the y-axis lying in the vertical plane containing the raise dip vector,
and the x-axis lying in the horizontal plane. The origin of the model axes is located at the center of
the raise (see Figure 3.12). The dip and dip direction of the fault must be redefined relative to the
x,y,z-model axes as oriented in the figure.
UP

N
ventilation
raise

Raise Orientation
> = 125º
= = 84º

>

E

=
N35º
x

Model Axes

y
z

Figure 3.12 Orientation of 3DEC model axes (x,y,z) relative to north-eastvertical reference axes

3DEC Version 4.1
113

3 - 24

User’s Guide

The fault pole is plotted on the lower hemisphere stereonet shown in Figure 3.14. The relation
between the fault and the model axes is found by plotting the positive x-, y- and z-axes of the model
on the stereonet. The dihedral angle between the fault pole and each axis is then read from the
stereonet. In this example, the dihedral angles are 86◦ for x-axis to fault pole, 73◦ for z-axis to fault
pole, and 17◦ for y-axis to fault pole.
On a second stereonet (Figure 3.13), the model axes are oriented to align with the axes of the
stereonet: z (vertical), x (east) and y (north). The intersection of the three dihedral angles on this
plot gives the pole of the fault (plotted on the upper hemisphere). The orientation of the fault relative
to the model axes is thus 74◦ / 2◦ .
3.2.6 Choice of Model Scale
Analysis of rock mass response involves several different scales. It is impossible (and undesirable)
to include all features, details or rock mass response mechanisms in one model. It is also wellrecognized that location of the far-field boundary in the model can have a significant influence
on results obtained for underground excavations. However, in three-dimensional analysis, it is
not always feasible to place boundaries sufficiently far from the excavations to avoid adversely
affecting the results. These two observations taken together suggest that a reasonable modeling
approach involves starting with a large global model and proceeding through reasonable models to
the smallest size required, with increasing complexity and detail added at each stage. 3DEC has an
automatic method of recording stresses at specified locations so that they can be applied as boundary
tractions on smaller problems. This unique feature ensures stress compatibility between larger and
smaller models. See Section 3.4.4.2 for additional information on applying this technique.
3.2.7 Incorporation of Discontinuities
Selection of joint geometry for input to a model is a crucial step in distinct element analysis.
Typically, only a very small percentage of joints can actually be included in the model, so that
models of reasonable size and execution speed for practical analysis can be created. Thus, the
modeler must filter joint geometry data, and select only those joints that are most critical to the
mechanical response by identifying those which are most susceptible to slip for the prescribed
loading conditions. This may involve, for example, determining whether sufficient kinematic
freedom is provided (e.g., through the use of block theory) or comparing in-situ observations and
records (e.g., microseismic records to identify key joints).
Once a consistent set of joints is selected, the geometric parameters (e.g., strike, dip, location) for
these features are input into the model, and the practicality of the analysis in terms of required
memory and runtime are assessed. If the model size is too large, the number of joints must be
reduced, and it is necessary to further filter the input to bring the model to a practical size. This
dilemma of balancing model size and critical joint structures is addressed by Hart (1993).
In some cases, exactly how important certain discontinuities are, or whether discontinuities should
be incorporated into the model at all, may not be clear. The guiding philosophy in these cases
is to first run the models either with no discontinuities, or with the discontinuities in a welded
state. Comparisons should then be made with observations. If adequate calibration of the model

3DEC Version 4.1
114

PROBLEM SOLVING WITH 3DEC

3 - 25

behavior can be obtained without discontinuities, then discontinuities need not be modeled. By
rerunning the model and allowing certain discontinuities to slip, the modeler can determine exactly
how the discontinuities affect the system behavior, and whether that behavior agrees more closely
with observations.

3DEC Version 4.1
115

3 - 26

User’s Guide

N
x-axis
86º
73º
pole to fault
17º
z-axis

E

fault plane

Figure 3.13 Stereonet plot of fault relative to model axes

z

17º

73º
fault

86º

pole on
upper hemisphere

fault plane
74º/2º

x
y (up)

fault
pole on
lower hemisphere

Figure 3.14 Stereonet plot of pole to fault and model reference axes relative
to problem north-east axes

3DEC Version 4.1
116

PROBLEM SOLVING WITH 3DEC

3 - 27

3.3 Selection of Deformable versus Rigid Blocks
An important consideration when doing a discontinuum analysis is whether to use rigid or deformable blocks to represent the behavior of intact material. The considerations for rigid versus
deformable blocks are discussed in this section. If a deformable block analysis is required, there are
several different models available to simulate block deformability; these are discussed in Section 3.7.
As mentioned in Section 1.1 in Theory and Background, early distinct element codes assumed
that blocks were rigid. However, the importance of including block deformability has become
recognized, particularly for stability analyses of underground openings and studies of seismic
response of buried structures. One of the most obvious reasons to include block deformability in a
distinct element analysis is the requirement to represent the “Poisson’s ratio effect” of a confined
rock mass.
3.3.1 Poisson’s Effect
Rock mechanics problems are usually very sensitive to the Poisson’s ratio chosen for a rock mass.
This is because joints and intact rock are pressure-sensitive; their failure criteria are functions of
the confining stress (e.g., the Mohr-Coulomb criterion). Capturing the true Poisson behavior of a
jointed rock mass is critical for meaningful numerical modeling.
The effective Poisson’s ratio of a rock mass is comprised of two parts: a component due to the
jointing; and a component due to the elastic properties of the intact rock. Except at shallow depths
or low confining stress levels, the compressibility of the intact rock makes a large contribution to
the compressibility of a rock mass as a whole. Thus, the Poisson’s ratio of the intact rock has a
significant effect on the Poisson’s ratio of a jointed rock mass.
A single Poisson’s ratio, ν, is, strictly speaking, defined only for isotropic elastic materials. However, there are only a few jointing patterns that lead to isotropic elastic properties for a rock mass.
Therefore, it is convenient to define a “Poisson effect” that can be used for discussion of anisotropic
materials.
The Poisson effect will be defined as the ratio of horizontal-to-vertical stress when a load is applied
in the vertical direction and no strain is allowed in the horizontal direction; plane-strain conditions
are assumed. As an example, the Poisson effect for an isotropic elastic material is
σxx
ν
=
σzz
1−ν

(3.1)

Consider the Poisson effect produced by the vertical jointing pattern shown in Figure 3.15. If this
jointing were modeled with rigid blocks, applying a vertical stress would produce no horizontal
stress at all. This is clearly unrealistic, because the horizontal stress produced by the Poisson’s ratio
of the intact rock is ignored.

3DEC Version 4.1
117

3 - 28

User’s Guide

yy

yy

Figure 3.15 Model for Poisson’s effect in rock with vertical and horizontal
jointing
The joints and intact rock act in series. In other words, the stresses acting on the joints and on the
rock are identical. The total strain of the jointed rock mass is the sum of the strain due to the jointing
and the strain due to the compressibility of the rock. The elastic properties of the rock mass as a
whole can be derived by adding the compliances of the jointing and the intact rock:


 
 
xx
σxx
rock
jointing
= C
+C
yy
σyy

(3.2)

If the intact rock were modeled as an isotropic elastic material, its compliance matrix would be
1+ν
C rock =
E



1−ν
−ν

−ν
1−ν


(3.3)

The compliance matrix due to the jointing is

C jointing =

1
Skn

0

0

1
Skn



where S is the joint spacing, and kn is the normal stiffness of the joints.

3DEC Version 4.1
118

(3.4)

PROBLEM SOLVING WITH 3DEC

3 - 29

If xx = 0 in Eq. (3.2), then
(total)

C
σxx
= − 12
(total)
σyy
C

(3.5)

11

where C (total) = C (rock) + C (j ointing) .
Thus, the Poisson effect for the rock mass as a whole is
ν (1 + ν)
σxx
=
σyy
E/(Skn ) + (1 + ν)(1 − ν)

(3.6)

Eq. (3.6) is graphed as a function of the ratio E/(Skn ) in Figure 3.16. Also graphed are the results
of several two-dimensional UDEC simulations run to verify the formula. The ratio E/(Skn ) is a
measure of the stiffness of the intact rock in relation to the stiffness of the joints. For low values
of E/(Skn ), the Poisson effect for the rock mass is dominated by the elastic properties of the intact
rock. For high values of E/(Skn ), the Poisson effect is dominated by the jointing.
Now consider the Poisson effect produced by joints dipping at various angles. The Poisson effect
is a function of the orientation and elastic properties of the joints. Consider the special case shown
in Figure 3.17. A rock mass contains two sets of equally spaced joints dipping at an angle, θ , from
the horizontal. The elastic properties of the joints consist of a normal stiffness, kn , and a shear
stiffness, ks . The blocks of intact rock are assumed to be completely rigid.

UDEC Simulations

0.4

Analytic Solution

xx

yy

0.3

0.2

0.1

0
0

0.5

1

1.5

E

2

2.5

3

SK n

Figure 3.16 Poisson’s effect for vertically jointed rock
(ν = 0.3 for intact rock)

3DEC Version 4.1
119

3 - 30

User’s Guide

S

yy

O

yy

Figure 3.17 Model for Poisson’s effect in rock with joints dipping at angle θ
from the horizontal and with spacing S
The Poisson effect for this jointing pattern is
cos2 θ [(kn / ks ) − 1]
σxx
=
σyy
sin2 θ + cos2 θ (kn / ks )

(3.7)

This formula is illustrated graphically for several values of θ in Figure 3.18. Also shown are the
results of numerical simulations using UDEC. The UDEC simulations agree closely with Eq. (3.7).

0.8

xx

yy

0.6

0.4
Analytic Solution UDEC Simulation
o
O = 20
o
O = 45

0.2

o
O = 60

0
2

4

6

Kn

8

10

Ks

Figure 3.18 Poisson’s effect for jointed rock at various joint angles (blocks
are rigid)

3DEC Version 4.1
120

PROBLEM SOLVING WITH 3DEC

3 - 31

Eq. (3.7) demonstrates the importance of using realistic values for joint shear stiffness in numerical
models. The ratio of shear stiffness to normal stiffness dramatically affects the Poisson response
of a rock mass. If shear stiffness is equal to normal stiffness, the Poisson effect is zero. For more
reasonable values of kn /ks , from 2.0 to 10.0, the Poisson effect is quite high, up to 0.9.
Next, the contribution of the elastic properties of the intact rock will be examined for the case of
θ = 45◦ . Following the analysis for the vertical jointing case, the intact rock will be treated as an
isotropic elastic material. The elastic properties of the rock mass as a whole will be derived by
adding the compliances of the jointing and the intact rock.
The compliance matrix due to the two equally spaced sets of joints dipping at 45◦ is
C

(j ointing)



1
=
2S kn ks

ks + kn
ks − kn

ks − kn
ks + kn



Thus, the Poisson effect for the rock mass as a whole is
[ν(1 + ν)] / E + (kn − ks ) / (2S kn ks )
σxx
=
σyy
[(1 + ν)(1 − ν)] / E + (kn + ks ) / (2S kn ks )

(3.8)

Eq. (3.8) is graphed for several values of the ratio E/(Skn ) for the case of ν = 0.2 (see Figure 3.19).
Also plotted are the results of UDEC simulations. For low values of E/(Skn ), the Poisson effect of
a rock mass is dominated by the elastic properties of the intact rock. For high values of E/(Skn ),
the Poisson effect is dominated by the jointing.

0.8
Rigid

locks

B

(

E SK n

=

)

xx

yy

0.6
0.5
E SK n =

0.4
Rock with No Joints

0.2

( E SK

n

= 0

)

UDEC Simulation

0
2

4

6

Kn

8

10

Ks

Figure 3.19 Poisson’s effect for rock with two equally spaced joint sets
with θ = 45◦ (blocks are deformable with ν = 0.2)

3DEC Version 4.1
121

3 - 32

User’s Guide

3.3.2 Zoning for Deformable Blocks
If a deformable block analysis is required, models with different densities of block zoning should
be evaluated once the block cutting and boundary location have been established. The GENERATE
edge and GENERATE quad commands are used to specify the zoning density. The highest density
of zoning should be in regions of high stress or strain gradients (e.g., in the vicinity of excavations).
For greatest accuracy, the aspect ratio of zone dimensions (i.e., tetrahedron base length to height
ratio) should also be as near unity as possible; anything above 5:1 is potentially inaccurate. Neither
is it advisable to have large jumps in zone size between adjacent polyhedra. The ratio between
zone volumes in adjacent polyhedra should not exceed roughly 4:1 for reasonable accuracy. Use
the LIST max command to find the maximum and minimum zone volumes.
The GENERATE edge command will automatically create tetrahedral zones within an arbitrarily
shaped convex polyhedron. It is recommended that if block-cutting results in blocks that are long
and thin, these blocks should be further cut and joined before generating zones. By doing this,
zones with an aspect ratio closer to unity can be generated.
The GENERATE quad command will only generate zones within six-sided polyhedra. This command
creates mixed-discretization (m-d) zones (two overlays of five tetrahedral zones) that provide better
accuracy for problems involving failure and collapse of the intact blocks. (See Section 1.2.2.5 in
Theory and Background for details.) It is recommended that the GENERATE quad command be
used for analyses involving plastic failure of the intact material. The GENERATE edge command
can provide reasonable accuracy for certain failure modes (e.g., confined compression loading);
however, this type of zoning does not produce an accurate prediction for collapse loads in bearing
capacity problems. Comparisons of results using GENERATE quad versus GENERATE edge for
plasticity analysis are given in Sections 5 and 6 in the Verifications volume.
The GENERATE edge command produces zoning that is more computationally efficient, and is
recommended for blocks in regions where extensive intact material failure is not anticipated. In order
to improve the calculational efficiency for models involving intact material failure, the GENERATE
quad command can be used to generate m-d zones around an excavation, and the GENERATE edge
command can then be used to generate zones in blocks at greater distance from the excavation (or
for surrounding blocks that are not six-sided).
The GENERATE hotetra command produces high-order tetrahedral zones that can be used in blocks
which cannot be zoned with m-d zoning. These zones have additional gridpoint nodes and are
more accurate than the standard tetrahedral zoning. Note that high-order tetrahedral zones are not
compatible with the far-field dynamic boundary or the extended zone models (CPPUDM).
The analysis of large models can also be aided by using the GENERATE center command, which
is a variation of the GENERATE edge command. This command allows the sizes of the tetrahedral
zones to be increased gradually, outward from a central point.

3DEC Version 4.1
122

PROBLEM SOLVING WITH 3DEC

3 - 33

3.4 Boundary Conditions
The boundary conditions in a numerical model consist of the values of field variables (e.g., stress,
displacement) that are prescribed at the boundary of the model. Boundaries are of two categories:
real and artificial. Real boundaries exist in the physical object being modeled (e.g., a tunnel surface
or the ground surface). Artificial boundaries do not exist in reality, but they must be introduced in
order to enclose the chosen number of elements (e.g., blocks). The conditions that can be imposed on
each type are similar; these conditions are discussed first. Then (in Section 3.4.4), some suggestions
are made concerning the location and choice of artificial boundaries, and the effect they have on
the solution.
Mechanical boundaries are of two main types: prescribed displacement and prescribed stress. A
free surface is a special case of the prescribed-stress boundaries. The two types of mechanical
boundaries are described in Sections 3.4.1 and 3.4.2. Viscous boundaries, which are used for
dynamic analysis, are described in Section 2 in Optional Features.
3.4.1 Stress Boundary
By default, the boundaries of a 3DEC model are free of stress and any constraint. Forces or stresses
may be applied to any boundary, or part of a boundary, with the BOUNDARY command. Note that
forces and stresses can be applied to either rigid or deformable blocks. Individual components
of the stress tensor (σxx , σyy , σzz , σxy , σxz and σyz ) are specified with the stress keyword. For
example, the command
boundary (0,10) (-1,1) (0,10) stress 0,0,-1e6 0,0,0

would apply σxx = 0, σyy = 0, σzz = −106 and zero shear stresses to a model boundary lying
within the coordinate window 0 < x < 10, −1 < y < −1, 0 < z < 10. The user should always
make sure that the window encompasses all of the boundary vertices designated for the assigned
boundary condition. This can be done using the command
list boundary state

Each exterior boundary vertex will be listed with its assigned boundary code. (See the LIST boundary
command in Section 1.3 in the Command Reference.) The boundary can move during a model
calculation, so the user must make sure that the coordinate window is large enough to include the
appropriate boundary vertices at the time the BOUNDARY command is executed.
Alternatively, boundary conditions can be specified along a boundary defined by the orientation of
the boundary face. For example, the same boundary condition as above can be applied with the
command
boundary dip 90 dd 180 or 0,1,0 above stress 0,0,-1e6

0,0,0

This will apply the boundary condition along the boundary face located within the range defined
by a plane with a dip angle of 90◦ , a dip direction of 270◦ , and above the position x = 0, y = 1, z =
0.

3DEC Version 4.1
123

3 - 34

User’s Guide

Compressive stresses have a negative sign, in accordance with the general sign convention for
internal stresses in 3DEC. Also, 3DEC actually applies stress components as forces, or tractions,
which result from a stress tensor acting on the given boundary plane. The tractions are divided into
two components, permanent and transient. Permanent tractions are constant loads, and transient
tractions are time-varying loads applied for dynamic analysis (see Section 2 in Optional Features)
by using the history keyword on the same command line as the stress keyword. Various forms
of time-varying histories can be applied, including linear-varying, sine and cosine wave, and usersupplied functions; these are described in Section 1.3 in the Command Reference (see BOUNDARY
history).
Individual forces can be applied to the model boundary of rigid or deformable blocks by using the
xload, yload and zload keywords, which specify x-, y- and z-components of an applied force vector.
3.4.1.1 Applied Stress Gradient
The BOUNDARY command may take additional keywords xgrad, ygrad and zgrad, which allow the
applied stresses or forces to vary linearly over the specified range. Six parameters follow each of
these keywords and describe the variation of the stress components in the x-, y- or z-direction:
xgrad sxxx syyx szzx sxyx sxzx syzx
ygrad sxxy syyy szzy sxyy sxzy syzy
zgrad sxxz syyz szzz sxyz sxzz syzz
The stresses vary linearly with distance from the global coordinate origin of x = 0, y = 0, z = 0:
◦
σxx = σxx
+ (sxxx)x + (sxxy)y + (sxxz)z
◦
σyy = σyy
+ (syyx)x + (syyy)y + (syyz)z
◦
σzz = σzz
+ (szzx)x + (szzy)y + (szzz)z
◦
σxy = σxy
+ (sxyx)x + (sxyy)y + (sxyz)z
◦
σxz = σxz
+ (sxzx)x + (sxzy)y + (sxzz)z
◦
σyz = σyz
+ (syzx)x + (syzy)y + (syzz)z
◦ , σ ◦ , σ ◦ , σ ◦ , σ ◦ and σ ◦ are the stress components at the origin.
where σxx
yy zz xy xz
yz

The operation of this feature is best explained by an example:
boundary -.1,.1 0,10 -100,0 stress 0,0,-10e6 0,0,0

3DEC Version 4.1
124

zgrad 0,0,1e5 0,0,0

(3.9)

PROBLEM SOLVING WITH 3DEC

3 - 35

The stresses at the origin (x = 0, y = 0, z = 0) are:
◦
= 0
σxx
◦
= 0
σyy
◦
σzz
= −10 × 106

◦
σxy
= 0
◦
= 0
σxz
◦
= 0
σyz

The equation for the z-variation in stress component σzz is
σzz = −10 × 106 + (105 )z
The value for σzz at z = −100 is then −20 × 106 . At points in between, the z-variation is linearly
scaled to the relative z-distance from the origin.
Typically, applied stress gradients are used to reproduce the effects of increasing stress with depth
caused by gravity. It is important to make sure that the applied gradient is compatible with the
gradient specified with the INSITU command and the value of gravitational acceleration (GRAVITY
command). Section 3.5 provides more details on this matter.
3.4.1.2 Changing Boundary Stresses
As discussed above, transient loading can be performed with the history keyword for dynamic
analysis. For static analysis, it may also be necessary to alter the values of applied stresses during
the course of a 3DEC simulation. For example, the load on a footing may change. To effect a
sudden change in an existing applied stress or load, a new BOUNDARY command is given with the
range that encompasses the same boundary vertices as in the original command, but with a change
in stress value or variation.
In this case, the new value will be added to the existing value.* If the stress is to be removed,
the current value should be given with an opposite sign. If a transient load is changed (i.e., a load
assigned with the history keyword), any new load with the same history type is added to the existing
load; however, a new transient load with a different history type replaces the old transient load.
* The user should be aware that this approach is different than the one used in the Itasca code FLAC,
in which the stresses are updated to the new values when a new boundary condition is specified.

3DEC Version 4.1
125

3 - 36

User’s Guide

3.4.1.3 Checking the Boundary Condition
The boundary stresses and loads may be verified with the command LIST bound. The LIST bound
command lists the boundary vertex addresses, along with current values and conditions assigned to
each vertex. Once a BOUNDARY command is issued, a boundary vertex list is created for the model
face to which the boundary condition is assigned. Optional keywords can be used with the LIST
bound command to check the different conditions along the boundary. For example,
list bound force

lists the permanent forces (fx,fy,fz) and incremental forces (fxi,fyi,fzi) added during the current
loading stage. If transient loads are applied (with the BOUND. . . hist command), the total forces
refer to the permanent plus transient loads at the current cycle number.
The command
list bound state

identifies the type of boundary condition assigned to a boundary vertex.
3.4.1.4 Cautions and Advice
In this section, some miscellaneous difficulties with stress boundaries are described. With 3DEC, it
is possible to apply stresses to the boundary of a body that has no displacement constraints (unlike
many finite element programs, which require some constraints). The body will react in exactly the
same way as a real body would (i.e., if the boundary stresses are not in equilibrium, then the whole
body will start moving).
A similar, but more subtle, effect arises when material is excavated from a body that is supported
by a stress boundary condition: the body is initially in equilibrium under gravity, but the removal
of material reduces the weight. The whole body then starts moving upward, as demonstrated in
Example 3.9 and illustrated in Figure 3.20.
Example 3.9 Uplift when material is removed
new
poly brick 0,10 0,10 0,10
plot block axes
pl reset
plot set dip 70 dd 150
jset dip 0 dd 180 origin 0,0,5
gen quad ndiv 4 4 4
change cons 1
prop mat=1 dens 1000 bulk 8e9 g 5e9
prop jmat=1 jkn 1e10 jks 1e10
gravity 0,0,-10
bound stress 0,0,-1e5 0,0,0 range x 0,10 y 0,10 z -0.1,.1
bound xvel = 0.0 range x -.1,.1

3DEC Version 4.1
126

PROBLEM SOLVING WITH 3DEC

3 - 37

bound xvel = 0.0 range x 9.9,10.0
bound yvel = 0.0 range y -.1,.1
bound yvel = 0.0 range y 9.9,10.1
insitu stress 0,0,-1e5 0,0,0 zgrad 0,0,1e4 0,0,0
hist zdisp 5,5,2.5
step 300
excavate range x 0,10 y 0,10 z 5,10
step 100
pl block colorby mat fill off axes
plot add vel line color red
ret

Figure 3.20 Uplift when material is removed
The difficulty encountered in running this data file can be eliminated by fixing the bottom boundary,
rather than supporting it with stresses. Section 3.4.4 contains information relating to the location
of such artificial boundaries.
Finally, the stress boundary affects all degrees-of-freedom. Velocity boundary conditions must,
therefore, be prescribed after stress boundary conditions affecting the same boundary corners. If
the stress boundary is applied after the velocity boundary, the effect of the prescribed velocity will
be lost. Example 3.10 demonstrates this problem:

3DEC Version 4.1
127

3 - 38

User’s Guide

Example 3.10 Mixing stress and velocity boundary conditions
new
poly brick 0,10 0,10 0,10
pl bl
plot reset
gen quad ndiv 4 4 4
prop mat=1 dens 1000 bulk 8e9 g 5e9
bound zvel = 0.0
range z 0.0
bound stress -1e5,0,0 0,0,0 range x 0.0
bound stress -1e5,0,0 0,0,0 range x 10.0
bound stress 0,-1e5,0 0,0,0 range y 0.0
bound stress 0,-1e5,0 0,0,0 range y 10.0
bound stress 0,0,-2e5 0,0,0 range z 10.0
hist zdisp 0,0,0
step 100
plot axes block fill off vel line color blue
ret

Figure 3.21 Mixing stress and velocity boundary conditions
The fixed z-velocity boundary condition along the bottom boundary of the model is removed along
the bottom edges of the block when the stress boundaries are applied. These points move downward,
as indicated by the velocity vector plot in Figure 3.21, when the model is loaded.

3DEC Version 4.1
128

PROBLEM SOLVING WITH 3DEC

3 - 39

3.4.2 Displacement Boundary
Displacements cannot be controlled directly in 3DEC; in fact, they play no part in the calculation
process, as explained in Section 1.2.2 in Theory and Background. In order to apply a given
displacement to a boundary of a deformable block model, it is necessary to fix the boundary and
prescribe the boundary’s velocity for a given number of steps (using the BOUNDARY command). If
the desired displacement is D, a velocity, V , is applied for a time increment, T (e.g., D = V T ),
where T = tN, t is the timestep and N is the number of steps (or cycles). In practice, V should
be kept small and N large, in order to minimize shocks to the system being modeled.
The BOUNDARY command is used to fix the velocity of gridpoints of deformable blocks in the x-, yor z-direction (BOUND xvel, yvel or zvel) or in the normal direction (BOUND nvel) along boundaries
not aligned with the x-, y- and z-axes. The velocity of rigid or deformable blocks can be fixed with
the FIX command (at the current velocity). Use the APPLY command to specify a velocity other
than the current value for rigid blocks. The velocity can also be altered with a FISH function.
Time-varying velocity histories can be applied via the BOUND . . . hist command for deformable
blocks or the APPLY . . . hist command for rigid blocks. This history keyword must appear on the
same line as BOUND xvel, BOUND yvel or BOUND zvel to prescribe a velocity history. Histories
can also be applied as FISH functions. As discussed in Section 3.4.1.4, velocity boundaries should
always be assigned after stress boundaries. Fixed velocity conditions can be removed for deformable
blocks with the BOUND xfree, BOUND yfree or BOUND zfree command, and for rigid blocks with
the FREE command.
3.4.3 Real Boundaries — Choosing the Right Type
It is sometimes difficult to know the type of boundary condition to apply to a particular surface on
the body being modeled. For example, in modeling a laboratory triaxial test, should the load applied
by the platen be regarded as a stress boundary, or should the platen be treated as a rigid displacement
boundary? Of course, the whole testing machine, including the platen, could be modeled, but that
might be very time-consuming. Remember that 3DEC takes a long time to converge if there is a
large contrast in stiffnesses. In general, if the object applying the load is very stiff compared with
the sample (say, more than 20 times stiffer), then it may be treated as a rigid boundary. If it is
soft compared with the sample (say, 20 times softer), then it may be modeled as a stress-controlled
boundary. Clearly, a fluid pressure acting on the surface of a body is in the latter category. Footings
on jointed rock can often be represented as rigid boundaries that move with constant velocity, for
the purposes of finding the collapse load of the rock. This approach has another advantage: it is
much easier to control the test and obtain a good load/displacement graph. It is well-known that
stiff testing machines are more stable than soft testing machines.

3DEC Version 4.1
129

3 - 40

User’s Guide

3.4.4 Artificial Boundaries
Artificial boundaries fall into two categories: planes of symmetry and planes of truncation. Symmetry planes take advantage of symmetry conditions in a physical system; truncation planes are
needed when modeling an infinite or very large system.
3.4.4.1 Symmetry Planes
Sometimes it is possible to take advantage of the fact that the geometry and loading in a system are
symmetrical about one or more planes. For example, if everything is symmetrical about a vertical
(yz) plane, then the horizontal displacements on that plane will be zero. Therefore, we can make
that plane a boundary, and fix all gridpoints in the horizontal direction, using the command BOUND
xvel=0. If velocities on the plane of symmetry are not already zero, they will be set to zero with this
command. In the case considered, the y-component and z-component of velocity on the vertical
plane of symmetry are not affected; they should not be fixed. Similar considerations apply to a
horizontal plane of symmetry. The command BOUND nvel=0 can be used to set planes of symmetry
that lie at angles to the coordinate axes.
As discussed in Section 3.2.3, the presence of discontinuities makes the application of symmetry
planes more difficult. When using symmetry planes in 3DEC, the modeler should always be careful
to consider the effect of joint orientation.
3.4.4.2 Boundary Truncation — Location of the Far-Field Boundary
Analysis of rock-mass response involves several different scales. It is impossible (and undesirable)
to include all features, details or rock-mass response mechanisms in one model. It is also wellrecognized that location of the far-field boundary in the model can have a significant influence
on results obtained for underground excavations. However, in three-dimensional analysis, it is
not always feasible to place boundaries sufficiently far from the excavations to avoid adversely
affecting the results. These two observations, taken together, suggest that a reasonable modeling
approach involves starting with a large global model and proceeding through reasonable models
to the smallest size required, with increasing complexity and detail added at each stage. 3DEC
has an automatic method of recording stresses at specified locations so that they can be applied as
boundary tractions on smaller problems. This unique feature ensures stress compatibility between
larger and smaller models.
An example of the application of this technique is a mine in which the local topographic relief is
significant relative to the size of the mine, and in which a model incorporating both the surrounding
topography and the mine geometry is prohibitively large. A coarse regional model incorporating
a relatively large sample of the surrounding topography is first created, as shown in Figure 3.22.
Following this, a smaller central portion of the regional model is generated, incorporating details of
the mining geometry, which is more finely zoned. Boundary tractions applied to the detailed model
are transferred from the regional model at points corresponding to the locations of the detailed
model boundaries by the following procedure:

3DEC Version 4.1
130

PROBLEM SOLVING WITH 3DEC

3 - 41

1. Run Model A.
2. Enter the command SET log on.
3. Enter the command LIST brick xl xu yl yu zl zu where (xl, xu), (yl, yu) and (zl,
zu) correspond to the boundaries of Model B.
4. The loads printed to the log file for the LIST brick command can be applied to
Model B by using the BOUND xtraction, BOUND ytraction and BOUND ztraction
commands.
An important modeling decision to be made when using this procedure, is how extensive a volume
should be incorporated into each of the regional and detailed models.
In the regional model, the topographic relief should be small relative to the external dimensions
of the model. A criterion recommended for selecting the depth of the model is that stresses near
the bottom of the model should be relatively uniform (i.e., it should not be possible to determine
whether a point is beneath a mountain peak or a valley); otherwise, the finite depth of the model
will influence the stress field near the surface. Analyses performed using two-dimensional models
indicate that to satisfy this criterion, the thickness of the model beneath the valleys should be
approximately three times the topographic amplitude.

Model B

Model A

Figure 3.22 Models used to transfer stress boundary conditions

3DEC Version 4.1
131

3 - 42

User’s Guide

Boundary locations for the detailed model are chosen using the conventional criterion that induced
stresses at the boundary location caused by internal changes (such as mining) should not be significant. An estimate of this distance can be obtained using the elastic solution for stress around a
t , at a distance
sphere in a hydrostatic stress field. The induced tangential component of stress, σind
R from a cavity of radius a in a hydrostatic stress field po is
t
σind
a3
=
po
2 R3

(3.10)

Because the decay of induced stress away from the excavation is more rapid than for a circular hole,
the two-dimensional equivalent boundaries around three-dimensional excavations do not have to
be particularly far. For example, at a distance of approximately 2a, the induced stress is only 5%
of the hydrostatic level, and only 1% at a distance of 3.7a. Solutions for other shaped openings can
also be used, depending on the actual excavation shape.
An important aspect of the point-wise boundary traction transfer to the smaller model is that a more
complex boundary stress distribution can be generated than by conventional linear variations. The
dimensions of boundaries in the detailed model can, therefore, be small relative to the surrounding
topographic relief. This would be impossible to achieve using standard linearly varying boundary
stress distributions.
An alternative to the stress transfer technique can be used when the entire model is not too big to
fit in memory, but runs too slowly to allow investigation of such things as strength variations or
extraction sequences. In this case, the COUPLE command may be used. The COUPLE command
allows the decoupling of an inner and outer region. After reaching internal equilibrium, the large
mass shown in Figure 3.22 (Model A) is defined as a single region (for example, region 1 – see the
MARK command).
The outer area can be removed from calculation cycles with the COUPLE 1 off command. From this
point, 3DEC does not include the blocks that lie in region 1 in the cycle calculations. The model
forces at the interface between region 1 and all other regions are held constant. Changes in the
inner model that affect the interface will not cause a change in the forces at the boundaries unless
an outer region is turned back on (COUPLE 1 on). The status of any region can be determined with
the LIST region command.

3DEC Version 4.1
132

PROBLEM SOLVING WITH 3DEC

3 - 43

3.5 Initial Conditions
In all civil or mining engineering projects, there is an in-situ state of stress in the ground, before any
excavation or construction is started. By setting initial conditions in the 3DEC model, an attempt is
made to reproduce this in-situ state, because it can influence the subsequent behavior of the model.
Ideally, information about the initial state comes from field measurements, but, when these are not
available, the model can be run for a range of possible conditions. Although the range is potentially
infinite, there are a number of constraining factors (e.g., the system must be in equilibrium, and the
chosen yield and slip criteria must not be violated anywhere).
In a uniform layer of soil or rock with a free surface, the vertical stresses are usually equal to gρz,
where g is the gravitational acceleration, ρ is the mass density of the material and z is the depth below
surface. However, the in-situ horizontal stresses are more difficult to estimate. There is a common
(but erroneous) belief that there is some “natural” ratio between horizontal and vertical stress, given
by ν/(1 − ν), where ν is the Poisson’s ratio. This formula is derived from the assumption that
gravity is suddenly applied to an elastic mass of material in which lateral movement is prevented.
This condition hardly ever applies in practice, due to repeated tectonic movements, material failure,
overburden removal and locked-in stresses due to faulting and localization (see Section 3.11.3). Of
course, if we had enough knowledge of the history of a particular volume of material, we might
simulate the whole process numerically, in order to arrive at the initial conditions for our planned
engineering works. This approach is not usually feasible. Typically, we compromise: a set of
stresses is installed in the model, and then 3DEC is run until an equilibrium state is obtained. It is
important to realize that there is an infinite number of equilibrium states for any given system.
In the following sections, we examine progressively more complicated situations, and the ways
in which the initial conditions may be specified. The user is encouraged to experiment with the
various data files that are presented.
3.5.1 Uniform Stresses in an Unjointed Medium: No Gravity
For an excavation deep underground, the gravitational variation of stress from top to bottom of the
excavation may be neglected because the variation is small in comparison with the magnitude of
stress acting on the volume of rock to be modeled. The GRAVITY command may be omitted, causing
the gravitational acceleration to default to zero. The initial stresses are installed with the INSITU
command — e.g.,
insitu stress -5e6 -5e6 -1e7 0.0 0.0 0.0

The components σ11 (or σxx ), σ22 (or σyy ) and σ33 (or σzz ) are set to compressive stresses of 5×106 ,
5 × 106 and 5 × 107 , respectively, throughout the model. Range parameters may be added if the
stresses are to be restricted to a subregion of the model. The INSITU command sets all stresses to
the given values, but there is no guarantee that the stresses will be in equilibrium. There are at least
three possible problems. First, the stresses may violate the yield criterion of a nonlinear constitutive
model assigned to deformable blocks. In this case, plastic flow of zones in the blocks will occur
immediately after the STEP command is given, and the stresses will readjust; this possibility should
be checked by doing one trial step and examining the response (e.g., PLOT plas). Second, the stress

3DEC Version 4.1
133

3 - 44

User’s Guide

state may result in slip or separation along joints within the model. The command PLOT vel should
indicate locations where joint movement is occurring. Third, the prescribed stresses at the model
boundary may not equal the given initial stresses. In this case, the boundary gridpoints will start
to move as soon as a STEP command is given; again, output should be checked (e.g., PLOT vel) for
this possibility.
The commands in Example 3.11 produce a single block with initial stresses that are in equilibrium
with prescribed boundary stresses:
Example 3.11 Initial and boundary stresses in equilibrium
new
poly brick 0,10 0,10 0,10
pl block
pl reset
gen edge 2.0
prop mat=1 dens 1000 bulk 8e9 g 5e9
bound stress -5e6,
0,
0 0,0,0 range x 0.0
bound stress -5e6,
0,
0 0,0,0 range x 10.0
bound stress
0,-5e6,
0 0,0,0 range y 0.0
bound stress
0,-5e6,
0 0,0,0 range y 10.0
bound stress
0,
0,-1e7 0,0,0 range z 0.0
bound stress
0,
0,-1e7 0,0,0 range z 10.0
insitu stress -5e6 -5e6 -1e7 0,0,0
step 1
plot block fill off stress colorby maximum
ret

3.5.2 Stresses with Gradients in an Unjointed Medium: Uniform Material
Variation in stress with depth cannot be ignored near the ground surface — the GRAVITY command
is used to inform 3DEC that gravitational acceleration operates on the model. It is important to
understand that the GRAVITY command does not directly cause stresses to appear in the model;
it simply causes body forces to act on all gridpoints of deformable blocks (or centroids of rigid
blocks). These body forces correspond to the weight of material surrounding each gridpoint. If
no initial stresses are present, the forces will cause the material to move (during stepping) in the
direction of the forces until equal and opposite forces are generated by zone stresses. Given the
appropriate boundary conditions (e.g., fixed bottom, roller side boundaries), the model will, in fact,
generate its own gravitational stresses compatible with the applied gravity. However, this process is
inefficient, since many hundreds of steps may be necessary for equilibrium. It is better to initialize
the internal stresses such that they satisfy both equilibrium and the gravitational gradient. The
INSITU command must include the xgrad, ygrad and zgrad parameters so that the stress gradient
matches the gravitational gradient, gρ. The internal stresses must also match boundary stresses at
stress boundaries.

3DEC Version 4.1
134

PROBLEM SOLVING WITH 3DEC

3 - 45

Even though the boundary and in-situ stresses are specified to produce a force balance, some cycling
of the model is normally required. This is because the boundary forces are only applied at the end
of a cycle; a small force imbalance is produced by the in-situ stresses. Usually, this imbalance is
reduced within a few hundred cycles.
Consider, for example, a 20 m × 20 m × 20 m box of homogeneous unjointed material at a depth
of 200 m underground, with fixed base and stress boundaries on the other five sides. Example 3.12
produces an equilibrium system for this problem condition:
Example 3.12 Initial stress state with gravitational gradient
new
poly brick 0,20 0,20 0,20
pl bl
pl reset
gen edge 4.0
prop mat=1 dens 2500 bulk 5e9 g 3e9 phi 35
change cons 2
gravity 0 0 -10
bound stress -2.75e6,-2.75e6,-5.5e6 0,0,0 &
zgrad
1.25e4, 1.25e4, 2.5e4 0,0,0 range x 0.0
bound stress -2.75e6,-2.75e6,-5.5e6 0,0,0 &
zgrad
1.25e4, 1.25e4, 2.5e4 0,0,0 range x 20.0
bound stress -2.75e6,-2.75e6,-5.5e6 0,0,0 &
zgrad
1.25e4, 1.25e4, 2.5e4 0,0,0 range y 0.0
bound stress -2.75e6,-2.75e6,-5.5e6 0,0,0 &
zgrad
1.25e4, 1.25e4, 2.5e4 0,0,0 range y 20.0
bound stress
0,
0,-5.0e6 0,0,0 range z 20.0
bound zvel = 0.0
range z 0.0
insitu stress -2.75e6,-2.75e6,-5.5e6 0,0,0 &
zgrad
1.25e4, 1.25e4, 2.5e4 0,0,0
step 500
plot block fill off stress colorby maximum reverse
ret

In this example, horizontal stresses and gradients are equal to half the vertical stresses and gradients,
but they may be set at any value that does not violate the yield criterion (Mohr-Coulomb, in this
case). After preparing a data file such as the one above, the model should be cycled to check that an
equilibrium state is reached. If material failure does occur (e.g., reduce phi = 10◦ ), this will show as
an unbalanced force magnitude that is roughly the same order of magnitude as the applied loading.

3DEC Version 4.1
135

3 - 46

User’s Guide

3.5.3 Stresses with Gradients in a Nonuniform Material
It is more difficult to give the initial stresses when materials of different densities are present.
Consider a layered system with a free surface, enclosed in a box with roller side boundaries and a
fixed base. Suppose that the material has the following density distribution:
1600 kg/m3 from 0 to 10 m depth
2000 kg/m3 from 10 to 15 m
2200 kg/m3 from 15 to 25 m
An equilibrium state is produced by the data file in Example 3.13.

Example 3.13 Initial stress gradient in a nonuniform material
new
poly brick 0,20 0,20 0,25
pl bl
pl reset
jset dip 0.0 origin 0,0,10
jset dip 0.0 origin 0,0,15
gen edge 2.0
change mat 1 range z 0,10
change mat 2 range z 10,15
change mat 3 range z 15,25
prop mat=1 dens 1600 bulk 5e9 g 3e9
prop mat=2 dens 2000 bulk 5e9 g 3e9
prop mat=3 dens 2200 bulk 5e9 g 3e9
change jmat 1
prop jmat 1 jkn 1e10 jks 1e10 coh 1e10
gravity 0 0 -10
insitu stress 0.0,0.0,-4.8e5 0,0,0 &
zgrad 0.0,0.0, 2.2e4 0,0,0 range z 0,10
insitu stress 0.0,0.0,-4.6e5 0,0,0 &
zgrad 0.0,0.0, 2.0e4 0,0,0 range z 10,15
insitu stress 0.0,0.0,-4.0e5 0,0,0 &
zgrad 0.0,0.0, 1.6e4 0,0,0 range z 15,25
bound xvel = 0.0 range x 0.0
bound xvel = 0.0 range x 20.0
bound yvel = 0.0 range y 0.0
bound yvel = 0.0 range y 20.0
bound zvel = 0.0 range z 0.0
hist unbal
step 500

3DEC Version 4.1
136

PROBLEM SOLVING WITH 3DEC

3 - 47

plot set dip 90 dd 180 cent 10,11,12.5
plot x bcont szz minimum -6e5 maximum 0 interval 1.25e5 wireframe off

An individual block is created for each material density; fictitious joints separate each block. The
internal stress profile is calculated manually for each block from the known overburden above it.
Note that the example is simplified: in a real case, the elastic moduli would vary, and there would
be horizontal stresses. If high horizontal stresses exist in a layer, these may also be installed with
the INSITU command.
This example is not in equilibrium at one calculation step; approximately 500 steps are required.
The presence of the fictitious joints also prevents the model from being in equilibrium when the
initial stresses match the boundary stresses. A jointed model will often require more steps to
equilibrate than an unjointed model.
3.5.4 Compaction within a Model with Nonuniform Zoning
Puzzling results are sometimes observed when a model with nonuniform zoning is allowed to come
to equilibrium under gravity. A model that is composed of deformable blocks of different sizes will
usually have nonuniform zoning. When a Mohr-Coulomb (or other nonlinear constitutive) model is
assigned to the blocks, the final stress state and displacement pattern are not uniform, even though
the boundaries are straight and the free surface is flat. The data file in Example 3.14 illustrates the
effect (see Figure 3.23 for the generated plot showing vertical stress contours):
Example 3.14 Nonuniform stress initialized in a model with nonuniform zoning
new
poly brick 0,10 0,2 0,10
plot block
plot reset
jset dip 90.0 dd 90 origin 3,0,0
hide dip 90.0 dd 90 origin 3,0,0 above
;gen edge .3
gen quad ndiv 1,5,10
seek
gen quad ndiv 1,2,10
;gen edge 1.0
change cons 2
prop mat=1 dens 2000 bulk 2e8 g 1e8 phi 30
prop jmat 1 jkn 1e8 jks 1e8 coh 1e10 ten 1e10
gravity 0 0 -10
bound xvel = 0.0 range x -0.1 0.1
bound xvel = 0.0 range x 9.9 10.1
bound yvel = 0.0 range y -0.1 0.1
bound yvel = 0.0 range y 1.9 2.1
bound zvel = 0.0 range z -0.1 0.1

3DEC Version 4.1
137

3 - 48

hist unbal
sav ex3_14.sav
step 500
plot bcont szz max 0 min -200000 int 20000
pause key
; optional method 1
restore ex3_14.sav
insitu stress -1.5e5 -1.5e5,-2.0e5, 0,0,0
zgrad
1.5e4 1.5e4, 2.0e4, 0,0,0
step 400
pause key
;
; optional method 2
restore ex3_14.sav
prop mat=1 bcoh 1e10 bten 1e10
step 750
prop mat=1 bcoh 0.0 bten 0.0
step 250
ret

3DEC Version 4.1
138

User’s Guide

&

PROBLEM SOLVING WITH 3DEC

3 - 49

Figure 3.23 Nonuniform stresses
Since we have roller boundaries on the four sides, we might expect the material to move down
equally on all sides. However, the zones are not the same size in the blocks. For static analysis,
3DEC tries to keep the timestep equal for all zones, so it increases the inertial mass for the gridpoints
of the smaller zones to compensate for their size. These gridpoints then accelerate more slowly
than those for the larger zones. This would have no effect on the final state of a linear material, but
it causes nonuniformity in a material that is path-dependent. For a Mohr-Coulomb material without
cohesion, the situation is similar to dropping sand from some height into a container and expecting
the final state to be uniform. In reality, a large amount of plastic flow would occur because the
confining stress does not build up immediately. Even with a uniformly zoned model, this approach
is not a good one because the horizontal stresses depend on the dynamics of the process.
The best solution is to use the INSITU stress command to set initial stresses to conform to the
desired Ko value (ratio of horizontal to vertical stress). For example, the STEP 1000 command in
the previous data file could be replaced by the following lines:
insitu stress (-1.5e5,-2.0e5,-1.5e5,0,0,0)
ygrad (1.5e4,2.0e4,1.5e4,0,0,0)
step 400

&

A stable state is achieved with Ko = 0.75; fewer steps are needed to reach equilibrium, and the
stress state is uniform (see Figure 3.24). Note that there is a slight nonuniformity, but this is related
to the contouring routine and the coarseness of the zoning.

3DEC Version 4.1
139

3 - 50

User’s Guide

Alternatively, the model can be run with an elastic behavior for the initial equilibrium calculation,
and then changed to the nonlinear behavior model for the final state. Replace the STEP 1000
command with the following lines:
prop
step
prop
step

mat=1 btens=1e10 bcoh=1e10
750
mat=1 btens=0 bcoh=0
250

The result is the same as that shown in Figure 3.24. The material is prevented from yielding during
the compaction process, but the original properties are restored when equilibrium is achieved.

Figure 3.24 Uniform stresses

3.5.5 Initial Stresses following a Model Change
There may be situations in which one material model for deformable blocks is used in the process
of reaching a desired stress distribution, but another model is used for the subsequent simulation.
Models can be changed for entire blocks (via the CHANGE command). If one model is replaced by
another non-null model, the stresses in the affected zones are preserved:

3DEC Version 4.1
140

PROBLEM SOLVING WITH 3DEC

3 - 51

Example 3.15 Initial stresses following a model change
new
poly brick 0,5 0,5 0,5
plot block colorby model
plot reset
gen edge 1.0
prop mat=1 dens 2000 bulk 3e8 g 2e8
gravity 0 0 -10
bound xvel = 0.0 zvel = 0.0 range z (-0.1,0.1)
hist unbal
step 250
pause key
change cons 2
prop mat=1 dens 2000 bulk 3e8 g 2e8 phi 34
ret

At this point in the run, the stresses generated by the initial elastic model still exist and act as initial
stresses for the region containing the new Mohr-Coulomb model.
Two points should be remembered. First, if a null block is created (via the EXCAVATE command)
in any part of the model (even if it is subsequently replaced by another non-null block), all stresses
are removed from the null block. Second, if one material model is replaced by another and the
stresses should physically be zero in the new model, then an INSITU command must be used to reset
the stresses to zero in this region. This situation would occur if rock is mined out and replaced by
backfill; the backfill should start its life without stress.
3.5.6 Stresses in a Jointed Medium
A spatial heterogeneity in an initial stress state can develop in a jointed and fractured medium. This
results from the stress path followed during the geologic history of the medium, and the physical
processes (related to fracturing and slip and separation along discontinuities) that may have occurred
at different stages in the history. Spatial heterogeneity of the stress state can be an important factor in
the design of underground excavations, particularly if the resulting stress concentrations adversely
influence the excavation stability.
It is very difficult to determine whether the stress state installed in a jointed model is representative
of the in-situ state of stress. As will be discussed in Section 3.11.2, statistical analyses may provide
a means to develop confidence in the model representation. One such study using UDEC is reported
by Brady et al. (1986).
There are certain modeling aspects that should be considered when bringing a jointed model to an
equilibrated state. First, the INSITU command should be invoked after all joints are generated in
the model. Then the normal and shear stresses along joints will be initialized, corresponding to the
initial stress values resolved along the plane of each joint.

3DEC Version 4.1
141

3 - 52

User’s Guide

As mentioned previously, a jointed model will not be in equilibrium initially, even when internal
stresses are set to match boundary stresses: some calculation steps are required, and the unbalanced
force should be monitored. In addition, histories of velocities or displacements should be recorded
at various locations in the model. These are good indicators of the calculation step at which motion
is negligible. The user should always ensure that motion in the model has essentially stopped for
the equilibrium stress state before beginning the next stage of an analysis.
It is possible that, for the specified initial stress state and joint strength properties, some joints will
slip or separate when the model is brought to an equilibrated state. Joint slip that is confined within
the model is acceptable; “locked-in” stresses at the joint ends will result. However, the user should
avoid conditions for which joint failure extends to the model boundary. This indicates that the
model conditions are not well-posed. It may be necessary to reevaluate the assigned stress state,
joint properties and joint orientations and locations. If conditions are such that joint failure still
extends to a boundary, then a fixed boundary condition should be considered. This implies that the
joint is truncated at the boundary.
The data file in Example 3.16 demonstrates the case of a joint dipping at 60◦ , confined between
two joints dipping at 20◦ . The 60◦ joint slips for the prescribed initial stress, while the 20◦ joints
do not. The friction angle for all joints is 30◦ .
Example 3.16 Slip of a confined joint
new
poly brick -10,10 -10,10 -20,0
plot block
plot reset
jset dip 60 dd 90 origin 0,0,-10
jset dip 20 dd 90 origin 0,0,-8
jset dip 20 dd 90 origin 0,0,-12
join on range z -20,-14
join on range z -7,0
gen edge 2.0
prop mat=1 dens 2000 bulk 8e9 g 5e9
prop jmat=1 jkn 5e11 jks 2.5e11 fric 30
insitu stress -2.5e6,-2.5e6,-1e7 0,0,0
bound stress -2.5e6
0
0 0 0 0 range x -10.0
bound stress -2.5e6
0
0 0 0 0 range x 10.0
bound stress
0 -2.5e6
0 0 0 0 range y -10.0
bound stress
0 -2.5e6
0 0 0 0 range y 10.0
bound stress
0
0 -1e7 0 0 0 range z
0.0
bound zvel
0.0
range z -20.0
hist unbal
hist zdis 0,0,-10
step 1000
plot clear
plot cut add plane origin (0,0,-10) name "Plane 1" normal (0,1,0)

3DEC Version 4.1
142

PROBLEM SOLVING WITH 3DEC

3 - 53

plot add jointvector shear shearoffset 0.1 plane on point size 0 &
arrowhead on arrowsize (30,30) arrowbody 70 arrowquality 30 &
plane onplane on frontplane off behindplane off
plot add blockcontour sxz fill on wireframe off
plot add joint colorby material clear addlabel "1" black line width 3
plot set orientation (90,180,0) center (0,0,-10)
ret

Figure 3.25 shows a block plot on which the region of joint slip is indicated by joint shear vectors.
Contours of σxz are also plotted and show the areas of locked-in stresses near the ends of the 60◦
joint.

Figure 3.25 Slip of a confined joint; plot shows shear stress contours

3.5.7 Determination of the In-situ Stress State
Knowledge of the virgin stress field is required in order to establish appropriate boundary and initial
conditions for models of underground excavations. However, often it is not possible to perform
in-situ stress measurements sufficiently far from underground excavations or topographic features
to determine virgin stresses. This is particularly true for mines using massive mining methods.
Boundary stresses may be approximated from regional stress compilations if available (e.g., Müller
et al., 1992; Lindner and Halpern 1978), but three-dimensional modeling can be used to quantify
the various forms of induced stress, such as those generated by topography, excavations or material

3DEC Version 4.1
143

3 - 54

User’s Guide

property variations. Subtracting the induced stress components from the total or measured stress
enables the virgin stress field to be computed. The latter method has the advantage of being able to
utilize stress measurements, which are known to include induced stresses from various sources (or
to check whether the measurements are free of induced stress). It also enables a computation of the
local stress field to be made, which is not necessarily represented by the regional stress field. The
following procedure has been used in three-dimensional stress analyses to estimate virgin stresses
from in-situ measurements that were influenced by various forms of induced stress.
The total stress field, σtot , at any point is the sum of virgin stress plus any induced stress components,
σind . Virgin stress, in turn, is composed of gravitational stress, σgrav , plus an as-yet-undetermined
additional horizontal component that will be referred to as a tectonic component, σtec . There
are various geological reasons for why this additional horizontal component of stress should be
incorporated into the total stress tensor. Eq. (3.11) relates these components:
σtot = σgrav + σtec + σind

(3.11)

The induced stress, in turn, is composed of gravitational and tectonic components:
σind = σ̄grav + σ̄tec

(3.12)

Substituting Eq. (3.12) into Eq. (3.11) produces
σtot = σgrav + σ̄grav + σtec + σ̄tec

(3.13)

which, upon regrouping, becomes
σtec + σ̄tec = σtot − (σgrav + σ̄grav )

(3.14)

Terms on the right-hand side of Eq. (3.14) are either known (stress measurements are representative
of the total stress field), or can be computed using a model with only gravitational loading.
To start the computation process, it should be assumed that the problem geometry (i.e., topography,
nearby excavations) is the primary factor generating the induced stress field, and that material
property variations produce only second-order effects. (Experience has shown this to be a reasonable
assumption.)
First, a model is constructed, taking into account the topography and excavation geometry. This
is run with gravitational loading only. The resulting stress field at the stress measurement points
accounts for gravity, plus the gravitational component of induced stress caused by the problem
geometry. The resultant calculated vertical stresses are compared to the corresponding measured
vertical stresses, and the measured stresses (all components) are adjusted to bring the measured
vertical stress into agreement with the calculated vertical stress. This latter step essentially scales
the measured stress to the model. If the computed and measured vertical components of stress are

3DEC Version 4.1
144

PROBLEM SOLVING WITH 3DEC

3 - 55

found to differ by a large amount, then either the model is incorrect (e.g., incorrect densities), there
are other unknown sources of induced stress (e.g., locked-in stresses from geological processes), or
there are significant errors in the measurements. In these situations, it is wise to investigate further,
to determine the reason for the stress anomaly, because confidence in the stress field is a critical
design requirement.
The unknown tectonic components can be solved by applying unit normal or shear stress boundary
conditions to the model, and computing the resultant stress level at the stress measurement point.
The correct “far-field” tectonic boundary stress is computed by scaling the unit stress results to
match the magnitudes of components obtained using Eq. (3.14). The total stress field is specified
by the combination of horizontal tectonic stresses applied at the boundary of the model, as well as
gravitational stresses.
3.5.8 Transferring Field Stresses to Model Stresses
A utility program, “TRANS.EXE,” is provided in the “\Tutorial\Solving” directory to transform
field stresses into a set of stress components referenced to the local problem axes defined for the
3DEC model. The orientation of the local (model) axes is defined by the dip and dip direction of
the local y-axis. The local z-axis lies in the vertical plane containing the y-axis dip vector, and the
x-axis lies in the horizontal plane. The program “TRANS.EXE” calculates local stress components
on the basis of the following input data:
field principal stress 1 (σ1 ): magnitude, dip and dip direction
field principal stress 2 (σ2 ): magnitude, dip and dip direction
field principal stress 3 (σ3 ): magnitude, dip and dip direction
local y-axis: dip and bearing
The user must ensure that the directions of σ1 , σ2 and σ3 are orthogonal.
“TRANS.EXE” computes, first, a set of stress components referenced to a left-handed set x, y, z of
global axes which are oriented x (north), y (vertical) and z (east). Then, the set of stress components
referenced to the model axes are calculated. The output stress components are recorded on a file
named “TRANS.REC.”
The following example illustrates the transformation of field stresses to boundary stresses for the
3DEC model. A tunnel ventilation raise is oriented with an axis dip of 84◦ and dip direction of
125◦ , as shown previously in Figure 3.12. The 3DEC model axes are oriented as shown in that
figure. The y-axis is directed down the raise, the z-axis lies in the vertical plane containing the raise
dip vector, and the x-axis lies in the horizontal plane, directed N35◦ E.
The field stresses for this problem are:
σ1 = 30 MPa directed 24◦ / 231◦ (dip / dip direction)
σ2 = 15 MPa directed 5◦ / 138◦ (dip / dip direction)

3DEC Version 4.1
145

3 - 56

User’s Guide

σ3 = 12 MPa directed 66◦ / 36◦ (dip / dip direction)
For a y-axis orientation of dip = 84◦ and dip direction = 125◦ , program “TRANS.EXE” computes
the following stress components relative to the local axis (in 3DEC, tensile stresses are considered
positive).

3DEC Version 4.1
146

PROBLEM SOLVING WITH 3DEC

3 - 57

Stress Data for 3DEC (left-handed axes)
Field Stress:
Principal Stress 1

Magnitude −30.0

Dip 24.0

Bearing 231.0

Principal Stress 2

Magnitude −15.0

Dip

Bearing 138.0

Principal Stress 3

Magnitude −12.0

Dip 66.0

5.0

Bearing

36.0

Stresses Relative to Global Axes (X (north), Y (vertical), Z (east)):
FXX −19.44

FYY −22.47

FZZ −15.09

−5.79

FYZ −5.17

FZX −4.38

FXY

Model z-Axis Orientation:
Dip 84.0

Bearing 125.0

Stresses Relative to Model Axes:
SXX −25.85
SXY

4.07

SYY −16.38
SYZ

1.59

SZZ −14.74
SXZ −6.16

This information is contained in “TRANS.REC.” The boundary stresses applied to the model are
then:
σxx = −25.8 MPa, σyy = −16.38 MPa, σzz = −14.74 MPa
σxy = 4.07 MPa, σyz = 1.59 MPa, σzx = −6.16 MPa
3.5.9 Topographical Stresses
The command INSITU topograph automatically calculates gravity loading in models that have an
irregular top surface. The stresses are calculated based on the density of the overlying materials
and specify Ko values.

3DEC Version 4.1
147

3 - 58

User’s Guide

3.6 Loading and Sequential Modeling
By applying different model loading conditions at different stages of an analysis, it is possible to
simulate changes in physical loading, such as sequences of excavation and construction. Changes
in loading may be specified in a number of ways (e.g., by applying new stress or displacement
boundaries, by changing the material model in blocks to either a null material or to a different
material model, or by changing material properties).
It is important to recognize that sequential modeling follows the stages of an engineering work.
In most analyses, each work stage corresponds to a different static solution following a loading
change (i.e., physical time is not a parameter). 3DEC can perform calculations for heat transfer
and dynamic mechanical analysis as well (see Sections 1 and 2 in Optional Features). In these
cases, a static solution for an equilibrium stress state may be followed, for example, by a dynamic
calculation for an applied explosive excitation or a transient calculation for flow through joints.
Time-dependent behavior, on the other hand, cannot be simulated directly. Some engineering
judgment must be used to estimate the effects of time. For example, a model parameter may be
changed after a pre-determined amount of displacement or strain has occurred. This displacement
may be estimated to have occurred over a given period of time.
A loading change must cause unbalanced forces to develop in order to effect a change in model
response. Therefore, changing the elastic properties will have no effect; changing strength properties
will, if the change causes the current stress state to exceed the failure limit.
The recommended approach to sequential modeling is demonstrated by the following example. This
problem involves the stability analysis of an underground opening in jointed rock, and includes the
evaluation of different types of support measures. The stages to be analyzed are:
(1) equilibration at the in-situ stress state;
(2) excavation of the tunnel; and
(3) application of the tunnel support.
The objective is to investigate the stability of the excavation under in-situ conditions, and assess
the effect of the support measures. Three types of support are evaluated: local reinforcement rock
bolts, cable bolts and a continuous concrete liner. Note that this model is greatly simplified for
rapid execution, but it still illustrates the recommended steps for loading and sequential modeling.
The tunnel is located in rock containing three major faults: one dipping at 65◦ with a dip direction
of 40◦ ; the second dipping at 70◦ with a dip direction of 270◦ ; and the third dipping at 60◦ with a
dip direction of 130◦ . The tunnel is horseshoe-shaped and is centered along the y-axis of the model.
The tunnel is created with the TUNNEL command. A second TUNNEL command is also used to define
the location of the concrete liner. Note that this must be done before any cycling is performed. The
model is created with the following series of commands, beginning with Example 3.17:

3DEC Version 4.1
148

PROBLEM SOLVING WITH 3DEC

3 - 59

Example 3.17 Stability analysis of an underground excavation — initial model
new
poly brick -10 10 -10 10 -10 10
pl bl
pl reset
; --- tunz: FISH function to define tunnel geometry parameters -------; ... tunnel along Y axis, from YYA to YYB
; ... semi-circular roof, centered at (TXC,TZC)
;
def tunz
;
yya = -10.0
yyb = 10.0
;
; --- outer surface --txb1 = -4.0
tzb1 = -4.0
txb2 = 4.0
tzb2 = -4.0
;
txc = 0.0
tzc = 0.0
tr = 4.0
tx1 = txc + tr * cos(180*degrad)
tz1 = tzc + tr * sin(180*degrad)
tx2 = txc + tr * cos(135*degrad)
tz2 = tzc + tr * sin(135*degrad)
tx3 = txc + tr * cos(90*degrad)
tz3 = tzc + tr * sin(90*degrad)
tx4 = txc + tr * cos(45*degrad)
tz4 = tzc + tr * sin(45*degrad)
tx5 = txc + tr * cos(0*degrad)
tz5 = tzc + tr * sin(0*degrad)
;
; --- inner surface --; thickness th
th = 0.5
txb1i = -4.0 + th
tzb1i = -4.0 + th
txb2i = 4.0 - th
tzb2i = -4.0 + th
;
txc = 0.0
tzc = 0.0

3DEC Version 4.1
149

3 - 60

User’s Guide

tri = tr tx1i = txc
tz1i = tzc
tx2i = txc
tz2i = tzc
tx3i = txc
tz3i = tzc
tx4i = txc
tz4i = tzc
tx5i = txc
tz5i = tzc

th
+ tri
+ tri
+ tri
+ tri
+ tri
+ tri
+ tri
+ tri
+ tri
+ tri

*
*
*
*
*
*
*
*
*
*

cos(180*degrad)
sin(180*degrad)
cos(135*degrad)
sin(135*degrad)
cos(90*degrad)
sin(90*degrad)
cos(45*degrad)
sin(45*degrad)
cos(0*degrad)
sin(0*degrad)

;
end
;
; --------------------------------------------------------------------; (execute function)
@tunz
;
; create outer surface
tunnel radial &
a @txb1,@yya,@tzb1
@tx1,@yya,@tz1 &
@tx2 ,@yya,@tz2
@tx3,@yya,@tz3 &
@tx4 ,@yya,@tz4
@tx5,@yya,@tz5 @txb2,@yya,@tzb2 &
b @txb1,@yyb,@tzb1
@tx1,@yyb,@tz1 &
@tx2 ,@yyb,@tz2
@tx3,@yyb,@tz3 &
@tx4 ,@yyb,@tz4
@tx5,@yyb,@tz5 @txb2,@yyb,@tzb2 &
reg 5
hide reg 0
;
; create inner surface
tunnel radial &
a @txb1i,@yya,@tzb1i @tx1i,@yya,@tz1i &
@tx2i ,@yya ,@tz2i @tx3i,@yya,@tz3i &
@tx4i ,@yya ,@tz4i @tx5i,@yya,@tz5i @txb2i,@yya,@tzb2i &
b @txb1i,@yyb,@tzb1i @tx1i,@yyb,@tz1i &
@tx2i ,@yyb ,@tz2i @tx3i,@yyb,@tz3i &
@tx4i ,@yyb ,@tz4i @tx5i,@yyb,@tz5i @txb2i,@yyb,@tzb2i &
reg 7
seek
;
; --- NOTE: region inside inner surface is REG 7
;
region between surface (to be liner) is REG 5
;
save tun_a.sav
;
; --- joints --- 3 joints to form a wedge in the roof

3DEC Version 4.1
150

PROBLEM SOLVING WITH 3DEC

;
jset dd 270 dip 70 origin 0 0,5.7
jset dd 40 dip 65 origin 0 0,5.7
jset dd 130 dip 60 origin 0 0,5.7
;
save tun_b.sav
;
; --- mesh generation --; rock blocks
hide reg 5 7
gen edge 5
;
; liner
find reg 5
gen edge 2
;
find reg 7
gen edge 2
;
save tun_z.sav
plot block colorby mat
plot set dip 70 dd 210
ret

3 - 61

id 10
id 10
id 10

Figure 3.26 shows the resulting model configuration. The tunnel geometry parameters are defined
in the FISH function tunz. The inner region of the tunnel is assigned region number 7, and the
region corresponding to the liner is assigned region number 5. Note that the tunnel is created first,
and then the physical joint set is generated. Blocks are joined automatically with the TUNNEL
commands. Zone generation is performed separately for the rock blocks, the liner blocks and the
interior region of the tunnel.

3DEC Version 4.1
151

3 - 62

User’s Guide

Figure 3.26 3DEC model of tunnel region
Material properties are assigned to the rock blocks (mat 1), the concrete liner blocks (mat 5), the
rock joints (jmat 1), the concrete-concrete joints (jmat 5) and the concrete-rock interface (jmat 6).
The in-situ stress state and boundary conditions are applied, assuming the tunnel is at a depth of
200 m and the ratio of horizontal to vertical stress is 0.5. Note that for a practical simulation, the
boundaries are too close to the tunnel excavation and should be moved to a greater distance to
minimize their influence on the model results (see Section 3.4.4.2).
The commands to assign material properties and achieve the initial stress state are listed in Example 3.18:
Example 3.18 Stability analysis of an underground excavation — initial equilibrium stress
state
rest tun_z.sav
;
; --- properties --;
; --- MAT 1 : rock --; density = 2700 kg/m3 = 0.0027e6 kg/m3
; E=50 GPa, Poisson’s ratio=0.2
prop mat 1 dens 0.0027 k 27778 g 20833
;
; --- MAT=5 : concrete liner ---

3DEC Version 4.1
152

PROBLEM SOLVING WITH 3DEC

3 - 63

; density = 2400 kg/m3 = 0.0024e6 kg/m3
; E=30 GPa, Poisson’s ratio=0.2
prop mat 5 dens 0.0025 k 16667 g 12500
;
; --- JMAT=1 : rock joints --prop mat 1 jkn 10000 jks 2000 fric 25
;
; --- JMAT=5 : concrete-concrete joints (elastic) --prop mat 5 jkn 30000 jks 12000 coh 1e6 tens 1e6
;
; --- JMAT=6 : concrete-rock interface --prop mat 6 jkn 10000 jks 2000 fric 0.001
;
; --- assign material numbers --; initially all materials are rock
change mat 1
change jmat 1
;
; --- insitu stress state --; assume tunnel at 200 m depth
; vertical stress: syy=(0.0027*g)*(y-200)
;
at z=0: szz=-5.4
;
z-gradient of szz: 0.027
;
(positive: less compression going up)
; horizontal sxx=szz=0.5*syy
;
insitu stress -2.7 -2.7 -5.4 0 0 0
&
zgrad 0.0135 0.0135 0.027 0 0 0
;
; gravity
grav 0 0 -10
;
; --- boundary conditions for insitu stress state --; top of model (z=10): szz=-0.027*190=-5.13
bound stress 0 0 -5.13 0 0 0 range z 10.0
; bottom
bound zvel 0 range z -10.0
; sides
bound xvel 0 range x -10.0
bound xvel 0 range x 10.0
bound yvel 0 range y -10.0
bound yvel 0 range y 10.0
;
; --- histories to monitor convergence --hist nc=1 unbal
; top of model

3DEC Version 4.1
153

3 - 64

User’s Guide

hist xdis 0 0 10 ydis 0 0 10 zdis 0 0 10
;
save tun_c0.sav
plot hist 2 3 4 yaxis label ’Displacement’
cycle 1000
save tun_c.sav
ret

The maximum unbalanced force in the model and displacements at the top boundary are monitored
to help make sure that an initial equilibrium stress state is reached within 1000 cycles. Figure 3.27
shows the x-, y- and z-displacement histories for the gridpoint (x = 0, y = 0, z = 10) at the top of
the model:

Figure 3.27 Displacement histories at top of model
If the tunnel is excavated without support, a rock wedge detaches and falls from the roof. This
is shown by running Example 3.19; the tunnel is excavated with the DELETE command, and the
z-displacement at a location in the roof is monitored while the model is cycled. Figure 3.29 plots
the z-displacement history and indicates that the position is moving downward. Figure 3.28 shows
a close-up view of the detached wedge, with surrounding blocks hidden for better viewing.
Example 3.19 Stability analysis of an underground excavation — unsupported tunnel
rest tun_c.sav

3DEC Version 4.1
154

PROBLEM SOLVING WITH 3DEC

3 - 65

pl block
pl reset
; delete interior blocks
remove reg 5 7
pause key
;
; history point at tunnel roof
reset disp time hist
hide
seek range xr .44 .46
hist zdis 1.8 0 3.72
hist label 1 ’Vertical Displacement’
seek
;
pl hist 1 yaxis label ’Displacement’
cycle 5000
;
save tun_x.sav
pause key
hide dip 60 dd 130 or 0 0 5.7 above
pl block velocity line color cyan
plot set dip 80 dd 180 mag 3
ret

Figure 3.28 z-displacement history at tunnel roof

3DEC Version 4.1
155

3 - 66

User’s Guide

Figure 3.29 Close-up view of wedge in roof (surrounding blocks hidden)
The effect of rock bolt support is evaluated first for local reinforcement elements (STRUCT axial), and
then for fully bonded cable elements (STRUCT cable). See Section 4 in Theory and Background
for a detailed description of these two types of structural support.
Example 3.20 lists the commands to excavate the tunnel and install the local reinforcement elements,
and Example 3.21 lists those for cable element support. Note that we use the REMOVE command
to excavate the tunnel this time. This has the same effect as the DELETE command, but now we
can view the excavated region with the PLOT exc command. The reinforcement elements and cable
elements are positioned in the same locations in the side walls and roof of the tunnel. Figure 3.30
shows the location of the cable elements around the tunnel excavation.

3DEC Version 4.1
156

PROBLEM SOLVING WITH 3DEC

3 - 67

Figure 3.30 Cable bolts positioned around tunnel excavation

Example 3.20 Stability analysis of an underground excavation — local reinforcement support
rest tun_c.sav
;
; delete interior blocks
remove region 7
;
; delete liner blocks
remove reg 5
;
; --- install axial elements --struct axial -8 -5 -2 -3.9 -5 -2 prop 7
struct axial -8 0 -2 -3.9 0 -2 prop 7
struct axial -8 5 -2 -3.9 5 -2 prop 7
struct axial -6.8 -5 6.8 -2.8 -5 2.8 prop 7
struct axial -6.8 0 6.8 -2.8 0 2.8 prop 7
struct axial -6.8 5 6.8 -2.8 5 2.8 prop 7
;
struct axial 8 -5 -2 3.9 -5 -2 prop 7
struct axial 8 0 -2 3.9 0 -2 prop 7
struct axial 8 5 -2 3.9 5 -2 prop 7
struct axial 6.8 -5 6.8 2.8 -5 2.8 prop 7

3DEC Version 4.1
157

3 - 68

User’s Guide

struct axial 6.8 0 6.8 2.8 0 2.8 prop 7
struct axial 6.8 5 6.8 2.8 5 2.8 prop 7
;
struct axial 0 -5 4
0 -5 8 prop 7
struct axial 0 0 4
0 0 8 prop 7
struct axial 0 5 4
0 5 8 prop 7
;
struct prop 7 rkax 250 rlen 0.10 rult 0.55
;
reset disp time hist
; history point at tunnel roof
hide
seek range xr .44 .46
hist zdis 1.8 0 3.72
hist label 1 ’Vertical Displacement’
seek
;
pl hist 1 yaxis label ’Displacement’
cy 2000
;
save tun_lr.sav
ret

Example 3.21 Stability analysis of an underground excavation — fully grouted cable support
rest tun_c.sav
;
; delete interior blocks
plot block
remove region 7
;
; delete liner blocks
remove reg 5
;
; --- install cable elements --struct cable -8 -5 -2
-4.05 -5 -2 prop 8 seg 4
struct cable -8 0 -2
-4.05 0 -2 prop 8 seg 4
struct cable -8 5 -2
-4.05 5 -2 prop 8 seg 4
struct cable -6.8 -5 6.8
-2.85 -5 2.85 prop 8 seg 4
struct cable -6.8 0 6.8
-2.85 0 2.85 prop 8 seg 4
struct cable -6.8 5 6.8
-2.85 5 2.85 prop 8 seg 4
;
struct cable 8 -5 -2
4.05 -5 -2 prop 8 seg 4
struct cable 8 0 -2
4.05 0 -2 prop 8 seg 4
struct cable 8 5 -2
4.05 5 -2 prop 8 seg 4

3DEC Version 4.1
158

PROBLEM SOLVING WITH 3DEC

struct cable 6.8 -5 6.8
2.85 -5 2.85 prop 8
struct cable 6.8 0 6.8
2.85 0 2.85 prop 8
struct cable 6.8 5 6.8
2.85 5 2.85 prop 8
;
struct cable 0 -5 4.1
0 -5 8 prop 8 seg 4
struct cable 0 0 4.1
0 0 8 prop 8 seg 4
struct cable 0 5 4.1
0 5 8 prop 8 seg 4
;
; start with high SBOND
struct prop 8 area 5e-4 e 100000 yield 0.55 kbond
;
reset disp time hist
; history point at tunnel roof
hide
seek range xr .44 .46
hist zdis 1.8 0 3.72
hist label 1 ’Vertical Displacement’
seek
;
cycle 500
;
; set real SBOND
struct prop 8 sbond 0.8
;
pl hist 1 yaxis label ’Displacement’
cy 1500
;
save tun_cab.sav
pause key
pl exc colorby material cable
pl set dip 80 dd 190
ret

3 - 69

seg 4
seg 4
seg 4

15e4 sbond 1e6

The roof is stabilized for both types of reinforcement. The z-displacement history now indicates
that the wedge movement stops at roughly 25 mm displacement for both the reinforcement elements
and the cable elements (see Figures 3.31 and 3.32).

3DEC Version 4.1
159

3 - 70

User’s Guide

Figure 3.31 z-displacement history at tunnel roof — reinforcement element
support

Figure 3.32 z-displacement history at tunnel roof — cable support

3DEC Version 4.1
160

PROBLEM SOLVING WITH 3DEC

3 - 71

The axial forces that develop in the support are greatest in the roof elements. This is shown for
both the reinforcement elements and the cable elements by the axial force plots in Figures 3.33 and
3.34:

Figure 3.33 Axial forces in reinforcement elements

Figure 3.34 Axial forces in cable elements

3DEC Version 4.1
161

3 - 72

User’s Guide

The model of a tunnel excavation and support sequence should simulate the change in stresses
around the tunnel as the excavation advances, before the tunnel support is installed. This can
be done in a 3DEC model by excavating the tunnel in sections and installing support after each
excavation section. This is the recommended approach to simulate support loading changes due to
tunnel advancement.
Alternatively, in this simplified model we simulate the effect of tunnel advancement by reducing
the tractions at the tunnel periphery in increments, and installing the liner before the tractions are
completely removed. This demonstrates an approach for simulating a gradual excavation of a tunnel
section. Example 3.22 shows the data file for this approach:
Example 3.22 Stability analysis of an underground excavation — reduce tunnel tractions by
50% and install liner
rest tun_c.sav
plot block
plot set dip 80 dd 200
; delete interior blocks
delete region 7
;
; excavate liner blocks (not deleted)
excavate reg 5
;
; history point at tunnel roof
hide
seek range xr .44 .46
hist xdis 1.8 0 3.72 ydis 1.8 0 3.72 zdis 1.8 0 3.72
hist label 7 ’Vertical Displacement’
seek
;
; simulate the removal of approximately 50% of insitu stress
; applying at liner-rock interface a stress state
; szz=-2.7 sxx=syy=-1.35
;
bound str -1.35 -1.35 -2.7 0 0 0 range x -4.1,-3.9 y -11 11 z -4.1 0.1
bound str -1.35 -1.35 -2.7 0 0 0 range x 3.9,4.1 y -11 11 z -4.1 0.1
bound str -1.35 -1.35 -2.7 0 0 0 range x -4.1,4.1 y -11 11 z -4.1 -3.9
; note: need to include all faces on tunnel surface
;
(inner radius must be a bit smaller than 4.0)
bound str -1.35 -1.35 -2.7 0 0 0 &
range zr -0.1,4.1 cyl end1 0,-11,0 end2 0,11,0 rad 3.5,4.1
;
; must fix again end-surfaces that were freed by BOU STRESS
bou yvel 0 range yr -10.1,-9.9
bou yvel 0 range yr 9.9,10.1
;

3DEC Version 4.1
162

PROBLEM SOLVING WITH 3DEC

; check that sum of applied forces on tunnel surface
list boun force range x -5,5 y -11,11 z -5,5
; check that sum of applied x and z forces on tunnel
pause
;
cycle 2000
;
save tun_l1.sav
;
; --- insert liner --; remove loads from tunnel surface
;
bound xfree yfree zfree range x -4.1,-3.9 y -11,11 z
bound xfree yfree zfree range x 3.9,4.1 y -11,11 z
bound xfree yfree zfree range x -4.1,4.1 y -11,11 z
bound xfree yfree zfree range zr -0.1,4.1 &
cyl end1 0,-11,0 end2 0,11,0 rad 3.5,4.1
;
; must fix again end-surfaces
bou yvel 0 range yr -10.1 -9.9
bou yvel 0 range yr 9.9 10.1
;
; insert liner
fill mat 5 jmat 5 range reg 5
;
; join liner blocks
join on range reg 5
;
; assign rock-liner interface material
change jmat 6 range rint 0 5
;
pl hist 7 yaxis label ’Displacement’
cy 2000
;
save tun_l2.sav
pause key
hide
seek reg 5
pl block
plot set dip 80 dd 200
ret

3 - 73

is zero
surface is near zero

-4.1,0.1
-4.1,0.1
-4.1,-3.9

The BOUND command is used to apply 50% of the in-situ stress state to the liner-rock interface, and
the BOUND range covers all faces on the tunnel surface. The applied stresses at the tunnel surface
should produce traction forces on the surface that sum to zero; this can be checked with the LIST
bound force command. The model is cycled to an equilibrium state with tunnel tractions reduced

3DEC Version 4.1
163

3 - 74

User’s Guide

by 50%. Then, the tractions are removed completely and the liner is installed (with the FILL region
command). Figure 3.35 shows the liner blocks created for this model. The model is cycled to a
new equilibrium state. The load that develops in the liner is due to the reduction of the tractions
from 50% to zero.
Note that the selection of a 50% reduction in tunnel tractions in this example is arbitrary and only
for demonstration purposes. If it is necessary to simulate a gradual excavation, it may be necessary
to reduce the tractions in smaller increments to minimize the effects of transient stress waves on
the response of the model.

Figure 3.35 Thick concrete liner support — liner blocks
The displacement of the roof is monitored in Figure 3.36. Roughly 1 mm of vertical displacement
occurs when the tractions are reduced by 50%, and an additional 1 mm displacement after the tunnel
tractions are completely removed and the liner is installed.

3DEC Version 4.1
164

PROBLEM SOLVING WITH 3DEC

3 - 75

Figure 3.36 z-displacement history at tunnel roof — tunnel liner added after
tractions reduced by 50%
If a more representative model of the liner behavior (including an elastic-plastic response) is required, then mixed-discretization zoning (see Section 3.3.2) should be used to define the liner with
a minimum of five m-d zones across the liner thickness. The POLY prism command can be used to
create liner blocks for the m-d zones. Example 3.23 presents a data file to create the liner with m-d
zoning:
Example 3.23 Stability analysis of an underground excavation — liner with m-d zoning
rest tun_c0.sav
; delete interior blocks
delete range reg 5 7
; --------------------------------------------------------------------; --- insert support with POLY prism commands --;
poly prism a @txb1 @yya @tzb1
@tx1
@yya @tz1
&
@tx1i @yya @tz1i
@txb1i @yya @tzb1i &
b @txb1 @yyb @tzb1
@tx1
@yyb @tz1
&
@tx1i @yyb @tz1i
@txb1i @yyb @tzb1i &
reg 8
;
poly prism a @tx1 @yya @tz1
@tx2 @yya @tz2 &
@tx2i @yya @tz2i
@tx1i @yya @tz1i &

3DEC Version 4.1
165

3 - 76

User’s Guide

b @tx1 @yyb @tz1
@tx2i @yyb @tz2i
reg 8
;
poly prism a @tx2 @yya @tz2
@tx3i @yya @tz3i
b @tx2 @yyb @tz2
@tx3i @yyb @tz3i
reg 8
;
poly prism a @tx3 @yya @tz3
@tx4i @yya @tz4i
b @tx3 @yyb @tz3
@tx4i @yyb @tz4i
reg 8
;
poly prism a @tx4 @yya @tz4
@tx5i @yya @tz5i
b @tx4 @yyb @tz4
@tx5i @yyb @tz5i
reg 8
;
poly prism a @tx5
@yya @tz5
@txb2i @yya @tzb2i
b @tx5
@yyb @tz5
@txb2i @yyb @tzb2i
reg 8
;
poly prism a @txb2 @yya @tzb2
@txb1i @yya @tzb1i
b @txb2 @yyb @tzb2
@txb1i @yyb @tzb1i
reg 8
;
hide
seek reg 8
plot block
plot set dip 80 dd 200
pause key
gen quad ndiv 5 10 5 rmul 1.0
plot block fill off
pause key
;
change mat 5 range reg 8
change jmat 5 range rint 8 8
change jmat 6 range rint 0 8

3DEC Version 4.1
166

@tx2 @yyb @tz2 &
@tx1i @yyb @tz1i &

@tx3
@tx2i
@tx3
@tx2i

@yya
@yya
@yyb
@yyb

@tz3
@tz2i
@tz3
@tz2i

&
&
&
&

@tx4
@tx3i
@tx4
@tx3i

@yya
@yya
@yyb
@yyb

@tz4
@tz3i
@tz4
@tz3i

&
&
&
&

@tx5
@tx4i
@tx5
@tx4i

@yya
@yya
@yyb
@yyb

@tz5
@tz4i
@tz5
@tz4i

&
&
&
&

@txb2
@tx5i
@txb2
@tx5i

@txb1
@txb2i
@txb1
@txb2i

@yya
@yya
@yyb
@yyb

@tzb2
@tz5i
@tzb2
@tz5i

@yya
@yya
@yyb
@yyb

&
&
&
&

@tzb1
@tzb2i
@tzb1
@tzb2i

&
&
&
&

PROBLEM SOLVING WITH 3DEC

3 - 77

;
; --- MAT=5 : concrete liner --; density = 2400 kg/m3 = 0.0024e6 kg/m3
; E=30 GPa, Poisson’s ratio=0.2
prop mat 5 dens 0.0025 k 16667 g 12500
;
; --- JMAT=5 : concrete-concrete joints (elastic) --prop mat 5 jkn 30000 jks 12000 coh 1e6 tens 1e6
;
; --- JMAT=6 : concrete-rock interface --prop mat 6 jkn 10000 jks 2000 fric 35
;
; --------------------------------------------------------------------;
; history point at tunnel roof
reset disp time hist
hide
seek range xr .44 .46
hist zdis 1.8 0 3.72
hist label 1 ’Vertical Displacement’
seek
;
pl hist 1 yaxis label ’Displacement’
cycle 2000
pause key
;
save tun_lin3.sav
ret

Note that the prism-shaped blocks must be created before cycling is initiated. In this example, we
delete the blocks in region 5, and insert prism-shaped blocks for the liner (defined now as region
8). The m-d zoning is created with the GEN quad command, and only elastic behavior is assigned
to the liner material. If we wish to evaluate the elastic-plastic response, the bilinear material model
(CHANGE cons 6 with the ubiquitous joint behavior suppressed) can be assigned to the liner material.
The liner supports the entire load in this example. (We could also reduce the tractions as before,
in Example 3.22.) Figure 3.37 illustrates the liner blocks for this case, and Figure 3.38 shows the
m-d zoning within the liner.

3DEC Version 4.1
167

3 - 78

User’s Guide

Figure 3.37 Thick concrete liner support — prism-shaped liner blocks

Figure 3.38 Thick concrete liner support — mixed-discretization zoning in
liner blocks

3DEC Version 4.1
168

PROBLEM SOLVING WITH 3DEC

3 - 79

Figure 3.39 shows the plot of the z-displacement in the roof for this case. Approximately 1.6 mm
displacement occurs when the liner supports the tunnel. The stresses in the liner are plotted in
Figure 3.40.

Figure 3.39 z-displacement history at tunnel roof — support by prism-shaped
liner blocks

Figure 3.40 Principal stress distribution in top section of liner

3DEC Version 4.1
169

3 - 80

User’s Guide

3.7 Choice of Constitutive Model
This section provides an overview of the block and joint constitutive models in 3DEC, as well
as recommendations concerning when to use a model. Section 2 in Theory and Background
presents background information on the block constitutive model formulations. Also see userdefined models and extended material models in Optional Features. The joint models are described
in Sections 1.2.2.3 and 3 in Theory and Background.
3.7.1 Deformable-Block Material Models
There are five built-in block material models in 3DEC:
(1) null (EXCAVATE command);
(2) elastic, isotropic (CHANGE cons = 1);
(3) elastic, anisotropic (CHANGE cons = 3);
(4) Mohr-Coulomb plasticity (CHANGE cons = 2); and
(5) bilinear strain-hardening/softening, ubiquitous joint (CHANGE cons = 6).
Note that the null model is assigned with the EXCAVATE command. The other four models are
assigned with the CHANGE cons command. Model properties are then specified for the non-null
models with the PROPERTY mat command for material property numbers, and the property numbers
are assigned to the blocks with the CHANGE mat command.
Each block model is designed to represent a specific type of constitutive behavior commonly
associated with geologic materials. The null model is used to represent material that is removed
from the model. The elastic, isotropic model is valid for homogeneous, isotropic, continuous
materials which exhibit linear stress-strain behavior. The elastic, anisotropic model is appropriate
for elastic materials that exhibit a well-defined elastic anisotropy. The Mohr-Coulomb plasticity
model is used for materials that yield when subjected to shear loading. But the yield stress depends
on the major and minor principal stresses only; the intermediate principal stress has no effect on
yield. The bilinear strain-softening, ubiquitous joint model combines a strain-softening MohrCoulomb model for the matrix material with a strain-softening ubiquitous joint model to represent
a well-defined strength anisotropy. This model includes a bilinear failure envelope for both the
matrix and the ubiquitous joints.
The material models in 3DEC are primarily intended for applications related to geotechnical engineering (e.g., underground construction, mining, slope stability, foundations, earth and rock-fill
dams). When selecting a constitutive model for a particular engineering analysis, the following two
considerations should be kept in mind:
1. What are the known characteristics of the material being modeled?
2. What is the intended application of the model analysis?

3DEC Version 4.1
170

PROBLEM SOLVING WITH 3DEC

3 - 81

Table 3.2 presents a summary of the 3DEC block models, along with examples of representative
materials and possible applications of the models. The elastic block model is generally applicable
for cases in which slip along discontinuities is the predominant mechanism for failure. The MohrCoulomb model should be used when stress levels are such that failure of intact material is expected.
Mohr-Coulomb parameters for cohesion and friction angle are usually available more often than
other properties for geo-engineering materials.

Table 3.2

3DEC block constitutive models

Model

Representative Material

Example Application

null

void

holes, excavations, regions in which
material will be added at later stage

elastic

homogeneous, isotropic continuum;
linear stress-strain behavior

manufactured materials (e.g., steel)
loaded below strength limit; factor-ofsafety calculation

Drucker-Prager
plasticity

limited application; soft clays with low
friction

common model for comparison to
implicit finite-element programs

Mohr-Coulomb
plasticity

loose and cemented granular materials;
soils, rock, concrete

general soil or rock mechanics (e.g.,
slope stability and underground
excavation)

strain-hardening /
softening MohrCoulomb with
ubiquitous-joint

granular materials that exhibit
nonlinear material hardening or
softening and/or thinly laminated
material exhibiting strength anisotropy
(e.g., slate)

studies in post-failure (e.g., progressive
collapse, yielding pillar, caving) and
excavation in closely bedded strata

The bilinear strain-softening, ubiquitous-joint model is actually a variation of the Mohr-Coulomb
model. This model will produce results for shear failure identical to those for Mohr-Coulomb if
the additional material parameters are set to high values.
The only difference between the Mohr-Coulomb model and the bilinear model is the tensile failure
criterion:
In the Mohr-Coulomb model, a tension cutoff is specified. When any principal stress
component in a zone exceeds the tension cutoff, all principal stress components in the
zone are set to zero.
In the bilinear model, tensile failure is defined by a tensile strength limit, and postfailure is governed by an associated plasticity flow rule. The value assigned for the
tensile strength remains constant when tensile failure occurs. Tensile softening can be
controlled with the strain-hardening/softening component of the bilinear model.

3DEC Version 4.1
171

3 - 82

User’s Guide

By default, the tensile strength is zero in both the Mohr-Coulomb and bilinear models. A comparison
of the two tensile failure conditions is given in Example 3.25.
The Mohr-Coulomb model is more computationally efficient than the bilinear model: the bilinear
model requires increased memory and additional time for calculation. For example, plastic strain is
not calculated directly in the Mohr-Coulomb model. If plastic strain is required, the bilinear model
must be used. This model is primarily intended for applications in which the post-failure response
is important (e.g., yielding pillars, caving or backfilling studies).
3.7.2 Joint Material Models
There are two built-in models available to represent the material behavior of discontinuities:
(1) joint area contact — Coulomb slip (CHANGE jcons = 1); and
(2) continuously yielding (CHANGE jcons = 3).
The joint models are assigned to one or more contacts by using the CHANGE jcons command.
Joint model properties are then specified with the PROPERTY jmat command for material property
numbers, and the property numbers are assigned to the contacts with the CHANGE jmat command.
The joint constitutive models are designed to be representative of the physical response of rock
joints. The joint area contact model is intended for closely packed blocks with area contact. The
model provides a linear representation of joint stiffness and yield limit, and is based upon elastic
stiffness, frictional, cohesive and tensile strength properties, and dilation characteristics common
to rock joints. The model simulates displacement-weakening of the joint by loss of cohesive and
tensile strength at the onset of shear or tensile failure. (A variation of the area contact model
(CHANGE jcons = 2), in which the cohesion and tensile strength are maintained following failure,
is also available.) The continuously yielding joint model is a more complex model that simulates
continuous weakening behavior as a function of accumulated plastic-shear displacement.
Table 3.3 summarizes the 3DEC joint models, and presents examples of representative materials
and possible applications. The area contact Coulomb slip model is most applicable for general
engineering studies. Coulomb friction and cohesion properties are usually available more often
than other joint properties.

3DEC Version 4.1
172

PROBLEM SOLVING WITH 3DEC

Table 3.3

3 - 83

3DEC joint constitutive models

Model

Representative Material

Example Application

area contact

joints, faults, bedding planes in rock

general rock mechanics (e.g., underground excavation)

continuously
yielding

rock joints displaying progressive
damage and hysteretic behavior

cyclic loading and load reversal with
predominant hysteretic loop; dynamic
analysis

The continuously yielding joint model is an empirical expression that requires more detailed knowledge of the joint behavior. The properties for the continuously yielding model are derived from
laboratory test results relating joint shear stress to shear and normal displacement. It is always
recommended that initial studies be based on the Coulomb slip model first, in order to develop a
fundamental understanding of joint response before applying a more complex joint model. This
is discussed further in the following section. A demonstration of the response of the continuously
yielding model and the required properties is provided in Section 3 in Theory and Background.
3.7.3 Selection of an Appropriate Model
A problem analysis should always start with simple block and joint material models. In most cases,
an elastic block model (cons = 1) and a joint area contact Coulomb slip model (jcons = 1) should
be used first. The elastic block model only requires three material parameters: mass density, bulk
modulus and shear modulus (see Section 3.8.1.2). The Coulomb slip model requires six parameters:
normal and shear stiffness, friction angle, cohesion, tensile strength and dilation angle. Estimates
and references for these properties are given in Section 3.8.2. These material models provide a
simple perspective of stress-deformation behavior in the 3DEC model; the results of these analyses
can help the user assess whether a more complex (or simpler) material model is needed to describe
the block or joint behavior. For example, if the stresses and deformations in the blocks are low
compared to the joint movements, then a simpler, rigid block model may be sufficient.
It is often helpful to run simple tests of the selected material model before using it to solve the fullscale boundary-value problem. This can provide insight into the expected response of the model
compared to the known response of the physical material.
The following example illustrates the use of a simple test model. The problem application is the
analysis of joint slip around an underground excavation. A simple model is created to evaluate the
adequacy of the Coulomb slip model to represent the response of a joint subjected to shear loading.
The test is a simulation of a direct shear test, which consists of a single horizontal joint that is first
subjected to a normal confining stress, and then to a unidirectional shear displacement. Figure 3.41
shows the model; the joint is defined by one contact that is composed of 10 sub-contacts.

3DEC Version 4.1
173

3 - 84

User’s Guide

Figure 3.41 Direct shear test model
First, a normal stress of 20 MPa, which is representative of the confining stress acting on the joint, is
applied. A horizontal velocity is then applied to the top block to produce a shear displacement that
is also representative of the displacements expected in the problem application. For demonstration
purposes, we only apply a small shear displacement of less than 1 mm to this model.
The average normal and shear stresses, and normal and shear displacements along the joint, are
measured with a FISH function (av str). With this information we can determine the peak and
residual shear strengths and dilation that are produced with the different models. The data file for
this test using the Coulomb slip model is
Example 3.24 Direct shear test with Coulomb slip model
new
;
Coulomb slip joint model
;
direct shear test
;
poly brick -0.15,0.15 -0.10,0.10 -0.10,0
poly brick -0.10,0.10 -0.10,0.10 0,0.10
pl block
pl reset
gen edge 0.2
pl reset
;

3DEC Version 4.1
174

PROBLEM SOLVING WITH 3DEC

3 - 85

prop
mat=1 dens=0.0026 k=4000
g=3000
;
; Coulomb slip model
change jcons=1
prop jmat=1 kn=100000 ks=100000 fric=30.0 dil 15 zdil 6e-4
prop jmat=1 coh 10
;
hide range z 0 1
boun xvel 0 yvel 0 zvel 0 range z -1 0.1
seek
;
; normal load
bound str 0 0 -50 0 0 0 range z 0.09 0.11
;
step 100
;
; function to calculate average joint stresses
; and average joint displacements
;
def av_str
whilestepping
sstav = 0.0
nstav = 0.0
njdisp = 0.0
sjdisp = 0.0
ncon = 0
jarea = 0.04
ic = contact_head
loop while ic # 0
icsub = c_cx(ic)
loop while icsub # 0
ncon = ncon + 1
sstav = sstav + cx_xsforce(icsub)
nstav = nstav + cx_nforce(icsub)
njdisp = njdisp + cx_ndis(icsub)
sjdisp = sjdisp + cx_xsdis(icsub)
icsub = cx_next(icsub)
endloop
if ncon # 0
sstav = sstav / jarea
nstav = nstav / jarea
njdisp = njdisp / ncon
sjdisp = - sjdisp / ncon
endif
ic = c_next{ic)
endloop

3DEC Version 4.1
175

3 - 86

User’s Guide

end
;
reset jdisp
; shear load
hide range z -.1 0.0
bound xvel=0.005 range z -.1 1.1
bound yvel 0 range z -1 1
seek
;
;
hist unbal nc 5
hist @sstav @nstav @njdisp @sjdisp
;
hist sdis -1 -1 0 ndis -1 -1 0
hist sdis -1 1 0 ndis -1 1 0
hist sdis 0 0 0 ndis 0 0 0
hist sstr -1 -1 0 nstr -1 -1 0
hist sstr -1 1 0 nstr -1 1 0
hist sstr 0 0 0 nstr 0 0 0
hist sfor -1 -1 0 nfor -1 -1 0
hist label 2 ’Shear Stress’
hist label 5 ’Shear Displacement’
hist label 4 ’Normal Displacement’
hist type 16
plot add hist 2 vs 5 yaxis label ’Shear Stress’ &
xaxis label ’Shear Displacement’
cyc 15000
pause key
plot hist 4 vs 5 yaxis label ’Normal Displacement’ &
xaxis label ’Shear Displacement’
save cs_1.sav
return

The average shear stress versus shear displacement along the joint is plotted in Figure 3.42, and
the average normal displacement versus shear displacement is plotted in Figure 3.43. These plots
indicate that joint slip occurs for the prescribed model properties and conditions. The loading
slope in Figure 3.42 is linear until a peak shear strength of approximately 2.9 MPa is reached. As
indicated in Figure 3.43, the joint begins to dilate when the joint fails in shear, at roughly 0.3 mm
shear displacement. Dilation occurs until the limiting shear displacement (zdilation = 0.6 mm) is
reached for zero dilation. The maximum average dilation is approximately 0.077 mm.

3DEC Version 4.1
176

PROBLEM SOLVING WITH 3DEC

3 - 87

Figure 3.42 Average shear stress versus shear displacement
— Coulomb slip model

Figure 3.43 Average normal displacement versus shear displacement
— Coulomb slip model

3DEC Version 4.1
177

3 - 88

User’s Guide

As these results indicate, the Coulomb slip model (jcons = 1) only defines a limiting shear strength
value for the joint. The dilation that occurs after the joint begins to slip is approximated as a linear
function of the dilation angle, with a dilation limit that is a function of the shear displacement.
(These functions are described in Section 1.2.2.3 in Theory and Background.)
Other modifications to the joint behavior are also available for the Coulomb slip model. For
example, a displacement-weakening behavior can be approximated by including a joint cohesion
of 10 MPa (PROP jmat 1 coh = 10). At the onset of failure, the cohesion is set to zero. The results
shown in Figure 3.44 illustrate the peak and residual strengths that develop when the effect of
cohesion is included. Note that the drop in strength occurs abruptly. The maximum dilation (as
shown in Figure 3.36) is lower than the previous case without cohesion for the same limiting shear
displacement, because more shear displacement occurs before the joint fails initially. (Compare
Figure 3.45 to Figure 3.43.)

Figure 3.44 Average shear stress versus shear displacement
— Coulomb slip model with peak and residual strength
Note that if no weakening behavior is associated with a joint that has a cohesive strength, the
command CHANGE jcons = 2 should be given in place of CHANGE jcons = 1. In this case there will
be no change in the cohesion when the joint fails.

3DEC Version 4.1
178

PROBLEM SOLVING WITH 3DEC

3 - 89

Figure 3.45 Average normal displacement versus shear displacement
— Coulomb slip model with peak and residual strength
The displacement-weakening behavior is produced automatically with the continuously yielding
joint model (jcons = 3). This model simulates the progressive damage of the joint under shear.
For details and an example direct shear test with the continuously yielding model, see Section 3 in
Theory and Background.
The material properties for the Coulomb slip model in these examples were selected to produce
roughly the same response for joint shear strength and dilation for joints subjected to unidirectional
shearing. For an actual application, properties should be selected (and adjusted as necessary)
to simulate the response of the joints under the expected loading conditions. In most cases, the
Coulomb model parameters are relatively easy to estimate (see Section 3.8.2), and the simple
modifications that are available with the Coulomb model may be sufficient to approximate the joint
behavior.
For other joint models, such as the continuously yielding model, the determination of properties
is more involved. In order to use the continuously yielding model, it is necessary to run a series
of joint shear tests to best-fit the model properties to physical test results. It is recommended that
simple shear tests always be performed, regardless of the joint model selected, to ensure that the
joint behaves as expected under the anticipated problem conditions.
If it is necessary to simulate a complicated joint response, then a more complex joint model may be
required. However, before going to a more complex model, it is usually helpful to apply a simple
model first, to establish a basis for evaluating the influence of the more complicated joint behavior.

3DEC Version 4.1
179

3 - 90

User’s Guide

3.8 Material Properties
3DEC requires material properties for both the intact blocks and the discontinuities. This section
provides an overview of typical properties used to represent the behavior of jointed rock, and
presents guidelines for selecting the appropriate properties for a given model. There are also
special considerations such as the definition of post-failure properties and the extrapolation of
laboratory-measured properties to the field scale. These topics are also discussed.
The selection of properties is often the most difficult element in the generation of a model because
of the high uncertainty in the property database. It should be kept in mind when performing an
analysis, especially in geomechanics, that the problem will always involve a data-limited system;
the field data will never be known completely. However, with the appropriate selection of properties
based on the available database, important insight to the physical problem can still be achieved.
This approach to modeling is discussed further in Section 3.11.
3.8.1 Block Properties
Properties assigned to blocks are generally derived from laboratory testing programs. The following
four sections describe intrinsic (laboratory-scale) properties and list common values for various
rocks.
3.8.1.1 Mass Density
The mass density is required for every non-void material in a 3DEC model. This property has units
of mass divided by volume, and does not include the gravitational acceleration. In many cases,
the unit weight of a material is prescribed. If the unit weight is given with units of force divided
by volume, then this value must be divided by the gravitational acceleration before entering it as
3DEC input for density.
3.8.1.2 Intrinsic Deformability Properties
All material models for deformable blocks in 3DEC assume an isotropic material behavior in the
elastic range described by two elastic constants (bulk modulus, K, and shear modulus, G). The
elastic constants, K and G, are used in 3DEC instead of Young’s modulus, E, and Poisson’s ratio,
ν, because it is believed that bulk and shear moduli correspond to more fundamental aspects of
material behavior than do Young’s modulus and Poisson’s ratio. (See note 8 in Section 3.9 for
justification for using (K,G) rather than (E,ν).)
The equations to convert from (E,ν) to (K,G) are:

K=

G=

3DEC Version 4.1
180

E
3(1 − 2ν)
E
2(1 + ν)

(3.15)

PROBLEM SOLVING WITH 3DEC

3 - 91

Eq. (3.15) should not be used blindly when ν is near 0.5, since the computed value of K will be
unrealistically high and convergence to the solution will be very slow. It is better to fix the value
of K at its known physical value (estimated from an isotropic compaction test or from the p-wave
speed), and then compute G from K and ν.
Some typical values for elastic constants are summarized in Table 3.4 for selected rocks:

Table 3.4 Selected elastic constants (laboratory-scale) for rocks
(adapted from Goodman 1980)
E (GPa)

ν

K (GPa)

G (GPa)

Berea sandstone

19.3

0.38

26.8

7.0

Hackensack siltstone

26.3

0.22

15.6

10.8

Bedford limestone

28.5

0.29

22.6

11.1

Micaceous shale

11.1

0.29

8.8

4.3

Cherokee marble

55.8

0.25

37.2

22.3

Nevada Test Site granite

73.8

0.22

43.9

30.2

3.8.1.3 Intrinsic Strength Properties
The basic criterion for block material failure in 3DEC is the Mohr-Coulomb relation, which is a
linear failure surface corresponding to shear failure:

fs = σ1 − σ3 Nφ + 2c Nφ
where: Nφ
σ1
σ3
φ
c

(3.16)

= (1 + sin φ)/(1 − sin φ);
= major principal stress (compressive stress is negative);
= minor principal stress;
= friction angle; and
= cohesion.

Shear yield is detected if fs < 0. The two strength constants, φ and c, are conventionally derived
from laboratory triaxial tests.

3DEC Version 4.1
181

3 - 92

User’s Guide

The Mohr-Coulomb criterion loses its physical validity when the normal stress becomes tensile,
but, for simplicity, the surface is extended into the tensile region to the point at which σ3 equals the
uniaxial tensile strength, σ t . The minor principal stress can never exceed the tensile strength —
i.e.,
ft = σ3 − σ t

(3.17)

Tensile yield is detected if ft > 0. Tensile strength for rock and concrete is usually derived from
a Brazilian (or indirect tensile) test. Note that the tensile strength cannot exceed the value of σ3
corresponding to the apex limit for the Mohr-Coulomb relation. This maximum value is given by
t
=
σmax

c
tan φ

(3.18)

Typical values of cohesion, friction angle and tensile strength for a representative set of rock
specimens are listed in Table 3.5:

Table 3.5 Selected strength properties (laboratory-scale) for rocks
(adapted from Goodman 1980)
friction
angle
(degrees)

cohesion
(MPa)

tensile
strength
(MPa)

Berea sandstone

27.8

27.2

1.17

Repetto siltstone

32.1

34.7

—

Muddy shale

14.4

38.4

—

Sioux quartzite

48.0

70.6

—

Indiana limestone

42.0

6.72

1.58

Stone Mountain granite

51.0

55.1

—

Nevada Test Site basalt

31.0

66.2

13.1

The ubiquitous-joint component of the bilinear model also requires strength properties for the planes
of weakness. Joint properties are discussed in Section 3.8.2. The properties for joint cohesion and
friction angle also apply for the ubiquitous-joint model.

3DEC Version 4.1
182

PROBLEM SOLVING WITH 3DEC

3 - 93

3.8.1.4 Post-Failure Properties
In many instances, particularly in mining engineering, the response of a material after the onset
of failure is an important factor in the engineering design. Consequently, the post-failure behavior
must be simulated in the material model. In 3DEC, this is accomplished with properties which
define four types of post-failure response:
(1) shear dilatancy;
(2) shear hardening/softening;
(3) volumetric hardening/softening; and
(4) tensile softening.
These properties are only activated after the onset of failure, as defined by the Mohr-Coulomb
relation. Shear dilatancy is assigned for the Mohr-Coulomb and bilinear strain-hardening/softening
ubiquitous joint model. Hardening/softening parameters are assigned for the bilinear model.
Shear Dilatancy — Shear dilatancy, or dilatancy, is the change in volume that occurs with shear
distortion of a material. Dilatancy is characterized by a dilation angle, ψ, which is related to the
ratio of plastic volume change to plastic shear strain. This angle can be specified in the block
plasticity models in 3DEC. The dilation angle is typically determined from triaxial tests or shear
box tests. For example, the idealized relation for dilatancy, based on the Mohr-Coulomb failure
surface, is depicted for a triaxial test in Figure 3.46. The dilation angle is found from the plot
of volumetric strain versus axial strain. Note that the initial slope for this plot corresponds to the
elastic regime, while the slope used to measure the dilation angle corresponds to the plastic regime.
|I1 - I3|

I1
1

2 c cos B - (I1 - I3) sin B

E

elastic

A1

plastic

I2 = I3
Av

I3

atan (1-2K)

atan

2 sin O
1 - sin O

A1

Figure 3.46 Idealized relation for dilation angle, ψ, from triaxial test results
(Vermeer and de Borst 1984)

3DEC Version 4.1
183

3 - 94

User’s Guide

For soils, rocks and concrete, the dilation angle is generally significantly smaller than the friction
angle of the material. Vermeer and de Borst (1984) report the following typical values for ψ:
dense sand
loose sand
normally consolidated clay
granulated and intact marble
concrete

15◦
< 10◦
0◦
12◦ − 20◦
12◦

Vermeer and de Borst observe that values for the dilation angle are approximately between 0◦ and
20◦ , whether the material is soil, rock or concrete. The default value for the dilation angle is zero
for all of the constitutive models in 3DEC.
The dilation angle can also be prescribed for the joints in the ubiquitous-joint component of the
bilinear model. This property is typically determined from direct shear tests, and common values
can be found in the references discussed in Section 3.8.2.
Shear Hardening/Softening — The initiation of material hardening or softening is a gradual process
once plastic yield begins. At failure, deformation becomes more and more inelastic as a result of
micro-cracking in concrete and rock, and particle sliding in soil. This also leads to degradation
of strength in these materials and the initiation of shear bands. These phenomena, related to
localization, are discussed further in Section 3.11.
In 3DEC, shear hardening and softening are simulated by making Mohr-Coulomb properties (cohesion and friction, along with dilation) functions of plastic strain (see Section 2.3.5 in Theory
and Background). These functions are accessed from the bilinear model, and can be specified by
using the TABLE command.
Hardening and softening parameters must be calibrated for each specific analysis with values that
are generally back-calculated from results of laboratory triaxial tests. This is usually an iterative
process. Investigators have developed expressions for hardening and softening. For example,
Vermeer and de Borst (1984) propose the frictional hardening relation

sin φm

√
ep ef
= 2
sin φ
ep + ef

for ep ≤ ef
(3.19)

sin φm = sin φ
where: φ
φm
ep
ef

= ultimate friction angle;
= mobilized friction angle;
= plastic strain; and
= hardening constant.

3DEC Version 4.1
184

for ep > ef

PROBLEM SOLVING WITH 3DEC

3 - 95

Numerical testing conditions can influence the model response for shear hardening/softening behavior. The rate of loading can introduce inertial effects; this can be controlled by monitoring
the unbalanced force and reducing the loading rate accordingly. A FISH function can be used to
control the loading rate automatically. The results are also mesh-dependent. Thus, it is important
to evaluate the model behavior for differing zone sizes and mesh orientations whenever performing
an analysis involving shear hardening or softening.
Tensile Softening — At the initiation of tensile failure, the tensile strength of a material will generally
drop to zero. The Mohr-Coulomb model (cons = 2) does not strain-soften in tensile failure. The
tensile stress remains constant after the tensile stress limit has been reached. The bilinear zone
model (subi) will also have a constant tensile strength unless a tensile softening table is defined.
The rate at which the tensile strength drops, or tensile softening occurs, can also be controlled by
the plastic tensile strain in 3DEC. This function is accessed from the bilinear model (subi), and
can be specified by using the TABLE command.
A simple tension test (Example 3.25) illustrates perfectly plastic tensile failure, as built into the
Mohr-Coulomb model, and brittle tensile failure in the bilinear model (subi). The model is a tension
test on a cubic block composed of Mohr-Coulomb material. The ends of the sample are pulled apart
at a constant velocity. The test is performed with both the cons 2 and the subi block models.
Example 3.25 Tension test on tensile-softening material
new
poly brick 0 1 0 1 0 1
plot block
plot reset
gen quad ndiv 1 1 1 rmul 1
; Mohr-Coulomb (cons = 2) model
change cons 2
prop
mat=1 dens=2500 k=1.19e10 g=1.1e10 bcoh 2.72e5 phi 44 bten 2e5
; bilinear model
;config cpp
;zone model subi
;prop mat 1 dens 2500
;zone bulk=1.19e10 shear=1.1e10 coh 2.72e5 fric 44 ten 2e5
;zone jcoh 1e20 jten 1e20 jfric 44
;zone ttab 1
;table 1 0 2e5 9e-6 0
;
bound zvel -1e-5 range z 0.0
bound zvel 1e-5 range z 1.0
def ax_str
str = 0.0
ib = block_head
ig = b_gp(ib)
nx = 0

3DEC Version 4.1
185

3 - 96

User’s Guide

ny = 0
xbpos = 0.0
xbdis = 0.0
xtpos = 0.0
xtdis = 0.0
zbpos = 0.0
zbdis = 0.0
ztpos = 0.0
ztdis = 0.0
loop while ig # 0
if gp_z(ig) > ztop then
igb = gp_bou(ig)
str = str + bou_zforce{igb)
ztpos = ytpos + gp_z(ig)
ztdis = ytdis + gp_zdis(ig)
end_if
if gp_z(ig) < zbot then
nz = nz + 1
zbpos = zbpos + gp_z(ig)
zbdis = zbdis + gp_zdis(ig)
end_if
if gp_x(ig) < xbot then
nx = nx + 1
xbpos = xbpos + gp_x(ig)
xbdis = xbdis + gp_xdis(ig)
end_if
if gp_x(ig) > xtop then
xtpos = xtpos + gp_x(ig)
xtdis = xtdis + gp_xdis(ig)
end_if
ig = gp_next(ig)
end_loop
ax_str = str / area
xbdis = xbdis / nx
xbpos = xbpos / nx
xtdis = xtdis / nx
xtpos = xtpos / nx
zbdis = zbdis / nz
zbpos = zbpos / nz
ztdis = ztdis / nz
ztpos = ztpos / nz
ex_str = (xtdis - xbdis) / (xtpos - xbpos)
ez_str = (ztdis - zbdis) / (ztpos - zbpos)
end
set @area = 1.0 @ztop = 0.9 @zbot = 0.1 @xbot = 0.1 @xtop = 0.9
hist @ax_str @ex_str @ez_str

3DEC Version 4.1
186

PROBLEM SOLVING WITH 3DEC

3 - 97

damp local
plot his 1 vs 3 xaxis label ’Vertical Strain’ &
yaxis label ’Vertical Stress’
step 20000
save mc.sav
pause key
plot his 2 vs 3 xaxis label ’Vertical Strain’ &
yaxis label ’Horizontal Strain’
ret

The plot of σzz -stress versus zz-strain (Figure 3.47) shows that the average stress remains constant
for the Mohr-Coulomb model in cons 2. The stress will remain constant in the bilinear model
without tensile softening. The brittleness of the tensile softening can be controlled by the plastic
tensile-strain function. If Example 3.25 is repeated with the bilinear model (subi) and a tensile
softening table, an instantaneous softening response can be produced, as shown in Figure 3.48.

Figure 3.47 σzz -stress versus zz-strain for tension test with cons 2 model

3DEC Version 4.1
187

3 - 98

User’s Guide

Figure 3.48 σzz -stress versus zz-strain for tension test with cons 6 model and
tensile-softening table
The average xx-strain and yy-strain across the model decrease until tensile failure is initiated. With
the cons 2 model, this strain is not controlled in the post-failure region; the model will continue to
contract as indicated by the plot of xx-strain versus zz-strain in Figure 3.49.
With the bilinear model, the strain is affected after the onset of tensile failure; the model expands
in the x- and y-directions as tensile softening occurs, as indicated in Figure 3.50.

3DEC Version 4.1
188

PROBLEM SOLVING WITH 3DEC

3 - 99

Figure 3.49 xx-strain versus zz-strain for tension test with cons 2 model

Figure 3.50 xx-strain versus zz-strain for tension test with cons 6 model and
tensile-softening table

3DEC Version 4.1
189

3 - 100

User’s Guide

Note that local damping (DAMP local) is used to minimize oscillations that can arise when the abrupt
tensile failure occurs. Alternatively, if adaptive global damping is used by giving the DAMP auto
command, oscillations are observed in the stress/strain plots. With adaptive global damping, the
damping parameter is continually decreased as the model is stretched. When tensile failure occurs,
the global damping parameter is low, and oscillations that may affect the final solution state are
produced. With local damping, the amount of damping varies from gridpoint to gridpoint, and is
proportional to the unbalanced force. This damping minimizes the oscillations that are produced
when the abrupt tensile failure occurs. (See Section 1.2.3.2 in Theory and Background for further
discussion on damping.)
The brittleness of the tensile softening can be controlled by the plastic tensile strain function, by
using the bilinear model instead of the Mohr-Coulomb model. As with the shear-softening, the
tensile-softening must be calibrated for each specific problem and mesh size, since the results will
be mesh-dependent.
3.8.1.5 Extrapolation to Field-Scale Properties
The material properties used in the 3DEC model should correspond as closely as possible to the
actual values of the physical problem. Laboratory-measured properties generally should not be used
directly in a 3DEC model for a full-scale problem. The presence of discontinuities in the model
will account for a good portion of the scaling effect on properties. However, some adjustment of
block properties will still probably be required to represent the influence of heterogeneities and
micro-fractures, fissures and other small discontinuities on the rock mass response.
Several empirical approaches have been proposed to derive field-scale properties. Some of the more
commonly accepted methods are discussed.
Deformability of a rock mass is generally defined by a modulus of deformation, Em . If the rock
mass contains a set of relatively parallel, continuous joints with uniform spacing, the value for Em
can be estimated by treating the rock mass as an equivalent transversely isotropic continuum. The
relations in Section 3.8.2 can then be used to estimate Em in the direction normal to the joint set.
Deformation moduli can also be estimated for cases involving more than one set of discontinuities.
The references listed in Section 3.8.2 provide solutions for multiple joint sets.
In practice, the rock mass structure is often much too irregular, or sufficient data is not available,
to use the preceding approach. It is common to determine Em from a force-displacement curve
obtained from an in-situ compression test. Such tests include plate bearing tests, flatjack tests and
dilatometer tests.
Bieniawski (1978) developed an empirical relation for Em based on field test results at sites throughout the world. The relation is based on rock mass rating (RMR). For rocks with a rating higher than
55, the test data can be approximately fit to
Em = 2(RMR) − 100
The units of Em are GPa.

3DEC Version 4.1
190

(3.20)

PROBLEM SOLVING WITH 3DEC

3 - 101

For values of Em between 1 and 10 GPa, Serafim and Pereira (1983) found a better fit, given by
Em = 10

RMR−10
40

(3.21)

References by Goodman (1980) and Brady and Brown (1985) provide additional discussion on
these methods.
The most commonly accepted approach to estimate rock mass strength is that proposed by Hoek
and Brown (1980). They developed the empirical rock mass strength criterion,
σ1s = σ3 + (mσc σ3 + sσc2 )1/2

(3.22)

where: σ1s
= major principal stress at peak strength;
σ3
= minor principal stress;
m and s = constants that depend on the properties of the rock, and the
extent to which it has been broken before being subjected to
failure stresses; and
σc
= uniaxial compressive strength of intact rock material.
The unconfined compressive strength for a rock mass is given by
qm = σc s 1/2

(3.23)

and the uniaxial tensile strength of a rock mass is
σt =

1
σc [m − (m2 + 4s)1/2 ]
2

(3.24)

Table 3.6 (from Hoek and Brown 1988) presents typical values for m and s for undisturbed and
disturbed rock masses.
It is possible to estimate Mohr-Coulomb friction angle and cohesion from the Hoek-Brown criterion
(see, for example, Hoek 1990).
For a given value of σ3 , a tangent to the function (Eq. (3.22)) will represent an equivalent MohrCoulomb yield criterion in the form
σ1 = Nφ σ3 + σcM
where Nφ =

1+sin φ
1−sin φ

(3.25)

= tan2 ( φ2 + 45◦ )

3DEC Version 4.1
191

3 - 102

User’s Guide

By substitution, σcM is
σcM

= σ1 − σ3 Nφ = σ3 +



σ3 σc m + σc2 s

− σ3 Nφ = σ3 (1 − Nφ ) +



σ3 σc m + σc2 s

σcM is the apparent uniaxial compressive strength of the rock mass for that value of σ3 .
The tangent to the Eq. (3.22) is defined by
Nφ (σ3 ) =

∂σ1
σc m
= 1 + 
∂σ3
2 σ3 · σc m + sσc2

(3.26)

The cohesion (c) and friction angle (φ) can then be obtained from Nφ and σcM :

φ = 2 tan−1
σM
c = c
2 Nφ

3DEC Version 4.1
192


Nφ − 90◦

(3.27)
(3.28)

PROBLEM SOLVING WITH 3DEC

Typical values for Hoek-Brown rock-mass strength parameters
(adapted from Hoek and Brown (1988))

Laboratory specimens free

m

7.00

10.00

15.00

17.00

from discontinuities

s

1.00

1.00

1.00

1.00

1.00

CSIR rating: RMR = 100

m

7.00

10.00

15.00

17.00

25.00

NGI rating: Q = 500

s

1.00

1.00

1.00

1.00

1.00

VERY GOOD QUALITY ROCK MASS
Tightly interlocking undisturbed rock
with unweathered joints at 1 to 3 m
CSIR rating RMR = 85
NGI rating: Q = 100

m
s
m
s

2.40
0.082
4.10
0.189

3.43
0.082
5.85
0.189

5.14
0.082
8.78
0.189

5.82
0.082
9.95
0.189

8.56
0.082
14.63
0.189

GOOD QUALITY ROCK MASS
Fresh to slightly weathered rock, slightly
disturbed with joints at 1 to 3 m
CSIR rating: RMR = 65
NGI rating: Q = 10

m
s
m
s

0.575
0.00293
2.006
0.0205

0.821
0.00293
2.865
0.0205

1.231
0.00293
4.298
0.0205

1.395
0.00293
4.871
0.0205

2.052
0.00293
7.163
0.0205

FAIR QUALITY ROCK MASS
Several sets of moderately weathered
joints spaced at 0.3 to 1 m
CSIR rating: RMR = 44
NGI rating: Q = 1

m
s
m
s

0.128
0.00009
0.947
0.00198

0.183
0.00009
1.353
0.00198

0.275
0.00009
2.03
0.00198

0.311
0.00009
2.301
0.00198

0.458
0.00009
3.383
0.00198

POOR QUALITY ROCK MASS
Numerous weathered joints at 30-500 mm,
some gouge; clean compacted waste rock
CSIR rating: RMR = 23
NGI rating: Q = 0.1

m
s
m
s

0.029
0.000003
0.447
0.00019

0.041
0.000003
0.639
0.00019

0.061
0.000003
0.959
0.00019

0.069
0.000003
1.087
0.00019

0.102
0.000003
1.598
0.00019

VERY POOR QUALITY ROCK MASS
Numerous heavily weathered joints spaced
<50 mm with gouge; waste rock with fines
CSIR rating: RMR = 3
NGI rating: Q = 0.01

m
s
m
s

0.007
0.0000001
0.219
0.00002

0.01
0.0000001
0.313
0.00002

0.015
0.0000001
0.469
0.00002

0.017
0.0000001
0.532
0.00002

0.025
0.0000001
0.782
0.00002

EMPIRICAL FAILURE CRITERION
σ'1 = σ'3 ÷ √(mσcσ'3 ÷ sσ2c)
σ'1 = major principal effective stress
σ'3 = minor principaI effective stress
σc = uniaxial compressive strength
of intact rock, and
m and s are empirical constants.

ARENACEOUS ROCKS WITH STRONG
CRYSTALS AND POORLY DEVELOPED
CRYSTAL CLEAVAGE — sandstone and
quartzite

LITHIFIED ARGILLACEOUS ROCKS —
mudstone, siltstone, shale and slate (normal to
cleavage)

COARSE-GRAINED POLYMINERALLIC
IGNEOUS & METAMORPHIC CRYSTALLINE
ROCKS — amphibolite, gabbro gneiss, granite,
norite, quartz-diorite

Undisturbed rock mass m and s values

CARBONATE ROCKS WITH WELLDEVELOPED CRYSTAL CLEAVAGE —
dolomite, limestone and marble

Disturbed rock mass m and s values

FINE-GRAINED POLYMINERALLIC IGNEOUS
CRYSTALLINE ROCKS — andesite, dolerite,
diabase and thyolite

Table 3.6

3 - 103

INTACT ROCK SAMPLES
25.00

3DEC Version 4.1
193

3 - 104

User’s Guide

3.8.2 Joint Properties
Joint properties are conventionally derived from laboratory testing (e.g., triaxial and direct shear
tests). These tests can produce physical properties for joint friction angle, cohesion, dilation angle
and tensile strength, as well as joint normal and shear stiffnesses. The joint cohesion and friction
angle correspond to the parameters in the Coulomb strength criterion.
Values for normal and shear stiffnesses for rock joints typically can range from roughly 10 to 100
MPa/m for joints with soft clay in-filling, to over 100 GPa/m for tight joints in granite and basalt.
Published data on stiffness properties for rock joints is limited; summaries of data can be found in
Kulhawy (1975), Rosso (1976) and Bandis et al. (1983).
Approximate stiffness values can be back-calculated from information on the deformability and
joint structure in the jointed rock mass and the deformability of the intact rock. If the jointed rock
mass is assumed to have the same deformational response as an equivalent elastic continuum, then
relations between jointed rock properties and equivalent continuum properties can be derived.
For uniaxial loading of rock containing a single set of uniformly spaced joints oriented normal to
the direction of loading, the following relation applies:
1
1
1
=
+
Em
Er
kn s
or
kn =

Em Er
s (Er − Em )

(3.29)

where:Em = rock mass Young’s modulus;
Er = intact rock Young’s modulus;
kn

= joint normal stiffness; and

s

= joint spacing.

A similar expression can be derived for joint shear stiffness:
ks =
where:Gm = rock mass shear modulus;
Gr = intact rock shear modulus; and
ks

= joint shear stiffness.

3DEC Version 4.1
194

Gm Gr
s (Gr − Gm )

(3.30)

PROBLEM SOLVING WITH 3DEC

3 - 105

The equivalent continuum assumption, when extended to three orthogonal joint sets, produces the
following relations:

Ei =

Gij =

1
1
+
Er
si kni

−1

1
1
1
+
+
Gr
si ksi
sj ksj

−1

(i = 1, 2, 3)

(3.31)

(i , j = 1, 2, 3)

(3.32)

Several expressions have been derived for two- and three-dimensional characterizations and multiple
joint sets. References for these derivations can be found in Singh (1973), Gerrard (1982(a) and (b))
and Fossum (1985).
There is a limit to the maximum joint stiffnesses that are reasonable to use in a 3DEC model. If
the physical normal and shear stiffnesses are less than ten times the equivalent stiffness of adjacent
zones (see Eq. (3.33) in Section 3.9), then there is no problem with using physical values. If the
ratio is more than ten, the solution time will be significantly longer than for the case in which the
ratio is limited to ten, without much change in the behavior of the system. Serious consideration
should be given to reducing supplied values of normal and shear stiffnesses to improve solution
efficiency. There may also be problems with block interpenetration if the normal stiffness, kn , is
very low. A rough estimate should be made of the joint normal displacement that would result from
the application of typical stresses in the system (u = σ/kn ). This displacement should be small
compared to a typical zone size. If it is greater than, say, 10% of an adjacent zone size, then either
there is an error in one of the numbers or the stiffness should be increased.
Published strength properties for joints are more readily available than for stiffness properties.
Summaries can be found, for example, in Jaeger and Cook (1969), Kulhawy (1975) and Barton
(1976). Friction angles can vary from less than 10◦ for smooth joints in weak rock (such as tuff),
to over 50◦ for rough joints in hard rock (such as granite). Joint cohesion can range from zero
cohesion to values approaching the compressive strength of the surrounding rock.
It is important to recognize that joint properties measured in the laboratory typically are not representative of those for real joints in the field. Scale dependence of joint properties is a major
question in rock mechanics. Often, the only way to guide the choice of appropriate parameters is
by comparison to similar joint properties derived from field tests; however, field test observations
are extremely limited. Some results are reported by Kulhawy (1975).

3DEC Version 4.1
195

3 - 106

User’s Guide

3.9 Tips and Advice
When problem solving with 3DEC, it is often important to try to optimize the model for the most
efficient analysis. This section provides several suggestions on ways to improve a model run. Some
common pitfalls which should be avoided when preparing a 3DEC calculation are also listed.
1. Designing the Model
It is tempting to try to build as much detail of the geologic structure as possible
into a 3DEC model. There are three main arguments against this approach:
(1) It is futile to ever expect to have sufficient data to model a jointed rock mass
in every detail. (2) The computer hardware requirements for a detailed model
quickly exceed what is typically available for engineering projects. (3) Most
importantly, a controlled engineering understanding of model results becomes
less effective as more detail is added.
Two considerations should be kept in mind when creating the 3DEC model.
The first is whether a discontinuum analysis is actually required. This depends
in large part on the ratio of the scale of the physical system under investigation
to the average spacing of the joint structure. For example, if an excavation
is made in a rock mass containing a single joint set with an average spacing
of 1 m or less, and the minimum dimension of the excavation is 10 m, then
a continuum analysis with a ubiquitous-joint material model may be a more
reasonable approach. At this scale, the continuum analysis can produce a response that is broadly equivalent to that obtained when the joints are explicitly
modeled. The analysis with 3DEC provides a more detailed analysis of the
failure mechanism, but may require more computation time than the continuum analysis. In instances where the ratio of the physical system scale to
the joint spacing exceeds approximately 10:1, a continuum analysis may be
preferred. Analyses should be conducted with both continuum and discontinuum analyses when there is a question as to whether the continuum analysis
is sufficient to represent the discontinuum response. See Board et al. (1996)
for an illustration of the application of discontinuum and continuum analyses
(using UDEC and FLAC) in a comparative study of toppling behavior of a
jointed rock slope.
The second consideration is the extent to which the detailed geologic structure
should be included in the model. A detailed representation that includes the
most critical joint structure (see Section 3.2.7) is usually only required within
a limited region surrounding the area of interest (e.g., within a few tunnel radii
surrounding a tunnel excavation). Generally, the greater jointing detail only
needs to extend from the area of interest to a distance sufficient to encompass
the region in which failure is anticipated. That is, the detailed geologic structure should extend beyond the distance to which joint slip and separation are
calculated.

3DEC Version 4.1
196

PROBLEM SOLVING WITH 3DEC

3 - 107

2. Check Model Runtime
The solution time for a 3DEC run is a function of both the number of rigid
blocks or gridpoints in deformable blocks, and the number of contacts in a
model. If there are very few contacts in the model, then the time is proportional to N 3/2 , where N is the number of rigid blocks or gridpoints in
deformable blocks. This formula holds for elastic problems. The runtime will
vary somewhat, but not substantially, for plasticity problems.
The solution time will increase as more contacts are created in the model. It
is important to check the speed of calculation on your computer for a specific
model. An easy way to do this is to run the benchmark test described in
Section 6. Then use this speed to estimate the speed of calculation for the
specific model, based on interpolation from the number of gridpoints and
contacts.
3. Effects on Runtime
3DEC will take a longer time to converge if:
(a) there are large contrasts in stiffness in block materials or in joint
materials, or in block versus joint materials; or
(b) there are large contrasts in block or zone sizes.
The code becomes less efficient as these contrasts become greater. The effect
of a contrast in stiffness should be investigated before performing a detailed
analysis. For example, for mechanical-only calculations, joint normal and
shear stiffnesses should be kept smaller than ten times the equivalent stiffness
of the stiffest neighboring zone in blocks adjoining the joint — i.e.,




K + 4/3G
kn and ks ≤ 10.0 max
zmin


(3.33)

where K and G are the bulk and shear moduli, respectively, of the block
material, and zmin is the smallest dimension of the zone adjoining the joint
in the normal direction. If the joint stiffnesses are greater than 10 times the
equivalent stiffness, the solution time of the model will be significantly longer
than for the case in which the ratio is limited to ten, without a significant
change in the behavior of the system.
On the other hand, there may be problems if the normal stiffness, kn , is very
low. A rough estimate of the joint normal displacement that would result from
the application of typical stresses in the system (u = σ/kn ) should be made.
This displacement should be small compared to a typical zone size. If it is
greater than roughly 10% of an adjacent zone size, then either there is an error
in one of the numbers or the stiffness should be increased.

3DEC Version 4.1
197

3 - 108

User’s Guide

4. Considerations for Density of Zoning
3DEC uses constant-strain elements in deformable blocks. If the gradient
of stress/strain is high, many zones will be needed to represent the varying
distribution. Run the same problem with different zoning densities to check
the effect. Constant-strain zones are used in 3DEC because a better accuracy
is achieved when plastic flow is modeled with many low-order elements rather
than with a few high-order elements.
Try to keep the zoning as uniform as possible, particularly in the region of
interest. Avoid long, thin zones with aspect ratios greater than 5:1.
5. Check Model Response
3DEC shows how a system behaves. Make frequent simple tests to check
whether you are doing what you think you are doing. For example, if a
loading condition and geometry are symmetrical, make sure that the response
is symmetrical. After making a change in the model, execute a few calculation
steps (for example, 5 or 10) to verify that the initial response is of the correct
sign and in the correct location. Do back-of-the-envelope estimates of the
expected order of magnitude of stress or displacements, and compare to the
3DEC output.
If you apply a violent shock to the model, you will get a violent response. If
you do physically unreasonable things to the model, you must expect strange
results. If you get unexpected results at a given stage of an analysis, review
the steps you followed up to this stage.
Critically examine the output before proceeding with the model simulation.
If, for example, everything appears reasonable except for large velocities in
one corner block, do not go on until you understand the reason for this. In this
case, you may not have fixed a boundary corner properly.
6. Use Bulk and Shear Moduli
It is better to use bulk modulus, K, and shear modulus, G, than Young’s
modulus, E, and Poisson’s ratio, ν, for elastic properties in 3DEC.
The pair (K, G) makes sense for all elastic materials that do not violate thermodynamic principles. The pair (E, ν) does not make sense for certain admissible
materials. At one extreme we have materials that resist volumetric change but
not shear; at the other extreme, materials that resist shear but not volumetric
change. The first type of material corresponds to finite K and zero G; the second to zero K and finite G. However, the pair (E, ν) is not able to characterize
either the first or second type of material. If we exclude the two limiting cases
(conventionally, ν = 0.5 and ν = −1), the equations

3DEC Version 4.1
198

PROBLEM SOLVING WITH 3DEC

3 - 109

3K(1 − 2ν) = E
(3.34)
2G(1 + ν) = E
relate the two sets of constants. These equations hold, however close we approach (but not reach) the limiting cases. We do not need to relate them to
physical tests that may or may not be feasible; the equations are simply the
consequence of two possible ways of defining coefficients of proportionality.
Suppose we have a material in which the resistance to distortion progressively
reduces, but in which the resistance to volume change remains constant. ν
approaches 0.5 in this case. The equation 3K(1 − 2ν) = E must still be satisfied. There are two possibilities (argued on algebraic, not physical, grounds):
either E remains finite (and nonzero) and K tends to an arbitrarily large value;
or K remains finite and E tends to zero. We rule out the first possibility because there is a limiting compressibility to all known materials (e.g., 2 GPa for
water, which has a Poisson’s ratio of 0.5). This leaves the second, in which E
is varying drastically, even though we supposed that the material’s principal
mode of elastic resistance was unchanging. We deduce that the parameters
(E, ν) are inadequate to express the material behavior.
7. Choice of Damping
In most instances, it is recommended that DAMP local be used for static analyses. This is generally appropriate for static analysis, for the reasons given in
Section 1.2.3.2 in Theory and Background. Also, as demonstrated in Example 3.25, local damping is more suitable to minimize oscillations that may
arise when abrupt failure occurs in the model.
In some cases, particularly when calculating an initial equilibrium state, it
may be more computationally efficient to use DAMP auto. As discussed in
Section 1.2.3.2 in Theory and Background, local damping is most efficient
when velocity components at gridpoints pass through zero periodically, because the mass-adjustment process depends on velocity sign changes. Adaptive global damping, on the other hand, applies a constant damping factor that
is not affected by velocity sign-changes. If velocities act predominantly in
one direction (e.g., due to gravity loading), then a system with local damping
may take longer to converge than one with adaptive global damping. When
in doubt, it is usually best to run the model with both DAMP local and DAMP
auto, and compare the calculation steps required to reach convergence.

3DEC Version 4.1
199

3 - 110

User’s Guide

8. Avoiding Rounding Errors
Most of the calculations in 3DEC are in single precision (e.g., coordinate updates and displacements). Usually, the significant figures that are available
in single-precision, 32-bit computer arithmetic are sufficient to keep rounding
errors from affecting the solution. However, there are circumstances in which
numerical rounding errors can affect the results of an analysis. For example, rounding errors may become noticeable in problems that run for several
hundred thousand cycles with a low applied velocity.
To minimize rounding error problems, avoid large coordinates when creating
a model. For example, it is tempting to adopt the same coordinate values as
those used in mine plan and section drawings when creating a model for a
mining application. While this makes it easier to refer plots and results back
to the mine drawings, it may inadvertently magnify the rounding errors in the
computation.
3DEC always updates coordinates progressively as deformations develop. If
the initial coordinates are very large numerically (e.g., a coordinate range of
10000 to 10100), significant accuracy may be lost when small displacement
increments are added to the coordinates. Also, searches for block contacts,
which involve differences between coordinate values, may become unreliable.
By changing the coordinates to range from 0 to 100, the problem can be
avoided.
9. Determining Collapse Loads
In order to determine a collapse load, it often is better to use “strain-controlled”
boundary conditions instead of “stress-controlled” boundary conditions (i.e.,
apply a constant velocity and measure the boundary reaction forces, rather than
apply forces and measure displacements). A system that collapses becomes
difficult to control as the applied load approaches the collapse load. This is
true of a real system as well as a model system.
10. Determining Factor of Safety
3DEC does not calculate a “factor of safety” directly. If you need a safety
factor, it can be determined for any selected parameter by calculating the ratio
of the selected parameter value under given conditions, to the parameter value
that results in failure. For example:

3DEC Version 4.1
200

FL =

applied load to cause failure
design load

Fφ =

tan (actual failure angle)
tan (friction angle at failure)

PROBLEM SOLVING WITH 3DEC

3 - 111

Note that the larger value is always divided by the smaller value (assuming
that the system does not fail under the actual conditions). The definition of
failure must be established by the user.

3DEC Version 4.1
201

3 - 112

User’s Guide

3.10 Interpretation
Because 3DEC models a nonlinear system as it evolves in time, the interpretation of results may
be more difficult than with a conventional finite element program that produces a “solution” at
the end of its calculation phase. There are several indicators that can be used to assess the state
of the numerical model for a static analysis* (e.g., whether the system is stable, unstable or is in
steady-state plastic flow). The various indicators are described below.
3.10.1 Unbalanced Force
Forces are accumulated at each centroid of rigid blocks, and each gridpoint of deformable blocks.
At equilibrium (or steady plastic flow in deformable blocks), the algebraic sum of these forces is
almost zero (i.e., the forces acting on one side of the block centroid or gridpoint nearly balance
those acting on the other). During timestepping, the maximum unbalanced force is determined for
the whole model; this force is displayed continuously on the screen. It can also be saved as a history
and viewed as a graph. The unbalanced force is important in assessing the state of the model for
static analysis, but its magnitude must be compared with the magnitude of typical internal forces
acting in the model. In other words, it is necessary to know what constitutes a “small” force. A
representative internal gridpoint force for deformable blocks may be found by multiplying stress by
zone area perpendicular to the force, using values that are typical in the area of interest in the model.
Denoting R as the ratio of maximum unbalanced force to the representative internal force (expressed
as a percentage), the value of R will never decrease to zero. However, a value of 1% or 0.1% may be
acceptable as denoting equilibrium, depending on the degree of precision required (e.g., R = 1%
may be good enough for an intermediate stage in a sequence of operations, while R = 0.1% may
be used if a final stress or displacement distribution is required for inclusion in a report or paper).
Note that a low value of R only indicates that forces balance at all gridpoints. However, steady
plastic flow may be occurring, without acceleration. In order to distinguish between this condition
and “true” equilibrium, other indicators (such as those described below) should be consulted.
3.10.2 Block/Gridpoint Velocities
The velocities of rigid blocks and gridpoints of deformable blocks may be assessed by plotting
the whole field of velocities (using the PLOT vel command), or by selecting certain key points in
the model and tracking their velocities with histories (HIS xvel, HIS yvel and HIS zvel). Both types
of plots are useful. Steady-state conditions are indicated if the velocity histories show horizontal
traces in their final stages. If they have all converged to near-zero (in comparison to their starting
values), then absolute equilibrium has occurred. If a history has converged to a nonzero value, then
either the block is falling, or steady plastic flow is occurring at the block/gridpoint corresponding
to that history. If one or more velocity history plots show fluctuating velocities, then the system is
likely to be in a transient condition.
* Interpretation of the state of a model for a dynamic analysis is discussed in Section 2 in Optional
Features.

3DEC Version 4.1
202

PROBLEM SOLVING WITH 3DEC

3 - 113

The plot of the field of velocity vectors is more difficult to interpret, since both the magnitudes and
the nature of the pattern are important. As with gridpoint forces, velocities never decrease precisely
to zero. The magnitude of velocity should be viewed in relation to the displacement that would
occur if a significant number of steps (e.g., 1000) were to be executed. For example, if current
displacements in the system are of the order of 1 cm, the maximum velocity in the velocity plot is
10−3 m/sec and the timestep is 10−5 sec, then 1000 steps would produce an additional displacement
of 10−5 m or 10−3 cm, which is 0.1% of the current displacements. In this case, it can be said
that the system is in equilibrium, even if the velocities all seem to be “flowing” in one direction.
More often, the vectors appear to be random (or almost random) in direction and (possibly) in
magnitude. This condition occurs when the changes in gridpoint force fall below the accuracy limit
of the computer, which is around six decimal digits. A random velocity field of low amplitude is
an infallible indicator of block stability and no plastic flow.
If the vectors in the velocity field are coherent (i.e., there is some systematic pattern) and their
magnitude is quite large (using the criterion described above), then either blocks are falling or
slipping, plastic flow is occurring within blocks, or the system is still adjusting elastically (e.g.,
damped elastic oscillation is taking place). To confirm that continuing plastic flow is occurring,
a plot of plasticity indicators should be consulted (see Section 3.10.3). If, however, the motion
involves elastic oscillation, then the magnitude should be observed in order to indicate whether such
movement is significant. Seemingly meaningful patterns of oscillation may be seen. However, if
amplitude is low, then the motion has no physical significance.
3.10.3 Plastic Indicators for Block Failure
For most of the nonlinear block models in 3DEC, the command PLOT plas displays those zones in
which the stresses satisfy the yield criterion. Such an indication usually denotes that plastic flow
is occurring, but it is possible for a block zone simply to “sit” on the yield surface without any
significant flow taking place. It is important to look at the whole pattern of plasticity indicators to
see whether a mechanism has developed. A failure mechanism is indicated if there is a contiguous
line of active plastic zones that join two surfaces. The diagnosis is confirmed if the velocity plot also
indicates motion corresponding to the same mechanism. Note that initial plastic flow often occurs at
the beginning of a simulation, but subsequent stress redistribution unloads the yielding elements so
that their stresses no longer satisfy the yield criterion (“yielded in past”). Only the actively yielding
elements (“at yield surface”) are important to the detection of a failure mechanism. If there is
no contiguous line or band of active plastic zones between boundaries, two patterns should be
compared before and after the execution of, say, 500 steps. Is the region of active yield increasing
or decreasing? If it is decreasing, then the system is probably heading for equilibrium; if it is
increasing, then ultimate failure may be possible.
If a condition of continuing plastic flow has been diagnosed, one further question should be asked:
Does the active flow band(s) include zones adjacent to artificial boundaries? The term “artificial
boundary” refers to a boundary that does not correspond to a physical entity, but exists simply to
limit the size of the model that is used. If plastic flow occurs along such a boundary, then the
solution is not realistic because the mechanism of failure is influenced by a nonphysical entity. This
comment only applies to the final steady-state solution; intermediate stages may exhibit flow along
boundaries.

3DEC Version 4.1
203

3 - 114

User’s Guide

3.10.4 Histories
In any problem, there are certain variables that are of particular interest (e.g., displacements may
be of concern in one problem, but stresses may be of concern in another). Liberal use should be
made of the HIST command to track these important variables in the regions of interest. After some
timestepping has taken place, the plots of these histories often provide the way to find out what the
system is doing.
3.10.5 Factor of Safety
A factor of safety can be determined in 3DEC for any selected parameter by calculating the ratio
of the selected parameter value under given conditions to the parameter value that results in failure.
For example:
FL =

applied load to cause failure
design load

Fφ =

tan (actual friction angle)
tan (friction angle at failure)

Note that the larger value is always divided by the smaller value (assuming that the system does
not fail under the actual conditions). The definition of failure must be established by the user. A
comparison of this approach based on strength reduction for determining factor of safety to that
based upon limit analysis solutions is given by Dawson and Roth (1999) and Dawson et al. (1999).
The strength reduction method for determining factor of safety is implemented in 3DEC through the
SOLVE fos command. This command implements an automatic search for factor of safety using the
bracketing approach, as described in Dawson et al. (1999). The SOLVE fos command may be given
at any stage in a 3DEC run, provided that all non-null zones contain Mohr Coulomb-based models.
During the solution process, properties will be changed, but the original state will be restored on
completion, or if the fos search is terminated prematurely with the  key.
When 3DEC is executing the SOLVE fos command, the bracketing values for F are printed continuously to the screen so that you can tell how the solution is progressing. If terminated by the
 key, the solution process terminates, and the best current estimate of fos is displayed. Save
files are produced for the last stable state and the last unstable state, so that velocity vectors, etc.
can be plotted. This allows a visual representation of the failure mode to be created. It is highly
recommended that you verify that the automatic bracketing process has correctly identified both
the stable and unstable models. Some modes of failure may occur without detection.
Example 3.26 is a simple model that illustrates how the command works. The run stops at F = 1.00.
Figure 3.51 shows shear strain as well as velocity, which allows the user to see that the failure
would be in the continuum instead of on the joint surfaces.

3DEC Version 4.1
204

PROBLEM SOLVING WITH 3DEC

3 - 115

It is recommended that the SOLVE fos command be given at an equilibrium state of a model (to
improve solution time), but this is not essential.
The procedure used by 3DEC during execution of SOLVE fos is as follows. First the code finds
a “representative number of steps” (denoted by Nr ), which characterizes the response time of the
system. Nr is found by setting the cohesion to a large value, making a large change to the internal
stresses, and finding how many steps are necessary for the system to return to equilibrium. Then
for a given factor of safety, F , Nr steps are executed. If the unbalanced force ratio is less than 10−5 ,
then the system is in equilibrium. If the unbalanced force ratio is greater than 10−5 , then another
Nr steps are executed, exiting the loop if the force ratio is less than 10−5 . The mean value of force
ratio, averaged over the current span of Nr steps, is compared with the mean force ratio over the
previous Nr steps. If the difference is less than 10%, the system is deemed to be in non-equilibrium,
and the loop is exited with the new non-equilibrium F . If the above-mentioned difference is greater
than 10%, blocks of Nr steps are continued until: (1) the difference is less than 10%; or (2) 6 such
blocks have been executed; or (3) the force ratio is less than 10−5 . The justification for case (1) is
that the mean force ratio is converging to a steady value that is greater than that corresponding to
equilibrium; the system must be in continuous motion.
The default settings of the SOLVE fos command will adjust the strength parameters of friction and
cohesion for Mohr-Coulomb type failure in both the zones and the joints. If the constitutive model
does not use a Mohr-Coulomb type failure, this process will not apply (i.e., the CY joint model
will not produce a factor of safety using this command). Currently this technique may not be used
with DLL zone or joint models. There is an option to include tensile strength in the calculations
for either the zones or the joints.
The user may also exclude certain material types from inclusion in the factor-of-safety calculations.
(Such an exclusion will not apply to properties that have been assigned using the ZONE or JOINT
command.)
Example 3.26 Factor-of-safety calculation for a simple joint model
new
poly brick 0 20 0 1 0 12
jset dip 0 dd 180 or 0 0 2
hide dip 0 dd 180 or 0 0 2 below
jset dip 45 dd 270 or 12 0 12
hide dip 45 dd 270 or 12 0 12 below
del
seek
jset dip 60 dd 90 or 14 0 12 spac 3.6 num 10
jset dip 20 dd 270 or 20 0 12 spac 2.2 num 10
gen edge .7
change cons 2
prop mat 1 dens 2000.0
prop mat 1 bulk 1.0e8 shear 3.0e7 bcohesion 1e20
prop mat 1 bfriction 20.0 bdilation 20.0 btens 1e10

3DEC Version 4.1
205

3 - 116

User’s Guide

prop jmat 1 jkn 1e10 jks 1e9 jfric 30 jcoh 1e20
gravity 0,0 -10.0
boun zvel 0 range z 0
boun xvel 0 range z 0
boun xvel 0 range x 20
boun xvel 0 range x 0
boun yvel 0 range y 0
boun yvel 0 range y 1
damp auto
solve
prop jmat 1 jcoh 1e4
prop mat 1 bcoh 12380.0
solve fos associated
ret

Figure 3.51 Plot showing area of failure in slope

3DEC Version 4.1
206

PROBLEM SOLVING WITH 3DEC

3 - 117

3.11 Modeling Methodology
3.11.1 Modeling of Data-Limited Systems
In a field such as geomechanics, where data is not always available, the methodology used in
numerical modeling should be different from that used in a field such as mechanical engineering.
Starfield and Cundall (1988) provide suggestions for an approach to modeling that is appropriate
for a data-limited system. This paper should be consulted before any serious modeling with 3DEC
is attempted. In essence, the approach recognizes that field data (such as in-situ stresses, material
properties and geological features) will never be known completely. It is futile to expect the model
to provide design data (such as expected displacements) when there is massive uncertainty in the
input data. However, a numerical model is still useful in providing a picture of the mechanisms
that may occur in particular physical systems. The model acts to educate the intuition of the design
engineer by providing a series of cause-and-effect examples. The models may be simple, with
assumed data that is consistent with known field data and engineering judgement. It is a waste of
effort to construct a very large and complicated model that may be just as difficult to understand as
the real case.
Of course, if extensive field data is available, then these may be incorporated into a comprehensive
model that can yield design information directly. More commonly, however, the data-limited
model does not produce such information directly, but provides insight into mechanisms that may
occur. The designer can then do simple calculations, based on these mechanisms, that estimate the
parameters of interest or the stability conditions.
3.11.2 Modeling of Chaotic Systems
In some calculations, especially in those involving discontinuous materials, the results can be
extremely sensitive to very small changes in initial conditions, or trivial changes in loading sequence.
At first glance, this situation may seem unsatisfactory, and may be taken as a reason to mistrust the
computer simulations. However, the sensitivity exists in the physical system being modeled. There
appear to be a least two sources for the seemingly erratic behavior:
1. There are certain geometric patterns of discontinuities that force the system to
choose (apparently at random) between two alternative outcomes; the subsequent evolution depends on which choice is made. For example, Figure 3.52
illustrates a small portion of a jointed rock mass. If block A is forced to move
down relative to B, it can either go to the left or to the right of B; the choice
will depend on microscopic irregularities in geometry, properties or kinetic
energy.

3DEC Version 4.1
207

3 - 118

User’s Guide

A

B

Figure 3.52 A small portion of a jointed rock mass
2. There are processes in the system that can be described as “softening” or, more
generally, as cases of positive feedback. In a fairly uniform stress field, small
perturbations are magnified in the subsequent evolution because when a region
has more strain, it softens more and thereby attracts more strain, and so on, in
a cycle of positive feedback.
Both phenomena give rise to behavior that is chaotic in its extreme form (Gleick 1987, and Thompson
and Stewart 1986). The study of chaotic systems reveals that the detailed evolution of such a system
is not predictable, even in principle. The observed sensitivity of the computer model to small changes
in initial conditions or numerical factors is simply a reflection of a similar sensitivity in the real world
to small irregularities. There is no point in pursuing ever more “accurate” calculations, because the
resulting model is unrepresentative of the real world, where conditions are not perfect. What should
our modeling strategy be in the face of a chaotic system? It appears that the best we can expect
from such a model is a finite spectrum of expected behavior; the statistics of a chaotic system are
well-defined. We need to construct models that contain distributions of initial irregularities (e.g.,
by using 3DEC ’s adev parameter on the JSET command). Each model should be run several times,
with different distributions of irregularities. Under these conditions, we may expect the fluctuations
in behavior to be triggered by the imposed irregularities, rather than by artifacts of the numerical
solution scheme. We can express the results in a statistical form.

3DEC Version 4.1
208

PROBLEM SOLVING WITH 3DEC

3 - 119

3.11.3 Localization, Physical Instability and Path-Dependence
In many systems that can be modeled with 3DEC, there may be several paths that the solution
may take, depending on rather small changes in initial conditions. This phenomenon is termed
bifurcation. For example, a shear test on an elastic/plastic material may either deform uniformly,
or it may exhibit shear bands, in which the shear strain is localized rather than being uniformly
distributed. It appears that if a numerical model has enough degrees of freedom (i.e., enough
elements), then localization is to be expected. Indeed, theoretical work on the bifurcation process
(e.g., Rudnicki and Rice 1975, and Vardoulakis 1980) shows that shear bands form even if the
material does not strain-soften, provided that the dilation angle is lower than the friction angle. The
“simple” Mohr-Coulomb material should always exhibit localization if enough elements exist to
resolve one or more localized bands. A strain-softening material is more prone to produce bands.
Some computer programs appear incapable of reproducing band formation, although the phenomenon is to be expected physically. However, 3DEC is able to allow bands to develop and
evolve, partly because it models the dynamic equations of motion (i.e., the kinetic energy that accompanies band formation is released and dissipated in a physically realistic way). Several papers
document the use of two-dimensional FLAC in modeling shear band formation (Cundall 1989, 1990
and 1991). These should be consulted for details concerning the solution process. One aspect that
is not treated well by 3DEC is the thickness of a shear band. In reality, the thickness of a band
is determined by internal features of the material, such as grain size. These features are not built
into 3DEC ’s constitutive models. Hence, the bands in 3DEC collapse down to the smallest width
that can be resolved by the grid: one grid-width if the band is parallel to the grid; or about three
grid-widths if the band cuts across the grid at an arbitrary angle. Although the overall physics of
band formation is modeled correctly by 3DEC, band thickness and band spacing are grid-dependent.
Furthermore, if the strain-softening model is used with a weakening material, the load/displacement
relation generated by 3DEC for a simulated test is strongly grid-dependent. This is because the
strain concentrated in a band depends on the width of the band (in length units), which depends on
zone size, as we have seen. Hence, smaller zones lead to more softening, since we move out more
rapidly on the strain axis of the given softening curve. To correct this grid dependence, some sort of
length scale must be built into the constitutive model. There is controversy, at present, concerning
the best way to do this. It is anticipated that future versions of 3DEC will include a length scale in
the constitutive models — probably involving the use of a Cosserat material, in which internal spins
and moments are taken into account. In the meantime, the processes of softening and localization
may be modeled, but it must be recognized that the grid size and angle affect the results; models
must be calibrated for each grid used.
One topic that involves chaos, physical instability and bifurcation is path-dependence. In most
nonlinear, inelastic systems, there are an infinite number of solutions that satisfy equilibrium,
compatibility and the constitutive relations. There is no “correct” solution to the physical problem
unless the path is specified. If the path is not specified, all possible solutions are correct. This
situation can cause endless debate among modelers and users, particularly if a seemingly irrelevant
parameter in the solution process (e.g., damping) is seen to affect the final result. All the solutions
are valid numerically. For example, a simulation of a mining excavation with low damping may
show a large overshoot, and, hence, large final displacements, while high damping will eliminate
the overshoot and give lower final displacements. Which one is more realistic? It depends on the
path. If the excavation is done by explosion (i.e., suddenly), then the solution with overshoot may

3DEC Version 4.1
209

3 - 120

User’s Guide

be the appropriate one; if the excavation is done by pick and shovel (i.e., gradually), then the second
case may be more appropriate. For cases in which path-dependence is a factor, modeling should
be done in a way that mimics the way the system evolves physically.

3DEC Version 4.1
210

PROBLEM SOLVING WITH 3DEC

3 - 121

3.12 References
Bandis, S. C., A. C. Lumsden and N. R. Barton. “Fundamentals of Rock Joint Deformation,” Int.
J. Rock Mech. Min. Sci. & Geomech. Abstr., 20(6), 249-268 (1983).
Barton, N. “The Shear Strength of Rock and Rock Joints,” Int. J. Rock Mech. Min. Sci. & Geotech.
Abstr., 13, 255-279 (1976).
Bieniawski, Z. T. “Determining Rock Mass Deformability: Experience from Case Histories,” Int.
J. Rock Mech. Min. Sci., 15, 237-247 (1978).
Board, M., E. Chacon, P. Varona and L. Lorig. “Comparative Analysis of Toppling Behaviour at
Chuquicamata Open-Pit Mine, Chile,” Trans. Instn. Min. Metall., Sec. A, 105, A11-A21, 1996.
Brady, B. H. G., and E. T. Brown. Rock Mechanics for Underground Mining. London: George
Allen and Unwin., 1985.
Brady, B. H. G., J. V. Lemos and P. A. Cundall. “Stress Measurement Schemes for Jointed and
Fractured Rock,” in Rock Stress and Rock Stress Measurements, pp. 167-176. Luleå, Sweden:
Centek Publishers, 1986.
Clark, I. H. “The Cap Model for Stress Path Analysis of Mine Backfill Compaction Processes,” in
Computer Methods and Advances in Geomechanics, Vol. 2, pp. 1293-1298. Rotterdam: A. A.
Balkema, 1991.
Cundall, P. A. “Numerical Experiments on Localization in Frictional Material,” Ingenieur-Archiv,
59, 148-159 (1988).
Cundall, P. A. “Numerical Modelling of Jointed and Faulted Rock,” in Mechanics of Jointed and
Faulted Rock, pp. 11-18. Rotterdam: A. A. Balkema, 1990.
Cundall, P. A. “Shear Band Initiation and Evolution in Frictional Materials,” in Mechanics Computing in 1990s and Beyond (Proceedings of the Conference, Columbus, Ohio, May, 1991), Vol.
2: Structural and Material Mechanics, pp. 1279-1289. New York: ASME, 1991.
Fossum, A. F. “Technical Note: Effective Elastic Properties for a Randomly Jointed Rock Mass,”
Int. J. Rock Mech. Min. Sci. & Geomech. Abstr., 22(6), 467-470 (1985).
Gerrard, C. M. “Elastic Models of Rock Masses Having One, Two and Three Sets of Joints,” Int.
J. Rock Mech. Min. Sci. & Geomech. Abstr., 19, 15-23 (1982b).
Gerrard, C. M. “Equivalent Elastic Moduli of a Rock Mass Consisting of Orthorhombic Layers,”
Int. J. Rock Mech. Min. Sci. & Geomech. Abstr., 19, 9-14 (1982a).
Gleick, J. Chaos: Making a New Science. New York: Penguin Books, 1987.
Goodman, R. E. Introduction to Rock Mechanics. New York: John Wiley and Sons, 1980.
Hart, R. D. “An Introduction to Distinct Element Modeling for Rock Engineering,” in Comprehensive Rock Engineering, Vol. 2, pp. 245-261. Oxford: Pergamon Press, Ltd., 1993.

3DEC Version 4.1
211

3 - 122

User’s Guide

Hoek, E. “Estimating Mohr-Coulomb Friction and Cohesion Values from the Hoek-Brown Failure
Criterion,” Int. J. Rock Mech. Min. Sci. & Geomech. Abstr., 27(3), 227-229 (1990).
Hoek, E., and E. T. Brown. “The Hoek-Brown Failure Criterion — a 1988 Update,” in Rock
Engineering for Underground Excavations, pp. 31-38. Toronto: University of Toronto, 1988.
Hoek, E., and E. T. Brown. Underground Excavations in Rock. London: Instn. Min. Metall.,
1980.
Huang, X., B. C. Haimson, M. E. Plesha and X. Qiu. “An Investigation of the Mechanics of Rock
Joints — Part I. Laboratory Investigation,” Int. J. Rock Mech. Min. Sci. & Geomech. Abstr., 30,
257-269 (1993).
Jaeger, J. C., and N. G. W. Cook. Fundamentals of Rock Mechanics, 2nd Ed. London: Chapman
and Hall, 1969.
Jing, L., E. Nordlund and O. Stephansson. “An Experimental Study on the Anisotropy and StressDependency of the Strength and Deformability of Rock Joints,” Int. J. Rock Mech. Min. Sci. &
Geomech. Abstr., 29, 535-542 (1992).
Kulhawy, Fred H. “Stress Deformation Properties of Rock and Rock Discontinuities,” Engineering
Geology, 9, 327-350 (1975).
Lindner, E. N., and J. A. Halpern. “In-Situ Stress in North America: A Compilation,” Int. J. Rock
Mech. Min. Sci. & Geomech. Abstr., 15, 183-203 (1978).
Lorig, L. J., and B. H. G. Brady. “An Improved Procedure for Excavation Design in Stratified
Rock,” in Rock Mechanics — Theory-Experiment-Practice, pp. 577-586. New York: Association
of Engineering Geologists, 1983.
Müller, B., M. L. Zoback, K. Fuchs, L. Mastin, S. Gregersen, N. Pavoni, O. Stephansson and C.
Ljunggren. “Regional Patterns of Tectonic Stress In Europe,” J. Geophys. Res., 97(B8), 1178311803 (1992).
Rosso, R. S. “A Comparison of Joint Stiffness Measurements in Direct Shear, Triaxial Compression,
and In-Situ,” Int. J. Rock Mech. Min. Sci. & Geomech. Abstr., 13, 167-172 (1976).
Rudnicki, J. W., and J. R. Rice. “Conditions for the Localization of the Deformation in PressureSensitive Dilatant Materials,” J. Mech. Phys. Solids, 23, 371-394 (1975).
Serafim, J. L., and J. P. Pereira. “Considerations of the Geomechanical Classification of Bieniawski,”
in Proceedings of the International Symposium on Engineering Geology and Underground Construction Lisbon 1983, Vol. 1, pp. II.33-42. Lisbon: SPGILNEC, 1983.
Singh, B. “Continuum Characterization of Jointed Rock Masses: Part I — The Constitutive Equations,” Int. J. Rock Mech. Min. Sci. & Geomech. Abstr., 10, 311-335 (1973).
Souley, M., F. Homand and B. Amadei. “An Extension to the Saeb and Amadei Constitutive Model
for Rock Joints to Include Cyclic Load Paths,” Int. J. Rock Mech. Min. Sci. & Geomech. Abstr.,
32, 101-109 (1995).

3DEC Version 4.1
212

PROBLEM SOLVING WITH 3DEC

3 - 123

Starfield, A. M., and P. A. Cundall. “Towards a Methodology for Rock Mechanics Modelling,” Int.
J. Rock Mech. Min. Sci. & Geomech. Abstr., 25(3), 99-106 (1988).
Thompson, J. M. T., and H. B. Stewart. Nonlinear Dynamics and Chaos. New York: John Wiley
and Sons, 1986.
Vardoulakis, I. “Shear Band Inclination and Shear Modulus of Sand in Biaxial Tests,” Int. J. Numer.
Anal. Meth. in Geomechanics, 4, 103-119 (1980).
Vermeer, P. A., and R. de Borst. “Non-Associated Plasticity for Soils, Concrete and Rock,” Heron,
29(3), 3-64 (1984).

3DEC Version 4.1
213

3 - 124

3DEC Version 4.1
214

User’s Guide

FISH BEGINNER’S GUIDE

4-1

4 FISH BEGINNER’S GUIDE
4.1 Introduction and Overview
FISH is a programming language embedded within 3DEC that enables the user to define new
variables and functions. These functions may be used to extend 3DEC ’s usefulness or add userdefined features. For example, new variables may be plotted or printed, special model generators
may be implemented, servo-control may be applied to a numerical test, unusual distributions of
properties may be specified, and parameter studies may be automated.
FISH was developed in response to requests from users who wanted to do things with Itasca
software that were either difficult or impossible to do with existing program structures. Rather
than incorporate many new and specialized features into the standard code, it was decided that an
embedded language would be provided so that users could write their own functions. Some useful
FISH functions have already been written; a library of these is provided with the 3DEC program
(see Section 3 in the FISH volume). It is possible for someone without experience in programming
to write simple FISH functions or to modify some of the simpler existing functions. Section 4.2
contains an introductory tutorial for non-programmers. However, FISH programs can also become
very complicated (which is true of code in any programming language); for more details, refer to
Section 2 in the FISH volume.
As with all programming tasks, FISH functions should be constructed in an incremental fashion,
checking operations at each level before moving on to more complicated code. FISH does less
error-checking than most compilers, so all functions should be tested on simple data sets before
they are used for real applications.
FISH programs are simply embedded in a normal 3DEC data file — lines following the word DEFINE
are processed as a FISH function; the function terminates when the word END is encountered.
Functions may invoke other functions, which may invoke others, and so on. The order in which
functions are defined does not matter as long as they are all defined before they are used (e.g.,
invoked by a 3DEC command). Since the compiled form of a FISH function is stored in 3DEC ’s
memory space, the SAVE command saves the function and the current values of associated variables.
A complete definition of FISH language rules and intrinsic functions is provided in Section 2 in the
FISH volume. This includes rules for syntax, data types, arithmetic, variables and functions. All
FISH language names are described in Section 2 in the FISH volume.

3DEC Version 4.1
215

4-2

User’s Guide

4.2 Tutorial
This section is intended for people who have run 3DEC (at least for simple problems) but have
not used the FISH language; no programming experience is assumed. To get the maximum benefit
from the examples given here, you should try them out with 3DEC running interactively. The short
programs may be typed in directly. After running an example, give the 3DEC command NEW to
“wipe the slate clean,” ready for the next example. Alternatively, the more lengthy programs may
be created on file and CALLed when required.
Type the lines in Example 4.1 after 3DEC ’s command prompt, pressing  at the end of
each line.
Example 4.1 Defining a FISH function
def abc
abc = 22 * 3 + 5
end

Note that the command prompt changes to Def> after the first line has been typed in; then it
changes back to the usual prompt when the command END is entered. This change in prompt lets
you know whether you are sending lines to 3DEC or to FISH. Normally, all lines following the
DEFINE statement are taken as part of the definition of a FISH function (until the END statement is
entered). However, if you type in a line that contains an error (e.g., you type the = sign instead of
the + sign), then you will get the 3DEC prompt back again. When this happens, you should give
the NEW command and try again from the beginning. Since it is very easy to make mistakes, FISH
programs are normally typed into a file using an editor. These are then CALLed into 3DEC just
like a regular 3DEC data file. We will describe this process later; for now, we’ll continue to work
interactively. Assuming that you typed in the preceding lines without error and that you now see
the 3DEC prompt 3Dec>, you can “execute” the function abc* (defined earlier in Example 4.1)
by typing the line
list @abc

The message
abc =

71

should appear on the screen. By defining the symbol abc (using the DEFINE ... END construction,
as in Example 4.1), we can now refer to it in many ways using 3DEC commands.
For example, the LIST command causes the value of a FISH symbol to be displayed; the value is
computed by the series of arithmetic operations in the line
abc = 22 * 3 + 5

* We will use courier boldface to identify user-defined FISH functions and declared variables
in the text.

3DEC Version 4.1
216

FISH BEGINNER’S GUIDE

4-3

This is an “assignment statement.” If an equal sign is present, the expression on the right-hand side
of the equal sign is evaluated and given to the variable on the left-hand side. Note that arithmetic
operations follow the usual conventions: addition, subtraction, multiplication and division are done
with the signs +, -, * and /, respectively. The sign ˆ denotes “raised to the power of.”
We now type in a slightly different program (using the NEW command to erase the old one):
Example 4.2 Using a variable
new
def abc
hh = 22
abc = hh * 3 + 5
end

Here we introduce a “variable,” hh, which is given the value of 22 and then used in the next line.
If we give the command LIST abc, then exactly the same output as in the previous case appears.
However, we now have two FISH symbols; they both have values, but one (abc) is known as a
“function” and the other (hh) as a “variable.” The distinction is:
When a FISH symbol name is mentioned (e.g., in a LIST statement),
the associated function is executed if the symbol corresponds to a
function. However, if the symbol is not a function name, then the
current value of the symbol is used.
The following experiment may help to clarify the distinction between variables and functions.
Before doing the experiment, note that 3DEC ’s SET command can be used to set the value of any
user-defined FISH symbol, independent of the FISH program in which the symbol was introduced.
Now type in the following lines without giving the NEW command, since we want to keep our
previously entered program in memory.
Example 4.3 SETting variables
set @abc=0 @hh=0
list @hh
list @abc
list @hh

The SET command sets the values of both abc and hh to zero. Since hh is a variable, the first
LIST command simply displays the current value of hh, which is zero. The second LIST command
causes abc to be executed (since abc is the name of a function); the values of both hh and abc
are thereby recalculated. Accordingly, the third LIST statement shows that hh has indeed been
reset to its original value. As a test of your understanding, you should type in the slightly modified
sequence shown in Example 4.4 and figure out why the displayed answers are different.

3DEC Version 4.1
217

4-4

User’s Guide

Example 4.4 Test your understanding of function and variable names
new
def abc
abc = hh * 3 + 5
end
set @hh=22
list @abc
set @abc=0 @hh=0
list @hh
list @abc
list @hh

At this stage, it may be useful to list the most important 3DEC commands that directly refer to simple
FISH variables or functions. (In Table 4.1, var stands for the name of the variable or function.)
Table 4.1 Commands that directly
refer to FISH names
LIST
SET
HISTORY

var
var = value
var

We have already seen examples of the first two (refer to Examples 4.3 and 4.4); the third case is
useful when histories are required of things that are not provided in the standard 3DEC list of history
variables. Example 4.5 shows how this can be done:
Example 4.5 Capturing the history of a FISH variable
new
poly brick 0,10 0,10 0,10
gen edge 10
prop mat=1 dens 1000 k 1e9 g 0.7e9
bound zvel 0.0 range z -0.01,0.01
grav 0 0 -10
def stress_z
zoneIdx = b_zone(block_head)
stress_z = z_szz(zoneIdx)
end
hist @stress_z
cyc 200
pl his 1

3DEC Version 4.1
218

FISH BEGINNER’S GUIDE

4-5

In this example, a history of the vertical stress in one zone is recorded. The symbols b zone(),
block head and z syy() are pre-defined names that permit access to 3DEC ’s data structures. We
obtained the index of the first zone in the one block in our model. With that index we can access a
number of parameters associated with that zone. In this case, we have accessed the vertical stress
and monitored its change in a history.
In addition to the above-mentioned pre-defined variable names, there are many other pre-defined
objects available to a FISH program. These fall into several classes; one such class consists of
scalar variables, which are single numbers — for example:

clock

clock time in hundredths of a second

pi

π

step

current step number

unbal

maximum unbalanced force

urand

random number drawn from uniform distribution between
0.0 and 1.0.

This is just a small selection; the full list is given in Section 2.5 in the FISH volume.
Another useful class of built-in objects is the set of intrinsic functions, which enables things like
sines and cosines to be calculated from within a FISH program. A complete list is provided in
Section 2.5 in the FISH volume; a few are given below:

abs(a)

absolute value of a

cos(a)

cosine of a (a is in radians)

log(a)

base-ten logarithm of a

max(a,b)

returns maximum of a, b

sqrt(a)

square root of a

An example in the use of intrinsic functions will be presented later, but now we must discuss one
more way a 3DEC data file can make use of user-defined FISH names:
Wherever a number is expected in a 3DEC input line, you may
substitute the name of a FISH variable or function.
This simple statement is the key to a very powerful feature of FISH that allows such things as
ranges, applied stresses, properties, etc. to be computed in a FISH function and used by 3DEC
input in symbolic form. Hence, parameter changes can be made very easily, without needing to
change many numbers in an input file.
As an example, let us assume that we know the Young’s modulus and Poisson’s ratio of a material.
Although properties may be specified using Young’s modulus and Poisson’s ratio, internally 3DEC

3DEC Version 4.1
219

4-6

User’s Guide

uses the bulk and shear moduli, we may derive these with a FISH function, using Eqs. (4.1) and
(4.2):
G=

E
2(1 + ν)

(4.1)

K=

E
3(1 − 2ν)

(4.2)

Coding Eqs. (4.1) and (4.2) into a FISH function (called derive) can then be done as shown in
Example 4.6:
Example 4.6 FISH functions to calculate bulk and shear moduli
new
def derive
s_mod = y_mod / (2.0 * (1.0 + p_ratio))
b_mod = y_mod / (3.0 * (1.0 - 2.0 * p_ratio))
end
set @y_mod = 5e8 @p_ratio = 0.25
@derive
list @b_mod @s_mod

Note that, here, we execute the function derive by giving its name by itself on a line; we are
not interested in its value, only what it does. If you run this example, you will see that values are
computed for the bulk and shear moduli, b mod and s mod, respectively. These can then be used,
in symbolic form, in 3DEC input as shown in Example 4.7:
Example 4.7 Using symbolic variables in 3DEC input
poly brick -1,1 -1,1 -1,1
jset
gen edge 1
prop mat 1 density = 2000 k =@b_mod g = @s_mod
list property block

The validity of this operation may be checked by printing the bulk and shear moduli with the LIST
property block command. In these examples, our property input is given via the SET command
— i.e., to variables y mod and p ratio, which stand for Young’s modulus and Poisson’s ratio,
respectively.
Note that there is great flexibility in choosing names for FISH variables and functions; the underline
character ( ) may be included in a name. Names must begin with a non-number and must not contain

3DEC Version 4.1
220

FISH BEGINNER’S GUIDE

4-7

any of the arithmetic operators (+, –, /, * or ˆ). A chosen name should not be the same as one of the
built-in (or reserved) names; Section 2.2.2 in the FISH volume contains a complete list of names
to be avoided, as well as some rules that should be followed.
In the preceding examples, we checked the computed values of FISH variables by giving their
names explicitly as arguments to a LIST command. Alternatively, we can list all current variables
and functions. A printout of all current values, sorted alphabetically by name, is produced by giving
the command
list fish

We now examine ways in which decisions can be made, and repeated operations done, in FISH
programs. The following FISH statements allow specified sections of a program to be repeated
many times:

LOOP

var (expr1, expr2)

ENDLOOP
The words LOOP and ENDLOOP are FISH statements, the symbol var stands for the loop variable,
and expr1 and expr2 stand for expressions (or single variables). Example 4.8 shows the use of a
loop (or repeated sequence) to produce the sum and product of the first 10 integers:
Example 4.8 Controlled loop in FISH
new
def xxx
sum = 0
prod = 1
loop n (1,10)
sum = sum + n
prod = prod * n
endloop
end
@xxx
list @sum, @prod

In this case, the loop variable n is given successive values from 1 to 10, and the statements inside
the loop (between the LOOP and ENDLOOP statements) are executed for each value. As mentioned,
variable names or an arithmetic expression could be substituted for the numbers 1 or 10.
A practical use of the LOOP construct is to install a nonlinear initial distribution of elastic moduli
in a 3DEC model. Suppose that the Young’s modulus at a site is given by Eq. (4.3),
√
E = E◦ + c y

(4.3)

3DEC Version 4.1
221

4-8

User’s Guide

where y is the depth below surface, and c and E◦ are constants. We write a FISH function to install
appropriate values of bulk and shear modulus in the model, as in Example 4.9:
Example 4.9 Applying a nonlinear initial distribution of moduli
new
poly
plot
plot
jset
jset

brick 0,30 0,30 -30,0
blockcolorby mat
reset
dip 36 dd 270 spac 6
dip -58 dd 270 spac 6

num 20
num 20

def install
iprop = 0
loop while iprop < 7
iprop = iprop + 1
z_depth1 = (float(iprop) - 1.0) * 5.0
z_depth2 = z_depth1 + 5.0
y_mod = z_zero + cc * sqrt((z_depth1 + z_depth2) / 2.0)
command
prop mat = @iprop ymod = @y_mod
prop mat = @iprop prat = 0.25 dens = 2000
endcommand
bi = block_head
loop while bi # 0
z_depth = float(-b_z(bi))
if z_depth > z_depth1 then
if z_depth <= z_depth2 then
b_mat(bi) = iprop
endif
endif
bi = b_next(bi)
endloop
endloop
end
set @z_zero = 1e7 @cc = 1e8
@install
ret

Having seen several examples of FISH programs, let’s briefly examine the question of program
syntax and style. A complete FISH statement must occupy one line; there are no continuation lines.
If a formula is too long to fit on one line, then a temporary variable must be used to split the formula.
Example 4.10 shows how this can be done.

3DEC Version 4.1
222

FISH BEGINNER’S GUIDE

4-9

Example 4.10 Splitting lines
new
def long_sum ;example of a sum of many things
temp1 = v1 + v2 + v3 + v4 + v5 + v6 + v7 + v8 + v9 + v10
long_sum = temp1 + v11 + v12 + v13 + v14 + v15
end

In this case, the sum of 15 variables is split into two parts. Also note the use of the semicolon in line
1 of Example 4.10 to indicate a comment. Any characters that follow a semicolon are ignored by
the FISH compiler, but they are echoed to the log file. It is good programming practice to annotate
programs with informative comments. Some of the programs have been shown with indentation
(i.e., space inserted at the beginning of some lines to denote a related group of statements). Any
number of space characters may be inserted between variable names and arithmetic operations to
make the program more readable. Again, it is good programming practice to include indentation
to indicate things like loops, conditional clauses, etc. Spaces in FISH are “significant” in the sense
that space characters may not be inserted into a variable or function name.
One other topic that should be addressed now is that of variable type. You may have noticed when
printing out variables from the various program examples, that a number is either printed without
decimal points or in “E-format” — that is, as a number with an exponent denoted by “E.” At
any instant in time, a FISH variable or function name is classified as one of three types: integer,
floating-point or string. These types may change dynamically, depending on context, but the casual
user should not normally have to worry about the type of a variable, since it is set automatically.
Consider Example 4.11:
Example 4.11 Variable types
new
def haveone
aa = 2
bb = 3.4
cc = ’Have a nice day’
dd = aa * bb
ee = cc + ’, old chap’
end
@haveone
list fish

3DEC Version 4.1
223

4 - 10

User’s Guide

The resulting screen display looks like this:
Name
------aa
bb
cc
dd
ee
(function) haveone

Value
-------------------2 (integer)
3.4 (real)
’Have a nice day’ (string)
6.8 (real)
’Have a nice day, old chap’ (string)
0 (integer)

The variables aa, bb and cc are converted to integer, float and string, respectively, corresponding
to the numbers (or strings) that were assigned to them. Integers are exact numbers (without decimal
points) but are of limited range; floating-point numbers have limited precision (about six decimal
places) but are of much greater range; string variables are arbitrary sequences of characters. There
are various rules for conversion between the three types. For example, dd becomes a floating-point
number because it is set to the product of a floating-point number and an integer; the variable ee
becomes a string because it is the sum (concatenation) of two strings. The topic can get quite
complicated, but it is fully explained in Sections 2.2.4 and 2.4.1 in the FISH volume.
There is another language element in FISH that is commonly used: the IF statement. The following
three statements allow decisions to be made within a FISH program:

IF

expr1 test expr2 THEN

ELSE
ENDIF
These statements allow conditional execution of FISH program segments (ELSE and THEN are
optional). The item test consists of one of the following symbols or symbol-pairs:
=

#

>

<

>=

<=

The meanings are standard except for #, which means “not equal.” The items expr1 and expr2
are any valid expressions or single variables. If the test is true, then the statements immediately
following IF are executed until ELSE or ENDIF is encountered. If the test is false, the statements
between ELSE and ENDIF are executed if the ELSE statement exists; otherwise, the program jumps
to the first line after ENDIF. The action of these statements is illustrated in Example 4.12.

3DEC Version 4.1
224

FISH BEGINNER’S GUIDE

4 - 11

Example 4.12 Action of the IF ELSE ENDIF construct
new
def abc
if xx >
abc =
else
abc =
end_if
end
set @xx =
list @abc
set @xx =
list @abc

0 then
33
11

1
-1

The displayed value of abc in Example 4.12 depends on the set value of xx. You should experiment
with different test symbols (e.g., replace > with <).
Until now, our FISH programs have been invoked from 3DEC either by using the LIST command,
or by giving the name of the function on a separate line of 3DEC input. It is also possible to do the
reverse: to give 3DEC commands from within a FISH function. Most valid 3DEC commands can
be embedded between the following two FISH statements:

COMMAND
ENDCOMMAND
There are two main reasons for sending out 3DEC commands from a FISH program. First, it is
possible to use a FISH function to perform operations that are not possible using the pre-defined
variables that we already discussed. Second, we can control a complete 3DEC run with FISH.

3DEC Version 4.1
225

4 - 12

3DEC Version 4.1
226

User’s Guide

GRAPHICAL INTERFACE

5-1

5 GRAPHICAL INTERFACE
The user interface for 3DEC is now described in detail in a compiled help file that is accessible from
the 3DEC ’s Help menu (select the item “3DEC User Interface”). The help file provides complete
documentation on the interface, its tools, and the methods for completing common tasks in 3DEC.
The file is comprised of six main sections: Menus and Toolbars, Data View, Model View, Plot
Items and Ranges, Program Options and How-To. In addition, the file contains a page on 3DEC
terminology, which gives explanations of frequently used terms. The documentation is provided in
this format to give fast access to information that can help with interface-related questions.

3DEC Version 4.1
227

5-2

3DEC Version 4.1
228

User’s Guide

MISCELLANEOUS

6-1

6 MISCELLANEOUS
6.1 3DEC Runtime Benchmark
3DEC has been tested on a number of different computers. The calculation rates are compared here
for the following benchmark problem: a cubic model that contains 125 blocks subject to applied
pressure boundary conditions. The timing test is made for both a rigid block analysis (with 1000
vertices) and a deformable block analysis (with 750 zones and 1000 gridpoints). The model is run
for 1000 steps, and the rate is calculated by a FISH function. The data file is given in Example 6.1.
Table 6.1 summarizes the calculation rates for different computers:
Table 6.1

3DEC runtime calculation rates

CPU
AMD Athlon 2800+
Intel Pentium 4
Intel Pentium 4
AMD Athlon 4200+ DC
Intel Pentium D 950 DC
Intel Xeon
Intel Core 2 T7200 Mobile
Intel Xeon 5160 DC

GHz
1.8
2.8
3.0
2.2
3.4
3.6
2.0
3.0

sec/gp/1000 steps
0.0149
0.0100
0.0093
0.0086
0.0083
0.0075
0.0069
0.0052

3DEC Version 4.1
229

6-2

User’s Guide

Example 6.1 Benchmark data file — “TIMING.DAT”
def _variables
t0 = 0
t1 = 0
end
@_variables
def rate
rate = (t1 - t0) / (1000)
end
define prate
ii = out(’rate = ’ + string(rate) + ’ (sec/gp/1000steps)’)
end
def time_0
t0 = clock / 100.0
end
def time_1
t1 = clock / 100.0
end
;
poly brick 0,10 0,10 0,10
jset dip 0 dd 180 spac 2 num 20
jset dip 90 dd 180 spac 2 num 20
jset dip 90 dd 90 spac 2 num 20
prop jmat 1 jkn 1e9 jks 1e9 fric 45.0
;
; for deformable block model
gen edge 4.0
prop mat 1 dens 1000
prop mat 1 bulk 1e9 g 7e8
;
bound stress 0 -2e6 0 0 0 0 range x 0,10
y 9.9,10.0 z 0,10
bound stress -2e6 0 0 0 0 0 range x 9.9,10.1 y 0,10
z 0,10
bound stress 0 0 -2e6 0 0 0 range x 0,10
y 0,10
z 9.9,10.1
;
; for deformable block model
bound xvel 0.0 range x -.1,.1 y 0,10
z 0,10
bound yvel 0.0 range x 0,10
y -.1,.1 z 0,10
bound zvel 0.0 range x 0,10
y 0,10
z -.1,.1
; for rigid block model
; apply xvel 0.0 range x 0 2 y 0 10 z 0 10
; apply yvel 0.0 range x 0 10 y 0 2 z 0 10
; apply zvel 0.0 range x 0 10 y 0 10 z 0 2
;

3DEC Version 4.1
230

MISCELLANEOUS

6-3

@time_0
cyc 1000
@time_1
@prate
ret

3DEC Version 4.1
231

6-4

User’s Guide

6.2 Error Reporting
Although 3DEC has been tested extensively, it is almost impossible to test all available combinations
of options in a code as complex as this one. For this reason, some errors may have evaded our
notice. If you discover a genuine bug, please let us know as soon as possible so that we may correct
it.
6.2.1 Reporting via the Internet
Itasca’s current Internet e-mail address is
software@itascacg.com
Please include the same information requested on the error notification form (in Section 6.2.2),
followed by the contents of your data file.
6.2.2 Reporting via Fax
A sample form for you to copy and mail or fax to us is given on the next page. Please fill out the
form completely, as this is the minimum information we will need to find and correct the error. The
sample file should, if possible, contain the minimum number of commands necessary to produce
the error. We may have to contact you for further information if we are unable to duplicate the error.
Be aware that it is always possible that the error is peculiar to your hardware, making it impossible
for us to duplicate.
6.3 Technical Support Service
Itasca and its offices and agents will provide telephone support, at no cost, to assist code owners
with the installation of Itasca codes on their computer systems. Additionally, general assistance
may be provided to aid the owner in understanding the capabilities of the various features of the
code. However, no-cost assistance is not provided for help in applying an Itasca code to specific
user-defined problems.
Questions should, in the first instance, be directed to the office or agent where 3DEC was purchased.

3DEC Version 4.1
232

MISCELLANEOUS

6-5

ERROR NOTIFICATION FORM
Found by:

Phone:

Fax:

Email:
Computer:

RAM:

3DEC Data
Serial No.:

Version*

Options:
Description:

* Type PRINT version to report your complete version number.
Please attach a sample input file that produces the error.
Itasca Consulting Group, Inc.
Mill Place
111 Third Avenue South, Suite 450
Minneapolis, Minnesota 55401 USA

Phone:
Fax:
E-Mail:
Web:

(1) 612-371-4711
(1) 612·371·4717
software@itascacg.com
www.itascacg.com

3DEC Version 4.1
233

6-6

3DEC Version 4.1
234

User’s Guide

BIBLIOGRAPHY

7-1

7 BIBLIOGRAPHY
Adachi, T., Y. Ohnishi and K. Arai. “Investigation of Toppling Slope Failure at Route 305 in
Japan,” in Proceedings of the 7th International Congress on Rock Mechanics (Aachen, Germany,
September, 1991), Vol. 2, pp. 843-846. Rotterdam: A. A. Balkema, 1991.
Aglawe, J. P., and A. G. Corkum. “Application of Distinct Element Analysis in Slope Stability
Problems,” presented at the Indo-Norwegian Workshop on Seismic Hazard and Risk Assessment
(New Delhi, India, March 2006).
Ahmadi, M., K. Goshtasbi and R. Ashjari. “Numerical Analyses of Masjed-E-Soleiman Powerhouse
Cavern, Iran,” in The Second Half Century of Rock Mechanics (11th Congress of the International
Society for Rock Mechanics, Lisbon, July 2007), Vol. 2, pp. 951-954. L. Ribeiro e Sousa, C. Olalla
and N. Grossmann, eds. London: Taylor & Francis Group, 2007.
Al-Harthi, A., and S. Hencher. “Physical and Numerical Modelling of Underground Excavations
in Dilational Rock Masses,” in Proceedings of the ISRM Regional Conference on Fractured and
Jointed Rock Masses (Lake Tahoe, June, 1992), Vol. 3, pp. 608-615. Berkeley, California:
Lawrence Berkeley Laboratory, 1992.
Alfonsi, P., J. L. Durville and X. Rachez. “Modelisation Numerique d’une Fondation sur Versant
Rocheux par la Methode des Elements Distincts: Comparaison 2-D/3-D,” in Proceedings of the
9th ISRM Congress on Rock Mechanics (Paris, 1999), Vol. 1, pp. 71-76. Rotterdam: A. A.
Balkema, 1999.
Andrieux, P., et al. “Determination and Validation of the Rock Mass Post-Peak Mechanical Properties for a 3DEC Strain-Softening Model of the 680 Sill Pillar at Louvicourt Mine,” in Numerical Modeling of Discrete Materials in Geotechnical Engineering, Civil Engineering & Earth
Sciences (1st International UDEC/3DEC Symposium, Bochum, Germany, September 2004),
pp. 121-127. H. Konietzky, ed. Leiden: Balkema, 2004.
Andrieux, P., et al. “Large-Scale Panel Destress Blast at Brunswick Mine,” in Proceedings of the
23rd Study Session on Blasting Techniques (Society of Explosive Engineers of Quebec, Quebec
City, November 2000), pp. 1-21 (2000).
Andrieux, P., R. Brummer and H. Z. Zhu. “Numerical Stress Analyses of Various Mining Sequences
and Geomechanics Considerations at the Falconbridge Kidd #3 Mine – Phase II and Mine D,” Itasca
Consulting Canada Inc., Draft Report to Falconbridge Limited, Kidd Mining Division (2003).
Antikainen, J., A. Simonen and I. Makinen. “3D Modelling of the Central Pillar in the Pyhasalmi
Mine,” in Innovative Mine Design for the 21st Century (Proceedings of the International Congress
on Mine Design, Kingston, Ontario, Canada, August, 1993), pp. 631-640. W. F. Bawden and
J. F. Archibald, eds. Rotterdam: A. A. Balkema, 1993.
Bandis, S. C., N. R. Barton and M. Christianson. “Application of a New Numerical Model of Joint
Behaviour to Rock Mechanics Problems,” in Fundamentals of Rock Joints (Proceedings of the
International Symposium on Fundamentals of Rock Joints, Björkliden, September, 1985),
pp. 345-356. Luleå, Sweden: Centek Publishers, 1985.

3DEC Version 4.1
235

7-2

User’s Guide

Barla, G., M. Borri-Brunetto and G. Gerbaudo. “Physical and Mathematical Modelling of a Jointed
Rock Mass for the Study of Block Toppling,” in Proceedings of the ISRM Regional Conference
on Fractured and Jointed Rock Masses (Lake Tahoe, June, 1992), Vol. 3, pp. 616-623. Berkeley,
California: Lawrence Berkeley Laboratory, 1992.
Baroudi, H., J. P. Piguet, J. P. Josien, I. Arif and P. Lebon. “Modelling of Underground Cavity
Storage and Consideration of Rock Mass Discontinuities,” in Proceedings of the 7th International
Congress on Rock Mechanics (Aachen, Germany, September, 1991), Vol. 2, pp. 1073-1081.
Rotterdam: A. A. Balkema, 1991.
Barton, N. “The Influence of Joint Properties in Modelling Jointed Rock Masses,” in Proceedings
of the 8th International Congress on Rock Mechanics (Tokyo, September 1995), Vol. 3, pp. 10231032. Rotterdam: Balkema, 1997.
Barton, N. “Modelling Jointed Rock Behavior and Tunnel Performance,” World Tunnelling, 4(7),
414-416 (November, 1991).
Barton, N., L. Harvik, M. Christianson, S. Bandis, A. Makurat, P. Chryssanthakis and G. Vik.
“Numerical Analyses and Laboratory Tests to Investigate the Ekofisk Subsidence,” Fjellsprengningsteknikk Bergmekanikk/Geoteknikk, 21.1-21.23, 1985.
Barton, N., L. Harvik, M. Christianson and G. Vik. “Estimation of Joint Deformations, Potential
Leakage and Lining Stresses for a Planned Urban Road Tunnel,” in Large Rock Caverns (Proceedings of the Conference on Large Rock Caverns, Helsinki, 1986), pp. 1171-1182. Oxford:
Pergamon Press, 1985.
Barton, N., R. Lien, F. Løset, T. Löken, E. Grimstad, H. Hansteen, L. Harvik and M. Christianson.
“Methods for Selecting Support in Sub-Sea Rock Tunnels,” Proceedings of the International Symposium on Strait Crossings (Stavanger, Norway, October, 1986), Vol. 2, pp. 715-731. Trondheim,
Norway: Tapir, 1986.
Barton, N., F. Løset, A. Smallwood, G. Vik, C. Rawlings, P. Chryssanthakis, H. Hansteen and T.
Ireland. “Radioactive Waste Repository Design Using Q and UDEC-BB,” in Proceedings of the
ISRM Regional Conference on Fractured and Jointed Rock Masses (Lake Tahoe, June, 1992),
Vol. 3, pp. 735-742. Berkeley, California: Lawrence Berkeley Laboratory, 1992.
Barton, N., A. Makurat, M. Christianson and S. Bandis. “Modelling Rock Mass Conductivity
Changes in Disturbed Zones,” in Rock Mechanics: Proceedings of the 28th U.S. Symposium
(Tucson, June-July, 1987), pp. 563-574. Rotterdam: A. A. Balkema, 1987.
Barton, N., K. Monsen, P. Chryssanthakis and O. Norheim. “Rock Mechanics Design for High
Pressure Gas Storage in Shallow Lined Caverns,” in Storage of Gases in Rock Caverns, pp. 159176. Rotterdam: A. A. Balkema, 1989.
Barton, N., L. Tunbridge, F. Løset, H. Westerdahl, J. Kristiansen, G. Vik and P. Chryssanthakis.
“Norwegian Olympic Ice Hockey Cavern of 60 m Span,” in Proceedings of the 7th International
Congress on Rock Mechanics (Aachen, Germany, September, 1991), Vol. 2, pp. 1073-1081.
Rotterdam: A. A. Balkema, 1991.

3DEC Version 4.1
236

BIBLIOGRAPHY

7-3

Bigarre, P., K. Ben Slimane and J. Tinucci. “3-Dimensional Modelling of Fault-Slip Rockbursting,” in Rockbursts and Seismicity in Mines 93 (Proceedings of the International Symposium,
Kingston, Ontario, Canada, August, 1993), pp. 315-319. R. Paul Young, ed. Rotterdam: A. A.
Balkema, 1993.
Blair, S. C., et al. “Coupled THM Simulations of the Drift Scale Test at Yucca Mountain,” in
NARMS-TAC 2002: Mining and Tunnelling Innovation and Opportunity, Vol. 2, pp. 13831390. R. Hammah et al., eds. Toronto: University of Toronto Press, 2002.
Blair, Stephen C., Steven R. Carlson and Jeffrey L. Wagoner. “Analysis of Geomechanical Behavior
for the Drift Scale Test,” in Proceedings of the 9th International High-Level Radioactive Waste
Management Conference (IHLRWM, Las Vegas, April-May 2001), Paper 08-3. La Grange Park,
Illinois: American Nuclear Society, Inc., 2001.
Blair, Stephen C., Steven R. Carlson and Jeffrey L. Wagoner. “Distinct Element Modeling of the
Drift Scale Test,” in Rock Mechanics in the National Interest (Proceedings of the 38th U. S.
Rock Mechanics Symposium, Washington, D.C., July 2001), Vol.1, pp. 527-531. Lisse, The
Netherlands: Swets & Zeitlinger B. V., 2001.
Board, M. Examination of the Use of Continuum versus Discontinuum Models for Design and
Performance Assessment for the Yucca Mountain Site. U.S. Nuclear Regulatory Commission,
NUREG/CR-5426, August, 1989.
Board, M. “Numerical Examination of Mining-Induced Seismicity,” in EUROCK ‘96 Special
Lectures (ISRM International Symposium on Prediction and Performance in Rock Mechanics
and Rock Engineering, Torino, Italy, September 1996), Vol. 3, pp. 1469-1486. G. Barla, ed.
Rotterdam: Balkema, 2000.
Board, M. UDEC (Universal Distinct Element Code) Version ICG1.5, Vols. 1-3. U.S. Nuclear
Regulatory Commission, NUREG/CR-5429, September 1989.
Board, Mark, Richard Brummer and Shawn Seldon. “Use of Numerical Modeling for Mine Design
and Evaluation,” in Underground Mining Methods: Engineering Fundamentals and International Case Studies, pp. 483-491. W. A. Hustrulid and R. L. Bullock, eds. Littleton, Colorado:
SME, 2001.
Board, M., T. Rorke, G. Williams and N. Gay. “Fluid Injection for Rockburst Control in Deep
Mining,” in Rock Mechanics (Proceedings of the 33rd U.S. Symposium on Rock Mechanics),
pp. 111-120. J. R. Tillerson and W. R. Wawersik, eds. Rotterdam: A. A. Balkema, 1993.
Board, M., S. Seldon, R. Brummer and R. Pakalnis. “Analysis of the Failure of a Large Hangingwall
Wedge: Kidd Mine Division, Falconbridge, Ltd.,” CIM Bull., 93(1043), 89-97 (September 2000).
Borri-Brunetto, M. “A Direct Variational Approach to Static Analysis of Discontinua,” in Second
European Speciality Conference on Numerical Methods in Geotechnical Engineering (Santander, Spain, September, 1990), pp. 33-44, 1990.
Brady, B., and J. Lemos. “Dynamic Analysis of Surface Rock Structures,” in Proceedings of the
2nd Italian Conference on Rock Mechanics and Rock Engineering, 1988.

3DEC Version 4.1
237

7-4

User’s Guide

Brady, B. H., S. H. Hsiung, A. H. Chowdhury and J. Philip. “Verification Studies on the UDEC
Computational Model of Jointed Rock,” in Mechanics of Jointed and Faulted Rock, pp. 551-558.
Rotterdam: A. A. Balkema, 1990.
Brady, B. H. G., M. L. Cramer and R. D. Hart. “Preliminary Analysis of a Loading Test on a Large
Basalt Block,” Int. J. Rock Mech., 22(5), 345-348 (1985).
Brown, E. T. “Block Caving Geomechanics (The International Caving Study I, 1997-2000).
University of Queensland, JKMRC Monograph Series in Mining and Mineral Processing, Vol. 3.
Indooroopilly, Australia: JKMRC, 2003.
Brummer, R. K., C. P. O’Connor and A. Turichshev. “Comprehensive Geomechanical Design of a
Large Underground Observatory at 6800 Ft,” in Golden Rocks 2006 – 50 Years of Rock Mechanics,
Colorado School of Mines (41st U.S. Rock Mechanics Symposium, June 2006), Paper No. 061162. D. P. Yale et al., eds. ARMA, 2006.
Cappa, F., et al. “Hydromechanical Modelling of Pulse Tests That Measure Fluid Pressure and
Fracture Normal Displacement at the Coaraze Laboratory Site, France,” Int. J. Rock Mech. Min.
Sci., 43, 1062-1082 (2006).
Cavieres, P., et al. “Three-Dimensional Analysis of Fracturing Limits Induced by Large Scale
Underground Mining at El Teniente Mine,” in Soil and Rock America 2003 (39th U.S. Rock
Mechanics Symposium, Cambridge, Massachusetts, June 2003), pp. 893-900. P. J. Culligan,
H. H. Einstein and A. J. Whittle, eds. Essen: Verlag Glückauf, 2003.
Chen, S. G., J. G. Cai, J. Zhao and Y. X. Zhou. “3DEC Modeling of a Small-Scale Field Explosion
Test,” in Pacific Rocks 2000: Rock around the Rim (Proceedings of the 4th North American Rock
Mechanics Symposium, Seattle, July-August 2000), pp. 571-576. J. Girard et al., eds. Rotterdam:
A. A. Balkema 2000.
Choi, S. K. “The Application of the Distinct Element Method for Rock Mechanics Problems,” in
Proceedings of the 1st U.S. Conference on Discrete Element Methods (Golden, Colorado, 1989).
G. G. W. Mustoe et al., eds. Golden, Colorado: CSM Press, 1990.
Choi, S. K., and M. A. Coulthard. “Modelling of Jointed Rock Masses Using the Distinct Element
Method,” in Mechanics of Jointed and Faulted Rock, pp. 471-478. Rotterdam: A. A. Balkema,
1990.
Choi, S. O., J. D. Kim and K. S. Kim. “Enlarged Interpretation of Hydrofracturing In-Situ Stress by
3-D Numerical Analysis,” in The Second Half Century of Rock Mechanics (11th Congress of the
International Society for Rock Mechanics, Lisbon, July 2007), Vol. 2, pp. 865-868. L. Ribeiro e
Sousa, C. Olalla and N. Grossmann, eds. London: Taylor & Francis Group (2007).
Christianson, M. Sensitivity of the Stability of a Waste Emplacement Drift to Variation in Assumed
Rock Joint Parameters in Welded Tuff. U.S. Nuclear Regulatory Commission, NUREG/CR-5336,
April, 1989.

3DEC Version 4.1
238

BIBLIOGRAPHY

7-5

Christianson, M., J. Itoh and S. Nakaya. “Seismic Analysis of the 25 Stone Buddhas Group at
Hakone, Japan,” in Rock Mechanics (Proceedings of the 35th U.S. Symposium, University of
Nevada, Reno, June, 1995), pp. 107-112. J. J. K. Daemen and R. A. Schultz, eds. Rotterdam:
A. A. Balkema, 1995.
Christianson, M. C., and B. Brady. Analysis of Alternative Waste Isolation Concepts. U.S. Nuclear
Regulatory Commission, NUREG/CR-5389, June, 1989.
Chryssanthakis, P., and N. Barton. “Predicting Performance of the 62 m Span Ice Hockey Cavern
in Gjøvik, Norway,” in Proceedings of the ISRM Regional Conference on Fractured and Jointed
Rock Masses (Lake Tahoe, June, 1992), Vol. 3, pp. 624-631. Berkeley, California: Lawrence
Berkeley Laboratory, 1992.
Chryssanthakis, P., K. Monsen and N. Barton. “Validation of UDEC-BB Against the CSM Block
Test and Large Scale Application to Glacier Loading of Jointed Rock Masses,” in Proceedings of
the 7th International Congress on Rock Mechanics (Aachen, Germany, September, 1991), Vol. 1,
pp. 693-698. Rotterdam: A. A. Balkema, 1991.
Contador, Nolberto V., and Marcelo F. Glavic. “Sublevel Open Stoping at El Soldado Mine: A
Geomechanic Challenge,” in Underground Mining Methods: Engineering Fundamentals and
International Case Studies, pp. 325-332. W. A. Hustrulid and R. L. Bullock, eds. Littleton,
Colorado: SME, 2001.
Corkum, A. G., and C. D. Martin. “Analysis of a Rock Slide Stabilized with a Toe-Berm: A Case
Study in British Columbia, Canada,” Int. J. Rock Mech. Min. Sci., 41, 1109-1121 (2004).
Cotesta, L., et al. “Application of Scientific Visualization – Stress Control on Permeability
Anisotropy in Moderately Fractured Rock,” in Rock Mechanics: Meeting Society’s Challenges
and Demands (1st Canada-U.S. Rock Mechanics Symposium, Vancouver, May 2007), Vol. 2:
Case Histories, pp. 1203-1212. E. Eberhardt et al., eds. London: Taylor & Francis Group, 2007.
Coulthard, M. A. “Distinct Element Modelling of Mining-Induced Subsidence — A Case Study,”
in Proceedings of the ISRM Regional Conference on Fractured and Jointed Rock Masses (Lake
Tahoe, June, 1992), Vol. 3, pp. 751-758. Berkeley, California: Lawrence Berkeley Laboratory,
1992.
Coulthard, M. A., and I. H. Clark. “Computational Stress Analysis for Mine Excavation Design,” in
Computer Applications in the Mineral Industry (Proceedings of the 2nd Australian Conference,
The University of Wollongong, N.S.W., July, 1991), pp. 165-170. E. Y. Baafi, ed. Wollongong:
University of Wollongong, 1991.
Coulthard, M. A., and A. J. Dutton. “Numerical Modeling of Subsidence Induced by Underground
Coal Mining,” in Key Questions in Rock Mechanics: Proceedings of the 29th U.S. Symposium
(University of Minnesota, June, 1988), pp. 529-536. Rotterdam: A. A. Balkema, 1988.
Coulthard, M. A., N. C. Journet and C. F. Swindells. “Integration of Stress Analysis into Mine
Excavation Design,” in Rock Mechanics (Proceedings of the 33rd U.S. Symposium, Santa Fe,
June, 1992), pp. 451-460. J. R. Tillerson and W. R. Wawersik, eds. Rotterdam: A. A. Balkema,
1992.

3DEC Version 4.1
239

7-6

User’s Guide

Cundall, P. A. “Alternative User Interfaces for Programs that Model Nonlinear Systems,” in Applications of Computational Mechanics in Geotechnical Engineering, pp. 343-352. E. A. Vargas et
al., eds. Rotterdam: A. A. Balkema, 1994.
Cundall, P. A. “Formulation of a Three-Dimensional Distinct Element Model — Part I: A Scheme
to Detect and Represent Contacts in a System Composed of Many Polyhedral Blocks,” Int. J. Rock
Mech., Min. Sci. & Geomech. Abstr., 25, 107-116 (1988).
Cundall, P. A. “Numerical Modeling of Jointed and Faulted Rock,” in Mechanics of Jointed and
Faulted Rock, pp. 11-18. Rotterdam: A. A. Balkema, 1990.
Cundall, P. A., and R. D. Hart. “Development of Generalized 2-D and 3-D Distinct Element
Programs for Modeling Jointed Rock,” Itasca Consulting Group Report to U.S. Army Engineering
Waterways Experiment Station, May, 1983; published as Misc. Paper SL-85-1, U.S. Army Corps
of Engineers, 1985.
Cundall, P. A., and R. D. Hart. “Numerical Modeling of Discontinua,” in Comprehensive Rock
Engineering, Vol. 2, pp. 231-243. J. A. Hudson Sr., ed. Oxford: Pergamon Press Ltd., 1993.
Cundall, P. A., and J. V. Lemos. “Numerical Simulation of Fault Instabilities with the Continuously
Yielding Joint Model,” in Rockbursts and Seismicity in Mines, pp. 147-152. C. Fairhurst, ed.
Rotterdam: A. A. Balkema, 1990.
Damjanac, Branko, and Charles Fairhurst. “Ecoulement tri-dimensionnel d’eau sous pression dans
les milieux fracturés,” in La sécurité des grands ouvrages: Hommage á Pierre Londe (October
2000), pp. 5-19. Paris: Presses de l’école nationale des Ponts et chaussées, 2000.
Damjanac, Branko, Charles Fairhurst and Terje Brandshaug. “Numerical Simulation of the Effects
of Heating on the Permeability of a Jointed Rock Mass,” in Proceedings of the 9th ISRM Congress
on Rock Mechanics (Paris, 1999), Vol. 2, pp. 881-885. Rotterdam: A. A. Balkema, 1999.
Dasgupta, B. “Numerical Modeling of Large Underground Caverns for Hydro Power Projects,” in
Trends in Rock Mechanics, Geotechnical Special Publication No. 102, Proceedings of Sessions
of Geo-Denver 2000 (August 2000, Denver), pp. 50-64. J. F. Labuz et al., eds. Reston, Virginia:
ASCE, 2000.
Dasgupta, B, R. Dham and L. J. Lorig. “Three-Dimensional Discontinuum Analysis of the Underground Power House for Sardar Sarovar Project, India,” in Proceedings of the Eighth International
Congress on Rock Mechanics (Tokyo, September 1995), Vol. II, pp. 551-554. T. Fujii, ed. Rotterdam: A. A. Balkema, 1995.
Dasgupta, B., and L. J. Lorig. “Numerical Modelling of Underground Power Houses in India,” in
Proceedings of the International Workshop on Observational Method of Construction of Large
Underground Caverns in Difficult Ground Conditions (8th ISRM International Congress on
Rock Mechanics, Tokyo, September, 1995), pp. 65-74. S. Sakurai, ed. (1995).
Dasgupta, B., K. N. Reddy and S. Nayak. “Discontinuum Analysis of Rock Slopes,” in Proceedings
of the Asian Regional Symposium on Rock Slopes (New Delhi, December, 1992), pp. 157-164.
New Delhi: Oxford EIBH Publications, 1993.

3DEC Version 4.1
240

BIBLIOGRAPHY

7-7

Dasgupta, B., and V. M. Sharma. “Numerical Modelling of Underground Power Houses in India,”
in Distinct Element Modeling in Geomechanics, pp. 187-217. V. M. Sharma et al., eds. New
Delhi: Oxford & IBH Publishing Co., 1999.
Dasgupta, B., M. K. V. Sharma, M. Verman and V. M. Sharma. “Design of Underground Caverns
for Tehri Hydropower Project, India by Numerical Modelling,” in Proceedings of the 9th ISRM
Congress on Rock Mechanics (Paris, 1999), Vol. 1, pp. 357-358. Rotterdam: A. A. Balkema,
1999.
Decker, J. B., et al. “An Integrated Relational Database for Tracking Rock Mass Data During
Tunnelling,” in AITES-ITA 2006 (World Tunnel Congress & 32nd ITA General Assembly, Seoul,
Korea, April 2006). I.-M. Lee, C. Yoo and K.-H. You, eds. Special Issue of Tunn. Undergr. Sp.
Tech., 21(3-4), Paper No. pita06-0312 (May-July). Elsevier Ltd, 2006.
Dialer, C. “A Distinct Element Approach for the Deformation Behavior of Shear Stressed Masonry
Panels,” in Proceedings of the 6th Canadian Masonry Symposium (University of Saskatchewan,
June, 1992), pp. 765-776, 1992.
Dialer, C., and M. Karaca. “Application of DEM to Problems in Rock Mechanics, Structural
Engineering and Material Testing,” submitted to the 2nd International Conference on Discrete
Element Methods (DEM), Massachusetts Institute of Technology, 1993.
Diederichs, M. S., et al. “Shear Strength Reduction (SSR) Approach for Slope Stability Analyses,”
in Rock Mechanics: Meeting Society’s Challenges and Demands (1st Canada-U.S. Rock Mechanics Symposium, Vancouver, May 2007), Vol. 1: Fundamentals, New Technologies & New
Ideas, pp. 319-327. E. Eberhardt et al., eds. London: Taylor & Francis Group, 2007.
Donovan, K. S., G. A. Lehmann, R. S. Pearce and K. Kim. “Rationale for Development of Constitutive Models of a Basalt Rock Mass for Design of a Nuclear Waste Repository at the Hanford Site,”
in Rock Mechanics: Proceedings of the 28th U.S. Symposium (University of Arizona, Tucson,
June-July, 1987), pp. 715-724. Rotterdam: A. A. Balkema, 1987.
Dupin, J.-M., W. Sassi and J. Angelier. “Homogeneous Stress Hypothesis and Actual Fault Slip:
A Distinct Element Analysis,” J. Struct. Geol., 15(8), 1033-1043 (1993).
Fairhurst, C. “Analysis and Design in Rock Mechanics — The General Context,” in Comprehensive
Rock Engineering, Vol. 2, pp. 1-29. J. A. Hudson, ed. Oxford: Pergamon Press Ltd., 1993.
Fairhurst, C. “Rock Mechanics and Nuclear Waste Repositories,” in Proceedings of the International Workshop on the Rock Mechanics of Nuclear Waste Repositories (Vail, Colorado, June
1999), pp. 1-43. S. Saeb and C. Francke, eds. Alexandria, Virginia: American Rock Mechanics
Association, 1999.
Fairhurst, C. “Three Gorges Dam Reservoir, Yangtze River, China,” Felsbau, 13(6), 390-394
(1995).

3DEC Version 4.1
241

7-8

User’s Guide

Fairhurst, C., B. Damjanac and R. Hart. “Numerical Analysis as a Practical Design Tool in Geo
Engineering,” in Slope Stability 2000 (Proceedings of Sessions of Geo-Denver 2000, Denver,
August 2000). Geotechnical Special Publication No. 101, pp. 169-183. D. V. Griffiths, G. A.
Fenton and T. R. Martin, eds. Reston, Virginia: ASCE (2000).
Fairhurst, C., and R. D. Hart. “Verification and Validation of Coupled Mechanical/Water Flow
Effects in Rock Masses: Some Possibilities and Limitations,” in GEOVAL-87 (Stockholm, April,
1987), pp. 527-545. Stockholm: SKI, 1987.
Fairhurst, C., and L. Lorig. “Improved Design in Rock and Soil Engineering with Numerical
Modelling,” in Distinct Element Modelling in Geomechanics, pp. 27-46. V. Sharma et al., eds.
New Delhi: Oxford & IBH Publishing, 1999.
Ferrero, A. M., et al. “Analysis of the Stability Condition of Underground Excavations by Experimental Measurements and 3D Numerical Modeling,” in Golden Rocks 2006 – 50 Years of Rock
Mechanics, Colorado School of Mines (41st U.S. Rock Mechanics Symposium, June 2006), Paper
No. 06-1141. D. P. Yale et al., eds. ARMA, 2006.
Gaffney, E. S., and B. Damjanac. “Localization of Volcanic Activity: Topographic Effects on Dike
Propagation, Eruption and Conduit Formation,” Geophys. Res. Letts., 33, L14313,
doi:10.1029/2006GL026852 (2006).
Gentier, S., et al. “Hydraulic Stimulation of Geothermal Wells in HFR Systems: Approach Based
on 3D Hydro-Mechanical Modeling,” in Soil and Rock America 2003 (39th U.S. Rock Mechanics
Symposium, Cambridge, Massachusetts, June 2003), pp. 1471-1477. P. J. Culligan, H. H. Einstein
and A. J. Whittle, eds. Essen: Verlag Glückauf, 2003.
Glamheden, R., H. Hökmark and R. Christiansson. “Modeling Creep in Jointed Rock Masses,”
in Numerical Modeling of Discrete Materials in Geotechnical Engineering, Civil Engineering
& Earth Sciences (1st International UDEC/3DEC Symposium, Bochum, Germany, September
2004), pp. 131-137. H. Konietzky, ed. Leiden: Balkema, 2004.
Grenon, M., and R. Caumartin. “Use of Resource Modeling Tools in Numerical Analysis of Slope
Stability,” in Rock Mechanics: Meeting Society’s Challenges and Demands (1st Canada-U.S.
Rock Mechanics Symposium, Vancouver, May 2007), Vol. 2: Case Histories, pp. 1295-1300.
E. Eberhardt et al., eds. London: Taylor & Francis Group (2007).
Hakami, H. “Propagation of Large, Twinned Fractures in Shear – A Numerical Investigation,” in
The Second Half Century of Rock Mechanics (11th Congress of the International Society for
Rock Mechanics, Lisbon, July 2007), Vol. 1, pp. 399-402. L. Ribeiro e Sousa, C. Olalla and
N. Grossmann, eds. London: Taylor & Francis Group (2007).
Hammer, H., H. C. Siegfried Niedermeyer and T. Niedermeyer. “Untersuchen zu Gebrigs-spannungen und – bewegungen in der Schwabischen Alb,” Felsbau, 13(6), 367-373 (1995).
Harper, T. R., and N. C. Last. “Interpretation by Numerical Modelling of Changes of Fracture
System Hydraulic Conductivity Induced by Fluid Injection,” Geotechnique, 39(1), 1-11 (1989).

3DEC Version 4.1
242

BIBLIOGRAPHY

7-9

Hart, R. “Enhancing Rock Stress Understanding Through Numerical Analysis,” Int. J. Rock Mech.
Min. Sci., 40, 1089-1097 (2003).
Hart, R., P. Cundall and J. Lemos. “Formulation of a Three-Dimensional Distinct Element Model
— Part II: Mechanical Calculations for Motion and Interaction of a System Composed of Many
Polyhedral Blocks,” Int. J. Rock Mech., Min. Sci. & Geomech. Abstr., 25, 117-126 (1988).
Hart, R., and C. Fairhurst. “Application of Discontinuum Modeling in Geotechnical Studies for
Nuclear Waste Isolation,” in Geoecology and Computers (Proceedings of the 3rd International
Conference on Advances of Computer Methods in Geotechnical and Geoenvironmental Engineering, Moscow, February 2000), pp. 15-28. S. A. Yufin, ed. Rotterdam: A. A. Balkema,
2000.
Hart, R., D. Hanson and D. Swan. “A Three-Dimensional Ground Control Program for Falconbridge
Limited,” Paper No. 89, 92nd Annual General Meeting of CIM — 1990. Canadian Institute of
Mining and Metallurgy, Ottawa, May, 1990.
Hart, R. D. “Discontinuum Analysis for Deep Excavations in Jointed Rock,” in Rock at Great
Depth, Vol. 3, pp. 1123-1130. Rotterdam: A. A. Balkema, 1990.
Hart, R. D. “An Introduction to Distinct Element Modeling for Rock Engineering,” in Proceedings
of the 7th International Congress on Rock Mechanics (Aachen, Germany, September, 1991),
Vol. 3, pp. 1881-1892. W. Wittke, ed. Rotterdam: A. A. Balkema, 1993; in Comprehensive Rock
Engineering, Vol. 2, pp. 245-261. J. A. Hudson Sr., ed. Oxford: Pergamon Press, Ltd., 1993.
Hart, R. D., M. Board, B. Brady, B. O’Hearn and G. Allan. “Examination of Fault-Slip Induced
Rockbursting at the Strathcona Mine,” in Key Questions in Rock Mechanics, pp. 369-379. P. A.
Cundall et al., eds. Rotterdam: A. A. Balkema, 1988.
Hart, R. D., P. A. Cundall and M. L. Cramer. “Analysis of a Loading Test on a Large Basalt Block,”
in Research and Engineering — Applications in Rock Masses, Vol. 2, pp. 759-768. E. Ashworth,
ed. Boston: A. A. Balkema, 1985.
Hellä, P., and P. Saksa. “3D Geological Modelling, Model Transfer and Validation,” in Proceedings
of the SCSC’95 Conference (Ottawa, Canada July 1995), pp. 967-971. T. I. Oren and L. G. Birta,
eds. SCS, 1995.
Hobbs, B. E., A. Ord and C. Marone. “Dynamic Behavior of Rock Joints,” in Rock Joints (Proceedings of the International Symposium on Rock Joints (Loen, Norway, June, 1990), pp. 435-445.
Rotterdam: A. A. Balkema, 1990.
Hökmark, H. “Acceptance of Emplacement Hole Positions — Stage 1 Thermomechanical Study,” in
Preprints of Contributions to the Workshop on Computational Methods in Engineering Geology
(Lund, Sweden, October, 1996), pp. 42-51. R. Pusch and R. Adey, eds. Lund: Clay Technology
AB, 1996.
Hökmark, H. “Numerical Study of the Performance of Tunnel Plugs,” in Preprints of Contributions
to the Workshop on Computational Methods in Engineering Geology (Lund, Sweden, October,
1996), pp. 212-221. R. Pusch and R. Adey, eds. Lund: Clay Technology AB, 1996.

3DEC Version 4.1
243

7 - 10

User’s Guide

Homand-Etienne, F., N. Rode and R. Schwartzmann. “Block Modelling of Jointed Cliffs,” in
Mechanics of Jointed and Faulted Rock, pp. 819-825. Rotterdam: A. A. Balkema, 1990.
Hosni, A., et al. “3D-Hydromechanical Modeling of Hydraulic Stimulation of Deep Geothermal
Wells in Hot Fractured Rock at Soultz-Sous-Forêts (Alsace, France),” in Numerical Modeling
of Discrete Materials in Geotechnical Engineering, Civil Engineering & Earth Sciences (1st
International UDEC/3DEC Symposium, Bochum, Germany, September 2004), pp. 139-144.
H. Konietzky, ed. Leiden: Balkema, 2004.
Hudson, J. “Rock Mechanics Studies for Disposal of Radioactive Waste in the UK: 1979-1999,” in
Proceedings of the International Workshop on the Rock Mechanics of Nuclear Waste Repositories
(Vail, Colorado, June 1999), pp. 229-258. S. Saeb and C. Francke, eds. Alexandria, Virginia:
American Rock Mechanics Association, 1999.
Hunt, S. P., B. A. Camac and P. J. Boult. “A New Geomechanical Tool for the Evaluation of
Hydrocarbon Trap Integrity,” in Golden Rocks 2006 – 50 Years of Rock Mechanics, Colorado
School of Mines (41st U.S. Rock Mechanics Symposium, June 2006), Paper No. 06-1064. D. P.
Yale et al., eds. ARMA, 2006.
Hutchinson, D. J., et al. “Four Dimensional Considerations in Forensic and Predictive Simulation
of Hazardous Slope Movement,” in Rock Mechanics: Meeting Society’s Challenges and Demands
(1st Canada-U.S. Rock Mechanics Symposium, Vancouver, May 2007), Vol. 1: Fundamentals,
New Technologies & New Ideas, pp. 11-19. E. Eberhardt et al., eds. London: Taylor & Francis
Group, 2007.
Jakubowski, J. “3DEC Modeling Results Generalized by Stochastic Approach,” in Numerical Modeling of Discrete Materials in Geotechnical Engineering, Civil Engineering & Earth Sciences
(1st International UDEC/3DEC Symposium, Bochum, Germany, September 2004), pp. 165-173.
H. Konietzky, ed. Leiden: Balkema, 2004.
Jakubowski, J., and P. Starzec. “Deformable and Rigid Block Models within the Scheme of Statistical Simulation,” in Proceedings of the Fifth North American Rock Mechanics Symposium
and the Seventeenth Tunnelling Association of Canada Conference — NARMS-TAC (Toronto,
Canada, July 2002), pp. 1225-1232. R. Hammah et al., eds. Toronto: University of Toronto Press,
2002.
Jakubowski, J., and J. B. Stypulokowski. “A Statistical Simulation of 3D Blocky Structure for
Optimal Tunnel Design,” in Geotechnical Engineering in the Information Technology Age (Geocongress 2006, Atlanta, February-March 2006). D. J. DeGroot et al., eds. Reston, Virginia:
ASCE, 2006.
Jakubowski, J., A. Tajdus, J. Walaszczyk and P. Starzec. “Probabilistic Approach to Deformable
Blocky Rock Mass Modeling,” in Proceedings of the International Conference on Probabilistics
in Geotechnics: Technical and Economic Risk Estimation (Graz, Austria, September 2002),
pp. 105-112. R. Pöttler et al., eds. Essen: Verlag Glückauf, 2002.

3DEC Version 4.1
244

BIBLIOGRAPHY

7 - 11

Jiao, Y. Y., J. Zhao and J. G. Cai. “Consideration for 2-D and 3-D Modelling of Shock Wave
Propagation in Jointed Rock Masses,” in Technology Roadmap for Rock Mechanics (10th Congress
of the ISRM, Johannesburg, September 2003), Vol. 1, pp. 583-586. Johannesburg: SAIMM,
2003.
Jing, L. Numerical Modelling of Jointed Rock Masses by Distinct Element Method for Two, and
Three-Dimensional Problems. Doctoral Thesis, Luleå University of Technology, Division of Rock
Mechanics, 1990:90, November, 1990.
Jing, L. “A Review of Techniques, Advances and Outstanding Issues in Numerical Modelling for
Rock Mechanics and Rock Engineering,” Int. J. Rock Mech. Min. Sci., 40, 283-353 (2003).
Jing, L., and J. A. Hudson. “Numerical Methods in Rock Mechanics,” Int. J. Rock Mech. Min.
Sci., 39, 409-427 (2002).
Jing, L., E. Nordlund and O. Stephansson. “Technical Note: A 3-D Constitutive Model for Rock
Joints with Anisotropic Friction and Stress Dependency in Shear Stiffness,” Int. J. Rock Mech.
Min. Sci. & Geomech. Abstr., 31(2), 173-178 (1994).
Jing, L., and O. Stephansson. “Distinct Element Modelling of the Influence of Glaciation and
Deglaciation of the State of Stress in Faulted Rock Masses,” SKB, Report No. 88-23 (1987).
Jing, L., and O. Stephansson. “Distinct Element Modeling of Sublevel Stoping,” in Proceedings
of the 7th International Congress on Rock Mechanics (Aachen, Germany, September, 1991),
Vol. 1, pp. 693-698. Rotterdam: A. A. Balkema, 1991.
Jing, L., and O. Stephansson. “Numerical Modeling of Large-Scale Sublevel Stoping by ThreeDimensional Distinct Element Method,” in Proceedings of the 1st U.S. Conference on Distinct
Elements (Golden, Colorado, October, 1989). Golden, Colorado: CSM Press, 1989.
Jing, L., and O. Stephansson. “Numerical Modeling of Sublevel Stoping for the Oscar Project
Using a Three-Dimensional Distinct Element Code,” Luleå University of Technology, Research
Report TULEA 1990:19 (1990).
Jing, L., O. Stephansson and E. Nordlund. “Study of Rock Joints Under Cyclic Loading Conditions,”
Rock Mech. Rock Engng., 26(3), 215-232 (1993).
Johansson, E., M. Hakala, E. Peltonen, J.-P. Salo and L. Lorig. “Comparisons of Computed Twoand Three-Dimensional Thermomechanical Response of Jointed Rock,” in Proceedings of the 7th
International Congress on Rock Mechanics (Aachen, September, 1991), pp. 115-119. Rotterdam:
A. A. Balkema, 1991.
Johansson, E., M. Kalliomaki, L. Lorig and S. Narvi. “Three-Dimensional Geomechanics Modelling: City Planning for the Kamppi Underground Bus Terminal in Helsinki,” in Underground
Construction in Modern Infrastructure, pp. 119-123. T. Franz et al., eds. Rotterdam: A. A.
Balkema, 1998.

3DEC Version 4.1
245

7 - 12

User’s Guide

Johansson, E., and L. J. Lorig. “Use of Numerical Models in Design and Excavation Monitoring
of Multiple Parallel Caverns,” in Proceedings of the International Symposium on Unique Underground Structures (Denver, June, 1990), Vol. 1, pp. 11-1 to 11-19. Golden, Colorado: CSM
Press, 1990.
Johansson, E., J. Pöllä and P. Holopainen. “Predicted and Observed Behaviour of Weakness Zones
in a Hard, Jointed Rock Mass,” in Prediction and Performance in Rock Mechanics & Rock Engineering (EUROCK ‘96, Turin, September 1996), Vol. 1, pp. 271-276. G. Barla, ed. Rotterdam:
Balkema, 1996.
Johansson, E., and J. Rautakorpi. “Rock Mechanics Stability at Olkiluoto, Hästholmen, Kivetty
and Romuvaara,” Posiva Oy, Report 2000-02, February 2000.
Johansson, E., J. Rautakorpi and J. P. Tinucci. “Optimizing Tunnel Support Requirements in Jointed
Rock – Applied to Wedge Stability Assessment of Waste Emplacement Drifts in Finland,” in Soil
and Rock America 2003 (39th U.S. Rock Mechanics Symposium, Cambridge, Massachusetts,
June 2003), pp. 2341-2347. P. J. Culligan, H. H. Einstein and A. J. Whittle, eds. Essen: Verlag
Glückauf, 2003.
Johansson, E., R. Riekkola, J.-P. Salo and P. Anttila. “State-of-the-Art Nuclear Waste Repository
Projects and Rock Mechanics in Finnish Program,” in Proceedings of the International Workshop
on the Rock Mechanics of Nuclear Waste Repositories (Vail, Colorado, June 1999), pp. 117-141.
S. Saeb and C. Francke, eds. Alexandria, Virginia: American Rock Mechanics Association, 1999.
Johansson, E. J. W. “Treating Sewage Underground,” Tunnels & Tunnelling, 21-23 (July, 1995).
Johansson, E. J. W., and H. Kuula. “Three-Dimensional Back-Analysis Calculations of Viikinmaki
Underground Sewage Treatment Plant in Helsinki,” in Proceedings of the Eighth International
Congress on Rock Mechanics (Tokyo, September, 1995), Vol. II, pp. 597-600. T. Fujii, ed.
Rotterdam: A. A. Balkema, 1995.
Johnson, K. I., C. F. Voss and D. J. Sherwood. “A Sensitivity Study of Near-Field Thermomechanical
Conditions in Tuff,” in FOCUS ’89 (Proceedings of the Conference on Nuclear Waste Isolation
in the Unsaturated Zone, Las Vegas, September, 1989), pp. 10-19. New York: American Nuclear
Society, 1989.
Jung, J., and S. R. Brown. “A Study of Discrete and Continuum Joint Modeling Techniques,” in
Proceedings of the ISRM Regional Conference on Fractured and Jointed Rock Masses (Lake
Tahoe, June, 1992), Vol. 3, pp. 640-647. Berkeley, California: Lawrence Berkeley Laboratory,
1992.
Kalenchuk, K. S., M. S. Diederichs and S. McKinnon. “Characterizing Block Geometry in Jointed
Rockmasses,” Int. J. Rock Mech. Min. Sci., 43, 1212-1225 (2006).
Karaca, M. “The Effects of Discontinuities on the Stability of Shallow Tunnels in Weak Rock,”
in Proceedings of the ISRM Regional Conference on Fractured and Jointed Rock Masses (Lake
Tahoe, June, 1992), Vol. 3, pp. 759-764. Berkeley, California: Lawrence Berkeley Laboratory,
1992.

3DEC Version 4.1
246

BIBLIOGRAPHY

7 - 13

Kay, D. R., K. E. McNabb and J. P. Carter. “Numerical Modelling of Mine Subsidence at Angus
Place Colliery,” in Computer Methods and Advances in Geomechanics (Proceedings of the 7th
International Conference, Cairns, Australia, May, 1991), pp. 999-1004. Rotterdam: A. A.
Balkema, 1991.
Kelly, M. S., X. Luo, P. Hatherly, S. R. Balusu, G. Smith Leblanc and W. Gale. “Ground Behaviour
about Longwall Faces and its Effect on Mining,” in Proceedings of the 9th ISRM Congress on
Rock Mechanics (Paris, 1999), Vol. 1, pp. 307-310. Rotterdam: A. A. Balkema, 1999.
Konietzky, H., ed. “Numerical Modeling of Discrete Materials in Geotechnical Engineering, Civil
Engineering & Earth Sciences (1st International UDEC/3DEC Symposium, Bochum, Germany,
September 2004). Leiden: Balkema, 2004.
Konietzky, H., P. Blümling and F. Rummel. “In Situ Stress Field in the Wellenberg Area,” NAGRA
Bull., No. 26, 38-48 (November 1995).
Konietzky, H., P. Blümling and L. te Kamp. “Site Characterization: The Tectonic Stress Field
for the Planned ‘Wellenberg Repository Site’ in Switzerland,” in Preprints, GeoEngineering of
Hazardous and Radioactive Waste Disposal (3rd European Geology Conference, University of
Newcastle Upon Tyne, September 1997), pp. 275-285 (1997).
Konietzky, H., and P. Marschall. “Excavation Disturbed Zone around Tunnels in Fractured Rock –
Example from the Grimsel Test Site,” in Geomechanics ‘96 (Roznov, Czech Republic, September
1997), pp. 235-240. Rotterdam: Balkema, 1997.
Konietzky, H., and L. te Kamp. “Numerical Stress Field Modeling for Underground Structures,”
in Numerical Modeling of Discrete Materials in Geotechnical Engineering, Civil Engineering
& Earth Sciences (1st International UDEC/3DEC Symposium, Bochum, Germany, September
2004), pp. 155-164. H. Konietzky, ed. Leiden: Balkema, 2004.
Konietzky, H., L. te Kamp and H. Hagedorn. “The Gotthard-Base-Tunnel: Conceptual Modeling for
Tunneling Extremely Weak Zones,” in Numerical Modeling of Discrete Materials in Geotechnical
Engineering, Civil Engineering & Earth Sciences (1st International UDEC/3DEC Symposium,
Bochum, Germany, September 2004), pp. 21-27. H. Konietzky, ed. Leiden: Balkema, 2004.
Kosugi, M., N. Barton and G. Vik. “Studies on Predicting Jointed Rock Mass Behavior (Part 1):
Joint Behavior Modelling and UDEC Analysis,” Resources, 3(2), 11-22 (1991) (abstract in English).
Kosugi, M., H. Ishihara and M. Nakagawa. “Tunnelling Method Coupled with Joint Monitoring
and DEM Analysis,” in Proceedings of the ISRM Regional Conference on Fractured and Jointed
Rock Masses (Lake Tahoe, June, 1992), Vol. 3, pp. 765-770. Berkeley, California: Lawrence
Berkeley Laboratory, 1992.
Kosugi, M., G. Vik and N. Barton. “Studies on Predicting Jointed Rock Mass Behavior; Part
2): Joint Characterization Based on JRC/JRC Indexes,” Resources, 3(1), 51-62 (1991) (abstract in
English).

3DEC Version 4.1
247

7 - 14

User’s Guide

Kulatilake, P. H. S. W., H. Uepirti, S. Wang, G. Radberg and O. Stephansson. “Use of the Distinct
Element Method to Perform Stress Analysis in Rock with Nonpersistent Joints and to Study the
Effect of Joint Geometry Parameters on the Strength and Deformability of Rock Masses,” Rock
Mech. Rock. Engng., 25(4), 253-274 (1992).
Kwon, S., B. Y. Park, C. H. Kang and K. Chang. “Structural Stability Analysis for a High-Level
Underground Nuclear Waste Repository in Granite,” in Pacific Rocks 2000: Rock around the
Rim (Proceedings of the 4th North American Rock Mechanics Symposium, Seattle, July-August
2000), pp. 1279-1285. J. Girard et al., eds. Rotterdam: A. A. Balkema 2000.
Larsson, H., R. Glamheden and G. Ahrling. “Storage of Natural Gas at High Pressure in Lined
Rock Caverns — Rock Mechanics Analysis,” in Storage of Gases in Rock Caverns, pp. 177-184.
Rotterdam: A. A. Balkema, 1989.
Leach, A. R., and G. J. Van Hout. “Modelling of Western Holdings 8 Shaft Pillar Extraction,”
Itasca Africa, Report PO18/96 (1996).
Last, N. C., and T. R. Harper. “Response of Fractured Rock Subject to Fluid Injection: Parts I-III
(Development of a Numerical Model, Characteristic Behavior, Practical Application),” Tectonophysics, 172, 1-65 (1990).
Lemos, J., R. Hart and L. Lorig. “Dynamic Analysis of Discontinua Using the Distinct Element
Method,” in Proceedings of the Sixth International Congress on Rock Mechanics (Montréal,
1987), Vol. 2, pp. 1079-1084. Rotterdam: A. A. Balkema and the Canadian Rock Mechanics
Association/CIM/CGS, 1987.
Lemos, J. V. “Assessment of the Ultimate Load of a Masonry Arch Using Discrete Elements,” in
Proc. Int. Conf. Comp. Meth. in Struct. Masonry, Lisbon, Portugal, April, 1995.
Lemos, J. V. “A Comparison of Numerical and Physical Models of a Blocky Medium,” in Mechanics
of Jointed and Faulted Rock, pp. 509-514. Rotterdam: A. A. Balkema, 1990.
Lemos, J. V. “Discrete Analysis of the S. Vicente de Fora Model Test,” in Monument 98 —
Workshop on Seismic Performance of Monuments (Lisbon, November 1998), pp. 13-20. Lisbon:
LNEC, 1998.
Lemos, J. V. “Discrete Element Analysis of Dam Foundations,” in Distinct Element Modeling in
Geomechanics, pp. 89-115. V. M. Sharma et al., eds. New Delhi: Oxford & IBH Publishing Co.,
1999.
Lemos, J. V. “Discrete Element Modelling of Historical Structures,” in Proc. Int. Conf. New
Technologies in Structural Engineering, Lisbon, Vol. 2, pp. 1099-1106. S. P. Santos and A. M.
Baptista, eds. Lisbon: LNEC, 1996.
Lemos, J. V. “Discrete Element Modelling of the Seismic Behaviour of Stone Masonry Arches,”
Computer Methods in Structural Masonry — 4 (Proceedings of 4th International Symposium
Num. Methods Structural Masonry — STRUMAS IV, Florence, September, 1997), pp. 220-227.
G. N. Pande, J. Middleton and B. Kralj, eds. London: E&FN Spon, 1997.

3DEC Version 4.1
248

BIBLIOGRAPHY

7 - 15

Lemos, J. V. “Modelling of Arch Dams on Jointed Rock Foundations,” in Prediction and Performance in Rock Mechanics & Rock Engineering (Proceedings of ISRM International Symposium
EUROCK ’96, Turin, September, 1996), Vol. 1, pp. 519-526. G. Barla, ed. Rotterdam: A. A.
Balkema, 1996.
Lemos, J. V. “Numerical Models for Seismic Analysis of Historical Figures,” in Proceedings of
the Assisi-99 Workshop on Seismic Performance of Built Heritage in Small Historical Centres
(Assisi, April 1999), pp. K53-K51. CICOP Italia, 1999.
Lemos, J. V., R. D. Hart and P. A. Cundall. “A Generalized Distinct Element Program for Modelling
Jointed Rock Mass: A Keynote Lecture,” in Proceedings of the International Symposium on
Fundamentals of Rock Joints (Björkliden, 15-20 September, 1985), pp. 335-343. Luleå, Sweden:
Centek Publishers, 1985.
Lemos, J. V., and L. J. Lorig. “Hydromechanical Modeling of Jointed Rock Masses Using the
Distinct Element Method,” in Mechanics of Jointed and Faulted Rock, pp. 605-612. Rotterdam:
A. A. Balkema, 1990.
Lemos, J. V., C. A. B. Pina, C. P. Costa and J. P. Gomes. “Experimental Study of an Arch Dam
on a Jointed Foundation,” in Proceedings of the 8th International Congress on Rock Mechanics
(Tokyo, September 1995), Vol. 3, pp. 1263-1266. Rotterdam: A. A. Balkema, 1997.
Lemos, J. V., F. Schiappa de Azevedo, C. Sousa Oliveira and G. Sincraian. “Three-Dimensional
Analysis of a Block Masonry Pillar Using Discrete Elements,” in Monument 98 — Workshop on
Seismic Performance of Monuments (Lisbon, November 1998), pp. 117-126. Lisbon: LNEC,
1998.
Lendel, U. “Rock Bolting and Rock Support and Their Combination in Hard Coal Mining – A Comparative Study Made with UDEC,” in Numerical Modeling of Discrete Materials in Geotechnical
Engineering, Civil Engineering & Earth Sciences (1st International UDEC/3DEC Symposium,
Bochum, Germany, September 2004), pp. 213-217. H. Konietzky, ed. Leiden: Balkema, 2004.
Lightfoot, N. “The Use of Numerical Modeling in Rockburst Control,” in Innovative Mine Design
for the 21st Century (Proceedings of the International Congress on Mine Design, Kingston,
Ontario, Canada, August, 1993), pp. 355-360. W. F. Bawden and J. F. Archibald, eds. Rotterdam:
A. A. Balkema, 1993.
Lin, M., et al. “Mechanical Degradation of Emplacement Drifts at Yucca Mountain – A Modeling
Case Study, Part I: Nonlithophysal Rock,” Int. J. Rock Mech. Min. Sci., 44, 351-367 (2007).
Liu, C. and Y. Tan. “Use of 3DEC to Predict Roof Movements in Thick Coal Seam Operations Where
Non-Entry Faces are Employed,” in Numerical Modeling of Discrete Materials in Geotechnical
Engineering, Civil Engineering & Earth Sciences (1st International UDEC/3DEC Symposium,
Bochum, Germany, September 2004), pp. 85-87. H. Konietzky, ed. Leiden: Balkema, 2004.
Lorig, L. “The Roles and Necessary Capabilities of Numerical Methods for Design Analysis
of Excavations in Rock,” in Proceedings of the VII National Congress on Soil Mechanics and
Cement Engineering (Lima, December, 1993), pp. 1-17. Lima: Servicomp Publicaciones, 1993.

3DEC Version 4.1
249

7 - 16

User’s Guide

Lorig, L., and C. Fairhurst. “Three-Dimensional Discontinuum Modeling for Underground Excavations,” in Proceedings of the 1992 Rock Engineering Symposium in Taiwan (Tainan, Republic
of China, December, 1992), pp. 349-358. S.-T. Chen et al., eds. Tainan, Taiwan: National Cheng
Kung University, 1992.
Lorig, L. J. “Analysis of Novel Retaining Structures Using Explicit Finite Difference Codes,”
in Computer Methods and Advances in Geomechanics (Proceedings of the 7th International
Conference, Cairns, Australia, May, 1991), pp. 157-164. Rotterdam: A. A. Balkema, 1991.
Lorig, L. J. “Distinct Element — Structural Element Analysis of Support Systems in Jointed
Rock Masses,” in VI Australian Tunnelling Conference (Melbourne, March, 1987), pp. 173-182.
Parkville, Australia: Australasian Institute of Mining and Metallurgy, 1987.
Lorig, L. J. “Modeling of Support Structures in Hard Rock,” in Kalliomekaniikan Paiva 1990
(Finnish Rock Mechanics Day 1990), Paper No. 9. Espoo, Finland: Vuorimiesyhdistys Bergsmannaforeningen r.y., 1990.
Lorig, L. J. “A Simple Numerical Representation of Fully Bounded Passive Rock Reinforcement
for Hard Rocks,” Computers and Geotechnics, 1, 79-97, 1985.
Lorig, L. J., and P. A. Cundall. “Modeling of Reinforced Concrete Using the Distinct Element
Method,” in Fracture of Concrete and Rock, pp. 459-471. S. P. Shah and S. E. Swartz, eds.
Bethel, Conn.: SEM, 1987.
Lorig, L. J., and B. Dasgupta. Analysis of Emplacement Borehole Rock and Liner Behavior
for a Repository at Yucca Mountain. U.S. Nuclear Regulatory Commission, NUREG/CR-5427,
September, 1989.
Lorig, L. J., R. D. Hart, M. P. Board and G. Swan. “Influence of Discontinuity Orientations and
Strength on Cavability in a Confined Environment,” in Rock Mechanics As a Guide for Efficient
Utilization of Natural Resources, pp. 167-174. A. Wahab Khair, ed. Rotterdam: A. A. Balkema,
1989.
Lorig, L. J., R. D. Hart and P. A. Cundall. “Slope Stability Analysis of Jointed Rock Using
the Distinct Element Method,” Transportation Research Record, 1330, 1-9. Washington, D.C.:
National Research Council, 1991.
Lorig, L. J., and B. E. Hobbs. “Numerical Modeling of Slip Instability Using the Distinct Element
Method with State Variable Friction Laws,” Int. J. Rock Mech. Min. Sci. & Geomech. Abstr.,
27(6), 525-534 (1990).
Mack, M. “Verification of Thermal Logic in the Three-Dimensional Code 3DEC,” ICG Report to
U.S. NRC, Contract No. NRC-02-85-002, August, 1989.
Mack, M. G., T. Brandshaug and B. Brady. “Rock Mass Modification around a Nuclear Waste
Repository in Welded Tuff,” Itasca Consulting Group Report to the U.S. Nuclear Regulatory Commission, Contract 02-85-002, Topical Report 006-01-T5, March, 1989; NUREG/CR-5390, August,
1989.

3DEC Version 4.1
250

BIBLIOGRAPHY

7 - 17

Makurat, A., N. Barton, G. Vik and S. Bandis. “Investigation of Disturbed Zone Effects and
Support Strategies for the Fjellinjen Road Tunnels under Oslo,” in Proceedings of the International
Congress on Progress and Innovation in Tunnelling (Toronto, September, 1989), pp. 125-134.
Toronto: TAC/NRC/ITA, 1989.
Mas Ivars, D. “Water Inflow Into Excavations in Fractured Rock – A Three-Dimensional HydroMechanical Numerical Study,” Int. J. Rock Mech. Min. Sci., 43, 705-725 (2006).
Mas Ivars, D., E. Hakami and O. Stephansson. “Influence of Rock Mass Characteristics on Inflow into Deposition Holes for Nuclear Waste Disposal – A Coupled Hydro-Mechanical Analysis
Using 3DEC,” in Numerical Modeling of Discrete Materials in Geotechnical Engineering, Civil
Engineering & Earth Sciences (1st International UDEC/3DEC Symposium, Bochum, Germany,
September 2004), pp. 95-103. H. Konietzky, ed. Leiden: Balkema, 2004.
McKinnon, S. D. “Analysis of Stress Measurements Using a Numerical Model Methodology,” Int.
J. Rock Mech. Min. Sci., 38, 699-709 (2001).
McKinnon, S. D., D. Harding and K. Birnie. “Crown Pillar Design at INCO’s South Mine,” in
NARMS-TAC 2002: Mining and Tunnelling Innovation and Opportunity, Vol. 2, pp. 1041-1048.
R. Hammah et al., eds. Toronto: University of Toronto Press, 2002.
McKinnon, S. D., and L. J. Lorig. “Considerations for Three-Dimensional Modeling in Analysis of
Underground Excavations,” in Distinct Element Modelling in Geomechanics, pp. 145-166. V. M.
Sharma et al., eds. New Delhi: Oxford & IBH Publishing, 1999.
McNearny, R. L., and J. F. Abel, Jr. “Large-Scale Two-Dimensional Block Caving Model Tests,”
Int. J. Rock Mech. Min. Sci. & Geomech. Abstr., 30(2), 93-109, 1993.
Minkley, W. “Back Analysis Rock Burst Völkershausen 1989,” in Numerical Modeling of Discrete
Materials in Geotechnical Engineering, Civil Engineering & Earth Sciences (1st International
UDEC/3DEC Symposium, Bochum, Germany, September 2004), pp. 105-112. H. Konietzky, ed.
Leiden: Balkema, 2004.
Morrison, D. M., G. Swan and C. H. Scholz. “Chaotic Behavior and Mining-Induced Seismicity,”
in Innovative Mine Design for the 21st Century (Proceedings of the International Congress on
Mine Design, Kingston, Ontario, Canada, August, 1993), pp. 233-237. W. F. Bawden and J. F.
Archibald, eds. Rotterdam: A. A. Balkema, 1993.
Ng, L. K. W., G. Swan and M. Board. “The Application of an Energy Approach in Fault Models
for Support Design,” in Rockbursts and Seismicity in Mines 93 (Proceedings of the International Symposium, Kingston, Ontario, Canada, August 1993), pp. 387-391. R. Paul Young, ed.
Rotterdam: A. A. Balkema, 1993.
Nordlund, E., and L. Jing. “Distinct Element Modelling of Jointed Rock Pillars,” in Proceedings
of the 1st U.S. Conference on Discrete Element Methods (Golden, Colorado, October, 1990).
G. G. W. Mustoe et al., eds. Golden, Colorado: CSM Press, 1989.

3DEC Version 4.1
251

7 - 18

User’s Guide

Nordlund, E., and G. Radberg. “Determination of Failure Modes in Jointed Pillars by Numerical
Modeling,” in Proceedings of the ISRM Regional Conference on Fractured and Jointed Rock
Masses (Lake Tahoe, June, 1992), Vol. 3, pp. 751-758. Berkeley, California: Lawrence Berkeley
Laboratory, 1992.
O’Connor, C. P., et al. “Numerical Modeling with 3DEC and Risk Assessment for a Geometrically
Complex and Highly Stressed Sill Pillar at Onaping Mine,” in Numerical Modeling of Discrete
Materials in Geotechnical Engineering, Civil Engineering & Earth Sciences (1st International
UDEC/3DEC Symposium, Bochum, Germany, September 2004), pp. 89-94. H. Konietzky, ed.
Leiden: Balkema, 2004.
O’Connor, K. M., and C. H. Dowding. “Monitoring and Simulation of Mining-Induced Subsidence,”
in Mechanics of Jointed and Faulted Rock, pp. 781-787. Rotterdam: A. A. Balkema, 1990.
O’Hearn, B., D. Morrison, G. Allan, M. Board and R. Hart. “Use of Numerical Modeling in Mine
Design at Falconbridge, Ltd.,” SME Annual Meeting (Phoenix, January, 1988), Geomechanics,
Session II, 1988.
O’Hearn, B., and G. Swan. “The Use of Models in Sill Mat Design at Falconbridge,” in Innovations
in Mining Backfill Technology (Montréal, October, 1989), pp. 139-146. Rotterdam: A. A.
Balkema, 1989.
Papantonopoulos, C., et al. “Numerical Prediction of the Earthquake Response of Classical Columns
Using the Distinct Element Method,” Earthquake Engng. Struct. Dyn., 31, 1699-1717 (2002).
Papastamatiou, D., I. Psycharis, P. Carydis, C. Papantonopoulos, H. Mouzakis, J. V. Lemos and
C. Zambas. Monuments Under Seismic Action: A Numerical and Experimental Approach,
National Technical University of Athens, Laboratory for Earthquake Engineering, Report to E. U.
Environment Programme, NTUA/LEE-97-01, May 1997.
Peng, Y.-R., and Y.-C. Chen. “The Deformation Behaviour of Tunnels Passing Through Rock
Mass with Different Stiffness,” in Rock Engineering: Theory and Practice (EUROCK 2004 &
53rd Geomechanics Colloquy, Salzburg, Austria, October 2004), pp. 765-770. W. Schubert, ed.
Essen: Verlag Glückauf, 2004.
Poisel, R., A. Preh and A. Zettler. “Rock as a Continuous Material and as a Discontinuous Material
– Are Clear Definitions Possible?” in Rock Engineering: Theory and Practice (EUROCK 2004
& 53rd Geomechanics Colloquy, Salzburg, Austria, October 2004), pp. 717-722. W. Schubert,
ed. Essen: Verlag Glückauf, 2004.
Pritchard, M. A., K. W. Savigny and S. G. Evans. “Toppling and Deep-Seated Landslides in Natural
Slopes,” in Mechanics of Jointed and Faulted Rock, pp. 937-943. Rotterdam: A. A. Balkema,
1990.
Psycharis, I. N., et al. “Numerical Study of the Seismic Behavior of a Part of the Parthenon Pronaos,”
Earthquake Engng. Struct. Dyn., 32, 2063-2084 (2003).

3DEC Version 4.1
252

BIBLIOGRAPHY

7 - 19

Ray, A. A., et al. “A Virtual Environment for Visualizing Fractures During Tunneling,” in Golden
Rocks 2006 – 50 Years of Rock Mechanics, Colorado School of Mines (41st U.S. Rock Mechanics
Symposium, June 2006). Paper No. 06-1104. D. P. Yale et al., eds. ARMA, 2006.
Reddy, M. N., et al. “Novel Approach to Optimise the Dimensions of Pillars in Underground
Hard Rock Mine,” in Geoecology and Computers (3rd International Conference on Advances
of Computer Methods in Geotechnical and Geoenvironmental Engineering, Moscow, February
2000), pp. 451-459. S. A. Yufin, ed. Rotterdam: Balkema, 2000.
Resende, R., J. V. Lemos and P. B. Dinis. “Application of a Discontinuity Model with Softening to
the Analysis of Dam Foundations Using the Discrete Element Method,” in Numerical Modeling
of Discrete Materials in Geotechnical Engineering, Civil Engineering & Earth Sciences (1st
International UDEC/3DEC Symposium, Bochum, Germany, September 2004), pp. 249-255.
H. Konietzky, ed. Leiden: Balkema, 2004.
Roest, J. P. A., R. D. Hart and L. J. Lorig. “Modelling Fault-Slip in Underground Mining with the
Distinct Element Method,” in Proceedings of the 6th International IAEG Congress (Amsterdam,
August, 1990), pp. 105-110. Rotterdam: A. A. Balkema, 1990.
Rosengren, L., M. Board, N. Krauland and S. Sandström. “Numerical Analysis of the Effectiveness
of Reinforcement Methods at the Kristineberg Mine in Sweden,” in Rock Support in Mining and
Underground Construction (Proceedings of the International Symposium on Rock Support,
Sudbury, Ontario, Canada, June, 1992), pp. 507-514. P. K. Kaiser and D. R. McCreath, eds.
Rotterdam: A. A. Balkema, 1993.
Sainsbury, D. P., M. E. Pierce and L. J. Lorig. “Two- and Three-Dimensional Numerical Analysis of
the Interaction between Open-Pit Slope Stability and Remnant Underground Voids,” in Harnessing
Technology by Managing Data and Information (5th Large Open Pit Conference, Kalgoorlie,
Western Australia, November 2003), pp. 251-257. C. Workman-Davies and E. Chanda, eds.
Carlton: AUSIMM (2003).
Salo, J., R. Riekkola, E. Johansson, M. Hakala, P. Särkka and H. Kuula. “Further Development
of the Continuously Yielding Joint Model for Studying Disposal of High-Level Nuclear Waste in
Crystalline Rock (Yhteistyöprojekti II),” Saanio & Riekkola OY, Report T-2000-41/97, November
1997.
Salzer, K., W. Minkley and T. Popp. “Safety Assessment for the Land Surface in the Vicinity of
the Potash Shaft Neutassfurt VI,” in Numerical Modeling of Discrete Materials in Geotechnical
Engineering, Civil Engineering & Earth Sciences (1st International UDEC/3DEC Symposium,
Bochum, Germany, September 2004), pp. 113-119. H. Konietzky, ed. Leiden: Balkema, 2004.
Samadhiya, N. K., M. N. Viladkar and B. Singh. “Three-Dimensional Analysis of a Powerhouse
Cavern in an Anisotropic Rock Mass,” Special Issue of Int. J. Rock Mech. Min. Sci., 41(3), Paper
No. 2B 33 (April 2004). Proceedings of the ISRM SINOROCK2004 symposium (Three Gorges
Project Site, China, May 2004). J. A. Hudson and X.-T. Feng, eds. (2004).
Santarelli, F. J., D. Dahen, H. Baroudi and K. B. Slimane. “Mechanisms of Borehole Instability in
Heavily Fractured Rock,” Int. J. Rock Mech. Min. Sci. & Geomech. Abstr., 29(5), 457-467, 1992.

3DEC Version 4.1
253

7 - 20

User’s Guide

Schelle, H., and G. Grünthal. “Synthetic Earthquake Sequences – Aspects of the Spatiotemporal
Event Distribution,” in Numerical Modeling of Discrete Materials in Geotechnical Engineering, Civil Engineering & Earth Sciences (1st International UDEC/3DEC Symposium, Bochum,
Germany, September 2004), pp. 175-181. H. Konietzky, ed. Leiden: Balkema, 2004.
Segalini, A., et al. “Stability Analysis of Fractured Rock Mass Excavation in Ornamental Stone
Quarries by Means of 3D Numerical Modelling,” in Golden Rocks 2006 – 50 Years of Rock
Mechanics, Colorado School of Mines (41st U.S. Rock Mechanics Symposium, June 2006),
Paper No. 06-1088. D. P. Yale et al., eds. ARMA, 2006.
Senseny, P. E. “Stress Wave Loading of a Tunnel: A Benchmark Study,” in Dynamic Analysis and
Design Considerations for High-Level Nuclear Waste Repositories, pp. 311-338. Q. A. Hossain,
ed. New York: ASCE, 1993.
Sharifzadeh, M., M. Ghorbani and R. Nateghi. “Long Term Stability Assessment of Siah Bisheh
Pumped Storage Powerhouse Cavern Under Saturated Condition,” in The Second Half Century of
Rock Mechanics (11th Congress of the International Society for Rock Mechanics, Lisbon, July
2007), Vol. 2, pp. 947-950. Ribeiro e Sousa, C. Olalla and N. Grossmann, eds. London: Taylor &
Francis Group, 2007.
Shen, B., and O. Stephansson. “Rock Mass Response to Glaciation and Thermal Loading from
Nuclear Waste,” in GEOVAL’90, pp. 550-558. Paris: Organization for Economic Co-operation
and Development, 1991.
Siebrits, E., M. W. Hildyard and A. Daehnke. “Elastodynamics: Past, Present and Future,” in The
Application of Numerical Modeling in Geotechnical Engineering, pp. 9-12. Pretoria: ISRMSANG, 1994.
Sismer, B., et al. “The Rock Mechanics Design for a 352 800 Tonne Mass Blast at the Brunswick
Mine, Bathhurst, New Brunswick,” in NARMS-TAC 2002: Mining and Tunnelling Innovation
and Opportunity, Vol. 1, pp. 815-823. R. Hammah et al., eds. Toronto: University of Toronto
Press, 2002.
Sjöberg, J. “Failure Modes and Pillar Behavior in the Zinkgruvan Mine,” in Rock Mechanics
(Proceedings of the 33rd U.S. Symposium, Santa Fe, June, 1992), pp. 491-500. J. R. Tillerson
and W. R. Wawersik, eds. Rotterdam: A. A. Balkema, 1992.
Sjöberg, J., E. Nordlund and E. Olofsson. “Analysis of Rock Culverts under Railroads,” in Rock
Mechanics for Industry (Proceedings of the 37th U.S. Rock Mech. Symp., Vail, Colorado, June
1999), Vol. 2, pp. 577-584. Bernard Amadei et al., eds. Rotterdam: A. A. Balkema, 1999.
Staub, I., A. Fredriksson and R. Christiansson. “A Theoretical Model for the Characterisation
of Rock Mass Mechanical Properties – Application at the Äspö HRL, Sweden,” in Technology
Roadmap for Rock Mechanics (10th Congress of the ISRM, Johannesburg, September 2003),
Vol. 2, pp. 1161-1166. Johannesburg: SAIMM, 2003.

3DEC Version 4.1
254

BIBLIOGRAPHY

7 - 21

Stead, D., et al. “New Developments in Rock Slope Engineering: Implications for Open Pit Slope
Design,” in Sea to Sky Geotechnique (Canadian Geotechnical Conference & 7th Joint CGS/IAHCNC Groundwater Specialty Conference, Vancouver, October 2006), pp. 1054-1061, Paper No.
0163-170 (2006).
Stephansson, O. “Rock Mechanics and Rock Engineering of Spent Nuclear Fuel and Radioactive
Waste Repositories in Sweden,” in Proceedings of the International Workshop on the Rock Mechanics of Nuclear Waste Repositories (Vail, Colorado, June 1999), pp. 205-227. S. Saeb and
C. Francke, eds. Alexandria, Virginia: American Rock Mechanics Association, 1999.
Stephansson, O., and B. Shen. “Modelling of Rock Masses for Site Location of a Nuclear Waste
Repository,” in Proceedings of the 7th International Congress on Rock Mechanics (Aachen,
Germany, September, 1991), Vol. 1, pp. 157-162. Rotterdam: A. A. Balkema, 1991.
Stephansson, O., B. Shen and J. Lemos. “Modelling of Excavation, Thermal Loading and Bentonite
Swelling Pressure for a Waste Repository,” in High-Level Waste Management (Proceedings of the
Second Annual International Conference, Las Vegas, Nevada, April-May, 1991), pp. 1375-1381.
New York: American Nuclear Society/ASCE, 1991.
Strouth, A., and E. Eberhardt. “The Use if LiDAR to Overcome Rock Slope Hazard Data Collection
Challenges at Afternoon Creek, Washington,” in Golden Rocks 2006 – 50 Years of Rock Mechanics,
Colorado School of Mines (41st U.S. Rock Mechanics Symposium, June 2006), Paper No. 06-993.
D. P. Yale, eds. ARMA, 2006.
Thorval, A., H. Baroudi, J. P. Piguet, E. Vuillod, G. Abdallah, A. Hosni and J. Lin. “Couple
Thermo-Hydro-Mechanical Phenomena in Fractured Rocks: Recent Developments in Modelling
Methods and Validation Tests (in French),” in Proceedings of the 8th International Congress on
Rock Mechanics (Tokyo, September, 1995), Vol. 2, pp. 703-706. T. Fujii, ed. Rotterdam: A. A.
Balkema, 1995.
Tinucci, J. P. “A Ground Control Computer Program for Support Analyses of Three-Dimensional
Critical Rock Blocks,” in Rock Support in Mining and Underground Construction (Proceedings
of the International Symposium on Rock Support, Sudbury, Ontario, Canada, June, 1992),
pp. 49-56. P. K. Kaiser and D. R. McCreath, eds. Rotterdam: A. A. Balkema, 1992.
Tinucci, J. P., and D. S. G. Hanson. “Assessment of Seismic Fault-Slip Potential at the Strathcona
Mine,” in Rock Mechanics Contributions and Challenges, pp. 753-760. Rotterdam: A. A.
Balkema, 1990.
Tinucci, J. P., and J. Israelsson. “Site Characterization and Validation Excavation Stress Effects
around the Validation Drift,” SKB Stripa Project Technical Report 91-20, August 1991.
Tinucci, J. P., A. R. Leach and A. J. S. Spearing. “Improved Seismic Ground Conditions with the
Double-Cut Mining Method in Wide Tabular Reef Extraction,” in Rockbursts and Seismicity in
Mines 93 (Proceedings of the International Symposium, Kingston, Ontario, Canada, August,
1993), pp. 429-434. R. Paul Young, ed. Rotterdam: A. A. Balkema, 1993.

3DEC Version 4.1
255

7 - 22

User’s Guide

Tolppanen, P. J., E. J. W. Johansson and R. Riekkola. “Comparison of Vertical and Horizontal Deposition Hole Concept for Disposal of Spent Fuel Based on the Rock Mechanical In-Situ
Stress/Strength Analyses,” in Preprints of Contributions to the Workshop on Computational Methods in Engineering Geology (Lund, Sweden, October, 1996), pp. 230-237. R. Pusch and R. Adey,
eds. Lund: Clay Technology AB, 1996.
Tolppanen, P. J., E. J. W. Johansson and J. P. Salo. “Rock Mechanical Analyses of In-Situ
Stress/Strength Ratio at the Posiva Oy Investigation Sites, Kivetty, Olkiluoto and Romuvaara, in
Finland,” in Prediction and Performance in Rock Mechanics & Rock Engineering (Proceedings
of ISRM International Symposium EUROCK ’96, Turin, September, 1996), Vol. 1, pp. 435-442.
G. Barla, ed. Rotterdam: A. A. Balkema, 1996.
Valdivia, C., and L. Lorig. “Slope Stability at Escondida Mine,” in Slope Stability in Surface
Mining, Ch. 17, pp. 153-162. W. A. Hustrulid, M. K. McCarter and D. J. A. Van Zyl, eds.
Littleton, Colorado: SME, 2000.
Vervoort, A. “Initial Roof Movement during Development of Room and Pillar Sections,” in Computer Methods and Advances in Geomechanics (Proceedings of the 7th International Conference,
Cairns, Australia, May, 1991). Rotterdam: A. A. Balkema, 1991.
Vonk, R. A., H. S. Rutten, J. G. M. van Mier and H. J. Fijneman. “Micromechanical Simulation of
Concrete Softening,” in Fracture Processes in Concrete, Rock and Ceramics, Section 10. London:
E. & F. N. Spon, 1991.
Voyat, I., et al. “Advanced Techniques for Geo Structural Surveys in Modelling Fractured Rock
Masses: Application to Two Alpine Sites,” in Golden Rocks 2006 – 50 Years of Rock Mechanics,
Colorado School of Mines (41st U.S. Rock Mechanics Symposium, June 2006), Paper No. 061138. D. P. Yale et al., eds. ARMA, 2006.
Windsor, C. R. “Invited Lecture: Cable Bolting for Underground and Surface Excavations,” in
Rock Support in Mining and Underground Construction, pp. 349-366. P. K. Kaiser and D. R.
McCreath, eds. Rotterdam: Balkema, 1992.
Wyllie, D. C., and C. W. Mah, eds. Rock Slope Engineering, 4th ed. London: Spon Press, 2004.
Yan, M., D. Stead and M. Sturzenegger. “Step-Path Characterization in Rock Slopes: An Integrated
Digital Imaging-Numerical Modeling Approach,” in The Second Half Century of Rock Mechanics
(11th Congress of the International Society for Rock Mechanics, Lisbon, July 2007), Vol. 1, pp.
693-696. L. Ribeiro e Sousa, C. Olalla and N. Grossmann, eds. London: Taylor & Francis Group,
2007.
Zhu, F., O. Stephansson and Y. Wang. “Stability Investigation and Reinforcement for Slope at Daye
Open Pit Mine, China,” in Prediction and Performance in Rock Mechanics & Rock Engineering
(EUROCK ‘96, Turin, September 1996), Vol. 1, pp. 621-625. G. Barla, ed. Rotterdam: Balkema,
1996.

3DEC Version 4.1
256

BIBLIOGRAPHY

7 - 23

Zhu, H. “Discussion on the Determination of the Kbond Parameter for the Numerical Modeling of
Cablebolt Elements with 3DEC,” in Numerical Modeling of Discrete Materials in Geotechnical
Engineering, Civil Engineering & Earth Sciences (1st International UDEC/3DEC Symposium,
Bochum, Germany, September 2004), pp. 209-211. H. Konietzky, ed. Leiden: Balkema, 2004.
Zhu, H., H. Li and C. O’Connor. “Numerical Modeling of Brittle Rock Failure (in Chinese),” in
Proceedings, 9th China National Rock Mechanics & Engineering Conference, pp. 260-266.
Beijing: Science Publishing Co., 2006.

3DEC Version 4.1
257

7 - 24

User’s Guide

NOTE: NUREG reports may be ordered from:
The National Technical Information Service
5285 Fort Royal Road
Springfield, Virginia 22161
Telephone: (703)-487-4650

3DEC Version 4.1
258

3DEC
3 Dimensional Distinct Element Code
Command Reference

©2007
Itasca Consulting Group, Inc.
Mill Place
111 Third Avenue South, Suite 450
Minneapolis, Minnesota 55401 USA

259

Phone:
Fax:
E-Mail:
Web:

(1) 612-371-4711
(1) 612·371·4717
software@itascacg.com
www.itascacg.com

First Edition December 1998
First Revision May 1999
Second Revision September 1999
Second Edition January 2003
First Revision August 2005
Third Edition December 2007*

* Please see the errata page in the \Manuals\3DEC410 folder.

260

Command Reference

Contents - 1

TABLE OF CONTENTS
1 COMMAND REFERENCE
1.1

1.2

1.3

Common Conventions and Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.2 Interactive Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.3 Range Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.4 FISH Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.5 Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Commands by Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.1 Specify Program Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2 Specify Special Calculation Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3 Input Problem Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4 Specify Block Deformability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5 Assign Constitutive Relations and Properties . . . . . . . . . . . . . . . . . . . . . . .
1.2.6 Assign Initial Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7 Apply Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8 Perform Alterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.9 Specify Solution Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.10 Specify User-Defined Variables or Functions . . . . . . . . . . . . . . . . . . . . . . .
1.2.11 Monitor Model Conditions during the Solution Process . . . . . . . . . . . . . .
1.2.12 Solve the Problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.13 Generate Model Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.14 Access the DOS System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.15 Monitor Problem Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3DEC Commands — Detailed Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-1
1-1
1-2
1-3
1 - 11
1 - 11
1 - 12
1 - 12
1 - 13
1 - 13
1 - 14
1 - 14
1 - 14
1 - 15
1 - 15
1 - 16
1 - 16
1 - 17
1 - 17
1 - 17
1 - 18
1 - 18
1 - 18

3DEC Version 4.1
261

Contents - 2

Command Reference

TABLES
Table 1.1
Table 1.2
Table 1.3
Table 1.4
Table 1.5
Table 1.6
Table 1.7
Table 1.8
Table 1.9
Table 1.10
Table 1.11

Interactive input editing keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Commands accepting the range phrase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constitutive models for deformable blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Joint constitutive models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Summary of PLOT manipulation keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Color switch keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Line switch keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Text switch keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
List of available plot items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Summary of SET keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Property groups by failure segment for the bilinear, strain-hardening/softening
ubiquitous-joint model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3DEC Version 4.1
262

1-2
1-3
1 - 34
1 - 35
1 - 134
1 - 136
1 - 137
1 - 137
1 - 152
1 - 359
1 - 434

Command Reference

Contents - 3

FIGURES
Figure 1.1
Figure 1.2
Figure 1.3
Figure 1.4
Figure 1.5

Relations between block edge lengths and the input parameters i1, i2 and i3
Definition and description of view-setting keywords . . . . . . . . . . . . . . . . . . . . .
Parameters used in defining partial tunnel liners . . . . . . . . . . . . . . . . . . . . . . . . .
Grout material properties for cable elements . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cable material properties for cable elements . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1 - 75
1 - 150
1 - 387
1 - 390
1 - 391

3DEC Version 4.1
263

Contents - 4

Command Reference

EXAMPLES
Example 1.1
Example 1.2

Performing union and intersection of range elements . . . . . . . . . . . . . . . . . . . 1 - 4
Use of a FISH range element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 - 10

3DEC Version 4.1
264

COMMAND REFERENCE

1-1

1 COMMAND REFERENCE
This section contains detailed information about all the commands used by 3DEC. The commands
are described in two major sections. First, Section 1.2 contains a summary of the commands, organized into groups of related modeling functions. (This summary is also intended as a recommended
command sequence for preparing an input data file.) Second, Section 1.3 contains an alphabetical
listing (with detailed descriptions) of all the commands.
The syntax which must be followed when entering commands is described below, in Section 1.1.
1.1 Common Conventions and Features
1.1.1 Syntax
3DEC may be operated in “interactive” mode (i.e., commands entered via the keyboard) or “filedriven” mode (i.e., data stored in a data file and read in from the hard drive). In either case, the
commands for running a problem are identical, and the particular method of data input depends on
user preference.
All input commands are word-oriented and consist of a primary COMMAND word followed by one or
more keywords, and numerical input, as required. Some commands (e.g., PLOT) accept “switches,”
which are keywords that modify the action of the command. Each command has the following
format:

COMMAND

keyword value . . . 

The commands are typed literally on the input line. You will note that only the first few letters are
presented in bold type. The program requires only these letters to be typed (at a minimum) for the
command to be recognized. Likewise, the keywords (shown in lowercase) are typed literally, and
only those letters designated by bold type need to be entered for the keyword to be recognized. The
entire word for a command or keyword may be entered if the user so desires. By default, the words
are not case-sensitive: either uppercase or lowercase letters may be used.
Many of the keywords are followed by a series of numbers (values) that provide the numeric input
required by the keyword. Words appearing in bold italic type stand for numbers. Integers are
expected when the word begins with i, j, m or n; otherwise, a real (or decimal) number is expected.
The decimal point can be omitted from a real number; a decimal point must not appear in an integer.
Commands, keywords and numeric values may be separated by any number of spaces, or by any
of the following delimiters:
( )

,

=

3DEC Version 4.1
265

1-2

Command Reference

You will see additional notations with some of the input parameters. These are:
< > denotes optional parameter(s). (The brackets are not to be typed.)
. . . indicates that an arbitrary number of such parameters may be given.
Anything that follows a semicolon ( ; ) in the input line is taken to be a comment and is ignored.
It is useful to make such comments in the input file when running in batch (i.e., file-driven) mode,
since the comments are reproduced in the output. A single input line, including comments, may
contain up to 80 characters. An ampersand (&) at the end of a line denotes that the next line is a
continuation of keywords or numeric input. The maximum length of a single command, including
all continuations, is 5000 characters. A maximum of 1000 input parameters are allowed in one
command.
The keyword bool is used to describe the input of a Boolean value (e.g., on or off, true or false).
Any of these keywords may be used to define a Boolean: off, false, no, on, true, yes. In general, if
none of the preceding keywords is specified, on is implied.
1.1.2 Interactive Input
There are several line-editing features that can be used when entering data interactively. These
features are summarized in Table 1.1:
Table 1.1
Key

Effect

any character key

inserts character on input line

<←>

moves cursor left on input line

<→>

moves cursor right on input line



cursor jumps to next input parameter to the left



cursor jumps to next input parameter to the right



deletes character to left of cursor



deletes character at cursor location



moves cursor to end of input line

<↑>

moves back through history of command input by keyboard

<↓>

moves forward through history of command input by keyboard



moves cursor to beginning of input line

3DEC Version 4.1
266

Interactive input editing keys

COMMAND REFERENCE

1-3

1.1.3 Range Logic
The range logic allows the user to apply certain commands to a restricted set of objects (such as
blocks, contacts or gridpoints). The commands in Table 1.2 accept an optional range keyword
phrase, which must be given at the end of the command line. If the range keyword is not specified,
then the command will be applied to all relevant visible objects in the model.

Table 1.2 Commands accepting
the range phrase
APPLY
BOUNDARY
CHANGE
DELETE
EXCAVATE
FFIELD
FILL
FIX
FREE
GENERATE
HIDE
INITIALIZE
INSITU
JMODEL
JOIN
LIST
MARK
PFIX
PLOT
REMOVE
SHOW
STRUCTURE
ZONE
A range identifies a set of objects, and is comprised of any number of range elements (defined
below). If multiple range elements are specified, the final set of objects will be those that comprise
the intersection of the separate range elements. This behavior can be modified using the union
keyword. If union is specified, the range will be a union of the range elements. In addition, all
objects not within a particular range element are identified by giving not immediately following
that range element.

3DEC Version 4.1
267

1-4

Command Reference

A named range can be created via the RANGE command. Once a range has been named, the name
becomes a keyword that can be specified in place of a range element in any command that uses the
range logic (see the nrange entry, below).
The procedure by which multiple range elements can be combined to produce the union or the
intersection of the different range elements is illustrated in Example 1.1. First, an assembly of
1000 blocks is generated. Then, two separate named ranges are created. The first named range,
“intersected blocks,” contains the blocks comprising the intersection of the x and y range elements.
The second named range, “union blocks,” contains the blocks comprising the union of the x and y
range elements. The blocks comprising these two different named ranges are then plotted in red in
two different plot views.

Example 1.1 Performing union and intersection of range elements
;fname: range1.dat
new
poly brick -1 1 -1 1 -1 1
jset number 10 spacing 0.2
jset dip 90 number 10 spacing 0.2
jset dip 90 dd 90 number 10 spacing 0.2
range name intersected_blocks x=(0,0.6) y = (-0.4,0.4)
range name union_blocks union x=(0,0.6) y = (-0.4,0.4)
plot create view intersected_blocks
plot add block yellow range nrange intersected_blocks not
plot add block red range nrange intersected_blocks
plot add axes
plot create view united_blocks
plot add block yellow range nrange union_blocks not
plot add block red range nrange union_blocks
plot add axes

The following range elements (specified by stating these keyword phrases immediately following
the range keyword) are provided in 3DEC. In addition to this built-in set of range elements, userdefined range elements can be created using FISH (see the fish entry, below).
In general, if the range element is designed to select blocks, then other types of objects will react
in the following ways:
• Contacts will be selected if either of the blocks they are connecting is selected.
• Vertices will be selected if they are contained within a block that is selected.
• Faces will be selected if they are contained within a block that is selected.
• Zones will be selected if they are contained within a block that is selected.

3DEC Version 4.1
268

COMMAND REFERENCE

1-5

And if the range element is designed to select contacts, then other types of objects will react in the
following ways:
• Blocks will be selected if any contact attached to this block is selected.
• Vertices will be selected if they are contained within a block that is selected.
• Faces will be selected if they are contained within a block that is selected.
• Zones will be selected if they are contained within a block that is selected.

annulus

center x y z radius r1 r2
spherical annular region with center at (x, y, z), inner radius of r1 and
outer radius of r2

bid

il 
blocks with ID numbers in the interval (il,iu) – if iu is not specified,
then it is set equal to il. Block ID numbers are distinct from block
addresses.

bmaterial


selects blocks with material numbers imat1, imat2, etc. Any number
of imats may be added to the list, and any block with a material
number that matches any of the imats in the list is part of the element.

cylinder

end1 x1 y1 z1 end2 x2 y2 z2 radius r 
cylindrical range with one end of the cylinder axis (end1) at location
(x1, y1, z1), and the other end (end2) at location (x2, y2, z2), with
a radius r. If r2 is specified, then the range is a cylindrical annulus
from r to r2.

deformable

selects blocks that are deformable.

displacement dl  
selects vertices with displacements in the interval (dl,du). (If du is
not specified, then the interval is set equal to (dl−t,dl+t); if neither
vu nor t is specified, t is set equal to dl ×10−6 . Note that a tolerance
should only be specified if du is not specified.) Blocks are selected if
any of their vertices is selected by the element. Zones are selected if
any of their vertices is selected by the element. Faces are selected if
any of their vertices is selected by the element. Contacts are selected
if either of the two blocks they connect is selected.

excavated

selects blocks that have been excavated (see the EXCAVATE command).

3DEC Version 4.1
269

1-6

Command Reference

feface

il 
finite element face numbers in the interval (il,iu); if iu is not specified,
then it is set equal to il. Vertices are selected if they belong to a finite
element face that falls within the element. Finite element faces are
selected if they belong to a finite element that is selected.

fish

fname
invokes the user-defined range element that is implemented by the
function fname. A range-element function must be a function accepting two arguments, and must return an integer. The first argument is
a vector indicating the position of the object. The second argument
to the function is a pointer to the object being filtered. A non-zero
return value means the object falls within the range element; a zero
return value means the object falls outside of the range element.
Example 1.2 illustrates how to define and invoke a user-defined range
element. In this example, an assembly of 1000 blocks is generated.
Then, a range-element function called cylinder element is defined. This function returns a value of 0 if the queried object is not
within the circle with center at (cy x, cy z) and radius of cy rad.
The function is called during the CHANGE command, which assigns
material number 2 to all blocks in the range. The blocks in the group
are then plotted with the block plot-item.

id

il 
objects with ID numbers in the interval (il, iu); if iu is not specified,
then iu is set equal to il

jmaterial


selects contacts with material numbers jmat1, jmat2, etc. Any number
of jmats may be added to the list, and any block with a material number
that matches any of the jmats in the list is part of the element.

joint


selects contacts with joint ID numbers jid1, jid2, etc. Any number of
jids may be added to the list, and any contact with a joint ID number
that matches any of the jids in the list is part of the element.

mintersection imat1 imat2
selects contacts that connect one block with material number imat1,
and a second block with material number imat2.

3DEC Version 4.1
270

COMMAND REFERENCE

name

1-7

rname
creates a named range called rname that is described by the collection
of range elements contained in the command line. Typically, a named
range is created via the RANGE command.

nrange

sname
named range sname

orientation

keyword
selects contacts or faces whose orientations match the orientation
specified. If dip or dd (dipdirection) is specified, then the dip and
dipdirection of the object must be within the default or assigned tolerance. If normal is specified, then the angle between the object’s
normal vector and the vector specified must be within the default or
specified tolerance.

dd

dd 
specifies the dip direction angle required. ddtol specifies the tolerance in degrees. (The default value for
ddtol is 2 degrees.)

dip

dip 
specifies the dip angle required. diptol specifies the
tolerance in degrees. (The default value for diptol is 2
degrees.)

dipdirection

dd 
This is a synonym for dd.

normal

nx, ny, nz 
specifies the normal direction required. normtol specifies the tolerance in degrees. The tolerance in this
case is the angle between the object’s normal vector
and this normal vector. (The default value for normtol
is 2 degrees.)

3DEC Version 4.1
271

1-8

Command Reference

plane

keyword
region surrounding an infinite plane. The plane is defined by origin
and either dip and dd, or normal. The region surrounding the plane is
defined by either above, below or distance.

above

half-space above the plane

below

half-space below the plane

dd

dd
dip-direction angle [degrees], measured in the global
xy-plane, clockwise from the positive y-axis

dip

dip
dip angle [degrees], measured in the negative z-direction from the global xy-plane

distance

d
region within distance d of the plane

normal

nx ny nz
unit normal vector (nx, ny, nz) of the plane

origin

x y z
a point (x, y, z) on the plane

region


selects blocks with region numbers ireg1, ireg2, etc. Any number of
iregs may be added to the list, and any block with a region number
that matches any of the iregs in the list is part of the element.

rintersection

ireg1 ireg2
selects contacts that connect one block with region number ireg1, and
a second block with region number ireg2.

sphere

center x y z radius r
spherical region with center at (x, y, z) and radius of r

3DEC Version 4.1
272

COMMAND REFERENCE

sregion

1-9


selects faces with surface region numbers ireg1, ireg2, etc. Any
number of iregs may be added to the list, and any face with a surface
region number that matches any of the iregs in the list is part of the
element. Blocks are selected if any of its faces is selected by the
element. Vertices are selected if they are part of a face selected by
the element.

velocity

vl 
selects vertices with velocities in the interval (vl,vu). (If vu is not
specified, then the interval is set equal to (xl−t,xl+t); if neither vu nor
t is specified, t is set equal to xl ×10−6 . Note that a tolerance should
only be specified if vu is not specified.) Blocks, zones and faces are
selected if any of their vertices is selected by the element. Contacts
are selected if either of the two blocks they connect is selected.

vid

il 
vertices with ID numbers in the interval (il,iu) – if iu is not specified,
then it is set equal to il. Note that ID numbers are distinct from
addresses. Blocks, faces and zones are selected if any of their vertices
is selected. Contacts are selected if either of the two blocks they
connect is selected.

volume

vl  
selects blocks with volumes in the interval (vl,vu). (If vu is not specified, then the interval is set equal to (xl−t,xl+t); if neither vu nor t
is specified, t is set equal to xl ×10−6 . Note that a tolerance should
only be specified if vu is not specified.)

x

xl  
objects with x-coordinate in the interval (xl, xu). (If xu is not specified, then the interval is set equal to (xl−t, xl+t); if neither xu nor t
is specified, t is set equal to xl ×10−6 . Note that a tolerance should
only be specified if xu is not specified.)

y

yl  
objects with y-coordinate in the interval (yl, yu). (If yu is not specified,
then the interval is set equal to (yl−t, yl+t); if neither yu nor t is
specified, t is set equal to yl ×10−6 . Note that a tolerance should only
be specified if yu is not specified.)

3DEC Version 4.1
273

1 - 10

Command Reference

z

zl  
objects with z-coordinate in the interval (zl, zu). (If zu is not specified,
then the interval is set equal to (zl − t, zl + t); if neither zu nor t is
specified, t is set equal to zl ×10−6 . Note that a tolerance should only
be specified if zu is not specified.)

Example 1.2 Use of a FISH range element
;fname: range2.dat
new
poly brick -1 1 -1 1 -1 1
jset number 10 spacing 0.2
jset dip 90 dd 90 number 20 spacing 0.2
;
def cylinder_element
argument position
argument object
; ----- Defined a FISH range element that determines whether an object
;
lies within a cylinder of radius [cy_rad] with axis perpendicular
;
to the x-y plane and with coordinates [cy_x], [cy_y].
;
; INPUT: cy_x, cy_y - global symbols defining the center of the circle.
;
cy_rad
- global symbol defining the radius of the circle.
;
; RETURN VALUE: 0 - object does not lie within circle
;
1 - object does lie within circle
local dist = sqrt( (xcomp(position) - cy_x)ˆ2 + (ycomp(position)-cy_y)ˆ2)
if dist < cy_rad then ; object is not within the circle
cylinder_element = 1
else
cylinder_element = 0
endif
end
set @cy_x=0.0 @cy_y=0.0 @cy_rad=0.6
change mat=2 range fish cylinder_element
plot create the_cylinder
plot add block colorby material

3DEC Version 4.1
274

COMMAND REFERENCE

1 - 11

1.1.4 FISH Substitution
The embedded language FISH may be used to prescribe user-defined modeling conditions (including property and boundary-condition variations) and controls (to perform parameter studies, for
example). Any real, integer or string on any 3DEC input line may be replaced by a FISH variable
or function name, provided that the name has already been mentioned in a DEFINE . . . END segment.
The FISH symbol must be prefixed by an @ character unless safe mode has been turned off. (See
SET fish safe conversion.) See Section 2.4.2 in the FISH volume for more details.
1.1.5 Online Help
The 3DEC Help menu contains two help files: 3DEC Help and 3DEC GUI Help. The 3DEC
Help file provides, for ease of reference, the complete Command Reference, FISH in 3DEC and
Verification Problems and Example Applications volumes from the printed (and PDF) 3DEC
Manual, in HTML-help format. 3DEC GUI Help provides reference information and a guide for
operating the 3DEC user-interface.
Another form of help is also available within 3DEC: a command and keyword list. The ? (or help)
keyword lists all of the keywords that apply to each 3DEC command. For example, to list all of the
keywords that apply to the DELETE command, type
delete ?

Some keywords that are listed by help are not described in the manual. These are usually obsolete
keywords. They exist to support data files created for previous versions of 3DEC, but their use is
discouraged.
Note that the ? command does more than just list keywords: It lists all entities (keywords, numbers,
strings, etc.) in alphabetical order.

3DEC Version 4.1
275

1 - 12

Command Reference

1.2 Commands by Function
The following is a recommended sequence for command input, according to function. In general,
commands may be given in any logical order; however, certain commands must precede others.
These are identified in this section. Only the primary command words and most frequently used
keywords are presented; detailed descriptions of all commands and keywords are given in Section 1.3.
1.2.1 Specify Program Controls
Certain commands allow the user to start new analyses without leaving 3DEC, or to restart previous
model simulations and continue from the last analysis stage. The following commands provide
program control:

CALL

reads a user-prepared batch input data file into 3DEC and executes the commands.
This is called batch mode.

CONTINUE

continues reading a batch file after it has been interrupted due to a pause or an error.

NEW

starts a new problem without exiting 3DEC.

PAUSE

pauses reading of a batch file.

QUIT/EXIT

stops execution of 3DEC and returns control to the operating system.

RESTORE

restores an existing saved state from a previously executed problem.

RETURN

returns program control from batch mode to the local, interactive mode (or to the
calling file if multiple levels of calls are nested).

SAVE

saves the current state of the analysis in a file.



interrupts program execution at any time during cycling, block creation or zone
generation. When the  key is pressed, the process being performed will stop,
and control will return to the user. At this point, the user can save the state of the
model or continue program operation.

To avoid confusion when a saved state is RESTOREd or an input file is CALLed, it is best to give
SAVEd files (e.g., “.SAV”) and input files (e.g., “.DAT”) different extensions.

3DEC Version 4.1
276

COMMAND REFERENCE

1 - 13

1.2.2 Specify Special Calculation Modes
3DEC performs mechanical calculations as the standard mode. Optional calculation modes are also
available and are specified with the CONFIG command. CONFIG must be given before the POLY
command if one or more of the following options is used:

cppudm

extended material models and user-defined constitutive models (only
available with the user-defined models option)

creep

allows creep constitutive models to be used.

dynamic

fully dynamic analysis (only available with the dynamic option —
see Section 2 in Optional Features)

feblock

finite element coupling (only available with the structural lining option — see Section 3 in Optional Features)

gwflow

fracture fluid flow

highorder

high-order elements

liner

structural tunnel liners (only available with the structural lining option
— see Section 3 in Optional Features)

thermal

thermal analysis (only available with the thermal option — see Section 1 in Optional Features)

1.2.3 Input Problem Geometry
The general procedure to establish the problem geometry is to:
(1) Create single or multiple rigid block(s) defining the original boundary of the
modeled region using one or several POLY commands.
(2) Create single or multiple joints in a block using the JSET command. Use the
HIDE and SHOW commands to create noncontinuous joints.
(3) Create boundaries of man-made structures (e.g., slopes, tunnels, stopes), either manually with the JSET command or automatically with the TUNNEL
command.
(4) Delineate regions in the model with the MARK command for future alteration.
Additionally, split blocks can be rejoined using the JOIN command.
WARNING: All possible future blocks must be created during this step because
blocks can no longer be created once they are zoned and execution has begun.
Once rigid blocks are zoned as fully deformable blocks, they can no longer be
split.

3DEC Version 4.1
277

1 - 14

Command Reference

1.2.4 Specify Block Deformability
All blocks are rigid by default. The GENERATE command discretizes specified blocks into constantstrain finite-difference tetrahedral zones. Rigid and deformable blocks cannot be mixed in one
model.
1.2.5 Assign Constitutive Relations and Properties
There are two separate methods for assigning constitutive models and properties for 3DEC blocks
and joints. The first method uses property arrays and is more memory efficient. This method makes
use of the CHANGE command to assign the constitutive models; it uses the PROPERTY command
to assign property values. This method is limited to 50 variations in each property
The second method uses externally defined DLL constitutive models, and allocates local property
storage space for each zone or joint. This consumes more memory than the previously described
method. The ZONE command is used to assign constitutive models and properties for zones, and
the JMODEL command is used to define constitutive models and properties for joints.
Constitutive models that are placed in the appropriate plug-in folders are automatically loaded into
3DEC at runtime (i.e., c:\program files\itasca\3dec410\plugins\models for zone models). The
LOAD command may be used to load models that are not placed in these plug-in folders. Some
of the models in the models plug-in folder are only available after purchasing the User-Defined
Models (UDM) option and using the CONFIG cppudm command.
1.2.6 Assign Initial Conditions
Initial problem and model solution conditions are assigned with the following commands:
GRAVITY

sets gravitational acceleration in the x-, y- and z-directions.

INITEMP

initializes temperature.

INITIALIZE

initializes certain gridpoint and zone variables.

INSITU

sets initial zone stresses in all fully deformable blocks and joints.

RESET

resets certain variables to zero.

WATER

initializes water table conditions for effective stress calculation.

3DEC Version 4.1
278

COMMAND REFERENCE

1 - 15

1.2.7 Apply Boundary Conditions
Model boundary conditions are prescribed with the following commands:
APPLY

applies velocities at block centroids of rigid blocks.

BOUNDARY

applies mechanical boundary conditions.

COUPLE

switches forces exerted between different regions of a model on and off.

FFIELD

applies free-field boundary blocks for dynamic problems.

FIX/FREE

allows velocity at block centroids to be fixed (i.e., prevented from changing) or freed
(i.e., allowed to change) for selected blocks.

FLUID

specifies a joint fluid-flow condition.

ISOTHERMAL defines isothermal boundary layers.
LINE

applies a “line” heat source consisting of np point sources.

PFIX

allows pressure to be fixed or freed at selected joint contacts.

POINT

applies a heat point source.

SOURCE

defines general information about the heat source components.

SYMMETRY

defines thermal symmetry planes.

1.2.8 Perform Alterations
(1) Excavate/Fill Openings
Openings in the model can be excavated with the EXCAVATE command and
backfilled with the FILL command. Individual blocks or block regions can be
deleted with the DELETE or REMOVE command. Once a block is deleted, it
cannot be recalled.
(2) Change Material Models, Properties or Boundary Conditions
Block or joint material models can be changed at any time with the CHANGE
command. Properties can be changed with the PROPERTY command, and
boundary conditions can be changed (see Section 4 in Theory and Background). Use the CAVE command to simulate material property change due
to caving.

3DEC Version 4.1
279

1 - 16

Command Reference

(3) Specify Structural Support
Four types of artificial passive support may be specified via the STRUCT command:
(a) STRUCT beam, which generates structural elements attached to zone
gridpoints;
(b) STRUCT cable, which generates global reinforcing elements across
joints and within deformable blocks for modeling fully bonded passive reinforcement that explicitly considers the shear behavior of
the grout annulus;
(c) STRUCT axial, which generates local reinforcement elements
across joints for modeling fully bonded passive reinforcement in
hard rocks; and
(d) STRUCT liner, which generates structural elements for modeling
tunnel lining (only available with the structural lining option — see
Section 3 in Optional Features).
1.2.9 Specify Solution Conditions
The following commands may be used to specify numerical conditions to achieve a solution:

DAMPING

material damping (used to absorb kinetic energy)

FRACTION

fraction of critical timestep used in solution

MSCALE

sets zone and block masses for mass-scaling.

SET

sets certain internal variables such as time interval to update contacts.

1.2.10 Specify User-Defined Variables or Functions
FISH, the embedded programming language in 3DEC, may be invoked to define special variables or
functions that a user wishes to use for a specific problem. FISH statements (described in Section 2
in the FISH volume) are any statements given between the 3DEC commands DEFINE and END.
Model conditions can also be varied using the TABLE command.

3DEC Version 4.1
280

COMMAND REFERENCE

1 - 17

1.2.11 Monitor Model Conditions during the Solution Process
The HISTORY command is available to monitor the change in model variables as the solution
process progresses. This is helpful both to ascertain when an equilibrium or failure state has been
reached, and to monitor the change in variables during transient calculations (such as dynamic wave
propagation).
HISTORY

makes a record of the changes in a variable as timestepping proceeds. The resulting
plots help the user identify when a steady-state condition is reached.

1.2.12 Solve the Problem
Once the appropriate problem conditions are defined in the 3DEC model, the problem is solved by
taking a series of calculational steps or cycles:
CYCLE n

execute n cycles (timesteps)

SOLVE

cycles until a defined limit is reached

SOLVE fos

determines a factor of safety against general collapse

STEP n

execute n cycles (timesteps)

The maximum out-of-balance force is the maximum of the gridpoint force sums for all gridpoints.
For static equilibrium, this value will trend toward zero. The maximum out-of-balance force for
the model is continually printed to the screen. The user may interrupt the calculational stepping at
any time by pressing the  key. 3DEC will return full control to the user after the current step
is complete; the user may then check the solution and save the state, or continue with the analysis,
if desired.
THSOLVE

The thermal solution is calculated when this command is given.

1.2.13 Generate Model Output
Several commands are available to allow the user to examine the current problem state:
LIST

prints output for problem conditions and main variables of the model.

PLOT

requests a plot, on the screen, of various problem variables, including the
HISTORY of a variable.

SET

log
allows the user to save a record of interactive sessions on a file. The SET command
also provides several controls over different plotting conditions.

TITLE

assigns a title to a plot.

3DEC Version 4.1
281

1 - 18

Command Reference

1.2.14 Access the DOS System
The 3DEC command SYSTEM is available to allow the user to access DOS commands without
leaving 3DEC.
1.2.15 Monitor Problem Variables
A command is available to track variables not specifically identified by 3DEC:

HISTORY

monitors the change of an individual variable.

1.3 3DEC Commands — Detailed Listing
The detailed listing of all 3DEC commands (in alphabetical order) follows.

3DEC Version 4.1
282

COMMAND REFERENCE
APPLY

APPLY

1 - 19

keyword value  
Velocities or thermal boundary conditions are applied to the centroids of rigid blocks.
The range over which the item is applied can be limited by the optional range. Ranges
are described in Section 1.1.3.
The following keywords are available to apply velocities:

xvel

v
constant velocity in x-direction

yvel

v
constant velocity in y-direction

zvel

v
constant velocity in z-direction

thermal

The thermal keyword is used to apply thermal boundary conditions
to any external or internal boundary of the model grid, or to interior
gridpoints. The user must specify the keyword type to be applied (e.g.,
flux), the numerical value (if required), and the range over which the
boundary conditions are to be applied.
Two keyword types are used to apply thermal boundary conditions.
The associated keywords are given for each type.
Gridpoint-Type Keywords

psource

v
A heat-generating source, v, is applied as a point source
of the specified strength (e.g., in W) at each gridpoint
in the specified range. When a new source is applied
to a gridpoint with an existing source, the new source
strength replaces the existing source strength.

temp

t
Temperature is fixed at all gridpoints in the specified
range. The history keyword can be used to prescribe
a temperature history. (See the flux keyword for an
example.)

3DEC Version 4.1
283

1 - 20
APPLY

Command Reference

thermal

temp
Zone-Type Keyword

vsource

v
A heat-generating source, v, is applied as a volume
source of the specified strength (e.g., in W/m3 ) in
each zone in the specified range. When a new source
is applied to a zone with an existing source, the new
source strength replaces the existing source strength.
Decay of the heat source can be represented by a FISH
history using the history keyword. (See the flux keyword for an example.)

Face-Type Keywords

convection

v1 / v2
v1 is the temperature, Te , of the medium at which convection occurs.
v2 is the convective heat-transfer coefficient, h (e.g.,
in W/m2◦ C).
A convective boundary condition is applied over the
range of faces specified. The history keyword is not
active for convection.

flux

v
v is the initial flux (e.g., in W/m2 ).
A flux is applied over the range of faces specified. This
command is used to specify a constant flux into (v > 0)
or out of (v < 0) a thermal boundary of the grid. Decay
of the flux can be represented by a FISH history using
the optional keyword history. For example, the following FISH function performs an exponential decay
of the applied flux:
def decay
decay=exp(deconst*(thtime-thini))
end
set thini=0.0 deconst=-1.0
apply flux=10 hist=0decay

For dynamic analysis (see Section 2 in Optional Features), a time-varying history
multiplier may be applied to the numerical value of velocity with the hist keyword.
The history can be applied with any of the following types:

3DEC Version 4.1
284

COMMAND REFERENCE
APPLY
constant

1 - 21

constant

constant value

cosine

freq tvel
cosine wave velocity with frequency freq (cycles/sec), and applied
for a problem time period of tvel

fish

fishsym
The specified FISH symbol is used to provide a history multiplier.

impulse

freq tvel
impulse velocity with frequency freq (cycles/sec), and applied for a
problem time period of tvel (i.e., velocity = 0.5 × (1.0 − cos(2 ×
f req × t)))

linear

The velocity multiplier varies from 0 to 1 during the next CYCLE
command.

sine

freq tvel
cosine wave velocity with frequency freq (cycles/sec), and applied
for a problem time period of tvel

table

n
history given by the TABLE command. TABLE n consists of a list of
pairs: time, f(time). Linear interpolation is performed between the
given discrete points.

The APPLY command sets the block to FIXed — i.e., the components of velocity not
prescribed (including rotational components) remain unchanged. To remove APPLY,
use the FREE command.

3DEC Version 4.1
285

1 - 22
APPLY

3DEC Version 4.1
286

Command Reference

COMMAND REFERENCE
BOUNDARY

BOUNDARY

1 - 23

   
Boundary conditions are specified for an external boundary. The range over which
the boundary condition is applied can be limited by the range. Ranges are described
in Section 1.1.3.
Boundary conditions are defined by a given boundary condition keyword. The keywords are divided into ten boundary types. The keywords and associated parameters
are as follows:
1. Load Boundary

An optional point on the boundary at location x,y,z can be specified
to apply the load (for deformable blocks only).

xload

fx
x-direction load (see NOTE, below)

yload

fy
y-direction load (see NOTE, below)

zload

fz
z-direction load (see NOTE, below)

NOTE: All loads are assumed to be constant and permanent by default, and are
added to the existing permanent loads. Transient (time-varying) loading is applied
if a history keyword phrase (his, xhis, yhis or zhis) is given on the same command
line as the load or stress (see Histories for Loads and Velocities, below).
2. Traction Boundary

An optional triangular surface on the face of a deformable block,
defined by the three vertices at (x1,y1,z1), (x2,y2,z2), (x3,y3,z3), can
be specified to apply the traction (for deformable blocks only). The
three points of the triangle must be entered in counterclockwise order,
looking at the block-face from outside the block.

3DEC Version 4.1
287

1 - 24
BOUNDARY

Command Reference

xtraction
xtraction

tx
traction in x-direction on block face

ytraction

ty
traction in y-direction on block face

ztraction

tz
traction in z-direction on block face

3. Stress Boundary

stress

sxxo syyo szzo sxyo sxzo syzo
boundary stress parameters: xx-stress, yy-stress, zz-stress
xy-stress, xz-stress, yz-stress (see NOTE, below)
A range phrase must be specified for the BOUNDARY stress command
(see NOTE, below).

xgradient

sxxx syyx szzx sxyx sxzx syzx

ygradient

sxxy syyy szzy sxyy sxzy syzy

zgradient

sxxz syyz szzz sxyz sxzz syzz
linearly varying boundary stress, where sxxo, sxyo and syyo are
stresses at origin (0,0,0), defined by the stress keyword, and where:
sxx =sxxo + (sxxx∗x) + (sxxy∗y) + (sxxz∗z)
syy =syyo + (syyx∗x) + (syyy∗y) + (syyz∗z)
szz =sxxo + (szzx∗x) + (szzy∗y) + (szzz∗z)
sxy =sxyo + (sxyx∗x) + (sxyy∗y) + (sxyz∗z)
sxz =sxzo + (sxzx∗x) + (sxzy∗y) + (sxzz∗z)
syz =syzo + (syzx∗x) + (syzy∗y) + (syzz∗z)
The xgrad, ygrad and zgrad keywords must follow the STRESS command on the same input line. (Use “&” at the end of the line if a
continuation line is required.)
An x,y,z-coordinate region must be specified for the xgrad, ygrad and
zgrad boundary conditions (see NOTE, below).

3DEC Version 4.1
288

COMMAND REFERENCE
BOUNDARY
zgradient

1 - 25

example:
bound

-.1,.1 -1,1 -1,1

stress

-5,0,0,0,0,0 &

ygrad

5,0,0,0,0,0

&

This command applies a gradient to the xx-stress varying from −10
at y = −1 to zero at y = 1.
NOTE: All loads and stresses are assumed to be constant and permanent by default,
and are added to the existing permanent loads. Transient (time-varying) loading is
applied if a history keyword phrase (his, xhis, yhis or zhis) is given on the same
command line as the load or stress (see Histories for Loads and Velocities, below).
CAUTION: The stress boundary affects all degrees of freedom. For example,
if BOUND stress follows a BOUND xvel, BOUND yvel or BOUND zvel command
affecting the same velocities, then the effect of the previously prescribed xvel,
yvel or zvel will be lost. Be careful when using the stress, xgrad, ygrad and zgrad
keywords to apply stresses only to the outer boundary of the model. If no coordinate
region is given, stresses will be applied to boundaries of internal blocks as well as
outer blocks.
4. Velocity (Displacement) Boundary

nvel

0
The normal direction velocity for deformable blocks is set to zero. The
normal direction is defined as the normal to the block face. Velocity
boundary conditions will be removed if nvel = 0 is applied in the same
direction as the velocity condition. Two nvel = 0 conditions can be
applied at the same vertex. If these are applied, the condition reverts
to BOUND xvel = 0, BOUND yvel = 0, BOUND zvel = 0.

xvel

vx
x-direction velocity (for deformable blocks only)

yvel

vy
y-direction velocity (for deformable blocks only)

zvel

vz
z-direction velocity (for deformable blocks only)

3DEC Version 4.1
289

1 - 26
BOUNDARY

Command Reference

5. Free Boundary

xfree

removes boundary condition in the x-direction.

yfree

removes boundary condition in the y-direction.

zfree

removes boundary condition in the z-direction.

6. Non-reflecting (Viscous) Boundary (only available with dynamic option)
Viscous boundaries cannot be used together with a velocity boundary. Viscous
boundaries may be combined with stress boundaries. Non-reflecting boundaries
are available for dynamic analyses:

mat

n
material number n assigned to far-field properties (required for nonreflecting boundaries)

xvisc

non-reflecting boundary in x-direction

yvisc

non-reflecting boundary in y-direction

zvisc

non-reflecting boundary in z-direction

7. Reaction Boundary

reaction

Point loads are applied in the opposite direction to unbalanced forces
at all vertices within the range. The command CYCLE 1 should be
given before BOUND reaction so that unbalanced forces are calculated. Any velocity boundary conditions will be removed when this
command is applied.

8. Fluid Boundary
Specify the fluid boundary conditions. By default, all boundaries are impermeable.

disch

q
sets discharge boundary condition. Discharge is per unit length of a
joint trace on the boundary surface.

kndis

q
specifies a point source at flow knots within a specified range.

pgrad

fn
specifies boundary pore-pressure gradient; assumes that up is positive
y-axis.

3DEC Version 4.1
290

COMMAND REFERENCE
BOUNDARY
ppressure

ppressure

1 - 27

fn
specifies boundary pore pressure.

9. Fluid-Thermal Coupling
Specify thermal boundaries for fluid-flow calculation. This is only available with
the thermal option.

fluidtemp

q
sets fixed fluid-boundary temperature at flow knots in the range.

flux

q
sets heat-flux boundary conditions for convection on flow pipes in the
range.

knflux

sets point heat-source boundary conditions on flow knots in the range.

10. Histories for Loads and Velocities
The keywords his, xhis, yhis and zhis define a time history that is a multiplier for
all the load, traction, stress and x-, y- and z-velocities given on the same command
line.
NOTE: Loads assigned a history are considered transient loads, and are stored
independent of any permanent loads assigned to the same vertices. If a vertex
already has a transient load, any new load with the same history type is added to it;
however, a new transient load with a different history type replaces the old transient
load.
Boundary loads, tractions, stresses or velocities can be applied as constant, linear,
sinusoidal or impulse functions, or they may consist of a series of points given by
a TABLE command or read from a file. The keywords must be given on the line
specifying the load, traction, stress or velocity.

xhistory


x-direction history parameters

yhistory


y-direction history parameters

zhistory


z-direction history parameters

3DEC Version 4.1
291

1 - 28
BOUNDARY

Command Reference

history
history


x-, y- and z-direction history parameters
where types are:

constant

constant value

cosine

freq tload
cosine wave load with frequency freq (cycles/sec), and
applied for a problem time period of tload

fish

fishsym
The specified FISH symbol is used to provide a history
multiplier.

impulse

freq tload
impulse load with frequency freq (cycles/sec), and applied for a problem time period of tload
(i.e., velocity = 0.5 × (1.0 − cos(2 × f req × t)))

linear

The load multiplier varies from 0 to 1 during the next
CYCLE command. At the end of the CYCLE command,
the transient loads are added into the permanent loads.

sine

freq tload
sine wave load with frequency freq (cycles/sec), and
applied for a problem time period of tload

table

n
is the history given by the TABLE command. TABLE
n consists of a list of pairs: time, f(time). Linear interpolation is performed between the given discrete
points.

3DEC Version 4.1
292

COMMAND REFERENCE
CALL

CALL

1 - 29

 
begins processing of the data file fname. If fname is not specified, then it is set equal
to “3DEC.DAT.” If fname does not contain an extension, then the extension is set
equal to “.DAT.”
Any series of input instructions can be placed in a data file. This allows 3DEC to
run unattended in batch mode. Additional files may, in turn, be called from a data
file; there is no limit to the levels of call nesting. However, files must not call each
other recursively (e.g., file “ABC” calls file “DEF,” which then calls file “ABC”).
The RETURN command returns program control from batch mode to interactivecommand mode (if a single level of calling was used), or to the calling file at the next
line after the CALL command if multiple levels of calls have been nested. Pressing
the  key terminates input from data files and returns program control to
interactive mode, no matter to what level calls have been nested.
The PAUSE command may be inserted into a data file to allow the user to check
intermediate results; the CONTINUE command is used to continue processing of a
PAUSEd file.
If the optional keyword suppress is added, then the command processor will not
echo the contents of the file to the screen while it processes the file (and any files
called by it).

3DEC Version 4.1
293

1 - 30
CALL

3DEC Version 4.1
294

Command Reference

COMMAND REFERENCE
CAVE

CAVE

1 - 31

on/off 
The CAVE command is used to simulate the effects of material property changes in
rock due to crushing in a block caving operation. The command causes the assignment of a new material property and/or constitutive model based on the percentage
of failed zones in a block. The command can also zero the stresses in the zones and
contacts. Currently the command works only with fully deformable blocks assigned
with cons = 2 (Mohr-Coulomb). The keywords are:

newcon

i
the new constitutive model to assign when the percentage of failed
zones reaches the specified limit (valid values are 1 or 2; default is 1)

newmat

i
the new material type to assign when the percentage of failed zones
reaches the specified limit (default is 1)

percent

v
assigns the ratio of failed to total zones in a block required to trigger
the substitution (default is 1.0).

zero

off
on
This keyword, if set to on, instructs the code to zero stresses in zones
and contacts. Contact displacements are also zeroed. This is to simulate the destressing of the material due to crushing (default is off).

3DEC Version 4.1
295

1 - 32
CAVE

3DEC Version 4.1
296

Command Reference

COMMAND REFERENCE
CHANGE

CHANGE

1 - 33

keyword  
Block and joint material characteristics are prescribed and changed with the CHANGE
command. Material characteristics should be prescribed after all discontinuities are
created. The range over which the CHANGE command is applied can be limited by
the optional range phrase. Characteristics of blocks whose centroids lie within the
optional range are changed. The range phrases for blocks are listed in Table 1.2. If no
range is specified, all blocks in the model will have characteristics changed. The HIDE
command can also be used to hide blocks selectively, to keep their characteristics
from being changed (i.e., only visible blocks are changed).
Characteristics of joints (i.e., contacts between blocks) are changed in a way similar
to the way they are changed for blocks. Contacts whose coordinates lie within the
optional range are changed. If no range is specified, all contacts in the model will
have characteristics changed. The range affects joints between both visible and
hidden blocks.
The following keywords are used to change characteristics:
Block Characteristics

cons

n
Constitutive number n is assigned to designated deformable blocks
(see Table 1.3). (The default is n = 1.)

mat

n
Material property number n is assigned to designated rigid or deformable blocks. (All blocks initially default to mat = 1. The maximum value for n is 50.)

Joint Characteristics

jcons

n
Constitutive number n is assigned to designated contacts (see Table 1.4).

jmat

=n
Material property number n is assigned to designated contacts. (All
contacts initially default to jmat = 1. The maximum value for n is
50.)

3DEC Version 4.1
297

1 - 34
CHANGE

Command Reference

Cable Characteristics

cable

matg 
Material property number matg is assigned to designated cable nodes.
Material property number mats is assigned to designated cable elements. The midpoint of an element must lie within the range to be
changed. Note: Properties must be defined by the STRUCT prop command before cable nodes or elements can be assigned new property
numbers. Cable nodes are not normally assigned property numbers
until the first cycle command. Therefore, they will show property 0
in LIST cable.

Table 1.3 Constitutive models for deformable blocks
cons

Model Description

1

linearly elastic, isotropic (default)

2

elastic/plastic, Mohr-Coulomb failure*

3

anisotropic elastic

*WARNING: This model should be used with caution. Accurate solutions
to plasticity problems can only be achieved if all tetrahedral zones have a
gridpoint at the centroid of the block and are diagonally opposed tetrahedra in
the block, or if “mixed discretization” is used. 3DEC provides for improved
plasticity solutions with mixed discretization when the GEN quad command is
used for zone generation, or when SET nodal on is issued to use nodal mixed
discretization. Nodal mixed discretization improves plasticity when using the
default tetrahedral meshing. See “Mixed Discretization Procedure for Accurate
Solution of Plasticity Problems (J. Marti and P. A. Cundall), Int. J. Num. and
Analy. Methods in Geom., 6, 129-139 (1982).
All block constitutive models are described in Section 2 in Theory and
Background.

3DEC Version 4.1
298

COMMAND REFERENCE
CHANGE

1 - 35

Table 1.4 Joint constitutive models
jcons

Model Description

1

area contact elastic/plastic with Coulomb slip failure (units are
[stress/displacement] for contact stiffnesses and [stress] for cohesion
and tension). Failure of joint in shear or tension results in the use of
cohesion, tension and friction residual values. The default residual
values of cohesion and tension are 0. If a residual friction value is not
provided, the initial friction value is maintained.

2

is the same as jcons = 1, but cohesion is maintained following failure,
and the tensile value is reduced to the residual value. The default
residual value for tension is 0.

3

continuously yielding joint model (see Section 3 in Theory and Background for a detailed explanation)

7

elastic joint model, no slip or tensile failure is allowed

3DEC Version 4.1
299

1 - 36
CHANGE

3DEC Version 4.1
300

Command Reference

COMMAND REFERENCE
CONFIG

CONFIG

1 - 37

keyword 
This command allows the user to specify optional calculation modes. Some modes
need extra memory to be assigned to each zone or gridpoint. If any of these modes is
desired, CONFIG must be given before the POLY command. The following keywords
apply:

array

fmem
attempts to resize the amount of memory in 3DEC ’s main array to
fmem megabytyes. NOTE: This can be performed at any time, even
after model creation. However, it is possible that a critical error will
occur, forcing a shutdown of the code.

cppudm

allows extended zone constitutive models and user-defined models
(see Section 4 in Optional Features).

creep

allows creep constitutive models to be used (requires the cppudm
option — see Section 4 in Optional Features).

dynamic*

dynamic analysis (only available with dynamic option — see Section 2 in Optional Features)

feblock*

experimental linkage with finite element structures (only available
with structural option — see Section 3 in Optional Features)

gwflow*

fluid flow analysis; experimental fracture flow logic

highorder*

enables the use of high-order isoparametric zones.

lhs*

3DEC will now use a left-handed coordinate system.

liner

structural element tunnel liners (only available with structural option
— see Section 3 in Optional Features)

thermal*

thermal analysis (only available with thermal option — see Section 1
in Optional Features)

* These must be specified prior to creating any blocks.

3DEC Version 4.1
301

1 - 38

CONFIG

3DEC Version 4.1
302

Command Reference

COMMAND REFERENCE
CONTINUE

CONTINUE

1 - 39

This command allows the user to resume reading a data file. Reading of the data
file will pause if a PAUSE command is encountered. CONTINUE will then resume
reading the data file on the next line.

3DEC Version 4.1
303

1 - 40

CONTINUE

3DEC Version 4.1
304

Command Reference

COMMAND REFERENCE
COUPLE

COUPLE

1 - 41

on/off 
The COUPLE command allows the user to switch parts of the model on and off. This
provides for loose coupling between an inner and an outer region. The part of the
model to be switched on or off is specified by the region numbers. The command
LIST couple state gives the on/off state of the model regions. In the default stressuncoupling mode, a list of forces containing the effect of the off and on regions is
created. The list can be printed via the LIST couple forces command. The contact
stresses are still calculated during the uncoupled stage, under the assumption that
the inner region is elastic. However, they are not applied to the blocks. This is only
done after re-coupling, so that these forces are used to reestablish the continuity of
the model. The joints between the on and previously off regions remain elastic even
after coupling. The couple logic applies only to deformable blocks. If an on block is
joined to an off block, the gridpoints laying on the interface will remain fixed. The
keywords are:

mode

stress
displacement
When stress mode is selected, the forces exerted by the inactive regions on the active regions are held constant. When displacement
mode is selected, the joints between the active and inactive regions
are assumed to be elastic (no slip or separation). The inactive regions
remain fixed, so the active regions are tied to them by this elastic
interface.

noreset

A RESET damping command is issued every time a REGION on or
REGION off command is given, unless noreset is also given.

region

n1,
specifies which regions to turn on or off.

3DEC Version 4.1
305

1 - 42
COUPLE

3DEC Version 4.1
306

Command Reference

COMMAND REFERENCE
CYCLE

CYCLE

1 - 43

n
executes n timesteps. (CYCLE 0 is permitted as a check on data.) If the  key
is pressed during execution, 3DEC will return control to the user after the current
cycle is complete. (Also see the STEP and SOLVE commands.)

3DEC Version 4.1
307

1 - 44
CYCLE

3DEC Version 4.1
308

Command Reference

COMMAND REFERENCE
DAMPING

DAMPING

1 - 45

keyword
selects damping types for static and dynamic analyses. The following keywords
apply:

auto


Viscous damping is specified for the blocks. For static or steady-state
problems, the objective is to absorb vibrational energy as rapidly as
possible. In this case, the first form of the command (auto keyword)
should be used; this causes energy to be absorbed in proportion to the
rate of change of kinetic energy. The optional parameter fac is the
ratio of damping dissipation to kinetic energy change. If fac is not
given, the default value of 0.5 is used. In most cases, this gives a fast
convergence. The multipliers mult1 and mult2 adjust the damping
coefficient by a fractional amount as the ratio changes. The default
values of 0.99 for mult1 and 1.05 for mult2 are optimum in most
cases. Auto damping is the default for static analysis.

combined


combined damping (the damping value is 0.8 by default)

contact

mat 1, mat 2, Betaffn, Betaffs, Betavvn, Betavvs, Betaven, Betaves,
Betavfn, Betavfs, Betaeen, Betaees, Betaefn, Betaefs
allows setting of different stiffness damping factors, depending on
the material numbers and contact types. mat 1 and mat 2 refer to the
material numbers of the blocks in contact. The Beta factors are the
normal and shear stiffness damping factors to be used for the different
contact types. This method of setting the stiffness damping factors
gives greater control for block bounce simulations.
The general equation for the stiffness damping force is:
f = −β × K × aγ
where f = damping force;
β = damping factor;
K = stiffness;
a = area of contact; and
γ = change in velocity.

3DEC Version 4.1
309

1 - 46
DAMPING

Command Reference
fcrit freq

fcrit freq

 
This form of the command is normally used for dynamic calculations
when a certain fraction of critical damping is required over a given
frequency range. This type of damping is known as Rayleigh damping, where fcrit = the fraction of critical damping operating at the
center frequency of freq. (NOTE: Input frequencies for the program
are in cycles/sec, not radians/sec.) The optional modifiers stiffness
and mass denote that the damping is to be restricted to stiffness or
mass-proportional, respectively. If they are omitted, normal Rayleigh
damping is used. (NOTE: By specifying stiffness-damping, the critical timestep for numerical stability will automatically be reduced. It
is still possible for instability to result if large deformation occurs.
In such a case, lower the timestep with the FRACTION command.)
Damping considerations for dynamic analysis are discussed further
in Section 2 in Optional Features.

local


local damping (the damping value is 0.8 by default)

NOTE: Mass scaling (see the command MSCALE) is performed automatically when
the command DAMP auto or DAMP local is issued. Mass scaling is turned off when
the command DAMP 0,0 is invoked. Mass scaling may only be turned off if the
dynamic option is active.

3DEC Version 4.1
310

COMMAND REFERENCE
DEBUG

DEBUG

1 - 47

fish
executes the FISH function fish in debug mode. See Section 2.6 in the FISH volume
for further details. fish may or may not be prefixed with an @ symbol, even in safe
mode.

3DEC Version 4.1
311

1 - 48
DEBUG

3DEC Version 4.1
312

Command Reference

COMMAND REFERENCE
DEFINE

1 - 49

DEFINE

function-name

END

DEFINE and END are commands used to define a function written in FISH, the embedded language built into 3DEC. All statements between the DEFINE and END
commands are compiled and stored in compact form for later execution. Compilation errors are reported as the statements are processed. These “source” statements
are not retained by 3DEC; hence, FISH functions normally should be prepared as
data files that can be corrected and modified if errors are found.
FISH is a useful means by which to create new variables to print or plot, to control
conditions during 3DEC execution, to create special distributions of properties, or to
analyze 3DEC output in some special way. Section 2 in the FISH volume describes
the operation and use of FISH in detail.

3DEC Version 4.1
313

1 - 50
DEFINE

3DEC Version 4.1
314

Command Reference

COMMAND REFERENCE
DELETE

DELETE

1 - 51


All blocks with centroids in the optional range are deleted. If no range is specified,
all blocks are deleted. NOTE: Only visible blocks are deleted. Deleted blocks
cannot be plotted or backfilled (FILL). If the voids will eventually be filled, use the
EXCAVATE command. If they will not be backfilled but you may want to plot these
blocks, use the REMOVE command.

3DEC Version 4.1
315

1 - 52
DELETE

3DEC Version 4.1
316

Command Reference

COMMAND REFERENCE
DUMP

DUMP

1 - 53

n m 
dumps m words of memory from the main array to the screen, starting from address
n. Internal pointers mfree, junk, ibpnt, icpnt and ibdpnt are also printed. mfree gives
the lowest memory location that is currently free. See Section 4 in the FISH volume
for a description of the data structure and definitions of pointers and offsets.
Using the keyword offset causes the addresses to be displayed as offsets from n.
This is a diagnostic tool and does not affect the running of any models.

3DEC Version 4.1
317

1 - 54
DUMP

3DEC Version 4.1
318

Command Reference

COMMAND REFERENCE
EXCAVATE

EXCAVATE

1 - 55


All blocks within the range are excavated. Excavated blocks are assigned a null
constitutive model for calculation purposes. The blocks can be replaced later with the
FILL command. EXCAVATE can only be used with deformable blocks; use DELETE for
rigid blocks. Deformable blocks can also be removed with the REMOVE command.
(Blocks which are removed cannot be replaced later with the FILL command.)
Excavated and/or removed blocks can be seen with the PLOT excavate command.

3DEC Version 4.1
319

1 - 56
EXCAVATE

3DEC Version 4.1
320

Command Reference

COMMAND REFERENCE

1 - 57

EXIT
EXIT

This is a synonym for the QUIT command.

3DEC Version 4.1
321

1 - 58

EXIT

3DEC Version 4.1
322

Command Reference

COMMAND REFERENCE

1 - 59

FFIELD
FFIELD

 
A dynamic free field is created. This dynamic free field consists of a one-dimensional
finite-difference calculation, executed in parallel with the main calculation, and provides the lateral boundary conditions for dynamic analysis in which a vertically
propagating plane wave is applied to the base of the model.
The model requirements of the free field are:
deformable blocks
rectangular base
vertical side boundaries parallel to the x-and z-axes (y-axis assumed
to be vertical)
top surface may be irregular (thus different FF heights)
The six free field blocks consist of four side FF meshes corresponding to the four
model sides and four corner FF meshes that act as an FF boundary to the side FF
meshes. The blocks in the FF mesh are standard deformable blocks. The joint
structure in the FF mesh is the same as in the model side boundaries. Therefore,
joint traces on the model sides are assumed to extend horizontally into the FF mesh.
By default, all blocks in an FF mesh are joined when the FF blocks are created, but the
user may unjoin them afterwards. The zoning of FF blocks is similar to the zoning
of model side faces. The side FF blocks have a thickness of two gridpoints across,
linked to move together. The corner FF meshes have four gridpoints at each level,
also linked to move together.
Prior to creating the dynamic free field, the mode must be in static equilibrium.
Th standard procedure for using the free field logic is:
Run the main model to static equilibrium.
FFIELD apply
Set dynamic boundary conditions at the base of model and FF (and
possibly at the top, for deep underground models).
Run dynamic analysis.
In some cases, it may be necessary for the user to change the initial state of the FF
meshes (for example, to unjoin some blocks, change properties or loads, etc.). These
things may be done as follows:
Run the main model to static equilibrium.
FFIELD apply
FFIELD link off

3DEC Version 4.1
323

1 - 60

Command Reference

FFIELD
Make any changes in FF.
Set static boundary conditions at the FF base.
Run to static equilibrium.
FFIELD link on
Set dynamic boundary conditions at the base of model and FF (and
possibly at the top, for deep underground models).
Run dynamic analysis.
The keywords for the FFIELD command are:

apply


creates the zoned FF blocks. The material and constitutive numbers
are set to those in model side blocks. The blocks in each FF mesh
are joined. The FF mesh stresses are obtained from the model side
zones. Balancing forces are applied to FF gridpoints to maintain static
equilibrium. No boundary conditions are applied to the FF gridpoints.
On all of the model side gridpoints, the following occur:
FF conditions are applied (removing any fixed velocity
condition)
FF stresses are applied
balancing forces to maintain static equilibrium are applied
Optional FFIELD apply keywords are:

gap

viewing gap between FF and main model (default =
5% of model length)

thickness

thickness of FF blocks (default = 5% of model length)

tol

tolerance to find gridpoints on model boundaries to
apply FF conditions (default = ATOL)

x1, x2, z1, z2 location of 4 model boundaries (default = min. and
max. x- and z-coordinates)

delete

This deletes all free field meshes.

link off

This disconnects free field from main model.

link on

This reconnects free field to main model.

3DEC Version 4.1
324

COMMAND REFERENCE
FILL

FILL

1 - 61

 
All excavated blocks within the range are filled (i.e., restored for calculation purposes).
The blocks and joints within the filled range can be assigned material characteristics
with the following optional keywords:

cons

n
Constitutive number n is assigned to filled blocks.

jcons

n
Constitutive number n is assigned to contacts between blocks in the
filled region.

jmat

n
Material number n is assigned to contacts between blocks in the filled
region.

mat

n
Material property number n is assigned to filled blocks.

1 is the default value for both the material and constitutive numbers if the keyword
is not specified. The interface between a filled region and the surrounding blocks or
another filled region is assigned material number 1 by default. This can be changed
by using the CHANGE command after the FILL command.
The EXCAVATE and FILL commands must be used with caution. EXCAVATE retains
all of the initial excavated block’s geometry in memory. The FILL command simply
replaces the original block with the newly defined material parameters. If the excavation shape has changed significantly since the block was excavated, overlapping
of the original block and its neighbors may occur, resulting in numerical instability.

3DEC Version 4.1
325

1 - 62
FILL

3DEC Version 4.1
326

Command Reference

COMMAND REFERENCE
FIND

FIND

1 - 63

 
All hidden blocks with centroids within the range are restored (i.e., made visible).
Only visible blocks may be deleted by the DELETE command. Only visible blocks
may have their material or constitutive numbers changed by the CHANGE command,
and region numbers assigned or changed by the MARK command. Only visible blocks
are made deformable with the GEN command. Only visible blocks can be joined by
the command JOIN. Only visible blocks can be cut with the JSET command.
The range types are described in Section 1.1.3. If no range is specified, all hidden
blocks are made visible. If the optional keyword ffield is given, then only blocks in
the free-field boundary are hidden.

3DEC Version 4.1
327

1 - 64
FIND

3DEC Version 4.1
328

Command Reference

COMMAND REFERENCE
FIX

FIX

1 - 65


All blocks with centroids in the range specified have current velocities fixed. If no
range is specified, all visible blocks are fixed. Both rigid and deformable blocks can
be fixed. Joined blocks must be unjoined (by using JOIN off) before fixing. Refer
to the APPLY command to specify a velocity (other than the current value) for rigid
blocks; refer to BOUND nvel, BOUND xvel, BOUND yvel or BOUND zvel to specify
velocities for deformable blocks. (Use the command LIST vel to make sure that
blocks are fixed; code = 1 if fixed, 0 if freed.)

3DEC Version 4.1
329

1 - 66
FIX

3DEC Version 4.1
330

Command Reference

COMMAND REFERENCE
FLUID

FLUID

1 - 67


There is an experimental fracture fluid-flow logic built into 3DEC. The flow geometry consists of flow planes along the faces of blocks. There are flow pipes at the
intersections of the flow planes along the edges of the faces. There are flow knots at
the intersections of flow pipes (corners of blocks). Fluid flow occurs in joints only;
there is no matrix flow calculation. The normal sequence to define the fluid flow
geometry of the model is:
CONFIG GW
GEN ...
FLUID BULK v DENSITY v VISC v
SET FLOW ON
CYCLE

The command CONFIG gw must be given before any blocks are created. The PROP
command can be used to define azero, ares and amax, which control the hydraulic
aperture. The INSITU command may be used to define initial pore pressures in the
model. The BOUNDARY command may be used to set fluid boundary conditions for
the model.
The SET command can be used to turn on/off fluid flow calculation (flow); turn
on/off mechanical calculations (mech); control the interlace of mechanical and fluid
calculations (nmech and ngw); turn fastflow on/off; set unbalanced volume controls
(aunb, munb); and set a limit to unbalanced forces (fobu).
The LIST command can be used to print information on the flow planes (fplane) and
the fluid flow knots (knot).
Currently you can plot the flow plane structure, discharge vectors and contours of
pore pressure and aperture.
The keywords are:

bulk

v
defines the bulk modulus of the fluid.

density

v
defines the density of the fluid.

fhide


hides fluid-flow planes.

fht coe

v
specifies fluid heat-transfer coefficient.

3DEC Version 4.1
331

1 - 68
FLUID

Command Reference

fseek
fseek


restores fluid-flow planes.

fspec heat

v
specifies fluid-specific heat.

fth cond

v
specifies fluid-thermal conductivity.

transmax

v
defines the maximum flow-knot transmissivity. This is used to avoid
the calculation of extremely small timesteps.

visc

v
defines the viscosity of the fluid.

volmin

v
defines the minimum flow-knot volume. This is used to avoid extremely small timesteps based on areas of small aperture.

Also see the BOUNDARY, INSITU, LIST, PROP and SET commands.

3DEC Version 4.1
332

COMMAND REFERENCE
FRACTION

FRACTION

1 - 69

fb 
fb is taken as the fraction of critical timestep to be used for block timestep (default fb
= 0.1). fz is the fraction of critical timestep to be used for zone timestep (default fz
= 1.0). The timestep used in cycling is the smaller of the zone and block timesteps.

3DEC Version 4.1
333

1 - 70
FRACTION

3DEC Version 4.1
334

Command Reference

COMMAND REFERENCE
FREE

FREE

1 - 71


All blocks with centroids in the range specified by the range are set free. If no range
is specified, all visible blocks are freed. By default, all blocks are free initially. (Use
the command LIST vel to check whether blocks are freed; code = 1 if fixed, 0 if freed.)

3DEC Version 4.1
335

1 - 72
FREE

3DEC Version 4.1
336

Command Reference

COMMAND REFERENCE
GENERATE

GENERATE

1 - 73

keyword value  
All blocks with centroids lying within the range are made deformable. If no range is
specified, all visible blocks are made deformable. For a deformable-block analysis,
all blocks in a model must be made deformable. Once the zone size for a block
has been specified, subsequent GEN commands for the same block are ignored. The
generation of tetrahedral zones is performed after all blocks are made deformable.
(This restriction is necessary to match all gridpoints between neighboring blocks.) In
previous versions, all zoning had to be performed in a single pass to ensure matching
face gridpoints. This restriction has been removed. If a block fails zone generation
in the first try, attempts to rezone that block with different parameters are allowable.
The generation routine will check surrounding blocks to ensure that face gridpoints
match.
The  key can be used to interrupt zone generation; the block currently being
zoned will be made rigid again.
The following keywords are used to specify mesh zoning conditions:

center

x y z ecenter ec distance d edistance ed
A radially graded mesh is generated. The mesh size varies from an
edge length of ec at center point x, y, z in the model, to an edge length
of ed at a distance d from the center point. If ecenter is inside a block,
a uniform mesh with edge length ec will be generated.

edge

ed 
The parameter ed defines the average edge length of tetrahedral zones.
The alternate keyword may be used for blocks that do not zone properly using the normal schemes (see below). In this case, the block
is meshed independent of adjacent blocks, and gridpoint matching is
performed post-zoning. In general, this scheme leads to more-poorly
shaped zones and should be used as a last resort.
Retrying zone generation with either a longer or shorter length can
be done safely. Retrying zone generation with a different edge length
often produces good results. For flat or narrow blocks, sometimes a
shorter length is better. For large blocks, the edge length may have
to be increased.

3DEC Version 4.1
337

1 - 74
GENERATE

Command Reference

hotetra
hotetra

This keyword causes the constant strain elements to be converted to
degenerate isoparametric brick elements (4 sides rather than 6). An
extra gridpoint is added to the center of each zone edge. The command
may be used only after the blocks have already been zoned using the
normal GEN commands. The high-order zones cannot be JOINed to
lower-order zones. The CONFIG highorder command must be given
before any blocks are created.
The plasticity solution for the high-order zones is more accurate than
for the normal constant-strain tetrahedral zones. Under certain conditions the solution may not be as accurate as for mixed discretization
zones (GEN quad). However, the high-order logic does not have the
same shape restrictions as do the mixed discretization zones.
Stresses in the high-order zones may be projected to the gridpoints
(see LIST grid stress). Note: The high-order elements are incompatible with the free-field boundary and with the zone models (DLL).

new

Use a new Delaunay meshing algorithm. Currently this does not work
with double precision.

old

uses the old meshing algorithm. This is used to maintain consistency
with previous versions, and is the default setting.

quad

ndivide i1 i2 i3
generates a grid of “quad” zones in cubic, six-sided polyhedra. (Each
quad zone consists of 2 sets of five overlapping tetrahedral zones.)
This is referred to as mixed discretization, and greatly improves the
solution when plastic deformations occur. The keyword ndiv controls the way discretization is done. i1, i2 and i3 are the numbers
of zones generated along three local directions: i1 is the number of
zones along the direction of the shortest edge length; i2 is the number
of zones along the intermediate edge length; and i3 is the number of
zones along the longest edge length. The maximum number of subdivisions in each axis is 50. Note: This technique works only with
regular six-sided polyhedra, and it is used to make the zone overlays
geometrically compatible.

3DEC Version 4.1
338

COMMAND REFERENCE
GENERATE

1 - 75

E
E
E!

Figure 1.1

Relations between block edge lengths and the input parameters
i1, i2 and i3

Optional keywords are provided to assist with automatic zone generation:

alternate

This invokes a different zoning scheme where the gridpoints on the
surface of a block are not forced to match the gridpoints of neighboring blocks. This keyword is to be used only if changing the edge
lengths of zones fails to succeed in zoning a block. The gridpoints of
the neighboring blocks are adjusted to match after the gridpoints are
created.

check

checks whether face gridpoints match.

fix

xyz
The keyword fix is optional and is used to define the location of a
single gridpoint (vertex) at position x, y, z. This command is helpful
when a boundary condition is to be applied at a specific location
(either internal or external). Multiple fix keywords may be used to fix
several vertices.

gpmatch

performs gridpoint matching for previously zoned blocks.

nomatch

turns off the gridpoint matching between blocks. This may result in
nonuniform stress distributions. This may also affect stresses in zones
near the edges of joined blocks.

tolerance

v1,v2
changes the tolerance values used in the zoning process (default values
are v1= 10−6 , v2= 10−4 ).

3DEC Version 4.1
339

1 - 76
GENERATE

3DEC Version 4.1
340

Command Reference

COMMAND REFERENCE
GRAVITY

GRAVITY

1 - 77

gx gy gz
Gravitational accelerations are set for the x-, y- and z-directions.

3DEC Version 4.1
341

1 - 78
GRAVITY

3DEC Version 4.1
342

Command Reference

COMMAND REFERENCE
HEADING

HEADING

1 - 79

string
This is a synonym for the TITLE command.

3DEC Version 4.1
343

1 - 80
HEADING

3DEC Version 4.1
344

Command Reference

COMMAND REFERENCE
HELP

HELP

1 - 81

The HELP command provides a screen listing of the available 3DEC commands.
HELP may also be typed as a keyword to a command. For example, LIST help will
list all available keywords for the LIST command. A “?” may be used in place of the
HELP command or keyword.

3DEC Version 4.1
345

1 - 82
HELP

3DEC Version 4.1
346

Command Reference

COMMAND REFERENCE
HIDE

HIDE

1 - 83

 
All blocks with centroids in the range defined by range are made invisible; they are
put on a stack and can be recalled later with the FIND command. When blocks are
invisible, they are not split by the JSET command; in this way, discontinuous joints
may be made. However, the invisible blocks interact normally with other blocks,
and are remembered on restart. In general, invisible blocks are unaffected by the
commands CHANGE, DELETE, FIX, FREE, GEN, JOINT, JSET and MARK.
If no range is specified, all blocks are hidden. If the optional keyword ffield is given,
then only blocks in the free-field boundary are hidden.

3DEC Version 4.1
347

1 - 84
HIDE

3DEC Version 4.1
348

Command Reference

COMMAND REFERENCE
HISTORY

HISTORY

1 - 85

  keyword. . .
The values of a set of variables can be sampled and stored during a model run
by using the HISTORY command. These variables can then be plotted versus step
number or versus other histories (with the PLOT history command). Histories can
also be written to a file (with the write keyword). Only one variable may be given
per HISTORY command. History variables may be added at any time. The contents
of all histories can be erased with the purge keyword, and all histories can be deleted
with the delete keyword. A summary of all histories is printed by the LIST history
command.
Each history is given a unique ID number, based upon the order in which the HISTORY
commands are issued. However, a specific ID number can be assigned with the
id keyword. All histories are sampled at a single sampling interval. By default,
the sampling interval for the history mechanism is every 10 steps. The sampling
interval can be changed with the nstep keyword (or with the SET hist rep command).
Different nstep values cannot be assigned for different history variables.
In addition to the keywords listed below, a FISH symbol name can be given as a
keyword, in which case the value of that variable will be sampled and stored — see
Section 2.4.1 in the FISH volume. The keywords are grouped into two categories:
built-in history variables and history-logic support.
Built-in History Variables
All new history declarations may be preceded by the add keyword (for clarity); they
may also be preceded by an optional id = id statement. This assigns an ID number
to the history instead of allowing 3DEC to assign one itself. ID numbers must be
unique. Histories based on location will find only blocks that are currently visible.
The closest object to the specified position will be selected for the history.
Zone Histories

s1

xyz

s2

xyz

s3

xyz
principal stress components of zone

ssmax

xyz
maximum shear stress in zone

sxx

xyz

syy

xyz

szz

xyz

3DEC Version 4.1
349

1 - 86
HISTORY

Command Reference

sxy
sxy

xyz

sxz

xyz

syz

xyz
stress components of zone

Contact Histories
In addition to contact location, you may also select a particular orientation with the dip and dd keywords.

ar sum

x y z  
sum of areas for all sub-contacts associated with the contact area x y z
the area of the contact nf sum x y z
sum of normal forces for all sub-contacts associated with the contact sf sum x y z
sum of shear forces for all sub-contacts associated with the contact sdisplacement x y z
ndisplacement x y z
shear and normal contact displacements sforce x y z
nforce x y z
shear and normal contact force stress x y z
nstress x y z
shear and normal contact stress xsdisplacement x y z
ysdisplacement x y z
3DEC Version 4.1 350 COMMAND REFERENCE HISTORY zsdisplacement 1 - 87 zsdisplacement x y z
one component of the contact shear displacement vector xsstress x y z
ysstress x y z
zsstress x y z
one component of contact shear force Global Histories address iadd defines a history of a real variable with offset iadd and index ioff. Addresses for various blocks, contacts, etc. can be obtained with the LIST command. See Section 4 in the FISH volume for offsets. (The default value for ioff is 0.) crtime creep time damping adaptive global damping parameter (see Section 1.2.3.2 in Theory and Background) mtime mechanical time (synonym for time) thtime thermal time time mechanical time unbalanced maximum out-of-balance force Fluid Knot Histories fluid pp xyz pore pressure fluid temp xyz temperature Vertex Histories xvelocity xyz yvelocity xyz zvelocity xyz one component of vertex velocity 3DEC Version 4.1 351 1 - 88 HISTORY Command Reference velocity velocity xyz velocity magnitude xdisplacement x y z ydisplacement x y z zdisplacement x y z one component of vertex displacement displacement x y z displacement magnitude temperature xyz vertex temperature xacceleration x y z yacceleration x y z zacceleration x y z one component of vertex acceleration (only available with CONFIG dynamic) acceleration xyz acceleration magnitude (only available with CONFIG dynamic) History-Logic Support delete All history traces are deleted. (This keyword is a synonym for the reset keyword.) dump id1 The values of histories id1 to idn versus the step number are written to the screen. The information can be limited to a specified range of steps by using the following keywords: begin nb Values with a step number greater than or equal to nb will be output. 3DEC Version 4.1 352 COMMAND REFERENCE HISTORY dump end end 1 - 89 ne Values with a step number less than or equal to ne will be output. skip ns Only one set of values for every ns sampled intervals will be output. For example, skip 10 means that every 10th recorded set of values (starting with the first) will be output. vs id0 The values of the histories id1 to idn versus history id0 (rather than versus step number) are written to the screen. For example, hist dump 1 3 7 vs 2 begin 150 end 375 outputs the values of histories 1, 3 and 7 versus the value of history 2. Only those values corresponding to step numbers in the range 150 to 375 are output. If id0 is negative, then the value of HISTORY id0 is reversed (multiplied by −1) and used. Alternatively, the keyword step (the default) or -step may be used to indicate that the step number (or negative step number) should be used. The destination for the dump keyword is, by default, the console. By using one of these keywords, the user can send the history output to a different destination. file filename The history information is sent to a text file. If no extension is specified, “.HIS” is used. table tab tab can be either a table ID number or a string containing a table name. The contents of the history are added to the contents of table tab. Note that only one history at a time may be output to a table. hist rep n This is a synonym for ncycle. 3DEC Version 4.1 353 1 - 90 HISTORY Command Reference label label id hname assigns a label hname to history ID id. During plotting, this name will appear instead of the default name. If you wish to use the original name again, assign an empty string (“ ”). limits The limits (min/max step numbers and min/max values) of all history traces are written to the screen. list