FISH Scripting

FISH Rules and Usage

Lines

Data Types

Reserved Names for Functions and Variables

Scope of Variables

Functions: Structure, Evaluation, and Calling Scheme

Arithmetic: Expressions and Type Conversions

Redefining FISH Functions

Execution of FISH Functions

Inline FISH or FISH Fragments

FISH Error Handling

FISH Callback Events

FISH Debugging

FISH Scripting

FISH是一种嵌入式编程语言，使用户能够与PFC模型进行交互和操作，根据需要定义新的变量和函数。这些功能可用于扩展PFC的用途或增加用户定义的功能。

FISH程序被简单地嵌入到一个正常的PFC数据文件中。define字样之后的行被作为FISH函数处理；当遇到end字样时，函数终止。函数可以调用其他函数，而其他函数可以调用其他函数，以此类推。定义函数的顺序并不重要，只要它们在被使用之前都被定义了。

FISH Rules and Usage

Lines

FISH程序可以嵌入到PFC数据文件中，也可以直接输入到控制台。

FISH的变量、函数名和语句必须全拼--它们不能被截断，这与PFC命令不同。允许在行末使用...控制语句的续行。FISH在任何时候都是 "不区分大小写的"。空格可以用于分隔变量、关键字等，以提高可读性；在变量或函数名称中不允许嵌入空位。分号（；）后面的任何字符都会被忽略；注释可以通过在FISH程序前面加上分号来嵌入。

有效的fish代码的形式：

①The line starts with a statement, such as if, loop, etc. (see “FISH statements”).
②The line contains one or more names of user-defined FISH functions, separated by spaces (for example, fun_1 fun_2 fun_3).
③The line consists of an assignment statement (i.e., the expression on the right of the = sign is evaluated, and the value is given to the variable or function name on the left of the = sign).
④The line consists of a PFC command, provided that the line is embedded in a section of FISH code delimited by command - endcommand.
⑤The line is blank or starts with a semicolon.

该行是空白或以分号开始。

Data Types

FISH变量的形式：

①Integer: Exact numbers in the range -2,147,483,648 to +2,147,483,647.
②Boolean: Either a value of true or false.
③Floating-point: Approximate numbers with about fourteen decimal digits of precision, with a range of approximately 10^-308 to 10^308.
④String: Packed sequence of any printable characters; the sequence may be any length, but it may be truncated when printed. Strings are denoted in FISH and PFC by a sequence of characters enclosed by single or double quotes (e.g., 'Have a nice day' or "Have a nice day"). See the “Strings” section for further details.
⑤Pointer: Machine address used when looping through a list and marking references to an object. They have an associated type from the object to which the pointer refers, except for the null pointer.
⑥Vector: 2D or 3D vector of floating-point types. 浮点类型的二维或三维矢量。
⑦Array: A collection of FISH variables with specified dimensionality.
⑧Matrix: Matrix of numeric values with specified dimensionality.
⑨Tensor: A symmetric tensor. 对称的张量
⑩Map: An associative array with string or number key and any FISH variable as value.
⑪Structure: A structure may contain multiple FISH variables.

string

唯一对字符串变量有效的算术运算是加法。

Pointer

指针可以不引用任何对象，也可以为 null。如果对象被删除或销毁，则所有 FISH 符号指向该对象的点将设置为 null。同样只能进行+运算。

vector

FISH中内置了五个协助创建和操作矢量的通用函数。这些函数被列在FISH参考文献的三个部分：comp.x、comp.y和comp.z在组件实用程序部分；math.dot和math.cross在数学实用程序部分；vector在构造函数部分。

数学运算符/、*、+、-可以在两个相同类型的向量之间使用。在向量和数字（整数或浮点）之间可以使用*运算符。在向量和数字之间也可以使用/运算符，但数字必须在右边。

Array（数组）

Arrays are less flexible and perform less well than Maps. We suggest arrays be replaced with Maps whenever possible.

array array1 (i1 , i2 …)
；创建名字为array1的array
array abc(1,2,3)
abc = array.create(1,2,3)
；前者是在编译时执行，而后者是在运行时执行。

数组对象也可以用array.create和array.delete的内在函数来创建和销毁。

一个FISH阵列的符号名称可以在命令行中使用，并带有索引参数：set gravity 0 0 @abc(1,2,3) ，其中abc指向一个三维数组。赋值情况： set @abc(1,2,3) = 4.0。list @abc(1,2,3)打印了数组的数组指针、数组大小以及数组条目。

