LIBRARY OF FISH FUNCTIONS 3-1

3 LIBRARY OF FISH FUNCTIONS

This section contains a library of FISH functions that have been written for general application in
FLAC 3D analysis. The functions can be used for various aspects of model generation and solution,
including mesh generation, plotting, assigning material properties and solution control.
The FISH function files are contained in the “\FISH\Library” directory.
The general procedure to implement these FISH functions is performed in three steps.
1. The FISH file is first called by the FLAC 3D data file with the command
call filename.fis

2. Next, FISH variables, if given at the top of the function file, must be set in the data file
with the command
set var1 = value var2 = value ...
where var1, var2, etc. are the variable names that must be set to specified values.

3. Finally, the FISH function is invoked by entering the function name that follows directly
after the DEF command in the FISH file. The name does not have to be given if a fishcall
is used within the file.

The FISH functions interact with FLAC 3D in various ways. You should turn to Section 2.4 for a
description of the different types of linkages between FISH and FLAC 3D.

FLAC 3D Version 3.0

3-2 FISH in FLAC 3D

FLAC 3D Version 3.0

LIBRARY OF FISH FUNCTIONS FFT.FIS - 1

Finding the Fast Fourier Transform Power Spectrum of a FLAC 3D Table

The FISH file “FFT.FIS” performs a Fast Fourier Transform on a table of data, resulting in a power
spectrum that is output to another table. The ID number of the input table is defined by fft in, and
the output table is defined by fft out. The output table with the same table number, fft out,
must not exist before the call of the file “FFT.FIS.” Both fft in and fft out must be specified
in a separate FISH function, defined and executed before the call to “FFT.FIS.”
There are several definitions for a power spectrum. The one used here is adapted from Press et al.
(1992). The power spectrum is a set of N/2 real numbers defined as:

1
P0 = ∗ (|f0 |)2 (1)
N2

1
Pk = ∗ [(|fk |)2 + (|fN −k |)2 ] (2)
N2

1
PN = ∗ (|f N |)2 (3)
2 N2 2

where: N is half the number of points in the original data field;

P is the power spectrum output;
f is the result of the Fast Fourier Transform of the original data; and
N
k varies from 0 to 2.

Note that an array, worka, is used to manipulate the table data. The array dimension (FISH variable
n point) is defined from the following conditions: (1) to be greater than the number of elements
in the input table; and (2) to be a power of 2. (The array dimension need not be declared manually.)
The fft algorithm requires input data with a constant timestep. So, a timestep is calculated, and
the data are interpolated from the table and stored into the array for processing.
The following example verifies the fft FISH function. The history input is the sum of a sine wave
at 1 Hz and an amplitude of 1, a cosine wave at 5 Hz and an amplitude of 2, and a sine wave at 10 Hz
and an amplitude of 3. The combined history input is calculated by the FISH function cr tab.
The input is plotted in Figure 1. The power spectrum shown in Figure 2 consists of three sharp
peaks at 1, 5 and 10 Hz, with increasing peak values.

Reference
Press, W. H., B. P. Flannery, S. A. Teukolsky and W. T. Vetterling. Numerical Recipes in C.
Cambridge: Cambridge University Press, 1992.

FLAC 3D Version 3.0

FFT.FIS - 2 FISH in FLAC 3D

Data File “FFT.DAT”

def cr tab
i = 1
p2 = 2.*pi
loop while i <= num point
xx=end time*float(i)/float(num point)
i = i+1
yy = sin(xx*p2/per1)+2.*cos(5.*xx*p2/per1)+3.*sin(10.*xx*p2/per1)
table(1,xx) = yy
end loop
end

set num point 1024 end time 12.0

set per1 1.0

cr tab

def tab ind

fft in = 1
fft out = 2
end
tab ind
ca fft.fis
fftransform
ret

FLAC 3D Version 3.0

LIBRARY OF FISH FUNCTIONS FFT.FIS - 3

FLAC3D 3.00
13:18:18 Fri Mar 25 2005 5.0

Table
1 UnNamed
Linestyle 4.0
-5.381e+000 <-> 5.467e+000

3.0

2.0

1.0

0.0

-1.0

-2.0

-3.0

-4.0

