PFC3D基础说明

PFC3D命令说明

（COMMON COMMAND REFERENCE）

PFC3D是基于命令驱动模式（COMMAND-DRIVEN FORMAT）的软件，各种命令控制着程序的运行，这部分内容将介绍PFC3D软件的内嵌命令。

本说明文件译自PFC3D软件2.0版使用手册中的COMMAND REFERENCE部分，并补充了一些手册中没有的命令（如设置粘性阻尼、生成圆柱、螺旋壁面等，这些命令在更高版本的手册中有说明）。命令说明的顺序没有采用原手册中按字母排序的方式，而是根据创建PFC3D模型解决实际物理问题的一般过程，对相关命令加以说明。PFC3D手册中COMMON COMMAND REFERENCE只对每个命令的格式和基本功能做了简单介绍，本说明文件对每个命令做了更详细的解释，为保持文件的可读性，对命令的详细解释都以附录形式给出。

本文件介绍了PFC3D的基本功能，对初学者有较大帮助，但要进行高级应用，还需清楚了解DEM和PFC3D相关功能的基本原理以及软件的结构等。由于只关注使用PFC3D解决颗粒流的问题，涉及颗粒流的命令介绍的比较详细，而用于岩土工程等其他领域的命令，由于关注很少且专业知识缺乏，只是不求甚解。

0.关于命令格式的说明：

PFC3D中每个命令基本包含3部分：命令名、必需关键词和可选关键词。本说明文件中，命令名和必需关键词写在第一行，尖括号表示该命令具有可选关键词，罗列于命令名的下一行次级列；带参数的关键词，参数紧随关键词之后用加粗斜体表示。名字较长的“命令”和“关键词”，PFC3D允许不写出全部字母，只需简写前面的一些字母，最短可简写名（即PFC3D能识别的最短简写“命令”和“关键词”名）用加粗字体表示。例如命令：

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

GENERATE

JSET

WALL

FIX—FREE

MODEL

PROPERTY & CHANGE & INITIALIZE

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号修改已有壁面的属性参数。

WALL不能使用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 NERATE x xl xu y yl yu z zl zu rad ius rl ru id il iu

以下关键词可用于修改该命令的功能：

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定义

1SET random

该命令用于设置随机数发生器的随机种子iseed。

我们知道，计算机只能生成相对随机数（伪随机数），伪随机数的计算取决于随机算法和随机种子的选取，当算法和种子确定后，产生的随机数就确定了；种子和算法相同时，产生的随机数也相同。

PFC3D软件中随机算法是不变的，因此随机数的生成完全取决于用户设定的随机种子的大小，即iseed的值。

iseed的默认值等于10000，用户可以自定义随机种子，其大小应和默认值在同一量级；

三点必须明确：

1.如果用户没有使用SET random 命令，则随机种子由软件自动选取，一般取自计算的系统时钟，即来自计算机主板上的定

时/计数器在内存中的记数值。这种情况下，同一个模型每次运行时的随机数都不同，Generate生成的球组初始状态（球的大小和位置）每次也不同；

2.如果用户使用了SET random 命令自定义随机种子的大小，那么随机数的产生取决于用户选取的iseed值的大小，相同的

随机种子意味着对于同一个模型而言，无论运行多少次，由Generate命令生成的初始球组的状态是一样的；

3.随机种子的设置只与有无SET random 命令以及iseed的大小有关，NEW命令不会改变随机种子的设置。

的球环形空间与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命令生成新球的过程是不断

尝试的过程；每次尝试先按指定的分布形式确定球径大小，并随机（伪随机）确定一个球心位置，再检测该位置周围是否有足够空间生成该球；若空间足够，新球生成，否则进行下一次尝试。软件默认尝试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

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]上的均匀概率分布.

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

SOLVE

CALL – RETURN

CONTINUE – PAUSE

NEW

PARALLEL

QUIT & STOP

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个时步的循环计算。如果运行期间按下键，PFC3D软件将在执行完当前循环

