PFC手册中文翻译整理3FISH

1、FISH语言 4FISH语言初学指南4.1介绍和概述FISH是一种内嵌于PFC2D的编程语言，使用户能够定义新的变量和函数。这些函数可以扩大PFC2D的应用范围或增加用户定义特性。例如，可以绘制或打印新的变量，生成特殊粒子，将伺服控制用于数值试验，指定性能的不均匀分布，以及自动进行参数研究。FISH语言是针对那些想用Itasca软件做些事情的人开发的，而用现存的Itasca软件很难或者说不可能做到。它提供了一个内置语言，因此用户可以写自己需要的函数，而不是在标准代码中加入许多新的和专门的功能。一些有用的FISH函数已经写出；这些函数的相互关联设置，称为扩张的Fishtank，在PFC2D程序中

2、给出（见FISH volume第3节）。对于没有编程经验的人，写一些简单的函数或对现有的函数作一些简单修改是可行的。第4.2节为非程序员作了介绍。但是FISH程序也可以变的复杂（在任何编程语言中的代码都是这样）；更多详细资料参见FISH volume第2节。与所有的编程任务一样，FISH函数应按一个渐进的方式编写，在编写更加复杂的代码之前每一步都要检查运行。FISH函数的错误检查不会比大多数编译器少，因此所有的函数在用于实际应用之前，应进行简单的数据测试。FISH程序简单地嵌入一个正常的PFC2D数据文件在DEFINE后面的行是FISH函数；函数遇到END终止。FISH函数还可以调用其它函数。

3、定义函数的顺序并不重要，只要它们都是先定义后使用（例如通过PFC2D命令引用）。由于FISH函数的汇编形式是储存在PFC2D的存储空间，SAVE命令保存FISH函数和相关变量的当前值。FISH语言规则和固有功能的完整定义见FISH volume第2节。其中包括语法规则，数据类型，运算，变量和函数。所有FISH语言名称在FISH volume第2节进行了描述，在命令和FISH参考概要中给出了这些名称的概要。4.2新手指南和教程本节是为已经运行PFC2D（至少是一些简单问题）而没有使用FISH语言的人准备的；如果没有编程经验。为了从例子中获得最大的好处，你应该尝试用PFC2D运行这些例子。短的程序

4、可以直接键入。在运行一个例子之后，使用命令NEW“清除界面”，就可以为下一个例子作准备。另外较长的程序可以先在文件中创立然后用CALL调用。在PFC2D命令提示后面输入例4.1中的各行，每输入一行便在其末尾按<enter>键。（在此和后面的所有例子，第一行用了分号，这仅表示注释不必输入。）注意在输入第一行后（不是注释行），命令提示符变为DEF>；当输入END命令后，命令提示符变为常用提示符。如果你是在给PFC2D或FISH输入行得到话，提示符的变化会让你了解。通常情况下，DEFINE语句后面的所有行都作为FISH函数定义的一部分（直到输入END语句）。但是如果输入的行中有错误

5、（例如将“=”输入为“+”），那么会使PFC2D提示符回到原来状态。在这种情况下，应输入NEW命令重新开始。因为输入很容易出错，因此FISH程序通常通过编辑器输入文件。它们被PFC2D调用就像正常的PFC2D数据文件。这一过程将稍后描述；现在继续运行。如果在输入下面行时没有错误，在PFC2D>提示符下，实现abc函数的值（在前面例4.1中定义的），输入行：将得到：通过定义符号abc（用DEFINEEND结构，如例4.1），现在在使用PFC2D的许多方面都涉及到该结构。例如PRINT命令使FISH函数的值显示出来；该值经过一系列的算术运算：这是一个赋值语句。如果等号成立，等号右边的表达式值

6、将赋给等号左边的变量。注意算术运算按照通常的法则；加、减、乘、除分别用符号+，-，*，/表示。符号“”表示指数。我们现在输入一个稍微不同的程序（用命令NEW清除旧的）：这里我们引入变量hh，给它赋值为22，在后面的行用到。如果我们输入命令PRINT abc，输出的结果与前面完全相同。但是我们这里用到两个FISH符号；它们都有值，一个（abc）是作为函数。另外一个（hh）是作为变量。它们的区别如下：当用到FISH函数符号名时（例如在PRINT语句中），如果符号对应一个函数，那么相关的函数将被执行。但是，如果符号并不是一个函数名称，那么仅仅使用符号的当前值。下面的实验可以帮助澄清区分变量和函数。在

