3DEC 7 for 3DEC 5.2 Users

3DEC 7 represents a major change from 3DEC 5.2 and previous versions. As well as many improvements and new features (New in Version 7), 3DEC 7 uses a whole new command and FISH syntax, plotting system, and documentation system.

Command and FISH Syntax

The change in command and FISH syntax is the first overhaul of the command system since 3DEC was first released in 1988. The new scheme addresses the many inconsistencies and cryptic syntax that has crept in over the last 30 years. In Version 7, all commands and FISH functions follow the pattern of NOUN-VERB-OPTIONS-MODIFIERS-RANGE. For example BLOCK APPLY VELOCITY RANGE POSITION-X 0 10. As in version 5.2, it is not necessary to type out the entire word. The new system has the following advantages:

  • It is clear what is being operated on with every command (blocks, faces, gridpoints, etc.).
  • The commands and FISH are as similar as possible (and in many cases the same) as FLAC3D 7 and UDEC 7 to make it easier for users to switch between programs
  • The new system allows for coupling between FLAC3D, PFC and 3DEC. The use of FLAC3D structural elements is already built in to 3DEC 7

To make it easier for experienced users to start using Version 7, several tools are provided:

  • Automatic file conversion from 3DEC (Conversion of 5.2 and older Data Files)
  • Documents for mapping 5.2 commands and FISH to 7.0 commands and FISH (3DEC 5.2 to 7.0 Command Mapping)
  • Contextual help. Press F1 when your cursor is over a command to get the full help entry for that command
  • Intelligent command completion (inline help). Use Ctrl-Space as you are typing a command to see a list of possible following keywords.


In 3DEC 5.2 (and earlier) it was possible to assign material properties to a material number, and then specify material numbers for zones and joints. This is no longer possible. Material properties are now assigned directly to zones and joints (block zone property and block contact property). Also, there is no default constitutive model for zones as there was in version 5.2. Zone constitutive models must be assigned before assigning properties (block zone cmodel assign). Contacts will still default to Mohr-Coulomb material as in 5.2. To assign a different constitutive model use cmd:\(block.contact.jmodel.assign\).

There are also no defaults for the joint material properties. If running in large strain, where new contacts may form, it is necessary to set these defaults. See block contact material-table.

Large Strain

In Version 5.2, large-strain analysis was the default. In Version 7, the user must specify whether running in large or small strain before cycling using the command model large-strain.


In 3DEC 5.2, looping was generally done with linked lists. This was cumbersome and confusing, especially for gridpoints or zones, which required looping through blocks and then looping through each gridpoint or zone for each block.

The new FISH allows for the use of FOREACH to loop through items. For example:

fish define myfunction
  loop foreach zone block.zone.list
    ; do something

What used to be eight lines of FISH is now two.

Another difference is that in version 7, FISH variables must be assigned a value or declared as local or global prior to being used. This is to prevent the problem of having variables in an equation that contain a typo and therefore form a new variable with a value of 0.

New Features in Version 7.0

Commands and Scripting

  • Syntax is totally updated for commands and FISH to make it more intuitive and more consistent with other Itasca programs.
  • The new conversion tool (see Conversion of 5.2 and older Data Files below) converts commands and FISH from old syntax to new syntax.
  • The HTML help system can be displayed in a window in 3DEC or in a separate browser.
  • Possible command keywords can be displayed as while typing using CTRL-space.
  • Display of global FISH symbols as calculation progresses.
  • New variable types include: Boolean, Symmetric Tensor (e.g., stress and strain), Matrix (with built-in functions to inverse, multiply, etc.), Map (or associative array), and Structures.
  • FISH foreach construct can now be used for 3DEC objects. This greatly simplifies 3DEC FISH.

Figure 3: Looping through all zones in a model in 3DEC 5.2 (left) and 3DEC 7 (right)

  • FISH functions are now available for all objects, including structural elements.
  • Multi-threaded FISH is now available. Looping over a set of objects (e.g. zones) can be split across processors, greatly speeding up the execution of the function.
  • The editor is improved, with better highlighting, visible line numbers, and code folding (collapse and expand segments of code).
  • Python is fully integrated. All FISH functions also available as Python methods.

Plotting and User Interface

  • A new plotting paradigm allows selection of the object being plotted and then selecting the color scheme or value to be contoured.
  • All quantities can now be contoured (e.g., stress and strain).
  • Most plot items include the ability to map to other coordinates and the ability to plot with exaggerated deformation.

Model Building

  • A new file format for importing and exporting blocks and zones is implemented.
  • Tetrahedral blocks can be turned into zones when importing. Blocks with the same group name can be merged together to form multiple zones within a single block. This produces 2-3 times faster run times than joining.

Figure 4: 3DEC model created by importing blocks from Griddle (left) and by using the new merge functionality (right).

  • Build models directly from closed geometry surfaces (e.g. DXF):
    • either fill a volume with tetrahedral blocks, or
    • merge blocks to form zones within single closed surfaces.
  • Create 3DEC blocks directly from VRML files.

Figure 5: A Rhino model of masonry blocks (left) and resulting 3DEC model (right).

  • Cut blocks with an imported geometry (e.g., DXF).

Figure 6: Imported DXF geometry (left) and cross-section of cut 3DEC model (right).

Hybrid Bolts

Add dowel segments to cable bolts so the bolts resist shearing and opening across joints.


Figure 7: Cables around an excavated tunnel. Dowel segments are contoured by shear force.


  • Groups and extra variables for all objects are implemented (including structural elements, flow planes, etc.).
  • Optional compressed save files are available.
  • Save files will be compatible with future versions.

Conversion of 5.2 and older Data Files

3DEC provides a means of converting commands from version 5.2 (or previous) format to the version 7.0 equivalent. This is accomplished by choosing a command from the Edit menu.

With a 5.2 (or older) data file open in an Edit pane, choose Edit —> Command Conversion to show the “Command Conversion” dialog.

explicit command conversion dialog

The dialog provides the option to convert with FISH Safe conversion mode on or off.

Before doing the conversion, a back-up copy of the file will be made in a folder called “pre-conversion” in the same directory as the data file. The data file will be converted on-disk and then reloaded into the text editor.


There will be cases where the conversion tool cannot translate a version 5.2 command to version 7.0. In such cases the problematic portion of the command in question will be surrounded by “%%” symbols in the data file and highlighted in orange. When available, explanatory information will appear, commented and also highlighted in orange. These commands will require user correction to complete conversion. TIP: place the cursor in the line with problem command and press F1 to directly access program documentation for that command.

For example:

example of a failed conversion