Obsoleted future plans

From Yade

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









Also see the current development schedule.

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

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:

  1. 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.
  2. 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.
  3. 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.


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).

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
T .png ? T .png ?
L .png ? L .png ?

PhysicalParameters

BodyConstitutiveParameters
T .png FEMSetParameters T .png ?
T .png FEMTetrahedronData T .png ?
T .png LatticeBeamParameters T .png ?
T .png LatticeNodeParameters T .png ?
T .png LatticeSetParameters T .png ?
T .png ParticleParameters T .png ?
IT .png FEMNodeData T .png ?
IL .png RigidBodyParameters T .png ?
IxL.png ElasticBodyParameters T .png ?
IxxL.png BodyMacroParameters T .png ?
L .png ParticleSetParameters L .png ?

GeometricalModel

BodyShape
T .png Box T .png BshBox
T .png FEMSetGeometry T .png *
T .png LatticeSetGeometry T .png *
T .png LineSegment T .png BshLineSegment
T .png Mesh2D T .png BshMesh
T .png Quadrilateral T .png **
T .png Sphere T .png BshSphere
L .png Tetrahedron L .png BshTetrahedron

InteractingGeometry

BodySimplifiedShape
T .png InteractingBox T .png BssBox
T .png InteractingMyTetrahedron T .png BssFourSpheres**
T .png InteractingSphere T .png BssSphere
T .png MetaInteractingGeometry T .png *
IL .png LatticeInteractingGeometry IL .png *
L .png TetraMold L .png BssTetrahedron

BoundingVolume

BodyBoundingVolume
T .png AABB T .png BbvAabb
L .png BoundingSphere L .png BbvSphere

Interaction

InteractionGeometry

InteractionState
T .png ClosestFeatures T .png ?
T .png InteractionOfMyTetrahedron T .png ?
T .png SDECLinkGeometry T .png ?
T .png SpheresContactGeometry T .png ?
T .png SpringGeometry T .png ?
L .png TetraBang L .png ?

InteractionPhysics

InteractionConstitutiveParameters
T .png LatticeBeamAngularSpring T .png ?
T .png NonLocalDependency T .png ?
T .png SDECLinkPhysics T .png ?
T .png SpringPhysics T .png ?
L .png SimpleElasticInteraction L .png ?
XL .png ElasticContactInteraction XL .png ?
XxTz.png
CapillaryParameters
Real CapillaryPressure
int currentIndexes [4]
Real Delta1
Real Delta2
Vector3r Fcap
bool meniscus
Real Vmeniscus
XxT.png ?
XxL.png
CohesiveFrictionalContactInteraction
bool cohesionBroken
bool cohesionDisablesFriction
bool fragile
Real normalAdhesion
Real shearAdhesion
XxL.png

* - 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...

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.

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