7、此实验之前，请注意，PFC2D的SET命令可以用来设置任何用户定义的FISH符号的值，符号在FISH程序中的独立性已介绍。现在，键入以下行不使用NEW命令，因为我们希望保留以前输入的程序。SET命令将abc和hh的值设为0。因为hh是一个变量，第一个PRINT命令简单地显示了hh的值为0。第二个PRINT命令使abc执行（因为abc是函数名）；hh和abc的值被重新计算。因此，第三个PRINT命令表明hh已经重置其原来的值。为了测试您是否已经理解，请输入稍作修改的程序（例4.4）并指出为什么显示的答案是不同的。在这个阶段，直接列出涉及到FISH变量或函数的PFC2D最重要的命令是很有好处的。（

8、见表4.1，var代表变量或函数名）我们已经看到了前面的两个例子（参考例4.3和4.4）；第三种有用的情况是，当在历史变量的。例4.5说明了如何做到这一点。例4.5显示了粒子的不平衡力是如何储存在FISH变量中和通过HISTORY命令使用的。在这个例子中，一个球落到平面上，经反弹后达到平衡。b_yfob在函数中是一个预定义的变量名在这种情况下，为相应的在y方向的不平衡力。Ball_head是另外一个预定义名，为相应的球的“地址”。PFC2D所有预定义的名称在FISH volume的表2.1中给出。运行结束后，与其它历史一样，我们简单的绘制了yforce（历史1，y方向的不平衡力）。以类似的方式

9、，可以用FISH函数绘制任何数量我们想得到的历史，不管用多么复杂的公式来描述它。除了上述预定义的变量名，还有许多其它提供给FISH程序的预定义对象。它们可以分为几类；有一类是是由标量变量组成，它们有单一的号码例如：内置于对象有用的另一类是一系列的固有功能，这些固有功能可以使诸如正弦和余弦之类的函数能在FISH中程序计算。完整的清单见FISH volume中第2.5.2节；一部分如下：使用固有功能的例子稍后给出。现在我们必须讨论一种更深入的方法，运用这种方法，PFC2D数据文件可以利用用户定义的FISH名。当想在PFC2D中输入一个数字时，可以用FISH变量或函数来代替。这个简单的声明对于FIS

10、H非常强大的功能来说是很重要的，它允许在FISH函数中计算，并使用通过PFC2D以符号形式输入的诸如范围，作用力和性能等。因此，参数的变化可以很容易，而无需在输入文件中改变许多号码。例如4.6要求将墙的几何形状和刚度定于文件开始的某个位置，而不是许多位置。这就减少了出现错误和数据文件紊乱的风险，以及在许多模型中重复利用一块工作。顺便请注意，为FISH变量和函数选择名称有很大的灵活性；字符“_”可以包含在名称中。名称必须以非数字开头，并且不能包含任何算术运算符（+，-，*或）。选定的名称不应与内置（或保留）名称相同；FISH volume第2.2.2节中表2.1包含所有需要避免的名称的清单，以及

11、应该遵循的一些规则。在上面的例子中，我们检查了FISH变量的计算值，通过将它们的名称直接给PRINT命令。另外，我们可以通过命令print fish列出当前所有的变量和函数。我们现在研究如何在FISH程序中进行选择和循环运行。下面的FISH语句允许程序的指定部分重复多次。LOOP和ENDLOOP是FISH语句，字符var代表loop变量，expr1和expr2代表表达式（或单个变量）。例4.7显示了循环的应用（或重复顺序），得到10的阶乘。在这种情况下，循环变量n从1连续变化到10，循环里面的语句（在LOOP和ENDLOOP之间的语句）对每个价都执行。如前所述，变量名称或算术表达式可取代1到1

12、0之间的数字。在PFC2D中一个实际使用的循环，将按顺序选取模型中的每个球并访问和/或改变一些属性。例4.8包含了FISH函数makecolors，说明了（随机，在这种情况下）如何改变模型中每个球的颜色指数。其中0到2内的整数值指定为颜色指数。我们已经看到了几个FISH程序的例子，让我们简要地检查一下程序语法和风格的问题。一个完整的FISH语句必须占一行；没有连续行。如果一个公式太长而不能放在一行，那么必须用一个临时变量将公式分开。例4.9说明了这个问题。在这种情况下15个变量的和被分为两部分。注意分号之后的函数名表示注释。分号之后的任何字符都会被FISH编译器忽略，但是它们反映了日志文件。带

