From YADE

Future development is tracked at http://blueprints.launchpad.net/yade

Next YADE release will have names changed according to presented below scheme. This is a result of lenghty discussions and the names are final - they are already in a submitted article about YADE. Download short summary in pdf file

Also see the current development schedule.

[edit] New names for core classes

Proposed new names for the most important classes in the project.

Current name	New name	3 letter name	Meaning
	`BodyState`	`Bst`	information about a body that changes during the simulation process and is different for each instance of a body in the simulation, like position, velocity, acceleration and mass, inertia
	`BodyStateConstraints`	`Bsc`	information about constraints imposed on a body state, like disallowing to change body's position in z direction, or exceeding a velocity or y position a given maximum limit, a constrained value can be either kept at limiting value, or could decide that body must be deleted (like maximum strain, or body ran out of the simulation edges). This information is respected by engines when the BodyExternalVariables are used to calculate a BodyState for the next execution of simulation loop. Usually a big number of bodies will use the same constraints, and even bigger will not use constraints, thus the count of instances of this class will be much smaller than total count of bodies.
`PhysicalParameters`	`BodyConstitutiveParameters`	`Bcp`	information about a body that usually does not change during the simulation and is the same for many instances of bodies. For example whole simulation of reinforced concrete will need only two instances of this class: one for concrete, second for reinforcement. It's intended to be an information used by constitutive laws, like stiffness or cohesion
`GeometricalModel`	`BodyShape`	`Bsh`	The idealized shape of a body that we want to simulate: it is used to create a simplified shape, and for display
`InteractingGeometry`	`BodySimplifiedShape`	`Bss`	a shape of the body used for performing the actual simulation, may be different from idealized shape, because it's merely its represntstation used for the prupose of simulation
`BoundingVolume`	`BodyBoundingVolume`	`Bbv`	a bounding volume is used to detect potential interaction between bodies, usually is built from information stored inside simplified shape
`InteractionGeometry`	`InteractionState`	`Ist`	information about an interaction happenning between bodies which changes while the interaction evolves during the simulation, like penetration depth or shearing force
`InteractionPhysics`	`InteractionConstitutiveParameters`	`Icp`	information about an interaction happening between bodies which usually does not change during the simulation, even when bodies disconnect and reconnect again. Like contact stiffness
	`InteractionShape`	`Ish`	if an interaction can have an idealized shape representation, this class is for it, like a water meniscus between two spheres in cohesive interaction caused by water.
	`OutputData`^[1]	`Odt`	If you need some information which cannot be directly read from the classes mentioned above, but you need to calculate something and store it somewhere for further reading, use this class. The engines of simulation loop usually will not read from this class, it is rather to store some (final) results needed from the simulation
