woo.utils

Heap of functions that don’t (yet) fit anywhere else.

woo.utils.capsule(center, radius, shaft, ori=Quaternion((1, 0, 0), 0), fixed=False, color=None, wire=False, mat=<function defaultMaterial>, mask=5)

Return a ready-made capsule particle.

woo.utils.cone(vertices, radii, *, fixed=True, wire=False, color=None, angVel=None, mat=<function defaultMaterial>, visible=True, mask=3)

Create cone with given parameters.

woo.utils.defaultEngines(damping=0.0, gravity=None, verletDist=- 0.05, kinSplit=False, dontCollect=False, noSlip=False, noBreak=False, cp2=None, law=None, model=None, collider='sap', grid=None, dynDtPeriod=100, cpKw={}, lawKw={})

Return default set of engines, suitable for basic simulations during testing.

woo.utils.defaultMaterial()

Return default material, when creating particles with woo.utils.sphere and friends and material is unspecified. This function returns FrictMat(density=1e3,young=1e7,ktDivKn=.2,tanPhi=tan(.5)).

woo.utils.ellipsoid(center, semiAxes, ori=Quaternion((1, 0, 0), 0), angVel=None, color=None, mat=<function defaultMaterial>, fixed=False, wire=False, visible=True, mask=5, **kw)

Return an woo.dem.Ellipsoid particle.

woo.utils.ensureDir(d, msg='Creating directory %s')

Ensure that directory d exists. If d is empty, return immediately (signifies usually the current directory). Otherwise try to create the directory. msg is an optional message to be printed to stdout only when something is actually done, and must include %s which will be replaced by the directory.

woo.utils.ensureWriteableDir(d)

Make sure given directory is writeable; raise exception (IOError) if not.

woo.utils.facet(vertices, fakeVel=None, halfThick=0.0, fixed=True, wire=True, color=None, highlight=False, mat=<function defaultMaterial>, visible=True, mask=3, flex=None, __class=<class 'woo.dem.Facet'>)

Create facet with given parameters.

Parameters

• vertices ([Vector3,Vector3,Vector3]) – coordinates of vertices in the global coordinate system.

• wire (bool) – if True, facets are shown as skeleton; otherwise facets are filled

See woo.utils.sphere’s documentation for meaning of other parameters.

woo.utils.find_executable(ex)

Thin wrapper for find_executable, using either shutil.which or distutils.spawn.find_executable.

woo.utils.fixWindowsPath(p)

woo.utils.freecadExport(S, out, mask=0)

woo.utils.htmlReport(S, repFmt, headline, afterHead='', figures=[], dialect=None, figFmt=None, svgEmbed=False, show=False, hideWooExtra=False)

Generate (X)HTML report for simulation.

Parameters

• S – Scene object; must contain Scene.pre

• repFmt – format for the output file; will be expanded using Scene.tags; it should end with .html or .xhtml.

• headline – title of the report, used as HTML title and the first <h1> heading.

• afterHead – contents (XHTML fragment) to be added verbatim after the header (title, woo config table, preprocessor parameters)

• figs –

  figures included in the report; they are either embedded (SVG, optionally ) or saved to files in the same directory as the report, using its name as prefix, and referenced via relative links from the XHTML. Figures are given as list of 2- or 3-tuples, where each item contains:

  1. name of the figure (will generate a <h2> heading)

  2. figure object (Matplotlib figure object)

  3. optionally, format to save the figure to (svg, png, …)

• figFmt – format of figures, if the format is not specified by the figure itself; if None, choose format appropriate for given dialect (png for html4, svg for html5 and xhtml)

• dialect – one of “xhtml”, “html5”, “html4”; if not given (None), selected from file suffix (.html for html4, .xhtml for xhtml). html4 will save figures as PNG (even if something else is specified) so that the resulting file is easily importable into LibreOffice (which does not import HTML with SVG correctly now).

• svgEmbed – don’t save SVG as separate files, embed them in the report instead.

• show – open the report in browser via the webbrowser module, unless running in batch.

• hideWooExtra – don’t show wooExtra.* modules in object names or URLs

Returns

(filename of the report, list of external figures)

woo.utils.htmlReportHead(S, headline, dialect='xhtml', repBase='', hideWooExtra=False)

