Python Class Reference

Python modules.

SudoDEM3D

Basic classes

class State(inherits Serializable)
State of a body (spatial configuration, internal variables).

angMom(=Vector3r::Zero())
Current angular momentum
angVel(=Vector3r::Zero())
Current angular velocity
blockedDOFs
Degress of freedom where linear/angular velocity will be always constant (equal to zero, or to an user-defined value), regardless of applied force/torque. String that may contain ‘xyzXYZ’ (translations and rotations).
dict() → dict
Return dictionary of attributes.
inertia(=Vector3r::Zero())
Inertia of associated body, in local coordinate system.
isDamped(=true)
Damping in Newtonintegrator can be deactivated for individual particles by setting this variable to FALSE. E.g. damping is inappropriate for particles in free flight under gravity but it might still be applicable to other particles in the same simulation.
mass(=0)
Mass of this body
ori
Current orientation.
pos
Current position.
refOri(=Quaternionr::Identity())
Reference orientation
refPos(=Vector3r::Zero())
Reference position
se3(=Se3r(Vector3r::Zero(), Quaternionr::Identity()))
Position and orientation as one object.

Module _superquadrics_utils

NewSuperquadrics2($r_x$, $r_y$, $r_z$, $\epsilon_1$, $\epsilon_2$, mat, rotate, isSphere)
Generate a Superquadric with isSphere option.
- $r_x$, $r_y$, $r_z$: float, semi-major axis lengths in x, y, and z axies.
- $\epsilon_1$, $\epsilon_2$: float, shape parameters.
- mat: Material, a material attached to the particle.
- rotate: bool, with a random orientation or not.
- isSphere: bool, particle is spherical or not.
NewSuperquadrics_rot2($r_x$, $r_y$, $r_z$, $\epsilon_1$, $\epsilon_2$, mat, $q_w$, $q_x$, $q_y$, $q_z$, isSphere)
Generate a Super-ellipsoid with specified quaternion components: $q_w$, $q_x$, $q_y$, $q_z$ with isSphere option.
- $r_x$, $r_y$, $r_z$: float, semi-major axis lengths in x, y, and z axies.
- $\epsilon_1$, $\epsilon_2$: float, shape parameters.
- mat: Material, a material attached to the particle.
- isSphere: bool, particle is spherical or not.
- $q_w$, $q_x$, $q_y$, $q_z$: float, components of a quaternion ($q_w$, $q_x$, $q_y$, $q_z$) representing the orientation of a particle.
outputWalls(filename)
Output positions of all walls in the scene.
- filename: string, the name (with path) of the output file.
getSurfArea(id, w, h)
Get the surface area of a super-ellipsoid by a given particle id with resolution w and h (e.g., w=10,h=10). Larger w and h will yield more accurate results.
- id: int, the id of the given particle.
- w, h: int, w$\times$h slices the particle surface will be discretized into.
outputParticles(filename)
Output information including id, shape parameters, position and orientation of all particles into a file.
- filename: string, the name (with path) of the output file.
outputParticlesbyIds(filename, ids)
Output particles by a list of ids, referring to the last function. [Only for superellipsoids]
- filename: string, the name (with path) of the output file.
- ids: list of int, a list of particle ids, e.g., [10, 24, 22].
NewPolySuperellipsoid(eps, rxyz, mat, rotate, isSphere, inertiaScale = 1.0)
Generate a PolySuperellipsoid.
- $eps$: Vector2, shape parameters, i.e., [$\epsilon_1$, $\epsilon_2$].
- $rxyz$: Vector6, semi-major axis lengths in x, y, and z axies, i.e.,[$r_x^-$, $r_x^+$, $r_y^-$, $r_y^+$, $r_z^-$, $r_z^+$].
- mat: Material, a material attached to the particle.
- rotate: bool, with a random orientation or not.
- isSphere: bool, particle is spherical or not.
- inertialScale: float, scale the moment of inertia only. Do not set it if you are not sure the side effect.
NewPolySuperellipsoid_rot(eps, rxyz, mat, $q_w$, $q_x$, $q_y$, $q_z$, isSphere, inertiaScale = 1.0)
Generate a PolySuperellipsoid with specified quaternion components: $q_w$, $q_x$, $q_y$ and $q_z$.
- $eps$: Vector2, shape parameters, i.e., [$\epsilon_1$, $\epsilon_2$].
- $rxyz$: Vector6, semi-major axis lengths in x, y, and z axies, i.e.,[$r_x^-$, $r_x^+$, $r_y^-$, $r_y^+$, $r_z^-$, $r_z^+$].
- mat: Material, a material attached to the particle.
- isSphere: bool, particle is spherical or not.
- $q_w$, $q_x$, $q_y$ and $q_z$: float, components of a quaternion ($q_w$, $q_x$, $q_y$, $q_z$) representing the orientation of a particle.
- inertialScale: float, scale the moment of inertia only. Do not set it if you are not sure the side effect.
outputPOV(filename)
Output Superellipsoids (including spheres) into a POV file for post-processing using POV-ray. [Only for superellipsoids and spheres]
- filename: string, the name (with path) of the output file.
PolySuperellipsoidPOV(filename, ids = [], scale = 1.0)
Output PolySuperellipsoids into a POV file for post-processing using POV-ray. This function only output the particles' information to a POV file like *.inc, and the user may need to add some other info such as camera etc. See the module snapshot.
- filename: string, the name (with path) of the output file.
- ids: list of int, a list of particle ids. A NULL list will output all particles by default.
- scale: float, scale the length unit.
outputVTK(filename, slices)
Output Superellpisoids into a VTK file for post-processing using Paraview. [Only for superellipsoids]
- filename: string, the name (with path) of the output file.
- slices: int, into how many slices the particle surface will be discretized.