`PhysicalAction`	`BodyExternalVariables`	`Bex`	It is a complementary information about a body, which usually sums the effect of all physical actions on a body. This information most often is an intermediate stage that is used to calculate future values (for the next execution of simulation loop) of data stored in BodyState. For example a sum of forces and moments acting on a sphere (they will be used to change body's position and orientation which are stored in BodyState)
`Engine`	`Engine`	`Egi`	Anything that is reading or writing into the simulation data while performing some computational operations, it is a basic building block of the simulation loop. The engine is not supposed to store any information related to calculated model, only information that configures the way in which the engine runs. Also see note at `EngineFunctor`
`MetaEngine`	`EngineDispatcher`	`Egd`
`EngineUnit`	`EngineFunctor`	`Egf`	Both `Engine` and `Enginefunctor` will receive information about current iteration, so they could perform something during only a single iteration on all bodies (eg. on the first call to prepare them for further calculations). It must be done because the loop has to be outside - to allow parallelization of the loop
`DeuxExMachina`	`EgiConditionApplier`	`Econ`
`InteractionSolver`	`EgiConstitutiveLaw`	`Elaw`
`BroadInteractor`	`EgiBoundingVolumeCollider`	`Ebvc`
`DataRecorder`	`EgiDataProcessor`	`Edat`
`MetaBody`	`Model`	^[2]	This class contains everything inside: the data classes for bodies, interactions, and also a simulation loop with engines inside
`Body`			class is removed, to allow reorganization of containers

The 3 letter name: is used to prefix each class name in yade, to indicate the ROOT of inheritance tree. Yade developers will need to remember those short name versions - thus the intention is to make them easy to remember.

^[1] - an idea is to add a class that is used specifically to record and calculate some information about happening simulation (and have an GLDraw handler also, just like all the other classes have it and can be drawn on the screen). It's an intermediate stage between reading directly from the simulation to have results - a stage to process this information a bit ans tore it here.

^[2] - you never derive from this class

[edit] Model and its containers

Since all the data is to be stored inside Model we need to say something about its containers. First of all:

Groups
1. To simplify managment of data a boost::bimap<X,Y> will be used. This container works in both directions like std::map<X,Y> and std::map<Y,X>, where: X is a body_id number while Y is a set of group_ids to which it belongs, like std::set<group_id>.
2. body_id numbers are positive, group_id numbers are negative. Number zero means empty as in not a body and not a group. Either int, or long int (even short int ;) can be used here for the body and group ids.
3. To help humans in identifying stuff the ids can be named with std::string but don't need to. For this, we use another container of type boost::bimap<Z,std::string>, where Z can be either a body_id or a group_id, which is in fact a (maybe long) int. using boost::bimap allows to identify ids in both directions - either with a name, or with an id number.
Body data classes
1. Each Body* data class listed above has dedicated, separate, container for it. We got a container for BodyState, another container for BodyStateConstraints, and so on.
2. All bodies have an id number, thus the containrs are actually a bit similar to std::map<id,Class> in functionality (but see notes about Containers in point 2. below). Information with the same id number in two different containers belongs to the same body.
3. Each body can belong to several groups, thus it is fast to iterate over all members of some chosen group.
Containers
1. Containers take care of multithreading synchronization on their own. Classes written by users, stored inside containers, won't need to worry about this.
2. Therefore they provide two means of access: a read-only access, and read-write access to container elements. The function names could be eg: get(id) and see(id). The operator[] accessor can default to read-only function see().
3. Containers allow links between the content, like parent/target/members. So that a single BoundingVolume (for example a cylinder) will consist of many members bounding boxes that cover the cylinders walls (so that the inside of a cylinder is outside bounding volume). Another example - a clump has many members that are spheres.

[edit] A note on acronyms in naming

We are using CamelCase for class names, but it turns out that we cannot avoid using acronyms, which are not compatibile with CamelCase, for example AABB. So I propose, that when it is necessary to use an acronym, we will make it a word - only first letter is capital. Like this: Aabb. The same was done with three-letter abbreviations (they have only first letter capital).

[edit] Naming of data classes

There comes another problem: the DispatcherFunctor will have a lenghty name of no matter how hard we try: it will contain in it a full name of SomeClass1 and SomeClass2, so th epoint is to make a bit shorter names of derived data classes, using mentioned above Short name or Acronym.

Class naming, along with inheritance tree

Current name

New name

Body

State

BodyVariables

?

PhysicalParameters

BodyConstitutiveParameters

FEMSetParameters

?

FEMTetrahedronData

?

LatticeBeamParameters

?

LatticeNodeParameters

?

LatticeSetParameters

?

ParticleParameters

?

FEMNodeData

?

RigidBodyParameters

?

ElasticBodyParameters

?

BodyMacroParameters

?

ParticleSetParameters

?

GeometricalModel

BodyShape

Box

BshBox

FEMSetGeometry

^*

LatticeSetGeometry

^*

LineSegment

BshLineSegment

Mesh2D

BshMesh

Quadrilateral

^**

Sphere

BshSphere

Tetrahedron

BshTetrahedron

InteractingGeometry

BodySimplifiedShape

InteractingBox

BssBox

InteractingMyTetrahedron

BssFourSpheres^**

InteractingSphere

BssSphere

MetaInteractingGeometry

^*

LatticeInteractingGeometry

^*

TetraMold

BssTetrahedron

BoundingVolume

BodyBoundingVolume

AABB

BbvAabb

BoundingSphere

BbvSphere

Interaction

InteractionGeometry

InteractionState

ClosestFeatures

?

InteractionOfMyTetrahedron

?

SDECLinkGeometry

?

SpheresContactGeometry

?

SpringGeometry

?

TetraBang

?

InteractionPhysics

InteractionConstitutiveParameters

LatticeBeamAngularSpring

?

NonLocalDependency

?

SDECLinkPhysics

?

SpringPhysics

?

SimpleElasticInteraction

?

ElasticContactInteraction

?

CapillaryParameters

Real CapillaryPressure
int currentIndexes [4]
Real Delta1
Real Delta2
Vector3r Fcap
bool meniscus
Real Vmeniscus

?

CohesiveFrictionalContactInteraction

bool cohesionBroken
bool cohesionDisablesFriction
bool fragile
Real normalAdhesion
Real shearAdhesion

^* - after refactoring containers, empty classes will no longer be necessary, and will be removed

^** - this Quadrilateral is actually a DataProcessor, and so it will become it.

NOTE: we should consider adding basic classes that will be used for multiple inheritance:

Tetrahedron for BS_Tetrahedron (Tetrahedron) and BOS_Tetrahedron (TetraMold). They have the same data members!
Sphere for BS_Sphere, BOS_Sphere, BBV_Sphere. They also have exactly the same data members!
Box for BS_Box and BOS_Box.

Then Unless a specific GLDraw is written for BBV_Sphere - a generic one that understands Sphere can be used ;)

