FISH is a scripting language embedded within UDEC that allows you to create new model variables, customized functionality and interact with the model. FISH was developed in response to requests from users who wanted to do things with Itasca software that were either difficult or impossible to do with existing program structures. Rather than incorporate many new and specialized features into the standard software, an embedded language was provided so that users could write their own functions. For example, FISH functions can be written to:
- Prescribed unusual property distributions within the model;
- Calculate, plot and print user-defined variables;
- Implement custom model geometries and joint generators;
- Simulate numerical tests of servo-control material strength testing (e.g., UCS, triaxial, shear);
- Specify unusual boundary conditions (variations in time and space); and
- Automate parametric and sensitivity studies.
FISH functions can be simply defined anywhere in a UDEC data file. For example, the function abc will execute a simple mathematical expression when called.
define abc
abc = 22 * 3 + 5
end
Functions may invoke other functions, which may invoke others, and so on. The order in which functions are defined does not matter, as long as they are all defined before they are called. A compiled form of every FISH function in UDEC’s memory space and the current values of associated variables are all stored as part of a UDEC save file. FISH variables can be called directly, embedded symbolically into UDEC commands and called at any stage of the calculation cycle.
The FISH scripting language incorporates:
- Integer, floating and string variable types;
- Data arrays;
- Pre-defined UDEC model variables (block, contact, boundary, gridpoint, zone, structural elements, etc.);
- Customizable user-variables;
- Intrinsic math, trigonometric, table and logic functions (clock, cos, sqrt, urand, pi, max, etc.);
- Conditional statements (if, else, case);
- Control loops;
- Input and output statements and text boxes;
- ASCII and binary data file import, export and parsing functions;
- Data exchange between two or more Itasca software running simultaneously;
- Embedded commands; and
- Embedded user-comments.
FISH functions can be as simple as the previous example, more advanced as shown below or they can be made up of combinations of hundreds of other FISH functions comprising thousands of lines of code. Although the latter can be quite complicated, it can be remarkably powerful, providing users tremendous flexibility and control in their modeling. This example automatically places cable structural elements into a model from a center point along an arc.
FISH Editor Pane
FISH functions can be (1) manually entered into the record, (2) written using a third-party text editor and called, imported or pasted into the record or (3) written and edited using the built-in FISH editor pane. A FISH function created with the latter can be executed directly from the FISH editor.
The editor is divided into three tabbed views. A new FISH function can be written, or an existing function can be opened, in the FISH editor view. Input parameters for the function are specified in the Parameters view. Reference information and a bitmap image to describe the function can be entered via the Information view. The FISH function can either be executed as a CALL file in the UDEC model or the contents of the function can be echoed directly in the Console and Record panes, interrupted, or saved. Should an error occur during execution, an error message will be shown in the Console output area to help identify the cause of the error. Corrections can then be made directly in the Editor text area, and the function executed again. Once you are satisfied that the function is working properly, you can include the function in the UDEC project record tree by pressing OK at the bottom of the FISH editor pane. The function then will be executed and incorporated in the current branch of the project tree and the FISH editor will be deactivated.