Python类参考文档
SudoDEM3D
基类
class State(继承自 Serializable 类)
颗粒的状态 (空间位置,固有的物理状态)。
-
angMom(=Vector3r::Zero())
当前时步角动量 -
angVel(=Vector3r::Zero())
当前时步角速度 -
blockedDOFs
平动/转动的自由度约束状态。 该变量设置后,相应的平动或转动将保持在一个恒定值。 若要约束颗粒所有的平动及转动速度,可以使用字符串 ‘xyzXYZ’。 -
dict() → dict
返回状态的字典。 -
inertia(=Vector3r::Zero())
颗粒在局部坐标的转动惯量。 -
isDamped(=true)
该布尔值设置为false后颗粒在牛顿积分引擎中的计算将不考虑阻尼, 例如在模拟颗粒自由落体时,人工阻尼的引入将会导致错误的计算结果。 -
mass(=0)
颗粒的质量 -
ori
颗粒的旋转属性 -
pos
颗粒当前时步的位置 -
refOri(=Quaternionr::Identity())
颗粒参考旋转坐标 -
refPos(=Vector3r::Zero())
颗粒参考位置 -
se3(=Se3r(Vector3r::Zero(), Quaternionr::Identity()))
封装颗粒的位置和旋转坐标在一个变量中
超二次椭球模块 _superquadrics_utils
-
NewSuperquadrics2($r_x$, $r_y$, $r_z$, $\epsilon_1$, $\epsilon_2$, mat, rotate, isSphere)
该函数用于生成超二次椭球。-
$r_x$, $r_y$, $r_z$: float, 超二次椭球的半长轴
-
$\epsilon_1$, $\epsilon_2$: float, 超二次椭球形状参数
-
mat: Material, 超二次椭球的材料属性
-
rotate: bool, 超二次椭球在生成时是否被赋予随机旋转朝向
-
isSphere: bool, 超二次椭球是否是球体
-
-
NewSuperquadrics_rot2($r_x$, $r_y$, $r_z$, $\epsilon_1$, $\epsilon_2$, mat, $q_w$, $q_x$, $q_y$, $q_z$, isSphere)
该函数用于生成具备特定旋转朝向的超二次椭球。 $q_w$, $q_x$, $q_y$, $q_z$ 用于表征颗粒的旋转四元数,isSphere 用于决定颗粒是否为球体。-
$r_x$, $r_y$, $r_z$: float, 超二次椭球的半长轴
-
$\epsilon_1$, $\epsilon_2$: float, 超二次椭球形状参数
-
mat: Material, 超二次椭球的材料属性
-
isSphere: bool, 超二次椭球是否是球体
-
$q_w$, $q_x$, $q_y$, $q_z$: float, 颗粒的旋转四元数
-
-
outputWalls(filename)
输出当前模拟试样中的墙体位置- filename: string, 墙体位置保存文件的文件名
-
getSurfArea(id, w, h)
输出特定颗粒索引的表面积,该表面积由两个精度参数w 和 h 来控制,比如 w=10,h=10。 更大的 w 和 h值可以得到更高精度的表面积值。-
id: int, 颗粒索引
-
w, h: int, w$\times$h 将颗粒表面剖分为较小的四边形以此来进行表面积计算
-
-
outputParticles(filename)
输出所有颗粒信息到文件中,包括颗粒的索引,形状参数以及颗粒朝向信息到文件中- filename: string, 颗粒信息保存文件文件名
-
outputParticlesbyIds(filename, ids)
输出指定索引的颗粒信息到文件中,包括颗粒的索引,形状参数以及颗粒朝向信息到文件中 [Only for superellipsoids]-
filename: string, 颗粒信息保存文件文件名
-
ids: list of int, 颗粒索引列表, 例如, [10, 24, 22].
-
-
NewPolySuperellipsoid(eps, rxyz, mat, rotate, isSphere, inertiaScale = 1.0)
生成组合超二次椭球颗粒-
$eps$: Vector2, 组合超二次椭球的形状参数 即, [$\epsilon_1$, $\epsilon_2$].
-
$rxyz$: Vector6, 颗粒在三个正交坐标 (x, y, z) 的正向以及负向的半长轴, 即[$r_x^-$, $r_x^+$, $r_y^-$, $r_y^+$, $r_z^-$, $r_z^+$].
-
mat: Material, 组合超二次椭球的材料属性
-
rotate: bool, 生成的组合超二次椭球是否被赋予随机朝向
-
isSphere: bool, 生成的组合超二次椭球是否为球体
-
inertialScale: float, 用于缩放颗粒的转动惯量,如果尚未仔细了解此变量施加后的实际效果,请谨慎行事
-
-
NewPolySuperellipsoid_rot(eps, rxyz, mat, $q_w$, $q_x$, $q_y$, $q_z$, isSphere, inertiaScale = 1.0)
生成具有指定旋转属性的组合超二次椭球颗粒-
$eps$: Vector2, 组合超二次椭球的形状参数 即, [$\epsilon_1$, $\epsilon_2$].
-
$rxyz$: Vector6, 颗粒在三个正交坐标 (x, y, z) 的正向以及负向的半长轴, 即[$r_x^-$, $r_x^+$, $r_y^-$, $r_y^+$, $r_z^-$, $r_z^+$].
-
mat: Material, 组合超二次椭球的材料属性
-
isSphere: bool, 生成的组合超二次椭球是否为球体
-
$q_w$, $q_x$, $q_y$ and $q_z$: float, 组合超二次椭球的四元数参数 ($q_w$, $q_x$, $q_y$, $q_z$)
-
inertialScale: float, 用于缩放颗粒的转动惯量,如果尚未仔细了解此变量施加后的实际效果,请谨慎行事
-
-
outputPOV(filename)
输出超二次椭球(包括球体)的 POV 渲染信息到文本文件中,以便于用于可以使用 POV-ray来后处理相应的模拟结果 [目前仅支持超二次椭球以及球体]- filename: string, POV文件文件名
-
PolySuperellipsoidPOV(filename, ids = [], scale = 1.0)
输出组合超二次椭球的 POV 渲染信息到文本文件中,输出文件包括 *.inc 等文件, 用户可以通过修改该文件来改变相应的相机设置。详情请参见模块 snapshot.-
filename: string, POV文件文件名
-
ids: list of int, 给定的颗粒索引列表,若列表为空,则默认输出所有颗粒的信息。
-
scale: float, 用于对长度单位进行缩放。
-
-
outputVTK(filename, slices)
输出超二次椭球的颗粒信息到VTK文件中,以便于用户可以使用 Paraview 来对计算结果进行后处理。 [仅支持超二次椭球]-
filename: string, 输出文件的文件名
-
slices: int, 颗粒表面的离散精度
-
模块 _gjkparticle_utils
-
GJKSphere(radius,margin,mat)
-
radius, float, 球体半径
-
margin, float, 颗粒表面较小的边缘,用于辅助颗粒之间的接触检测
-
mat, Material, 颗粒材料属性
-
-
GJKPolyhedron(vertices,extent,margin,mat, rotate)
-
vertices, 多面体顶点列表,每个列表表征一个顶点的坐标, 例如, $[x, y, z]$。
-
extent, 用于缩放顶点的系数,尽在 vertices 为空时有效 (例如, $ $); 随机形状的多面体将基于Voronoi剖分生成。
-
margin, float, 颗粒表面较小的边缘,用于辅助颗粒之间的接触检测
-
mat, Material, 颗粒材料属性
-
rotate, bool, 颗粒是否在生成时被赋予随机旋转朝向
-
-
GJKCone(radius, height, margin, mat, rotate)
-
radius, float, 圆锥基地半径
-
height, float, 圆锥高
-
margin, float, 颗粒表面较小的边缘,用于辅助颗粒之间的接触检测
-
mat, Material, 颗粒材料属性
-
rotate, bool, 颗粒是否在生成时被赋予随机旋转朝向
-
-
GJKCylinder(radius, height, margin, mat, rotate)
-
radius, float, 圆柱半径
-
height, float, 圆柱高
-
margin, float, 颗粒表面较小的边缘,用于辅助颗粒之间的接触检测
-
mat, Material, 颗粒材料属性
-
rotate, bool, 颗粒是否在生成时被赋予随机旋转朝向
-
-
GJKCuboid(extent, margin,mat, rotate)
-
extent, 缩放系数用于缩放立方体在三维空间的尺寸
-
margin, float, 颗粒表面较小的边缘,用于辅助颗粒之间的接触检测
-
mat, Material, 颗粒材料属性
-
rotate, bool, 颗粒是否在生成时被赋予随机旋转朝向
-
注: 每个颗粒都被设置了一个较小的边缘尺寸用于加速颗粒的接触检测,该边缘应该足够大以满足颗粒接触检测的精度, 同时该边缘也应该足够小以至于不影响颗粒的实际形状尺寸。
模块 snapshot
-
outputBoxPov(filename, x, y, z, r=0.001, wallMask=[1,0,1,0,0,1])
输出立方体的 *.POV 文件 (x=[x_min, x_max], y=[y_min, y_max], z=[z_min, z_max]) 以便于用户使用 Pov-ray 进行后处理。-
filename: string, POV 文件名
-
x, y, z: Vector2, 立方体在三维空间的尺寸大小
-
r: float, 立方体盒子边缘大小
-
wallMask, list of 6 int, 该掩码用于设置六面墙体的消隐 (x-, x+, y-, y+, z-, z+)。 1 表示显示, 0 表示隐去。
-
-
outPov(fname,transmit=0,phong=1.0,singleColor=True,ids=[],scale=1.0, withbox = True)\
-
filename, string, POV 文件名
-
transmit, float, 颗粒的透明度大小,取值为0到1
-
phong, float, 颗粒亮度强光设置,取值为0到1
-
singleColor, bool, 是否为颗粒采用单一颜色,若否,则颗粒的颜色设置将视形状而定
-
ids, list of int, 指定的输出颗粒索引列表。若列表为空则默认输出所有颗粒信息。
-
scale, float, 缩放颗粒的长度尺寸
用户可参见 POV-Ray 相关手册来详细了解该函数所使用的 POV-Ray 内置变量的信息,例如 transmit 和 phong。
-
SudoDEM2D
基类
Class State
颗粒的状态 (空间位置,固有的物理状态)。
-
angMom(=Vector2r::Zero())
当前时步角动量 -
angVel(=Vector2r::Zero())
当前时步角速度 -
blockedDOFs
平动/转动的自由度约束状态。 该变量设置后,相应的平动或转动将保持在一个恒定值。 若要约束颗粒所有的平动及转动速度,可以使用字符串 ‘xyZ’。 -
dict() → dict
返回状态的字典。 -
inertia(=Vector2r::Zero())
颗粒在局部坐标的转动惯量。 -
isDamped(=true)
该布尔值设置为false后颗粒在牛顿积分引擎中的计算将不考虑阻尼, 例如在模拟颗粒自由落体时,人工阻尼的引入将会导致错误的计算结果。 -
mass(=0)
颗粒的质量 -
ori
颗粒的旋转属性,该旋转变量使用 Rotation2d 对象 (参见 Eigen 库 Rotation2D ), 该对象具有如下方法
Class Rotation2d-
angle: float, 用弧度制表征的旋转角度
-
toRotationMatrix(): Matrix2r, 返回响应的 2 $\times$ 2旋转矩阵
-
Identity(): Roation2d, 返回单位旋转矩阵
-
smallestAngle(): float, 返回旋转角度,取值为 $[-\pi,\pi]$
-
inverse(): Roation2d, 返回逆旋转状态
-
smallestPositiveAngle(): float, 返回旋转角度,取值为 $[0,2\pi]$
-
-
pos
颗粒当前时步的位置 -
refOri(=Rotation2D::Identity())
颗粒参考旋转坐标 -
refPos(=Vector2r::Zero())
颗粒参考位置 -
se2(=Se2r(Vector2r::Zero(), Rotation2d::Identity()))
封装颗粒的位置和旋转坐标在一个变量中 -
vel(=Vector2r::Zero()) 当前颗粒的平动速度
模块 _superellipse_utils
-
NewSuperellipse(rx, ry, epsilon, material, rotate, isSphere, z_dim =1.0)
该函数用于生成超二次椭圆。
-
rx, ry: float, 超二次椭圆的半长轴
-
epsilon: float, 超二次椭圆形状参数
-
material: 超二次椭圆的材料属性
-
rotate: bool, 超二次椭圆在生成时是否被赋予随机旋转朝向
-
isSphere: bool, 超二次椭圆是否是球体,该变量用于加速计算
-
z_dim: float, 颗粒在z方向的虚拟厚度,默认为1
-
-
NewSuperellipse_rot(x, y, epsilon, material, miniAngle, isSphere, z_dim = 1.0)
该函数用于生成具备特定旋转朝向的超二次椭圆
-
rx, ry: float, 超二次椭圆的半长轴
-
epsilon: float, 超二次椭圆形状参数
-
material: 超二次椭圆的材料属性
-
miniAngle: 颗粒的旋转四元数
-
isSphere: bool, 超二次椭圆是否是球体,该变量用于加速计算
-
z_dim: float, 颗粒在z方向的虚拟厚度,默认为1
-
-
outputParticles(filename)
输出所有颗粒信息到文件中,包括颗粒的索引,形状参数以及颗粒朝向信息到文本文件中
-
drawSVG(filename, width_cm = 10.0, slice = 20, line_width = 0.1, fill_opacity = 0.5, draw_filled = true, draw_lines = true, color_po = false, po_color = Vector3r(1.0,0.0,0.0), solo_color = Vector3r(0,0,0), force_line_width = 0.001, force_fill_opacity = 0, force_line_color = Vector3r(1.0,1.0,1.0), draw_forcechain = false)
输出颗粒的轮廓以及力链信息到 SVG 文件中
-
filename: string, 输出文件名
-
width_cm: float, SVG 头部信息中的宽度
-
slice: int, 超椭圆的剖分数量
-
line_width: float, 超椭圆边缘轮廓线的宽度
-
fill_opacity: float, 超椭圆填充颜色的透明度
-
draw_filled: bool, 超椭圆是否进行颜色填充
-
draw_lines: bool, 是否输出超椭圆的轮廓线
-
color_po: bool, 是否使用填充颜色来表征超椭圆的朝向
-
po_color: Vector3r, 用于表征超椭圆朝向的颜色 RGB
-
solo_color: Vector3r, 超椭圆填充颜色,若该值为0则使用 po_color 定义的颜色或使用 shape$\rightarrow$color
-
force_line_width: float, 力链线条的宽度
-
force_fill_opacity: float, 力链线条透明度
-
force_line_color: Vector3r, 力链线条颜色
-
draw_forcechain: bool, 是否将力链信息叠加绘制在颗粒轮廓上
-
模块 _utils
-
unbalancedForce(useMaxForce=false)
计算平均或最大不平衡力(若要计算最大不平衡力,使用 *useMaxForce*)。 For 对于绝对静止的平衡系统来说,所有颗粒的合力为0; 对于特定数值模拟, 理论上来说该不平衡力系数将随着模拟的进行渐趋于0,但是考虑到计算的精度问题,该不平衡力系数只能有限度的趋近于0。 用户可以设置足够小的不平衡力系数,例如1e-2或更小, 该值的具体设置取决于实际的模拟问题。
-
getParticleVolume2D()
模拟中颗粒的总体积 -
getMeanCN()
获取颗粒的平均配位数 -
changeParticleSize2D(alpha)
以特定比例来放大颗粒 -
getVoidRatio2D(cellArea=1)
计算颗粒试样的二维孔隙比,变量 cellArea 仅在非周期边界情况下适用 -
getStress2D(z_dim=1)
计算周期边界下试样的应力张量 -
getFabricTensorCN2D()
计算颗粒接触法向的组构张量 -
getFabricTensorPO2D()
计算颗粒朝向的组构张量 -
getStressAndTangent2D(z_dim=1,symmetry=true)
计算周期边界下的颗粒应力张量以及对应的雅克比: $S_{ijkl}=\frac{1}{V}\sum_{c}(k_n n_i l_j n_k l_l + k_t t_i l_j t_k l_l)$ -
getStressTangentThermal2D(z_dim=1, symmetry =true)
计算周期边界下考虑热应力耦合的颗粒应力张量以及对应的雅克比: $S_{ijkl}=\frac{1}{V}\sum_{c}(k_n n_i l_j n_k l_l + k_t t_i l_j t_k l_l)$
模块 utils
-
disk(center, radius, z_dim=1, dynamic=None, fixed=False, wire=False, color=None, highlight=False, material=-1,mask=1)
生成圆盘-
center: Vector2, 圆盘坐标
-
radius: float, 圆盘半径
-
dynamic: float, 已被弃用
-
fixed: float, 是否约束颗粒的自由度
-
material: 颗粒材料属性有如下定义方式
-
int: 颗粒将采用 O.materials[material] ; 若 material==-1 且对应颗粒材料无定义,utils.defaultMaterial() 将被设置为 O.materials[0]
-
string: 已存在的颗粒材料的标签
-
‘Material’ instance: 颗粒材料对象
-
callable: 无参调用; 返回颗粒材料值
-
-
int mask: 颗粒形状的掩码 ‘Body.mask’
-
wire: GUI显示中该颗粒将用线条而不是面来渲染
-
highlight: GUI中该颗粒是否高亮显示
-
Vector2-or-None: 颗粒颜色, 归一化的 RGB; 若该值定义为 None,则颗粒颜色为随机设置
-
-
wall(position, axis, sense=0, color=None, material=-1, mask=1)
返回墙体-
position: float-or-Vector3 , 墙体中心位置。若给定一维浮点数,则其他两个分量自动填充为0。
-
axis: {0,1} , 墙体的朝向
-
sense: {-1,0,1} , 激活墙体的接触检测,若设为0,则墙体的两侧接触检测都被激活,若设为-1,墙体仅在负方向激活接触检测;反之,反之
其他参数的具体定义请参见文档 ‘utils.disk’。
-
-
fwall(vertex1, vertex2, dynamic=None, fixed=True, color=None, highlight=False, noBound=False, material=-1, mask=1, chain=-1)
返回fwall墙体,该类与wall的区别在于,fwall是有限范围而wall是无限大范围-
vertex1: Vector2, 顶点1的全局坐标
-
vertex2: Vector2, 顶点2的全局坐标
-
noBound: bool, 设置对应的 ‘Body.bounded’
-
color: Vector3-or-None , fwall的颜色; 若改定为None则采用随机颜色
其他参数的具体定义请参见文档 ‘utils.disk’。
-