最新版PFC Command 命令大全
PFC3D命令说明
（COMMON COMMAND REFERENCE）
PFC3D是基于命令驱动模式（COMMAND-DRIVEN FORMA T）的软件，各种命令控制着程序的运行，这部分内容将介绍PFC3D软件的内嵌命令。
本说明文件译自PFC3D软件2.0版使用手册中的COMMAND REFERENCE部分，并补充了一些手册中没有的命令（如设置粘性阻尼、生成圆柱、螺旋壁面等，这些命令在更高版本的手册中有说明）。命令说明的顺序没有采用原手册中按字母排序的方式，而是根据创建PFC3D模型解决实际物理问题的一般过程，对相关命令加以说明。PFC3D手册中COMMON COMMAND REFERENCE只对每个命令的格式和基本功能做了简单介绍，本说明文件对每个命令做了更详细的解释，为保持文件的可读性，对命令的详细解释都以附录形式给出。
本文件介绍了PFC3D的基本功能，对初学者有较大帮助，但要进行高级应用，还需清楚了解DEM 和PFC3D相关功能的基本原理以及软件的结构等。由于只关注使用PFC3D解决颗粒流的问题，涉及颗粒流的命令介绍的比较详细，而用于岩土工程等其他领域的命令，由于关注很少且专业知识缺乏，只是不求甚解。
0.关于命令格式的说明：
PFC3D中每个命令基本包含3部分：命令名、必需关键词和可选关键词。本说明文件中，命令名和必需关键词写在第一行，尖括号
BALL rad r
…
hert z …
id id
x x
y y
z z
说明：命令名为BALL的命令，具有必需关键词rad（参数r）和hert z、id、x、y、z等可选关键词。其中hert z不带参数，最短可简写为hert；id、x、y、z的参数分别为id、x、y、z。
另外，PFC3D默认对内嵌命令以及FISH函数中的命令名、关键词、参数等的字母大小写不敏感，也可设置为大小写敏感（使用SET case_sensitivity on命令），建议使用对字母大小写不敏感模式，可减少错误的产生。
1.模型属性命令（MODEL-PROPERTY COMMANDS）
模型属性命令支持数值模型的创建与修改，主要包括表1所示的命令，这些命令可分为模型创建（或删除）和模型修改两大类
表1 模型属性命令
BALL生成一个新颗粒；
CLUMP生成一个新块体，或修改已有块体的属性；
DELETE 删除球、壁面、块体或历史（HISTORIES）；
GENERATE在特定空间内生成一组颗粒，其大小按指定方式分布；
JSET以给某个接触分配一个“接点”ID号的方式生成一组“接点”；
WALL生成一个新壁面或修改已有壁面的属性（包括修改物性和外加速度）；
FIX为颗粒设置固定速度标记
FREE清除颗粒的固定速度标记
MODEL在指定“接触”上使用用户自定义接触模型；
PROPERTY修改已有颗粒（ball）、接点（joint）、粘结（bond）和接触（contact）的属性。
球的属性包括物性、外加力和速度等；使用区域元素（range element）JSET，
用户可以修改特定接点附件的颗粒属性；对于“粘结”，接触粘结和平行粘结都
可以被创建并修改其属性；对于“接触”，PROPERTY用于修改用户自定接触
模型的修改。同义命令：CHANGE、INITIALIZE。
1.1模型创建命令：
WALL keyword…
WALL命令有两个功能，生成一个新的壁面，或按指定的ID号修改已有壁面的属性参
数。W ALL不能使用RANGE逻辑，即不能给一个壁面的不同部分赋不同的属性参数。
壁面只与球有相互作用，壁面之间没有相互作用，因此壁面可以相互重叠。壁面有两侧，有效侧（active side）与非有效侧（inactive side），只有与有效侧接触的球，才与壁面有相互作用。关于有效侧的定义，见附录1。
每个壁面都可以设置平移速度与转动速度。使用Theory and Background中的1.28公式，可更新构成壁面的每个顶点的位置，从而得到壁面的运动情况。应当注意的是，转动速度的设定还与壁面转动中心有关，默认情况下，转动中心在坐标原点(0.0, 0.0, 0.0）。
两类壁面可以定义：（1）无限大壁面：由关键词origin和normal定义的一个无限大平面；
（2）有限壁面：圆柱形或由一组凸面多边形组成，使用关键词face定义。
A.无限大壁面（infinite wall）:无限壁面由关键词normal和origin定义，前者定义壁面的
单位法向向量，所指向的一侧是壁面的有效侧；后者定义壁面上的任意一点。
no rmal nx, ny, nz
无限壁面单位法向向量的分量；
or igin x0, y0, z0
无限壁面上任意一点的坐标；
B.圆柱壁面（cylinder）:使用关键词type cylinder可以定义圆柱壁面，也可定义圆锥、圆
台壁面等回旋壁面。
type cylinder keyword…
end1x1, y1, z1
回旋面的第一个端点；
end2x2, y2, z2
回旋面的第二个端点；
rad ius rl, ru
rl: 端点end1处的回旋半径；
ru: 端点end2处的回旋半径；
type cylinder的几点说明：
1)end1, end2至多只能缺省一个，缺省时对应的参数都为0；
2)rl和end1对应，ru和end2对应；
3)rad ius值决定了回旋壁面的类型：
i.rl = ru，对应圆柱壁面；
ii.rl = 0.0，对应圆锥壁面；
iii.rl ≠ru，对应圆台壁面；
例如：
Wall type cylinder end1 0 0 0, end2 0 0 1, radius 0.5,0.5, id=1, kn=1e6, ks=1e6, fric=0.2 ;生产半径
为0.5的圆柱面；
Wall type cylinder end1 0 0 0, end2 0 0 1, radius 0.0,0.5, id=1, kn=1e6, ks=1e6, fric=0.2 ;生产地面半径为0.5的圆锥面；
Wall type cylinder end1 0 0 0, end2 0 0 1, radius 0.2,0.5, id=1, kn=1e6, ks=1e6, fric=0.2 ;生产上底面半径0.2，下底面半径为0.5的圆台面；
C.螺旋壁面（spiral）:使用关键词type spiral可以生产螺旋壁面。
type spiral keyword…
end1x1, y1, z1
螺旋面的第一个端点；
end2x2, y2, z2
螺旋面的第二个端点；
rad in rin
rin: 螺旋面的内径；
rad out rout
rout: 螺旋面的外径；
pi tch pt
pt: 螺距。
说明：螺纹的个数由end1,end2之间的距离除以pitch得到的整数决定。如ed1-end2=10,pitch=3，则螺纹数等于3个。
例如：
Wall type spiral end1 0 0 0, end2 10 0 0, radius 0.5,1.0, pitch=1, id=1, kn=1e6, ks=1e6, fric=0.2 ;生产10个螺纹的螺旋面；
D.凸面多边形壁面（convex polygons）：使用关键词face可以构造由若干有限平面（face）
组成的有限壁面（wall），每个平面（face）必须是由一组按顺序连接的顶点（vertices）组成的多边形（polygon）；有限壁面的有效侧按右手法则确定，详见附录1。
fa ce x1, y1, z1 x2, y2, z2 …xn, yn, zn
x1, y1, z1 x2, y2, z2 …xn, yn, zn为平面多边形的顶点坐标，它们的位
置顺序代表着顶点的连接顺序，决定了有效侧的位置。
使用具有相同ID号的W ALL命令，可以在已有壁面上增加若干多边形平
面，如下列命令定义了一系列有限壁面：
wall id=1 face (1,1,1) (1,0,1) (6,0,1) (6,1,1)
wall id=2 face (6,0,1) (6,0,6) (6,1,6) (6,1,1)
wall id=3 face (1,0,6) (1,1,6) (6,1,6) (6,0,6)
wall id=4 face (1,1,1) (1,1,6) (1,0,6) (1,0,1)
wall id=5 face (2,1,2) (5,1,2) (5,0,2) (2,0,2)
wall id=5 face (5,0,2) (5,1,2) (5,1,5) (5,0,5)
wall id=5 face (2,0,5) (5,0,5) (5,1,5) (2,1,5)
wall id=5 face (2,1,2) (2,0,2) (2,0,5) (2,1,5)
wall id=9 normal 0, 1,0 origin 3.5,0.0,3.5
wall id=10 normal 0,-1,0 origin 3.5,1.0,3.5
通过使用多个具有相同ID号（id=5）的W ALL命令，定义了一个由4个
平面构成的凸面多边形壁面，如下图所示。
图1 face定义有限平面
警告：PFC3D软件现阶段只能生成有效的凸壁面，即有效侧夹角大于180°
的两个连接面（如图1中的id=5壁面）；对于凹形几何结构，不能定义成
一个壁面，必须通过连接不同的壁面得到。
E.WALL命令的其他关键词：以下关键词用于设置壁面的属性，如刚度系数、摩擦系数、
平移速度、旋转速度等。关键词的可以在命令中的任意位置出现。
id id
指定壁面的ID号，必须是正整数。如果不指定，则将选择比当前最大壁
面id号大1的整数。如果指定的id号已经存在，则对应壁面的属性将被
修改，如增加1个平面，或修改刚度系数、摩擦系数等。
kn kn
设定或修改壁面法向刚度系数（线性接触模型）；
ks ks
设定或修改壁面切向刚度系数（线性接触模型）；
f riction f
设定或修改壁面摩擦系数；
x x
设定转动中心（x坐标）；
y y
设定转动中心（y坐标）；
z z
设定转动中心（z坐标）；
xs pin xs
设定绕转动中心的转动速度（x分量）[单位：弧度/秒]；
ys pin ys
设定绕转动中心的转动速度（y分量）[单位：弧度/秒]；
zs pin zs
设定绕转动中心的转动速度（z分量）[单位：弧度/秒]；
xv elocity xv
设定平移速度（x分量）；
yv elocity yv
设定平移速度（y分量）；
zv elocity zv
设定平移速度（z分量）；
BALL rad r
生成半径为r的单个颗粒，可选择的关键词有：
her tz 启用Hertz接触模型，若不是用该可选关键词，则模型默认使用线性接触
模型
id id
设置颗粒的ID号。每个颗粒的ID号应为独一的正整数，如果模型内有相
同的ID号，则软件会报错。如果用户不设置颗粒ID号，软件将自动指定
比当前模型内最大ID号大1的号码。
x x
球心的x坐标
y y
球心的y坐标
z z
球心的z坐标
GE NERA TE
以下关键词可用于修改该命令的功能：
n o_shadow 禁止在非阴影区内生成颗粒（见附录二）；默认情况下，颗粒会在
壁面的有效侧与非有效侧生成。
t ries tmax
PFC3D默认尝试20,000次，以将指定数量的待生成颗粒置于指定
空间。该命令将尝试的次数设为tmax次，需注意的是，这个值
只对当前Generate命令有效，并不是将模型内所有Generate命令
的尝试次数都设为tmax。
f ilter fname
使用用户自定义的颗粒生成过滤器（user-defined generation filter）。
在生成每个球的每一次尝试中，名为fname的FISH函数被调用，
详见说明9和附录4。
g auss 颗粒半径服从高斯概率分布，而不是默认的均匀概率分布。此时，
平均半径为(rl + ru) / 2，标准偏差为(ru - rl) / 2；其中rl , ru为关
键词radius定义的参数。
h ertz 新生颗粒使用Hertz接触模型。若无该关键词，则使用默认的线
性接触模型。
l ocal 该关键词只在并行计算过程起作用，用于强制性地只在本地处理
器上生成颗粒，而不在处理器之间共享信息。
m in rmin
该关键词只在使用了g auss关键词的情况下起作用，用于将高斯
概率分布中的最小球半径设为rmin。默认情况下，高斯概率分布
中的最小球半径为rl / 10。
说明：
1.BALL和GENERATE是用于生成新球的两个命令，他们之间有很大区别：
a)BALL是在用户指定的一个特定位置，生成一个新球；新球的生成不受已有球的影响，允许
与其他球有任意大的重叠；由于球之间允许重叠，当循环计算开始时，球之间会突然产生大
小相应于重叠量的作用力；
b)GENERATE是在用户指定的一个空间区域内，生成指定数量的新球；新球的生成受已有球
的影响，因为球与球之间不允许有重叠；因此用GENERATE命令能否在指定空间生成指定
数量的球，还取决于空间是否足够大，或生成球过程中的尝试次数（tries）是否足够多等；
c)BALL命令一般用于生成规则排列球组（Regular particle assembly），GENERATE用于生成
非规则排列球组(Irregular particle assemble)；
2.Generate命令必须指定球的生成空间范围、半径大小分布形式和ID号范围（确定球的数量）。球
的位置与半径随机选择，因此最终生成的颗粒组的状态（位置和大小）受随机数发生器（Random number generator）的影响。SET random1命令用于设置随机数发生器的状态，详见脚注1；
3.关键词x xl xu y yl yu z zl zu用于定义指定空间，新生球的质心x，y，z坐标值分别处于区间[xl, xu]，
[yl, yu]和[zl,zu]之内。若使用可选关键词annulus，则颗粒的生成空间为一球环形空间，其球心为(xc, yc, zc)，内外球径分别为r1, r2；此时定义方形空间的x, y, z关键词可以省略，否则，指定的空间为annulus定义的球环形空间与x, y, z定义的方形空间的交集；X,y,z与annulus等关键词只能定义简单的方形与球环形空间，而实际问题大多数涉及较复杂的空间。此时最有效的方法是使用用户自定义FISH函数进一步限制球的生成空间，见关键词filter的说明；
4.球径大小由关键词rad ius定义，默认情况下，球径大小在区间[rl, ru]之内，且服从均匀概率分布2
（uniform distribution），也可使用关键词gauss指定球径大小服从高斯概率分布；
5.关键词id il iu指定了需要生成多少数量的球。生成球的总数量为iu-il+1，其中iu, il为球ID号的最大
值与最小值；
6.Generate生成球时，新球与已有球之间不允许相互重叠，因此，当没有足够的空间（或尝试的次
数不足，见关键词tries）生成所有指定数量的球时，将生成少于所需数量的球。软件默认这种情况为发生错误，不过也可以使用SET gen_error命令将这种情况当作警告处理（软件提示警告信息，但是指令处理过程继续进行）；颗粒生成以后，紧随其后应使用PROPERTY命令设置球的属性参数，包括法向刚度、切向刚度、局部阻尼、密度、摩擦系数，Hertz模型下的弹性模量、泊松比等。
7.t ries tmax的说明：Generate命令生成的球与球之间不允许重叠，用Generate命令生成新球的过程是
不断尝试的过程；每次尝试先按指定的分布形式确定球径大小，并随机（伪随机）确定一个球心
1SET random
该命令用于设置随机数发生器的随机种子iseed。
我们知道，计算机只能生成相对随机数（伪随机数），伪随机数的计算取决于随机算法和随机种子的选取，当算法和种子确定后，产生的随机数就确定了；种子和算法相同时，产生的随机数也相同。
PFC3D软件中随机算法是不变的，因此随机数的生成完全取决于用户设定的随机种子的大小，即iseed的值。
iseed的默认值等于10000，用户可以自定义随机种子，其大小应和默认值在同一量级；
三点必须明确：
1.如果用户没有使用SET random
上的定时/计数器在内存中的记数值。这种情况下，同一个模型每次运行时的随机数都不同，Generate生成的球组初始状
态（球的大小和位置）每次也不同；
2.如果用户使用了SET random
相同的随机种子意味着对于同一个模型而言，无论运行多少次，由Generate命令生成的初始球组的状态是一样的；
3.随机种子的设置只与有无SET random
2均匀概率分布的数学概念：
设连续型随机变量X的分布函数为
F(x)=(x-a)/(b-a),a≤x≤b
则称随机变量X服从[a,b]上的均匀概率分布,记为X~U[a,b].若[x1,x2]是[a,b]的任一子区间,则P{x1≤x≤x2}=(x2-x1)/(b-a)这表明X 落在[a,b]的子区间内的概率只与子区间长度有关,而与子区间位置无关,因此X落在[a,b]的长度相等的子区间内的可能性是相等的,所谓的均匀指的就是这种等可能性.
在实际问题中,当我们无法区分在区间[a,b]内取值的随机变量X取不同值的可能性有何不同时,我们就可以假定X服从[a,b]上的均匀概率分布.
位置，再检测该位置周围是否有足够空间生成该球；若空间足够，新球生成，否则进行下一次尝试。软件默认尝试20,000次，当所需新生球数量较多时，必须使用t ries tmax命令，设置更大的尝试次数，否则即使有足够的空间，也不能生成所需数量的球。
8.f ilter fname：该关键词的作用是引用用户自定义颗粒生成过滤器（generation filter），fname是用
户自定义FISH函数名，生成每个试产球(trial ball)时都将被调用。在函数fname里，试产球的半径通过fc_arg(0)传递，位置坐标的x, y, z分量分别通过fc_arg(1), fc_arg(2), fc_arg(3)传递。要使试产球被接受（即其符合过滤条件），函数中fname的值设为0，否则fname的值设为1。关于f ilter fname 的更详细说，见附录4。
DEL ETE keyword…
删除球(balls)、块(clumps)、历史(histories)或壁面(walls)等，命令的形式取决于要删
除的对象。相关关键词及其参数如下：
b alls
删除球。如果指定id号，仅删除对应的1个球；如果指定一个范围
(range)，则处于该范围内的球（即质心处于该范围之内的球）都将被
删除；如果既不指定id号，也不指定范围，则模型中的所有球都将被
删除。
利用FISH函数，我们能更灵活地按照所希望的方式删除一些对象，
比如删除一些超出指定范围的球。User’s Guide中的例3.21介绍了每
经100个循环，删除位置低于某一高度的球。关于FISH语言，将在
另一部分给予介绍。
Example 3.21 FISH function to delete escaping particles
;fname: zapballs.DAT
def remove_balls
while_stepping
y_del_count = y_del_count + 1
if y_del_count > 100
y_del_count = 0
bp = ball_head
loop while bp # null
next = b_next(bp)
if b_y(bp) < y_del
ii = b_delete(bp)
end_if
bp = next
end_loop
end_if
end
c lump id
删除ID为id的块，不可指定范围(range)参数。删除块只是解散组成
块体的球，并不删除这些球。
h istories 删除所有历史记录(history traces)。另外，也可以用HISTORY reset命
令擦除所有历史记录的内容。
w alls id
删除ID号为id的壁面，不可指定范围（range）参数。
CL UMP keywords…
创建ID号为id的新块，若指定的id已经存在，则其功能为修改ID为id的块体的
属性。
……
……
……
J SET ……
……
1.2模型修改命令：
FI X keyword…
固定某一范围(range)内球的指定速度自由度，若不指定范围(range)，该命令将应用
于模型中的所有球。应当注意的是，固定的是“速度”而不是位移。当速度的某一
分量被固定时，其速度将保持当前值不变，即每个循环中运动方程不会更新速度分
量。速度值可使用PROPERTY命令设置。
以下关键词可使用：
x固定x方向线速度；
y固定y方向线速度；
z固定z方向线速度；
xs pin 固定x方向角速度；
ys pin 固定y方向角速度；
zs pin 固定z方向角速度；
例如，下列命令行将把ID为5的球的x方向线速度固定为1.5m/s。
fix x range id = 5;
property xvel = 1.5 range id=5;
FR EE keyword…
FR EE是与FI X相反的命令，其功能是移除对某一范围（range）内的球在速度自由
度上的固化, 若不指定范围，该命令将应用于模型中的所有球。当某速度分量自由
化（be free）后，其大小变化将由每个循环过程的运动方程决定。默认情况下，所
有球的所有分量都是自由变化的。
以下关键可用于该命令：
x释放x方向线速度(frees x-velocity)；
y释放y方向线速度；
z释放z方向线速度；
xs pin 释放x方向角速度；
ys pin 释放y方向角速度；
zs pin 释放z方向角速度；
PRO PERTY keyword v
设置某范围(optional range)内已有球(balls)、接点(joints)、粘结(bonds)以及接触
(contacts)的属性，包括球的物性、外加力和速度；修改连接到某个接点的球的属性；
修改接触粘结和平行粘结的属性。对于接触，PROPERTY只能修改用户自定义接触
模型的接触属性。若没有指定范围，则模型中所有有效对象的属性都将被修改。
命令CHANGE和INITIALIZE是PROPERTY的同义命令，具有相同的功能。
以下关键词可用于修改PROPERTY命令的功能：
a dd v
修改处于指定范围内的所有对象的参数值，使其在当前值的基础上加
上设定值v得到新的值。例如，给所有球的半径加0.1的命令是：
PROPERTY radius add 0.1。
g radient gx, gy, gz
该关键词的作用是有梯度地设定参数值，
即将对象的的参数值设为：。这里关键
词gradient应紧随v值之后设定，(x, y, z)为对象的位置坐标。如果还
使用了关键词multiply，则由gradient设定梯度(gx, gy, gz)也将用于乘
数值的设定。
mu ltiply v
将指定范围内的对象的参数值乘以v得到新的参数值，注意是乘以v
而不是将参数值设定为v。例如命令:PROPERTY radius multiply 1.5
的作用是将所有球的半径扩大1.5倍，若此时某球的半径等于2.0m，
则应用该命令后其半径为3.0m。
PROPERTY命令的关键词可分为以下三类：修改球属性、修改接触粘结属性(contact-bond properties)和修改平行粘结属性(parallel-bond properties)。在必要之处，属性参数的单位在方括号内给予了说明。
球属性：
ra dius 球的半径
de nsity 密度[质量/体积]
co lor 设置颜色标号(index)。球的颜色标号必须是一个非零整数，标号等于0对应于plot命令给球设定的一系列颜色中的第一个颜色。
例如命令：PLOT add ball red blue orange black设置了4种颜色
的球，其中颜色编号0对应red(红色)，编号1对应blue，依此类
推。此时命令PROPERTY color 2的作用就是把所有球的颜色设
为orange(橙色)。
kn法向刚度系数(线性接触模型) [力/位移];
ks切向刚度系数(线性接触模型) [力/位移];
da mping 局部阻尼系数。PFC3D软件默认对于每个新生成的球使用局部阻尼，默认的局部阻尼系数等于0.7，用户可以通过关键词damping
修改局部阻尼系数。
f riction 球表面摩擦系数（注意，不是摩擦角）；
po iss 泊松比（Hertz接触模型）；
sh ear 剪切模量（Hertz接触模型）；
xf orce 作用于球质心的x方向的外加力(applied force)；
yf orce 作用于球质心的y方向的外加力(applied force)；
zf orce 作用于球质心的z方向的外加力(applied force);
xd isplacement x方向累积位移[距离, distance]；
yd isplacement y方向累积位移[距离, distance]；
zd isplacement z方向的累积位移[距离, distance]；
xv elocity x方向速度[距离/时间，distance/time]；
yv elocity y方向速度[距离/时间，distance/time]；
zv elocity z方向速度[距离/时间，distance/time]；
xs pin x方向角速度[弧度/时间]；
ys pin y方向角速度[弧度/时间]；
zs pin z方向角速度[弧度/时间]；
xm oment x方向外加力矩[力*距离]；
ym oment y方向外加力矩[力*距离]；
zm oment z方向外加力矩[力*距离]；
接触粘结属性(Contact-bond properties)：
创建球与球之间的接触粘结是通过把任意一个接触粘结属性参数设为非零值实现的。
此时，程序会在指定范围内的所有真实接触（两球之间有实际重叠量）和虚拟接触
（两球间距小于其平均半径的10-6）上设置接触粘结。
如果法向或切向接触粘结力被设为0，那么该接触粘结将在下一个循环中断裂。手
册Theory and background中的2.3.1节对接触粘结逻辑(contact-bond logic)有详细
叙述。
n_b ond 法向接触粘结力(contact bond normal strength)[力(force)];
s_b ond 切向接触粘结力(contact bond shear strength) [力(force)]；
平行粘结属性(Parallel-bond properties)：
类似与接触粘结，创建球与球之间的平行粘结是通过把任意一个平行粘结属性参数
设为非零值实现的。此时，程序会在指定范围内的所有真实接触（两球之间有实际
重叠量）和虚拟接触（两球间距小于其平均半径的10-6）上设置接触粘结。
如果法向或切向平行粘结力被设为0，那么该平行粘结将在下一个循环中断裂。手
册Theory and background中的2.3.2节对平行粘结逻辑(parallel-bond logic)有详细
叙述。
pb_kn 平行粘结法向刚度系数[应力/位移(stress/displacement)];
pb_ks 平行粘结法向刚度系数[应力/位移(stress/displacement)];
pb_n strength 法向平行粘结力[应力(stress)];
pb_s strength 切向平行粘结力[应力(stress)];
pb_r adius 半径乘数(radius multiplier)，由此平行粘结的半径等于该乘数
乘以两个粘结球中的最小半径。
注意：
1.如果使用了用户自定义的接触模型，则其属性参数也是通过PROPERTY命令
对模型中定义的属性名赋值来设置的。详见手册FISH volume中的第4节。
2.关键词radius的简写不可短于“rad”，否则将被识别为“range”
2.程序控制命令（PROGRAM-CONTROL COMMANDS）
程序控制命令用于支持程序的批处理模式(batch mode)运行，并允许用户修改程序状态。这类命令列于表2。
表2 程序控制命令
CYCLE执行指定数量的循环计算（同义词：STEP）；
SLOVE持续循环计算直到达到指定的停止条件；
CALL将数据文件读入PFC3D软件并执行其中的命令，这就是所谓的批处理模式；
RETURN从批处理模式(batch mode)返回命令交互模式(interactive-command mode)；
如果嵌套了多层调用，则返回上一层的调用文件。
PAUSE暂停读入数据文件，与CONTINUE命令对应；
CONTINUE继续读入数据文件，与PAUSE命令对应；
NEW清除程序状态，开始一个新的模型计算；
PARALLEL控制并行处理程序的运行；
QUIT停止程序运行（同义词：STOP）；
SAVE将程序当前状态存入文件，与RESTORE命令对应；
RESTORE还原存储文件(SA VE d file)中的程序状态，与SA VE命令对应；
TITLE设置模型标题，该标题会在绘图中显示并记录在存储文件中。
CY CLE n
执行n个时步的循环计算。如果运行期间按下
前循环步数后返回命令交互模式；如果按下
环步数后调用下一个批处理文件（如果有的话）。
例如，命令CYCL 10000意为执行10000步循环计算，如果用户在第5000步的时候
按下了
步时按下
件，则程序将停止运行，并返回命令交互模式。同义词：STEP
SO LVE
启动并持续循环计算，直到达到指定的停止条件。默认情况下，当最大或平均不平
衡力比达到1*10-2时，则认为得到稳定状态解。以下关键词用于定义该命令的停止
条件（注意：达到任意一个停止条件时，循环计算都将停止）。
a verage v
平均不平衡力与平均接触力的比值，默认v= 0.01。平均不平衡
力为：所有不平衡力分量绝对值的总和在所有球上的平均值；平
均接触力：所有法向力接触力绝对值的总和在所有法向力接触力
不为零的接触点上的平均。
m aximum v
所有球中的最大不平衡力与最大接触力的比值，默认v= 0.01。
最大不平衡力：不平衡力矢量任何一个分量的最大值。对于任意
一个球而言，其不平衡力分量都有一个最大值F unmax，所有球中
最大的F unmax (记为max(F unmax))，就是maximum命令中所谓的所
有球中的最大不平衡力。
最大接触力：所有具有非零法向力的“接触(contact)”中（不考
虑平行粘结），法向接触力绝对值的最大值。
c ycles n
循环步数限定条件，默认n = 100,000步；
s teps s
关键词cycles的同义词；
c lock t
计算机运行时间限定条件，默认t = 1440分钟；
t ime t
累计问题时间（即所有时步的和）限制条件，默认t = 360,000秒。说明：问题时间(Problem-time)与计算机运行时间(Computer runtime)
PFC3D模型都是用于模拟一个实际物理问题。对于一个PFC3D模型而言，都具有两个时间概念，即问题时间(problem-time)和计算机运行时间(computer runtime)。前者是实际物理时间，也就是所有时间步长的总和；后者是计算机模拟该问题所花的计算时间，这与时间步长的大小、计算的硬件性能等相关，时步越大、计算机性能越好，所花运行时间越短。
例如用PFC3D模拟一个5m高的自由落体运动，从运动开始到结束，问题时间( problem-time )约为1s。而对于计算机而言，其模拟自由落体运动必须分为若干个时间步长来计算，每个时步中必须进行查找接触、更新数据、绘图、保存数据等操作，因此计算机的运行时间(computer runtime)必然比问题时间更长。
我们常说DEM方法耗时太长，指的就是计算机的运行时间太长。对于一个实际物理问题，其问题时间由物理原则决定，模拟过程不能改变；而对于计算机运行时间则可以想方设法缩短，比如选择大小合适的时步、使用高性能计算机、并行计算等。
CA LL
CALL命令用于批处理模式(batch mode)，作用是调用名为fname的数据文件。如果
没有指定文件名，则默认调用“PFC3D.DA T”；如果没有指定fname的扩展名，则
扩展名默认为“.DAT”。
数据文件中可以有任意多的注释行（分号“;”用于注释），PFC3D不会运行这些注
释信息。一个数据文件内可以按顺序嵌套调用其他数据文件，对嵌套的层数没有限
制，但是不允许文件之间的递归调用。例如，“ABC”文件中调用了“DEF”文件，
而“DEF”中同时又调用了“ABC”文件，这种情况是不允许的。
如果只有一层调用，用RETURN命令可从批处理模式返回命令交互模式；如果是
多层嵌套调用（即在一个数据文件中调用了另一个数据文件），则（被调用文件中）
RETURN的作用为返回上一层数据文件中（调用文件中）CALL命令的下一行。如
果按下
行模式并返回命令交互模式；如果按下
用户可以在数据文件中插入PAUSE命令，该命令会暂停程序的运行，允许用户检
查中间结果是否正确。使用CONTINUE命令可以继续运行被暂停程序。RETURN如果只有一层调用，用RETURN命令可从批处理模式返回命令交互模式；如果是多层嵌套调用（即在一个数据文件中调用了另一个数据文件），则（被调用文件中）
RETURN的作用为返回上一层数据文件中（调用文件中）CALL命令的下一行。无
论用户是否在数据文件的最后一行写上RETURN命令，每个数据文件的最后一行，
都默认有RETURN命令。
RETURN命令也用于从一个FISH函数的COMMAND section跳出。
PAUSE
用于暂停运行数据文件，该命令能以下列3种方式中的一种调用：
1)如果没有指定任何关键词，则PFC3D将在遇到PAUSE命令的地方停止运行数
据文件，并进入命令交互模式，此时用户可以通过键盘输入命令控制程序（如
敲入PLOT ball命令绘制球的图像）。当敲入CONTINUE命令时，PFC3D将
恢复运行数据文件；
2)如果指定了关键词
据文件，并等待用户按下一个按键。当用户按下任意一个按键（
时，PFC3D将恢复运行数据文件。如果按下
运行（包括已经暂停的任何数据文件的运行）并进入命令交互模式。
3)如果指定了关键词
如果按下
何数据文件的运行）并进入命令交互模式(interactive-command mode)；如果按
下
CONTINUE恢复运行被PAUSE命令暂停的数据文件。此时，程序将从PAUSE命令的下一行继续运行。
NEW清除大部分程序状态信息，从而允许用户不用退出PFC3D软件就能开始一个新问题的模拟。对于每个启动命令，都将调用(或参考？consult)“PFC3D.INI”文件。
命令NEW可以清除程序的大部分状态信息，如球、壁面、接触、粘结等对象都将
被删除，不会影响下个新问题的模拟。但是以下3个状态信息不受命令NEW的影
响：日志文件(log-file)、反馈模式(echo mode)和随机数发生器的种子(即随机种子，
random-number generator seed)[参见命令SET {log, echo, random}]。日志文件仍然打
开（如果已经打开的话），日志文件名和反馈模式的开关状态不会被命令NEW改变，
而且随机种子不会因为使用命令NEW而重置。除此之外，所有其他的程序状态信
息（包括所有FISH函数和变量、历史记录[histories]、表格以及绘图等）都将丢失！
不过这些信息都可以通过SA VE命令保存到文件内，以后使用RESTORE命令恢复。
另外，也可以编写FISH函数将数据保存到一个文件内，并通过另一个FISH函数读
出这些数据，详见FISH volume中的2.5.1.6节：Input-Output Functions
PAR ALLEL keyword…
控制并行处理程序的运行以及拓扑连接的初始说明(controls parallel-processing
program operation and the initial specification of the connection topology)。并行处理功
能是作为PFC3D软件的一个可选功能供用户选用的，Theory and background中
5.2.3节有关于并行处理的详细介绍。
该命令可应用以下关键词：
e nd 当主处理器收到该命令时，所有进程都将归复独立运行模式。
m aster mname
从属进程(slaves)使用该命令将网络中名为mname的进程指定为
他们的主进程(master process)。
n umprocess n
主进程使用该命令指定参与并行运行的总进程数。
p rocess pn
每个进程都需使用该命令给自己分配一个编号。pn必须在{0, n-1}
之间，其中n为总进程数，编号0特指主进程。
s tart 对主进程而言，该命令将所有从键盘或文件输入PFC3D的本地输
入(local input)发送到所有从属进程，包括主进程本身。对从属进
程而言，该命令将禁止键盘提示(keyboard prompt)，并指示PFC3D
接收从主进程发送的所有输入信息。FISH语言的并行化以及并行
环境下FISH衍生命令的解释，在Theory and Background中的5.2.6
节有讨论。一些其他命令也使得进程间的通信处于一个更低的水
平（详见Theory and background中5.3节）。
Start命令假设在其之前已经运行了process，numprocess和
master等命令，即start命令必须在这些命令运行之后才有效。
以下是对并行化运行的注解，更多注解和例子请参考Theory and Background中第5
节。
1)如果有n个处理器，编号为0, 1, …, n-1，每个处理器对应于一个空间区域，那
么0号则对应“最左侧”区域（least x range横坐标x最小的区域），依此类推，
相应地n-1号处理器对应于“最右侧”区域（most positive x range横坐标x最
大的区域）。
0号处理器
2)
QUIT停止程序运行（同义词：STOP）；
SAVE将程序当前状态存入文件，与RESTORE命令对应；
RESTORE还原存储文件(SA VE d file)中的程序状态，与SA VE命令对应；
TITLE设置模型标题，该标题会在绘图中显示并记录在存储文件中。
3.模型监控命令（MODEL MONITORING COMMANDS）
模型监控命令用于监控模型的响应，主要包括以下命令
PLOT命令
PLOT keyword
PLOT命令用于在屏幕上绘图或将图导出到硬拷贝绘图设备（如打印机、PDF）或文件（如导出位图、JPG等文件）里。绘图逻辑（PLOTTING LOGIC）的建立是基于“视图（VIEW）”的概念。一个视图包含视图设置参数（如视图的背景、尺寸等）和实际需要绘制的项目（如模型平面model surface，向量等），在没有建立任何模型的时候，绘图逻辑会将视图列表初始化为标识号（viewid）为0，名字为“BASE”的唯一视图。打开PFC3D软件时，在VIEWS菜单栏下可以看到名为“1 0\BASE”选项条，这就是绘图逻辑初始化的视图，点击“show”，我们就能看到这个默认视图的全貌，如下图1、2所示。
1
用户可以创建并储存多个视图，并可以在视图之间切换以定义“活动视图（active view）”。Viewid可以是一个代表视图ID号的整数，也可以是一个表示视图名字的字符串（如默认视图的标识号0\BASE 中，0为该视图的ID号，BASE是该视图的名字）。使用关键词create可以创造一个视图，使用关键词current可以激活一个视图，关键词print可以查看视图列表。
每个视图存储了一系列“绘图选项（plot items）”，即视图能显示的一些特定图片选项（例如模型图和速度矢量图等）。使用add关键词可以将绘图选项添加到视图里，subtract用于删除绘图选项，modify 用于修改绘图选项，move可以重新组织绘图选项。当使用了show关键词时，所有添加到视图里的选项都会显示在屏幕上。使用print item可以得到与特定视图相关的所有绘图选项的列表。
绘图操作命令可归为以下4类：
●视图操作——定义视图属性和输出条件的关键词；
●视图设置操作——设置视图的背景和前景颜色、视图位置、视图说明和视图名称的关键词；
●绘图选项操作——用于在视图内创建（即添加、删除、修改等操作）视图选项的关键词；
●交互式操作——在图形屏幕模式下，使用一些特定键击，用户可与PFC3D进行交互式操作。
表1.7列出了前三类关键词，表1.8列出了第四类提到的相关键击。
*每隔n个计算循环重绘视图，n由SET pinterval命令设定（默认n=20），此时按下空格键将停止计算。 PLOT命令详述
1. 视图操作关键词
PLOT keyword …
Close
关闭当前视图或关闭指定ID（viewid）的视图；
Copy viewid1 viewid2
将视图viewid1复制到视图viewid2中，如果视图viewid2原来不存在，则会被创建。