13、有信息的注释程序是非常好的。有些程序出现了缩进在某些行的开头插入空格来说明相关的一组语句。可以在变量名和算术运算之间插入（随意地）任何数量的空格字符使程序更具可读性。通过缩进来表示循环，条件语句等是很好的程序实践。空格在FISH中的“重要”意义，即空格字符不可以插入变量和函数名中。需要说明的另一个问题是变量的类型。您可能已经注意到，当从各种程序的例子打印出变量时，这数字没有小数点或“E格式”指数的次数。在任何时候，FISH函数或变量名分为四种类型：整数，浮点数，字符串和指针。这些类型可以根据情况发生动态变化，但临时的用户不必担心变量类型，因为它是自动设置的。思考例4.10。与变量aa,bb,c

14、c相对应分配给它们的数字（或字符串）分别转化为整数，浮点数和字符串。整型是精确的数字（没有小数点），但范围有限；浮点数精度有限（大约精确到小数点后15位），范围较大；字符串变量是任意的字符序列；在PFC2D中指针用来处理内部变量。四种类型存在一定转换规则。例如，dd成为一个浮点数，因为它是一个浮点数和一个整数的乘积；ee变变成一个字符串，因为它是两个字符串的和（串联）。这个问题可以相当复杂，它的充分解释见FISH volume第2.2.5节。此外，FISH中还有常用的语言要素if语句。下面的三个语句通过FISH程序可以做出选择。这些语句允许FISH程序有条件的执行，ELSE和THEN表示选择。

15、测试的项目包括下列其中一个符号或符号配对：The meanings are standard except for #, which means “not equal.”expr1和expr2是任意有效的表达或单一变量。如果测试为真，立即执行IF后的语句直到遇到ELSE或ENDIF。如果测试为假，则执行ELSE和ENDIF之间的语句；否则程序跳到ENDIF后的第一行。这些语句的应用见例4.11。例4.1中显示的abc的值取决于xx的值。可以用不同的测试符号检验（例如用“<”代替“>”。到现在为止，我们已经调用了来自PFC2D的FISH程序，通过使用PRINT命令，或在PFC2D输入

16、窗口独立行中给定函数名。也有可能是相反的就是在FISH函数中给？最有效的PFC2D命令是位于下列两FISH语句之间：从FISH程序中发出PFC2D命令主要有两个原因。首先，它可以使用FISH函数执行我们已经讨论过的预定义变量不能实现的操作。第二，我们可以控制FISH在PFC2D中的整个运行。在例4.12中，我们通过函数make walls创建了四个墙。为了从FISH函数中执行这四个PFC2D墙命令，它们必须在置于COMMAND ENDCOMMAND结构之间。我们现在已经覆盖到了FISH语言的一些方面以及如何与PFC2D相互作用。FISH语言的完整指南见FISH volume第2节。墙的状态信息

17、功能墙的状态信息包括位置，速度，非平衡加载和固定。W_pos(wp,dof) 旋转中心的位置（dof为分量形式，其中dof1，2，3）W_x(wp) 旋转中心的位置(x分量)W_y(wp) 旋转中心的位置(y分量)W_z(wp) 旋转中心的位置(z分量)W_vvel(wp,dof) 速度（dof为分量形式，其中dof1，2，3）W_xvel(wp) 速度（x分量）W_yvel(wp) 速度（y分量）W_yvel(wp) 速度（z分量）W_rvel(wp) 旋转中心周围的旋转速度W_vrvel(wp,dof) 旋转中心周围的旋转速度（dof为分量形式，其中dof1，2，3）W_vxvel(wp)

18、 旋转中心周围的旋转速度(x分量)W_vyvel(wp) 旋转中心周围的旋转速度(y分量)W_vzvel(wp) 旋转中心周围的旋转速度(z分量)W_vfob(wp,dof) 考虑所有墙产生的非平衡力（dof为分量形式，其中dof1，2，3）W_xfob(wp) 非平衡力（x分量）W_yfob(wp) 非平衡力（y分量）W_zfob(wp) 非平衡力（z分量）W_mom(wp) 由所有发生接触的球产生的旋转中心的非平衡力矩W_vmom(wp,dof) 旋转中心的非平衡力矩（dof为分量形式，其中dof1，2，3）W_xmom(wp) 旋转中心的非平衡力矩（x分量）W_ymom(wp) 旋转中心

