Scripting FISH in FLAC3D

Model Creation: Stress Initialization
Parameterization: Varying Model Geometry
Custom Visualization: Positing a Plane of Weakness
Physics Extension: Ground Freezing
Run Control: Yield at Multiple Joint Angles

The commands and functions shown in the examples below are for FLAC3D 6.0, which is in active development.   The concepts under discussion, however, apply just as well to FLAC3D 5.0; only the details of the syntax will change.


FISH is a built-in scripting language that gives the FLAC3D user powerful control over most every aspect of program operation.  From among the numerous possibilities, this presentation gives brief examples of five areas in FLAC3D most commonly customized by use of FISH.

FISH is short for “FLAC-ISH” (or the language of FLAC), the code for which it was first developed.  Now, in addition to FLAC and FLAC3D, FISH is also integrated into UDEC, 3DEC, and PFC.

FISH is embedded deeply into FLAC3D at nearly every level.  It can be used to parameterize data files so that a number of varying cases can be built into the same basic model.   Every data type that makes up a FLAC3D model is also available for FISH to manipulate directly – before, after, and during the solution. This means that not only can FISH be used to create custom complex models and customized results, it can also be used to add custom physics to the solution process that is not part of the standard package.

FISH includes constructs to embed FLAC3D commands within FISH functions (see the command – end command block in the example shown in the Run Control section).

FISH is a semi-compiled language that uses dynamic typing for variables – syntax and use is similar to (but not exactly the same as) Python.  It has been created to be very simple for small needs, but it provides structure and data types needed to support large and complex programs if necessary.

The following illustrations give just an idea of the power of FISH. For a complete tutorial, refer to the FLAC3D documentation, Section 2 of FISH in FLAC3D (FLAC Manual). [1]

Model Creation: Stress Initialization

The following FISH routine specifies a lateral stress coefficient (K0) in a model that has reached initial equilibrium under gravity.

This is a particularly simple example, for the purposes of illustration. Bear in mind that for simpler cases stress initialization is done by command and FISH is not required.

Parameterization: Varying Model Geometry

For this example, we create a simple model of a tunnel interactively using the 2D extrusion tool.  The tool's data and the resulting zones are shown below.  Note that the points used for tunnel are marked, in green, as a group named Tunnel.

Using this as a template, we use the State Record pane to create a data file named create_tunnel.dat that reproduces this geometry.  Then we can create a parameterized data file that allows us to test various tunnel locations while only changing one value (tunnel_height defined on line 3).

As seen on line 8, this example demonstrates the use of inline FISH (FISH fragments) that allow a single line of FISH to be embedded and evaluated anywhere within a data file.

Note that things like material properties, tunnel cross-section, and pretty much anything involved in the model can be parameterized in such a fashion – sometimes just with parameter replacement in the data file as seen here, sometimes with the use of FISH functions (as seen above in the Model Creation section).  This allows quick and easy exploration of the parameter space of a model that requires set up once and only once.

Custom Visualization: Positing a Plane of Weakness

Perhaps the most common use of FISH is to customize model results.  Providing this ability was the original motivation for its introduction into Itasca software.  FISH allows the user to plot any quantity of interest in the model without requiring addition of a bewildering variety of rarely-used options on a menu tree somewhere.  The following is an example of a script that calculates, over the entire model,  the normal and shear stress components on a particular plane orientation.  It also creates a flag (fail, line 9) that indicates if failure would occur on that plane, given a specific friction angle (tau_crit, line 8).

Compressive stresses are negative in FLAC3D (note the definition of tau_crit on line 8).  The following is a plot of the result, looking at a cut-away plane at the same orientation, from the “Pillar Loads At Intersecting Tunnels” example problem (Section 2, Example Applications, FLAC3D Manual). [1]  Note that FLAC3D legend entries can be customized to make the content of the plot clearer — in this case fail evaluates to Boolean values (“true”, “false”) but on the plot legend these are re-labeled “Failed” and “Stable”.


Physics Extension:  Ground Freezing

FISH functions can be called during cycling/solving to solution.  FISH can be invoked at any point during each calculation cycle, to override or to add additional physics to the model.   Each cycle is one iteration of the steps in the explicit solution scheme; placement of FISH within that sequence can be specified by command.

The following is a simple illustration of a FISH function, ground_freezing, that could be used to model ground freezing during a couple thermo-mechanical analysis:

This calls a FISH function freeze_zone (definition below) that actually changes the stress and stiffness of the zone and marks it as frozen:

Freezing could be added to the solution processing with a command like the following:

This inserts a call to the ground_freezing FISH function at the start of every 10th solution step (to limit the effect on solution time).  The same thing can be done as part of the solve command, as in the example (see lines 33-35 in the fragment below) .  A command such as the following would solve to 10 seconds of thermal time with a ground freezing check every 10 cycles:

The distinction between the two formulations shown above is that the former is global and will take effect with any subsequent model solve command; the latter specifies execution of FISH only for that particular issuance of model solve.

The following image displays the results when run on a modified version of the “Infinite Line Heat Source in an Infinite Medium” example problem (Section, Thermal Analysis, FLAC3D Manual). [1]

This example is very simple but still potentially useful.  More accuracy can be added, depending on the needs of the model.  For example, more properties can be modified, the constitutive model can be changed to one that supports creep, and the heat of fusion required to change water to ice can be taken into account.


Run Control:  Yield at Multiple Joint Angles

The following is a simplification of “Uniaxial Compressive Strength of a Jointed Material Sample” (Section 6, Verification Problems, FLAC3D Manual). [1]  Eighteen model runs are made under FISH control to create a plot of failure stress versus joint angle (which is increased by five degrees with each run, starting from 0).   The entire data file required is shown below:

Before the data file is run, the 2D extrusion tool is used to create a cylinder cross-section that is extruded in the y direction.   The extrusion set and the zones created from it are shown below.

Next the State Record Pane (new in version 6.0) is used to create a data file that recreates this result (the file is named cylinder.f3dat — called in the first line of the data file above).  Next a FISH function that measures stress at the end of the cylinder and stores the result in a table is written and saved as measure.f3fis (this is called on the second line of the data file above and is shown at the end of this example, for reference).

With these two preliminaries in hand, the data file can be run, and the following is produced from the result table (see data file below):

Note that in the actual verification problem the applied boundary conditions use a FISH servo to optimize convergence accuracy and the result is compared against an analytical solution calculated via FISH.

[1] All program documentation for FLAC3D — including all twelve volumes of the FLAC3D 5.0 Manual — is installed with the free demonstration version of the program available on this site, for those who are interested in exploring this material in greater depth.