Module _gjkparticle_utils

GJKSphere(radius,margin,mat)
- radius, float, radius of the sphere.
- margin, float, a small margin added to the surface for assisting contact detection.
- mat, Material, a specified material attached to the particle.
GJKPolyhedron(vertices,extent,margin,mat, rotate)
- vertices, a list of vertices, and each vertex is a list, e.g., $[x, y, z]$ for coordinates.
- extent, a list of three components to scale the x, y, z dimensions; valid only if vertices has no elements (i.e., $ $); a randomly shaped polyhedron will be generated based on Voronoi tessellation.
- margin, float, a small margin added to the surface for assisting contact detection.
- mat, Material, a specified material attached to the particle.
- rotate, bool, with random orientation or not.
GJKCone(radius, height, margin, mat, rotate)
- radius, float, base radius of the cone.
- height, float, height of the cone.
- margin, float, a small margin added to the surface for assisting contact detection.
- mat, Material, a specified material attached to the particle.
- rotate, bool, with random orientation or not.
GJKCylinder(radius, height, margin, mat, rotate)
- radius, float, radius of the cylinder.
- height, float, height of the cylinder.
- margin, float, a small margin added to the surface for assisting contact detection.
- mat, Material, a specified material attached to the particle.
- rotate, bool, with random orientation or not.
GJKCuboid(extent, margin,mat, rotate)
- extent, a list of three floats, extent of the cuboid in the x, y, z dimensions.
- margin, float, a small margin added to the surface for assisting contact detection.
- mat, Material, a specified material attached to the particle.
- rotate, bool, with random orientation or not.

Note: a margin is used to expand a particle for achieving a better computational efficiency, which however should be large enough for ensuring that collision occurs in this small region but small enough for shape fidelity.

Module snapshot