19、的非平衡力矩（y分量）W_zmom(wp) 旋转中心的非平衡力矩（z分量）W_radend1(wp) 圆柱墙的end1（endpoint1）的半径W_radend2(wp) 圆柱墙的end2（endpoint2）的半径W_radfob(wp) 圆柱墙的径向非平衡力W_radvel(wp) expand或contract圆柱墙的径向速度W_fix(wp) 如果此值被设置成非零时，那么、墙节点速度的更新是向内（inhibited）的。一般来说，这个标志是在墙节点被用户自定义一个功能的时候直接使用。2.5.1.5 wall-sagment 的功能在PFC2D中，wall-sagment 的功能以wa

20、ll-sagment数据结构执行。由每个组成墙的wall-sagment被储存在一个连着的序列中，这个序列都可以由命令w_wlist(wp)得到。这个连着的序列可以利用以下两个命令两面翻转（即可以以任一端为头）ws_next(wsp) 和ws_prev(wsp)。注意，由每个wall-sagment组成的墙可以是封闭的，也可以是开放的。Ws_next(wsp) 在上述序列中下一个wall-sagment的地址。（当墙是不闭合的时候，那么在该序列中，最后一个sagment的ws_next为null。相反，如果墙是闭合的时候，那么序列中最后一个segment的ws_next则为序列的第一个segm

21、ent ）Ws_prev(wsp) 在上述序列中前一个wall-sagment的地址。（当墙是不闭合的时候，那么在该序列中，第一个sagment的ws_prev为null。相反，如果墙是闭合的时候，那么序列中第一个segment的ws_prev则为序列的最后一个segment。）Ws_length(wsp) wall segment wsp 的长度Ws_x(wsp) 与在上述序列中此segment的第一个节点相应的wall segment wsp的end-0的位置坐标（x分量）。（当墙是由n个segment组成的开放环时，则此时会有n+1个wall segment数据结构，而且最后一个节点的位

22、置坐标会储存在最后一个segment的数据结构中。）Ws_x(wsp) wall segment wsp的end-0的位置坐标（y分量）Ws_xun(wsp) wall segment wsp的单位法向向量（x分量）。（这个单位法向向量指向墙的有效面。如果墙是由n个segment组成的开放环时，则会有n+1个wall segment数据结构，而且最后的segment的单位法向向量不会被定义。）Ws_yun(wsp) 单位向量（y分量）Ws_xvel(wsp) 速度（x分量）Ws_yvel(wsp) 速度（y分量）2.5.1.6 wall-face的功能wall-face的功能的执行基于PFC3

23、D有限wall-face结构。每个有限长度的wall组成的Wall-face的信息储存在一个连接的链当中，其中数据链的头由wall-support 功能中的w_flist(wp)命令调用。这个数据链可以用wf_next(wp)功能截断。Wf_next(wfp) 由墙组成的face wall的数据链中下一个facewall的地址。Wf_xun(wfp) wallface wfp的单位法向量（x分量）。（这个单位法向量指向强的有效面的反向。）Wf_yun(wfp) wallface wfp的单位法向量（y分量）Wf_zun(wfp) wallface wfp的单位法向量（z分量）2.5.1.7 （

24、parallel-bond）平行键的功能平行键功能的执行是在PFC2D的平行键数据结构上。平行键的信息与每一个接触有关，储存地址可以通过c_pb命令获得。这个功能被分为两类，每一种都有它自己的小节：物理性质（see table 2.24）和陈述信息（see table 2.25）.平行键的语法的描述见理论与背景中的2.3.2节。平行键物理性质功能Pb_kn(pbp) 法向硬度（应力/位移）Pb_ks(pbp) 切向硬度（应力/位移）Pb_nstrength(pbp) 法向载荷（应力）Pb_sstrength(pbp) 切向载荷（应力）Pb_rad(pbp) 半径相加，因此平行键半径为Pb_ra

25、d与两接触小球中最小半径的乘积。Pb_nforce(pbp) 键材料承载的法向力；正值代表压缩；方向由c_vun(cp)给定Pb_sforce(pbp) 在接触面上键材料承载的切向力，接触面由c_vun(cp)给定Pb_vsforce(pbp,dof)切向力向量（dof为向量的分量，dof属于1，2，3） Pb_xsforce(pbp) 切向力向量（x分量）Pb_ysforce(pbp) 切向力向量（y分量）Pb_zsforce(pbp) 切向力向量（z分量）Pb_mom(pbp) 键材料承载的弯曲力矩Pb_tmom(pbp) 键材料承载的扭曲力矩（这个力矩就在两个圆心的连线上）Pb_vmom