model new
model random 10001
fish define afill          ; fill matrix with random numbersarray var(4,3)loop local m (1,array.size(var,1))loop local n (1,array.size(var,2))var(m,n) = math.random.uniformend_loopend_loop
end
fish define ashow          ; display contents of matrixloop local m (1,array.size(var,1))local hed = '   'local msg = '  '+string(m)loop local n (1,array.size(var,2))hed = hed + '               '+string(n)msg = msg + '  '+string(var(m,n),8,' ',8,'e')end_loopif m = 1io.out(hed)end_ifio.out(msg)end_loop
end
@afill
@ashow

Matrices

矩阵可以用array.convert方法转换为数组。矩阵可以由张量创建。

Tensors

FISH支持3x3的对称张量。张量在计算主轴和应力不变量时非常有用。张量可以被添加和相乘。注意，张量乘法的结果是一个矩阵。

Maps

地图与数组类似，它们以一种有序的方式存储FISH变量。与数组不同的是，地图的大小可以是动态的，用于从地图中检索数值的键可以是一个整数或一个字符串。

map1 = map (i1 or s1, var1, i2 or s2, var2, ...)
；其中键可以是整数或字符串。额外的值可以用map.add方法添加，用map.remove方法删除。我们可以简单地通过给出地图名称和括号（）中的键来访问值。

Structures

结构可以包含多个FISH变量。这是一种编程数据结构，可用于对FISH变量进行分门别类。

model new
fish define teststruct mystruct val1 val2 val3construct mystruct fred(1,2,3) test = fred->val1
end
[test]fish define test2construct mystruct fred(1,2,3)construct mystruct george(1,2,3)if ( fred == george )test2 = 7endif
end
[test2]

Reserved Names for Functions and Variables

①变量或函数名称必须以非数字开头，并且不能包含以下任何符号：. , * / + - ^ = < > # ( ) [ ] @ ; ' "

②变量或函数名称不区分大小写

③一般来说，名称可以任意选择，尽管它们不能与FISH语句或预定义的变量或函数相同

Scope of Variables

默认情况下，变量和函数名是全局识别的。当给出fish list symbols命令时，一个变量也会出现在显示的变量列表中。

如果FISH变量的自动创建选项被禁用（see the fish automatic-create command)），所有的全局变量必须用global关键字来声明。一个全局变量可以在一个FISH函数中被赋予一个值，并在另一个函数或PFC命令中使用。这个值会被保留，直到它被改变。所有全局变量的值也由模型保存model save命令保存，由模型恢复model restore命令恢复。

If the local identifier is used to declare a variable, the variable is considered local to that function and is not available once the function has been executed.

Functions: Structure, Evaluation, and Calling Scheme

FISH语言中唯一可以执行的对象是函数。

一个函数在被定义之前可以在另一个函数中被提及；FISH编译器只是在第一次提及时创建一个符号，然后在用define语句定义该函数时链接所有对它的引用。一个函数不能被删除，但它可以被重新定义。

函数可以被以下几种方式调用：

①as the single word xxx inside a FISH function;

②as the variable xxx in a FISH formula, e.g.,: new_var = (math.sqrt(xxx) / 5.6)^4;
③as a single word @xxx in a PFC input line;

④as a single word [xxx] enclosed in brackets as outlined here;

⑤as a symbolic replacement for a number in a PFC input line;

⑥as a parameter to the fish set, program list, or history commands.

Arithmetic: Expressions and Type Conversions

^ / * - + 运算

可以使用任意数量的小括号来明确计算的顺序；小括号内的表达式在其他东西之前被计算。

如果算术运算中的两个参数（arguments）中的任何一个是浮点类型的，那么结果将是浮点的（ floating-point type）。如果两个参数都是整数（integers），那么结果将是整数。

一个整数除以另一个整数会导致结果的截断。例如，5/2产生的结果是2，而5/6产生的结果是0。

It is important to note that the division of one integer by another causes truncation of the result. For example, 5/2 produces the result 2, and 5/6 produces the result 0.

Redefining FISH Functions

重新定义函数时注意事项：

