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 that must be followed when entering commands is described in Section 1.1.
PLOT commands, which are only available when using the Itasca-provided graphical user interface,
are described in Section 1 in the Plot Command Reference.
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 . . . <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 (at a minimum) to be typed in
order 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 5.0

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 are specified, on is implied.
If the exclamation point (!) is the first character on the input line, the character is removed and
the line processed as usual, except the command will be tagged as expecting an error. When an
error occurs, the error message will be reported, but 3DEC will not stop processing commands.
If an error message does not occur while processing the line, then an error will be reported and
processing will stop.
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:

3DEC Version 5.0

COMMAND REFERENCE

Table 1.1

1-3

Interactive input editing keys

Key

Effect

any character key

inserts character on input line

<>

moves cursor left on input line

<>

moves cursor right on input line

<Ctrl >

cursor jumps to next input parameter to the left

<Ctrl >

cursor jumps to next input parameter to the right

<Backspace>

deletes character to left of cursor

<Delete>

deletes character at cursor location

<End>

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

<Home>

moves cursor to beginning of input line

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.

3DEC Version 5.0

1-4

Command Reference

Table 1.2 Commands accepting

the range phrase
APPLY
BOUNDARY
CHANGE
DELETE
DENSIFY
EXCAVATE
FFIELD
FILL
FIND
FIX
FREE
GENERATE
GROUP
HIDE
INITIALIZE
INSITU
JMODEL
JOIN
JOIN CONTACT
LIST
MARK
PFIX
PLOT
REMOVE
SEEK
SHOW
STRUCTURE
ZONE
A range identifies a set of objects, and comprises 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. When the keyword extent is used, the extent of the object (rather than the object centroid)
is used to verify whether the object is within the range. This keyword is only applied to geometric
range elements (e.g., spheres).

3DEC Version 5.0

COMMAND REFERENCE

1-5

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 sh 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 5.0

1-6

Command Reference

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 <iu>
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
indices.

block

i1 <, i2, . . . in>

block index. Any number of indices may be specified.

bmaterial

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

contact

i1 <, i2, . . . in>

contact index. Any number of contact indices may be specified.

cylinder

end1 x1 y1 z1 end2 x2 y2 z2 radius r <r2>

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

3DEC Version 5.0

selects blocks that are deformable.

COMMAND REFERENCE

dfn

1-7

sname keyword
selects objects based on their distances from fractures in the DFN
with name sname. One can specify additional DFNs with the optional
<name sname2>, <name sname3>, etc. keywords. If no additional
keywords are given, then objects with 0 distance (e.g., whose positions
fall on a fracture surface or, if the optional extent keyword is given,
whose extent intersects or contains a fracture) are selected. This
distance is modified by the distance keyword. One can also use the
aperture keyword to use the fracture apertures as the distance criteria
on a per fracture basis.

aperture

bstate
If bstate is true, defines a range within the distance
of each fracture aperture to fractures in the defined
DFN with name sname. If bstate is false, the distance,
supplied with the distance keyword, is used.

distance

fdist
defines a range within the distance fdist to fractures in
the defined DFN with name sname.

name

sname2
adds an additional DFN with name sname2. If adding
one or more DFNs, use name sname2, name sname3,
etc.

displacement dl <du> <tolerance t>

selects vertices with displacements in the interval (dl,du). (If du is
not specified, then the interval is set equal to (dlt,dl+t); if neither
vu nor t is specified, t is set equal to dl 106 . 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).

feface

il <iu>
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.

3DEC Version 5.0

1-8

Command Reference

feid

i1 <, i2, . . . in>

finite element ID number. Any number of finite element IDs may be
specified.

sh

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

geometry

sname keyword
selects objects associated with the geometry set with name sname.
Either the distance f dist or count i keyword is required. The optional
keywords are <set sname2>, <set sname3>, etc. If the keyword
count i is used, the optional keyword to define a ray direction is
<direction x y z>. The following keywords are available:

count

i <direction x y z>
odd <direction x y z>
defines a range with the intersection number of a ray
in the direction of (x, y, z) with the polygons (edges
and points are not considered) in the geometry sets. If
the direction is not explicitly defined, the default one
is vertical upward (0.0, 0.0, 1.0). count i defines the
intersection number of a ray with the defined direction
with the geometry sets. If odd is specified instead
of an integer, then all odd numbers of intersections
are considered in the element. This can be used to
determine objects inside a geometry set that forms a
closed volume.

3DEC Version 5.0

COMMAND REFERENCE

1-9

distance

f dist
defines a range within a distance of f dist to the defined geometry set with the name sname. The defined
geometry set may include points, edges and polygons,
and the distance is defined to the closest distance to
any of these points, edges or polygons.

set sname2

group

adds an additional geometry set named sname2. If

adding one or more geometry sets, use set sname2,
set sname3, etc. For example, range geometry name1
set name2 set name3 count 2 direction (1.0 0.0 0.0) will
define a range that any ray with a direction of (0.0, 0.0,
1.0) from this range will have 2 intersections with the
geometry sets of name1, name2 and name3.

sname keyword
selects objects associated with the group sname. See the GROUP
command for details about how an object is associated with a group.

or

sname
adds an additional group name to the list of those considered to be part of this range element. Any number
of group names may be added in this way.

slot

any
specifies which group slot on the object will be
searched. The default value of any indicates that all
valid slots will be checked for a match. Only one slot
is associated with all groups in a range element.

id

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

jmaterial

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

3DEC Version 5.0

1 - 10

Command Reference

joint

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

name

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 objects
normal vector and the vector specified must be within the default or
specified tolerance.

dd

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

dip

dip <tolerance diptol>

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

dipdirection

dd <tolerance ddtol>
This is a synonym for dd.

3DEC Version 5.0

COMMAND REFERENCE

1 - 11

normal

nx, ny, nz <tolerance normtol>

specifies the normal direction required. normtol specifies the tolerance in degrees. The tolerance in this
case is the angle between the objects normal vector
and this normal vector. (The default value for normtol
is 2 degrees.)

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

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

3DEC Version 5.0

1 - 12

Command Reference

set

keyword
selects objects based on their parent set containers. This keyword
only applies to fractures in DFNs currently. Parent set containers are
added with the id or name keyword. For instance, if one wishes to
delete all fractures in a DFN with name fred, one can build the range
range set name fred and use this range with the DFN delete command.

id

id
The parent set container with ID id is added to the
range.

name

sname
The parent set container with name sname is added to
the range.

sphere

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

sregion

<ireg1 . . . >
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 are selected by the
element. Vertices are selected if they are part of a face selected by
the element.

velocity

vl<vu> <tolerance t>

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

vertex

i1 <, i2, . . . in>

vertex index. Any number of vertex indices may be specified.

vid

il <iu>
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
are selected. Contacts are selected if either of the two blocks they
connect is selected.

3DEC Version 5.0

COMMAND REFERENCE

volume

1 - 13

vl <vu> <tolerance t>

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

xl <xu> <tolerance t>

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

yl <yu> <tolerance t>

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

zl <zu> <tolerance t>

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 106 . 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.
;

3DEC Version 5.0

1 - 14

Command Reference

; 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

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 sh safe conversion.) See Section 2.4.2 in the FISH volume for more details.
1.1.5 Online Help
The 3DEC Help menu provides, for ease of reference, the complete User Interface Guide, Command Reference volume, FISH in 3DEC volume, Plug-ins Guide and Verification Problems
and Example Applications volume from the 3DEC Manual, in compiled HTML (.CHM) 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 ?

Note that the ? command does more than just list keywords: It lists all entities (keywords, numbers,
strings, etc.) in alphabetical order.
Additional help can be obtained by using the built-in file editor. Pressing <F1> will bring up the
help file related to the command on the current text line.

3DEC Version 5.0

COMMAND REFERENCE

1 - 15

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.

<Esc>

interrupts program execution at any time during cycling, block creation or zone
generation. When the <Esc> 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 5.0

1 - 16

Command Reference

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
POLYHEDRON 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)

gwow

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 POLYHEDRON 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 or JOIN CONTACT
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 5.0

COMMAND REFERENCE

1 - 17

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\3dec500\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 5.0

1 - 18

Command Reference

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 3 in Theory and Background). Use the CAVE command to simulate material property change due
to caving.

3DEC Version 5.0

COMMAND REFERENCE

1 - 19

(3) Specify Structural Support

Four types of artificial passive support may be specified via the STRUCTURE
command:
(a) STRUCTURE beam, which generates structural elements attached to
zone gridpoints;
(b) STRUCTURE 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) STRUCTURE axial, which generates local reinforcement elements
across joints for modeling fully bonded passive reinforcement in
hard rocks; and
(d) STRUCTURE 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 5.0

1 - 20

Command Reference

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.

TRACE

records the positions of model objects over time.

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

MAIL

allows the user to send email notifications during a model run.

PLOT

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

HISTORY of a variable.

SET

log

3DEC Version 5.0

COMMAND REFERENCE

1 - 21

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.

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.2.16 Access Built-in Help

HELP or ?

provides a listing of available commands.

1.3 3DEC Commands Detailed Listing

The detailed listing of all 3DEC commands (in alphabetical order) follows.

3DEC Version 5.0

1 - 22

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
APPLY

APPLY

1 - 23

keyword value <hist type. . . > <range . . . >

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.,
ux), 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 ux keyword for an
example.)

3DEC Version 5.0

1 - 24
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 ux 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.

ux

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 5.0

COMMAND REFERENCE
APPLY
cosine

cosine

1 - 25

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

constant

constant value

sh

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 5.0

1 - 26
APPLY

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
BOUNDARY

BOUNDARY

1 - 27

<keyword> <value. . . > <hist keyword> <range>

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 eleven boundary types. The keywords and associated
parameters are as follows:
1. Load Boundary
<point x y z>
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 (history, xhistory, yhistory or zhistory) is given on the
same command line as the load or stress (see Histories for Loads and Velocities,
below).
2. Traction Boundary
<triangle x1 y1 z1 x2 y2 z2 x3 y3 z3>
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 5.0

1 - 28
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

principal

s1,s2,s3 s1 dip,s1 dd s2 dip s2 dd <keyword>

Alternate method to define stress at a boundary by specifying a stress
measurement at a point and an optional gradient.

s1

major principal stress

s2

intermediate principal stress

s3

minor principal stress

s1 dip

major principal stress dip

s1 dd

major principal stress direction

s2 dip

intermediate principal stress dip

s2 dd

intermediate principal stress direction

The following are optional keywords:

zgradient

value
gradient in the z-direction (vertical)

location

xs,ys,zs
The location specifies the coordinates of the stress
measurement. The gradient is the stress change in the
vertical direction. All other stresses are incremented
proportionately by the gradient to prevent stress rotation.

3DEC Version 5.0

COMMAND REFERENCE
BOUNDARY
stress

stress

1 - 29

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 + (sxxxx) + (sxxyy) + (sxxzz)
syy =syyo + (syyxx) + (syyyy) + (syyzz)
szz =sxxo + (szzxx) + (szzyy) + (szzzz)
sxy =sxyo + (sxyxx) + (sxyyy) + (sxyzz)
sxz =sxzo + (sxzxx) + (sxzyy) + (sxzzz)
syz =syzo + (syzxx) + (syzyy) + (syzzz)
The xgradient, ygradient and zgradient 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 xgradient, ygradient and zgradient boundary conditions (see NOTE, below).
example:
bound

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

stress

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

&

3DEC Version 5.0

1 - 30
BOUNDARY

Command Reference

zgradient

ygrad
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 (history, xhistory, yhistory or zhistory) 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
BOUNDARY stress follows a BOUNDARY xvel, BOUNDARY yvel or BOUNDARY 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, xgradient, ygradient
and zgradient 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 BOUNDARY xvel = 0, BOUNDARY yvel = 0, BOUNDARY zvel = 0.

verbose

increases messages to screen.

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 5.0

COMMAND REFERENCE
BOUNDARY

1 - 31

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. Nonreflecting (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. Nonreflecting boundaries are
available for dynamic analyses:

mat

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

xvisc

nonreflecting boundary in x-direction

yvisc

nonreflecting boundary in y-direction

zvisc

nonreflecting 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 BOUNDARY 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
z-axis.

3DEC Version 5.0

1 - 32
BOUNDARY

Command Reference

ppressure
ppressure

fn
specifies boundary pore pressure.

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

uidtemp

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

ux

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. Dynamic Mass

added mass keyword

This boundary command is used to add additional dynamic masses
to gridpoints on the face of blocks to simulate the effects of an adjacent mass of water. This procedure was established by Westergaard
(1933).
The following keywords are available:

density

value
density of the water

depth

average depth of water in the reservoir (constant added

mass). Not used if water surface is specified.

g dir

x,y,z
gravitational vector (if different from static gravity definition)

proj

n
The full solution involves a 3 3 matrix for each
gridpoint. In 3DEC, the matrix is diagonalized. By
default, each row is added into the diagonal. The proj
keyword (proj = 1) provides a better solution by calculating the diagonal based on the surface normal.

3DEC Version 5.0

COMMAND REFERENCE
BOUNDARY
added mass region depth

1 - 33

region depth region to apply added mass based on depth below surface

remove

remove any previously defined added masses

surface

x,y,z
water surface location if depth is to be calculated

xmass

add mass in the x-direction only

ymass

add mass in the y-direction only

zmass

add mass in the z-direction only

11. Histories for Loads and Velocities

The keywords history, xhistory, yhistory and zhistory 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

<type>
x-direction history parameters

yhistory

<type>
y-direction history parameters

zhistory

<type>
z-direction history parameters

3DEC Version 5.0

1 - 34
BOUNDARY

Command Reference

history
history

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

cosine

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

constant

constant value

sh

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 5.0

COMMAND REFERENCE
CALL

CALL

1 - 35

lename <line ival> <label slab> <suppress> call . . .

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 <Esc> 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).
If the line keyword is specified, then the data file starts reading at the line ival. If the
line is past the end of the file, the file returns instantly, as if you had processed to the
end of the file.
If the label keyword is specified, then the data file starts reading at the label slab. To
place a label in a data file, use the syntax :label (where the colon must be the first
character in the line). The data file will be read starting with the first line after the
label. Lines containing a label are ignored (as if the colon were a comment). If the
label is not found in the data file, an error is indicated.
Any number of file names may now be given on the same line, indicating that the
call files will start nested. For example,
call mary.dat line 30

call george.dat label fred

will first push mary.dat onto the input stack, followed by george.dat. Input will
start being processed from george.dat, starting at label fred. When george.dat
is done being processed, input will continue from mary.dat starting from line 30.

3DEC Version 5.0

1 - 36
CALL

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
CAVE

CAVE

1 - 37

on/off <keyword. . . >

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 5.0

1 - 38
CAVE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
CHANGE

CHANGE

1 - 39

keyword <keyword> <range . . . >

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

dfn

id <jmat ni no> <jcons mi mo>

changes the properties of the joints that constitute dfn id. Material
property number ni is assigned to sub-contacts inside the DFN fractures (i.e., lying on a fracture). Property no is assigned to sub-contacts
on a block face that was cut by the fracture that lie outside of the actual fracture. If blocks have not been zoned, no is assigned to the
contact. Similarly, constitutive numbers mi and mo are assigned to
sub-contacts inside and outside of the fractures, respectively.

jcons

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

3DEC Version 5.0

1 - 40
CHANGE

Command Reference

jmat
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.)

Cable Characteristics

cable

matg <mats>
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 STRUCTURE property 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

linearly elastic, isotropic (default)

elastic/plastic, Mohr-Coulomb failure*

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 GENERATE 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 1 in Constitutive Models.

3DEC Version 5.0

COMMAND REFERENCE
CHANGE

1 - 41

Table 1.4 Joint constitutive models

jcons

Model Description

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.

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.

continuously yielding joint model (see Section 2 in Constitutive Models

for a detailed explanation)

elastic joint model, no slip or tensile failure is allowed

3DEC Version 5.0

1 - 42
CHANGE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
CONFIG

CONFIG

1 - 43

keyword <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 POLYHEDRON command. The following
keywords apply:

array

fmem
attempts to resize the amount of memory in 3DEC s main array to
fmem megabytes. 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. The default is 1000 megabytes.

cppudm

allows extended zone constitutive models and user-defined models

(see Section 3 in Constitutive Models).

creep

allows creep constitutive models to be used. Also sets DAMPING

combined as default damping mode.

dynamic*

dynamic analysis (only available with dynamic option see Section 2

in Optional Features)

energy*

allows energy components to be accumulated.

feblock*

experimental linkage with finite element structures (only available

with structural option see Section 3 in Optional Features)

uid*

fluid flow analysis; fracture flow logic. Sub-contact locations are not
updated when CONFIG uid is used. Small-strain mode is set when
CONFIG uid is used.

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 5.0

1 - 44

CONFIG

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
CONTINUE

CONTINUE

1 - 45

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 5.0

1 - 46

CONTINUE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
COUPLE

COUPLE

1 - 47

on/off <keyword. . . >

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 damp command is issued every time the region on or region

off keyword is given, unless noreset is also given.

region

n1,<n2 . . . nn>
specifies which regions to turn on or off.

3DEC Version 5.0

1 - 48
COUPLE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
CYCLE

CYCLE

1 - 49

n<keyword>
executes n timesteps. (CYCLE 0 is permitted as a check on data.) If the <Esc> 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.)

continue

resumes a previous CYCLE or SOLVE command that was interrupted

by an <Esc>.

3DEC Version 5.0

1 - 50
CYCLE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
DAMPING

DAMPING

1 - 51

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

auto

<fac mult1 mult2>

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

<value>
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 different stiffness damping factors to be set, 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 5.0

1 - 52
DAMPING

Command Reference
fcrit freq

fcrit freq

<stiffness> <mass>
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

<value>
local damping (the damping value is 0.8 by default)

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

3DEC Version 5.0

COMMAND REFERENCE
DEFINE

1 - 53

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 5.0

1 - 54
DEFINE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
DELETE

DELETE

1 - 55

<range . . . >
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 5.0

1 - 56
DELETE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
DENSIFY

DENSIFY

1 - 57

<keyword><range . . . >
Subdivide blocks to increase density of blocking over the input range. Blocks are
subdivided by cutting joints parallel to the global x, y, z axes. The following keywords apply:

gradlimit

Blocks chosen for densification will be checked to attempt to ensure

that adjacent blocks differ by, at most, one level of densification.
This may mean more blocks will be densified than actually fall into
the range.

id

n
specifies joint IDs for faces and joints created with this command.

join

joins blocks across the joints created with the DENSIFY command.

maxlength

l1 <l2 l3>
This specifies the maximum edge lengths to be densified, in order. If
l2 and l3 are not specified, they will be set to the same number as l1.

nsegment

n1 <n2 n3>
This specifies the number of subdivisions in the x-, y- and z-directions. If n2 and n3 are not specified, they will be set to the same
number as n1.

repeat

<n>
repeats the densification n times, causing a recursive application of
the range and densification settings. This can, for example, be used
to create an octree grid. Note that if no number is given, then 3DEC
will repeat until the maxlength length is reached, applying the division
specified in nsegment each time.

3DEC Version 5.0

1 - 58
DENSIFY

3DEC Version 5.0

Command Reference

COMMAND REFERENCE

1 - 59

DFN
DFN

keyword
operates on discrete fracture networks (DFNs). A DFN is a collection of planar,
convex polygons and/or disks. Each element in a DFN is termed a fracture. Fractures
hold lists of properties, and can also hold extra variables and belong to groups. The
properties may be of any type, and are assigned as needed. DFNs, as sets of fractures,
can be generated via DFN templates that are sets of statistical parameters describing
the distribution of fractures. Intersections between fractures can be calculated and
queried for fracture connectivity analyses. NOTE: All DFN fractures must be created
inside the model domain, as specified by the DOMAIN command.
NOTE: Both fracture properties and extra variables are converted to floating point
numbers or integers when imported from a property file, though they are exported in
their actual format. Thus one may save/restore general properties or extra variables
of fractures in a save file, but may not import these values from a property file
appropriately. An Itasca DFN data file format is specified in Section 1.5.12, along
with a property file format to assign properties to the fractures.

addfracture

keyword . . .
adds a deterministic fracture to the DFN specified by the id or name
keyword. If the DFN does not exist, a new DFN is created. If name
is not given, then the name is set to dfnn, where n is the DFN ID.
If the id keyword is not given, the ID is set to the next available ID.
This command attempts to create a fracture as a disk. A domain must
be specified prior to fracture addition. This command contrasts with
the DFN generate command that generates fractures based on a DFN
template (i.e., a stochastic description of a DFN).

dfndominance i
If a new DFN is created, its dominance is set to i, where
i > 1. This keyword has no effect on a 3DEC model.

dip

dv
dip angle (degrees) of the fracture, measured in the
negative z-direction from the global xy-plane. dv must
fall within the range [0;90] (default dv = 0).

dipdir

ddv
dip direction (degrees) of the fracture, measured in the
global xy-plane clockwise from the positive y-axis.
ddv must fall within the range [0;360] (default ddv =
0).

dominance

specifies the fracture dominance. This keyword has

no effect on a 3DEC model.

3DEC Version 5.0

1 - 60

DFN

Command Reference

addfracture

fracid
fracid

i
assigns the ID i to the fracture unless a fracture with
this ID exists. By default, the next available ID is
assigned to the fracture.

id

i
Add the fracture into the DFN with this ID. If the DFN
does not exist, then one is created. Cannot be given
with the name keyword.

interset

iset
Fracture intersections with the newly created fracture
are calculated and added to the intersection set iset.

name

s
Add the fracture into the DFN with this name. If the
DFN does not exist, then one is created. Cannot be
given with the id keyword.

nothrow

This is an optional keyword indicating that the command will return a warning instead of an error if the
fracture addition fails. The requirement of the fracture position falling within the model domain is not
enforced when this keyword is given.

position

px py pz
position of the fracture center. The point (px,py,pz)
must fall within the model domain (default (0,0,0))
unless the nothrow keyword is specified.

size

sv
size of the fracture (i.e., the disk diameter). sv must
be positive (default sv = 1).

aperture

keyword <range . . . >

assigns aperture to fractures. Fractures can be filtered out by DFN or
by fractures using the set range element. Apertures can be used for
connectivity distance calculations (with the DFN connectivity command), and with the DFN range element for distance filtering. Apertures currently have no effect on a 3DEC model.

3DEC Version 5.0

COMMAND REFERENCE
DFN
aperture
constant

constant

1 - 61

v
assigns a constant value v to fracture apertures. v must
be strictly positive.

sh

name p1 . . . pn
assigns aperture using a user-defined FISH function.
The function name is given by name, and function
arguments are given by p1 . . . pn. This function must
return a float value.

gauss

m, sd
draws apertures from a Gaussian distribution with
mean m and standard deviation sd.

limit

vl vu
sets the min and max value of apertures. The condition
is 0<vl<vu. If not defined, default values are vl = 0
and vu = +.

lognormal

m, sd
draws apertures from a lognormal distribution with
mean m and standard deviation sd.

powerlaw

exp
draws apertures from a negative power-law distribution with exponent exp.

uniform
attribute

draws aperture within a uniform distribution within the

given limits

keyword
sets the value of a fracture attribute. This command is a synonym for
the DFN initialize command. Note that modification of the fracture
geometry will fail if the fracture would not fall entirely within the
model domain. Fracture attributes are characteristics of fractures
such as position or size. These are distinct from fracture properties
(assigned with the DFN property command). The DFN properties
have no effect on a 3DEC model.

aperture

fap
fracture aperture where fap 0

3DEC Version 5.0

1 - 62

DFN

Command Reference

attribute

area
area

farea
fracture area where farea > 0

diameter

fdia
diameter of disk fractures with fdia > 0

dip

fdip
dip angle in degrees where 0 fdip 90. The dip is
the angle from the dip direction projected on the xyplane to the fracture surface measured in the negative
z-direction.

dipd

fdipdir
dip directions in degrees, as measured in a clockwise
fashion from the positive y-axis where 0 fdipdir
360.

dominance

i
changes the fracture dominance (i.e., the priority order
of fractures). It is not currently used in 3DEC.

position

fpos
the fracture position vector. This corresponds to the
center of the fracture.

xposition

<replace, add, multiply> v <gradient gx,gy,gz>

position (x-component)

yposition

<replace, add, multiply> v <gradient gx,gy,gz>

position (y-component)

zposition

<replace, add, multiply> v <gradient gx,gy,gz>

position (z-component)

3DEC Version 5.0

COMMAND REFERENCE

DFN

1 - 63

cluster
cluster

keyword
computes clusters and assigns corresponding groups. Clusters are
defined as sets of fractures connected via intersections. These fracture
sets are indexed and group names are assigned based on the indices.
Intersections are created via the DFN intersection command. If either
no intersection set is specified or the specified intersection set does not
exist, a new intersection set is created and all intersections between
fractures are delineated; the resulting intersection set is used as the
basis for the cluster calculation.

groupslot

slot
assigns group names in slot islot. The group name is
based on the intersection set name. The group name is
set to cnameXX, where cname is the intersection
set name and XX is the cluster index. By default
islot = 1.

interset

keyword
specifies the intersection set used for cluster calculation. An intersection set name or ID must be specified.

id

i
The intersection set with ID i is used for cluster calculations. The keyword cannot be
given with the name keyword.

name

sname
The intersection set with name sname is used
for cluster calculations. The keyword cannot
be given with the id keyword.

combine

keyword
Simplification method for DFNs. Fractures are sorted by decreasing size and, starting with the largest fracture (termed the reference
fracture), the algorithm determines smaller fractures in which the
following 2 criteria are met:
The difference between the reference fracture and fracture orientations is smaller than a given angle (provided by the angle keyword).
The distance between fractures (as determined by the distance between the fracture centers and the reference fracture plane) is less
than a specified distance ( provided by the distance keyword).

3DEC Version 5.0

1 - 64

DFN

Command Reference

combine
When these criteria are met, the smaller fractures are rotated to have
the same orientation as the reference fracture, and their centers are
translated onto the reference fracture plane. The algorithm continues
by switching the reference fracture to the next largest fracture that
has not been previously rotated. If the merge keyword is given, the
fractures that are coplanar are merged. If a fracture falls completely
within a larger fracture, it is removed; otherwise, the surface of the
largest fracture is increased so that it is equal to the sum of the surface
of the two merged fractures.
Note: Using the merge keyword can significantly change the fracture
density. Use this keyword with caution.

angle

d
specifies the angle criterion for proximity detection
with d 0.

collapse

collapses rotated fractures onto the reference fracture

plane. Fractures are not merged.

distance

d
specifies the distance criterion for fracture proximity
identification with d 0.

merge

connectivity

merges fractures that would overlap the reference fractures if they were collapsed onto the reference fracture
plane. If a fracture falls completely within a larger
fracture, it is removed.

keyword
calculates the connectivity of the network from a starting structure
(fracture or geometry). By default, integer connectivity levels are
computed for each fracture (i.e., the fracture is connected to the structure through n fracture intersections) and extras are assigned based on
the distance (e.g., 0 for a directly connected fracture). This behavior
can be modified with the aperture, cubic and distance keywords. If
either no intersection set is specified or the specified intersection set
does not exist, a new intersection set is created and all intersections
between fractures are delineated; the resulting intersection set is used
as the basis for the connectivity calculation.

aperture

3DEC Version 5.0

Connectivity is assigned to the extra variable in the slot

specified with the extra keyword. Connectivity is the
distance (as defined in the description of the distance
keyword) divided by the fracture aperture.

COMMAND REFERENCE
DFN
connectivity cubic

1 - 65

cubic

Connectivity is assigned to the extra variable in the slot

specified with the extra keyword. Connectivity is the
distance (as defined in the description of the distance
keyword) divided by the cube of the fracture aperture
(i.e., similar to the transmissivity).

distance

Connectivity is assigned to the extra variable in the

slot specified with the extra keyword. Connectivity is
given as the physical distance from the structure to the
fracture calculated as the path through the centers of
intersections.

extra

iindex
The connectivity is calculated, and this keyword specifies the extra index for assignment. The extra slot 1
is used if this keyword is not specified.

fracture

i
The starting structure is set to the fracture with ID i.
This keyword cannot be specified with the geometry
keyword.

