Flac3D 4

  BEGINNER’S GUIDE  FISH  BEGINNER’S

4-1

4   FISH  BEGINNER’S  BEGINNER’S GUIDE 4.1 Intr Introd oduc uctio tion n   is a programming language embedded within  FLAC 3D that enables the user to define new FISH  is variables variables and functions. These functions functions may be used to extend FLAC 3D’s usefulness or add userdefined features. features. For example, example, new variables may be plotted or printed, printed, special grid generators may be implemented, servo-control may be applied to a numerical test, unusual distributions of  properties may be specified, and parameter studies may be automated. was deve develo lope ped d in respo respons nsee to reque request stss from from users users who who want wanted ed to do thin things gs with with Itasc Itascaa softw software are FISH was that were either difficult difficult or impossible impossible with existing existing program structures. structures. Rather than incorporate incorporate many new and specialized features into the standard code, the decision was made to provide an embe embedd dded ed lang langua uage ge so that that users users coul could d writ writee thei theirr own own funct functio ions ns.. Some Some usefu usefull FISH functions functions have have 3D already already been written; written; a library library of these is provided with the  FLAC  program (see Section (see Section 3 in 3  in the ). It is possi possibl blee for for someo someone ne with withou outt exper experie ienc ncee in progr program ammi ming ng to writ writee simp simple le FISH   FISH volume  FISH volume). funct functio ions ns,, or to modi modify fy some some of the the simp simple lerr exis existi ting ng func functi tion ons. s. Sect  Section ion 4.2 contai contains ns an introdu introducto ctory ry tutorial for non-programmers. However, FISH  programs  programs can also become very complicated (which is true of code in any programming language); for more details, refer to  Section 2 in 2  in the  FISH  volume. volume. As with all programming tasks,  FISH  functions  functions should be constructed in an incremental fashion, checking operations at each level before moving on to more complicated code.   FISH  does   does less error-checking than most compilers, so all functions should be tested on simple data sets before using them for real applications.   programs are simply embedded in a normal  FLAC 3D data file — lines following the word FISH  programs function; on; the functio function n termin terminate atess when when the word word END is encountered. encountered. DEFINE areprocessedasa FISH functi Functions Functions may invoke invoke other functions, functions, which may invoke invoke others, and so on. The order in which funct functio ions ns are are defin defined ed does does not not matt matter er as long long as they they areall defin defined ed befo before re they they areused (e.g. (e.g.,, invo invoke ked d 3D 3D by a FLAC  comma command nd). ). Sinc Sincee the the compi compile led d form form of a FISH func functi tion on is store stored d in FLAC  ’s memory space, the  SAVE  command saves the function and the current values of associated variables. All of the   FISH   language rules and intrinsic functions are discussed in  Section 2  in the  FISH  includes rules for syntax, data types, arithmetic, arithmetic, variable variabless and functions. functions. All FISH  volume. volume. This includes language names are described in Section in  Section 2 in 2  in the FISH  the  FISH  volume,   volume, and a summary of the names is provided in Section in  Section 2 in 2  in the Command the  Command and FISH  and  FISH  Reference   Reference Summary. Summary .

FLAC 3D Version 3.0

 4 - 2

User’s Guide

4.2 Tutor utorial ial This section is intended for people who have run  FLAC 3D (at least for simple problems), but have not used the  FISH  language;   language; no programming experience is assumed. To get the maximum benefit from the examples given here, you should try them out with  FLAC 3D running interacti interactively vely.. The 3D short programs programs may be typed in directly directly.. After running running an example, example, give the  FLAC  command “wipe the slate slate clean, clean,”” ready ready for the next next examp example. le. Altern Alternati ativel vely y, the more more length lengthy y program programss NEW to “wipe may be created on file and  CALLed when required. required. Type the lines in  Example 4.1 after 4.1  after  FLAC 3D’s command prompt, pressing  < Enter>  at the end of  each line.  Example 4.1

Defining a FISH function