26、(pbp,dof) 键材料承载的弯曲力矩向量（dof为向量的分量，dof属于1，2，3）Pb_xbmom(pbp) 键材料承载的弯曲力矩向量(x分量)Pb_ybmom(pbp) 键材料承载的弯曲力矩向量(y分量)Pb_zbmom(pbp) 键材料承载的弯曲力矩向量(z分量)Pb_nstress(pbp) 作用在键外围的最大法向力Pb_sstress(pbp) 作用在键外围的最大切向力2.5.1.8 measurement-circle 的功能measurement-circle 的功能的执行基于measurement-circle 数据结构。这些功能被分为以下几类：辅助(see table 2

27、.26) 和 陈述信息(see table 2.27)。measurement-circle的信息被储存在一个首尾相连的链中，可以用circhead命令调用他的头。储存地址也可以由辅助命令findmeas 见 table 2.5. measurement-circle 的语法的描述见理论与背景中的3.4节。measurement-circle辅助功能M_id(mp) measurement-circle mp 的ID号码M_next(mp) 数据链中下一个measurement-circle的位置。M_rad(mp) measurement-circle mp 的半径measurement-c

28、ircle 陈述信息功能注意到应力或张力率的当前值在measure（）功能被执行了以后才能使用，调和数（详细见下文）、空隙率和滑动比则没有此要求。M_ccord(mp) 调和数（每个球的平均解除数）M_poros(mp) 空隙率M_sfrac(mp) 滑动比（正在滑动的面积占重面积的比值）Measure(mp,code) 计算measurement circle mp的所有的应力(stress)成分（如果code=1）或者measurement circle mp的所有的张力率（strain rate）成分（如果code=2），并把结果储存在相应的与mp相关的数据结构里比如m_ed11和m_s

29、11等。注意并未定义返回值。2.5.19 clump的功能clump的功能的执行基于PFC2D中的clump数据结构。这些功能被分为一下几类：援助（见table 2.28）和陈述信息（见table 2.29）。clump的信息储存在一个首位相连的数据链中，利用clump_head命令可调用其头数据。储存地址也可以通过table2.9所示的命令获得，b_clump和b_cllist。Clump的语法的描述见理论与背景中的section4clump的援助功能Cl_add(clp,bp) 把小球bp加入到clump clp中，并返回加入小球的那个clump的地址。如果clp是null，那么就创立一个

30、新的clump，并返回他的地址。War=cl_extra(clp,i) 把clump clp的cl_extra结构的第i个槽中的FISH变量的值以及类型制定为常规FISH变量var（见set extra clump 命令）cl_extra(clp,i)= War 上个命令的反命令。（见set extra clump命令）cl_list(clp) 由clump clp组成的小球的局部数据链的头。（这个数据链可以通过b_cllist命令截断。）cl_id(clp) clump clp的ID号码cl_next(clp) clumps的全局数据链中的下一个clump的地址cl_rel(clp,bp)

31、在clump clp中删去小球bp。注意未定义返回值clump的陈述信息功能Cl_vpos(clp,dof) 质心的坐标（dof为分量形式，dof属于1，2，3）Cl_x(clp) 质心的坐标（x分量）Cl_y(clp) 质心的坐标（y分量）Cl_z(clp) 质心的坐标（z分量）Cl_vvel(clp,dof) clump的质心的坐标（dof为分量形式，dof属于1，2，3）Cl_xvel(clp) clump的质心的速度（x分量）Cl_yvel(clp) clump的质心的速度（y分量）Cl_zvel(clp) clump的质心的速度（z分量）Cl_vrvel(clp,dof) 以clum

32、p的质心为中心的旋转速度（dof为分量形式，dof属于1，2，3）Cl_rvel(clp) 以clump的质心为中心的旋转速度Cl_vxvel(clp) 以clump的质心为中心的旋转速度(x分量)Cl_vyvel(clp) 以clump的质心为中心的旋转速度(y分量)Cl_vzvel(clp) 以clump的质心为中心的旋转速度(z分量)Cl_vfob(clp,dof) 非平衡力（dof为分量形式，dof属于1，2，3）Cl_xfob(clp,dof) 非平衡力（x分量)Cl_yfob(clp,dof) 非平衡力（y分量)Cl_zfob(clp,dof) 非平衡力（z分量)2.5.1.10 cell信息的功能cell信息的功能的执行基于PFC2D的cells，这些cells指向一个PFC2D cell数据结构。Cell_li