-5.0

0.2 0.4 0.6 0.8 1.0 1.2

Itasca Consulting Group, Inc. x10^1
Minneapolis, MN USA

Figure 1 Sum of three input waves

FLAC3D 3.00
13:18:45 Fri Mar 25 2005

Table
2 UnNamed 7.0
Linestyle
0.000e+000 <-> 7.837e+000

6.0

5.0

4.0

3.0

2.0

1.0

0.0
0.0 0.5 1.0 1.5 2.0
Itasca Consulting Group, Inc. x10^1
Minneapolis, MN USA

Figure 2 Power spectrum; power versus frequency in Hz

FLAC 3D Version 3.0

FFT.FIS - 4 FISH in FLAC 3D

FLAC 3D Version 3.0

LIBRARY OF FISH FUNCTIONS NUMBER.FIS - 1

Printing a Floating-Point Number with User-Specified Precision

The FISH file “NUMBER.FIS” is used to output a floating point number with a user-specified
precision up to a maximum precision limit of 16 digits. Normally, a FISH function outputs the
result of a floating-point operation with a precision limit of 5 digits.
The algorithm used to extract digits up to the precision required is outlined below.
(a.) Convert number to a float value (type cast).
(b.) Determine “k,” the exponent of the resulting number.
k = [log(number)-1] if log(number) < 0.0
= [log(number) ] otherwise
where [ ..] denotes the integral value of number within brackets.
(c.) Extract each significant digit up to a precision of precision limit + 1
and store it in an array.

After all digits are found up to a precision limit of “precision limit + 1,” the last digit is rounded
off, depending on whether its value is greater than or equal to 5. Thus the result will be a floating
point number with user-defined precision stored as a string. The digits are then output as a string
value with an exponent of “k.”
Note: If the user does not specify a precision limit, the FISH function assumes a precision limit of
7 digits.
The data file “NUMTEST.DAT” illustrates how to print numbers with a user-specified precision
limit of 10 digits. In this example, 20 numbers are generated randomly and their values are output
with 10 digits of precision.
Data File “NUMTEST.DAT”
; Exercise the Number functions
call number.fis
set digits=10
def qqq
loop n (1,20)
power = int((urand - 0.5) * 40.0)
Given = urandˆ power
oo = out(’ input = ’+string(Given)+’ output = ’+Number)
endLoop
end
qqq

FLAC 3D Version 3.0

NUMBER.FIS - 2 FISH in FLAC 3D

FLAC 3D Version 3.0

LIBRARY OF FISH FUNCTIONS SPEC.FIS - 1

Finding the Response Spectrum of an Acceleration History in a FLAC 3D Table

The FISH file “SPEC.FIS” finds the displacement response spectrum, the pseudo-velocity response
spectrum and the pseudo-acceleration response spectrum of an input acceleration stored in a FLAC 3D
table. The ID number of the input table is defined by acc in, and the three output tables are
identified by sd out, sv out and sa out. If any of the output tables currently exist, they will
be deleted and overwritten with the new results.
The damping constant for the response analysis is specified by dmp. The calculation is only
approximate for damped responses — the higher dmp is, the less accurate the response.
The range of periods over which the spectrum is calculated by pmin and pmax, and the number
of points in the output tables, are defined by n point.
This routine can take considerable time to execute. If Ni is the number of input points and Np is the
number of points in the output, then the number of calculations increases as Np × Ni × log(Ni ).
This formulation tends to give somewhat distorted results for periods approaching zero; however,
improving the accuracy for small periods increases the calculation time.
The algorithm was adapted from Craig (1981). As an example of its use, a simple sine wave
was input into a FLAC 3D table as an input acceleration. The function was then executed from a
period of 0.5 to 2, with 50 points, in the output tables (see “SPEC.DAT”). Figure 1 shows the input
acceleration generated — a sine wave with a period of 1.0. Figures 2 through 4 show the various
response spectrums generated, displaying the expected peaks at a period of 1.0.
Reference
Craig, Jr., R. R. Structural Dynamics — An Introduction to Computer Methods. New York: John
Wiley and Sons, 1981.

FLAC 3D Version 3.0

SPEC.FIS - 2 FISH in FLAC 3D