def def abc abc abc = 22 * 3 + 5 end

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

The message abc =

71

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

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

FLAC 3D Version 3.0

  BEGINNER’S GUIDE  FISH  BEGINNER’S

4-3

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

Using a variable

new def def abc abc hh = 22 abc = hh * 3 + 5 end

Here we introduce a “variable,” hh “variable,”  hh,, which is given the value of 22 and then used in the next line. If we give the command  PRINT  abc  abc,, then exactly the same output as in the previous case appears. However, we now have two  FISH  symbols;   symbols; they both have values, but one (abc ( abc)) is known as a “function,” and the other (hh (hh)) as a “variable.” The distinction is as follows. When When a FISH FISH symb symbol ol name name is ment mentio ione ned d (e.g (e.g., ., in a PRINT statement), the associated function is executed if the symbol corresponds to a  function. However, However, if the symbol is not a function name, then the current current value of the symbol is simply simply used.

The following experiment may help to clarify the distinction between variables and functions. Before doing the experiment, note that  FLAC 3D’s SET command can be used to set the value of any user-defined FISH  symbol,   symbol, independent of the  FISH  program   program in which the symbol was introduced. Now type in the following lines without giving the command NEW, since we want to keep our previously entered program in memory.  Example 4.3

SET ting variables

set set abc= abc=0 0 hh=0 hh=0 prin print t hh print pri nt abc prin print t hh

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

FLAC 3D Version 3.0

 4 - 4

User’s Guide

 Example 4.4

Test your understanding of function and variable names

new def def abc abc abc = hh * 3 + 5 end set hh= hh=22 22 print pri nt abc set set abc= abc=0 0 hh=0 hh=0 prin print t hh print pri nt abc prin print t hh

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

PRINT SET HISTORY

var var = var  = value  value var

We have already seen examples of the first two (refer to  Examples 4.3 an 4.3  and d  4.4  4.4); ); the third case is 3D useful when histories of things that are not provided in the standard  FLAC  list of history variables are required.  Example 4.5 shows shows how the total load on the top platen platen of a triaxial test sample sample can be stored as a history.  Example 4.5

Capturing the history of a FISH variable var iable

new gen gen zone zone brick brick size size 1 2 1 model mod el moh mohr r prop pro p she shear= ar=1e8 1e8 bul bulk=2e k=2e8 8 & cohes=1e5 cohes=1e5 tens=1e10 tens=1e10 fix x y z

range y -0.1 0.1

appl apply y yvel yvel -1 -1ee-5 5 rang range e y def get get_ad _ad ad1 = gp_ gp_nea near(0 r(0,2,0 ,2,0) ) ad2 = gp_ gp_nea near(1 r(1,2,0 ,2,0) ) ad3 = gp_ gp_nea near(0 r(0,2,1 ,2,1) ) ad4 = gp_ gp_nea near(1 r(1,2,1 ,2,1) ) end

FLAC 3D Version 3.0

1.9 1.9 2.1 2.1

  BEGINNER’S GUIDE  FISH  BEGINNER’S

4-5

get_ad def def load load load=gp_yfunbal(ad1)+gp_yfunbal(ad2)+gp_yfunbal(ad3)+gp_yfunbal(ad4) end hist his t loa load d hist hist gp ydis ydis 0,6, 0,6,0 0 step ste p 100 1000 0 plot his 1 vs -2