Return (X)HTML fragment for simulation report: (X)HTML header, title, Woo logo, configuration and preprocessor parameters.

In order to obtain a well-formed XHTML document, don’t forget to add ‘</body></html>’.

woo.utils.importNmesh(filename, mat, mask, trsf=None, dem=None, surf=True, surfMat=None, surfMask=None, surfHalfThick=0.0)

Import nmesh file, text format written by Netgen. All nodes are created with woo.dem.DemData.blocked equal to XYZ (no rotations, but all translations allowed); if some of them are to be fixed, this must be done by the user after calling the function. Tetrahedra mass is lumped onto nodes. Thickness of surface triangles (if any) is ignored for mass lumping.

Parameters

• mat – material for volume (woo.fem.Tet4) elements.

• mask – woo.dem.Particle.mask for new volume elements.

• trsf – callable for transforming input-file vertex coordinate to the simulation space.

• dem – a woo.dem.DemField instance; if given, nodes and particles will be added to this DemField.

• surf – create surface triangulation, for collisions.

• surfMat – material for surface (woo.dem.Facet); if None, mat is used.

• surfMask – mask for surface; if None, mask is used.

• surfHalfThick – woo.dem.Facet.halfThick for the surface (must be positive for collisions between two triangulated surfaces).

Returns

([Node,Node,…],[Particle,Particle,…])

woo.utils.infCylinder(position, radius, axis, glAB=None, fixed=True, mass=0, color=None, wire=False, angVel=None, mat=<function defaultMaterial>, mask=5)

Return a ready-made infinite cylinder particle.

woo.utils.makeLog(name)

woo.utils.makeVideo(frameSpec, out, renameNotOverwrite=True, fps=24, kbps=15000, holdLast=- 0.5, open=False)

Create a video from external image files using mencoder, avconv or ffmpeg (whichever is found on the system). Encodes using the default mencoder codec (mpeg4), two-pass with mencoder and one-pass with avconv, running multi-threaded with number of threads equal to number of OpenMP threads allocated for Woo.

Some out extensions (.gif, .mng) will call ImageMagick (convert; likely not available under Windows) to create animated image instead of video file.

Parameters

• frameSpec – wildcard | sequence of filenames. If list or tuple, filenames to be encoded in given order; otherwise wildcard understood by mencoder’s mf:// URI option (shell wildcards such as /tmp/snap-*.png or and printf-style pattern like /tmp/snap-%05d.png), if using mencoder, or understood by avconv or ffmpeg if those are being used.

• out (str) – file to save video into

• renameNotOverwrite (bool) – if True, existing same-named video file will have -number appended; will be overwritten otherwise.

• fps (int) – Frames per second (-mf fps=…)

• kbps (int) – Bitrate (-lavcopts vbitrate=…) in kb/s (ignored for animated images)

• holdLast – Repeat the last frame this many times; if negative, it means seconds and will be converted to frames according to fps. This option is not applicable if frameSpec is a wildcard (as opposed to a list of images).

• open – Open the resulting movie file with the default system program for that type of file.

Note

avconv and ffmpeg need symlinks, which are not available under Windows.

woo.utils.membrane(*args, **kw)

woo.utils.readParamsFromTable(*args, **kw)

woo.utils.rod(vertices, radius, fixed=True, wire=True, color=None, mat=<function defaultMaterial>, visible=True, mask=3, __class=<class 'woo.dem.Rod'>)

Create Rod with given parameters:

Parameters

• vertices – endpoints given as coordinates (Vector3) or nodes

• radius – radius of the rod

• wire – render as wire by default

• color – color as scalar (0…1); if not given, random color is assigned

• mat – material; if not given, default material is assigned

• visible –

• mask –

woo.utils.runAllPreprocessors()

Run all preprocessors with default parameters, and run the very first step of their simulation.

woo.utils.runPreprocessorInBatch(*args, **kw)

woo.utils.runningInBatch()

woo.utils.sphere(center, radius, mat=<function defaultMaterial>, fixed=False, wire=False, color=None, highlight=False, mask=5, vel=None)

Create sphere with given parameters; mass and inertia computed automatically.

Parameters

• center (Vector3) – center

• radius (float) – radius

• float-or-None – particle’s color as float; random color will be assigned if None.