Data File “SPEC.DAT”

def cr tab
i = 0
p2 = 2.*pi
loop while i <= num point
xx=end time*float(i)/float(num point)
i = i+1
yy = sin(xx*p2/per1)
table(1,xx) = yy
end loop
end

set num point 250 end time 3.0

set per1 1.0

cr tab

ca spec.fis
set pmin = 0.5
set pmax = 2.
set dmp = 0.
set acc in = 1
set sd out = 2
set sv out = 3
set sa out = 4
set n point = 50
spectra
;
table 1 name ’input acceleration’
;
table 2 name ’displacement response spectrum’
;
table 3 name ’pseudo-velocity spectrum’
;
table 4 name ’pseudo-acceleration spectrum’
;
ret

FLAC 3D Version 3.0

LIBRARY OF FISH FUNCTIONS SPEC.FIS - 3

x10^-1
FLAC3D 3.00
13:19:30 Fri Mar 25 2005

Table 8.0
1 input acceleration
Linestyle
-9.999e-001 <-> 9.999e-001

6.0

4.0

2.0

0.0

-2.0

-4.0

-6.0

-8.0

0.0 0.5 1.0 1.5 2.0 2.5 3.0

Itasca Consulting Group, Inc.
Minneapolis, MN USA

Figure 1 Input acceleration

x10^-1
FLAC3D 3.00
13:19:53 Fri Mar 25 2005 2.4

Table
2 displacement response spectrum 2.2
Linestyle
1.097e-002 <-> 2.476e-001

2.0

1.8

1.6

1.4

1.2

1.0

0.8

0.6

0.4

0.2

0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0

Itasca Consulting Group, Inc.
Minneapolis, MN USA

Figure 2 Displacement response spectrum

FLAC 3D Version 3.0

SPEC.FIS - 4 FISH in FLAC 3D

FLAC3D 3.00
13:20:18 Fri Mar 25 2005
1.4
Table
3 pseudo-velocity spectrum
Linestyle
1.378e-001 <-> 1.505e+000

1.2

1.0

0.8

0.6

0.4

0.2

0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0

Itasca Consulting Group, Inc.
Minneapolis, MN USA

Figure 3 Pseudo-velocity response spectrum

FLAC3D 3.00
13:20:34 Fri Mar 25 2005
9.0
Table
4 pseudo-acceleration spectrum
Linestyle
1.333e+000 <-> 9.460e+000
8.0

7.0

6.0

5.0

4.0

3.0

2.0

0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0

Itasca Consulting Group, Inc.
Minneapolis, MN USA

Figure 4 Pseudo-acceleration response spectrum

FLAC 3D Version 3.0

LIBRARY OF FISH FUNCTIONS TOPO.FIS - 1

Grid Generation of Topography

A FISH function, “TOPO.FIS,” is described here, to illustrate the use of FISH to create a model
surface that corresponds to a given topography.
The generation is based upon a series of GENERATE zone brick commands. Each of these commands
creates a column of 1 × 1 × z size zones. (The z-direction corresponds to the vertical direction.)
The problem is to define the eight coordinates of the column. We assume that the base is formed by
n zon row × n zon col rectangular elements with uniform dimensions dx and dy. We also
assume that all the gridpoints at the base have a common elevation of z base. Now the problem
is reduced to defining the elevation of four points of known horizontal projection.
Several approaches can be used at this point, depending on the format of the topography data.
Contouring programs, such as SURFER, from Golden Software, will interpolate a regular grid
from an irregularly distributed data set. The interpolated data can then be imported into FLAC 3D
via a table. In this example we have used a different approach. Starting from a contour map such as
the one shown in Figure 1, we take several sections at constant y-coordinate. The distance between
each section is dy. A table is created for each section, with an x,z-pair for every point that intersects
a contour level. It is relatively simple to program a digitizer to obtain these tables rapidly. The
FISH function topo interpolates the value of z for a given x in the corresponding table.
The interpolation logic and the loop containing the GENERATE zone brick command are included
in the file “TOPO.FIS.” The file “TOPOTAB.DAT” contains the digitized data for this particular
example. This will produce the contour map shown in Figure 2. Note that because FLAC 3D does
not plot contours of coordinates, the elevation has been dumped into a zone extra array for plotting
(FISH function contour map).
Reference
Davis, J. C. Statistics and Data Analysis in Geology, Fig. 6.10, p. 323. New York: John Wiley &
Sons, Inc., 1973.