geometry

set
The starting structure is set to the geometry set with
name set. This keyword cannot be specified with the
fracture keyword.

interset

keyword
specifies the intersection set used for connectivity calculation.

id

i
The intersection set with ID i is used for cluster calculation. This keyword cannot be given
with the name keyword.

name

sname
The intersection set with name sname is used
for cluster calculation. This keyword cannot
be given with the id keyword.

3DEC Version 5.0

1 - 66

DFN

Command Reference

copy
copy

fromID toID <range. . . >

Copy fractures in the specified range from fracture network with ID
fromID to the fracture network with ID toID. If the fracture network with ID toID does not exist, then a new fracture network is
created with name copy of dfn id where id = fromID. If the name
copy of dfn id is currently assigned to a fracture network, then
integers are appended to the name until a unique name is found.

delete

<range. . . >
deletes whole DFNs or fractures within a DFN. Empty DFNs are
automatically deleted. Use the set range element to delete entire
DFNs.

export

<range. . . > keyword . . .

exports the DFN in the format specified below. If no keyword is given,
then the Itasca DFN data file format will be used (see Section 1.5.12)
and the .dat extension is added to the file name if an extension is
absent. FishLab and FracMan formats are also supported. In addition,
the associated DFN template (if unique) can be exported in a DFN
template file, and fracture properties in a property file. These files
can be imported with the DFN import command.

lename

file
gives the name of the file to be exported. If no extension is provided, then the appropriate extension is
added.

shlab

outputs only the disk-shaped fractures in FishLab format. The .flab file extension is added to the file name
if one is absent.

fracman

outputs the disk-shaped fractures in ASCII FracMan

format. The .fab file extension is added to the file
name if one is absent.

intersect

<keyword>
This keyword specifies that a 2D set of fractures is to be
output corresponding with the intersection of a plane
(specified with the orientation and origin keywords).
No area intersections are delineated. Note that the
resulting 2D DFN cannot be displayed in 3DEC, but
must be opened in a 2D Itasca program. Note also
that the output intersections are centered at the location specified with the origin keyword, and that the

3DEC Version 5.0

COMMAND REFERENCE
DFN
export
intersect

1 - 67

x-coordinates of the intersections are in the direction

of strike of the plane, and the y-coordinates of the intersections are in the down-dip direction of the plane.

orientation

fdip fdipd

orientation of a plane to intersect with the

fractures for 2D output

origin

forx fory forz

origin of the plane to intersect with the fractures for 2D output

itasca

outputs the disk-shaped fractures in Itasca DFN data

file format.

propertyle

propfile
name of the property file to be output corresponding
with the DFN. If no property file is specified, the property number is set uniformly to 1. The property file
format is specified in Section 1.5.12.

template

file
Name of the template file to be output corresponding
with the DFN. The .idt file extension is appended
to the file name if one is absent. Available only if
the exported fractures/DFNs are linked to one single
DFN template. The template file format is specified
in Section 1.5.12.

extra

index v <range. . . >

assigns the value v to the extra variable at that index for all fractures
falling within the specified range. Use the set range element to filter
fractures by DFN.

generate

keyword . . .
generates a set of fractures from a statistical description. A domain
must be specified prior to generation, the spatial range must fall within
the domain, and only disk-shaped fractures can be generated (with
the exception of truncated disks, as discussed below). The generation
uses a DFN template that must be previously defined, and the generated DFN is linked to this template, provided that the modify keyword
is not given. If no template is provided, the default template (if created) is used. For further details, see the template keyword. Fractures

3DEC Version 5.0

1 - 68

DFN

Command Reference

generate
are generated until a specified stopping criterion is met. These conditions include: a target fracture number (nfrac); a target P10 (p10);
a target density (P32) (density); a target percolation volume (P33)
(percolation); DFN at the connectivity threshold (threshold); and a
user-defined criteria (stopsh). In addition, a user-defined function
can be called after the generation of each fracture to modify the current fracture, to skip it or to add/calculate specific properties. Fracture
characteristics can then be modified with the DFN attribute command,
and properties assigned with the DFN property command. Note: The
specified DFN must not already exist.

density

val
The generation will stop when the fracture density
(P32) in the tolbox reaches val.

dfndominance

i
This applies when the DFN is being created. In this
case, the dominance of the DFN is set to i. The DFN
dominance has no effect on 3DEC models.

genbox

xl xu yl yu zl zu
generates fractures with positions within this rectangular generation region. By default, the generation
box is set to the domain extent.

id

Generated fractures are added to the DFN with ID id.

The specified DFN must either be empty or not exist.
If the name keyword is not specified and the DFN does
not exist, then a DFN is created with name is dfnXX
where XX is id.

modify

s p1 . . . pn
defines a FISH function that is called after the generation of each single fracture. s is the name of the
function. This function must have at least one argument, an fr prt pointing to the last generated fractures. Additional arguments can be specified with p1
. . . pn . The FISH function can be used to access and/or
change the fracture parameters. If the function returns
the string remove, the fracture is removed from the
generation process. Note that using a modification
function prevents from linking the generated DFN to
the underlying template.

3DEC Version 5.0

COMMAND REFERENCE
DFN
generate
name

name

1 - 69

s
generates fractures in the DFN with this name. The
specified DFN must either be empty or not exist.

nfrac

i
The generation will stop when the number of fractures
in the tolbox is i.

p10

val bx by bz ex ey ez
The generation will stop when P10 measured along the
scanline starting from point (bx,by,bz) and ending at
point (ex,ey,ez) reaches val.

p10geom

val name
The generation will stop when the average P10 measured along the set of scanlines defined by the geometric object name. Each edge in the geometry set is
assumed to be a scanline, and the average P10 of all
scanlines is used to test for termination.

percolation

val
The generation will stop when the fracture percolation
volume (P33) in the tolbox reaches val.

stopsh

s p1 . . . pn
defines a FISH function used to stop the generation.
The FISH function name is s, and p1 . . . pn (any number) are the function arguments. This function must be
previously defined, and returns an integer. If its value
is larger than 0, the generation stops.

template

keyword
Fractures are generated according to the specified template. If no template is provided, the template named
default is used. If it does not exist or if the given name
or ID are not valid, an error is indicated.

id

itid
DFN template with ID itid is used as the statistical description for generation. It cannot
be given with the name keyword.

3DEC Version 5.0

1 - 70

DFN

Command Reference

generate

template

name
name

stname
DFN template with name stname is used as
the statistical description for generation.
It cannot be given with the id keyword.

threshold

keyword
Generation terminates at the connectivity threshold
(i.e., the instant one can traverse all dimensions of a
spatial region via fracture intersections).

box

fxl fxu fyl fyu fzl fzu

Generation terminates the instant one can traverse fracture intersections from each edge of
the specified box to each other edge.

geometry

sgname1 <sgname2>

Generation terminates when the DFN is connected to all polygons of the geometry set
sgname1. If sgname2 is given, generation
terminates when the DFN connects at least
one polygon of the geometry set sgname1 to
at least one polygon of the geometry set sgname2.

tolbox

xl xu yl yu zl zu
A tolerance used to truncate fractures that may either
be larger or smaller than the generation box. The tolerance box must fall within the model domain. This box
is used for density or percolation calculation if these
are the stopping criteria. Should a tolerance box not
be provided, then the generation box (or the domain,
if the generation bow is larger) is used.

gimport

<range. . . of polygons> keyword . . .

imports a set of fractures from a geometry set and adds it to the DFN
specified by the id or name keyword. This geometry set is filtered
by the specified range. If the DFN does not exist, then a new DFN
is created. If name is not given, then the name is set to dfnn where
n is the DFN ID. If the id keyword is not given, then the ID is set to
the next available ID. This command attempts to import fractures as
both planar polygons and disks. Planar polygon importation scans
the geometry polygon data structure. Disk importation occurs by
scanning all geometry points and investigating the extra variables.

3DEC Version 5.0

COMMAND REFERENCE
DFN
gimport

1 - 71

Should 3 extra variables that are doubles exist in extra slots 1, 2

and 3, then the point is deemed to represent a disk where the extra
variables are the radius, dip (in degrees) and dip direction (in degrees),
respectively. A domain must be specified prior to importation, and all
fractures must fall completely within the domain unless the nothrow
keyword is given.

center

The DFN will be centered, wherein the average location of the fracture centers is aligned with the origin.
This location is taken for all joints prior to modification
(e.g., truncation or omission). Note: The centering of
fractures coming from polygonal geometry objects is
currently independent of the centering of disk-shaped
fractures.

clean

deletes the geometry set after importation.

dfndominance

i
The dominance of the DFN is set to i. The DFN dominance has no effect on 3DEC models.

dominance

random, ordered
specifies the mode to set the fracture dominance. The
dominance has no effect on 3DEC models.

geometry

s
imports fractures from the geometry set with name s.

id

i
imports fractures into the DFN with this ID. If id is not
specified, then the next available ID is used.

intersect

<keyword>
While importing, all intersections between fractures
are delineated when this keyword is specified. If the
iname keyword is not given, then the intersection set
name is intersectionsXX, where XX is the intersection
set ID.

iid

iid
The ID of the intersection set is set to iid.

3DEC Version 5.0

1 - 72

DFN

Command Reference

gimport

intersect

iname
iname siname
The name of the intersection set is set to
siname.

model

s
has no effect on 3DEC models.

name

s
imports fractures into the DFN with this name.

group

nothrow

indicates that the import will continue in spite of fractures lying outside the model domain. The offending
fractures will not be imported.

truncate

indicates that the fractures that intersect the domain

boundary will be truncated, leaving polygonal fractures that fall within the model domain. Fractures that
do not intersect the model domain are ignored.

gname keyword <range . . . >

specifies that the fractures are part of the group gname. By default,
the group slot with index 1 is assigned the value gname. Use the set
range element to assign group names to all fractures in a DFN.

add

assigns gname to the next available group slot.

slot

i
sets the group slot with index i to gname.

import

keyword . . .
imports a set of fractures from a file and adds it to the DFN specified
by the id or name keyword. If the DFN does not exist, then a new
DFN is created. If name is not given, then the name is set to dfnn,
where n is the DFN ID. If the id keyword is not given, then the ID
is set to the next available ID. A domain must be specified prior to
importation, and all fractures must fall completely within the domain
unless the nothrow keyword is given. In addition to the geometry,
the DFN can be associated with a DFN template described in a DFN
template file, fracture properties can be described by a property file,
and a contact model can be specified.
See the format keyword for further details about supported file formats. A model domain must be specified prior to importation, and
all fractures must fall entirely within the model domain unless the

3DEC Version 5.0

COMMAND REFERENCE
DFN
import

1 - 73

nothrow keyword is given. Also, the main characteristics of the DFN

(e.g., center, spatial extent, etc.) can be investigated prior to loading
with the DFN information command.

center

The DFN will be centered, wherein the average location of the joint centers is aligned with the origin.
This location is taken for all joints prior to modification
(e.g., truncation or omission).

dfndominance

i
The dominance of the DFN is set to i. The DFN dominance has no effect on 3DEC models.

dominance

random, ordered
The fracture dominance has no effect on 3DEC models.

lename

file
Name of file to be imported. See the format keyword
for further details of supported file formats.

format

s
imports from the file format specified by this keyword. Three formats are acceptable: itasca, fishlab
and fracman. The itasca format is as specified in Section 1.5.12. The fishlab format is the flowplane format used in FishLab. The fracman format follows the
ASCII FracMan output format. Should no format be
specified, then the file extensions are used to determine the file format. A .dat file is assumed to be in the
itasca format, a .flab file is assumed to be in the fishlab
format, and a .fab file is assumed to be in the fracman
format.

id

i
imports fractures into the DFN with this ID. If id is not
specified, then the next available ID is used.

3DEC Version 5.0

1 - 74

DFN

Command Reference

import

intersect
intersect

<keyword>
While importing, all intersections between fractures
are delineated when this keyword is specified. The
intersection set ID and name can be specified with the
iid and iname keywords. If the iid is not given, then
the intersection set ID is the next available ID. If the
iname keyword is not given, then the intersection set
name is intersectionsXX where XX is the intersection
set ID.

iid

iid
The ID of the intersection set is iid.

iname siname
The name of the intersection set is siname.

makedisk

i
Fractures with at least i vertices are made into disks
with radii equal to the average distance from the centroid to the vertices and dip, as specified.

makeplanar

With this keyword, planarity is forced for all fractures

that are not disks. The fracture normal is as defined
in the data file, and the origin of the fracture plane is
set to the average position of the vertices. The vertices
are adjusted so that they fall on the plane.

model

s
This keyword has no effect on 3DEC models.

name

s
imports fractures into the DFN with this name.

nothrow

indicates that the import will continue in spite of fractures lying outside the model domain. The offending
fractures will not be imported.

offset

foffset
applies a translation of foffset to all fracture positions.

3DEC Version 5.0

COMMAND REFERENCE
DFN
import
propertyle

propertyle

1 - 75

file
indicates that the properties of fractures are set via
a property file. This is not currently used in 3DEC.
See Section 1.5.12 for a definition of the property file
format.

template

file
indicates that the provided DFN has been generated
according to the DFN template defined in the file file.
The template file format is specified in Section 1.5.12.

truncate

information

indicates that the fractures that intersect the domain

boundary will be truncated, leaving polygonal fractures that fall within the model domain. Fractures that
do not intersect the model domain are ignored.

keyword <range . . . >

gets DFN information. One can query various density measures of
fractures filtered by range, as well as investigate the characteristics
of DFNs not yet in memory. In fact, when given a DFN file, it is
recommended that one uses the DFN information command with the
lename keyword to check the validity/characteristics of the fractures
represented in that file. For instance, error information, the number
of fractures, the spatial range of the fractures and the center can all
be assessed prior to importation. This tool can be very useful when
identifying invalid fractures, as well as the appropriate offset/scaling
to be used with the imported fractures.

avetrace

sgeomname
returns the average trace length, where traces are the
intersections between the DFN and the planar geometry set with name sgeomname.

box

lx ux ly uy lz uz
restricts the density measurement to the given box. It is
effective only with the density, dcenter and percolation
keywords.

dcenter

returns the DFN center density, or P30.

density

returns the DFN mass density, or P32.

3DEC Version 5.0

1 - 76

DFN

Command Reference

information

lename
lename

sfilename
prints information regarding the DFN represented by
the file with name sfilename. See the format keyword
for further details about supported file formats. This
keyword can only be provided with the plename keyword. The range is not used in this case. The following
information is output:
error information while reading the DFN file;
the number of fractures in the file;
the minimum/maximum spatial range of the fractures;
the minimum/average/maximum area of the fractures
in 2D (3D), respectively; and
the DFN center.

format

sformat
specifies the file format. It is used only with the lename keyword. The following formats are acceptable:
itasca, fishlab and fracman. The itasca format is as
specified in Section 1.5.11 and is the default format.
See the DFN import command for further details.

p10

keyword
returns the P10 along the line defined by p10begin and
p10end, or along the geometry edges defined by geometry.

geometry

sgeomname

P10 is measured along the edge of the geometry set with name sgeomname.

p10begin

sbx sby sbz (z-components, 3D only)

defines the starting point of the reference line

where P10 is measured.

p10end sex sey sez (z-components, 3D only)

defines the end point of the reference line
where P10 is measured.

3DEC Version 5.0

COMMAND REFERENCE
DFN
information p20

p20

1 - 77

sgeomname
returns the trace center density, where traces are the intersections between the DFN and the planar geometry
set with name sgeomname.

p21

sgeomname
returns the trace mass density, where traces are the intersections between the DFN and the planar geometry
set with name sgeomname.

percolation

returns the DFN percolation parameter, namely P33.

plename

spropfile
indicates the property file to be queried. This is used
only with the lename keyword. This is not currently
used in 3DEC. See Section 1.5.12 for a definition of
the property file format.

initialize

keyword . . .
This is a synonym for the attribute keyword.

intersection

keyword <range . . . >

delineates/destroys intersections. Intersections can exist between
fractures, and between fractures and geometry objects. The geometry keyword can be provided to produce intersections with fractures
and geometries. The supported geometries are polygons and edges.
Concave, planar polygons are not supported, nor are nonplanar polygons. Intersections are stored within an intersection set identified
by the name and id keywords. This intersection set must not exist.
Intersections can be visualized and queried in FISH. In addition, intersections are used to calculate clusters (see the DFN cluster command)
and connectivity (see the DFN connectivity command).
Intersections with geometry objects can result in polyline intersections. For instance, a fracture may intersect a cylindrical geometry
representing a borehole at many locations. Those individual fracture/polygon intersections that meet at geometry edges are merged
into polyline intersections.

delete

deletes the intersection set specified with the name and

id keywords.

3DEC Version 5.0

1 - 78

DFN

Command Reference

intersection

geomname
geomname

sgname <geometry range geomrange>

delineates the intersections between fractures and the
geometry set with name sgname. An optional range of
edges (polygons) can be specified following the geometry keyword to filter the geometry object in 2D (3D),
respectively. The di end2 fish intrinsic returns a
pointer to the geometry set in this case.

groupslot

islot
is an optional keyword indicating that the intersection
set name is placed in group slot islot of all fractures
found to be in the intersection.

id

iid
The ID of the intersection set is iid. If not specified,
the next available ID is chosen.

name

siname
The name of the intersection set is siname. If not
specified, siname = intersectionsXX where XX is the
intersection set ID.

nothrow

indicates that the determination of intersections will

continue in spite of geometry objects being nonplanar, concave or not simple polygons. The offending
fractures are skipped.

model

not currently used in 3DEC

property

pname v <pname v. . . > <range. . . >

assigns the value v to the surface property pname of fractures in
range. . . . This is not currently used in 3DEC.

prune

keyword
prunes isolated fractures. The intersection set that forms the basis for
this operation is specified by either the id or name keyword. Clusters
of fractures with size less than or equal to the number of fractures
specified with the size keyword are deleted.

id

id
The intersection set with ID id is used as the basis for
delineating fracture clusters. It cannot be given with
the name keyword.

3DEC Version 5.0

COMMAND REFERENCE
DFN
prune
name

name

1 - 79

sname
The intersection set with name sname is used as the
basis for delineating fracture clusters. It cannot be
given with the id keyword.

size

icrit
critical number of fractures in a cluster to mark it for
removal (icrit = 1, by default)

template

create keyword . . .
creates a DFN template. A DFN template is a set of statistical parameters used to generate stochastic DFNs with the DFN generate
command. These parameters are the size distribution, the position
distribution and the orientation distribution. By default, the DFN
template uses several properties: uniform fracture positions, uniform
orientations (dip between 0 and 90 , dip direction between 0 and
360 ) and sizes obeying a negative power-law distribution with exponent 4, l0 = 1 and lmax = +. Any of these values can be modified
with the following optional keywords:

dipdirlimit

ddl ddu
the minimum (ddl) and maximum (ddu) values for
fracture dip directions

diplimit

dl du
the minimum (dl) and maximum (du) values for fracture dips

id

i
creates a DFN template with the ID i. This ID must be
free. If not specified, the next available ID is chosen.

name

s
creates a DFN with the name s. This name must be
free. If not specified, the name templateID is chosen,
where ID is the template ID.

3DEC Version 5.0

1 - 80

DFN

Command Reference

template

orientation
orientation

type p1 . . . pn
defines the generation rule for fracture orientations
with the parameters p1 . . . pn. The following types
are supported:
bootstrapped: The dip and dip direction are bootstrapped from a file. A first parameter, which is the file
name holding the discrete distribution of values, must
be given. This file obeys the bootstrapped distribution
file format given in the Section 1.5.12.
dips: The dip and dip direction are bootstrapped from
a DIPS file. A first parameter, which is the file name
holding the discrete distribution of values, must be
given. This file obeys the ASCII DIPS* file format.
sh: The sh keyword is used to get values from a userdefined FISH function. The function name is given by
the first parameter, and the function arguments (any
number) are given after the function name. The function must return a 2-dimensional vector.
sher: The dip and dip direction are drawn from a
Fisher distribution. Three additional parameters are
required: dip, dip direction and kappa.
gauss: The dip and dip direction are drawn from Gaussian distributions. Four additional parameters are required: mean and standard deviation for the dip distribution, followed by mean and standard deviation for
the dip direction distribution.
uniform: The dip and dip direction are drawn from a
uniform distribution. No additional parameters can be
given.

position

type p1 . . . pn
defines the generation rule for fracture positions. The
keyword type can be defined with the values uniform,
gauss, bootstrapped and sh. The meaning of these
keywords is the same as for the orientation keyword,
except that the position is a vector in 3D. Consequently,
if bootstrapped, the file must contain the required number of values, and if a FISH function is used it must

* DIPS is a joint set analysis program developed by Rocscience Inc.

3DEC Version 5.0

COMMAND REFERENCE
DFN
template
position

1 - 81

return a vector of correct dimension. Additionally, the

mean and standard deviations must be vectors if the
gauss keyword is specified.

size

type p1 . . . pn
defines the distribution of fracture sizes. The fracture
size is defined as the disk diameter. The supported
types are uniform, gauss, powerlaw, bootstrapped and
sh. The powerlaw specifier defines a negative powerlaw distribution which requires one parameter, as1,
which is the exponent of the distribution with as1 > 0.
The remaining types are as specified in the orientation description, except that the return value is a floating point value. Thus only 2 arguments follow the
gauss specifier, the bootstrapped file must follow a
one-dimensional format, and the sh function must
return a single value.

slimit

sl su
the minimum (sl) and maximum (su) values for fracture sizes. The fracture size is the disk diameter.

template

delete range range of template

deletes DFN templates and the existing associations between DFN
and template.

traces

keyword
creates intersections corresponding to scanline mapping; requires
specifying the supporting plane (planar, convex polygon) and the reference scanlines (list of segments).

id

i
i is the ID of the intersection set containing the traces.
If id is not specified, then the next available ID is used.
The specified intersection set must not exist.

name

s
s is the name of the intersection set containing the
traces. If name is not specified, the name is set to
intersectionsXX where XX is the intersection set ID.
The specified intersection set must not exist.

3DEC Version 5.0

1 - 82

DFN

Command Reference

traces

scanline
scanline

scanset
The edges in the geometry set scanset are taken as
the set of scanlines. All fracture intersections with the
measurement plane (given by the surface keyword)
that also intersect a scanline are kept in the specified
intersection set.

surface

s
s is the name of the geometry defining the measurement plane

3DEC Version 5.0

COMMAND REFERENCE
DOMAIN

DOMAIN

1 - 83

keyword
specifies the allowed domain of a model. Currently only DFN objects are aware of the
domain. In future versions of 3DEC, all model objects (zones, structural elements,
etc.) will be required to be inside a previously specified model domain. This is
an axis-aligned bounding box whose extent in space is specified with the DOMAIN
command. In addition, the boundary conditions are specified with this command.

condition

keyword <keyword> <keyword>

sets the domain boundary conditions. The domain conditions are
provided in pairs so that opposite domain boundaries have the same
boundary conditions. Thus, for 3D there are 3 strings that can be
specified for the x, y, z boundaries, in that order. The condition in
the x-direction must be specified. If the conditions in y- and/or zdirections are not specified, the condition specified for the x-direction
is used. The following keywords are available:

extent

destroy

Objects are destroyed once they pass the boundary.

periodic

This boundary is a periodic condition objects are

mapped from one side to the opposite.

reect

specifies a reflection boundary. This is the default.

stop

Objects are prevented from passing the boundary.

xl xu <yl yu zl zu>
creates a domain that encompasses the region defined by these edges
of a rectangular box. The lower and upper coordinates in the xdirection must be specified. If the coordinates in the y- and/or zdirections are not specified, the coordinates defined in the x-direction
are used.

3DEC Version 5.0

1 - 84
DOMAIN

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
DUMP

DUMP

1 - 85

n m <offset>
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 5.0

1 - 86
DUMP

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
DYNAMIC

DYNAMIC

1 - 87

keyword
calculates natural frequencies and modes of vibration for an elastic system. This
command only applies for a rigid block model. The kinematic variables of the
system of rigid blocks are the 6 degrees of freedom of each block, 3 translations
and 3 rotations. In a rigid block model, the deformability is given by the joint
stiffness. A global stiffness matrix for the rigid block system is assembled, which
relates the forces and moments applied to the blocks by their neighbors with the
block displacements and rotations. The mass matrix is assumed to be diagonal, for
each block consisting of 3 entries equal to the block mass and the 3 moments of
inertia in the 3 coordinate directions. This assumption involves an approximation as
the moments of inertia in the coordinate directions are not, in general, the principal
moments of inertia of the block.
The dynamic (unscaled) masses must be calculated first. The command SET dynamic
on must be given, followed by CYCLE 0, to force the calculation of dynamic masses.
Note that the eigenvalue calculation solves a stiffness matrix, which requires a large
storage. Therefore, it is recommended that the simulation be stored before the eigenvalue calculation is performed, and then restored to continue the dynamic analysis.
See Section 2.8 in Optional Features for further information.
The following keywords apply:

delete

deletes eigenvalue data.

modes

n
calculates the first n eigenmode values. The 10 lowest frequency
modes are listed:
Mode
1
2
3
4
5
6
7
8
9
10

setmode

Description
first bending mode
mode shape orthogonal to mode 1
second bending mode
mode shape orthogonal to mode 2
first torsional mode
third bending mode
mode shape orthogonal to mode 6
axial deformation mode
fourth bending mode
mode shape orthogonal to mode 9

n
copies mode n to displacement magnitude vectors plot item for plotting.

3DEC Version 5.0

1 - 88
DYNAMIC

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
EXCAVATE

EXCAVATE

1 - 89

<range . . . >
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 that are removed cannot be replaced later with the FILL command.)
Excavated and/or removed blocks can be seen with the PLOT block excavate command.

3DEC Version 5.0

1 - 90
EXCAVATE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE

1 - 91

EXIT
EXIT

This is a synonym for the QUIT command.

3DEC Version 5.0

1 - 92

EXIT

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
FACETRIANG

1 - 93

FACETRIANGLE keyword
triangulates faces of rigid blocks to increase the number of vertices on a face.
The following keywords apply:

rad8

adds a center vertex and mid-edge vertices to all faces

radial

adds a center vertex to all faces

3DEC Version 5.0

1 - 94

FACETRIANG

3DEC Version 5.0

Command Reference

COMMAND REFERENCE

1 - 95

FFIELD
FFIELD

<keyword> <range . . . >

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 FFIELD heights)
The six free field blocks consist of four side FFIELD meshes corresponding to the four
model sides and four corner FFIELD meshes that act as an FFIELD boundary to the
side FFIELD meshes. The blocks in the FFIELD mesh are standard deformable blocks.
The joint structure in the FFIELD mesh is the same as in the model side boundaries.
Therefore, joint traces on the model sides are assumed to extend horizontally into the
FFIELD mesh. By default, all blocks in an FFIELD mesh are joined when the FFIELD
blocks are created, but the user may unjoin them afterwards. The zoning of FFIELD
blocks is similar to the zoning of model side faces. The side FFIELD blocks have
a thickness of two gridpoints across, linked to move together. The corner FFIELD
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.
The 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 FFIELD
(and possibly at the top, for deep underground models).
Run dynamic analysis.

3DEC Version 5.0

1 - 96

Command Reference

FFIELD
In some cases, it may be necessary for the user to change the initial state of the
FFIELD 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
Make any changes in FFIELD.
Set static boundary conditions at the FFIELD base.
Run to static equilibrium.
FFIELD link on
Set dynamic boundary conditions at the base of model and FFIELD
(and possibly at the top, for deep underground models).
Run dynamic analysis.
The keywords for the FFIELD command are:

apply

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

3DEC Version 5.0

gap

viewing gap between FFIELD and main model (default

= 5% of model length)

thickness

thickness of FFIELD blocks (default = 5% of model

length)

COMMAND REFERENCE

FFIELD

apply

1 - 97

tol
tol

tolerance to find gridpoints on model boundaries to

apply FFIELD 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 5.0

1 - 98

FFIELD

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
FILL

FILL

1 - 99

<keyword> <range . . . >

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 blocks 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 5.0

1 - 100
FILL

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
FIND

FIND

1 - 101

