← Back to team overview

yade-users team mailing list archive

Re: lack of documentation


Vaclav SMILAUER said:     (by the date of Fri, 03 Nov 2006 11:18:37 +0100)

> Hello,

Hello Vaclav. First I will answer your concerns. The answers to your
tetrahedra related questions are coming in next email :)

> PS. You ask to report any disadvantages of yade on the website. As a 
> newcomer, my opinion may not count much, but anyways.

Because you are a newcomer, the disadvantages that you see are most
important ever. Everyone when starts looking at some software is a
newcomer first, so this kind of impressions is most important.

> 1. utter lack of documentation: most of the source code is not 
> documented (poorly or not at all). For casual user (are there any?),
> it might not be a problem, but for those building their own models etc.,
> this is (almost) prohibitive. 
> Frankly speaking, when you (Janek) finish your thesis and will no longer 
> develop and/or maintain yade, it is deemed to fall into oblivion (i.e. 
> no community around) for the lack of documentation - just my opinion, 
> though.

I'm very thankful for this constructive criticism, and I'm 100% aware
that you are right here. But relax a bit, my plans are different:

- currently I'm finishing the PhD, this should end by the april 2007,
  so I have no time to work on other yade aspects (eg. documentation)

- after defending PhD I don't plan to stop working on yade. Quite the
  opposite - I want to spend more time on yade, and no more time on
  lattice model. Starting from april for 4 months in grenoble I want to fix
  all the most outstaing issues. Here the documentation is a top
  priority. So that's the point: after I finish my thesis I will write
  an exhaustive documentation.

- after that period in grenoble I still plan to work on yade and
  improve it (I am currently in talks with Frederic to plan a longer,
  two-year post-doc, where I will focus on yade). So finally it shall
  reach the stage at which it will not fall into oblivion, because the
  userbase will be big enough. When I reach this point I'll probably
  spend less time working on it, but help the others to do what they

The beginnings are always hard. Remember that here (in poland) I work
on yade only because of my passion in my free time. Frederic can get
money for me to work on it, and when I'm paid, my workforce is able to
increase tenfold :) A usual case with all free software. Passion
alone is often not enough, but passion + money is certainly enough :)

That's why current yade development is slower. Still lacking
documentation, etc. But things will be much better in few months,
when I will start getting money for that.

However for the time being, since the documentation is so lacking,
you instead have to ask questions on this mailing list. And I will
help you as much as I can.

> For example, would someone knowledgeable mind to complete the
> User's manual left in an incomplete state by Olivier?

Unfortunately I am currently the only person capable of doing this.
And I *will* do it, but starting from april 2007.

> (In my case, I am very seriously
> looking at alternative DEs (ode, bullet) just because of that.)

If you consider this option seriously then:

- I investigated ODE to some extend (also looking for tetrahedron
related stuff) and I think that it may be worthwhile to perhaps get
from ODE some collision-related code and import it into yade. But IMO
it's not worthwile to make tetrahedron collisions in ODE because:

  - the default collision detection algorithm (even the most
    comprehensive version) is not stable - the resultant collision
    forces and momentums (PhysicalAction in yade ;) are getting insanely
    big if one object collides with the edge of another.

  - fixing this means writing new collision handling stuff. So it's
    the same work in ODE and in yade.

  - ODE's collision handling is some kind of "magic" in the means
    that you don't really know what it does. It "just works".
    Therefore ODE is useful for writing games, where object's collision
    just need to "look" correctly. But it is useless for scientific
    calculations (like yade). Because scientific calculations must be
    more than "just look nice". They must be scientifically correct.

  - ODE states on their webpage, that their main target are games
    (not scientific simulations).

- I don't know bullet, so maybe it's worth a try. But you should be
catious - maybe my concerns over ODE also apply to bullet? Especially
because on their frontpage it is written that the main target are
games, too.

> 2. I find the overdesigned 
> project/bunch-of-directories/one-class-per-directory to be unbrowsable 
> with command-line or anything available I use. To navigate through 100 
> files scattered everywhere to get the idea of a simple code-path, not a 
> great thing to do either.

Heh, that was the original idea from Olivier. I don't like this too,
because I mostly use gvim+xterm (+mc) (and I don't use kdevelop). I
plan to change this and flatten the directory tree. I just need time
to think and do it.

Because things are as they currently are I'm using following stuff to
ease my life a bit:

my xterm resides in top directory level (trunk):

1. I'm using ctags, first in the terminal run:

  ctags --recurse --language-force=c++ --extra=+q --exclude=.svn

then in gvim you use ctags by pressing ctrl-] on the variable (or a
class) to jump to its definition. Also in gvim read help about:

  :h tags 

2. To find some file I do

   find -iname "*part*of*classname*" | fgrep -v .svn

then I can copy/paste this file's name into gvim to open it. However
most of the time ctags do this work for me, so I don't need to search
for it with this command 'find'.

3. I use saving/loading of sessions in gvim to remember various work
contexts. In fact it is the only gvim command that I invoke by
clicking on an icon (in the top icon bar), all the other vim commands I
type from the keyboard :)

4. vim plugin: alternate file (swap between cpp/hpp):


I have mapped this plugin's command :A to F12 and shift-F12 (inside file ~/.vimrc):

:nnoremap <S-F12> :A<CR>
:vnoremap <S-F12> <esc>:A<CR>
:inoremap <S-F12> <C-O>:A<CR>
:nnoremap <F12> :A<CR>
:vnoremap <F12> <esc>:A<CR>
:inoremap <F12> <C-O>:A<CR>

6. vim plugin to switch buffers quickly:


I have mapped it to F1 (inside file ~/.vimrc):

:imap <silent> <F1> <esc><Plug>SelectBuf 
:nmap <silent> <F1> <Plug>SelectBuf 

If you use some other editor, then you should find a similar
functionality in this editor. If you use kdevelop you already have
this functionality.

7. moreover to speed up compilation I'm using distcc (full recompile
time went down from 30minues to 5 minutes). distcc uses all the
computers around that I have.

8. and also I'm using ccache (again the time of full recompile went
down from 5 minutes to 2 minutes).

However yade's makefiles are not distcc-friendly and I have numerous
link-failures near the end. Because one file is trying to link with
another file that is still being compiled (so the linker fails).

The current workaround (until I will fix the makefiles), is to run
compilation in the loop:

for (( i=0 ; i<15 ; i=i+1 )) ; \
  do make -j20 compile_install CXXFLAGS='-pthread -lpthread -O3 -DDOUBLE_PRECISION' \
  INSTALL_DIR='/YADE' PREFIX_DIR='/home/janek' ; \

I think that flattening the directory tree will fix this linker failures problem.

I'm looking forward to get more constructive criticism from you - it
is the best way to create succesfull software.

# Janek Kozicki
Yade-users mailing list

Follow ups