FLAC 3D Version 3.0

TOPO.FIS - 2 FISH in FLAC 3D

Data File “TOPO.DAT”

ca topotab.dat
ca topo.fis
set n zon col=10 n zon row=10 z base=500 z size=5 dx size=40. dy size=40.
set xor=0 yor=0
topo

config gpextra 1
def contour map
pnt=gp head
loop while pnt # null
gp extra(pnt,1)=gp zpos(pnt)
pnt=gp next(pnt)
end loop
end
contour map

plot create map

plot set rot 90 0 0
plot set pers off
plot add con gpextra 1 out on int 25 alias ’Z elevation’
plot show

FLAC 3D Version 3.0

LIBRARY OF FISH FUNCTIONS TOPO.FIS - 3

Data File “TOPOTAB.DAT”

; Tables of interpolated data from contour map
; (Figure 6.10, Statistics and Data Analysis in Geology, John C. Davis,
; John Wiley & Sons, 1973)
; Table number corresponds to constant y = 40
; with each x,z pair at point where the line intersects a contour level
;
; Table 1 @ y = 40
table 1 0 950
table 1 20 925
table 1 64 900
table 1 130 875
table 1 160 875
table 1 209 900
table 1 315 900
table 1 353 875
table 1 400 870

; Table 2 @ y = 80
table 2 0 910
table 2 20 925
table 2 50 925
table 2 110 900
table 2 180 900
table 2 215 925
table 2 248 950
table 2 276 950
table 2 306 925
table 2 337 900
table 2 365 875
table 2 376 875
table 2 400 900

; Table 3 @ y = 120
table 3 0 890
table 3 122 875
table 3 158 875
table 3 185 900
table 3 245 925
table 3 287 925
table 3 308 900
table 3 365 875
table 3 392 900
table 3 400 910

; Table 4 @ y = 160

FLAC 3D Version 3.0

TOPO.FIS - 4 FISH in FLAC 3D

table 4 0 910
table 4 8 900
table 4 42 875
table 4 125 850
table 4 162 850
table 4 191 875
table 4 270 875
table 4 325 850
table 4 357 850
table 4 385 875
table 4 400 880

; Table 5 @ y = 200
table 5 0 890
table 5 50 875
table 5 82 850
table 5 105 825
table 5 138 825
table 5 203 850
table 5 289 850
table 5 314 825
table 5 339 825
table 5 375 850
table 5 400 865

; Table 6 @ y = 240
table 6 0 860
table 6 73 850
table 6 106 825
table 6 134 800
table 6 157 800
table 6 243 825
table 6 296 825
table 6 350 825
table 6 400 850

; Table 7 @ y = 280
table 7 0 840
table 7 85 825
table 7 130 800
table 7 146 775
table 7 179 775
table 7 318 800
table 7 351 825
table 7 400 830

FLAC 3D Version 3.0

LIBRARY OF FISH FUNCTIONS TOPO.FIS - 5

; Table 8 @ y = 320
table 8 0 852
table 8 10 850
table 8 45 825
table 8 80 800
table 8 137 775
table 8 180 750
table 8 192 750
table 8 308 775
table 8 357 800
table 8 400 825

; Table 9 @ y = 360
table 9 0 870
table 9 32 850
table 9 57 825
table 9 102 800
table 9 132 775
table 9 166 750
table 9 255 750
table 9 293 775
table 9 323 800
table 9 364 825
table 9 389 850
table 9 400 860

; Table 10 @ y = 400
table 10 0 870
table 10 42 850
table 10 62 825
table 10 98 800
table 10 140 775
table 10 176 750
table 10 206 725
table 10 242 725
table 10 266 750
table 10 296 775
table 10 314 800
table 10 380 825
table 10 400 835

; Table 11 @ y = 440
table 11 0 860
table 11 23 850
table 11 46 825
table 11 72 800

FLAC 3D Version 3.0

TOPO.FIS - 6 FISH in FLAC 3D