Note that the  FISH  variable load    variable  load  is   is equal to the sum of four other variables,  gp yfunbal (index). (index). The FISH  grid  grid variable  gp yfunbal()  is an example of a grid quantity that is available within a  FISH  program; there is a complete list of these in  Section 2.5.3 in 2.5.3  in the FISH  the  FISH  volume.   volume. Grid variables are simply pre-defined named quantities that relate to the  FLAC 3D grid. In Example In  Example 4.5, 4.5,  gp yfunbal()  is the  y -component -component of the unbalanced gridpoint gridpoint force; each instance of  gp   gp yfunbal()  must be followed by a gridpoint memory address (or pointer). The address is found with with the functio function n get ad , whic which h uses uses the the FISH gridpoint gridpoint variable variable gp near to find find the the addr addres esss of the the gridpoint closest to the ( x ,y ,z) global global coordinates (0,2,0), (0,2,0), (1,2,0), (0,2,1) and (1,2,1). (1,2,1). The derived derived variable load  variable load , which is the sum of the four top forces, is calculated whenever history points are taken (every ten steps, by default). At the end of the run, we simply plot out the history of  load  of  load  (history (history 1) just like any other history. history. Similarly Similarly,, we may use  FISH  functions   functions to plot out a history of any quantity quantity we wish, no matter how complicated complicated the formula formula to describe it might be. In addition to the above-mentioned pre-defined variable names, there are many other pre-defined objects available to a  FISH   program. program. These fall into into several several classes; one such class consists of    variables, which are single numbers — for example, scalar  variables,

clock 

clock time in hundredths hundredths of a second

unbal

maximum unbalanced force

xgrav

x -component of gravity

pi

π

step

current step number

urand

random number drawn from uniform uniform distribut distribution ion between between 0.0 and 1.0.

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

absolute value of  a  a

 a) cos( a

cosine of  a (  is in radians)  a  ( a  a is

FLAC 3D Version 3.0

 4 - 6 

User’s Guide

log( a)

base-ten logarithm of  a  a

 a,b) max( a,b

returns maximum of  a,  a ,  b

 a) sqrt( a

square root of  a  a

An example in the use of intrinsic functions will be presented later, but now we must discuss one further way in which a  FLAC 3D data file can make use of user-defined FISH  names.   names. Wherever a number is expected in a FLAC 3D input line, you may substitute the name of a FISH variable or function.

This simple statement is the key to a very powerful feature of   FISH  that   that allows such things as ranges, applied stresses, properties, etc., to be computed in a  FISH  function   function and used by  FLAC 3D input in symbolic symbolic form. Hence, parameter parameter changes can be made very easily, easily, without the need to change many numbers in an input file. As an example, let us assume that we know the Young’s modulus and Poisson’s ratio of a material. Since  FLAC 3D needs the bulk and shear moduli, we may derive these with a  FISH  function,   function, using Eqs. (4.1) and (4.1) and (4.2)  (4.2)::

= 2(1E+ ν)

(4.1)

 = 3(1 −E 2ν)

(4.2)

G

K

Coding Eqs. Coding  Eqs. (4.1) and (4.1)  and  (4.2)  (4.2) into  into a  FISH  function   function (called derive (called  derive)) can then be done as shown in Example 4.6, 4.6, below.  Example 4.6

FISH functions f unctions to calculate bulk and shear moduli

new def der derive ive s_mo s_mod d = y_mo y_mod d / (2.0 (2.0 * (1.0 (1.0 + p_ra p_rati tio) o)) ) b_mo b_mod d = y_mo y_mod d / (3.0 (3.0 * (1.0 (1.0 - 2.0 2.0 * p_ra p_rati tio) o)) ) end set set y_mo y_mod d = 5e8 5e8 p_ra p_rati tio o = 0.25 0.25 derive print pri nt b_m b_mod od s_m s_mod od

Note that, here, we execute the function  derive by  derive  by giving its name by itself on a line; we are not interested in its  value, only what it  does. If you run this example, you will see that values are

FLAC 3D Version 3.0

  BEGINNER’S GUIDE  FISH  BEGINNER’S

4 - 7 

computed for the bulk and shear moduli,  b mod  and s mod , respectively. These can then be used, mod and 3D in symbolic form, in  FLAC  input as shown in Example in  Example 4.7.* 4.7.*  Example 4.7

Using symbolic variables in FLAC  FLAC  3D input

gen gen zone zone bric brick k size size 2,2, 2,2,2 2 model elastic elastic prop bulk=b_mod bulk=b_mod shear=s_mod shear=s_mod prin print t zone zone prop prop bulk bulk prin print t zone zone prop prop shear shear

The validity of this operation may be checked by printing out  bulk  and  and  shear  in the usual way. In these examples, our property input is given via the  SET  command — i.e., to variables  y mod  and p ratio, which stand for Young’s modulus and Poisson’s ratio, respectively. Note Note that that there there is great great flexi flexibi bili lity ty in choo choosi sing ng name namess for for FISH variables variables and functions; functions; the underline underline may be incl includ uded ed in a name name.. Name Namess must must begi begin n with with a non-n non-num umber ber and and must must not not cont contai ain n charact character er ( ) may any of the arithmetic operators (+, –, /, * or ˆ). See Section See  Section 2.2.2 in 2.2.2  in the FISH  the  FISH  volume for   volume  for a list of  symbols to avoid. A chosen name should not be the same as one of the built-in (or reserved) names; Table 2.1 in Section in  Section 2.2.2 in 2.2.2  in the FISH  the  FISH  volume contains   volume  contains a complete list of names to be avoided, as well as some rules that should should be followed. followed. Also note that parentheses parentheses were used in the above example; these should be used whenever it is necessary to make clear the order in which arithmetic operations are to be done. In the above examples, we checked the computed values of  FISH    variables by giving their names   FISH  variables explicitly as arguments to a  PRINT  command.  command. Alternati Alternatively vely,, we can list all current variables variables and functions. functions. A printout of all current values, values, sorted alphabeticall alphabetically y by name, is produced by giving giving the command print pri nt fis fish h

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

LOOP

var (expr1, expr2)

ENDLOOP * In  safe  mode, the  FISH  variable   variable must be preceded by an @ symbol — see  Section 2.2.2  in the  FISH  volume, in  Section 1.3 in 1.3  in the Command the  Command Reference.   volume, and the  SET  command in Section Reference .

FLAC 3D Version 3.0

 4 - 8

User’s Guide

The words  LOOP  and  ENDLOOP  are  FISH  statements,   statements, the symbol var symbol  var stands  stands for the loop variable,  expr2  stand for expressions and expr1 and  expr1 and  and  expr2 stand expressions (or single variables). variables).   Example 4.8  shows the use of a loop (or repeated sequence) to produce the sum and product of the first ten integers.  Example 4.8

Controlled loop in FISH 

new def def xxx xxx sum

= 0

prod = 1 loop loop n (1,1 (1,10) 0) sum

= su sum + n

prod = prod * n end_loop end xxx prin print t sum, sum, prod prod

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

 = E◦ + c√ z

(4.3)

where z  is the depth below surface, and  c  and  E◦  are constants. We write a  FISH  function  function to install appropriate values of bulk and shear modulus in the grid, as in Example in  Example 4.9. 4.9.  Example 4.9

Applying a nonlinear initial distribution of moduli

new gen gen zone zone bric brick k p0 (0, (0,0, 0,0) 0) p1 (-10 (-10,0 ,0,0 ,0) ) p2 (0,1 (0,10, 0,0) 0) p3 (0,0 (0,0,-1 ,-10) 0) model mod el ela elas s def ins instal tall l pnt pnt = zone zone_h _hea ead d loop loop whil while e pnt pnt # null null z_dept z_d epth h = -z_zcen -z_zcen(pn (pnt) t) y_mo y_mod d = y_zer y_zero o + cc * sqrt sqrt(z (z_d _dept epth) h) z_prop z_p rop(pn (pnt, t, ’sh ’shear ear’) ’) = y_m y_mod od / (2.0*(1 (2.0*(1.0+ .0+P_r P_rati atio)) o)) z_prop z_p rop(pn (pnt, t, ’bu ’bulk’ lk’) ) pnt = z_n z_next( ext(pnt pnt) ) end_loop

FLAC 3D Version 3.0

= y_m y_mod od / (3.0*(1 (3.0*(1.0.0-2.0 2.0*P_ *P_rat ratio)) io))

  BEGINNER’S GUIDE  FISH  BEGINNER’S

4-9

end set p_r p_rati atio=0 o=0.25 .25 y_zero= y_zero=1e7 1e7 cc= cc=1e8 1e8 install plot plot bloc block k prop prop bulk bulk

Agai Again, n, you you can can veri verify fy corre correct ct oper operat atio ion n of the the func functi tion on by prin printi ting ng or plot plotti ting ng shear shear and and bulk bulk modu moduli li.. In the functi function on install, the loop loop scan scanss all all zone zoness begi beginn nnin ing g with with zone head , whic which h is the the addr addres esss of  install, the the first zone in the zone list. The  FISH  statement  statement LOOP WHILE WHILE is a variation of  LOOP  LOOP that executes the loop until the test condition is met — i.e., until the address  pnt  equals zero ( pnt ( pnt # null means pnt means pnt not not equa equall to zero) zero).. This This cond condit itio ion n iden identi tifie fiess the the last last zone zone in the the zone zone list list.. Inside Inside the the loop loop,, the z -coordinate of each zone centroid is used to calculate the Young’s modulus given in  Eq. (4.3). (4.3). We assume that the datum (or ground surface reference point) is at z   = 0. Grid Grid values values for bulk  bulk  and shear moduli are calculated as in Example in  Example 4.6. 4.6. The vari variabl ables es z  zcen(pnt) (pnt),,  z prop (pnt, and are  variab  var iables les. . (Recal (Re call l that tha t we talked talked about about the  z prop (pnt, ’bulk   zone ’shear’) ’bulk’) ’)  variable  gp yfunbal (pnt)  earlier.) .) Here, we set properties properties directly directly from within within a  FISH  gridpoint  variable (pnt) earlier function, rather than with a  PROP  command as in our earlier example. Having seen several examples of  FISH    programs, let’s briefly examine the question of program   FISH  programs, syntax and style. style. A complete complete FISH statement must occupy one line; there are no continuation lines. If a form formul ulaa is too too long long to fit on one one line line,, the then n a temp tempor orar ary y varia ariabl blee must must be used used to spli splitt the the form formul ula. a. Example 4.10  shows how this can be done.  Example 4.10 Splitting lines new def def long long_s _sum um

;exa ;examp mple le of a sum sum of many many thin things gs

temp = v1 + v2 + v3 + v4 + v5 + v6 + v7 + v8 + v9 + v10 long_sum = temp + v11 + v12 + v13 + v14 + v15 end

In this case, the sum of fifteen variables variables is split into two parts. Also note the use of the semicolon semicolon in line 1 of  Example   Example 4.10  to indicate indicate a commen comment. t. Any Any charac character terss that that follo follow w a semico semicolon lon are ignored ignored by the FISH  compiler,  compiler, but they  are echoed to the log file. It is good programming programming practice to annotate programs with informativ informativee comments. comments. Some of the programs have been shown with indentation  — that is, space inserted at the beginning of some lines to denote a related group of  statements. Any number of space characters may be inserted (optionally) between variable names and arithmetic arithmetic operations operations to make the program more readable. readable. Again, it is good programming programming practice practice to include include indentation indentation to indicate indicate things like loops, conditional conditional clauses and so on. Spaces in  FISH  are   are “significant” in the sense that space characters may not be inserted into a variable or function name. One other topic that should be addressed now is that of variable  type. You may have noticed, when printing out variables from the various program examples, that numbers are either printed without decimal points or in “E-format” — that is, as a number with an exponent denoted by “E.” At any

FLAC 3D Version 3.0

 4 - 10

User’s Guide

instant in time, a  FISH  variable  variable or function name is classified as one of four types:  integer , floating point , string or pointer . These types may change dynamically, depending on context, but the casual user should not normally have to worry about the type of a variable, since it is set automatically. Consider Example Consider  Example 4.11. 4.11.  Example 4.11 Variable types new def hav haveon eone e aa = 2 bb = 3.4 cc = ’Hav ’Have e a nice nice day’ day’ dd = aa * bb ee = cc + ’, old cha chap’ end haveone print pri nt fis fish h

The resulting screen display looks like this: Value

Name

-----

----

2

aa

3.4000e+000

bb

- string -

cc

6.8000e+000

dd

- string -

ee

0

h a v eo n e

The variables aa  and  string, respectively, corresponding aa,,  bb and cc are converted to  integer ,  float  and to the the numb number erss (or (or stri strings ngs)) that that were were assi assign gned ed to them them.. Inte Intege gers rs are exac exactt numb number erss (wit (witho hout ut deci decima mall points) but are of limited range; floating-point numbers have limited precision (about 15 decimal places places), ), but but are of much much greate greaterr range; range; string string varia variable bless are arbitra arbitrary ry sequenc sequences es of charact characters; ers; pointers 3D are used to address internal variables in  FLAC  . There are various various rules for conversi conversion on between the four types. For example, example, dd   becomes a floating-point number, because it is set to the product  dd  becomes of a floating-point number and an integer; the variable  ee  becomes a string because it is the sum (concatenatio (concatenation) n) of two strings. strings. The topic can get quite complicated, complicated, but it is fully explained in Sections 2.2.4 and 2.2.4  and 2.2.5  2.2.5.. There is a further language element in  FISH  that is commonly used — the IF statem statement ent.. The following three statements allow decisions to be made within a  FISH  program.   program.

IF ELSE ENDIF

FLAC 3D Version 3.0

expr1 expr1 test test expr2 expr2   THEN

  BEGINNER’S GUIDE  FISH  BEGINNER’S

 

4-11

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

#

>

<

>=

<=

The meanings meanings are standard except for #, which means means “not equal.” equal.” The items expr1 items expr1 and expr2 and  expr2 are any valid expressions expressions or single variables. variables. If the test is true, then the statements statements immediately immediately following  IF  are executed until  ELSE  or  ENDIF  is encountered encountered.. If the test is false, the statements statements between  ELSE  and  ENDIF  are executed if the  ELSE  statement exists; otherwise, the program jumps to the first line after  ENDIF. The action of these statements is illustrated in  Example 4.12. 4.12.  Example 4.12 Action of the IF ELSE ENDIF  construct new def def abc abc if xx > 0 then abc = 33 else abc = 11 end_if end set xx = 1 print pri nt abc set xx = -1 print pri nt abc

The displa displayed yed value value of abc of abc in Exa Exampl mplee 4.1 4.12 2 depe depend ndss on the the set set value alue of xx. You should experiment experiment xx. You with different test symbols (e.g., replace  >  with  < ). Until Until now now, our FISH program programss have have been invo invoked ked from from FLAC 3D, eith either er by usin using g the the PRINT command, 3D or by giving the name of the function on a separate line of  FLAC    FLAC  input. It is also possible to do 3D the reverse — that is, to give  FLAC  commands from within a  FISH  function.   function. Most valid  FLAC 3D commands can be embedded between the following two  FISH  statements:  statements:

COMMAND ENDCOMMAND There are two main reasons for sending out  FLAC 3D commands from a  FISH  program.   program. First, it is possible to use a  FISH  function   function to perform operations that are not possible using the pre-defined variables variables that we already discussed. discussed. Second, Second, we can control a complete FLAC 3D run with  FISH . As an illustration of the first use of the  COMMAND   statement, we can write a  FISH  program   program to install a number of cable elements at different depths in a material. When many cable elements are required, it becomes tedious to type many separate  SEL cable  commands, each with different grid values. values. Howeve However, r, with  FISH , we can send out the commands from within a loop and assign the location of the cable ends automatically each time around the loop, as illustrated in  Example 4.13. 4.13.

FLAC 3D Version 3.0

 4 - 12

User’s Guide

 Example 4.13 Automated placing of cable elements new gen gen zone zone bric brick k size size 10 3 5 def place_cables place_cables loop loop n (1,5 (1,5) ) z_d z_d = floa float( t(n) n) - 0.5 0.5 command sel sel cable cable beg beg 0.0, 0.0,1. 1.5, 5,z_ z_d d end 7.0, 7.0,1. 1.5, 5,z_ z_d d nseg nseg 7 end_command end_loop end place_cables plot plot grid grid sel sel geom geom red red

After entering these statements, you should do a printout and plot of the cable data to verify that five cables have been created, and that they are located at the appropriate positions in the grid. In the example, we use variable z variable  z d  as   as a parameter in the function  place cables;   is the cables; z d  is z-coordinate -coordinate of the endpoints endpoints of each cable. We can modify this example example to perform a constructio construction n sequence sequence of excavation excavation and installati installation on of  cables. cables. This illustrat illustrates es the second use of  COMMAND   COMMAND. We use the  FREE  and  SOLVE  commands to “excavate” the boundary plane at  x  = 0 in five steps. steps. At the end of each step, step, we instal installl a row row of  three cables and then excavate the next section of the boundary.  Example 4.14 Sequence of excavation and cable placement new gen gen zone zone bric brick k size size 10 3 5 mod mod mohr mohr prop prop bulk bulk 1e8 1e8 shea shear r .3e8 .3e8 fric fric 35 prop prop coh coh 1e3 1e3 tens tens 1e3 1e3 ini ini dens dens 1000 1000 set gra grav v 0,0 0,0,-1 ,-10 0 fix x y z range z -.1 .1 fix y

range y -.1 .1

fix y

range y 2.9 3.1

fix x

range x -.1 .1

fix x

range x 9.9 10.1

set lar large ge hist his t unb unbal al solve save cab_str.sav cab_str.sav ini xdis 0 ydis 0 zdis dis 0 hist hist gp xdis xdisp p 0,1, 0,1,5 5 def place_cables place_cables

FLAC 3D Version 3.0

  BEGINNER’S GUIDE  FISH  BEGINNER’S

 

4-13

loop loop n (1,5 (1,5) ) z_d z_d = 5.5 5.5 - floa float( t(n) n) z_t = z_d + 0.5 z_b = z_d - 0.5 command free x ran range

x -. -.1 1,.1

z z_ z_b b,z_t

solve sel sel cable cable beg beg 0.0, 0.0,0. 0.5, 5,z_ z_d d end 7.0, 7.0,0. 0.5, 5,z_ z_d d nseg nseg 7 sel sel cable cable beg beg 0.0, 0.0,1. 1.5, 5,z_ z_d d end 7.0, 7.0,1. 1.5, 5,z_ z_d d nseg nseg 7 sel sel cable cable beg beg 0.0, 0.0,2. 2.5, 5,z_ z_d d end 7.0, 7.0,2. 2.5, 5,z_ z_d d nseg nseg 7 sel sel cabl cable e prop prop emod emod 2e10 2e10 yten ytensi sion on 1e8 1e8 xcar xcarea ea 1.0 1.0 & gr_k gr_k 2e10 2e10 gr_c gr_coh oh 1e10 1e10 gr_ gr_pe per r 1.0 1.0 end_command end_loop end place_cables save cab_end.sav cab_end.sav plot plot sket sketch ch sel sel cable cable forc force e red red

We have have now now cove covere red d some some of the the aspe aspect ctss of the the FISH langua language ge and how how it intera interacts cts with with FLAC 3D. A complete guide to the language is contained in Section in  Section 2 in 2  in the FISH  the  FISH  volume,  volume, detailed information on FISH lang langua uage ge names names is give given n in Sec Sectio tion n 2 in the the FISH volume and some some exam exampl ples es are are prov provid ided ed  FISH volume,, and in Section in  Section 3 in 3  in the FISH  the  FISH  volume.   volume.

FLAC 3D Version 3.0

 4 - 14

FLAC 3D Version 3.0

User’s Guide