步数后返回命令交互模式；如果按下键，PFC3D将在执行完当前循环步数后调

用下一个批处理文件（如果有的话）。

例如，命令CYCL 10000意为执行10000步循环计算，如果用户在第5000步的时候按下

了键，则PFC3D将在此时停止计算并返回命令交互模式；如果在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.DAT”；如果没有指定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将在遇到PAUSE命令的地方停止运行数据文

件，并等待用户按下一个按键。当用户按下任意一个按键（键除外）时，PFC3D

将恢复运行数据文件。如果按下键，PFC3D将异常中断所有运行（包括已经暂

停的任何数据文件的运行）并进入命令交互模式。

3)如果指定了关键词，PFC3D将暂停运行数据文件t秒，之后再恢复运行。如果

按下键，PFC3D将异常中断所有数据文件的运行（包括已暂停的任何数据文件

的运行）并进入命令交互模式(interactive-command mode)；如果按下键，则

PFC3D将继续运行数据文件。

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）

模型监控命令用于监控模型的响应，主要包括以下命令

HISTORY

MEASURE

PLOT

PRINT

TRACE

PLOT命令

PLOT keyword … >

PLOT命令用于在屏幕上绘图或将图导出到硬拷贝绘图设备（如打印机、PDF）或文件（如导出位图、JPG 等文件）里。绘图逻辑（PLOTTING LOGIC）的建立是基于“视图（VIEW）”的概念。一个视图包含视图设置参数（如视图的背景、尺寸等）和实际需要绘制的项目（如模型平面model surface，向量等），在没有建立任何模型的时候，绘图逻辑会将视图列表初始化为标识号（viewid）为0，名字为“BASE”的唯一视

图。打开PFC3D软件时，在VIEWS

菜单栏下可以看到名为“1

0\BASE”选项条，这就是绘图逻辑初始化的视图，点击“show”，我们就能看到这个默认视图的全貌，如下图1、2所示。

1 2

用户可以创建并储存多个视图，并可以在视图之间切换以定义“活动视图（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列出了第四类提到的相关键击。

表1.7 PLOT操作关键词汇总

视图操作视图设置操作视图选项操作

Close

Copy

Create

Current

Destroy

Export

Hardcopy

Print

Reset

Set keword…

Angle

Animate

Background

Caption

Center

Color

Add

Clear

Modify

Move

Print item

Subtract

Quit Eyedistance

Foreground

Mode

Moveincrement

Perspective

Plane

Rotation

Rotincrement

Size

Title

Window

表1.8 PLOT模式中的交互式键击键击功能

\

+

-

左方向键右方向键上方向键下方向键Ctr+C Ctr+G Ctr+L Ctr+R Ctr+Z Delete

End Enter Home Insert

M Shift+M PG Dn PG Up

X Shift+x

Y Shift+y

Z Shift+z

F5

F9

切换视图模式

增加增量（1.25倍）

减小增量（0.8倍）

左移

右移

上移

下移

打开摄像设置对话框

在彩色绘图和灰度绘图之间切

换

平面剪辑显示

重置视图设置至默认设置

矩形框选择放大

增大目距

移近观察

返回命令模式

远离观察

减小目距

放大视图

缩小视图

？

？

绕x轴旋转（前-上）

绕x轴旋转（前-下）

绕y轴旋转（顺时针）

绕y轴旋转（逆时针）

绕z轴旋转（前-右）

绕z轴旋转（前-左）

执行循环计算绘图*

重绘

*每隔n个计算循环重绘视图，n由SET pinterval命令设定（默认n=20），此时按下空格键将停止计算。

PLOT命令详述

1. 视图操作关键词

PLOT keyword …

Close

关闭当前视图或关闭指定ID（viewid）的视图；

Copy viewid1 viewid2

将视图viewid1复制到视图viewid2中，如果视图viewid2原来不存在，则会被创建。

settings，items和both是可选关键词，它们决定了是否复制视图设置、绘图选项或两者都

复制，默认为both。

Create viewed