OR: we should allow storing the same class (eg. Sphere) in different containers - in bounding volume container, in body shape container, etc...

[edit] EngineUnit (EngineFunctor) naming

To show you the full horror of currently used names, I have prepared a lenghty table at the bottom of this page with currently used names.

No doubt that we must do something to simplify and regularize the convention. Othwerwise, even though everyone of us does his best, we will have names that are difficult to work with. Current proposal is based on following reasoning which compares EngineUnit (DispatcherFunctor) to classical C++ virtual method:

Current proposal
question	a normal C++ virtual method	EngineUnit (EngineFunctor)
what it does?	is a virtual member function of single class	is simulating a virtual member function of two classes.
what is (would be) its fully qualified name?	`SomeClass::functionName()`	`SomeClass1::SomeClass2::functionName()`
so what is the proposal?	use current name ;-) `SomeClass::functionName()`	use EngineFunctor name like this: `SomeClass1_SomeClass2_functionName()`

It is impossible to have a name SomeClass1::SomeClass2::functionName() in C++, because DispatcherFunctor is simulating a missing C++ functionality. For the same reason functionName() must be part of the classname, because the member function of SomeClass1_SomeClass2_functionName() that contains the actual code has always a fixed name: go()

Currently we use '2' and '4', I proposed '_' but we can use three characters as well, like '_x_' or '_2_'. This matter is still open. In table at the end of this page I'll use '_', as an example.

[edit] Naming of DispatcherFunctors

Finally we can try to rename EngineUnits (DispatcherFunctors) to something which is not a horror anymore... uh.

Current name	New name
CohesiveFrictionalRelationships
CundallNonViscousForceDamping
CundallNonViscousMomentumDamping
ElasticBodySimpleRelationship
FEMSet2Tetrahedrons
FEMSetTextLoader
FEMTetrahedronStiffness
InteractingBox2AABB
InteractingBox2InteractingBox4ClosestFeatures
InteractingBox2InteractingSphere4ClosestFeatures
InteractingBox2InteractingSphere4SpheresContactGeometry
InteractingBox2InteractingSphere4SpheresContactGeometryWater
InteractingMyTetrahedron2AABB
InteractingMyTetrahedron2InteractingBox4InteractionOfMyTetrahedron	BssFourSpheres_BssBox_makeSixteenPenetrations
InteractingMyTetrahedron2InteractingMyTetrahedron4InteractionOfMyTetrahedron
InteractingSphere2AABB	BssSphere_makeBbvAabb
InteractingSphere2AABBwater
InteractingSphere2InteractingSphere4ClosestFeatures
InteractingSphere2InteractingSphere4DistantSpheresContactGeometry
InteractingSphere2InteractingSphere4SpheresContactGeometry
InteractingSphere2InteractingSphere4SpheresContactGeometryWater
LatticeSet2LatticeBeams
LeapFrogOrientationIntegrator
LeapFrogPositionIntegrator
MacroMicroElasticRelationships
MacroMicroElasticRelationshipsWater
MetaInteractingGeometry2AABB
NewtonsForceLaw
NewtonsMomentumLaw
ParticleSet2Mesh2D
SimpleElasticRelationships
Tetrahedron2InteractingMyTetrahedron

Future plans