• mat –

  specify woo.dem.Particle.material; different types are accepted:

  • woo.dem.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)

• mask (int) – woo.dem.Particle.mask for the body

Returns

Particle instance with desired characteristics.

Instance of material can be given:

>>> from woo import utils
>>> s1=utils.sphere((0,0,0),1,wire=False,color=.7,mat=ElastMat(young=30e9,density=2e3))
>>> s1.shape.wire
False
>>> s1.shape.color
0.7
>>> s1.mat.density
2000.0

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 woo.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())
...
>>> s2=utils.sphere([0,2,0],1,mat=matFactory)
>>> s3=utils.sphere([1,2,0],1,mat=matFactory)

woo.utils.spherePWaveDt(radius, density, young)

Compute P-wave critical timestep for a single (presumably representative) sphere, using formula for P-Wave propagation speed \(\Delta t_{c}=\frac{r}{\sqrt{E/\rho}}\). If you want to compute minimum critical timestep for all spheres in the simulation, use woo.utils.pWaveDt instead.

>>> spherePWaveDt(1e-3,2400,30e9)
2.8284271247461903e-07

woo.utils.svgFileFragment(filename)

Return fragment beginning with <svg till the end of given filename. Those data may be used for embedding SVG in other formats, such as XHTML.

woo.utils.tesselatePolyline(l, maxDist)

Return polyline tesselated so that distance between consecutive points is no more than maxDist. l is list of points (Vector2 or Vector3).

woo.utils.tet4(*args, **kw)

woo.utils.tetra(vertices, fixed=True, wire=True, color=None, highlight=False, mat=<function defaultMaterial>, visible=True, mask=3, __class=<class 'woo.fem.Tetra'>)

Create tetrahedral particle

woo.utils.truss(*args, **kw)

woo.utils.unbalancedEnergy(S)

woo.utils.vmData()

Return memory usage data from Linux’s /proc/[pid]/status, line VmData.

woo.utils.waitIfBatch()

woo.utils.wall(position, axis, sense=0, glAB=None, fixed=True, mass=0, color=None, mat=<function defaultMaterial>, visible=True, mask=3)

Return ready-made wall body.

Parameters

• position (float-or-Vector3-or-Node) – center of the wall. If float, it is the position along given axis, the other 2 components being zero

• axis (∈{0,1,2}) – orientation of the wall normal (0,1,2) for x,y,z (sc. planes yz, xz, xy)

• sense (∈{-1,0,1}) – sense in which to interact (0: both, -1: negative, +1: positive; see woo.dem.Wall)

See woo.utils.sphere’s documentation for meaning of other parameters.

woo.utils.wallBox(box, which=(1, 1, 1, 1, 1, 1), **kw)

Return box delimited by walls, created by woo.dem.Wall.make, which receives most arguments. Wall.glAB are computed automatically so that walls visually end at the edges.

Note

Since walls are infinite, they will still interact with other particle beyond this box; use woo.triangulated.box for true box with arbitrary orientation.

Parameters

• box – axis-aligned box determining positions of walls.

• which – determines which of the 6 walls are created (boolean values), in the order -x, -y, -z, +x, +y, +z. For instance, to create a box which does not have the top, say which=(1,1,1,1,1,0)).

Returns

list of Particle objects.

woo.utils.xMirror(half)

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.

woo._utils2

Note

This module is imported into the woo.utils module automatically; refer to its objects through woo.utils.

woo._utils2.bestFitCompliance()

Compute compliance based on best-fit hypothesis, using the paper [Liao1997], equations (30) and (28,31).

woo._utils2.boxPsd()

Compute Particle size distribution in given box (min,max) or in the whole simulation, if box is not specified; list of couples (diameter,passing) is returned; with unzip, tuple of two sequences, diameters and passing values, are returned.

woo._utils2.contactCoordQuantiles()

Return list of (local) contact z-coordinates for given quantile values; if node is omited, global coordinates are used; box is specified in node-local coordinates; if box is empty (default-initialized), all contacts are included.

woo._utils2.coordNumber()

Return coordination number of the sampled area given by optional local coordinates (node) and box (which is in local coordinates if node is given and global if not); if mask is non-zero, particles without matching mask are ignored. See yade.utils.avgNumInterations for formulas on skipping free particles (TODO: copy those over).