outputBoxPov(filename, x, y, z, r=0.001, wallMask=[1,0,1,0,0,1])
Output *.POV of a cubic box (x=[x_min, x_max], y=[y_min, y_max], z=[z_min, z_max]) for post-processing in Pov-ray.
- filename: string, the name (with path) of the output file.
- x, y, z: Vector2, ranges of the cubic box along the three (x, y, z) directions.
- r: float, thickness of the box edge.
- wallMask, list of 6 int, corresponding to the six walls at (x-, x+, y-, y+, z-, z+). 1 to show and 0 to hide the wall.
outPov(fname,transmit=0,phong=1.0,singleColor=True,ids=[],scale=1.0, withbox = True)\
- filename, string, the name (with path) of the output file.
- transmit, float, parameter for transparency of particles, ranging between 0 and 1.
- phong, float, parameter for highlighting the surface, ranging between 0 and 1.
- singleColor, bool, whether to use a single color for all particles. If not, particles' colors would be the values defined in Shape.
- ids, list of int, a list of particle ids that will be output. If no item are given, then all particles will be output by default.
- scale, float, scale the unit.
The user is referred to POV-Ray’s Doc for more details on the two parameters (transmit and phong) and others that will be written to the output file by this function.

SudoDEM2D

Basic classes

Class State
State of a body (spatial configuration, internal variables).

angMom(=Vector2r::Zero())
Current angular momentum
angVel(=Vector2r::Zero())
Current angular velocity
blockedDOFs
Degress of freedom where linear/angular velocity will be always constant (equal to zero, or to an user-defined value), regardless of applied force/torque. String that may contain ‘xyZ’ (translations and rotations).
dict() → dict
Return dictionary of attributes.
inertia(=Vector2r::Zero())
Inertia of associated body, in local coordinate system.
isDamped(=true)
Damping in Newtonintegrator can be deactivated for individual particles by setting this variable to FALSE. E.g. damping is inappropriate for particles in free flight under gravity but it might still be applicable to other particles in the same simulation.
mass(=0)
Mass of this body
ori
Current orientation. The orientation and rotation of a particle is represented by a Rotation2d object (see Rotation2D in the Eigen library), which has the following members and functions.
Class Rotation2d
- angle: float, rotation represented by an angle in rad.
- toRotationMatrix(): Matrix2r, returns an equivalent 2x2 rotation matrix.
- Identity(): Roation2d, returns an identity rotation.
- smallestAngle(): float, returns the rotation angle in $[-\pi,\pi]$
- inverse(): Roation2d, returns the inverse rotation
- smallestPositiveAngle(): float, returns the rotation angle in $[0,2\pi]$
pos
Current position.
refOri(=Rotation2D::Identity())
Reference orientation
refPos(=Vector2r::Zero())
Reference position
se2(=Se2r(Vector2r::Zero(), Rotation2d::Identity()))
Position and orientation as one object.
vel(=Vector2r::Zero()) Current linear velocity.

Module _superellipse_utils

NewSuperellipse(rx, ry, epsilon, material, rotate, isSphere, z_dim =1.0)

Create a Superellipse
- rx, ry: float, semi-axis length of the particle
- epsilon: float, shape parameter of a superellipse
- material: Material instance
- rotate: bool, rotate the particle with random orientation?
- isSphere: bool, is the superellipse a disk? A disk will speed up the computation.
- z_dim: float, the virtual length at the z dimension, and set to 1.0 by default.
NewSuperellipse_rot(x, y, epsilon, material, miniAngle, isSphere, z_dim = 1.0)

Create a superellipse with certain orientation
- rx, ry: float, semi-axis length of the particle
- epsilon: float, shape parameter of a superellipse
- material: Material instance
- miniAngle: orientation of the particle specified by the angle between its rx-axis and the global x axis
- isSphere: bool, is the superellipse a disk? A disk will speed up the computation.
- z_dim: float, the virtual length at the z dimension, and set to 1.0 by default.
outputParticles(filename)

output particle info(rx,ry,eps,x,y,rotation angle) to a text file
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)

Output particle profiles and contact force chains into a SVG file.
- filename: string, the name of the output file
- width_cm: float, width (in centimeters) in the SVG header
- slice: int, to how many slices a Superellipse will be discretized
- line_width: float, the line width of the edge of a Superellipse
- fill_opacity: float, the opacity of the fill color in a Superellipse
- draw_filled: bool, wheter to fill a Superellipse with a color
- draw_lines: bool, whether to draw the out profile of a Superellipse
- color_po: bool, whether to use a fill color to identify the orientation of a Superellipse
- po_color: Vector3r, the fill color to identify the orientation of a Superellipse
- solo_color: Vector3r, a solor color to fill a Superellipse. If its norm is zero, then use the color defined by po_color or shape$\rightarrow$color
- force_line_width: float, the line width of the force chain with the average normal contact force
- force_fill_opacity: float, the opacity of force chains
- force_line_color: Vector3r, the color of the force chain
- draw_forcechain: bool, whether to draw the contact force chain that will be superposed with the particles