table 11 129 775

table 11 150 750
table 11 182 725
table 11 203 700
table 11 230 700
table 11 265 725
table 11 285 750
table 11 315 775
table 11 366 800
table 11 400 820
ret

FLAC 3D Version 3.0

LIBRARY OF FISH FUNCTIONS TOPO.FIS - 7

Figure 1 Contour map (Davis 1973)

FLAC3D 3.00
Settings: Model Projection
13:21:56 Fri Mar 25 2005

Center: Rotation:
X: 2.000e+002 X: 90.000
Y: 2.000e+002 Y: 0.000
Z: 7.250e+002 Z: 0.000
Dist: 1.331e+003 Size: 5.295e+002

Z elevation
Magfac = 0.000e+000
7.0357e+002 to 7.2500e+002
7.2500e+002 to 7.5000e+002
7.5000e+002 to 7.7500e+002
7.7500e+002 to 8.0000e+002
8.0000e+002 to 8.2500e+002
8.2500e+002 to 8.5000e+002
8.5000e+002 to 8.7500e+002
8.7500e+002 to 9.0000e+002
9.0000e+002 to 9.2500e+002
9.2500e+002 to 9.5000e+002
9.5000e+002 to 9.5000e+002
Interval = 2.5e+001

Itasca Consulting Group, Inc.

Minneapolis, MN USA

Figure 2 Contour map produced by FLAC 3D

FLAC 3D Version 3.0

TOPO.FIS - 8 FISH in FLAC 3D

FLAC 3D Version 3.0

LIBRARY OF FISH FUNCTIONS WATER TAB.FIS - 1

Generation of a Water Table

An arbitrary phreatic surface can be specified in FLAC 3D by a series of WATER table face commands.
This task can be very repetitive, but is easily automated via FISH.
The approach used in the FISH function water tab (contained in the file “WATER TAB.FIS”) is
very similar to the one used in “TOPO.FIS” (see Grid Generation of Topography, in this section, for
a description of the logic and the input parameters). The only difference is that the GENERATE zone
brick command has been replaced by two WATER table face commands. While the four corners of
a face of a GENERATE zone brick command need not be coplanar, the points in a face polygon for a
water table must be coplanar and produce a convex polygon. The easiest way to satisfy these two
requirements is to make all the face polygons triangles.
The file “WATER.DAT” reproduces the same topography that “TOPO.DAT” creates, and assumes
that the ground is fully saturated. (The tables that define the phreatic surface are identical to the
ones that define the topography.) Figure 1 shows the contours of pore pressure and the water table
created with this file.

FLAC 3D Version 3.0

WATER TAB.FIS - 2 FISH in FLAC 3D

Data File “WATER.DAT”

ca topotab.dat
set grav 0 0 -10
water den 1000
ca topo.fis
set n zon col=10 n zon row=10 dx size=40. dy size=40.
set z base=500 z size=5
topo
ca water tab.fis
water tab
plot create water table
plot set rot 29.851 358.272 150.149
plot set cent 200 200 725
plot set dist 2121
plot set mag 1.25
pl add con pp out on
pl add water lgre
plot show
save water.sav
ret

FLAC3D 3.00
Settings: Model Perspective
13:22:44 Fri Mar 25 2005

Center: Rotation:
X: 2.000e+002 X: 29.851
Y: 2.000e+002 Y: 358.272
Z: 7.250e+002 Z: 150.149
Dist: 2.169e+003 Mag.: 1.25
Ang.: 22.500

Contour of Pore Pressure

Magfac = 0.000e+000
0.0000e+000 to 5.0000e+005
5.0000e+005 to 1.0000e+006
1.0000e+006 to 1.5000e+006
1.5000e+006 to 2.0000e+006
2.0000e+006 to 2.5000e+006
2.5000e+006 to 3.0000e+006
3.0000e+006 to 3.5000e+006
3.5000e+006 to 4.0000e+006
4.0000e+006 to 4.5000e+006
4.5000e+006 to 4.5000e+006
Interval = 5.0e+005
Water Surfaces

Itasca Consulting Group, Inc.

Minneapolis, MN USA

Figure 1 Water table and contours of pore pressure

FLAC 3D Version 3.0