\( \usepackage{euler} % must be loaded before fontspec for the whole doc (below); this must be kept for pngmath, however \usepackage{hyperref} \usepackage{amsmath} \usepackage{amsbsy} %\usepackage{mathabx} \usepackage{underscore} \usepackage[all]{xy} % Metadata of the pdf output \hypersetup{pdftitle={Yade Documentation}} \hypersetup{pdfauthor={Smilauer, V., et al.}} \hypersetup{pdfkeywords={Discrete element method, granular materials, contact law, hydromechanical coupling}} % symbols \renewcommand{\mat}{\boldsymbol} \renewcommand{\vec}{\boldsymbol} \renewcommand{\tens}{\boldsymbol} %normalized and locfram here \def\normalized#1{\widehat{#1}} \def\locframe#1{\widetilde{#1}} % timestep \def\Dt{\Delta t} \def\Dtcr{\Dt_{\rm cr}} % algorithm complexity \def\bigO#1{{\mathcal{O}(#1)}} % variants for greek symbols \let\epsilon\varepsilon \let\theta\vartheta \let\phi\varphi % shorthands \let\sig\sigma \let\eps\epsilon % variables at different points of time \def\prev#1{#1^-} \def\pprev#1{#1^\ominus} \def\curr#1{#1^{\circ}} \def\nnext#1{#1^\oplus} \def\next#1{#1^+} % shorthands for geometry \def\currn{\curr{\vec{n}}} \def\currC{\curr{\vec{C}}} \def\uT{\vec{u}_T} \def\curruT{\curr{\vec{u}}_T} \def\prevuT{\prev{\vec{u}}_T} \def\currn{\curr{\vec{n}}} \def\prevn{\prev{\vec{n}}} % motion \def\pprevvel{\pprev{\dot{\vec{u}}}} \def\nnextvel{\nnext{\dot{\vec{u}}}} \def\curraccel{\curr{\ddot{\vec{u}}}} \def\prevpos{\prev{\vec{u}}} \def\currpos{\curr{\vec{u}}} \def\nextpos{\next{\vec{u}}} \def\curraaccel{\curr{\dot{\vec{\omega}}}} \def\pprevangvel{\pprev{\vec{\omega}}} \def\nnextangvel{\nnext{\vec{\omega}}} \def\loccurr#1{\curr{\locframe{#1}}} \def\numCPU{n_{\rm cpu}} \DeclareMathOperator{\Align}{Align} \DeclareMathOperator{\sign}{sgn} % sorting algorithms \def\isleq#1{\currelem{#1}\ar@/^/[ll]^{\leq}} \def\isnleq#1{\currelem{#1}\ar@/^/[ll]^{\not\leq}} \def\currelem#1{\fbox{$#1$}} \def\sortSep{||} \def\sortInv{\hbox{\phantom{||}}} \def\sortlines#1{\xymatrix@=3pt{#1}} \def\crossBound{||\mkern-18mu<} \)

# Yade wrapper class reference

## Bodies

### Body

### Shape

Inheritance graph of Shape.

class yade.wrapper.Box(inherits Shape → Serializable)
  property color

    Color for rendering (normalized RGB).

  dict((Serializable)arg1) → dict :

    Return dictionary of attributes.

  dispHierarchy((Shape)arg1[, (bool)names=True]) → list :

    Return list of dispatch classes (from down upwards), starting with the class instance itself, top-level indexable at last. If names is true (default), return class names rather than numerical indices.

  property dispIndex

    Return class index of this instance.

  property extents

    Half-size of the cuboid

  getVolume((Box)arg1) → float :

    Returns the shape volume.

  property highlight

    Whether this Shape will be highlighted when rendered.

  updateAttrs((Serializable)arg1, (dict)arg2) → None :

    Update object attributes from given dictionary

  property wire

    Whether this Shape is rendered using color surfaces, or only wireframe (can still be overridden by global config of the renderer).

### State

Inheritance graph of State.

### Material

Inheritance graph of Material.

### Bound

Inheritance graph of Bound.

## Interactions

### Interaction

### IGeom

Inheritance graph of IGeom.

### IPhys

Inheritance graph of IPhys.

## Global engines

### GlobalEngine

Inheritance graph of GlobalEngine, gray dashed classes are discussed in their own sections: Collider, PeriodicEngine, BoundaryController, FieldApplier.

### PeriodicEngine

Inheritance graph of PeriodicEngine.

### BoundaryController

Inheritance graph of BoundaryController.

### Collider

Inheritance graph of Collider.

### FieldApplier

Inheritance graph of FieldApplier.

## Partial engines

Inheritance graph of PartialEngine.

## Dispatchers

Inheritance graph of Dispatcher, gray dashed classes are discussed in their own sections: InternalForceDispatcher, BoundDispatcher, IGeomDispatcher, IPhysDispatcher, LawDispatcher.

## Functors

Inheritance graph of Functor, gray dashed classes are discussed in their own sections: IPhysFunctor, GlShapeFunctor, GlIGeomFunctor, InternalForceFunctor, GlStateFunctor, GlBoundFunctor, LawFunctor, IGeomFunctor, BoundFunctor, GlIPhysFunctor.

## Bounding volume creation

### BoundFunctor

Inheritance graph of BoundFunctor.

### BoundDispatcher

## Interaction Geometry creation

### IGeomFunctor

Inheritance graph of IGeomFunctor.

### IGeomDispatcher

## Interaction Physics creation

### IPhysFunctor

Inheritance graph of IPhysFunctor.

### IPhysDispatcher

## Constitutive laws

### LawFunctor

Inheritance graph of LawFunctor.

### LawDispatcher

## Internal forces

### InternalForceFunctor

Inheritance graph of InternalForceFunctor.

### InternalForceDispatcher

## Callbacks

Inheritance graph of IntrCallback.

## Preprocessors

Inheritance graph of FileGenerator.

## Rendering

### OpenGLRenderer

### GlShapeFunctor

Inheritance graph of GlShapeFunctor.

### GlStateFunctor

### GlBoundFunctor

Inheritance graph of GlBoundFunctor.

### GlIGeomFunctor

Inheritance graph of GlIGeomFunctor.

### GlIPhysFunctor

Inheritance graph of GlIPhysFunctor.

## Simulation data

### Omega

class yade.wrapper.Omega

  The whole YADE world made of one or, possibly, several scenes serving as independent simulations. The Omega instance is accessed as O, e.g., O.bodies

  addScene((Omega)arg1) → int :

    Add new scene to Omega, returns its number

  property bodies

    Bodies in the current simulation (container supporting index access by id and iteration)

  bufferFromIntrsct((Omega)arg1, (Subdomain)subdomain, (int)rank, (int)size, (bool)mirror) → object :

    returns a (char*) pointer to the underying buffer of intersections[rank], so that it can be overwritten. Size must be passed in advance. Pointer to mirrorIntersections[rank] is returned if mirror=True. Python syntax: bufferFromIntrsct(…)[:]=bytes(something)

  property cell

    Periodic Cell of the current scene (None if the scene is aperiodic).

  childClassesNonrecursive((Omega)arg1, (str)arg2) → list :

    Return list of all classes deriving from given class, as registered in the class factory

  disableGdb((Omega)arg1) → None :

    Revert SEGV and ABRT handlers to system defaults.

  property dt

    Current timestep (Δt) value. See dynDt for enabling/disabling automatic Δt updates through a TimeStepper.

  property dynDt

    Whether a TimeStepper (when present in O.engines) is used for dynamic Δt control.

  property dynDtAvailable

    Whether a TimeStepper is amongst O.engines, activated or not.

  property energy

    EnergyTracker of the current simulation. (meaningful only with O.trackEnergy)

  property engines

    List of engines in the simulation (corresponds to Scene::engines in C++ source code).

  exitNoBacktrace((Omega)arg1[, (int)status=0]) → None :

    Disable SEGV handler and exit, optionally with given status number.

  property filename

    Filename under which the current simulation was saved (None if never saved).

  property forceSyncCount

    Counter for number of syncs in ForceContainer, for profiling purposes.

  property forces

    ForceContainer (forces, torques) in the current simulation.

  property interactions

    Access to interactions of simulation, by using

    1. id’s of both Bodies of the interactions, e.g. `O.interactions[23,65]`

    2. iteration over the whole container:

           for i in O.interactions: print i.id1,i.id2

    Note

    Iteration silently skips interactions that are not real.

  intrsctToBytes((Omega)arg1, (Subdomain)subdomain, (int)rank, (bool)mirror) → object :

    returns a copy of intersections[rank] (a vector<int>) from a subdomain in the form of bytes. Returns a copy mirrorIntersections[rank] if mirror=True.

  isChildClassOf((Omega)arg1, (str)arg2, (str)arg3) → bool :

    Tells whether the first class derives from the second one (both given as strings).

  property iter

    Get current step number

  labeledEngine((Omega)arg1, (str)arg2) → object :

    Return instance of engine/functor with the given label. This function shouldn’t be called by the user directly; every ehange in O.engines will assign respective global python variables according to labels.

    For example:

    > O.engines=[InsertionSortCollider(label=’collider’)]

    > collider.nBins=5 # collider has become a variable after assignment to O.engines automatically

  load((Omega)arg1, (str)file[, (bool)quiet=False]) → None :

    Load simulation from file. The file should have been saved in the same version of Yade built or compiled with the same features, otherwise compatibility is not guaranteed. Compatibility may also be affected by different versions of external libraries such as Boost

  loadTmp((Omega)arg1[, (str)mark=''[, (bool)quiet=False]]) → None :

    Load simulation previously stored in memory by saveTmp. mark optionally distinguishes multiple saved simulations

  lsTmp((Omega)arg1) → list :

    Return list of all memory-saved simulations.

  property materials

    Shared materials; they can be accessed by id or by label

  property miscParams

    MiscParams in the simulation (Scene::mistParams), usually used to save serializables that don’t fit anywhere else, like GL functors

  property numThreads

    Get maximum number of threads openMP can use.

  pause((Omega)arg1) → None :

    Stop simulation execution. (May be called from within the loop, and it will stop after the current step).

  property periodic

    Get/set whether the current scene is periodic or not (True/False).

  plugins((Omega)arg1) → list :

    Return list of all plugins registered in the class factory.

  property realtime

    Return clock (human world) time the simulation has been running, in seconds.

  reload((Omega)arg1[, (bool)quiet=False]) → None :

    Reload current simulation

  reset((Omega)arg1) → None :

    Reset simulations completely (including another scenes!).

  resetAllScenes((Omega)arg1) → None :

    Reset all scenes.

  resetCurrentScene((Omega)arg1) → None :

    Reset current scene.

  resetThisScene((Omega)arg1) → None :

    Reset current scene.

  resetTime((Omega)arg1) → None :

    Reset simulation time: step number, virtual and real time. (Doesn’t touch anything else, including timings).

  run((Omega)arg1[, (int)nSteps=-1[, (bool)wait=False]]) → None :

    Run the simulation. nSteps how many steps to run, then stop (if positive); wait will cause not returning to python until simulation will have stopped.

  runEngine((Omega)arg1, (Engine)arg2) → None :

    Run given engine exactly once; simulation time, step number etc. will not be incremented (use only if you know what you do).

  property running

    Whether background thread is currently running a simulation.

  save((Omega)arg1, (str)file[, (bool)quiet=False]) → None :

    Save current simulation to file (should be .xml or .xml.bz2 or .yade or .yade.gz). .xml files are bigger than .yade, but can be more or less easily (due to their size) opened and edited, e.g. with text editors. .bz2 and .gz correspond both to compressed versions. There are software requirements for successful reloads, see O.load.

  saveTmp((Omega)arg1[, (str)mark=''[, (bool)quiet=False]]) → None :

    Save simulation to memory (disappears at shutdown), can be loaded later with loadTmp. mark optionally distinguishes different memory-saved simulations.

  sceneToString((Omega)arg1) → object :

    Return the entire scene as a string. Equivalent to using O.save(…) except that the scene goes to a string instead of a file. (see also stringToScene())

  property speed

    Return current calculation speed [iter/sec].

  step((Omega)arg1) → None :

    Advance the simulation by one step. Returns after the step will have finished.

  property stopAtIter

    Get/set number of iteration after which the simulation will stop.

  property stopAtTime

    Get/set time after which the simulation will stop.

  stringToScene((Omega)arg1, (str)arg2[, (str)mark='']) → None :

    Load simulation from a string passed as argument (see also sceneToString).

  property subStep

    Get the current subStep number (only meaningful if O.subStepping==True); -1 when outside the loop, otherwise either 0 (O.subStepping==False) or number of engine to be run (O.subStepping==True)

  property subStepping

    Get/set whether subStepping is active.

  switchScene((Omega)arg1) → None :

    Switch to alternative simulation (while keeping the old one). Calling the function again switches back to the first one. Note that most variables from the first simulation will still refer to the first simulation even after the switch (e.g. b=O.bodies[4]; O.switchScene(); [b still refers to the body in the first simulation here])

  switchToScene((Omega)arg1, (int)arg2) → None :

    Switch to defined scene. Default scene has number 0, other scenes have to be created by addScene method.

  property tags

    Tags (string=string dictionary) of the current simulation (container supporting string-index access/assignment)

  property thisScene

    Return current scene’s id.

  property time

    Return virtual (model world) time of the simulation.

  property timingEnabled

    Globally enable/disable timing services (see documentation of the timing module).

  tmpFilename((Omega)arg1) → str :

    Return unique name of file in temporary directory which will be deleted when yade exits.

  tmpToFile((Omega)arg1, (str)fileName[, (str)mark='']) → None :

    Save XML of saveTmp’d simulation into fileName.

  tmpToString((Omega)arg1[, (str)mark='']) → str :

    Return XML of saveTmp’d simulation as string.

  property trackEnergy

    When energy tracking is enabled or disabled in this simulation.

  wait((Omega)arg1) → None :

    Don’t return until the simulation will have been paused. (Returns immediately if not running).

### BodyContainer

class yade.wrapper.BodyContainer
  __init__((object)arg1, (BodyContainer)arg2) → None
  addToClump((BodyContainer)arg1, (object)arg2, (int)arg3[, (int)discretization=0]) → None :

    Add body b (or a list of bodies) to an existing clump c. c must be clump and b may not be a clump member of c. Clump masses and inertia are adapted automatically (for details see clump()).

    See examples/clumps/addToClump-example.py for an example script.

    Note

    If b is a clump itself, then all members will be added to c and b will be deleted. If b is a clump member of clump d, then all members from d will be added to c and d will be deleted. If you need to add just clump member b, release this member from d first.

  append((BodyContainer)arg1, (Body)arg2) → int :

    Append one Body instance, return its id.

    append( (BodyContainer)arg1, (object)arg2) -> object :

      Append list of Body instance, return list of ids

  appendClumped((BodyContainer)arg1, (object)arg2[, (int)discretization=0]) → tuple :

    Append given list of bodies as a clump (rigid aggregate); returns a tuple of `(clumpId,[memberId1,memberId2,...])`. Clump masses and inertia are computed automatically depending upon discretization (for details see clump()).

  clear((BodyContainer)arg1) → None :

    Remove all bodies (interactions not checked)

  clump((BodyContainer)arg1, (object)arg2[, (int)discretization=0]) → int :

    Clump given bodies together (creating a rigid aggregate); returns `clumpId`. A precise definition of clump masses and inertia when clump members overlap requires spherical members together with discretization>0 and is achieved in this case by integration/summation over mass points using a regular grid of cells (grid cells length is defined as \(L_{min}/discretization\), where \(L_{min}\) is the minimum length of an Axis-Aligned Bounding Box. If *discretization*<=0 sum of inertias from members is simply used, which is faster but accurate only for non-overlapping members).

  deleteClumpBody((BodyContainer)arg1, (Body)arg2) → None :

    Erase clump member.

  deleteClumpMember((BodyContainer)arg1, (Body)arg2, (Body)arg3) → None :

    Erase clump member.

  property enableRedirection

    let collider switch to optimized algorithm with body redirection when bodies are erased - true by default

  erase((BodyContainer)arg1, (int)arg2[, (bool)eraseClumpMembers=0]) → bool :

    Erase body with the given id; all interaction will be deleted by InteractionLoop in the next step. If a clump is erased use O.bodies.erase(clumpId,True) to erase the clump AND its members.

  getRoundness((BodyContainer)arg1[, (list)excludeList=[]]) → float :

    Returns roundness coefficient RC = R2/R1. R1 is the equivalent sphere radius of a clump. R2 is the minimum radius of a sphere, that imbeds the clump. If just spheres are present RC = 1. If clumps are present 0 < RC < 1. Bodies can be excluded from the calculation by giving a list of ids: O.bodies.getRoundness([ids]).

    See examples/clumps/replaceByClumps-example.py for an example script.

  insertAtId((BodyContainer)arg1, (Body)arg2, (int)insertatid) → int :

    Insert a body at theid, (no body should exist in this id)

  releaseFromClump((BodyContainer)arg1, (int)arg2, (int)arg3[, (int)discretization=0]) → None :

    Release body b from clump c. b must be a clump member of c. Clump masses and inertia are adapted automatically (for details see clump()).

    See examples/clumps/releaseFromClump-example.py for an example script.

    Note

    If c contains only 2 members b will not be released and a warning will appear. In this case clump c should be erased.

  replace((BodyContainer)arg1, (object)arg2) → object
  replaceByClumps((BodyContainer)arg1, (list)arg2, (object)arg3[, (int)discretization=0]) → list :

    Replace spheres by clumps using a list of clump templates and a list of amounts; returns a list of tuples: `[(clumpId1,[memberId1,memberId2,...]),(clumpId2,[memberId1,memberId2,...]),...]`. A new clump will have the same volume as the sphere, that was replaced. Clump masses and inertia are adapted automatically (for details see clump()).

    > O.bodies.replaceByClumps( [utils.clumpTemplate([1,1],[.5,.5])] , [.9] ) #will replace 90 % of all standalone spheres by ‘dyads’

    See examples/clumps/replaceByClumps-example.py for an example script.

  subdomainBodies((BodyContainer)arg1) → object :

    id’s of bodies with bounds in MPI subdomain

  updateClumpProperties((BodyContainer)arg1[, (list)excludeList=[][, (int)discretization=5]]) → None :

    Manually force Yade to update clump properties mass, volume and inertia (for details of ‘discretization’ value see clump()). Can be used, when clumps are modified or erased during a simulation. Clumps can be excluded from the calculation by giving a list of ids: O.bodies.updateProperties([ids]).

  property useRedirection

    true if the scene uses up-to-date lists for boundedBodies and realBodies; turned true automatically 1/ after removal of bodies if enableRedirection=True , and 2/ in MPI execution. (auto-updated)

### InteractionContainer

class yade.wrapper.InteractionContainer

  Access to interactions of simulation, by using

  1. id’s of both Bodies of the interactions, e.g. `O.interactions[23,65]`

  2. iteraction over the whole container:

         for i in O.interactions: print i.id1,i.id2

  Note

  Iteration silently skips interactions that are virtual i.e. not real.

  __init__((object)arg1, (InteractionContainer)arg2) → None
  all((InteractionContainer)arg1[, (bool)onlyReal=False]) → list :

    Return list of all interactions. Virtual interaction are filtered out if onlyReal=True, else (default) it dumps the full content.

  clear((InteractionContainer)arg1) → None :

    Remove all interactions, and invalidate persistent collider data (if the collider supports it).

  countReal((InteractionContainer)arg1) → int :

    Return number of interactions that are real.

  erase((InteractionContainer)arg1, (int)arg2, (int)arg3) → None :

    Erase one interaction, given by id1, id2 (internally, `requestErase` is called – the interaction might still exist as potential, if the Collider decides so).

  eraseNonReal((InteractionContainer)arg1) → None :

    Erase all interactions that are not real .

  has((InteractionContainer)arg1, (int)id1, (int)id2[, (bool)onlyReal=False]) → bool :

    Tell if a pair of ids id1, id2 corresponds to an existing interaction (real or not depending on onlyReal)

  nth((InteractionContainer)arg1, (int)arg2) → Interaction :

    Return n-th interaction from the container (usable for picking random interaction). The virtual interactions are not reached.

  property serializeSorted

    None( (yade.wrapper.InteractionContainer)arg1) -> bool

  withBody((InteractionContainer)arg1, (int)arg2) → list :

    Return list of real interactions of given body.

  withBodyAll((InteractionContainer)arg1, (int)arg2) → list :

    Return list of all (real as well as non-real) interactions of given body.

### ForceContainer

class yade.wrapper.ForceContainer
  __init__((object)arg1, (ForceContainer)arg2) → None
  addF((ForceContainer)arg1, (int)id, (yade._minieigenHP.Vector3)f[, (bool)permanent=False]) → None :

    Apply force on body (accumulates). The force applies for one iteration, then it is reset by ForceResetter. # permanent parameter is deprecated, instead of addF(…,permanent=True) use setPermF(…).

  addT((ForceContainer)arg1, (int)id, (yade._minieigenHP.Vector3)t[, (bool)permanent=False]) → None :

    Apply torque on body (accumulates). The torque applies for one iteration, then it is reset by ForceResetter. # permanent parameter is deprecated, instead of addT(…,permanent=True) use setPermT(…).

  f((ForceContainer)arg1, (int)id[, (bool)sync=False]) → yade._minieigenHP.Vector3 :

    Resultant force on body, excluding gravity. For clumps in openMP, synchronize the force container with sync=True, else the value will be wrong.

  getPermForceUsed((ForceContainer)arg1) → bool :

    Check wether permanent forces are present.

  m((ForceContainer)arg1, (int)id[, (bool)sync=False]) → yade._minieigenHP.Vector3 :

    Deprecated alias for t (torque).

  permF((ForceContainer)arg1, (int)id) → yade._minieigenHP.Vector3 :

    read the value of permanent force on body (set with setPermF()).

  permT((ForceContainer)arg1, (int)id) → yade._minieigenHP.Vector3 :

    read the value of permanent torque on body (set with setPermT()).

  reset((ForceContainer)arg1[, (bool)resetAll=True]) → None :

    Reset the force container, including user defined permanent forces/torques. resetAll=False will keep permanent forces/torques unchanged.

  setPermF((ForceContainer)arg1, (int)arg2, (yade._minieigenHP.Vector3)arg3) → None :

    set the value of permanent force on body.

  setPermT((ForceContainer)arg1, (int)arg2, (yade._minieigenHP.Vector3)arg3) → None :

    set the value of permanent torque on body.

  property syncCount

    Number of synchronizations of ForceContainer (cummulative); if significantly higher than number of steps, there might be unnecessary syncs hurting performance.

  t((ForceContainer)arg1, (int)id[, (bool)sync=False]) → yade._minieigenHP.Vector3 :

    Torque applied on body. For clumps in openMP, synchronize the force container with sync=True, else the value will be wrong.

### MaterialContainer

class yade.wrapper.MaterialContainer

  Container for Materials. A material can be accessed using

  1. numerical index in range(0,len(cont)), like cont[2];

  2. textual label that was given to the material, like cont[‘steel’]. This entails traversing all materials and should not be used frequently.

  __init__((object)arg1, (MaterialContainer)arg2) → None
  append((MaterialContainer)arg1, (Material)arg2) → int :

    Add new shared Material; changes its id and return it.

    append( (MaterialContainer)arg1, (object)arg2) -> object :

      Append list of Material instances, return list of ids.

  index((MaterialContainer)arg1, (str)arg2) → int :

    Return id of material, given its label.

### Scene

### Cell

## Other classes

class yade.wrapper.TimingDeltas
  property data

    Get timing data as list of tuples (label, execTime[nsec], execCount) (one tuple per checkpoint)

  reset((TimingDeltas)arg1) → None :

    Reset timing information

class yade.wrapper.Serializable
  dict((Serializable)arg1) → dict :

    Return dictionary of attributes.

  updateAttrs((Serializable)arg1, (dict)arg2) → None :

    Update object attributes from given dictionary