<ffield> <range . . . >

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 GENERATE 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 feld is given, then only blocks in
the free-field boundary are hidden.

3DEC Version 5.0

1 - 102
FIND

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
FISH

FISH

1 - 103

<keyword>
The following keywords apply:

debug

fish <keyword>
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.

initialize

fish value . . .
Where fish is the name of a FISH symbol. If the symbol does not
already exist, it is created. Any tokens following in value are parsed as
a FISH parameter, and the type evaluated. If the symbol was created
or the type does not match the previous type, the value is assigned to
the symbol. Otherwise, the value is discarded.

3DEC Version 5.0

1 - 104
FISH

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
FIX

FIX

1 - 105

<range . . . >
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 BOUNDARY nvel, BOUNDARY xvel, BOUNDARY yvel or BOUNDARY
zvel to specify velocities for deformable blocks. (Use the command LIST block vel
to make sure that blocks are fixed; code = 1 if fixed, 0 if freed.)

3DEC Version 5.0

1 - 106
FIX

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
FLUID

FLUID

1 - 107

<keyword>
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 gwow must be given before any blocks are created. The
PROPERTY 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 (ow); turn on/off
mechanical calculations (mechanical); control the interlace of mechanical and fluid
calculations (nmech and ngw); turn fastow 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 (fknot).
Currently you can plot the flow plane structure, discharge vectors and contours of
pore pressure and aperture.
The keywords are:

area min

v
defines minimum area (of flow plane zone) to be used in fluid flow
calculations. This is used to avoid very small timesteps. This is now
the preferred keyword, over volmin.

bulk

v
defines the bulk modulus of the fluid.

cowater

v
defines the cohesion of the fluid for non-Newtonian flow.

density

v
defines the density of the fluid.

3DEC Version 5.0

1 - 108
FLUID

Command Reference

empa
empa

defines exponent on aperture for conductivity. The default is 3.0.

empb

defines b factor for conductivity. The default is 1.0.

fhide

<range . . . >
hides fluid-flow planes.

fht coe

v
specifies fluid heat-transfer coefficient.

fseek

<range . . . >
restores fluid-flow planes.

fspec heat

v
specifies fluid-specific heat.

fth cond

v
specifies fluid-thermal conductivity.

gas alpha

v
defines a factor for gas flow.

gas bulkmin v
specifies minimum bulk modulus for gas flow.

gas constant v
specifies the gas constant for gas flow.

gas densitymin v
specifies the minimum density for gas flow.

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, PROPERTY and SET commands.

3DEC Version 5.0

COMMAND REFERENCE
FRACTION

FRACTION

1 - 109

fb <fz> <fw>
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). fw is the fraction of critical timestep to be used for fluid-flow timestep
(default fw = 1.0). The timestep used in cycling is the smaller of the zone and block
timesteps.

3DEC Version 5.0

1 - 110
FRACTION

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
FREE

FREE

1 - 111

<range . . . >
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 block vel to check whether blocks are freed; code = 1 if fixed, 0
if freed.)

3DEC Version 5.0

1 - 112
FREE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
GENERATE

GENERATE

1 - 113

keyword value <keyword. . . > <range . . . >

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 GENERATE 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 <Esc> 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 <alternate>
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 5.0

1 - 114
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 GENERATE 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 (GENERATE 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 gridpoint stress). Note: The high-order elements are incompatible with the free-field boundary and with the zone models
(DLL).

limit iteration n
limits the interior gridpoint spacing algorithm to zones with fewer
than n gridpoints. The spacing algorithm is designed to evenly space
interior gridpoints. This process can be very slow for blocks with a
large number of zones, and is probably not necessary. This command
allows the user to skip the spacing algorithm for these blocks.

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 ndivide controls the way discretization is done. i1, i2 and i3 are the numbers of
zones generated along three local directions (as shown in Figure 1.1):
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 200. Note: This
technique works only with regular six-sided polyhedra, and it is used
to make the zone overlays geometrically compatible.

3DEC Version 5.0

COMMAND REFERENCE
GENERATE quiet

1 - 115

quiet

limits information printed during zone generation. Opposite of verbose. Default is off.

rezone

edge ed <range>
allows the rezoning of blocks after cycling. This keyword is designed
to address problems with backfilling nulled blocks. Often, the zones
have collapsed in these blocks due to distortion. This new keyword
may help in those cases. The stresses in the new zones will be 0.0.

verbose

causes additional information to be printed during the zone generation

process. Use quiet to turn off verbose. Default is on.

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.

xyz
The keyword x 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 x keywords may be used to fix
several vertices.

gpmatch

performs gridpoint matching for previously zoned blocks.

3DEC Version 5.0

1 - 116
GENERATE

Command Reference

nomatch
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= 106 , v2= 104 ).

3DEC Version 5.0

COMMAND REFERENCE
GEOMETRY

GEOMETRY

1 - 117

<set sname> keyword

The geometry system allows the user to create, import and export geometric data.
These data can be used to interact with the model in a variety of ways. It can be used
as a filter with the range logic. It can also be used as a visualization aid with plotting.
FISH extra variables and group names may be assigned to geometric data. FISH
may be used to create and manipulate the data. The geometric data are organized
into geometric sets, which are named collections of nodes, edges and polygons.

copy

<source sname> target name keyword . . . <range . . . >

copies all geometric data from the source set (or the current default,
if not specified) to the target geometric set. The target set is created
if it does not exist. The optional range can be used to filter which
geometric objects are included in the copy. By default, all nodes,
edges and polygons in the range are copied unless the type to be
copied is restricted with a keyword.

edges

If specified, only edges and dependent points will be

copied.

group

name <slot s>

All copied objects will be assigned group name in slot
s.

edge

nodes

If specified, only nodes will be copied.

polygons

If specified, only polygons and dependent edges and

nodes will be copied.

<id id> location location

location is either a point (x,y,z) or the node keyword followed by an
ID of an existing node. It attempts to find an existing node at (x,y,z).
It creates an edge joining two locations. Nodes are created if none
already exist. A warning is issued if a zero-length edge is created.

extra

param <index i>

param can be any FISH parameter, including a vector
delimited by parentheses or a FISH fragment delimited
by brackets. If an extra index is not specified, each
extra keyword assigns extra data to subsequent indices
(i.e., extra 1.0 extra fred assigns 1.0 to extra index
1 and fred to index 2).

3DEC Version 5.0

1 - 118
GEOMETRY

Command Reference

edge

group
group

name <slot s>

If a groups slot is not specified, each group keyword
assigns a group to a subsequent slot (i.e., group fred
group george assigns fred to slot 1 and george to
slot 2).

export

filename(.geom) <keyword . . . >

exports polygons in the geometric set (as well as all required nodes
and edges) to the file filename. If the nodes or edges keyword is
specified, includes objects of those types in the search even if they
are not connected to polygons. The following keywords are available:

binary

indicates that the binary version of the file format

should be used for export. Not valid with DXF export.

edges

indicates that free edges (unconnected to any polygon)

should be exported as well.

format

specifies the file format to use for export. The default

will be selected based on the file name extension. The
following formats are available:

dxf

AutoCAD DXF format

geometry
Itasca geometry format. This format is described in Section 1.5.

stl

STL output polygons only. The nodes and

edges keywords are not supported.

nodes

indicates that free nodes (unconnected to any polygon)

should be exported as well.

range

<keyword . . . >
specifies the range (as a normal range keyword) of the
polygons to export within this geometry set.

3DEC Version 5.0

COMMAND REFERENCE
GEOMETRY group

group

1 - 119

type <keyword . . . > <range . . . >

assigns group names to a type based on their relation to geometric
sets. All connected polygons in all specified sets are automatically
assigned a surface number. From the position of each object, a ray is
projected in the direction specified by the projection keyword. 3DEC
will count the number of times that ray intersects each surface, and
use that information to assign a group name.
For instance, if no surfaces are intersected, then the group name No
Intersections is assigned. If surface 1 is not intersected, surface 2
is intersected once and surface 3 is intersected twice, then the group
name (2,1) (3,2) is assigned. The first number in each pair is the
surface number; the second is the number of intersections. If no
intersections are found in a surface, no entry is made in the group
name. In this way, all of the objects may be assigned group names
based on their geometric relation to one or more geometric sets. The
option range selects which objects are checked.
The following types are available:

gp

all gridpoints in the model

scalar

all user-defined scalars

selelement

all structural elements in the model

sellk

all structural links in the model

selnd

all structural nodes in the model

tensor

all user-defined tensors

vector

all user-defined vectors

zone

all zones in the model

The following keywords are available:

set

name
adds geometric set name to the list of sets checked.
If name does not exist, an error will occur. If no sets
are specified, then the current set will be used. Any
number of geometric sets may be specified.

slot

i
sets the group slot to which groups will be assigned.
The default slot is 1.

3DEC Version 5.0

1 - 120
GEOMETRY

Command Reference

group

projection
projection

xyz
specifies the direction of the ray used to calculate intersections. The default ray is in the direction (0,0,1).

For example, to select the zones on one side of the geometry in the
file hopper.stl, you can use the commands
geometry import hopper.stl
geometry group zone set hopper projection (0,0,-1)

In this example, all zones above the hopper in the z-direction will be
assigned the group name (1,1), and all other zones will be assigned
the group name No Intersections.

import

filename <keyword . . . >

imports geometric data from the file filename. The following keywords are available:

format

keyword
The importer will attempt to infer the proper format
from the contents of the file, but the format keyword
can be used to force it to interpret the file as a given
format. The following formats are available:

dxf

DXF file (.dxf). This is a partial implementation of the format as of AutoCAD version
12. Layer names are assigned to group slot
1.

geometry
Itasca geometry file format geometry file
(.geom). Binary or text version is determined
automatically. The format is described in
Section 1.5.

stl

group

STL file (.stl). Solid names are assigned to

group slot 1. Binary or text version is determined automatically.

<slot s> <add>

assigns the group name to slot s in imported geometry
objects. The default slot number is 1. If the add keyword is used, the group is added to the first available
slot.

3DEC Version 5.0

COMMAND REFERENCE
GEOMETRY import
nomerge

1 - 121

nomerge

By default, the STL format will search for and merge

nodes and edges that are in the same location in space
within a default tolerance. Using this keyword will
stop this process, speeding up the import but increasing
the amount of data imported.

set

name
By default, the imported geometry is assigned to a set
with a name that is identical to the imported file name
without extension. This can be overridden with the set
keyword.

node

<id id> x y z keyword . . .

creates a node at location (x,y,z).

extra

param <index i>

param can be any FISH parameter, including a vector
delimited by parentheses or a FISH fragment delimited
by brackets. If an extra index is not specified, each
extra keyword assigns extra data to subsequent indices
(i.e., extra 1.0 extra fred assigns 1.0 to extra index
1 and fred to index 2).

group

name <slot s>

If a groups slot is not specified, each group keyword
assigns a group to a subsequent slot (i.e., group fred
group george assigns fred to slot 1 and george to
slot 2).

paint

i zonefield <keyword . . . > <range . . . >

paints the zone field variable zonefield (see Section 2.5.2.17 in the
FISH volume) and places the value into extra variable i of the nodes
of the geometry set. The range filters which nodes of the geometric
set have values applied. The following keywords are available:

effective

on/off
For stress data, sets the stress to effective if true. The
default is false.

extra

i
sets the extra variable index for zone or gridpoint extra
variable data.

3DEC Version 5.0

1 - 122
GEOMETRY

Command Reference

paint

method
method

keyword
sets the interpolation method for zone-based data. The
following keywords are available:

average The value is averaged to gridpoints, then linearly interpolated to zone interior.

constant The value is assumed constant across the

zone. This is the default.

idw

<keyword . . . >
Inverse distance weighting is used to bring
values to gridpoints. Then values are linearly
interpolated to the zone interior.

power

value
The larger the value, the more
nearby zones are weighted relative to more distant ones. The
default is 3.0.

radius

value
sets the radius, which controls
how many zones are used in the
averaging process. This should
fall between 0.0 and 1.0. The default is 0.75.

polynomial <tolerance value>

specifies that a polynomial fit is used to bring
values to the gridpoints, and then linear interpolation is used in the zone interior. The tolerance is used to indicate that insufficient data
were given in a degree-of-freedom, which is
then considered to be constant.

null

<keyword . . . >
By default, null mechanical zones are ignored when
bringing zone-based values to gridpoints. However,
the null keywords can be used to change that assumption. The null rules are reset, and the following keywords, if used, cause either fluid, thermal or mechanical null zones to be ignored. Any combination may
be given.

3DEC Version 5.0

COMMAND REFERENCE
GEOMETRY paint
null

1 - 123

fluid
fluid

Zones with null fluid models are ignored.

mechanical Zones with null mechanical constitutive

models are ignored.

thermal
property

Zones with null thermal models are ignored.

propname
For zone property data, specifies the name of the property.

polygon

<id id> edges id id id . . . <extrude x y z> <keyword . . . >

or nodes id id id . . . <extrude x y z> <keyword . . . >
or positions (x,y,z) (x,y,z) (x,y,z) . . . <extrude x y z> <keyword . . . >
creates a polygon from a list of edges, a list of nodes or a list of points
in space. If an edge list is used, they must be given in order and
they must form a closed polygon. If a node list is used, edges are
created if none are found, and the polygon is automatically closed. If
a position list is used, nodes and edges are created if none are found,
and the polygon is automatically closed. A warning results if the
polygon is not planar or convex. If an extrude vector is provided,
then the polygon will be extruded along that vector, resulting in a
closed volume of polygonal surfaces.

extra

param <index i>

param can be any FISH parameter, including a vector
delimited by parentheses or a FISH fragment delimited
by brackets. If an extra index is not specified, each
extra keyword assigns extra data to subsequent indices
(i.e., extra 1.0 extra fred assigns 1.0 to extra index
1 and fred to index 2).

group

name <slot s>

If a groups slot is not specified, each group keyword
assigns a group to a subsequent slot (i.e., group fred
group george assigns fred to slot 1 and george to
slot 2).

3DEC Version 5.0

1 - 124
GEOMETRY

Command Reference

remove
remove

<nodes> <polygons> <edges> <noclean> <set sname>

<range . . . >
Remove geometric objects that fall inside the given range. Removal
can be restricted to nodes, edges or polygons. All objects that depend on a given object will be removed. For instance, if a node is
removed, all edges connected to it will be removed. If an objects
removal causes data structures to be orphaned (no other objects
refer to them), then these objects are automatically removed as well,
unless the noclean keyword is given. The set keyword will remove
the geometric set (and all of its contents). In this case, any range
specification is ignored.

set

sname
specifies the current (and subsequent default) geometric set. All
nodes, edges and polygons are contained inside a geometric set. These
sets may be referred to by ID number or a string name. If never specified, the set is assumed to be named Default.

3DEC Version 5.0

COMMAND REFERENCE
GRAVITY

GRAVITY

1 - 125

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

3DEC Version 5.0

1 - 126
GRAVITY

3DEC Version 5.0

Command Reference

COMMAND REFERENCE

1 - 127

GRID
GRID

x1 y1 z1 x2 y2 z2 x3 y3 z3 type n str s N12 n12 N23 n23 <tstart ts>

A grid of point sources is set up, each of strength str. The source is of type n, and
starts at time ts. The grid need not be rectangular. The points (x1,y1,z1), (x2,y2,z2) and
(x3,y3,z3) are the top-left, top-right and bottom-right points of the grid, as illustrated
in Figure 1.27 in Optional Features. The number n12 defines the number of points
across the grid from left to right, and n23 defines the number from top to bottom.
The source may be outside the 3DEC grid. The start time defaults to zero if not
specified, but the type and strength must be specified. The type, strength and number
of sources may be specified in any order.

3DEC Version 5.0

1 - 128

GRID

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
GROUP

GROUP

1 - 129

type name keyword . . . <range>

assigns the group name to all objects of that type that fall within the range. Groups
are names used to identify sets of objects (e.g., zones). Each object may belong to
many groups, up to a maximum of 128.
The group range element can be used to select objects by group name. The command
GROUP list lists the existing group names.
The following types of objects can be used with the GROUP command:

block

The group range element will select a block if it is visible and part of
the group.

contact

The group range element will select a contact if either of the blocks
associated with it are visible and the contact is part of the group.

list

lists all groups that have been created.

scalar

user-defined scalars. See the SCALAR command.

subcontact

The group range element will select a sub-contact if either of the

blocks associated with it are visible and the sub-contact is part of the
group.

tensor

user-defined tensors. See the TENSOR command.

vector

user-defined vectors. See the VECTOR command.

vertex

vertex (gridpoints). The group range element will select a vertex

(gridpoint) if it is part of the group.

zone

zones

The following keywords can be used to modify how the group is applied:

add

If not already present, the group is added to the first available slot.

remove

The group is removed from all slots, if present.

slot

s
The group is assigned to slot s of the object. By default, the slot
number is 1.

3DEC Version 5.0

1 - 130
GROUP

3DEC Version 5.0

Command Reference

COMMAND REFERENCE

1 - 131

GUI
GUI

project save <filename(.3dprj)>

Under the standard Itasca interface for 3DEC, this causes the current project to be
saved. If a file name is not given, the file used for the last project save is used. The
default extension for a file name is .3dprj.

3DEC Version 5.0

1 - 132

GUI

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
HEADING

HEADING

1 - 133

string
This is a synonym for the TITLE command.

3DEC Version 5.0

1 - 134
HEADING

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
HELP

HELP

1 - 135

The HELP command provides a screen listing of the available 3DEC commands.
HELP may also be typed as a keyword to any 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 5.0

1 - 136
HELP

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
HIDE

HIDE

1 - 137

<ffield> <range . . . >

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 most
commands that change something.
If no range is specified, all blocks are hidden. If the optional keyword feld is given,
then only blocks in the free-field boundary are hidden.

3DEC Version 5.0

1 - 138
HIDE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
HISTORY

HISTORY

1 - 139

<id id> <nstep n> 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 5.0

1 - 140
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 <dip dip> <dd dd>

sum of areas for all sub-contacts associated with the contact

area

x y z <dip dip> <dd dd>

the area of the contact

nf sum

x y z <dip dip> <dd dd>

sum of normal forces for all sub-contacts associated with the contact

sf sum

x y z <dip dip> <dd dd>

sum of shear forces for all sub-contacts associated with the contact

sdisplacement x y z <dip dip> <dd dd>

ndisplacement x y z <dip dip> <dd dd>
shear and normal contact displacements

sforce

x y z <dip dip> <dd dd>

nforce

x y z <dip dip> <dd dd>

shear and normal contact force

sstress

x y z <dip dip> <dd dd>

nstress

x y z <dip dip> <dd dd>

shear and normal contact stress

3DEC Version 5.0

COMMAND REFERENCE
HISTORY
nstress

1 - 141

xsdisplacement x y z <dip dip> <dd dd>

ysdisplacement x y z <dip dip> <dd dd>
zsdisplacement x y z <dip dip> <dd dd>
one component of the contact shear displacement vector

xsstress

x y z <dip dip> <dd dd>

ysstress

x y z <dip dip> <dd dd>

zsstress

x y z <dip dip> <dd dd>

one component of contact shear force

Global Histories

address

iadd <ioff>
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.)

crtdel

creep timestep

crtime

creep time

damping

adaptive global damping parameter (see Section 1.2.3.2 in Theory

and Background)

energy

time histories for the summed totals of 20 strain and dissipation energy
components (see LIST energy)

mtime

mechanical time (synonym for time)

ratio

solve ratio

thtime

thermal time

time

mechanical time

unbalanced

maximum out-of-balance force

Fluid Knot Histories

uid pp

xyz
pore pressure

uid temp

xyz
temperature

3DEC Version 5.0

1 - 142
HISTORY

Command Reference

uid temp
Vertex Histories

xvelocity

xyz

yvelocity

xyz

zvelocity

xyz
one component of vertex 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

acceleration

xyz
acceleration magnitude

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

3DEC Version 5.0

All history traces are deleted. (This keyword is a synonym for the
reset keyword.)

COMMAND REFERENCE
HISTORY
dump

dump

1 - 143

id1 <id2 . . . idn> <keyword . . . > <destination>

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.

end

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.

le

filename
The history information is sent to a text file. If no
extension is specified, .HIS is used.

3DEC Version 5.0

1 - 144
HISTORY

Command Reference

dump

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

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

<label>
Summary information (descriptive name and position of the entity
being sampled) is written to the screen. If label is specified, then userassigned labels are displayed instead of positions. (This keyword is
a synonym for the LIST history command.)

ncycle

n
specifies the history-sampling interval.

purge

The contents of all history traces are erased, but the traces themselves
remain.

reset

All history traces are deleted. (This keyword is a synonym for the
delete keyword.)

type

id
displays the value of a variable (with history number id) on the console
during cycling.

write

id1 <id2 . . . idn> <keyword . . . > <destination>

This is a synonym for the dump keyword, except that the default
destination is the file 3DEC.HIS.

3DEC Version 5.0

COMMAND REFERENCE
INITEMP

1 - 145

INITEMPERATURE temperature t <xgrad dtx> <ygrad dty> <zgrad dtz> <gradient dtx dty dtz>
The initial temperature and temperature gradients are specified with this command. The temperature at any point is calculated as
Tgridpoint = t + dtx x + dty y + dtz z

3DEC Version 5.0

1 - 146
INITEMP

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
INITIALIZE

INITIALIZE

1 - 147

keyword vo <grad gx gy gz> <range . . . >

Certain gridpoint or zone variables are assigned initial values. The range over which
the initial condition is applied can be limited by range. Ranges are described in
Section 1.1.3. If no range is given, all visible blocks have their gridpoints or zone
variables initialized.

gpp

vo
gridpoint zone pressure
(calculated as: v = vo + gx x + gy y + gz z)

sxx

vo
zone xx-stress (total)

sxy

vo
zone xy-stress (total)

sxz

vo
zone xz-stress (total)

syy

vo
zone yy-stress (total)

syz

vo
zone yz-stress (total)

szz

vo
zone zz-stress (total)

temperature

vo
gridpoint temperatures (must be configured for thermal calculations
CONFIG thermal)

xdisplacement vo
gridpoint x-displacement

xvelocity

vo
gridpoint x-velocity

ydisplacement vo
gridpoint y-displacement

3DEC Version 5.0

1 - 148
INITIALIZE

Command Reference

yvelocity
yvelocity

vo
gridpoint y-velocity

zdisplacement vo
gridpoint z-displacement

zvelocity

vo
gridpoint z-velocity

NOTES:
1. Remember that compressive stresses are negative. Also, these are total stresses
if WATER table, INITIALIZE gpp or INSITU pp is issued.
2. Velocity units are length per timestep (real time only if a dynamic analysis is
performed).

3DEC Version 5.0

COMMAND REFERENCE
INSITU

INSITU

1 - 149

keyword . . . <range . . . >

Initial zone stresses in all deformable blocks and stresses along joints between rigid
blocks or deformable blocks (in the optional range defined by the range phrase) are
set with the INSITU command. The range types are described in Section 1.1.3. If
no range is specified, stresses are initialized for the entire model. The following
keywords apply:

pp

po <gradient px py pz> <nodisplacements>

pore-water pressure. nodisplacements prevents normal
displacements (due to initial stress) from being subtracted from azero
(hydraulic aperture at zero stress).
p = po + (px)x + (py)y + (pz)z

principal

s1,s2,s3 s1 dip,s1 dd s2 dip s2 dd <keyword>

Alternate method to define insitu stresses by specifying a stress measurement at a point and an optional gradient.

s1

major principal stress

s2

intermediate principal stress

s3

minor principal stress

s1 dip

major principal stress dip

s1 dd

major principal stress direction

s2 dip

intermediate principal stress dip

s2 dd

intermediate principal stress direction

The following are optional keywords:

zgradient

value
gradient in the z-direction (vertical)

location

xs,ys,zs
The location specifies the coordinates of the stress
measurement. The gradient is the stress change in the
vertical direction. All other stresses are incremented
proportionately by the gradient to prevent stress rotation.

3DEC Version 5.0

1 - 150
INSITU

Command Reference

stress
stress

sxxo syyo
<xgradient
<ygradient
<zgradient

szzo sxyo sxzo

sxxx syyx szzx
sxxy syyy szzy
sxxz syyz szzz

syzo
sxyx sxzx syzx>
sxyy sxzy syzy>
sxyz sxzz syzz>