创建一个名为viewid（注意：viewid可以是一个整数，也可以是一个字符串名字，为方

便起见，最好取一个合适的名字）的新视图。

Current viewid

激活视图viewid；

Destroy viewid

删除视图viewid

Export

该命令会将当前视图或指定的视图（viewid）用到的视图设置命令打印在屏幕上，如果指

定了文件名，这些命令将被写进该文件，以后可通过CALL命令调用，方便地使用这些

命令设置其他视图

Hardcopy

将当前视图或指定视图（viewid）发送至由SET plot命令设定的硬拷贝设备，如果该设备是一个能导出文件的设备（如位图、JPG），将导出一个名为filename.ext的文件，后缀.ext由SET plot 设定的设备类型决定；如果缺省，则默认导出名为PFC3D.EXT的文件，此时若导出多个文件，则之前的PFC3D.EXT文件将被覆盖。

SET plot keyword

SET plot keyword命令用于控制图形硬拷贝的输出类型，包括：windows打印机、windows剪贴板、windows 增强媒体文件、位图文件（BMP, JPG, PCX）和PS文件，默认输出类型为windows打印机。各类型输出及其设置可通过以下关键词来设定。

JPG

将图形文件以JPG类型输出，该类型输出格式可通过以下关键词来设定

Size iw ih

将PCX位图的分辨率设为iw*ih像素，iw, ih的默认值分别为1024和768像素。

Quality ql

设置JPG位图的品质，ql的取值范围为（2~255），2为最高品质，默认值为50.

BMP

将图形文件以BMP类型输出，该类型输出格式可通过以下关键词来设定

Size iw ih

将BMP位图的分辨率设为iw*ih像素，iw, ih的默认值分别为1024和768像素。

PCX

将图形文件以PCX类型输出，该类型输出格式可通过以下关键词来设定

Size iw ih

将PCX位图的分辨率设为iw*ih像素，iw, ih的默认值分别为1024和768像素。

Emf

将图形硬拷贝输出类型设为emf格式，可通过以下关键词修改相关设置：

Size iw ih

将emf图片的分辨率设为iw*ih像素，iw, ih的默认值分别为1024和768像素。

Clipboard

将图形硬拷贝输出到windows剪贴板，可通过以下关键词修改相关设置：

Size iw ih

将图片的分辨率设为iw*ih像素，iw, ih的默认值分别为1024和768像素。

Postscript

将图形硬拷贝输出为PS文件，可通过以下关键词修改相关设置：

……

Windows

将图形硬拷贝输出到windows打印机，可通过以下关键词修改相关设置：

……

PRINT >：在屏幕上打印视图viewid的所有设置信息；

：默认值，在屏幕上打印出所有视图及其标示名的列表；

：在屏幕上打印当前视图信息和硬拷贝设备设置信息；

>：在屏幕上打印当前视图包含的绘图选项信息，若指定了i，则打印该绘图选项

的打印信息。

Quit 退出绘图模式，进入命令模式。

Rename viewed1 viewid2

将视图viewid1的名字改为viewid2，默认视图（即名为BASE的视图）的名字不能修改，

viewid必须是唯一的。

Show

在屏幕上显示包含在当前视图的所有绘图选项，若指定了viewid，则绘制视图viewid 2. 绘图选项操作

PLOT KEYWORD…

Add item

添加绘图选项item至当前视图，所有可选视图选项列于表1.9.

表1.9 可选绘图选项

Axes Clump Extra Location Velocity

Ball

Cluster

Fish

Measure

Wall

Cbond

Contact

Group

Pbond

Cforce

Displacement

History

Table

Clear 擦除当前视图中的所有绘图选项；

Modify i switch …

修改绘图选项i的属性设置，i必须是与该选项对应的整数

如：将球（i=1）的颜色都修改为绿色的命令为plot modify 1 green green green …

Move i1 i2

将当前视图中的选项i1移到选项i2的前面，如需将某个选项移到所有选项的最后，只需

将i2设置为一个大于最大选项号的一个数

Print item