①在一个函数中使用的变量仍然存在，即使该函数被重新定义；只有代码被删除。由于变量是全局性的，它们很可能被用在其他地方。
②所有对旧函数的调用都将调用新函数。这包括FISH的回调事件。注意，如果参数的数量发生变化，这将导致运行时错误。

Execution of FISH Functions

;fname: fishr12.dat
model new
model domain extent -10 10
contact cmat default model linearpbond
ball create id=1 pos-x=0.0 pos-y=0.0 pos-z=0.0 rad=0.5   ; create 5 balls in a line
ball create id=2 pos-x=1.0 pos-y=0.0 pos-z=0.0 rad=0.5
ball create id=3 pos-x=2.0 pos-y=0.0 pos-z=0.0 rad=0.5
ball create id=4 pos-x=3.0 pos-y=0.0 pos-z=0.0 rad=0.5
ball create id=5 pos-x=4.0 pos-y=0.0 pos-z=0.0 rad=0.5
ball attribute density 2000 damp 0.7
ball property 'kn'=1e8 'ks'=1e8  
; create contacts
model clean
; bond them into a beam using pbonds
contact method bond gap 0.1
contact property pb_kn=1e10 pb_ks=1e10 pb_ten=1e20 pb_coh=1e20
ball fix velocity spin range id=1     ; fix ball at left end
model gravity 0 0 -9.8                ; specify gravity loading
ball history name 10 position-z id=5    ; monitor y-position of tip ball
;
fish define run_seriesbdens = 2000.0loop nn (1,3)t_var = ' Density of tip ball = ' + string(bdens)commandball attribute dens @bdens range id=5  ; modify density of tip ballmodel title @t_var
model cycle 1000end_commandbdens = bdens + 3000end_loop
end
@run_series

Inline FISH or FISH Fragments

除了@符号约定外，还有一种替代的语法用于将FISH连接到命令行。任何在方括号[]内发现的东西都会被识别并被视为内联FISH（inline FISH）。

;提前创建函数
ball create id [ballID] position [ballPos] radius [ballRad]
;直接执行FISH片段，作为单行FISH的方便速记，不需要创建一个明确的函数
[global fred = math.cos(4.5)]
[execute_my_imported_fish_intrisic(with,three,arguments)]

FISH Error Handling

PFC有一个内置的错误处理机制，当程序的某些部分检测到错误时，就会调用这个机制。错误处理机制也可以在不涉及 "错误 "的情况下使用。例如，当检测到某一条件时，步进可以停止。

The same logic may be accessed by a user-written FISH function by using the system.error FISH function. If a FISH function assigns a string to system.error, then the error-handling facility of PFC is invoked immediately, and a message containing the string assigned to system.error is printed. Stepping and FISH processing stop as soon as system.error is set.

FISH Callback Events

在PFC程序执行过程中，FISH函数可以从多个地方被调用。将FISH函数附加到回调事件上会导致FISH函数被PFC执行，可以是在周期序列中的一个固定点，也可以是对一个特定事件的响应。可以通过fish list callbacks命令列出与回调事件一起注册的FISH函数集。

在fish callback命令中，可以给出删除关键字来取消FISH函数的注册。比如说

set fish callback 11.0 remove xxx删除函数xxx和循环点11.0之间的关联。

一个FISH函数可能与同一个周期点关联两次（或更多）。在这种情况下，它将被调用两次（或更多）。删除关键字将只删除FISH函数的一个实例。

FISH函数中的whilestepping表达式会自动将FISH函数插入周期点-1.0的周期序列中。

FISH Debugging

To enter debugging mode, use the fish debug command, supplying the name of a FISH function. If the function requires arguments, these must be specified on the command line following the function name. The arguments will be evaluated, and the function will begin to execute in debug mode.

While interpreting a FISH function, each line of source is converted (pseudo-compiled) into one or more pseudo-code objects, and these objects are executed when the function is called. Each pseudo-code object created is assigned a unique ID number for reference. Each pseudo-code object is also aware of the source file from which it originated and the line number of that file. The pseudo-code objects, their ID numbers, and their breakpoint status are available through the fish list code command.

在调试模式（debug mode）下，代码进入函数时就会停止。每次当前执行点发生变化时，信息就会输出到屏幕上。命令提示符变为Debug>，PFC等待用户对如何进行的回应。注意，将接受来自当前输入源的输入，因此有可能在数据文件中包括调试命令。

debug模式下可用命令