Module _utils

unbalancedForce(useMaxForce=false)

Compute the ratio of mean (or maximum, if *useMaxForce*) summary force on bodies and mean force magnitude on interactions. For perfectly static equilibrium, summary force on all bodies is zero (since forces from interactions cancel out and induce no acceleration of particles); this ratio will tend to zero as simulation stabilizes, though zero is never reached because of finite precision computation. Sufficiently small value can be e.g. 1e-2 or smaller, depending on how much equilibrium it should be.
getParticleVolume2D()
Compute the total volume (area for 2D) of particles in the scene.
getMeanCN()
Get the mean coordination number of a packing
changeParticleSize2D(alpha)
expand a particle by a given coefficient
getVoidRatio2D(cellArea=1)
Compute 2D void ratio. Keyword cellArea is effective only for aperioidc cell
getStress2D(z_dim=1)
Compute overall stress of periodic cell
getFabricTensorCN2D()
Fabric tensor of contact normal
getFabricTensorPO2D()
Fabric tensor of particle orientation along the rx axis
getStressAndTangent2D(z_dim=1,symmetry=true)
Compute overall stress of periodic cell using the same equation as function getStress. In addition, the tangent operator is calculated using the equation: $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)$ float volume: same as in function getStress bool symmetry: make the tensors symmetric.
return: macroscopic stress tensor and tangent operator as py::tuple
getStressTangentThermal2D(z_dim=1, symmetry =true)
Compute overall stress of periodic cell using the same equation as function getStress. In addition, the tangent operator is calculated using the equation: $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)$ float volume: same as in function getStress bool symmetry: make the tensors symmetric. Finally, the thermal conductivity tensor is calculated based on the formular in PFC. macroscopic stress tensor and tangent operator as py::tuple

Module utils

disk(center, radius, z_dim=1, dynamic=None, fixed=False, wire=False, color=None, highlight=False, material=-1,mask=1)
Create a disk with given parameters; mass and inertia computed automatically.
- center: Vector2, center
- radius: float, radius
- dynamic: float, deprecated, see "fixed"
- fixed: float, generate the body with all DOFs blocked?
- material: specify ‘Body.material’; different types are accepted:
  - int: O.materials[material] will be used; as a special case, if material==-1 and there is no shared materials defined, utils.defaultMaterial() will be assigned to O.materials[0]
  - string: label of an existing material that will be used
  - ‘Material’ instance: this instance will be used
  - callable: will be called without arguments; returned Material value will be used (Material factory object, if you like)
- int mask: ‘Body.mask’ for the body
- wire: display as wire disk?
- highlight: highlight this body in the viewer?
- Vector2-or-None: body’s color, as normalized RGB; random color will be assigned if “None”.
wall(position, axis, sense=0, color=None, material=-1, mask=1)
Return ready-made wall body.
- position: float-or-Vector3 , center of the wall. If float, it is the position along given axis, the other 2 components being zero
- axis: {0,1} , orientation of the wall normal (0,1) for x,y
- sense: {-1,0,1} , sense in which to interact (0: both, -1: negative, +1: positive; see ‘Wall’)
See ‘utils.disk'’s documentation for meaning of other parameters.
fwall(vertex1, vertex2, dynamic=None, fixed=True, color=None, highlight=False, noBound=False, material=-1, mask=1, chain=-1)
Create fwall with given parameters.
- vertex1: Vector2, coordinates of vertex1 in the global coordinate system.
- vertex2: Vector2, coordinates of vertex2 in the global coordinate system.
- noBound: bool, set ‘Body.bounded’
- color: Vector3-or-None , color of the facet; random color will be assigned if ‘None’.
See ‘utils.disk'’s documentation for meaning of other parameters.