where:
sxx = sxxo + (sxxx)x + (sxxy)y + (sxxz)z
syy = syyo + (syyx)x + (syyy)y + (syyz)z
szz = szzo + (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 xgradient, ygradient and zgradient keywords must follow the stress
keyword on the same input line. (Use ... at the end of the line if a
continuation line is required.)
example:
poly brick 0,5 -10,0 0,5
jset. . .

insitu stress -5,0,0,0,0,0

ygrad 15.0,0,0,0,0
This command applies a gradient to the xx-stress varying from 5 at
y = 0 to 155 at y = 10.
The xx-stress, yy-stress, zz-stress, xy-stress, xz-stress and yz-stress
components are initialized to the values sxxo, syyo, szzo, sxyo, sxzo
and syzo.*

nodis

prevents normal displacements (due to initial stress)

from being subtracted from azero (hydraulic aperture
at zero stress). Consequently, if nodis is used, azero is
the initial stress aperture, not the zero-stress aperture.

* Remember that compressive stresses are negative.

3DEC Version 5.0

COMMAND REFERENCE
INSITU
topograph

topograph

1 - 151

<keywords>
enables the setting of in-situ stresses based on the density of overburden. This command is used in models where the top surface is
irregular, giving rise to significant variation in stress due to overburden.
The following keywords are available:

kox

vo
stress ratio in x-direction

koy

vo
stress ratio in y-direction

koz

vo
stress ratio in z-direction

xup

specifies that up is in the direction of positive x-axis.

yup

specifies that up is in the direction of positive y-axis.

This is the default setting.

zup

specifies that up is in the direction of positive z-axis.

NOTES:
1. jmat, jcons and joint properties must be specified prior to the INSITU command,
in order to calculate joint normal displacement due to in situ stress.
2. For jcons = 3, joint initial closure is only calculated for the INSITU command if
joint normal stiffness is constant (i.e., en = 0).

3DEC Version 5.0

1 - 152
INSITU

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
ISOTHERMAL

1 - 153

ISOTHERMAL <x> <y> <z>

This command is used to define isothermal boundary layers. For example, the two
planes defined by x = 0 and y = 0 are isothermal if the command ISOTHERMAL x y
is issued.
NOTE: A plane cannot simultaneously be an isothermal boundary and a symmetry
plane.

3DEC Version 5.0

1 - 154
ISOTHERMAL

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
JMODEL

JMODEL

1 - 155

keyword <range . . . >

This command is used to assign extended joint constitutive models or user-defined
joint models (UDJM) to sub-contacts in 3DEC. This command is also used to assign
properties to these sub-contacts. To use this command, the UDM option is required.
In addition, CONFIG cppudm must be used in order for this command to be accepted.
Joint models exist as dynamically linked libraries, and must be loaded. This can
be done by using the JMODEL load command (or the LOAD jmodel command). The
models may then be assigned to zones via the JMODEL command.

list

<keyword> <jmodel>
outputs a summary of all dynamically loaded joint constitutive models, or outputs information for only the model specified by jmodel.

load

list

outputs name and version numbers. (default)

properties

outputs the list of available properties.

states

outputs the possible states.

version

is a synonym for list.

jmodel
dynamically loads a joint constitutive model. The dynamic library
should have the name jmodeljmodel001.dll. For example, joint
model mohr would have a library name of jmodelmohr001.dll.

model

jmodel
assigns the dynamic joint constitutive model jmodel to all of the subcontacts in the range. If not already loaded, the system will attempt
to automatically load the library.

property

value
assigns value to the property property for every sub-contact in the
range for which that property applies.

At present, one constitutive model is available through the use of this command. The
model is described in Section 3.2.2.1 in Constitutive Models. Any joint constitutive
models that already exist for some or all of the sub-contacts in the given range (as
specified by CHANGE jcons) are ignored.
Properties assigned through this command are model-specific. Other joint properties
entered via the PROPERTY command are ignored if the sub-contacts fall within the
range specified by the JMODEL command. The joint model must be assigned before
assigning properties. If properties that are not consistent with the chosen model are
given, a warning message informing the user that the unneeded properties were not

3DEC Version 5.0

1 - 156
JMODEL

Command Reference

accepted will be given. If a required property is not specified, the default will be
used.
WARNING: When jmodel is invoked over a specified range, all properties associated
with that model are initialized to zero in that range. Properties previously assigned
to that range must be specified again, even if their values have not changed.
The following properties are for the Mohr model:

cohesion

joint cohesion

dilation

joint dilation angle in degrees

friction

friction angle in degrees

jkn

joint normal stiffness

jks

joint shear stiffness

resdilation

residual joint dilation angle in degrees

resfriction

residual joint friction angle in degrees

restension

residual joint tensile cutoff

tension

tensile cutoff

zerdilation

shear displacement for zero dilation

3DEC Version 5.0

COMMAND REFERENCE
JOIN

JOIN

1 - 157

on/off <range . . . >

Adjacent blocks within an optional range can be joined into one block by using the
on keyword, or unjoined by using the off keyword. Joined blocks act as one block
with a common centroid and volume calculated for all blocks joined together. A
joined block group consists of one master block and one or more slave blocks.
Use the LIST block command to identify master and slave blocks in a block group.
Ranges are described in Section 1.1.3. NOTE: Only visible blocks are joined. Block
ranges are used in this command.

3DEC Version 5.0

1 - 158
JOIN

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
JOIN CON

1 - 159

JOIN CONTACTon/off <range . . . >

Contacts within an optional range can be identified to join blocks by using the on
keyword, or unjoined by using the off keyword. Joined blocks act as one block with
a common centroid and volume calculated for all blocks joined together. A joined
block group consists of one master block and one or more slave blocks. Use
the LIST block command to identify master and slave blocks in a block group.
Ranges are described in Section 1.1.3. NOTE: Only visible blocks are joined.
Contact ranges are used in this command.

3DEC Version 5.0

1 - 160

JOIN CON

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
JSET

JSET

1 - 161

<keyword = value> <. . . >

generates one set of discontinuities, according to the parameters specified by the
following keywords. Blocks are split completely (i.e., no partial cracks are allowed).

dd

a <adev>
is the dip direction, in degrees, of joints comprising the set given by
angle a, where 0 < a < 360 , measured clockwise from the positive
z-axis, which is taken as North (see NOTE, below).
A random deviation, different for each block cut, is specified by adev.

dip

a <adev>
is the dip, in degrees, of the joints comprising the set (i.e., the angle
of the joints below the y = 0 plane; see NOTE, below).
An optional random deviation, adev, specifies the limit of deviation;
a different deviation is applied to each block split.

num

n
is the number of joints in the set. Joints are produced symmetrically
about the joint-set origin, given by origin (x,y,z).

origin

xyz
is the origin, or starting point, of the joint set. The first joint generated
will pass through this point.

p3

x1, y1, z1 x2, y2, z2 x3, y3, z3

specifies the joint orientation by 3 points on the plane.

persistence

p
is the probability that any given block lying in the path of a joint
will be split (i.e., if p = 0.5, then 50% of the blocks will be split, on
average).

spacing

s <sdev>
is the spacing between joints of the set. A random deviation (different
for each block cut) is specified by sdev.

Defaults for the preceding parameters, if not given, are zero, except for persistence
and num, which both default to 1.

3DEC Version 5.0

1 - 162
JSET

Command Reference

id
id

sets joint plane id number for all faces and contacts created with the
JSET command. This will override the number that would be assigned
automatically. The joint plane id is normally incremented with each
operation that creates new faces. The base number for the joint plane
id number is 0 unless specified by the SET jointid command.

join

joins blocks across the joints created by the JSET command.

NOTE: The reference axes for 3DEC are a left-handed set (x,y,z) which are oriented
for joint generation (x (east), y (vertically up) and z (north)). If the problem orientation is different from these reference axes, the joint or joint set will have to be
transformed from the problem reference frame to the model reference frame. (See
Section 3.2.5 in the Users Guide for recommended transformation procedures.)
All statistical variations in the joint set parameters are generated by a call to a random number generator. The SET random command can be used to vary the random
number generator seed.

3DEC Version 5.0

COMMAND REFERENCE
LABEL

LABEL

1 - 163

<id i> keyword

generates or modifies a user-defined label, which may be added to model information
during plotting. If id is specified, a label with ID i is either modified or created. If id
is not specified, then a new label will be created, and a unique ID number assigned
automatically. The following keywords apply:

arrow

bool
specifies whether the line connecting (xb,yb,zb) to (xe,ye,ze) ends
with an arrowhead. This only applies if end has been specified.

delete

completely deletes the label; no further keywords can be applied. An

ID must be specified, and must refer to an existing label.

end

xe ye ze
If end is specified as different from (xb,yb,zb), then the label will
include a line going from (xb,yb,zb) to (xe,ye,ze).

text

string
sets the labels text to be string. This text will be output to the screen
at the location defined by (xb,yb,zb).

xb yb zb

specifies the labels origin coordinates. The default is (0,0,0).

3DEC Version 5.0

1 - 164
LABEL

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
LINE

LINE

1 - 165

xb yb zb xe ye ze type n strength s n12 np <tstart ts>

A line heat source consisting of np point sources, each of strength s, is placed
along the line beginning at xb,yb,zb and ending at xe,ye,ze. The source is of type
n, and starts at time ts. As with the point source, the source may be outside the
3DEC grid, the start time defaults to zero if not specified, the type and strength must
be specified, and the type, strength and number of sources may be specified in any
order.

3DEC Version 5.0

1 - 166
LINE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
LIST

LIST

1 - 167

keyword <keyword> . . . <range . . . >

Printed output of program and model information is produced, according to the
keyword(s) given below. If a range is specified (see Section 1.1.3), then printed
output will be restricted to entities that lie within the given range.
In addition to the keywords listed below, one or more FISH symbol names can be
given as keywords; their values will be printed. If the symbol name is that of a FISH
function, then it will be executed (and all functions that it invokes will be executed)
before its value is printed. If the symbol is a simple FISH variable, then its current
value will be printed.
The following keywords are available:

apply

blocks with applied velocities or applied thermal conditions

at

x, y, z
zone stresses, vertex displacements and velocities nearest to specified
location

axial

data for axial reinforcement elements

b max

addresses of blocks that have the largest and smallest coordinates,

displacements and velocities

bad3

block faces that have 3 vertices along a single edge; used in diagnosing
problems with zoning

badface

block faces that have normals that do not point out from the center of
the block (inverted faces)

beam

<keyword>
data for structural beam elements. If no keyword is specified, the data
for all of the following keywords are output:

contacts
elements
loads
nodes
property
blist

block contact list data

3DEC Version 5.0

1 - 168
LIST

Command Reference

block
block

boundary

<keyword>

information

general block information, including ID, material

number, constitutive number, region, type and masterslave status (this is the default)

moment

block moment information

extensive information about a single block given by n

position

block centroid position and volume

velocity

both translational and rotational velocities

keyword

displacement displacement at boundary

force

forces at boundary

reactions

keyword

forces

reaction forces at any gridpoint with a fixed

velocity (output is in a format that can be used
directly in the BOUNDARY point x y z xload
command)

tractions reactions at fixed velocity points in the form

of average tractions on the surrounding faces
(the output can be used directly in the BOUNDARY triangle command)

state

boundary condition state specified by boundary code

ix, iy, iz
0 free
1 stress (or force)
2 viscous
3 velocity

3DEC Version 5.0

summary

total of forces applied on the x-, y- and z-boundaries

velocity

velocities applied to boundary

COMMAND REFERENCE
LIST
brick

brick

1 - 169

x1 xu y1 yu z1 zu forces <grid d> <le lename>

This command provides an alternative to the LIST boundary reactions
command. It is used when the stresses inside a global model are
to be transferred as boundary conditions to a smaller model. The
smaller model must be defined as a brick-shaped polyhedron. The
command creates a file with BOUNDARY point, BOUNDARY xload,
BOUNDARY yload and BOUNDARY zload, which are used as input in
the smaller model data file. The global model need not have joints
corresponding to the boundaries of the smaller model, as required by
the LIST boundary reactions command. The forces are calculated by
sampling stresses in a regular grid located on the brick faces. The
grid size may be defined by the user. The forces are corrected so
that the force sums balance the gravity forces acting inside the brick
region. It is assumed that no holes exist inside the brick. The default
file name is BRICK.PRN. The default grid-spacing is 0.1 largest
brick dimension.

cable

data for reinforcing elements (cables) that model shear behavior of

grout annulus

cave

input parameters used in the CAVE command

cell

cell space data

concave

block edges that have a face-to-face angle of 180 or greater. Face-toface angles greater than 180 are concave, and may cause problems
when zoning or sliding.

contact

<noms> <nonull> <null> <keyword>

general contact information. The noms keyword suppresses output
of data for master-slave contacts in joined blocks. The nonull keyword suppresses output of data for null contacts. The null keyword
suppresses output of data for non-null contacts.

allsub

data for contacts in two tables intended for transferring contact data to a file for use in post-processing.
Output is only sent to the log file, which must be turned
on by the user.

cy

additional parameter used for continuously yielding

model

displacement contact displacements

face

block face information for sub-contacts

3DEC Version 5.0

1 - 170
LIST

Command Reference

contact

couple

ff
ff

data only for face-to-face contacts must precede other

keywords

joint

joint ID information for contacts

location

contact locations

extensive information for a single contact identified by

n

orientation

contact dip and dip direction

pp

joint pore pressure

pressure

fluid pressure at contacts

state

state of contacts: area, fs/fn, shear displacement, slip

indicator (0 = not at slip, 1 = at slip, 2 = slipped in past,
3 = tensile failure), c-y parameters (eff , L, r)

stress

sub-contact shear and normal stress data

summary

gives a summary of sub-contacts in the model; gives

totals by material type, open and slipping contacts; and
gives slip area and maximum displacements.

type

global information according to contact type

vertex

displacement data for vertices associated with subcontacts

keyword

forces

interface forces between the on and off regions (used

with the COUPLE command)

state

on/off status of all regions. It is used with the COUPLE

command.

cp

common-plane data (unit normal vector and reference point) and type
(see Table 1.1 in Theory and Background)

creep

list of creep control parameters

dfn

discrete fracture network (DFN) information

dir

current directory (folder)

3DEC Version 5.0

COMMAND REFERENCE
LIST
displacement

1 - 171

displacement <along x1,y1,z1 x2,y2,z2 n> <lename(.prn)>

<at x,y,z>
<screen>
print feature designed for transferring 3DEC-calculated results to
other programs for additional processing. The print format is 7 digits
of precision. Each printout is headed by a single header line labeling
the data. For the displacement keyword, x, y, z, xdisp, ydisp and zdisp
are printed. Data for hidden blocks will not be included. If no file
name is specified, stress plots will go to DISP.PRN. Otherwise, the
output can be redirected to the console using the screen keyword.

domain

domain information for discrete fracture networks (DFN)

energy

summary of strain-energy calculation (see SET energy)

face

<keyword>

center

the location of the face centroid

information

general face information, including block number, normal vector, area, joint number and sregion (this is the
default)

vertices

vertices that make up the face

fcheck

performs an internal check on the data structures associated with the

face sub-contact logic. It is used in diagnosing problems.

feblock

finite element links (only available with structural liner option see
Section 3 in Optional Features)

fedge

fracture fluid-flow plane-edge data

ffield

dynamic free-field data

sh

<keyword>

basic

a more condensed list of all FISH symbols. Generally,

LIST sh symbols is preferred.

code <fish> lists all FISH internal pseudo-code used to execute

functions. If fish is specified, only the code associated
with the function fish is output. In safe mode (the
default), an @ character is required before the symbol
name.

3DEC Version 5.0

1 - 172
LIST

Command Reference

sh

contents
contents

fisharray
lists contents of arrays, matrices and tensors. For arrays larger than two dimensions, the array will be output as two-dimensional slices with the coordinates
given alongside input.

fishcall

lists all FISH functions that have been specified as a

fishcall. See SET sh call.

intrinsics

lists all available FISH intrinsic functions, in alphabetical order (includes arguments and return types).

memitem

lists all current memitem blocks.

symbols

lists all FISH variables, including their current types

and values, unless the symbol name starts with a $
character. This is the default.

fknot

fracture fluid-flow knot data

aw

<keyword . . . >
normal and shear tractions on a hypothetical plane, specified by dipangle, dip direction (ddirection) and origin coordinates. The area of
output may be limited by the radius keyword. This is used to assess
slip potential in different orientations.

ddirection

dd
dip direction of aw

dipangle

dip
dip angle of aw

le

filename(.txt)
Output is sent to the file filename.

origin

org
origin of sphere if radius is used

radius

rad
radius of sphere-limiting area of output

screen
owrate

3DEC Version 5.0

Output is sent to the screen rather than to a file.

fluid flow rates for flow planes

COMMAND REFERENCE
LIST
owvel

1 - 173

owvel

fluid velocities for flow planes

uid

lists fluid properties.

fos

current factor-of-safety value (see SOLVE fos)

fpipe

fracture fluid-flow pipe data

fplane

fracture fluid-flow plane data

fzone

flow zone information

geom

imported geometry objects

global

global model values

gridpoint

keywords:

displacement gridpoint displacements

dsfactor

gridpoint density scaling factors

force

gridpoint unbalanced forces

location

gridpoint coordinates

mass

gridpoint location, mass and block linkage

ppressure

gridpoint pore pressure

stress

gridpoint stresses (only for high-order elements)

temperature

gridpoint temperatures

thermal

gridpoint thermal mass, temperature state, temperature

change and heat

velocity

gridpoint velocities

group

group names

heat

heat source data (only available with thermal option see Section 1
in Optional Features)

history

<label>
outputs summary information (describing name and position of the
entity being sampled) to the screen. If label is specified, then userassigned labels are displayed instead of positions. LIST history is a
synonym for the HISTORY list command.

3DEC Version 5.0

1 - 174
LIST

Command Reference

information
information

extensive list of global variables, parameter settings and program state

information

jmodel

<model> <keyword>
outputs currently loaded user-defined joint models. If model is specified, information is generated for that model only.

list

outputs model keyword, name and version number.

properties

outputs property list for model(s).

states

outputs possible state flags for model(s).

jmtable

table of contact (joint) material mappings

junk

list of available memory packets (used for debugging purposes)

label

<id i>
lists all user-defined labels. If id is specified, the contents of the
corresponding label are output.

lg

list of joined gridpoints

line

x1,y1,z1 x2,y2,z2 n
data at n equally spaced points along the line (x1,y1,z1) to
(x2,y2,z2). At present, it works only with zone keywords.

liner

<keyword>
liner element information

contacts

material elements

elements

liner elements

loads

liner loads

nodes

liner nodes

property

liner properties

macro

user-defined macros

master

master blocks

maxima

maximum and minimum of block and zone data (hidden blocks are
excluded)

mechanical

list model mechanical information

3DEC Version 5.0

COMMAND REFERENCE
LIST
memory

1 - 175

memory

amount of memory that is actively being used by 3DEC

model

<model> <keyword>
outputs currently loaded user-defined models. If model is specified,
information is generated for that model only.

polyhedra

list

outputs model keyword, name and version number.

properties

outputs property list for model(s).

states

outputs possible state flags for model(s).

<lename(.txt)>
creates a file that contains POLYHEDRON face commands that will
recreate the block. This file can be called directly as a data file. This
is used to extract portions of a model (only visible blocks are printed).
This may also be used to reduce the amount of memory required by
a model in which many blocks were deleted during the construction
process. If not specified, the file is named POLY.TXT.

principal

min int max keyword . . .

lists the components and details of a symmetric 3D tensor input in
terms of its principal components and their directions. The first three
values are the minimum, intermediate and maximum principal stress
values, respectively. The following keywords specify the directions
of these principal components. At least two of the directions must be
specified; the third can be calculated from the other two. Directions
specified are corrected to form a valid orthonormal system, with priority given to the minimum principal stress direction. The following
keywords are available:

intermediate

direction
intermediate principal stress direction

maximum

direction
maximum principal stress direction

minimum

direction
minimum principal stress direction

The following keywords are available to specify the direction:

azimuthplunge azi plu

direction specified in terms of azimuth and plunge

3DEC Version 5.0

1 - 176
LIST

Command Reference

principal

dipdd
dipdd

dip dd
direction specified in terms of the dip and dip direction
of the plane normal to that direction

normal

xyz
direction specified in terms of a normal vector

trendplunge

tre plu
direction specified in terms of trend and plunge

property

pstress

keyword

anisotropic

anisotropic elastic properties

block

block properties

boundary

boundary properties

cable

cable properties

cyjoint

c-y joint properties (jcons = 3)

joint

joint properties (jcons = 1, 2)

reinforce

axial reinforcement properties

structure

liner properties

thermal

thermal properties

<along x1,y1,z1 x2,y2,z2 n> <lename(.prn)>

<at x,y,z>
<screen>
print feature designed for transferring 3DEC-calculated results to
other programs for additional processing. The print format is 7 digits
of precision. Each printout is headed by a single header line labeling
the data. Data for hidden blocks will not be included. If no file name is
specified, displacement plots will go to STRESS.PRN. Otherwise,
the output can be redirected to the console using the screen keyword.

range

<named>
lists all currently defined named ranges. If named is specified, a
detailed description of that named range will be printed.

3DEC Version 5.0

COMMAND REFERENCE
LIST
record

record

1 - 177

<keyword>
command record data. This is a record of all commands that have
been used to create the model.

rface

command

lists the commands stored in the record.

files

lists the imported files stored in the record, with a tag

indicating whether they currently exist or have been
modified since the record was created.

information

lists a summary of the number of lines and the number

of file entries stored in the record. This is the default.

<keyword>
faces that existed prior to zoning; same as face for rigid blocks

center

face centroids

information

normal, area, joint ID and sregion (this is the default

option)

vdistance

vertex addresses, distances, edges, adjacent edges and

adjacent faces

vertices

vertex addresses and positions

rlist

named ranges

scalar

<keyword> <range . . . >

lists the user-defined scalars that have been defined in the model. The
following keywords are available:

extra

i
lists the value of FISH extra variable index i in each
scalar.

group

<slot s>
lists the name of the group in slot s in each scalar.

value

lists the value of each scalar. This is the default.

security

summary of information stored in the hardware-lock key

serial

serial number assigned to the code by the hardware-lock key

3DEC Version 5.0

1 - 178
LIST

Command Reference

slave
slave

n
list of blocks that are slaved to block n

state

present state of global parameters

stress

<along x1,y1,z1 x2,y2,z2 n> <le name>

<at x,y,z>
<screen>
print feature designed for transferring 3DEC-calculated results to
other programs for additional processing. The print format is 7 digits
of precision. Each printout is headed by a single header line labeling
the data. For the stress keyword, x,y,z, sxx, sxy, sxz, syy, syz and szz
are printed. Data for hidden blocks will not be included. If no file
name is specified, stress plots will go to STRESS.PRN. Otherwise,
the output can be redirected to the console using the screen keyword.

structure

<keyword>
structural tunnel liner data (only available with the structural option
see Section 3 in Optional Features). Keywords are:

table

contacts

liner-rock contacts

elements

structural elements

nodes

structural nodes

properties

structural properties

<n>
data stored in table n; if n is omitted, all tables are printed

temp

gridpoint temperatures

tensor

<keyword> <range . . . >

lists the user-defined tensors that have been defined in the model. The
following keywords are available:

extra

i
lists the value of FISH extra variable index i in each
tensor.

group

<slot s>
lists the name of the group in slot s in each tensor.

3DEC Version 5.0

COMMAND REFERENCE
LIST
tensor
principal

1 - 179

principal

lists the value of each tensor in principal component

with direction format.

value

lists the value of each tensor in Cartesian component

format. This is the default.

thermal

model thermal settings

tknot

fluid-flow knot temperatures

trace

<labels>
outputs summary information about the current particle traces. If
labels is specified, then user-assigned labels are displayed instead of
positions.

unbalanced

rigid-block unbalanced forces

vector

<keyword> <range . . . >

lists the user-defined vectors that have been defined in the model. The
following keywords are available:

direction

lists the value of each in dip, dip direction, and magnitude format.

extra

i
lists the value of FISH extra variable index i in each
vector.

group

<slot s>
lists the name of the group in slot s in each vector.

magnitude

lists the value of each in unit vector and magnitude

format.

value

lists the value of each in vector format. This is the

default.

version

program-identifying information, including version number

vertex

block vertex data

wall

wall-typed blocks

water

water table definition

zdr

zone statistics

3DEC Version 5.0

1 - 180
LIST

Command Reference

zmaximum
zmaximum

<n rat>
volumes, aspect ratios and stress ratios for zones in deformable blocks.
Printouts can be screened by setting the optional parameters n and
rat:
For n =

zone

Zones with ratio of zone volume versus average zone

volume in the block < rat are printed.

Zones with ratio of maximum edge length versus the

cube root of zone volume > rat are printed (denoted
by drat).

Zones with ratio of circumscribed radius versus the

cube root of zone volume > rat are printed (denoted
by sphrat).

Zones with ratio of circumscribed radius versus inscribed radius > rat are printed (denoted by zdp).

<keyword>

location

gridpoint addresses, centroid coordinates and volume

(this is the default option)

model

zone model name

extensive information about one zone indicated by address n

ppressure

zone pore pressure (average gridpoint pore-pressure)

principal

zone principal stresses and orientations

state

zone centroid, material number, constitutive number

and plasticity state number. The plasticity state number is the sum of any state codes that may apply. The
state codes for zones are as follows:
0
1
2
4
8

stress

3DEC Version 5.0

elastic
matrix shear currently at yield
matrix tension currently at yield
matrix shear yield in past
matrix tension yield in past

zone stresses, tensors and plasticity state indicators

COMMAND REFERENCE
LIST
zone
varz

varz

1 - 181

property
lists values of properties for zone models. This applies
only to zones containing extended-zone constitutive
models (requires the user-defined model option).

3DEC Version 5.0

1 - 182
LIST

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
LOAD

LOAD

1 - 183

keyword
is a general interface for loading user-defined dynamic capability to the code.

function

name
attempts to load a user-defined FISH intrinsic named name. The
actual DLL should be named fishname001.dll. This function will
thereafter appear in the list of FISH intrinsics, and can be called in
the same way as a built-in FISH intrinsic. The FISH intrinsic remains
available until program shutdown.

jmodel

name
loads a user-defined joint constitutive model (jmodel). The dynamic
library should have the name jmodelname001.dll.

model

name
loads a user-defined constitutive model. The dynamic library should
have the name modelname001.dll.

3DEC Version 5.0

1 - 184
LOAD

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
MAIL

MAIL

1 - 185

keyword
Command-line control of the email facility is built into 3DEC. This allows data files
and FISH functions to send notification emails upon completion of notable tasks.
The following keywords are available:

add

keyword

attach

filename
adds an attachment to the message.

to

address
adds a to recipient to a message.

cc

address
adds a cc recipient to a message.

bcc

address
adds a bcc recipient to a message.

clear

clears the current mail variables, including body, recipient list and
attachment list.

remove

keyword

attach

filename
removes an attachment from the message.

to

address
removes a to recipient from the message.

cc

address
removes a cc recipient from the message.

bcc

address
removes a bcc recipient from the message.

send

validates the mail settings, composes the message and sends the message.

3DEC Version 5.0

1 - 186
MAIL

Command Reference

set
set

keyword

account

name
sets the user account name in the SMTP settings. For
example, me@mycompany.com.

body

keyword

file

filename
sets the message body by importing filename.

string

string
sets the message body as a string.

domain

name
sets the company domain name. For example,
smtp.mycompany.com or 192.197.32.6.

host

name
sets the SMTP host name. For example,
mycompany.com.

password

name
sets the user password for the email account.

subject

name
sets the message subject.

3DEC Version 5.0

COMMAND REFERENCE
MARK

MARK

1 - 187

<keyword> <range . . . >

Blocks and block faces within a specified range can be marked by a region identification number. Note that only visible blocks are marked. The following keywords
apply:

region

n
All blocks with centroids lying within the optional range are marked.
Blocks are marked by a region number n. A marked block does not
influence the calculations in any way, but serves to delimit a region for
recognition by the CHANGE, DELETE, EXCAVATE and FILL commands.
Note that blocks are also assigned region numbers with the TUNNEL
command. Use the LIST block command to obtain a list of current
block region numbers.

sregion

n
All faces for blocks with centroids lying within the optional range are
marked.

3DEC Version 5.0

1 - 188
MARK

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
MSCALE

MSCALE

1 - 189

off

on <zcmass bcmass>
part dt
maximum ratio
Mass (density) scaling for all blocks is turned on to speed convergence of static
problems involving very nonuniform blocks or zone meshes, or very nonuniform
elastic properties. For rigid blocks, the user must supply a value for bcmass. (A
dummy place for zcmass is therefore required.) For deformable blocks, zcmass and
bcmass need not be supplied. If no value is supplied, the code will perform density
scaling automatically, using average zone and block masses. Average zone and block
masses generally lead to satisfactory solutions.
Values for minimum, average and maximum zone and block masses can be found
using the LIST maxima command. Mass scaling is always on for the default (static)
calculation mode. Mass scaling may only be turned off for the dynamic analysis
option (see Section 2 in Optional Features). Mass scaling must be turned off for
correct results during the dynamic calculation.
In a dynamic analysis, global scaling should not be used. For complex jointed systems, small block zones may be created during the automatic meshing procedure.
The small zones require small timesteps for numerical stability of the explicit algorithm. This makes some dynamic solutions extremely time-consuming. However,
since these zones may be very small, with very small masses, it is possible to introduce some density scaling only for these zones in such a way that the change of
the system inertia is negligible. This is referred to as partial density scaling. Partial
density scaling was implemented in 3DEC in such a way that the user controls the
amount of scaling to be introduced. Given the timestep calculated by the code, the
user specifies the desired timestep with the command MSCALE part dt. This command
specifies that only the amount of density scaling required to achieve the timestep dt is
to be applied to the system. When a CYCLE command is given, a message indicating
the number of gridpoint masses that were scaled, and the amount of additional mass
introduced, is printed. The maximum keyword specifies the maximum ratio of the
maximum to minimum gridpoint mass scaling factors.

3DEC Version 5.0

1 - 190
MSCALE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
NEW

NEW

1 - 191

clears most program state information, and allows one to begin a new problem
without leaving 3DEC.
The log file, echo mode and random-number generator seed (see the commands
SET{log, echo, random}) are unaffected by the NEW command. The log file remains
open (if open already), the log file name and echo mode on/off status are not changed,
and the random-number generator seed (used by the GENERATE command) is not
reset when a NEW command is given. All other program-state information (including
any defined FISH functions and variables, histories, tables and plot views) is lost.
Such information can be written to a file via the SAVE command for subsequent
recovery via the RESTORE command. Alternatively, a FISH function can write data
to a file (see Section 2.5.2.7 in the FISH volume), and a different FISH function
(created after the NEW command is executed) can read back that data.

3DEC Version 5.0

1 - 192
NEW

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
PAUSE

PAUSE

1 - 193

<key>
<t>
This command pauses processing of a data file. It can be invoked in one of three
ways:
If no options are specified, then 3DEC will stop processing the data file at the point
where the PAUSE command was encountered, and the program will enter interactivecommand mode, in which commands can be typed on the keyboard (e.g., PLOT balls).
When the CONTINUE command is typed, 3DEC will resume processing the data file.
If the optional keyword key is specified, then 3DEC will stop processing the data file
at the point where the PAUSE command was encountered, and the program will wait
for the user to press a key. When any key (except <Esc>) is pressed, 3DEC will
resume processing the data file. If <Esc> is pressed, 3DEC will abort all processing
(including the processing of any data files that had been PAUSEd), and the program
will enter interactive-command mode.
If the optional variable t is specified, 3DEC will stop processing the data file for
t seconds and then resume processing of the data file. If <Esc> is pressed, then
3DEC will abort all processing (including the processing of any data files that had
been PAUSEd), and the program will enter interactive-command mode. If the space
bar is pressed, 3DEC will continue processing the data file.

3DEC Version 5.0

1 - 194
PAUSE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
PFIX

PFIX

1 - 195

pressure p <range>
This command allows fluid pressure to be specified at joint sub-contacts for rigid
or deformable blocks. The specified fluid pressures do not change until a different
PFIX command is executed or the sub-contact is deleted. Each PFIX command adds
pressure into an incremental fluid force applied at the sub-contact.
Positive pressures cause the joint to expand. In order to remove the pressure at a
contact, apply the negative value of the pressure with the PFIX command. Use the
LIST contact pressure command for current values of fluid pressures in the model.
Use the LIST contact stress command for current values of the effective normal
stress at sub-contacts in the model.
The fluid pressure is fixed at the sub-contacts lying within the optional range.
If the range is omitted, the command is assumed to apply to all sub-contacts.

3DEC Version 5.0

1 - 196
PFIX

3DEC Version 5.0

Command Reference

COMMAND REFERENCE

1 - 197

POINT
POINT

x y z type n strength s <tstart ts>

A heat point source of initial strength s is placed at point x,y,z, which need not be
within the blocks defined by 3DEC. The source is of type n (with components and
decay constants defined by the SOURCE command) and starts at the time ts. The start
time defaults to zero if not specified, but the type and strength must be specified.
The type and strength may be specified in any order (available only with thermal
option see Section 1 in Optional Features).

3DEC Version 5.0

1 - 198

POINT

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
POLYHEDRON

1 - 199

POLYHEDRON keyword . . .
creates a single rigid polyhedron defining the original boundary of the model. The
polyhedron has a material number n, a constitutive number m, and a region number
o; defaults are n = 1, m = 1, and o = 0. A single polyhedron may be created in two
ways: either by specifying the faces of the polyhedron with the face keyword, or by
defining a bounding region (with the brick, prism or tunnel keyword). More than one
POLYHEDRON command may be given per run, but all polyhedra must be convex.

constitutive

m
assigns constitutive model to newly created blocks.

face

<id id> x1 y1 z1 x2 y2 z2 x3 y3 z3 . . .
<joint jnt>
The polyhedron is formed by planar faces with the face keyword,
where the coordinates (x1,y1,z1), (x2,y2,z2), etc. define the boundary
of the face. The vertices must be entered in clockwise order, looking
at the block face from outside the block. Multiple face keywords must
be used to define a single polyhedron in a single command. Note that
the line continuation symbol ... may be used. There is no limit (other
than system memory) to the length of a line, or to the number of lines
that can be continued.

group

str <slot i>

string containing the group name for all blocks created by this command. If a slot is not specified, slot 1 is assumed.

material

n
assigns material model number to newly created blocks.

region

o
assigns region number to newly created blocks.

wall

blocks will be wall-type blocks

Additional model-building keywords are:

brick

xl xu yl yu zl zu
A regular six-sided brick-shaped region can be created with the
brick keyword. The region extends from coordinates xl to xu, yl to
yu and zl to zu.

3DEC Version 5.0

1 - 200
POLYHEDRON copy

copy

Command Reference

<keyword>
The copy keyword is used to make a copy of an existing rigid block
(or block assemblage) at another location. This keyword only applies
to rigid blocks. It is up to the user to make certain that the copied
block does not intersect with any existing blocks in the model. This
command may be used after cycling has occurred. If the block specified is a block in a joined group, the entire group is copied and joined.
This allows complex objects to be copied. Typically, the block copied
will be a hidden block that is fixed in space and only used as a master
for the new copied blocks.

new block will be fixed in space

free

new block will be free to move

hide

new block will be hidden

index

i
index of block to be copied

shift

x,y,z
relative displacement of copied block from the position
of the original block

show
cube

new block will be visible

is a way of generating a region of a model based on a user-defined

outline. The command first generates a region of cubic blocks. The
blocks are then cut based on the outline. The outline is a text file
containing the x,y,z coordinates. The outline should be contiguous.
The utility program PGEN can used to edit DXF files from AutoCAD
to make a contiguous outline file. The POLYHEDRON cube command
is intended to be an alternative to use of the PGEN geometry generator.
Under certain conditions, the blocks generated by PGEN cannot be cut
(or zoned, if the cut is successful). This is less likely to happen with
the POLYHEDRON cube blocks. The keywords are used to define the
orientation of the cubed region. The areas inside and outside of the
outline are assigned different region numbers. As each cube may only
be cut once by the outline, the size of the cubes defines the resolution
of the geometry. The keywords are:

box

ratio
specifies that an outer box should be cut to provide a
transition boundary for zoning. The size of the outer
box is controlled by ratio.

3DEC Version 5.0

COMMAND REFERENCE
POLYHEDRON cube
ddirection

ddirection

1 - 201

v
defines the dip direction of the control plane for the
cubic region. All cubes will be formed parallel to and
below the control plane.

dip

v
defines the dip of the control plane for the cubic region.
All cubes will be formed parallel to and below the
control plane.

dxf

specifies that a DXF format file should be used for

the outline. Note that the data in the DXF file should
be contiguous (file name is controlled by SET dxf lename = name). Normally the data are extracted from a
text file. The file name is controlled by the SET overlay lename = name command. The default file name
for DXF is 3DEC.DXF. The default name for the
overlay file is OVERLAY.TXT.

id

n
specifies the joint ID number for all cuts.

inside

n
specifies the inner region number. (The default = 1.)

join

specifies that the inner and outer regions should be

joined after cutting.

number

nx,ny,nz
specifies the number of cubes in the relative x-, y- and
z-directions.

outside

n
specifies the outer region number. (The default = 2.)

rotate

v
specifies the in-plane rotation of the control plane.

spacing

x <y <z>>
specifies the size of the cubes. If only x is specified,
cubes will be generated. If y and z are specified, the
blocks will be bricks.

3DEC Version 5.0

1 - 202
POLYHEDRON cube

Command Reference

top
top

x,y,z
defines the location in space of the center of the control
plane.

drum

x1,y1,z1 x2,y2,z2 r1 r2 nedge

creates a drum-shaped block with face center at x1,y1,z1 and x2,y2,z2.
The radii of the two faces are r1 and r2. nedge specifies the number
of edges used to define the sides of the drum.

A prism-shaped polyhedron can be created using the prism keyword.

prism

keyword
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 keywords are:

x1,y1,z1 x2,y2,z2 x3,y3,z3. . .

specifies coordinates for face a.

x1,y1,z1 x2,y2,z2 x3,y3,z3. . .

specifies coordinates for face b.

An entire model may be created at once by using the tunnel keyword.

tunnel

<keyword. . . >
This command generates a circular tunnel model with intact inner and
outer blocks. The size of the blocks increases radially outward from
the center. The user can control how many blocks are used to create
the model. The keywords are:

dd

a
is the dip direction of tunnel axis. (The default = 0.)

dip

a
is the dip of tunnel axis. (The default = 0.)

3DEC Version 5.0

COMMAND REFERENCE
POLYHEDRON tunnel
length

length

1 - 203

ll lu
is the location of the tunnel relative to the tunnel origin
along the dip and dip direction. The length of the
tunnel will be lu - ll along the tunnel center. (The
default is ll = 10, lu = 10.0.)

nrblocks

n
is the number of annular blocks to generate radially
from the tunnel boundary to the edge of the model.
(The default = 1.)

ntblocks

n
is the number of blocks to generate in each 45-degree
segment of the tunnel circumference. The total for the
circumference will be 8 n. (The default = 1.)

nxblocks

n
is the number of blocks to generate along the tunnel
axis. (The default = 1.)

origin

xyz
is the origin of the center of the tunnel. The tunnel axis
will pass through this point. (The default = 0,0,0.)

radius

a
is the radius of the tunnel. (The default = 1.0.)

ratradius

a
is the number of tunnel radii from tunnel boundary to
edge of the model a must be greater than 1.0. (The
default = 4.0.)

rmultiply

a
is the multiplier for size of blocks in radial direction
out from center. It is used to grade block sizes out
from center. (The default = 1.0.)

3DEC Version 5.0

1 - 204
POLYHEDRON

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
PROPERTY

PROPERTY

1 - 205

material n keyword v <keyword v. . . >

or

PROPERTY

jmat n keyword v <keyword v. . . >

The first parameter, n, must be the specification of the material number. Block
and joint properties are assigned to a material number by the PROPERTY command.
Material numbers are assigned to blocks and joints in the model by the CHANGE
command. Note that both block properties and joint properties can be assigned to
the same material number. Material properties, v, are defined for material number
n. Each property must be specified as a positive value. Note that properties for the
extended constitutive models (DLLs) and user-defined models are set via the ZONE
command. For fully deformable blocks, either the PROPERTY material=n density=v
or a ZONE density command may be used. Once the ZONE density command has
been used, changes in the density for zones must be made using the ZONE density
command. In other words, the user cannot mix command types for the same zone. If a
FISH fmem keyword is used to change density in a zone, then a dummy PROPERTY
material=n density=v command must be issued to force 3DEC to recalculate the
gridpoint masses. Property keywords for the available constitutive (see CHANGE
command) models follow:
Joint Models
Coulomb Slip Model (jcons 1,2)
(1)
(2)
(3)

amax
ares
azero

(4)
(5)
(6)
(7)
(8)
(9)
(10)
(11)
(12)
(13)

jcohesion
jdilation
jfriction
jkn
jks
jtensile
res cohesion
res friction
res tension
zdilation

maximum allowable joint hydraulic aperture in flow rate calculation

minimum allowable joint hydraulic aperture
hydraulic aperture at zero normal stress. If the nodisplacement
keyword is used with the INSITU command, then azero is
the initial hydraulic aperture at the applied normal stress.
joint cohesion
joint dilation
joint friction (total friction, including dilatancy component)
joint normal stiffness
joint shear stiffness
joint tensile strength
joint residual cohesion (used after slip has occurred) jcons 1 only
joint residual friction (used after slip has occurred) jcons 1 only
joint residual tension (used after slip has occurred)
shear displacement for zero dilation

See Section 1.2.2.4 in Theory and Background for details.

For the elastic joint model (jcons 7), only jkn and jks are required.

3DEC Version 5.0

1 - 206
PROPERTY

Command Reference

Continuously Yielding Joint Model (jcons 3)

(1)
(2)
(3)

amax
ares
azero

(4)

en

(5)

es

(6)
(7)
(8)
(9)
(10)

if

jfriction
jkn
jks
maxkn

(11) maxks
(12) minkn
(13) minks

(14) r

maximum allowable joint hydraulic aperture

minimum allowable joint hydraulic aperture
hydraulic aperture at zero normal stress. If the nodisplacement
keyword is used with the INSITU command, then azero is
the initial hydraulic aperture at the applied normal stress.
exponent of joint elastic normal stiffness. Specifying this
parameter permits joint normal stiffness to be a function
of current normal stress i.e.,
kn := kn(nen )
where := means replaced by, and n
is the current normal stiffness.
exponent of joint elastic shear stiffness. Use of this
parameter is identical to that discussed previously i.e.,
ks := ks(nes ).
joint initial bounding friction angle
joint friction (total friction, including dilatancy component)
joint normal stiffness
joint shear stiffness
maximum value of joint normal stiffness
(default is maxkn = kn)
maximum value of joint shear stiffness
(default is maxks = ks)
minimum value of joint normal stiffness
(default is minkn = kn)
minimum value of joint shear stiffness
(default is minks = ks)
If neither minkn nor maxkn is defined, joint normal stiffness
will be constant (i.e., exponent en will have no effect).
Joint shear stiffness is defined in a similar way.
Timestep calculations for jcons = 3 joints are based on the
values of maxkn and maxks. In general, it will not be
necessary to further reduce the timestep for numerical stability.
The user should avoid very large values for maxkn or maxks,
as their use might result in very small timesteps.
joint roughness parameter

See Section 2 in Constitutive Models for details.

3DEC Version 5.0

COMMAND REFERENCE
PROPERTY

1 - 207

Block Models
Isotropic Elastic (cons 1)
The user may specify either bulk and shear modulus or Youngs modulus and Poissons ratio.
(1)
(2)
(3)
(4)
(5)
(6)
(7)
(8)

bulk (or K)
conductivity
density
pratio
shear (or G)
spec heat
thexp
ymod

block bulk modulus

thermal conductivity
density
Poissons ratio
shear modulus
specific heat
thermal expansion coefficient
Youngs modulus

See Section 1.5.1 in Constitutive Models for details.

3DEC Version 5.0

1 - 208
PROPERTY

Command Reference

Anisotropic Elastic (cons 3)

(1)

antable*

(2)
(3)
(4)
(5)
(6)
(7)
(8)
(9)
(10)
(11)
(12)
(13)
(14)

conductivity
dd
dip
e1
e2
e3
g12
g13
g23
nu12
nu13
nu23
rot

(15) spec heat

(16) thexp
(17) transv

table number for user-defined elasticity matrix

(if this keyword is given, none of the previous
properties will be used)
thermal conductivity
dip-direction of plane 12
dip of plane 12
Youngs modulus in direction 1
Youngs modulus in direction 2
Youngs modulus in direction 3
shear modulus relating directions 1 and 2
shear modulus relating directions 1 and 3
shear modulus relating directions 2 and 3
Poissons ratio 12
Poissons ratio 13
Poissons ratio 23
angle of direction 1 with dip-direction vector
(measured counterclockwise from dd vector)
specific heat
thermal expansion coefficient
defines material as transversely isotropic, with direction 3
as the axis of symmetry

* The coefficients, given with the antable keyword, are assigned the following numbers:
sxx 1 2 3 4 5 6
exx
syy
7 8 9 10 11 eyy
szz
12 13 14 15 ezz
sxy
16 17 18 exy
sxz
19 20 exz
syz
21 eyz
See Section 1.5.3 in Constitutive Models for details.

3DEC Version 5.0

COMMAND REFERENCE
PROPERTY

1 - 209

Mohr-Coulomb (cons 2)
(1)
(2)
(3)
(4)
(5)
(6)
(7)
(8)
(9)
(10)
(11)
(12)

bcohesion
bdilation (or psi)
bfriction (or phi)
btension
bulk (or K)
conductivity
density
pratio
shear (or G)
spec heat
thexp
ymod

cohesion
dilation angle
friction angle
tensile strength
bulk modulus
thermal conductivity
density
Poissons ratio
shear modulus
specific heat
thermal expansion coefficient
Youngs modulus

See Section 1.6.2 in Constitutive Models for details.

3DEC Version 5.0

1 - 210
PROPERTY

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
QUIT

QUIT

1 - 211

stops program execution and returns control to the operating system. All information
generated during the modeling session will be lost unless a SAVE command is issued
prior to the QUIT command.
The STOP command is a synonym for this command.

3DEC Version 5.0

1 - 212
QUIT

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
RANGE

RANGE

1 - 213

name rname . . .
A named range, of name rname, is created. A list of range elements must follow
rname. Once a range has been named, it can be specified in place of a range element in
any command that uses the range logic (see Section 1.1.3). The command LIST range
lists the existing named ranges and provides detailed information about particular
named ranges.

3DEC Version 5.0

1 - 214
RANGE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
REMOVE

REMOVE

1 - 215

<range . . . >
Blocks with centroids in the range defined by the range phrase are removed from
calculation, but retained for plotting excavated regions. If no range is specified, all
visible blocks are removed. Blocks which are removed cannot be backfilled. The
zones and contacts associated with removed blocks are not included in the calculation
cycle. In contrast, excavated blocks remain part of the calculation cycle as a null
block, and with the intention that they will be backfilled. If you intend to backfill,
use the EXCAVATE command. If you do not need to plot the removed blocks, use the
DELETE command.
The range can be given in one range type, or combinations of range types (described
in Section 1.1.3).
Removed blocks can be seen with the PLOT block excavate command.

3DEC Version 5.0

1 - 216
REMOVE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
RESET

RESET

1 - 217

keyword <keyword. . . >

Certain variables are reset according to the following keywords:

damp

The adaptive global damping parameter is reset to initial (high) value.

displacement All displacements of gridpoints (vertices) of deformable blocks are

set to zero, but gridpoint coordinates are not affected. This command
does not alter the physics of the problem being modeled because
displacements are not used in any calculations.

dxf

clears settings for DXF file plotting.

history

All histories are cleared. Histories must be respecified as required.

jdisplacement All relative displacements (shear and normal) of contacts are set to
zero. This has no effect on the model results, and is useful for identifying effects of incremental changes.

jenergy

Joint energy terms are set to zero.

jstress

All joint stresses (shear and normal) are set to zero.

stress

Zone stresses are set to zero.

time

Problem time is set to zero. This has no effect on the problem being modeled, but is useful for input histories and for convenience in
presenting results.

velocity

Velocities of all vertices are set to zero.

3DEC Version 5.0

1 - 218
RESET

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
RESTORE

RESTORE

1 - 219

<fname>
restores all program-state information (that had been previously saved with the SAVE
command) from the file fname. If fname does not contain an extension, then the
extension is set equal to .3dsav. The path to the save file can be included as part
of fname.
The log- and plot-files and echo mode (see the commands SET{log,echo}) are unaffected by the RESTORE command. The files remain open (if open already), the
file names are not changed, and the echo mode on/off status is not changed when
a RESTORE command is given. All other program-state information (including any
defined FISH functions and variables, histories, tables and plot views) is lost and is
replaced by the information contained in the file fname.

3DEC Version 5.0

1 - 220
RESTORE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
RETURN

RETURN

1 - 221

returns program control from batch mode to interactive-command mode (if a single
level of calling was used), or to the calling file if multiple levels of calls have been
nested. The RETURN command is implicitly assumed to be present at the end of any
data file.
The RETURN command will also cause an exit from a COMMAND section in a FISH
function.

3DEC Version 5.0

1 - 222
RETURN

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
SAVE

SAVE

1 - 223

<fname>
saves all program-state information (including any defined FISH functions and variables, histories, tables and plot views) to the file fname. If fname does not contain
an extension, then the extension is set equal to .3dsav.
The program state can be recovered via the RESTORE command.

3DEC Version 5.0

1 - 224
SAVE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
SCALAR

SCALAR

1 - 225

keyword . . .
Scalars are an internal list of user-defined objects that have a position and a value
associated with them. They may also have groups and FISH values assigned to them.

add

x y z keyword . . .
adds a single scalar at location (x,y,z). The following keywords are
available:

extra

param <index i>

param can be any FISH parameter, including a vector
delimited by parentheses or a FISH fragment delimited
by brackets. If an extra index is not specified, each
extra keyword assigns extra data to subsequent indices
(i.e., extra 1.0 extra fred assigns 1.0 to extra index
1 and fred to index 2).

group

name <slot s>

If a groups slot is not specified, each group keyword
assigns a group to a subsequent slot (i.e., group fred
group george assigns fred to slot 1 and george to
slot 2).

value

export

specifies the value associated with the scalar.

filename(.scalar) <binary> <range . . . >

exports all scalars in the assigned range to a file. A text file is created
unless the binary keyword is specified. Any previous file is deleted.
The file format used is documented fully in Section 1.5.

import

filename(.scalar) <group str <slot i>>

imports scalar data from the file specified. The file format (text or binary) is determined by opening the file and looking for the appropriate
header. If the proper header is not found, an error is indicated and no
data are imported. If the group keyword is specified, imported scalars
are assigned group name str in slot i (which is 1, by default). This
group assignment overrides any in the import file. The file format
used is documented fully in Section 1.5.

remove

<range . . . >
removes (deletes) all scalars falling into the specified range. If a range
is not specified, all scalars are deleted.

3DEC Version 5.0

1 - 226
SCALAR

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
SEEK

SEEK

1 - 227

<ffield> <range . . . >

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 GENERATE command. Only visible blocks
can be joined by the JOIN command. 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 feld is given, then only blocks in
the free-field boundary are hidden.

3DEC Version 5.0

1 - 228
SEEK

3DEC Version 5.0

Command Reference

COMMAND REFERENCE

1 - 229

SET
SET

keyword
This command sets global condition variables which remain constant during a run.
The parameters can be divided into five categories: program control, model properties, creep-specific properties, fluid-specific properties and thermal-specific properties. The keywords used in these categories are summarized in Table 1.5:

Table 1.5

Summary of SET keywords

program control

model properties

creep

fluid

thermal

case sensitivity
cust1
cust2
deterministic
directory
echo
sh
hist rep
join contact
jplane
log
logle
ncycle
notice
nstep
pagination
plotinterval
seed
warning

arcmin
atol
ctol
cy
damp
dt
dxf
dynamic
edge
energy
htol
jcondf
jmatdf
jmtable
jointid
max cells
mech
min ang
nodal

crdt
creeptime
fobl
fobu
latency
lmul
maxdt
mindt
umul

aunb
convection
crack ow
datum
fastow
ow
fobu
fpcoef
gasow
munb
ngw
nmech
nup uid time

convection
mechanical
nther
th implicit
th numerical
th scale
th store matrix
th time
thcouple
thdt
thermal
thtolerance

nucp
nucx
nupdt
nupface
overlay
processors
random
rhs
sdel
skip join up
small
spface
tension
time
tunnel axis
zvol del
zvol nodal
zvol ratio

3DEC Version 5.0

1 - 230

Command Reference

SET
arcmin

value
sets value of minimum contact area (default = 1% of average face
area).

atol

value
sets general tolerance for model; used for:
(1) minimum distance between gridpoints;
(2) minimum area (atol*atol) of sub-contacts;
(3) tolerance to link gridpoints of joined blocks; and
(4) tolerance to select vertices close to the command plane.
(The default is 0.12% of the average model dimensions in x, y and z.)

aunb

value
is the limit for average unbalanced volume in fast-flow calculations.
This limit is used in a fully coupled calculation to stop mechanical
iterations within a single flow timestep before reaching nmech.

case sensitivity off

on
During command processing, case sensitivity is off by default. To
make 3DEC case-sensitive, set case sensitivity to on. Note that when
case-sensitivity is on, all commands, keywords and predefined FISH
functions and variables are treated as lowercase.

convection

off
on
turns convection calculations on and off during fluid/thermal coupled
calculations.

crack ow

off
on
SET crack ow on ensures that flow only occurs within portions of
flow planes where the associated sub-contacts have failed. When
crack ow is off, flow will occur in all planes. The default is off.

3DEC Version 5.0

COMMAND REFERENCE
SET
crdt

crdt

1 - 231

<value>
<auto>
sets the current creep timestep (see SET creeptime). If the keyword
auto is specified, the timestep will be automatically adjusted. The
timestep will be increased by the factor umul if the maximum outof-balance force stays below fobl for latency timesteps. The timestep
will be reduced by the factor lmul if the maximum out-of-balance
force stays above fobu for latency timesteps. The automatic timestep
is bounded by the values maxdt and mindt. The creep and mechanical
timesteps are not coupled. However, the creep time will be incremented by one creep timestep for each mechanical step taken. The
mechanical time is independent of the creep time, and is only used
to maintain mechanical equilibrium. The thermal solution is analytic
(and does not consider excavations). The SET thcouple command can
be used to interlace creep steps with thermal solutions. Setting crdt
to 0 turns creep off. The default value for the creep timestep is 0.

creeptime

value
sets the current creep time. The initial creep time is 0.

ctol

value
sets contact distance tolerance. Contacts are deleted if the distance
from the common plane is greater than value, or added if the block is
within value of the common plane.

cust1

string
sets the first line of customer information, which is displayed in the
lower-left corner of all plot views. If this string contains spaces, then
it must be enclosed by single quotes (as in string), in which case any
occurrence of a single quote or backslash character must be preceded
by a backslash character.

cust2

string
sets the second line of customer information, which is displayed in
the lower-left corner of all plot views. If this string contains spaces,
then it must be enclosed by single quotes (as in string), in which
case any occurrence of a single quote or backslash character must be
preceded by a backslash character.

3DEC Version 5.0

1 - 232

SET

Command Reference

cy
cy

n
allows the user to activate optional features of the continuously yielding joint model:

damp

normal model

discontinuous yielding goes directly to residual

strength

elastic, no failure

keyword
This is a synonym for the DAMPING command.

datum

z value used in hydraulic head plots

deterministic off
on
The addition of multi-threaded calculations in 3DEC has created a
situation where the summation of various loads to be applied to gridpoints and corners may occur in an unknown order. The order of
calculations may give rise to minute differences in the numeric roundoff. Over many thousands or millions of cycles, these differences may
accumulate to the point where the numeric result of a 3DEC model
run may be slightly different each time it is rerun. For this reason,
some of the calculations in 3DEC have been separated out of the
multi-threading loops such that the result is deterministic. In other
words, the randomness has been removed from the calculation order.
This does not imply that the result is any more or less correct, it just
means that it is numerically repeatable. As a result, the cycle calculations consume a little more time. If deterministic is turned off, this
additional time is not used. The default is deterministic = on.

directory

string
sets the current working directory to string. If this string contains
spaces, then it must be enclosed by single quotes (as in dir), in which
case any single backslash characters must be given as two backslash
characters in succession. To see the current working directory, try
SYSTEM DIR.

dt

value
user-defined timestep (use with caution)

3DEC Version 5.0

COMMAND REFERENCE

SET

1 - 233

dxf
dxf

lename = str
sets name of file used as input for the POLYHEDRON cube command.
The default is 3dec.dxf.

dynamic

off
on
turns dynamic analysis setting on; sets auto damping and mass scaling
off. This keyword can only be used if CONFIG dynamic has been
specified.

echo

keyword

le

off
on
turns the echo file recording on or off. Commands sent
to the command processor (and not the responses, as
in a log file) are recorded to a file. If the file name is
not specified, it defaults to 3DEC.ECHO.

name

fname(.echo)
sets the echo file name.

off

edge

on

controls the echo facility, which prints to the screen

and writes each line sent to the command processor
to the log file (if the logging facility is on see the
SET log command). By default, echo is on. The NEW
command does not affect the status of the echo facility.
(When CALLing a large data file from the interactivecommand mode, one may wish to temporarily turn off
the echo facility to prevent all of the information in the
data file from scrolling across the screen.)

suppress

suppresses echo output for the current input source,

such as the current data file or the current
COMMAND/ENDCOMMAND block.

value
The minimum edge length for a polygon is set to value. If value is too
large compared to the block size, then concave shapes may result. If
value is too small, timesteps for deformable blocks can be too small.
The default is 0.12% of the average problem dimension.

3DEC Version 5.0

1 - 234

SET

Command Reference

energy
energy

off
on
turns energy summation on and off. All energy calculations are incremental, except strain energies from the INSITU stress command (if
it is used with energy on).

fastow

off
on
turns fast flow calculations for incompressible fluid flow off and on.
(The default is off for compressible fluid-flow.) Do not set fast flow
on for fluid flow-only calculations. (Default is off.) (Also see SET
aunb, SET munb and SET fpcoef.)

sh

keyword

autocreate

off
on
is on by default. If autocreate is on and an unrecognized name is found while parsing a FISH function, a
global symbol is automatically created. If autocreate
is off, then global symbols must be explicitly declared
using the FISH keyword global.

call

n fish
allows one to add the FISH function fish from the list
of FISH functions associated with fishcall ID n. The
fishcall mechanism is described in Section 2.4.6 in the
FISH volume.

case sensitivity off

on
Case sensitivity during FISH parsing is off by default.
To make FISH case-sensitive, set sh case sensitivity
on. Note that when case sensitivity is on, all FISH
intrinsics are defined as lowercase.

remove

n fish
removes a FISH function from the list of functions
associated with fishcall ID n.

3DEC Version 5.0

COMMAND REFERENCE

SET

sh

1 - 235

safe conv
safe conversion off
on
controls command-processor FISH safe mode (see
Example 2.1 in the FISH volume). When safe mode
is on, all FISH variables that will be passed to the
command processor as part of a command line must
be prefixed with the special character @. This special
character unambiguously identifies these variables as
FISH symbols. The special characters are ignored
when safe mode is off. By default, safe mode is on.

ow

off
on
turns the fluid-flow calculations off and on. The default is off.

fobl

value
sets the limit for the maximum out-of-balance force that will allow
the timestep in creep calculations to be increased (requires the SET
crdt auto command). The default value is 1 104 .

fobu

value
This parameter is used for controlling creep timestep and fracture
fluid-flow stepping. For creep, this sets the limit for the maximum
out-of-balance force at which the timestep in creep calculations may
be decreased (requires the SET crdt auto command). The default value
is 1 105 .

fpcoef

value
is the relaxation parameter used in fast flow calculations. fpcoef < 1
should provide a stable solution. The default is 0.1.

gasow

off
on
controls gas-flow logic

hist rep

n
is the sampling interval for the history mechanism (see the HISTORY
command). By default, hist rep is equal to 10. The sampling interval
may also be set via the HISTORY nstep command.

3DEC Version 5.0

1 - 236

SET

Command Reference

htol
htol

value
is the tolerance used in cutting logic to determine whether nonplanar
cuts are to be made. Tolerance is a multiple of atol (default value is
0.1).

jcondf

n
is the default constitutive relation for new contacts (created after cycle
1). If jcondf is not specified, it is assumed equal to 1.

jmatdf

n
is the default material number for new contacts (created after cycle
1). If jmatdf is not specified, it is assumed to be material 1.

jmtable

mat 1 mat 2 jmat jcons

defines a table of property and constitutive models for contacts. mat 1
and mat 2 are property numbers of blocks in contact. jmat and jcons
are the material and constitutive models that will be assigned to the
contact. This is an alternative to jcondf and jmatdf.

join contact

off
on
controls use of alternate contact-based join logic. The default is off.

jointid

n
sets the starting number for the joint plane ID numbers.

jplane

off
on
controls the calculation of data structures used to generate the data
structures used for plotting joint planes. The data structure takes time
to calculate and uses a lot of memory. Eliminating this calculation
affects plotting only; it does not affect any mechanical calculations.

latency

n
controls the number of creep timesteps that the maximum out-ofbalance force must be above or below the set limits (fobl or fobu)
before the timestep is changed. This prevents spikes from changing
the timestep (requires the SET crdt auto command). The default value
is 100.

3DEC Version 5.0

COMMAND REFERENCE
SET
lmul

lmul

1 - 237

value
sets the multiplication factor used to increase the creep timestep if
the maximum out-of-balance force drops below fobl for more than
latency timesteps (requires SET crdt auto).

log

off <create, truncate, append>

on
controls the logging facility that writes each line sent to the command
processor (if the echo facility is on see the SET echo command) and
all program responses to a log file, thereby creating a detailed record
of a modeling session. By default, log is off.
To activate this facility, set log to on, which opens the text file lfname
in the current working directory. If lfname has not been specified with
the SET logle command, then lfname is set equal to 3DEC.LOG.
To disable this facility, set log to off, which halts further writing of
information to the log file but keeps the log file open for possible
reactivation via the SET log on command. The log file is closed either
when the program ends (via the QUIT, STOP or EXIT command), or
when a new log file name is specified with the SET logle command.
The NEW command does not affect the status of the logging facility.
If no keyword follows on, then the behavior is as follows. If lfname
does not exist, then it is created and opened for writing. If lfname
already exists and the program is in interactive-command mode, then a
prompt is displayed to determine whether the user wishes to overwrite
or append to the existing file; if lfname already exists and the program
is in batch mode, then additional information will be appended to the
file. Alternatively, one of the three keywords shown above may follow
on, in which case the behavior will correspond to the name of that
keyword.

logfile

lfname(.log) <create, truncate, append>

The name of the log file is set equal to lfname. The logging facility
must be turned on to activate writing (see the SET log command). If
the logging facility is on, then the previous file (if any) is closed, and
the new file lfname is opened using the attribute keyword, if present.

max cells

n
sets the number of cells in each direction to be used in cell-mapped
contact detection logic. (The default = 6.)

3DEC Version 5.0

1 - 238

SET

Command Reference

maxdt
maxdt

value
sets the upper limit for the creep timestep if SET crdt auto is used.
The default value is 1 104 .

mechanical

keyword <keyword value> . . .

on
off
The mechanical calculation process is turned on or off. The mechanical process is on by default. The mechanical calculation should be
turned off for a thermal-only calculation.

min ang

value
sets minimum edge angle allowed for a block cut. (The default is 1 .)

mindt

sets the lower limit for the creep timestep if SET crdt auto is used.
The default value is 1 102 .

munb

value
limits the maximum unbalanced volumes in fast-flow calculations.
The limit is used in fully coupled calculations to stop mechanical
iteration within a single flow timestep before reaching nmech. The
default is 0.0.

ncycle

n
synonym for hist rep

ngw

n
is the number of fluid cycles per mechanical cycle. (The default is 1.)

nmech

n
maximum number of mechanical cycles per fluid cycle. The default
is 1.

nodal

off
on
turns nodal mixed discretization (NMD) on for plasticity calculations.
This provides a more accurate solution for tetrahedral meshes. The
default is off. See Section 1.2.3 in Theory and Background.

3DEC Version 5.0

COMMAND REFERENCE
SET
notice

notice

1 - 239

off
on
controls whether informational messages generated by the program
during command processing will be sent to the screen and the log file
(if the logging facility is on see the SET log command). By default,
notice is set on. (A related command is SET warning.)

nstep

n
synonym for hist rep

nther

n
number of thermal sub-steps

nucp

n
updates common-plane location every n cycles. (The default is n =
10.)

nucx

n
searches for new sub-contacts every n cycles. (The default is n = 10.)

nup fluid timestep

number of cycles between updates to fluid timestep. The default is 1.

nupdt

n
timestep to update frequency (default = 0: no update)

nupface

n
face normal update frequency (default is every 10 cycles)

overlay

lename = str
sets name of file used as input for the POLYHEDRON cube command.
The default is overlay.txt.

pagination

off
on
controls the status of text pagination for textual information sent to
the screen. By default, text pagination is on.

plotinterval

n
During cycling, the number of steps between updates to the user
interface. In the Itasca GUI, this causes displayed plots to refresh.

3DEC Version 5.0

1 - 240

SET

Command Reference

processors
processors

n
specifies the number of processors (n) to use on a multiple-processor
machine. If n is greater than the number of available processors, then
all of the available processors will be used. This value is not stored
in save files.

random

nseed
sets the seed for the random-number generator (used by the GENERATE and JSET commands) to the integer nseed. By default, nseed
equals 10,000. The value specified should be of the same magnitude
as the default value. If SET random is given after a NEW command,
identical models can be generated for multiple runs. The seed is not
reset by the NEW command.

rhs

off
on
sets 3DEC to use a right-handed coordinate system.

sdel

off
on
allows deletion of open sub-contacts during the first cycle. (The
default is on.)

seed

n
sets the seed for the FISH random-number generator to urand and
grand. Also used by the DFN generator.

skip join update off

on
This causes 3DEC to not update the list of joined contacts at cycle
time. The update was based on the joined block structure, and would
cause block faces that were intentionally not joined to become joined.
This may cause unpredictable effects if blocks are cut after being
initially joined.

small

off
on
sets small strain on or off. The default is off.

spface

off
on
controls whether 3DEC will split non-convex faces. (The default is
on.)

3DEC Version 5.0

COMMAND REFERENCE
SET
tension

tension

1 - 241

off
on
sets the tension flag for the Mohr-Coulomb plasticity model (cons 2
only). If off, blocks cannot fail in tension. (This is often used when
creating excavations.) The shock of an instantaneous excavation may
cause some zones to fail in tension, even if they would not have failed
had the excavation occurred slowly. Tension may be turned back on
again after a few cycles, when the tensile stress wave has moved into
the model.

th implicit

off
on
The implicit solution scheme in the thermal model is turned on or off.
The default is off.

th numerical off
on
If off, switches the thermal logic used in 3DEC to the analytic solution
method. The default is on.

th scale

off
on
turns thermal mass scaling on. The default is off.

th store matrix off

on
sets flag to store some of the calculated thermal constants. This uses
more memory, but runs more quickly. The default is on.

th time

t
t is the thermal time.

thcouple

n
specifies the number of mechanical steps to execute between analytic
thermal solutions.

3DEC Version 5.0

1 - 242

SET

Command Reference

thdt
thdt

dt
t defines the thermal timestep. This timestep must be specified for the
implicit solution scheme. By default, 3DEC calculates the thermal
timestep automatically for the explicit solution scheme. This keyword
allows the user to choose a different timestep. If 3DEC determines
that the user-selected value is too large for numerical stability, the
timestep will be reduced to a suitable value when thermal steps are
taken. The calculation will not revert to the user-selected value until
another SET thdt command is issued.

thermal

off
on
The thermal calculation process is turned on or off. The thermal
process is on by default when the CONFIG thermal command is given.
The thermal calculation is turned off for a mechanical-only, fluid flowonly or mechanical-fluid flow calculation.

thtolerance

value
The keyword thtolerance can be used to set a tolerance for thermal
calculations. This tolerance can be thought of as a source radius. If
temperatures are calculated at a point closer than value to a gridpoint,
the distance from the gridpoint is taken as value. This is necessary
because the analytical solution for the temperature due to a point
source approaches infinity as the distance from the source approaches
zero. (The default is value = 0.1.)

time

value
sets current mechanical time. This will affect the behavior of APPLY
and BOUNDARY histories.

tunnel axis

x1,y1,z1 x2,y2,z2
specifies tunnel axis that is used for liner output.

umul

value
sets the multiplication factor used to lower the creep timestep if the
maximum out-of-balance force drops below fobl for more than latency
timesteps (requires SET crdt auto). The default value is 2.0.

3DEC Version 5.0

COMMAND REFERENCE
SET
warning

warning

1 - 243

off
on
controls whether warning messages generated by the program during
command processing will be sent to the screen and the log file (if
the logging facility is on see the SET log command). By default,
warning is set on. (A related command is SET notice.)

zvol del

value
Zones with volumes under the set value will be deleted during cycling.
The default is 0.0.

zvol nodal

value
Zones with volumes under the set value will be excluded from nodal
mixed discretization calculation. The default is 0.0.

zvol ratio

value
Zones with an inner/outer sphere volume ratio under the set value will
be excluded from nodal mixed discretization calculation. The default
is 0.001.

3DEC Version 5.0

1 - 244

SET

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
SHOW

SHOW

1 - 245

<ffield> <range . . . >

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 GENERATE 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 feld is given, then only blocks in
the free-field boundary are hidden.

3DEC Version 5.0

1 - 246
SHOW

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
SOLVE

SOLVE

1 - 247

keyword . . .
executes timesteps until the specified limit is reached. If the <Esc> key is pressed
during execution, 3DEC will return control to the user after the current cycle is
complete.

age

value
value is the total problem time.

clock

value
computer runtime limit, in minutes. The default is 0 minutes, which
indicates that this limit is ignored.

continue

resumes a previous CYCLE or SOLVE command that was interrupted

by an <Esc>.

cycles

n
cycle limit (the default is 2,000,000,000 cycles)

elastic

sets joints and zone constitutive models to infinite strength for initial
equilibrium cycling. The command does not reset previously established plasticity flags. However, plastic deformation will not occur
while in effect. This command can be used for built-in, zone and joint
models. This command does an initial solve with infinite strength,
and then solves again with strengths returned to previous values. To
do only the infinite strength step, use SOLVE elastic only. (See note
on p. 1 - 250.)

force

value
out-of-balance force limit. The default is 1 103 .

fos

keyword
determines model minimum factor-of-safety. See Section 3.10.5 in
the Users Guide.

associated

for block plasticity (default nonassociated)

bracket

v1 v2
sets two starting bracket values. FOS calculation stops
with a warning message, if it turns out that the FOS
falls outside of the specified brackets. If v1 = v2, 3DEC
tests one value for stability.

cycles

sets limit to maximum number of cycles (default =

50,000).

3DEC Version 5.0

1 - 248
SOLVE

Command Reference

fos

exclude
exclude

keyword

include

keyword
excludes or includes properties from those modified
by the factor-of-safety calculation.

bcohesion The default is include.

bfriction

The default is include.

btension The default is exclude.

jcohesion The default is include.
jfriction

The default is include.

jmat

n
joints of material n (default include all)

jtension

The default is exclude.

mat

n
blocks of material n (default include all)

le

fname(.fsv)
file name for mode of failure state (default FOSMODE.FSV)

ncharres

nc
sets the characteristic response steps, nc. If not specified, nc is tested using the existing perturbation
method.

ratio

v
resets unbalanced force ratio used to determine equilibrium. If this is not explicitly set, 3DEC uses the
current value used by the previous SOLVE command.
(default is 105 )

resolution

v
sets the resolution in comparing two bracketing (stable
and unstable) factors. (The default is .005 mean
value.)

3DEC Version 5.0

COMMAND REFERENCE
SOLVE
ftime

ftime

1 - 249

value
specifies the fluid-flow time limit.

noage

turns off age limit.

r type

keyword
The ratio limit for mechanical calculations can be calculated in three
different ways, as defined by the following keywords:

ratio

average

The ratio is defined to be the average unbalanced mechanical force magnitude divided by the average applied mechanical force magnitude for all block centroids or gridpoints in the model (default).

local

The ratio is defined to be the maximum value of the

unbalanced mechanical force magnitude, divided by
the applied mechanical force magnitude for all block
centroids or gridpoints in the model.

maximum

The ratio is defined to be the maximum unbalanced

mechanical force magnitude for all block centroids or
gridpoints in the model, divided by the average applied
mechanical force magnitude for all block centroids or
gridpoints.

value
The ratio limit for the mechanical calculation process. The default
value is 1 104 .

temp

value
specifies the maximum increase in temperature.

thtime

value
specifies the thermal time limit.

3DEC Version 5.0

1 - 250
SOLVE

Command Reference

time
time

value
value is the problem time duration in seconds for this increment of
cycling.

NOTE: The objective of the SOLVE elastic scheme is to get an initial state that is
both in equilibrium and not actively failing. Usually we have no knowledge of
how an existing system got to its present state unless we know, and can reproduce,
the complete history (e.g., excavation of a slope or tectonic loading of a geologic
system). Thus, any scheme that satisfies the two conditions listed above is valid,
given a lack of knowledge of history. However, since the process is arbitrary, the
plastic strains accumulated during the process of arriving at the initial state have no
significance. The approach of switching on plasticity after an initial elastic solution
will tend to minimize the region that goes plastic, which should lead to a more
uniform initial stress state. The plastic strains accumulated in getting to this solution
have no significance. This also applies to the displacements, which should be set to
zero (in general) before proceeding.

3DEC Version 5.0

COMMAND REFERENCE
SOURCE

SOURCE

1 - 251

keyword . . .
This command is used to input general information about the heat source components.
The POINT, LINE and GRID commands are used to position these sources and specify
their initial strengths and starting times. (Only available for the thermal option see
Section 1 in Optional Features.)
The keywords are:

component

n
component of heat source

decay

v
decay constants of the components

fraction

v
fraction of the initial source strength produced by each component

ncomponents nc
number of components making up the source

type

nt
The first item following the source command must be the identifying
number.

Before the fractions and decay constants can be input, the number of components
must be specified, either on the same command line or on a preceding one. The sum
of all the fractions must be 1.
The following are examples of valid commands. All of these sets have the same
effect.
SOURCE
SOURCE
SOURCE
SOURCE
SOURCE
SOU TY
SOU TY
SOU TY
SOU TY
SOU TY
SOU TY
SOURCE
SOURCE

TYPE
TYPE
TYPE
TYPE
TYPE
1 NC
1 CO
1 CO
1 CO
1 CO
1 NC
TYPE
TYPE

1
1
1
1
1
2
1
1
2
2
2
1
1

NCOMP 2
COMP 1 FRAC .4
COMP 1 DECAY 1e-10
COMP 2 FRAC .6
COMP 2 DECAY 2e-10
FR.4
DE 1e-10
FR.6
DE 2e-10
CO 1 FR .4 DEC 1e-10 CO 2 FR .6 DEC 2e-10
NCOMP 2
COMP 1 FRAC .4 DECAY 1e-10

3DEC Version 5.0

1 - 252
SOURCE

Command Reference

SOURCE
SOURCE
SOURCE
SOURCE
SOURCE

TYPE
TYPE
TYPE
TYPE
TYPE

1
1
1
1
1

COMP 2 FRAC .6 DECAY 2e-10

NCOMP 2
COMP 1 FRAC .4 COMP 2 FRAC .6
COMP 1 DECAY 1e-10
COMP 2 DECAY 2e-10

The POINT, LINE and GRID commands are used to define SOURCE locations, strengths
and starting times.

3DEC Version 5.0

COMMAND REFERENCE

1 - 253

STEP
STEP

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

3DEC Version 5.0

1 - 254

STEP

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
STOP

STOP

1 - 255

This command is a synonym for the QUIT command.

3DEC Version 5.0

1 - 256
STOP

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
STRUCTURE

1 - 257

STRUCTURE keyword <range . . . >

The STRUCTURE command is used to define the geometry and properties for axial
and cable reinforcing elements and structural lining elements. The keywords used
to define the elements are as follows:

axial

Axial reinforcement with local normal restraint across discontinuities

is provided. The geometry and property number for this reinforcement are defined by the values following the axial keyword. The
required input is in the form
STRUCT AXIAL x1 y1 z1 x2 y2 z2 PROP n

where x1, y1, etc. define the axial reinforcement endpoints.

When axial reinforcement is used with fully deformable blocks, the
blocks must be discretized into zones before reinforcement locations
are specified. PROP n defines the property number assigned to the
reinforcement.

beam

keyword
RADIAL GEN x1 y1 z1 x2 y2 z2 ...
SEG naxial nradial PROP n ...
<BEGIN xb yb zb END xe ye ze> <CONNECT>

generates a series of rings of beam elements on a tunnel surface in

sections along the tunnel axis where: x1 y1 z1 and x2 y2 z2 define
the endpoints of the tunnel axis; naxial is the number of sections
with beam elements; nradial is the number of beam elements in each
section; BEGIN xb yb zb and END xe ye ze are points defining the
initial and final radial directions for a partially closed cross-section;
and CONNECT connects new elements to existing nodes at the same
location.
NODE x y z <ID id> <PROP n> <TOL tol>

creates a single beam node where: ID id is the node ID (default =

automatically generated ID); PROP n is the property number (default
= 1); and TOL tol is the distance tolerance to search for a face to place
the node (default = ATOL).
ELEMENT naid nbid <ID id> <PROP n>

creates a single beam element where: ID id is the element ID (default

= automatically generated ID); and PROP n is the property number
(default = 1).

3DEC Version 5.0

1 - 258
STRUCTURE beam

Command Reference

apply
apply

keyword id n
applies forces or fixes velocities of beam nodes. Keywords are:

fixes translational velocity of node n.

force

fx fy fz
applies forces to node n.

free

frees translational velocity of node n.

moment mx my mz
applies moment to node n.

rx

fixes rotational velocity of node n.

rfree

frees rotational velocity of node n.

rvelocity rvx rvy rvz

initializes rotational velocity of node n.

velocity vx vy vz
initializes translational velocity of node n.

delete
cable

deletes all beam elements in a given range.

The cable element geometry, discretization, property number and pretensioning are defined by the values which follow the cable keyword.
The required input is in the form
STRUCT CABLE x1 y1 z1 x2 y2 z2
SEG ns PROP n <TENS t>

&

where: x1, y1, etc. define the cable endpoints; SEG ns is the number
of segments into which the cable is divided; PROP n is the property number assigned to the cable; and TENS t is the optional cable
pretension value.
When cable reinforcement is used with fully deformable blocks, the
FDEF blocks must be discretized into zones before reinforcement
locations are specified.

3DEC Version 5.0

COMMAND REFERENCE
STRUCTURE delete

delete

liner

1 - 259

keyword

axial

deletes axial reinforcement in a given range.

beam

deletes beam elements in a given range.

cable

deletes cable elements in a given range.

liner

deletes liner elements in a given range.

<keyword>
This command is available for the structural liner option only (see
Section 3 in Optional Features). The structural element liner, discretization and property number are defined by the values which follow the liner keyword. Available keywords are:
radial x1 y1 z1 x2 y2 z2 &
SEG na,nr PROP n <CYLINDER r> &
<BEGIN xb yb zb> <END xe ye ze> <CONNECT>

where: x1, y1, etc. define the endpoints of the liner axis; nr is the
number of radial segments into which the liner is divided; na is the
number of axial segments into which the liner is divided; PROP n
is the property number assigned to the liner; and CYLINDER r is an
optional parameter to limit the search for possible liner/host medium
contacts to a cylinder with radius r.
CONNECT specifies that new nodes should be connected to existing
nodes at the same location. By default, no connection is assumed.
BEGIN and END define the initial and final directions for partial liner
generation. By default, the entire cylindrical surface is used in generation. (See Figure 1.2.)

delete

deletes all liner elements with centroids in a given

range.

element

n1 n2 n3 <prop n>
creates a structural element with IDs n1, n2 and n3,
and property n.

face gen

prop n <range>
creates triangular liner elements for all faces inside
the range. (The sregion range is most useful in this
case.) sregions can be set up by using the MARK
command to specify the faces between two regions
or materials.

3DEC Version 5.0

1 - 260
STRUCTURE liner

Command Reference

node
node

x y z <id n> <prop n> <tolerance tol>

creates a new structural node at a location with a given
ID. If ID is not specified, it is generated. tolerance
is the tolerance used for finding a connection to new
blocks.

Ending
plane

(x , y , z )

E
B
(x, y, z)

Starting
plane

cylinder axis

Figure 1.2

property

Parameters used in defining partial tunnel liners

The axial, cable and liner element material properties, and area are
assigned using this keyword in the form
STRUCT

PROP n keyword = value . . .

This command associates property values with a particular property

number n set by the axial, cable or liner keyword.
Axial reinforcement properties are assigned using the following keywords:

rkaxial

value
axial stiffness [force/displacement]

rlength

value
1/2 active length [length]

3DEC Version 5.0

COMMAND REFERENCE
STRUCTURE property
rsstiffness

rsstiffness

1 - 261

value
shear stiffness [force/displacement]

rsstrain

value
shear rupture strain

rstrain

value
axial rupture strain

rultimate

value
ultimate axial capacity (must be greater than zero)
[force]

rushear

value
ultimate shear capacity [force]

Beam properties are assigned using the following keywords:

area

value
cross-section area

density

value
element density (required for dynamic analysis)

emod

value
Youngs modulus

value
bending inertia (if equal about both local axes, S1 and
S2)

I1

value
bending inertia about local axis S1

I2

value
bending inertia about local axis S2

value
polar moment of inertia

3DEC Version 5.0

1 - 262
STRUCTURE property

Command Reference

nu
nu

value
Poissons ratio

S1

v1 v2 v3
Y-vector defining cross-section axis S1 (default S1
axis is horizontal); see Section 3.3 in Theory and
Background for Y-vector usage

strain limit

value
strain limit for axial yielding. Yield capacity goes to
zero.

ycomp

value
yield capacity in compression [force] (default elastic
material)

yield

value
yield capacity in tension [force] (default elastic material)

Keywords for properties of contacts between beams and blocks:

cohesion

value
cohesive shear strength [force/unit length] (default =
0)

friction

value
friction angle [degrees] (default = 0)

kn

value
normal stiffness [force/unit length/displacement]

ks

value
shear stiffness [force/unit length/displacement]

tensile

value
tensile strength [force/unit length] (default = 0)

Cable properties are assigned using the following keywords. Figures 1.3 and 1.4 illustrate the relation of grout and cable material
properties, respectively.

3DEC Version 5.0

COMMAND REFERENCE
STRUCTURE property
area

area

1 - 263

value
cross-sectional area of cable

emod

value
Youngs modulus of cable

kbond

value
bond stiffness of grout [force/unit cable
length/displacement]

sbond

value
bond strength of grout [force/unit cable length]

thexpansion

value
thermal expansion coefficient

ycomp

value
compressive yield strength (default = 0)

yield

value
tensile yield strength (force) of cable

3DEC Version 5.0

1 - 264
STRUCTURE property

Command Reference

force/length

Fsmax
L
kbond
1
relative shear
displacement

Fsmax
L

Figure 1.3

3DEC Version 5.0

Grout material properties for cable elements

COMMAND REFERENCE
STRUCTURE property

1 - 265

- =HA=

Figure 1.4

Cable material properties for cable elements

Liner properties are assigned using the following keywords:

cohesion

value
cohesion [force] limit for contact between the liner and
the host medium

emod

value
Youngs modulus of liner material

friction

value
friction coefficient for contact between the liner and
the host medium

kn

value
normal stiffness [force/displacement] for contact between the liner and the host medium

ks

value
shear stiffness [force/displacement] for contact
between the liner and the host medium

3DEC Version 5.0

1 - 266
STRUCTURE property

Command Reference

nu
nu

value
Poissons ratio of liner material

tensile

value
tension [force] limit for contact between the liner and
the host medium

thexpansion

value
thermal expansion coefficient

thick

value
liner thickness

3DEC Version 5.0

COMMAND REFERENCE
SYMMETRY

SYMMETRY

1 - 267

<x> <y> <z>

This command is used to define thermal symmetry planes. For example, the plane
defined by y = 0 is a symmetry plane if the command SYMMETRY y is issued. Symmetry planes are used to represent adiabatic boundaries. (This is only available for
the thermal model option see Section 1 in Optional Features.)

3DEC Version 5.0

1 - 268
SYMMETRY

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
SYSTEM

SYSTEM

1 - 269

<clone> <timeout sec> string . . .

This command allows the user to access the underlying command-driven operating
system (DOS, under Windows). The contents of the string tokens are passed directly to the system, and the text output is redirected to the screen. Some common
commands used here are SYSTEM dir, SYSTEM copy test.dat test2.dat, SYSTEM del
temp.out, etc.
If the clone keyword is given, then a clone of the current program is spawned, and
the contents of the string are passed as arguments.
If the timeout keyword is given, the following integer is the number of seconds 3DEC
will wait for the process to complete before shutting down the process and moving
on. If this number is 1, then 3DEC will wait forever. If this number is 0, then
3DEC will spawn the process and move on immediately, leaving the process to run
in parallel. In this last case, text output from the program will not be captured.
CAUTION: Do not use these commands to modify files that 3DEC is currently
reading.

3DEC Version 5.0

1 - 270
SYSTEM

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
TABLE

TABLE

1 - 271

n <keyword> <x1 y1> <x2 y2> <x3 y3> . . .

This command sets up a table with ID number of n, containing the specified x- and
y-values. The table logic supports the creation and manipulation of tables, which are
indexed arrays of pairs of floating-point numbers, denoted for convenience as x and
y. Each table entry (or (x,y) pair) also has a sequence number (integer in the range
[1, 2, . . . , N], where N is the number of items in the table). Refer to Section 2.5.2.3
in the FISH volume for a comprehensive discussion of the table logic and how it
can be used by FISH functions to manipulate data.
Multiple tables may be defined. Each table has a unique ID number, which is an
integer greater than zero. In addition, each table also has a string representing the
table name (see the optional name keyword), which can be used in place of the table
ID for most commands that operate upon tables.
The contents of a history may be copied to a table via the HISTORY write table
command. Also, the contents of an ASCII file may be copied to a table via the
optional read keyword. The information in a table can be plotted using the PLOT
table command, and printed using the LIST table command.
The following optional keywords are available:

delete

completely deletes the table; no additional keywords can be applied.

erase

removes all entries from table n, and all memory associated with the
entries is freed.

insert

One or more (x,y) pairs can be added to a table at any time. The new
entries are added to the end of the table unless the insert keyword
is used, in which case each new entry is inserted between the two
existing entries that bracket the x-value of the new entry; or if the
x-value for the new entry is identical to that of an existing entry, then
the y-value of the existing entry is updated. The insertion process
has undefined results if the table is not currently sorted in order of
increasing x-value (which can be done automatically via the optional
sort keyword).

name

tname
sets the name of table n equal to tname. The table ID number is not
changed. The table name can be used in place of the table ID for most
commands that operate upon tables.

position

sxy
substitutes the specified (x,y) pair for the stored x- and y-values in
the slot in table n with sequence number s. If slot s does not exist,
then sufficient entries to encompass the given sequence number are
appended to table n. Then the given (x,y) pair is installed.

3DEC Version 5.0

1 - 272
TABLE

Command Reference

read
read

fname(.tab)
reads file fname (which must be formatted as described below), and
places its contents into table n.
NOTE: Values read are added to any current contents.
The file fname must be formatted and organized as follows:
Line 1 This line will be taken as the name of the table,
and can be of any length.
Line 2 gives the two values np, tdel (number of points
and timestep, respectively, where np is an integer
and tdel is a real).
Line 3 through Line np+2
np real values of the table y-value. The x-value
is calculated as equally spaced values of time at
intervals of tdel. If tdel is specified as 0.0, then it
is assumed that the timestep is not constant, and
the values for Line 3 through Line np+2 are read
as pairs.

sort

causes all entries in table n to be sorted in order of increasing xvalue. If additional (x,y) pairs are specified following this keyword,
then they will be inserted such that the table remains sorted in order
of increasing x-value.

write

fname(.tab)
The contents of the table are output to file fname. The format of the
output is compatible with the read keyword. The output assumes that
the x-increment is irregular. Therefore, the tdel parameter is set to
zero and the values are output as (x,y) pairs.

3DEC Version 5.0

COMMAND REFERENCE
TENSOR

TENSOR

1 - 273

keyword . . .
Tensors are an internal list of user-defined objects that have a position and a symmetric
tensor associated with them. They may also have groups and FISH values assigned
to them.

add

x y z keyword . . .
adds a single tensor at location (x,y,z).

extra

param <index i>

param can be any FISH parameter, including a vector
delimited by parentheses or a FISH fragment delimited
by brackets. If an extra index is not specified, each
extra keyword assigns extra data to subsequent indices
(i.e., extra 1.0 extra fred assigns 1.0 to extra index
1 and fred to index 2).

group

name <slot s>

If a groups slot is not specified, each group keyword
assigns a group to a subsequent slot (i.e., group fred
group george assigns fred to slot 1 and george to
slot 2).

principal

p1 p2 p3 p3x p3y p3z p2x p2y p2z

The tensor value is specified by principal magnitudes
(minimum, intermediate and maximum, respectively)
and the directions of the major and intermediate
stresses. The direction vectors are normalized. The
intermediate principal stress direction is also corrected
if it is not fully orthogonal to the major stress direction.
The minor principal stress direction is fully determined
by the other two.

s11 s22 s33 s12 s13 s23

specifies the tensor value. Any subsequent value overwrites a previous one given.

export

filename(.tensor) <binary> <range . . . >

exports all tensors in the assigned range to a file. A text file is created
unless the binary keyword is specified. Any previous file is deleted.
The file format is fully described in Section 1.5.

3DEC Version 5.0

1 - 274
TENSOR

Command Reference

import
import

filename(.tensor) <group str <slot i>>

imports tensor data from the file specified. The file format (text or binary) is determined by opening the file and looking for the appropriate
header. If the proper header is not found, an error is indicated and no
data are imported. If the group keyword is specified, imported scalars
are assigned group name str in slot i (which is 1, by default). This
group assignment overrides any in the import file. The file format is
fully described in Section 1.5.

remove

<range . . . >
removes (deletes) all tensors falling into the specified range. If a
range is not specified, all tensors are deleted.

3DEC Version 5.0

COMMAND REFERENCE

1 - 275

THSOLVE
THSOLVE

The thermal solution is calculated when this command is issued. Temperatures are
calculated at all gridpoints in the model. Stress increments are not calculated at this
point, but are calculated for all zones the next time mechanical cycling is performed.
If the THSOLVE command is not issued but the program detects a change in conditions, such as source parameters or time, when cycling is next performed, it will
automatically update the thermal solution before calculating new stress increments.
This is only for the thermal option (see Section 1 in Optional Features).

3DEC Version 5.0

1 - 276

THSOLVE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE

1 - 277

TIME
TIME

t
The time at which thermal results are to be calculated is input (only for the thermal
option see Section 1 in Optional Features).

3DEC Version 5.0

1 - 278

TIME

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
TITLE

TITLE

1 - 279

title
sets the model title to title. The title is included in subsequent plots and stored in
save files. The command LIST information lists the current title.
If title is specified, then that token is parsed as a string and taken as the title. The
token may be a FISH string variable. If so, do not enter the token in single quotes.
If title is not specified, then the prompt Job Title: appears and the next line input
is taken as the title; if one simply types <Return> without specifying a string, then
the title will be cleared.

3DEC Version 5.0

1 - 280
TITLE

3DEC Version 5.0

Command Reference

COMMAND REFERENCE

1 - 281

TRACE
TRACE

keyword . . .
The positions and velocities of certain objects can be sampled and stored during a
model run by using the TRACE command. The resulting path through space can be
plotted with the PLOT add particletrace command. Only one object may be traced
per TRACE command. Traces may be added at any time. The contents of all traces
can be erased with the purge keyword, and all traces can be deleted with the delete
keyword. A summary of all traces can be obtained by using the LIST trace command.
Each trace is given a unique ID number, based on the order in which the TRACE
commands are issued. However, a specific ID number can be assigned with the
id keyword. All traces are sampled at a single sampling interval. By default, the
sampling interval for the trace mechanism is 10 steps. The sampling interval can be
changed with the trace rep keyword or the SET trace rep command. Different trace
intervals cannot be assigned to different traces.
The following keywords are available:

add

<id id> keyword

adds a new trace to the list of those taken during an update. ID
numbers for the new trace are assigned automatically, but may be
assigned manually using the optional id keyword. Manually assigned
ID numbers must be unique.
The following keywords are available:

fish

symbol
indicates that the FISH symbol symbol will be sampled. See Section 2.4.1 in the FISH volume. The symbol should contain a three-dimensional vector value.
A leading @ character is not required (but will be accepted), even in safe-conversion mode. The velocity
of this trace will always be set to zero.

gp

<id id> <x y z>

traces the position and velocity of a gridpoint. A gridpoint ID (which may or may not currently exist) may
be specified, or the closest currently existing gridpoint
to position (x,y,z) will be found.

delete

causes all traces to be deleted. This keyword is a synonym for reset.

dump

id . . .
writes the contents of the list of traces indicated by id to the screen.

3DEC Version 5.0

1 - 282

TRACE

Command Reference

label
label

n string
replaces the default trace label for trace ID n with string. This is the
label that will appear when plotting the trace.

limits

lists the extent of position and velocity values taken for each trace.

list

lists all traces currently being taken and their current locations.

purge

purges the contents of all traces, but retains the list of objects to trace.
New values will continue to be taken upon further cycling.

range

This is a synonym for the limits keyword.

reset

causes all traces to be deleted. This keyword is a synonym for the

delete keyword.

trace rep

n specifies the step interval on which trace values will be recorded.

The default value is 10.

write

id . . . file filename
writes the contents of the list of traces indicated to the file filename.

3DEC Version 5.0

COMMAND REFERENCE
TUNNEL

TUNNEL

1 - 283

<region n> <radial> a x1,y1,z1 x2,y2,z2 x3,y3,z3. . .

b x1,y1,z1 x2,y2,z2 x3,y3,z3 . . .
A tunnel is created between the two faces designated by keywords a and b; the
straight lines connecting the two faces define the tunnel boundary. 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, which may be positioned either inside or outside the model. The list of
coordinate triples may extend over an arbitrary number of continuation lines, but a
triple cannot be split over two lines.
The keyword region allows the user to assign a specific number to a tunnel region.
Use the LIST block command for a list of current block region numbers.
The keyword radial will cause the cuts used for the tunnel shape to be radial to
the center rather than tangential to the tunnel edges. Note: The apparent extra cut
through the model occurs because any single cut must pass entirely through a block.
Thus the first cut passing through the first vertex cuts through both sides of the tunnel
outline.

3DEC Version 5.0

1 - 284
TUNNEL

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
UNDO

UNDO

1 - 285

lines
If possible, this command undoes the last lines of commands entered interactively to
the command processor, whether they were actually typed at the command prompt
or sent automatically by the user interface. This is implemented by playing back
the record of interactive commands recorded since the last model reset or save state.
A call to a data file is interpreted as a single line to UNDO. Commands that caused
an error will not interrupt playback; the error will be reported as before but will not
halt processing.
Note that UNDO is not always available:
Commands that were interrupted in an unsafe way will
prevent the undo playback.
A save or restore cannot be undone.
It is possible for UNDO to fail or result in a different model
state if the execution environment has changed.
Save states created during states when the NEW command is not allowed (such as while processing a FISH
COMMAND/END COMMAND) cannot be used as a starting
point for an undo.
Be aware that if you are using this command directly (by
typing UNDO on the command line), no check is made to
see how long the playback will take.

3DEC Version 5.0

1 - 286
UNDO

3DEC Version 5.0

Command Reference

COMMAND REFERENCE
VECTOR

VECTOR

1 - 287

keyword . . .
Vectors are an internal list of user-defined objects that have a position and a direction
and magnitude associated with them. They may also have groups and FISH values
assigned to them.

add

x y z keyword . . .
adds a single vector at location (x,y,z).

direction

dip dd m
The vector value is specified by direction. dip and dd
are dip and dip direction in degrees, respectively. m is
the vector magnitude.

extra

param <index i>

param can be any FISH parameter, including a vector
delimited by parentheses or a FISH fragment delimited
by brackets. If an extra index is not specified, each
extra keyword assigns extra data to subsequent indices
(i.e., extra 1.0 extra fred assigns 1.0 to extra index
1 and fred to index 2).

group

sname <slot s>

If a groups slot is not specified, each group keyword
assigns a group to a subsequent slot (i.e., group fred
group george assigns fred to slot 1 and george to
slot 2).

vx vy vz

<magnitude m>
specifies the vector value. Any subsequent value overwrites a previous one given. If the magnitude keyword
is used, then (vx,vy,vz) is used as a direction only, and
the length of the vector is determined by m.

export

filename(.vector) <binary> <range . . . >

exports all vectors in the assigned range to a file. A text file is created
unless the binary keyword is specified. Any previous file is deleted.
The file format used is documented fully in Section 1.5.

3DEC Version 5.0

1 - 288
VECTOR

Command Reference

import
import

filename(.vector) <group str <slot i>>

imports vector data from the file specified. The file format (text or binary) is determined by opening the file and looking for the appropriate
header. If the proper header is not found, an error is indicated and no
data are imported. If the group keyword is specified, imported scalars
are assigned group name str in slot i (which is 1, by default). This
group assignment overrides any in the import file. The file format
used is documented fully in Section 1.5.

remove

<range . . . >
removes (deletes) all vectors falling into the specified range. If a
range is not specified, all vectors are deleted.

3DEC Version 5.0

COMMAND REFERENCE
WATER

WATER

1 - 289

keyword value <keyword value> . . .

This command assigns a pore-water pressure field to all blocks/contacts defined in
terms of a groundwater surface. This surface may be defined as a plane or as a set
polygonal faces. This allows zone and contact model calculations to be performed
in terms of effective stress. The stresses stored in the zones are total stresses. Pore
pressures are defined at gridpoints. Zone pore pressures are then calculated as the
average of the zone gridpoints. The pore-water pressures are subtracted from the
total stresses before calling the constitutive routines.
Contact stresses are always effective stresses. Forces due to the pore pressures are
applied independently, causing the joints to deform.
The user may choose to apply pore pressures only to the blocks, or to the joints, or
both.
Pore pressures are not affected by zone volume changes, nor is there any flow of
water. Note that when using the WATER command, the dry density must be specified
for zones above the water table, and the saturated material density for zones below.
The following keywords apply:

blocks

off
on
If off, gridpoint pore-pressures are not assigned (default = on).

density

value
fluid density, w [SI units: kg/m3 ]

joints

off
on
If off, joint pore pressures are not assigned (default = on).

table

keyword value . . .
The WATER table command sets pore pressures for all gridpoints below the water table. The pore pressure gradient is given by the direction of the gravity vector, which can be arbitrary (see the GRAVITY
command).
The water table plane can be defined in two forms: a single infinite
plane, or an assembly of planar convex polygons. For an infinite
plane, the following keywords are used:

clear

deletes water table definition (pore pressures are unchanged).

3DEC Version 5.0

1 - 290
WATER

Command Reference

table

face
face

x1, y1, z1 . . . xn, yn, zn <face . . . >

The face polygon is defined by nodes x1, y1, z1 to
xn, yn, zn. The nodes must produce a convex polygon. Faces can have any number of nodes, but are
split into triangles for storage. Only gridpoints that
project along the gravity direction inside of faces
are assigned pore pressure. No checking of face overlapping or intersection is performed.
The three coordinates of each face vertex must be on
the same command line.

geometry

setname
uses a geometry set (imported or created) to define
the water table. Polygons from the geometry are used
to compute pore pressures as described for the face
keyword.

normal

nx ny nz
normal direction to the plane, defined by unit vector
nx, ny, nz and pointing in the direction of increasing
pore pressure

origin

xyz
one point at coordinate location (x, y, z) on the plane

Alternatively, the water table can be defined by an assembly of planar,

convex polygons.
NOTES: (1) Gravity must be defined prior to use of the WATER command.
(2) Successive WATER commands with the WATER table face command adds new
faces to the previous water table definition. WATER table clear must be given to
delete the old water table.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

ZONE

1 - 291

keyword <range. . . >

This command is used to assign constitutive models or user-defined models (UDM)
to zones in 3DEC. This command is also used to assign properties to these zones.
For some of the models, the UDM option is required (see model list). Also, for
models included in the UDM option, the CONFIG cppudm command must be used.
Models exist as dynamically linked libraries. Model DLL files that are placed in the
\plugins\models folder will be loaded automatically. Otherwise, this is done by
using the ZONE load command (or the LOAD model command). The models may
then be assigned to zones via the ZONE model command.

density

value
assigns the density value for every zone in the range.

list

<keyword> <model>
outputs a summary of all dynamically loaded joint-constitutive models, or outputs information only for the model specified by model.

load

list

outputs names and version numbers. (This is the default.)

properties

outputs the list of available properties.

states

outputs the possible states.

version

is a synonym for list.

model
dynamically loads a constitutive model. The dynamic library should
have the name modelmodel001.dll. For example, model mohr
would have a library name of modelmohr001.dll.

model

model
assigns the dynamic constitutive model model to all of the zones in the
range. If not already loaded, the system will attempt to automatically
load the library.

property

value
assigns value to the property property for every zone in the range to
which that property applies.

3DEC Version 5.0

1 - 292
ZONE

Command Reference

Either the PROPERTY material=n density=v or ZONE density=v command may be used
to assign densities for a zone. However, once a ZONE density command has been
used, any changes in the zone density must be made via a ZONE density command.
(The user cannot mix command types for the same zone.) If a FISH fmem keyword is
used to change the density of a zone, then a dummy PROPERTY material=n density=v
command must be given to force 3DEC to recalculate the gridpoint masses.
At present, 20 constitutive models are available through use of this command. The
20 models are described in Section 1 in Constitutive Models. Any constitutive
model that already exists for some or all of the zones in the given range (as specified
by CHANGE cons) is ignored. The model keyword assigns constitutive models via
the following names.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 293

Model name Description

anisotropic
transversely anisotropic elastic
burgers*
Burgers viscoelastic model
cam-clay*
Cam-clay model
cpower*
power/Mohr viscoplastic model
cviscous*
Burgers/Mohr viscoplastic model
cwipp*
WIPP crushed-salt model
doubleyield double-yield plasticity model
drucker
Drucker-Prager plasticity model
elastic
isotropic elastic model
hoek
Hoek-Brown plasticity model
mhoekbrown modified Hoek-Brown model
mohr
Mohr-Coulomb plasticity model
orthotropic
orthotropic elastic model
power*
two-component power creep model
pwipp*
WIPP/Mohr viscoplastic model
strainsoftening strain-softening plasticity model
subiquitous
bilinear strain-softening ubiquitous-joint model
ubiquitous
ubiquitous joint model
viscous*
classical viscous (Maxwell) model
wipp*
WIPP reference creep model
* These models require the use of the CONFIG creep command.
Properties assigned through this command are model-specific. Note that block mass
density is specified in the usual way, via the PROPERTY command. Other properties
entered via the PROPERTY command are ignored if the range of sub-contacts falls
within the range specified by the ZONE command.
The model must be assigned before assigning properties. If properties that are
inconsistent with the chosen model are given, a warning message will be given,
informing the user that the unneeded properties were not accepted. If a required
property is not specified, the default will be used.
WARNING: When a model is invoked over a specified range, all properties associated
with that model are initialized to zero in that range. Properties previously assigned
to that range must be specified again, even if their values have not changed.
The properties for the zone models are:

3DEC Version 5.0

1 - 294
ZONE

Command Reference

Transversely Anisotropic Elastic ZONE model anisotropic

(1)
(2)
(3)
(4)
(5)
(6)
(7)

dd
density
dip
e1
e3
g13
nu12

(8) nu13

dip direction of plane of isotropy

mass density,
dip angle of plane of isotropy
Youngs modulus in the plane of isotropy
Youngs modulus normal to the plane of isotropy
shear modulus for any plane normal to the plane of isotropy
Poissons ratio characterizing lateral contraction in the plane
of isotropy when tension is applied in the plane
Poissons ratio characterizing lateral contraction in the plane
of isotropy when tension is applied normal to the plane

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 295

Burgers Model ZONE model burgers

(1)
(2)
(3)
(4)
(5)
(6)

bulk
density
kshear
kviscosity
mshear
mviscosity

elastic bulk modulus, K

material density,
Kelvin shear modulus, GK
Kelvin viscosity, nK
Maxwell shear modulus, GM
Maxwell viscosity, nM

The following calculated values can be printed, plotted or accessed via FISH:
(7) k
(8) k
(9) k
(10) k
(11) k
(12) k

exx
exy
exz
eyy
eyz
ezz

Kelvin strain in x-direction

Kelvin xy-shear strain
Kelvin xz-shear strain
Kelvin strain in y-direction
Kelvin yz-shear strain
Kelvin strain in z-direction

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

1 - 296
ZONE

Command Reference

Modified Cam-Clay ZONE model cam-clay

(1)
(2)
(3)
(4)
(5)
(6)
(7)
(8)
(9)

bulk bound
cv
density
kappa
lambda
mm
mpc
mp1
mv l

(10) poisson
(11) shear

maximum elastic bulk modulus, Kmax

initial specific volume, v0 (by default, calculated internally)
material density,
slope of elastic swelling line,
slope of normal consolidation line,
frictional constant, M
pre-consolidation pressure, pc0
reference pressure, p1
specific volume at reference pressure, p1 , on normal
consolidation line, v
Poissons ratio,
elastic shear modulus, G

Plasticity state indicator flags are given below. Use logical and to find individual
and multiple state modes.
Bit
Number
1
2

State
failure in shear now
failure in shear in the past

If a nonzero Poissons ratio, poisson, is given, then the shear modulus will change as
the bulk modulus changes; Poissons ratio remains constant. If the shear modulus,
shear, is given, and Poissons ratio is specified, then the shear modulus remains
constant; Poissons ratio will change as the bulk modulus changes.
The following calculated properties can be printed, plotted or accessed via FISH:
(12) bulk
(13) cam cp
(14) cam ev
(15) camev p
(16) cq

elastic bulk modulus, K

current mean effective stress
accumulated total volumetric strain
accumulated plastic volumetric strain
current mean deviatoric stress

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 297

Power-Law Viscoplastic Model ZONE model cpow

(1)
(2)
(3)
(4)
(5)
(6)
(7)
(8)
(9)

a1
a2
bulk
cohesion
density
dilation
friction
n1
n2

power-law constant, A1
power-law constant, A2
elastic bulk modulus, K
cohesion, c
material density,
dilation angle,
angle of internal friction,
power-law exponent, n1
power-law exponent, n2
ref

(10) rs 1

reference stress, 1

(11) rs 2

reference stress, 2

(12) shear
(13) tension

elastic shear modulus, G

tension limit, t

ref

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

1 - 298
ZONE

Command Reference

Burgers-Creep Viscoplastic Model ZONE model cvisc

(1) bulk
(2) cohesion
(3) density
(4) dilation
(5) friction
(6) kshear
(7) kviscosity
(8) mshear
(9) tension
(10) mviscosity

elastic bulk modulus, K

cohesion, c
mass density,
dilation angle,
angle of internal friction,
Kelvin shear modulus, GK
Kelvin viscosity, K
elastic shear modulus, GM
tension limit t
Maxwell dynamic viscosity, M

The following calculated properties can be printed, plotted or accessed via FISH:
(11) k exx
Kelvin strain in x-direction
(12) k exy
Kelvin xy-shear strain
(13) k exz
Kelvin xz-shear strain
(14) k eyy
Kelvin strain in y-direction
(15) k eyz
Kelvin yz-shear strain
(16) k ezz
Kelvin strain in z-direction
See Section 1 in Constitutive Models for details.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 299

Crushed Salt Model ZONE model cwipp

(1) a wipp
(2) act energy
(3) b f
(4) b wipp
(5) b0
(6) b1
(7) b2
(8) bulk
(9) d f
(10) d wipp
(11) density
(12) e dot star
(13) gas c
(14) n wipp
(15) rho
(16) s f
(17) shear
(18) temp

WIPP model constant, A

activation energy, Q
final, intact salt, bulk modulus, Kf
WIPP model constant, B
creep compaction parameter, B0
creep compaction parameter, B1
creep compaction parameter, B2
elastic bulk modulus, K
final, intact salt, density, f
WIPP model constant, D
mass density,

critical steady-state creep rate, ss

gas constant, R
WIPP model exponent, n
density,
final, intact salt, shear modulus, Gf
elastic shear modulus, G
zone temperature, T

The following calculated properties can be printed, plotted or accessed via FISH:
(19) frac d
(20) s g1
(21) s k1

current fractional density, Fd

creep compaction parameter, G
creep compaction parameter, K

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

1 - 300
ZONE

Command Reference

Double-Yield ZONE model doubleyield

(1) bulk
maximum elastic bulk modulus, K
(2) cap pressure current intersection of volumetric yield surface (cap) with
pressure (mean stress) axis, pc
(3) cohesion
cohesion, c
(4) cptable
number of table relating cap pressure to plastic volume strain
(5) ctable
number of table relating cohesion to plastic shear strain
(6) density
mass density,
(7) dilation
dilation angle,
(8) dtable
number of table relating dilation angle to plastic shear strain
(9) ev plastic
accumulated plastic volumetric strain
(10) friction
angle of internal friction,
(11) ftable
number of table relating friction angle to plastic shear strain
(12) multiplier
multiplier on current plastic cap modulus to give elastic bulk
and shear moduli, R
(13) shear
maximum elastic shear modulus, G
(14) tension
tension limit, t
(15) ttable
number of table relating tensile limit to plastic tensile strain
Plasticity state indicator flags are given below. Use logical and to find individual
and multiple state modes.
Bit
Number
1
2
4
8
256
512

State
failure
failure
failure
failure
failure
failure

in
in
in
in
in
in

shear now
tension now
shear in the past
tension in the past
volume now
volume in the past

The strain-hardening and -softening behavior is controlled by the variation in friction,

cohesion and dilation as a function of plastic shear strain, and tension limit as a
function of plastic tensile strain, given by a specified table of values. The variation
in cap pressure is a function of plastic volumetric strain. Note that if table numbers
are given as 0 (default), the properties will take the values given (i.e., with the
cohesion, dilation, friction, tension or cap pressure keyword).

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 301

The following calculated properties can be printed, plotted or accessed via FISH:
(16) es plastic
accumulated plastic shear strain
(17) et plastic
accumulated plastic tensile strain
(18) ev plastic
accumulated plastic volumetric strain
See Section 1 in Constitutive Models for details.

3DEC Version 5.0

1 - 302
ZONE

Command Reference

Drucker-Prager ZONE model drucker

(1)
(2)
(3)
(4)
(5)
(6)
(7)

bulk
density
kshear
qdil
qvol
shear
tension

elastic bulk modulus, K

mass density,
material parameter, k
material parameter, q
material parameter, q
elastic shear modulus, G
tension limit, t

Plasticity state indicator flags are given below. Use logical and to find individual
and multiple state modes.
Bit
Number
1
2
4
8

State
failure
failure
failure
failure

in
in
in
in

shear now
tension now
shear in the past
tension in the past

See Section 1 in Constitutive Models for details.

Note that the default tension limit is zero for a material with q = 0, and is k /q
otherwise. The value assigned for the tension limit remains constant when tensile
failure occurs.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 303

Isotropic Elastic ZONE model elastic

(1) bulk
(2) density
(3) shear

elastic bulk modulus, K

mass density,
elastic shear modulus, G

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

1 - 304
ZONE

Command Reference

Hoek-Brown ZONE model hoekbrown

p

(1) atable

number of table relating a to e3

(2) bulk
(3) citable

bulk modulus, K
p
number of table relating ci to e3

(4) density
(5) hb e3plas

mass density,
p
accumulated plastic strain, e3

(6) hb ind
(7) hba
(8) hbmb
(9) hbs
(10) hbs3cv

plasticity indicator (as Mohr Coulomb)

Hoek-Brown parameter, a
Hoek-Brown parameter, mb
Hoek-Brown parameter, s
Hoek-Brown parameter, 3cv

(11) hbsigci

Hoek-Brown parameter, ci

(12) mtable

number of table relating to mb to e3

(13) multable
(14) shear
(15) stable

number of table relating a multiplier to 3

shear modulus, G
p
number of table relating s to e3

Bit
Number
1
2

State
failure in shear now
failure in shear in the past

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 305

Modified Hoek-Brown ZONE model mhoekbrown

(1)
(2)
(3)
(4)
(5)

atable
bulk
citable
density
hb doption

(6) hb len
(7) hb poption

(8) hb soption
(9) hba
(10) hbmb
(11) hbpsi
(12) hbs
(13) hbsigci
(14) hbtension
(15) mtable
(16) shear
(17) stable
(18) ttable

number of table relating a to the evolution parameter

elastic bulk modulus, K
number of table relating ci to the evolution parameter
mass density,
= 0 to input a constant dilation angle specified by hbpsi (default)
= 1 to specify associated plastic flow; c = c
= val where val is a fraction of friction angle, c (c = val c )
calibration length to calibrate model properties to account for zone size
= 0 for evolution parameter set to plastic strain in direction of least
compressive principal stress
= 1 for evolution parameter set to plastic shear strain (default)
= 0 for SOLVE fos solution controlled by shear strength (default)
= 1 for SOLVE fos solution controlled by unconfined compressive strength
Hoek-Brown parameter, a
Hoek-Brown parameter, mb
dilation angle, c (specified if hb doption = 0)
Hoek-Brown parameter, s
Hoek-Brown parameter, ci
current value of tensile strength, t
number of table relating mb to the evolution parameter
elastic shear modulus, G
number of table relating s to the evolution parameter
number of table relating t to plastic tensile strain

The following properties can be printed, plotted or accessed via FISH:

(19) hb
(20) hb
(21) hb
(22) hb
(23) hb
(24) hb

aac
cohesion
dilation
friction
mmc
plas

(25) hb scc
(26) hb ssc

current value of a
current value of cohesion, cc
current value of dilation angle, c
current value of friction angle, c
current value of mb
plastic strain in direction of least compressive principal stress
(if hb poption = 0)
current value of ci
current value of s

Plasticity state indicator flags are given below. Use logical and to find individual
and multiple state modes.

3DEC Version 5.0

1 - 306
ZONE

Command Reference

Bit
Number
1
2
4
8

State
failure
failure
failure
failure

in
in
in
in

shear now
tension now
shear in the past
tension in the past

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 307

Mohr-Coulomb ZONE model mohr

(1)
(2)
(3)
(4)
(5)
(6)
(7)
(8)

bulk
brittle
cohesion
density
dilation
friction
shear
tension

elastic bulk modulus, K

brittle failure mode (true/false)
cohesion, c
mass density,
dilation angle,
internal angle of friction,
elastic shear modulus, G
tension limit, t

Plasticity state indicator flags are given below. Use logical and to find individual
and multiple state modes.
Bit
Number
1
2
4
8

State
failure
failure
failure
failure

in
in
in
in

shear now
tension now
shear in the past
tension in the past

See Section 1 in Constitutive Models for details.

Note that the default tension limit is zero for a material with no friction, and is
c/tan otherwise. The value assigned for the tension limit remains constant when
tensile failure occurs. If brittle is set to true, tension limit will drop to zero after
tensile failure occurs.

3DEC Version 5.0

1 - 308
ZONE

Command Reference

Orthotropic Elastic ZONE model orthotropic

(1) dd
(2) density
(3) dip
(4) e1
(5) e2
(6) e3
(7) g12
(8) g13
(9) g23
(10) nu12
(11) nu13
(12) nu23
(13) nx
(14) ny
(15) nz
(16) rot

dip direction of plane defined by axes 1 -2

mass density,
dip angle of plane defined by axes 1 -2
Youngs modulus in direction 1
Youngs modulus in direction 2
Youngs modulus in direction 3
shear modulus in planes parallel to axes 1 -2
shear modulus in planes parallel to axes 1 -3
shear modulus in planes parallel to axes 2 -3
Poissons ratio characterizing lateral contraction in direction 1
when tension is applied in direction 2
Poissons ratio characterizing lateral contraction in direction 1
when tension is applied in direction 3
Poissons ratio characterizing lateral contraction in direction 2
when tension is applied in direction 3
x-component of unit normal to plane defined by axes 1 -2
y-component of unit normal to plane defined by axes 1 -2
z-component of unit normal to plane defined by axes 1 -2
rotation angle between the 1 axis and the dip-direction vector,
defined positive, clockwise from the dip-direction vector

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 309

Power Law ZONE model power

(1)
(2)
(3)
(4)
(5)
(6)

a1
a2
bulk
density
n1
n2

power-law constant, A1
power-law constant, A2
elastic bulk modulus, K
mass density,
power-law exponent, n1
power-law exponent, n2
ref

(7) rs 1

reference stress, 1

(8) rs 2

reference stress, 2

(9) shear

elastic shear modulus, G

ref

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

1 - 310
ZONE

Command Reference

WIPP-Creep Viscoplastic Model ZONE model pwipp

(1) a wipp
(2) act energy
(3) b wipp
(4) bulk
(5) d wipp
(6) density
(7) e dot star
(8) gas c
(9) kshear
(10) n wipp
(11) qdil
(12) qvol
(13) shear
(14) temp
(15) tension

WIPP model constant, A

activation energy, Q
WIPP model constant, B
elastic bulk modulus, K
WIPP model constant, D
mass density,

critical steady-state creep rate, ss

gas constant, R
material parameter, k
WIPP model exponent, n
material parameter, qk
material parameter, q
elastic shear modulus, G
zone temperature, T
tension limit, t

Plasticity state indicator flags are given below. Use logical and to find individual
and multiple state modes.
Bit
Number
1
2
4
8

State
failure
failure
failure
failure

in
in
in
in

shear now
tension now
shear in the past
tension in the past

The following calculated properties can be printed, plotted or accessed via FISH:
(16) e prime
primary creep strain
(17) e rate
primary creep rate
(18) es plastic
accumulated plastic shear strain
(19) et plastic
accumulated plastic tensile strain
See Section 1 in Constitutive Models for details.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 311

Strain-Hardening/Softening ZONE model strainsoftening

(1) bulk
(2) cohesion
(3) ctable
(4) density
(5) dilation
(6) dtable
(7) friction
(8) ftable
(9) shear
(10) tension
(11) ttable

elastic bulk modulus, K

cohesion, c
number of table relating cohesion to plastic shear strain
mass density,
dilation angle,
number of table relating dilation angle to plastic shear strain
angle of internal friction,
number of table relating friction angle to plastic shear strain
elastic shear modulus, G
tension limit, t
number of table relating tension limit to plastic tensile strain

Plasticity state indicator flags are given below. Use logical and to find individual
and multiple state modes.
Bit
Number
1
2
4
8

State
failure
failure
failure
failure

in
in
in
in

shear now
tension now
shear in the past
tension in the past

The strain-hardening and -softening behavior is controlled by the variation in friction,

cohesion and dilation as a function of plastic shear strain given by a specified table
of values. Variation of tensile strength as a function of plastic tensile strain is also
specified by a table. Note that if table numbers are given as 0 (default), the properties
will take the values given (i.e., with cohesion, dilation, friction or tension keyword).
The following calculated properties can be printed, plotted or accessed via FISH:
(12) es plastic
(13) et plastic

plastic shear strain

plastic tensile strain

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

1 - 312
ZONE

Command Reference

Bilinear, Strain-Hardening/Softening Ubiquitous-Joint ZONE model subiquitous

(1) bijoint
(2) bimatrix
(3) bulk
(4) c2table
(5) cj2table
(6) cjtable
(7) co2
(8) cohesion
(9) ctable
(10) d2table
(11) density
(12) di2
(13) dilation
(14) dj2table
(15) djtable
(16) dtable
(17) f2table
(18) fj2table
(19) fjtable
(20) fr2
(21) friction
(22) ftable
(23) jc2
(24) jcohesion

3DEC Version 5.0

= 0 for joint linear model (default);

= 1 for joint bilinear model
= 0 for matrix linear model (default);
= 1 for matrix bilinear model
elastic bulk modulus, K
number of table relating matrix cohesion c2 to matrix plastic
shear strain
number of table relating joint cohesion cj 2 to joint plastic
shear strain
number of table relating joint cohesion cj 1 to joint plastic
shear strain
matrix cohesion, c2
matrix cohesion, c1
number of table relating matrix cohesion c1 to matrix plastic
shear strain
number of table relating matrix dilation 2 to matrix plastic
shear strain
mass density,
matrix dilation angle, 2
matrix dilation angle, 1
number of table relating joint dilation j 2 to joint plastic
shear strain
number of table relating joint dilation j 1 to joint plastic
shear strain
number of table relating matrix dilation angle 1 to matrix
plastic shear strain
number of table relating matrix friction angle 2 to matrix
plastic shear strain
number of table relating joint friction angle j 2 to joint
plastic shear strain
number of table relating joint friction angle j 1 to joint
plastic shear strain
matrix friction angle, 2
matrix friction angle, 1
number of table relating matrix friction 1 angle to matrix
plastic shear strain
joint cohesion, cj 2
joint cohesion, cj 1

COMMAND REFERENCE
ZONE

1 - 313

(25) jd2
(26) jddirection
(27) jdilation
(28) jdip
(29) jf2
(30) jfriction
(31) jnx
(32) jny
(33) jnz
(34) jtension

joint dilation angle, j 2

dip direction of weakness plane
joint dilation angle, j 1
dip angle of weakness plane
joint friction angle, j 2
joint friction angle, j 1
x-component of unit normal to weakness plane
y-component of unit normal to weakness plane
z-component of unit normal to weakness plane
joint tension limit, jt

(35) shear
(36) tension
(37) tjtable

elastic shear modulus, G

matrix tension limit, t
number of table relating joint tension limit jt to joint
plastic tensile strain
number of table relating matrix tension limit t to matrix
plastic tensile strain

(38) ttable

Plasticity state indicator flags are given below. Use logical and to find individual
and multiple state modes.
Bit
Number
1
2
4
8
16
32
64
128

State
matrix failure in shear now
matrix failure in tension now
matrix failure in shear in the past
matrix failure in tension in the past
joint failure in shear now
joint failure in tension now
joint failure in shear in the past
joint failure in tension in the past

The following calculated properties can be printed, plotted or accessed via FISH:
(39) es plastic
(40) esj plastic
(41) et plastic
(42) etj plastic

plastic shear strain

joint plastic shear strain
plastic tensile strain
joint plastic tensile strain

See Section 1 in Constitutive Models for details.

Note that the default tension limits for the matrix and weakness planes are the same
as those for the ubiquitous-joint model.

3DEC Version 5.0

1 - 314
ZONE

Command Reference

Table 1.6 Property groups by failure segment for the bilinear,

strain-hardening/softening ubiquitous-joint model
Properties

Description

general

bijoint

<ttable>

1 for bilinear joint law

0 for linear joint law (default)
1 for bilinear matrix law
0 for linear matrix law (default)
bulk modulus
dip direction of weakness plane
dip angle of weakness plane
x-comp. of unit normal to weakness plane
y-comp. of unit normal to weakness plane
z-comp. of unit normal to weakness plane
tension limit of joint segments 1 and 2
shear modulus
tension limit of matrix segments 1 and 2

cohesion
dilation
friction

<ctable>
<dtable>
<ftable>

cohesion
dilation (degree)
friction (degree)

co2
di2
fr2

<c2table>
<d2table>
<f2table>

cohesion
dilation (degree)
friction (degree)

jcohesion
jdilation
jfriction

<cjtable>
<djtable>
<fjtable>

cohesion
dilation (degree)
friction (degree)

jc2
jd2
jf2

<cj2table>
<dj2table>
<fj2table>

cohesion
dilation (degree)
friction (degree)

bimatrix
bulk
jddirection
jdip
jnx
jny
jnz
jtension
shear
tension

<tjtable>

matrix-segment 1

matrix-segment 2

joint-segment 1

joint-segment 2

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 315

Ubiquitous-Joint ZONE model ubiquitous

(1) bulk
(2) cohesion
(3) density
(4) dilation
(5) friction
(6) jcohesion
(7) jddirection
(8) jdilation
(9) jdip
(10) jfriction
(11) jnx
(12) jny
(13) jnz
(14) jtension

elastic bulk modulus, K

cohesion of matrix, c
mass density,
dilation angle of matrix,
internal angle of friction of matrix,
joint cohesion, cj
dip direction of weakness plane
joint dilation angle, j
dip angle of weakness plane
joint friction angle, j
x-component of unit normal to weakness plane
y-component of unit normal to weakness plane
z-component of unit normal to weakness plane
joint tension limit, jt

(15) shear
(16) tension

elastic shear modulus, G

tension limit of matrix, t

Plasticity state indicator flags are given below. Use logical and to find individual
and multiple state modes.
Bit
Number
1
2
4
8
16
32
64
128

State
matrix failure in shear now
matrix failure in tension now
matrix failure in shear in the past
matrix failure in tension in the past
joint failure in shear now
joint failure in tension now
joint failure in shear in the past
joint failure in tension in the past

See Section 1 in Constitutive Models for details.

Note that the default tension limit of the matrix, t , is the same as that for the MohrCoulomb model. The default joint tension limit, jt , is zero if j = 0, and is cj /tanj
otherwise. The values assigned for t and jt remain constant when tensile failure
occurs in the matrix or on the weakness plane.

3DEC Version 5.0

1 - 316
ZONE

Command Reference

Classical Viscoelastic (Maxwell subst.) ZONE model viscous

(1)
(2)
(3)
(4)

bulk
density
shear
viscosity

elastic bulk modulus, K

mass density,
elastic shear modulus, G
dynamic viscosity,

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

COMMAND REFERENCE
ZONE

1 - 317

WIPP Model ZONE model wipp

(1) a wipp
(2) act energy
(3) b wipp
(4) bulk
(5) d wipp
(6) density
(7) e dot star
(8) gas c
(9) n wipp
(10) shear
(11) temp

WIPP model constant, A

activation energy, Q
WIPP model constant, B
elastic bulk modulus, K
WIPP model constant, D
mass density,

critical steady-state creep rate, ss

gas constant, R
WIPP model exponent, n
elastic shear modulus, G
zone temperature, T

The following calculated properties can be printed, plotted or accessed via FISH:
(12) e prime
(13) e rate

accumulated primary creep strain

accumulated primary creep strain rate

See Section 1 in Constitutive Models for details.

3DEC Version 5.0

1 - 318

Command Reference

1.4 References
Westergaard, H. M. Water Pressure on Dams During Earthquakes,Proceedings of ASCE, Transactions number 98, Vol. 59, No. 8, Part 3 (1933).

3DEC Version 5.0

COMMAND REFERENCE

1 - 319

1.5 Appendices
1.5.1 Scalar Text File Format
ITASCA SCALAR3D
; The line above is a text mode header indicator -- it is required for the
; file to be recognized as a scalar data text file.
; Comment field -- any text after a semicolon is ignored. Blank lines are
; ignored.
; The following first
; All data are comma- and space-delimited.
GROUP s name ; All scalars following are assigned group name name to the
; slot s.
; GROUP statements can be added later in the file,
; adding to or replacing previous GROUP assignments.
EXTRA i val ; All scalars following are assigned extra data val in the ith
; index.
; EXTRA statements can be added later in
; the file, adding to or replacing previous EXTRA assignments.
x y z EXTRA i val <i val> ... GROUP s name <s name> ...
x y z value EXTRA i val <i val> ... GROUP s name <s name> ...
; Each line indicates a single scalar object. The EXTRA and GROUP keywords
; are optional.
; each EXTRA and GROUP keyword (there can be more than one per line) can
; be followed
; by any number of index value pairs, indicating the index of slot the
; value should be made to.
; Group names are strings (" delimited for embedded spaces).
; EXTRA data can be a string, an integer, or a real.

3DEC Version 5.0

1 - 320

Command Reference

1.5.2 Scalar Binary File Format

0x03714711 (unsigned 32 bit integer indicating it is binary scalar data)
3 (unsigned 8 bit integer indicating 2 or 3 dimensions)
Each scalar:
x y z as double precision
value as double precision
uint32 as number of extra, following by that many extra.
uint32 as number of group names, following by that many strings.
extra: uint8 as type code (0= 64 bit signed int, 1 = 64 bit double
precision, 2 = string).
string: uint16 as string length, that many uint16 as string contents.

3DEC Version 5.0

COMMAND REFERENCE

1 - 321

1.5.3 Vector Text File Format

ITASCA VECTOR3D
; The line above is a text mode header indicator -- it is required for the
; file to be recognized as a scalar data text file.
; Comment field -- any text after a semicolon is ignored. Blank lines are
; ignored.
; The following first
; All data are comma- and space-delimited.
GROUP s name ; All scalars following are assigned group name name to the
; slot s.
; GROUP statements can be added later in the file,
; adding to or replacing previous GROUP assignments.
EXTRA i val ; All scalars following are assigned extra data val in the ith
; index.
; EXTRA statements can be added later
; in the file, adding to or replacing previous EXTRA
; assignments.
x y z vx vy vz EXTRA i val <i val> ... GROUP s name <s name> ...
; The above format is the position/vector value version, other valid
; formats are:
x y z vx vy vz MAG m EXTRA i val <i val> ... GROUP s name <s name> ...
; In the above format, (vx,vy,vz) is taken as a direction vector with a
; magnitude of m.
x y z DIR dip dd m EXTRA i val <i val> ... GROUP s name <s name> ...
; In the above format, the direction is given by dip and dip direction,
; with magnitude m.
; Each line indicates a single vector object. The EXTRA and GROUP keywords
; are optional.
; each EXTRA and GROUP keyword (there can be more than one per line) can
; be followed by any number of index value pairs, indicating the index of
; slot the value should be made to.
; Group names are strings (" delimited for embedded spaces).
; EXTRA data can be a string, an integer, or a real.

3DEC Version 5.0

1 - 322

Command Reference

1.5.4 Vector Binary File Format

0x03714712 (unsigned 32 bit integer indicating it is binary vector data)
3 (unsigned 8 bit integer indicating 2 or 3 dimensions)
Each scalar:
x y z as double precision
vx vy vz as vector value
uint32 as number of extra, following by that many extra.
uint32 as number of group names, following by that many strings.
extra: uint8 as type code (0= 64 bit signed int, 1 = 64 bit double
precision, 2 = string).
string: uint16 as string length, that many uint16 as string contents.

3DEC Version 5.0

COMMAND REFERENCE

1 - 323

1.5.5 Tensor Text File Format

ITASCA TENSOR3D
; The line above is a text mode header indicator -- it is required for the
; file to be recognized as a scalar data text file.
; Comment field -- any text after a semicolon is ignored. Blank lines are
; ignored.
; The following first
; All data are comma- and space-delimited.
GROUP s name ; All scalars following are assigned group name name to the
; slot s.
; GROUP statements can be added later in the file,
; adding to or replacing previous GROUP assignments.
EXTRA i val ; All scalars following are assigned extra data val in the ith
; index.
; EXTRA statements can be added later in
; the file, adding to or replacing previous EXTRA
; assignments.
x y z s11 s22 s33 s12 s13 s23 EXTRA i val <i val> ...
GROUP s name <s name> ...
; The above format is the position/tensor value version, other valid
; formats are:
x y z PRIN p1 p2 p3 NORM# vx vy vz DIR# dip dd EXTRA i val <i val> ...
GROUP s name <s name> ...
; In the above format, the tensor is given in terms of its principal
; values and directions.
; NORM# indicates NORM1, NORM2, or NORM3 -- DIR# is the same.
; At least two principal directions must be given using either DIR# or
; NORM#.
; Each line indicates a single vector object. The EXTRA and GROUP keywords
; are optional.
; each EXTRA and GROUP keyword (there can be more than one per line) can
; be followed by any number of index value pairs, indicating the index
; of slot the value should be made to.
; Group names are strings (" delimited for embedded spaces).
; EXTRA data can be a string, an integer, or a real.

3DEC Version 5.0

1 - 324

Command Reference

1.5.6 Tensor Binary File Format

0x03714713 (unsigned 32 bit integer indicating it is binary tensor data)
3 (unsigned 8 bit integer indicating 2 or 3 dimensions)
Each tensor:
x y z as double precision
s11 s22 s33 s12 s13 s23 as double values
uint32 as number of extra, following by that many extra.
uint32 as number of group names, following by that many strings.
extra: uint8 as type code (0= 64 bit signed int, 1 = 64 bit double
precision, 2 = string).
string: uint16 as string length, that many uint16 as string contents.

3DEC Version 5.0

COMMAND REFERENCE

1 - 325

1.5.7 Geometry Text File Format

ITASCA GEOMETRY3D
; The line above is a text mode header indicator -- it is required for the
; file to be recognized as a scalar data text file.
; Comment field -- any text after a semicolon is ignored. Blank lines are
; ignored.
; The following first
; All data are comma- and space-delimited.
GROUP s name ; All objects following are assigned group name name to the
; slot s.
; GROUP statements can be added later in the file,
; adding to or replacing previous GROUP assignments.
EXTRA i val ; All objects following are assigned extra data val in the ith
; index.
; EXTRA statements can be added later
; in the file, adding to or replacing previous EXTRA
; assignments.
NODES ; lines following are assumed to be nodes. Note that all IDs are
; LOCAL to the file, and do not (necessarily) correspond to ID
; numbers assigned in the code.
; Also note that GROUP and EXTRA statements can be inserted into
; the node list.
id x y z EXTRA i val <i val> ... GROUP s name <s name> ...
id x y z EXTRA i val <i val> ... GROUP s name <s name> ...
id x y z EXTRA i val <i val> ... GROUP s name <s name> ...
; Each line indicates a single node. ID numbers need not be sequential, but
; they must be unique for each object type in a file. The EXTRA and GROUP
; keywords are optional.
; each EXTRA and GROUP keyword (there can be more than one per line) can
; be followed by any number of index value pairs, indicating the index of
; slot the value should be made to.
; Group names are strings (" delimited for embedded spaces).
; EXTRA data can be a string, an integer, or a real.
EDGES ; lines following are assumed to be edges
id node1 node2 EXTRA i val <i val> ... GROUP s name <s name> ...
id node1 node2 EXTRA i val <i val> ... GROUP s name <s name> ...
id POINT x y z x y z EXTRA i val <i val> ... GROUP s name <s name> ...
POLYS ; lines following are assumed to be polygons. The specification
formats are available:
id edge1 edge2 edge3 ... EXTRA i val <i val> ...
GROUP s name <s name> ...
id edge1 edge2 edge3 ... EXTRA val <i val> ...
GROUP s name <s name> ...
id NODE node1 node2 node3 ... EXTRA i val <i val> ...
GROUP s name <s name> ...

3DEC Version 5.0

1 - 326
1.5.7 Geometry Text File Format

Command Reference

id NODE node1 node2 node3 ... EXTRA i val <i val> ...
GROUP s name <s name> ...
id POINT x y z x y z x y z ... EXTRA i val <i val> ...
GROUP s name <s name> ...
id POINT x y z x y z x y z ... EXTRA i val <i val> ...
GROUP s name <s name> ...
;
;
;
;

Note that if the NODE format is used, it is not necessary to specify

edges
If the POINT format is used, it is not necessary to specify edges or
nodes.

3DEC Version 5.0

COMMAND REFERENCE

1 - 327

1.5.8 Geometry Binary File Format

0x03714714 (unsigned 32 bit integer indicating it is binary geometry data)
; Repeat objects
quint8 code indicating type of object (0=node, 1=edge, 2=polygon).
Node:
uint64 as id
x y z as double precision
uint32 as number of extra, followed by that many extra
uint32 as number of group names, followed by that many strings
Edge: uint64 as id
uint64 as node 1 id
uint64 as node 2 id
uint32 as number of extra, followed by that many extra
uint32 as number of group names, followed by that many strings
Poly: uint64 as id
series of uint64 as edge id, with a value of 0 indicating no more edges
uint32 as number of extra, followed by that many extra
uint32 as number of group names, followed by that many strings
extra: uint8 as type code (0= 64 bit signed int, 1 = 64 bit double
precision, 2 = string).
string: uint16 as string length, that many uint16 as string contents.

3DEC Version 5.0

1 - 328

Command Reference

1.5.9 3DEC Ball Plot Item File Format

Ball plot items consist of a space delimited ASCII-formatted file and read by FISHLab3D. Any
number of extra FISH variables can be included for each ball and displayed in 3DEC using the
colorbyvalue attribute. If no extra variables are to be included, a zero can be specified.
Each ball may be associated with an optional label. If not present in the data file, the word default
will be displayed as the label in 3DEC. When used, each label must be surrounded by double
quotation marks.
The file format is as follows:
;ANY HEADER IN THE TOP LINE
NUMBER OF BALLS IN MODEL NUMBER OF EXTRA DATA
LABEL ID # X-POS Y-POS Z-POS BALL RADIUS EXTRA1 EXTRA2 ... EXTRAn
;This file contains 3 balls and each one has
;plotting.
3 4
Quartzite 1 0.0 0.0 0.0 5.0 12.223 0.002 1
Limestone 2 5.0 10.0 -1.0 1.0 88.067 0.109
Sandstone 3 -3.0 2.0 0.2 9.0 0.261 1.812 0

3DEC Version 5.0

4 EXTRA property variables for

12
0 12
12

COMMAND REFERENCE

1 - 329

1.5.10 3DEC Disk Plot Item File Format

Disk plot items consist of a space-delimited ASCII-formatted file. Any number of extra FISH
variables can be included for each disk, and displayed in 3DEC using the colorbyvalue attribute. If
no extra variables are to be included, a zero can be specified. Each disk may be associated with an
optional label. If not present, the word default will be displayed. When used, each label must be
surrounded by double quotation marks.
The format is as follows:
;ANY HEADER IN THE TOP LINE
NUMBER OF DISKS IN MODEL NUMBER OF EXTRA DATUM
LABEL ID # X-POS Y-POS Z-POS DIP DIP/DIR DISK RADIUS EXTRA1 EXTRA2 ...
EXTRAn
;This file contains 4 circular joints and each one has no EXTRA property
;variables to be plotted.
4 0
Set 1 1 0.0 0.0 0.0 23.0 256.0 5.6
Set 1 2 10.0 10.0 0.0 78.0 45.0 15.0
Set 2 3 10.0 15.0 -10.0 3.0 358.0 50.0
Set 3 4 5.0 5.0 17.0 -90 0.0 8.1

3DEC Version 5.0

1 - 330

Command Reference

1.5.11 Itasca DFN Data File Format

;The first line of the geometry file is a comment that is read and then
;discarded. The second line gives the total number of fracture blocks (num)
;as an integer.

header text
num
;Each fracture block begins with a line delineating the fracture number,
;the property set number, the number of vertices and a set of extra
;variables, as shown:
<fn> <pn> <vn> <e1> <e2> ...
;fn -- fracture number (integer, >= 1)
;pn -- property set number (integer, >= 1)
;vn -- number of vertices (integer, = 2 for 2D, = 1 for 3D disk, >= 3 for
3D planar polygons)
;Each extra variable is stored with the fracture and is accessible
;through FISH.
Note that fractures may have different numbers of extra
;values associated with them.
For 3D disks, the following line is
<cen x> <cen y> <cen z> <dip> <dd> <rad>
;cen

x -- center, x-component (float)

;cen

y -- center, y-component (float)

;cen

z -- center, z-component (3D only, float)

;dip -- dip (float, degrees)

;dd -- dip direction (3D only, float, degrees)
;rad -- radius (float)
For all other fractures, the following
<vn x> <vn y> <vn z> (3D)
<vn x> <vn y> (2D)

3DEC Version 5.0

vn lines are given by

COMMAND REFERENCE
1.5.11 Itasca DFN Data File Format
;vn

x -- polygonal vertex, x-component (float)

;vn

y -- polygonal vertex, y-component (float)

;vn

z -- polygonal vertex, z-component (float, 3D only)

1 - 331

One additional line finishes the fracture block:

<dip> <dd>
;dip -- dip (float, degrees)
;dd -- dip direction (3D only, float, degrees)

3DEC Version 5.0

1 - 332

Command Reference

1.5.12 DFN-Related File Formats

Bootstrapped distribution le format
1 header line
x lines defining the discrete distribution. Each contains an ID, followed by the n values of the
distribution (1 value for a 1D distribution, 2 values for a 2D distribution, etc.). A last optional
column defines the quantity for these values. If not given, all values have the same probability.
Separators can be space, tab, comma or semicolons.
The end of the file is specified by any empty line.
Example:
;ID
1
2
3
4
5
6
7
8
9
10
11
12

DIP
44.533
55.795
56.963
40.202
18.688
77.365
84.337
61.177
38.481
54.472
66.587
42.269

DipDir
195.3
218.98
209.31
344.11
98.29
295.8
237.87
290.59
108.53
97.35
288.12
126.88

weight
1.52
2.49
2.34
1.61
1
5.76
5.76
5.76
1.06
1.23
5.76
1.11

DFN template le format

1 header line
A group starting with <info> and ending with <\info> defining the template information. Each
info is given in a single line under the format info name info value.
A group starting with <stats> and ending with <\stats> defining the statistical distributions. This
group must contain a <size> . . . <\size> group, a <orientation> . . . <\orientation> group and
a <position> . . . <\position> group. For each distribution, the parameters are given (1 by line)
under the format param name param values. These parameters are:
The dimension of the distribution, defined as dim (e.g., dim 1)
The type of the distribution, defined as type (e.g., type 1). 1 stands for uniform, 2 stands
for Gaussian, 3 for power-law, 4 for bootstrapped and 5 for fish function.
The parameters of the distribution, defined as parameters, consistently with the type (e.g.,
parameters 1.0 0.5 for a Gaussian distribution)
The range of acceptable values, defined as bound (e.g., bounds 20 50 for 1D orientation)

3DEC Version 5.0

COMMAND REFERENCE
1.5.12 DFN-Related File Formats

1 - 333

Example:
;ITASCA DFN Template File
<info>
name example
<\info>
<stats>
<size>
dim 1
type 2
parameters 4.0
bounds 1.0 +inf
<\size>
<orientation>
dim 2
type 1
parameters
bounds 0 0 180 360
<\orientation>
<position>
dim 3
type 1
parameters
bounds -5 -5 -5 5 5 5
<\position>
<\stats>

DFN property le format

line 1: comment, read and discarded.
line 2: comma or space separated list of the properties given to be specified in the following lines.
Each fracture in a DFN will have the same set of properties at import and use the same contact
model. Different DFNs may have different sets of properties and also use different contact models.
Not all properties must be specified. When a property is not specified, the property is kept at its
default value. When using the smooth joint contact model it is not necessary for the user to specify
the dip or dd (e.g., dip direction) properties, as these are inherited from the fractures. There is no
guarantee that the exported property order will be the same as the imported property order.
line 3: total number of property sets (integer 1)
For each property set, 1 line contains all of the properties in the order specified in line 2. These
can either be integers or doubles. For instance, when using the smooth joint contact model, the file
may look like
sj kn sj ks sj fric sj da sj bmode sj bns sj bcoh sj bfa sj rmul sj large
1
1e5 1e6 0.6 0 0 1e5 1e3 0.6 1.1 0

3DEC Version 5.0

1 - 334
1.5.12 DFN-Related File Formats

3DEC Version 5.0

Command Reference