在屏幕上打印当前视图中的所有绘图选项的列表，若指定了i，则打印选项i的详细信息

Subtract i

从当前视图中删除绘图选项i，余下的选项按顺序重新编号。

3. 视图设置操作：PFC3D软件中的视图构成见附录5.

以下关键词用于指定视图设置，所有关键词都应用于设置当前视图。

Reset 重置视图的所有参数设置；

Set keyword

plot set keyword是一个非常重要的命令，视图的属性几乎都是通过该命令来设置的，可

选择的keyword包括以下一些：

angle a

视图角度控制视图的透视变形度，a值越高变形度越大，表现为视图越小。通过调整视图

的放大倍率可以有效地改变视图角度，因此angle值并不是很重要，因为对于任意一个

angle值而言，都可以通过调整放大倍率来得到合适大小的视图。

Animate off：关闭视图自动更新，只在需要更新的时候更新；

On：打开视图自动更新，此时在视图发生改变时都将显示最新的视图，on

为软件默认值；

Background color

设置视图背景颜色为“color”，可选颜色见附录表1。注意，视图的前景颜色可通过

foreground关键词来设定。

Foreground color

将视图前景颜色设为“color”。

Caption keyword

该命令用于设置说明窗口的属性，以下关键词可以选用：

Left 将说明窗口置于左侧（默认）

Right 将说明窗口置于右侧

Off 关闭说明窗口，此时屏幕上的所有位置都用来绘图

On 打开说明窗口（默认）

Size n

参数值n为10~50之间的整数值，表示说明窗口的大小占绘图窗口的百分

比（默认n=35，即说明窗口的大小为绘图窗口的35%）

Color off 关闭色彩显示，此时即使设置了颜色属性，也只能显示或输出灰

度图

On 打开色彩显示，on与off之间可通过快捷键切换

Eyedistance d

Auto

为透视图计算设置视者的眼睛到绘图屏幕的距离。如果指定auto，该距离

由程序自行选取

Magnification m

缩放视图m倍，如果m大于1则放大，小于1则缩小

Mode keyword

Model：切换至model视图模式

Plane：切换至plane视图模式

Firstperson：切换至firstperson视图模式

说明：Plot set mode keyword命令用于选择观察模型视图的模式，keyword有三个关键

词可供选择：firstperson, model, plane，代表3中不同的观察模式。

●Model模式（PFC3D默认模式）下，观察者静止不动，调整的是视图的位置。例如

让视图绕z轴旋转，此时观察者的位置不动，静止在原处看到视图在自己前方绕着

z轴旋转。该模式下通过center、distance和rotation三个关键词来调整视图的位置。

●在Plane模式下观察与在model模式下是一样的，也是观察对象动而观察者不动，

不同的时plane模式更为便利，它允许用户从一个平面的角度而不是一个点的角度

去描述视图。该模式下通过origin, dip, dd, normal, distance和zangle等关键词来调

整视图。

●Firstperson模式与model相反，此时观察对象静止不动，观察者绕着观察对象转动。

此时绕z轴旋转意味着观察者绕z轴转身，而观察对象静止不动，所以此时观察对

象会逐渐淡出观察者的视线，在观察者转身一周后又重新观察到之前一样的视图。

这种模式的有点在于观察者可以穿过进行观察，比如观察一个回转体对象（如圆柱，

套筒，环形），可以将观察者置于回转体轴心位置，在firstperson模式下就能方便地

观察回转体内部的情况。

设置model模式下的视图属性

Center x y z：将模型视图的中心放在点(x,y,z)

Auto：软件自动设定中心位置

Distance d：将观察者的眼睛至视图的距离设为d

Auto：软件自动设置

Rotation xr yr zr

设定视图旋转角度，xr，yr，zr分别是视图绕x-，y-，z-轴的旋转角度，为

角度值而非弧度值

说明：若一开始不知道将这些关键词的值设为多少合适，可以先把视图重置，利用交互

式按键调整视图，此时就可以得到这些关键词的值。

设置plane模式下的视图属性

……