Heap of functions that don’t (yet) fit anywhere else.
Devs: please DO NOT ADD more functions here, it is getting too crowded!
Compute the normal damping rate as a function of the normal coefficient of restitution . For
damping rate equals
Compute P-wave critical timestep for a single (presumably representative) sphere, using formula for P-Wave propagation speed .
If you want to compute minimum critical timestep for all spheres in the simulation, use utils.PWaveTimeStep instead.
>>> SpherePWaveTimeStep(1e-3,2400,30e9)
2.8284271247461903e-07
Class for reading simulation parameters from text file.
Each parameter is represented by one column, each parameter set by one line. Colums are separated by blanks (no quoting).
First non-empty line contains column titles (without quotes). You may use special column named ‘description’ to describe this parameter set; if such colum is absent, description will be built by concatenating column names and corresponding values (param1=34,param2=12.22,param4=foo)
Empty lines within the file are ignored (although counted); # starts comment till the end of line. Number of blank-separated columns must be the same for all non-empty lines.
A special value = can be used instead of parameter value; value from the previous non-empty line will be used instead (works recursively).
This class is used by utils.readParamsFromTable.
Return dictionary containing data from file given to constructor. Keys are line numbers (which might be non-contiguous and refer to real line numbers that one can see in text editors), values are dictionaries mapping parameter names to their values given in the file. The special value ‘=’ has already been interpreted, ! (bangs) (if any) were already removed from column titles, description column has already been added (if absent).
Return dimensions of the axis-aligned bounding box, optionally with relative part cutoff cut away.
Return 6 boxes that will wrap existing packing as walls from all sides; extrema are extremal points of the Aabb of the packing (will be calculated if not specified) thickness is wall thickness (will be 1/10 of the X-dimension if not specified) Walls will be enlarged in their plane by oversizeFactor. returns list of 6 wall Bodies enclosing the packing, in the order minX,maxX,minY,maxY,minZ,maxZ.
Return average numer of interactions per particle, also known as coordination number . This number is defined as
where is number of contacts and
is number of particles.
With skipFree, particles not contributing to stable state of the packing are skipped, following equation (8) given in [Thornton2000]:
Parameters: |
|
---|
Create box (cuboid) with given parameters.
Parameters: | extents (Vector3) – half-sizes along x,y,z axes |
---|
See utils.sphere‘s documentation for meaning of other parameters.
Create and connect a chainedCylinder with given parameters. The shape generated by repeted calls of this function is the Minkowski sum of polyline and sphere.
Parameters: |
|
---|
In order to build a correct chain, last point of element of rank N must correspond to first point of element of rank N+1 in the same chain (with some tolerance, since bounding boxes will be used to create connections.
Returns: | Body object with the ChainedCylinder shape. |
---|
Return default material, when creating bodies with utils.sphere and friends, material is unspecified and there is no shared material defined yet. By default, this function returns:
.. code-block:: python
FrictMat(density=1e3,young=1e7,poisson=.3,frictionAngle=.5,label=’defaultMat’)
Create facet with given parameters.
Parameters: |
|
---|
See utils.sphere‘s documentation for meaning of other parameters.
retrurn (min,max) that is the original minMax box (or aabb of the whole simulation if not specified) linearly scaled around its center to the fraction factor
Load variables from utils.saveVars, which are saved inside the simulation. If mark==None, all save variables are loaded. Otherwise only those with the mark passed.
Create a video from external image files using mencoder. Two-pass encoding using the default mencoder codec (mpeg4) is performed, running multi-threaded with number of threads equal to number of OpenMP threads allocated for Yade.
Parameters: |
|
---|
Return area perpendicular to given axis (0=x,1=y,2=z) generated by bodies for which the function consider returns True (defaults to returning True always) and which is of the type Sphere.
Plot 3 histograms for distribution of interaction directions, in yz,xz and xy planes and (optional but default) histogram of number of interactions per body.
Returns: | If noShow is False, displays the figure and returns nothing. If noShow, the figure object is returned without being displayed (works the same way as plot.plot). |
---|
Plot histogram with number of interactions per body, optionally cutting away cutoff relative axis-aligned box from specimen margin.
Calculates particle size distribution.
Parameters: |
|
---|---|
Returns: |
binsSizes, binsProc, binsSumCum |
Return random Vector3 with each component in interval 0…1 (uniform distribution)
Assign random colors to Shape::color.
If onlyDynamic is true, only dynamic bodies will have the color changed.
Read parameters from a file and assign them to __builtin__ variables.
The format of the file is as follows (commens starting with # and empty lines allowed):
# commented lines allowed anywhere
name1 name2 … # first non-blank line are column headings
# empty line is OK, with or without comment
val1 val2 … # 1st parameter set
val2 val2 … # 2nd
…
Assigned tags (the description column is synthesized if absent,see utils.TableParamReader);
O.tags[‘description’]=… # assigns the description column; might be synthesized O.tags[‘params’]=”name1=val1,name2=val2,…” # all explicitly assigned parameters O.tags[‘defaultParams’]=”unassignedName1=defaultValue1,…” # parameters that were left at their defaults O.tags[‘d.id’]=O.tags[‘id’]+’.’+O.tags[‘description’] O.tags[‘id.d’]=O.tags[‘description’]+’.’+O.tags[‘id’]
All parameters (default as well as settable) are saved using utils.saveVars('table').
Parameters: |
|
---|---|
Returns: | number of assigned parameters |
Replaces collider (Collider) engine with the engine supplied. Raises error if no collider is in engines.
Save passed variables into the simulation so that it can be recovered when the simulation is loaded again.
For example, variables a, b and c are defined. To save them, use:
>>> from yade import utils
>>> utils.saveVars('something',a=1,b=2,c=3)
>>> from yade.params.something import *
>>> a,b,c
(1, 2, 3)
those variables will be save in the .xml file, when the simulation itself is saved. To recover those variables once the .xml is loaded again, use
>>> utils.loadVars('something')
and they will be defined in the yade.params.mark module. The loadNow parameter calls utils.loadVars after saving automatically.
Create sphere with given parameters; mass and inertia computed automatically.
Last assigned material is used by default (material = -1), and utils.defaultMaterial() will be used if no material is defined at all.
Parameters: |
|
---|---|
Returns: | A Body instance with desired characteristics. |
Creating default shared material if none exists neither is given:
>>> O.reset()
>>> from yade import utils
>>> len(O.materials)
0
>>> s0=utils.sphere([2,0,0],1)
>>> len(O.materials)
1
Instance of material can be given:
>>> s1=utils.sphere([0,0,0],1,wire=False,color=(0,1,0),material=ElastMat(young=30e9,density=2e3))
>>> s1.shape.wire
False
>>> s1.shape.color
Vector3(0,1,0)
>>> s1.mat.density
2000.0
Material can be given by label:
>>> O.materials.append(FrictMat(young=10e9,poisson=.11,label='myMaterial'))
1
>>> s2=utils.sphere([0,0,2],1,material='myMaterial')
>>> s2.mat.label
'myMaterial'
>>> s2.mat.poisson
0.11
Finally, material can be a callable object (taking no arguments), which returns a Material instance. Use this if you don’t call this function directly (for instance, through yade.pack.randomDensePack), passing only 1 material parameter, but you don’t want material to be shared.
For instance, randomized material properties can be created like this:
>>> import random
>>> def matFactory(): return ElastMat(young=1e10*random.random(),density=1e3+1e3*random.random())
...
>>> s3=utils.sphere([0,2,0],1,material=matFactory)
>>> s4=utils.sphere([1,2,0],1,material=matFactory)
Track perfomance of a simulation. (Experimental) Will create new thread to produce some plots. Useful for track perfomance of long run simulations (in bath mode for example).
Return first engine from current O.engines, identified by its type (as string). For example:
>>> from yade import utils
>>> O.engines=[InsertionSortCollider(),NewtonIntegrator(),GravityEngine()]
>>> utils.typedEngine("NewtonIntegrator") == O.engines[1]
True
Get some data about the current packing useful for uniaxial test:
Parameters: |
|
---|---|
Returns: | dictionary with keys negIds, posIds, axis, area. |
Warning
The function utils.approxSectionArea uses convex hull algorithm to find the area, but the implementation is reported to be buggy (bot works in some cases). Always check this number, or fix the convex hull algorithm (it is documented in the source, see py/_utils.cpp).
Calculate the porosity of a sample, given the TriaxialCompressionEngine.
A function utils.voxelPorosity is invoked, with the volume of a box enclosed by TriaxialCompressionEngine walls. The additional parameter offset allows using a smaller volume inside the box, where each side of the volume is at offset distance from the walls. By this way it is possible to find a more precise porosity of the sample, since at walls’ contact the porosity is usually reduced.
A recommended value of offset is bigger or equal to the average radius of spheres inside.
The value of resolution depends on size of spheres used. It can be calibrated by invoking voxelPorosityTriaxial with offset=0 and comparing the result with TriaxialCompressionEngine.porosity. After calibration, the offset can be set to radius, or a bigger value, to get the result.
Parameters: |
|
---|---|
Returns: | the porosity of the sample inside given volume |
Example invocation:
from yade import utils
rAvg=0.03
TriaxialTest(numberOfGrains=200,radiusMean=rAvg).load()
O.dt=-1
O.run(1000)
O.engines[4].porosity
0.44007807740143889
utils.voxelPorosityTriaxial(O.engines[4],200,0)
0.44055412500000002
utils.voxelPorosityTriaxial(O.engines[4],200,rAvg)
0.36798199999999998
Block the simulation if running inside a batch. Typically used at the end of script so that it does not finish prematurely in batch mode (the execution would be ended in such a case).
Return ready-made wall body.
Parameters: |
|
---|
See utils.sphere‘s documentation for meaning of other parameters.
Mirror a sequence of 2d points around the x axis (changing sign on the y coord). The sequence should start up and then it will wrap from y downwards (or vice versa). If the last point’s x coord is zero, it will not be duplicated.
Get timestep accoring to the velocity of P-Wave propagation; computed from sphere radii, rigidities and masses.
Determination of time step according to Rayleigh wave speed of force propagation.
Return coordinates of box enclosing all bodies
Parameters: |
|
---|---|
Returns: | (lower corner, upper corner) as (Vector3,Vector3) |
Compute area of convex hull when when taking (swept) spheres crossing the plane at coord, perpendicular to axis.
Compute and return a table with per-particle stress tensors. Each tensor represents the average stress in one particle, obtained from the contour integral of applied load as detailed below. This definition is considering each sphere as a continuum. It can be considered exact in the context of spheres at static equilibrium, interacting at contact points with negligible volume changes of the solid phase (this last assumption is not restricting possible deformations and volume changes at the packing scale).
Proof:
First, we remark the identity: .
At equilibrium, the divergence of stress is null: . Consequently, after divergence theorem:
.
The last equality is implicitely based on the representation of external loads as Dirac distributions whose zeros are the so-called contact points: 0-sized surfaces on which the contact forces are applied, located at in the deformed configuration.
A weighted average of per-body stresses will give the average stress inside the solid phase. There is a simple relation between the stress inside the solid phase and the stress in an equivalent continuum in the absence of fluid pressure. For porosity , the relation reads:
.
Set translational and rotational velocities of all bodies to zero.
Return tuple of 2 same-length lists for coordinates and displacements (coordinate minus reference coordinate) along given axis (1st arg); if the Aabb=((x_min,y_min,z_min),(x_max,y_max,z_max)) box is given, only bodies within this box will be considered.
Create interaction between given bodies by hand.
Current engines are searched for IGeomDispatcher and IPhysDispatcher (might be both hidden in InteractionLoop). Geometry is created using force parameter of the geometry dispatcher, wherefore the interaction will exist even if bodies do not spatially overlap and the functor would return false under normal circumstances.
Warning
This function will very likely behave incorrectly for periodic simulations (though it could be extended it to handle it farily easily).
Compute the fabric tensor of the periodic cell. The original paper can be found in [Satake1982].
Parameters: |
|
---|
Flip periodic cell so that angles between axes and transformed axes are as small as possible. This function relies on the fact that periodic cell defines by repetition or its corners regular grid of points in
; however, all cells generating identical grid are equivalent and can be flipped one over another. This necessiatates adjustment of Interaction.cellDist for interactions that cross boundary and didn’t before (or vice versa), and re-initialization of collider. The flip argument can be used to specify desired flip: integers, each column for one axis; if zero matrix, best fit (minimizing the angles) is computed automatically.
In c++, this function is accessible as Shop::flipCell.
Warning
This function is currently broken and should not be used.
Find all interactions deriving from NormShearPhys that cross given plane and sum forces (both normal and shear) on them.
Parameters: |
|
---|
Get a list of body-ids, which contacts the given body.
Compute the total mass of spheres in the simulation (might crash for now if dynamic bodies are not spheres), mask parameter is considered
Compute the total volume of spheres in the simulation (might crash for now if dynamic bodies are not spheres), mask parameter is considered
Compute and return Love-Weber stress tensor:
, where the sum is over all interactions, with
the branch vector (joining centers of the bodies) and
is the contact force.
can be passed to the function. If it is not, it will be equal to one in non-periodic cases, or equal to the volume of the cell in periodic cases.
Compute viscoelastic interaction parameters from analytical solution of a pair spheres collision problem:
where ,
are normal elastic and viscous coefficients and
,
shear elastic and viscous coefficients. For details see [Pournin2001].
Parameters: |
|
---|---|
Returns: | dictionary with keys kn (the value of |
Change the size of spheres and sphere clumps by the multiplier. If updateMass=True, then the mass is updated. dynamicOnly=True is mandatory in many cases since in current implementation the function would crash on the non-spherical and non-dynamic bodies (e.g. facets, boxes, etc.)
Return center of inscribed circle for triangle given by its vertices v1, v2, v3.
Compute overall kinetic energy of the simulation as
For aspherical bodies, the inertia tensor is transformed to global frame, before multiplied by
, therefore the value should be accurate.
Return maximum overlap ration in interactions (with ScGeom) of two spheres. The ratio is computed as , where
is the current overlap distance and
,
are radii of the two spheres in contact.
Return list of ids for spheres (only) that are on extremal ends of the specimen along given axis; distFactor multiplies their radius so that sphere that do not touch the boundary coordinate can also be returned.
Compute overall stress tensor of the periodic cell decomposed in 2 parts, one contributed by normal forces, the other by shear forces. The formulation can be found in [Thornton2000], eq. (3):
where is the cell volume,
is “contact radius” (in our implementation, current distance between particle centroids),
is the normal vector,
is a vector perpendicular to
,
and
are norms of normal and shear forces.
Parameters: |
|
---|
Compute packing poro sity where
is overall volume and
is volume of spheres.
Parameters: | volume (float) – overall volume which must be specified for aperiodic simulations. For periodic simulations, current volume of the Cell is used. |
---|
Return True/False whether the point p is within box given by its min and max corners
Modify the friction value inside the material classes and existing contacts The friction for non-dynamic bodies is not modified.
Sets new vertices (in global coordinates) to given facet.
Set reference positions and orientations of all bodies equal to their current positions and orientations.
Shifts bodies listed in ids without updating their velocities.
Sum force magnitudes on given bodies (must have shape of the Facet type), considering only part of forces perpendicular to each facet’s face; if axis has positive value, then the specified axis (0=x, 1=y, 2=z) will be used instead of facet’s normals.
Return summary force on bodies with given ids, projected on the direction vector.
Sum forces and torques on bodies given in ids with respect to axis specified by a point axisPt and its direction axis.
Return summed forces on all interactions and average isotropic stiffness, as tuple (Vector3,float)
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.
Compute packing porosity where
is a specified volume (from start to end) and
is volume of voxels that fall inside any sphere. The calculation method is to divide whole volume into a dense grid of voxels (at given resolution), and count the voxels that fall inside any of the spheres. This method allows one to calculate porosity in any given sub-volume of a whole sample. It is properly excluding part of a sphere that does not fall inside a specified volume.
Parameters: |
|
---|
Set Shape::wire on all bodies to True, rendering them with wireframe only.
Set Shape::wire to True on non-spherical bodies (Facets, Walls).
Set Shape::wire on all bodies to False, rendering them as solids.