Executing FISH: Inline FISH or FISH Fragments

In general, FLAC3D and FISH operate as separate entities; FISH statements cannot be given as FLAC3D commands, and FLAC3D commands do not work directly as statements in a FISH program. However, there are many ways in which the two systems may interact; some of the more common ways are listed below.

  1. Direct use of function – A FISH function can executed at the user’s request by giving its name on the input line delimited by brackets:

    [myfunc]

    Some typical uses are to generate geometry, set up a particular profile of material properties, or initialize stresses in some fashion.

  2. Use as a history variable – When used as the parameter to a fish history command, a FISH function is executed at regular intervals throughout a simulation, whenever histories are stored.

  3. Automatic execution during stepping – If a FISH function makes use of the generalized callback capability, then it is executed automatically at every step in FLAC3D’s calculation cycle, or whenever a particular event occurs. (See fish callback for a discussion on callback events.)

  4. Use of function to control a run – Since a FISH function may issue FLAC3D commands (via the command statement or the system.command function), the function can be used to “drive” FLAC3D, similar to the way a data file is controlled. However, the use of a FISH function to control operation is much more powerful, since parameters to commands may be changed by the function.

The general rule during command processing is:

  1. If a line of FISH or a FISH function is being executed directly, then the code must be enclosed in [].

  2. If FISH is being substituted for a value on the command line, then the the FISH must be enclosed in [].

  3. If the command syntax indicates that a FISH symbol must follow, then the symbol name may be given directly. It need not be enclosed by string delimiters or enclosed in [].

Basically, if there is any ambiguity about whether FISH is expected at a given location in the command line, then it must be enclosed in [] to make it clear.

FISH code encountered during normal command processing (outside of a fish define or fish operator command) that is enclosed in [] is called inline-FISH, or FISH-fragments.

The primary way of executing a FISH function from FLAC3D is to give a line of fish enclosed by [] that includes the function name. For example the following code will execute the FISH function fred when encountered on the command line:

FISH fragments can also be executed directly as a convenient, single-line shorthand that bypasses the need to create an explicit function:

There is another important link between FISH and FLAC3D: In a FLAC3D command, a FISH symbol (variable or function name) may be substituted anywhere that an input value is expected. This is a very powerful feature, because data files can be set up with symbols rather than with actual numbers.

In this example, the x coordinates of the scalars generated are all controlled by the inital setting of the FISH symbol fred. This extremely simple example of parameterization is a powerful feature of the language acting in combination with the data file description of the model. It allows quick and easy creation of models that vary within a parameter space. Material properties, feature size, amount of structural reinforcement, etc. are commonly parameterized at the beginning of model creation so the effect of varying those important parameters can be explored.

Another important method of using a FISH function is to control a FLAC3D run or a series of FLAC3D operations. FLAC3D commands are placed within a command - endcommand section in the function. The whole section may be within a loop, and parameters (local or global) may be passed to FLAC3D commands.

A relatively simple example of this can be found in the verification problem Uniaxial Compressive Strength of a Jointed Material Sample (FLAC3D).

Note that inline FISH is parsed and executed every time an attempt to evaluate the token is made, which might happen several times while the command as a whole is processed if multiple token types are accepted and each must be checked. [CS: a for instance example to illustrate would be great here] Be aware of possible side effects and efficiency issues.