Warning

Clumps are not handled properly by this function and an exception will be raised if they are encountered.

woo._utils2.createContacts()

Create contacts between given DEM particles.

Current engines are searched for woo.dem.ContactLoop, unless geomFunctors and physFunctors are given. force will make woo.dem.CGeomFunctor acknowledge the contact even if particles don’t touch geometrically.

Warning

This function will very likely behave incorrectly for periodic simulations (though it could be extended it to handle it farily easily).

woo._utils2.facetsPlaneIntersectionSegments()

Return list of points, where consecutive pairs are segment where facets were intersecting plane given by pt and normal.

woo._utils2.flipCell()

Flip periodic cell (by default to the state the closest to the canonical (orthogonal) state) without affecting contacts.

woo._utils2.importSTL()

Return list of particles (with the Facet shape, or Membrane if flex is True) imported from given STL file. Both ASCII and binary formats are supported; COLOR and MATERIAL values in the binary format, if given and with readColors, are read but currently ignored (they should translate to the woo.dem.Shape.color scalar − that color difference would be preserved, but not the color as such), and a warning is issued. scale, shift and ori are applied in this order before nodal coordinates are computed. The threshold value serves for merging incident vertices: if positive, it is distance in the STL space (before scaling); if negative, it is relative to the max bounding box size of the entire mesh. maxBox, if positive, will cause any faces to be tesselated until the smallest dimension of its bbox (in simulation space) is smaller than maxBox; this is to avoid many spurious (potential) contacts with large obliquely-oriented faces.

If thickness is non-zero, all created particles (Facet or Membrane) will have their halfThick set, and node’s mass and inertia will be computed automatically.

woo._utils2.mapColor()

Map scalar to color (as 3-tuple). See woo.core.Master.cmap, woo.core.Master.cmaps to set colormap globally.

woo._utils2.muStiffnessScaling()

Compute stiffness scaling parameter relating continuum-like stiffness with packing stiffness; see ‘Particle assembly with cross-anisotropic stiffness tensor’ for details. With skipFloaters, ignore contacts where any of the two contacting particlds has only one real contact (thus not contributing to the assembly stability).

woo._utils2.outerTri2Dist()

Return signed distance of point pt in triangle A,B,C. The result is distance of point pt to the closest point on triangle A,B,C. The distance is negative is pt is inside, 0 if exactly on the triangle and positive outside. Signedness supposes that A,B,C are given anti-clockwise; otherwise, the sign will be reversed

woo._utils2.pWaveDt()

Get timestep accoring to the velocity of P-Wave propagation; computed from sphere radii, rigidities and masses.

woo._utils2.particleStress()

Return tuple of normal and shear stresses acting on given particle; raise exception for non-spherical particles

woo._utils2.porosity()

Return porosity for given box (in local coordinates, if node is not None), considering (only) spherical particles of which centroid is in the box.

woo._utils2.psd()

Return PSD of given particles (given as array of Vector2, where each Vector2 specifies diameter and mass) as arrays of diameters and passing; the semantics is the same as for woo.dem.BoxDeleter.psd and woo.dem.ParticleGenerator.psd.

woo._utils2.reactionInPoint()

Compute force and torque in point pt generated by forces on particles matching mask in DemField dem. Multinodal particles (such as facets) usually don’t nodal forces evaluated; their contacts are traversed and contact reaction computed directly if multinodal is True (in that case, multinodal-multinodal contacts should not be present at all). Return tuple (force,torque,N), where N is the number of particles matched by mask.

woo._utils2.stressStiffnessWork()

Compute stress and stiffness tensors, and work increment of current velocity gradient (nan for aperiodic simulations); returns tuple (stress, stiffness, work), where stress and stiffness are in Voigt notation. skipMultinodal skips all contacts involving particles with multiple nodes, where stress & stiffness values can be determined only by In2 functors.

woo._utils2.unbalancedForce()

Compute the ratio of mean (or maximum, if useMaxForce) summary force on bodies and mean force magnitude on interactions. It is an adimensional measure of staticity, which approaches zero for quasi-static states.

woo._utils2.vtkExportTraces()

Export traces of existing spheroid particles to VTK file, for visualization in Paraview.

Tip

Report issues or inclarities to github.