Hi Jérôme, nice idea. However, not sure if this is the way to go. I don't think we need a new attribute. Why not just adding a little table in each LawFunctor description in the doc? We can still grep for the table and build up the current wiki table.
BTW, if we don't find a solution here we can discuss and implement it at the workshop. I can put it on the list ;-) Cheers Klaus On Mon, May 26, 2014 at 10:27 PM, Jérôme Duriez < [email protected]> wrote: > So, I have a proposal, introducing two new attributes : > > One would be "LawFunctor.status" in ... LawFunctor. Here is a possible > c++ implementation in LawFunctor.hpp > ((bool, status,0,,"boolean expressing the status of the considered > LawFunctor. The use is safe if status=True (law validated, support might > come from mailing list..), whereas for status=False, no warranty exists > that the law is validated and/or maintained/used by anyone else. A warning, > see InteractionLoop.Law2warning, is displayed in this case.)) > The idea is to put in InteractionLoop something like (please apologize > possible syntax mistakes) : > if (LawFunctor->status==False) > cout/cerr << "You're using a non validated constitutive law ! Please > consider using another LawFunctor with status = True (e.g. > Law2_ScGeom_FrictPhys_CundallStrack), unless you are 100% autonom"; > > This warning would display at each iteration, so that users > necessarily see it. To not bother "100% autonom" people, here comes the > second attribute : InteractionLoop.Law2warning ! Wich has such a c++ > implementation, in InteractionLoop.hpp, for example : > ((bool,Law2warning,1,,"Autonom people that use constitutive laws with > status=0 may set this attribute to False to get rid of related warnings.")) > > > In this framework : > - For what concerns the devs, we get rid of the wiki page. Devs would > only have to take care of defining correctly the value of their status, > rather than painting in green or red in the wiki page. All other > informations such as description, publications, example scripts, should be > already in the sphinx doc (If not, such infos would probably be neither on > the wiki). There would be no risk of deprecation of the wiki page compared > to c++ code. If new laws are commited, it is easy to check which status > value is defined in the commit. > - For users, the warning of > https://www.yade-dem.org/doc/user.html#law2-functor-s would be rephrased, > to put attention of users on LawFunctor.status, rather than pointing > towards the wiki page. Users that did not read nor this warning, nor the > doc of their Law and pick unfortunately a "red" Law2 would be bored by the > warning, and quickly would use e.g. Law2_ScGeom_FrictPhys_CundallStrack, > before asking "useless" questions. > > Among the drawbacks, I confess that there is no synthetic presentation > with such design, compared with the coloured table of the wiki. But maybe > this could be generated automaticcaly, grepping for "status,1" in the code > ? And I consider in any case, that an up-to-date not so synthetic > information is better that a deprecated synthetic one... > > Tell me what you think ! > > Jérôme > > > > > Le 26/05/2014 11:06, Bruno Chareyre a écrit : > > 2/ is very unlikely to happen. More realistic is to translate the table in > *.rst. I was secretely hopping that you would be volunteer for that. :) > Besides, I'm open to suggestions on how to improve. > B > > > On 26/05/14 10:19, Jérôme Duriez wrote: > > Hi, > > Many thanks to the guy who in fact updated > Law2_ScGeom6D_NormalInelasticityPhys_NormalInelasticity for me ! I had only > to add the name of the example script... So, I edited my one (or even two) > lines in the wiki page. > > I do not know how much you were serious about your 2/ proposition, Bruno > (this could be a project for a computer science student ?), but let us hope > that this day will come. Otherwise I have no doubt that the destiny of this > page is to be most of the time deprecated. We just had another example with > Law2_ScGeom_ViscElPhys_Basic, with guys that are nevertheless "quite" > involved in Yade... (there is an euphemism there) > > Jérôme > > > Le 23/05/2014 13:21, Bruno Chareyre a écrit : > > Hi Jerome, > Thank you for suggestions. First, I'm glad you recognize that the functors > table is less puzzling than the inheritance diagram (or let's say, they > have different purpose). I saw many situations where users would come with > a very specific question, then we realize that they picked a wrong contact > law (bugged and/or unmaintained, L3 to name one). Frustrating for users, > wasted time for everyone. It was the reason to write this table. > Another possible solution would be to reduce the total number of functors. > For instance eliminate from the source code every law which results at > least partly from code duplication, and/or has no example script, and/or is > not documented, and/or has no known maintainer. > > Now, your message is twofold: 1/ where this content should be, and 2/ what > this content should be. > 1/ If someone could re-type this wiki page in rst format, he would have > his karma increased. The right place to put it is in place of this warning, > which currently links to the wiki page: > https://yade-dem.org/doc/user.html#law2-functor-s > Obviously, writing the table in rst will not escape the need to put > information in two different places: class documentation and user manual > (actually it may be easier to modify a table in a wiki page compared to > rst+github, but still I would like the rst option). So: > > 2/ If someone could write a program that would heuristicaly fill the > columns of the table by browsing bug reports, frequency and authors of > commits to each law, and bibliographic reference mentionned in the class > documentation (warning: references to original papers like Cundall1979 > should not appear in the "publications" column, it needs a semantic > analysis of the docstrings), his karma would not only explode, I would also > pay him. > Before this happens, laws will be orphan until somebody will vouch for > them and update the documentation (thank you for updating > NormalInelasticity, now you know you need to put an example script). > > > Thank you for raising this need for updates. It actually reminded me to > ping Anton and Raphaël for Law2_ScGeom_ViscElPhys_Basic, which still looks > red. > Could you please guys do something? > > Thanks > > Bruno > > > On 23/05/14 10:09, Jérôme Duriez wrote: > > Hi, > > This wiki page makes me puzzled since I stumbled upon it. Is there really > a consensus to consider this page as really usefull, and *efficient* ? > > Surely, it could be useful for new users that discover the diagram of > https://www.yade-dem.org/doc/yade.wrapper.html#lawfunctor... > > But, I tend to answer "no" about the relevance. For me, sphinx doc is the > best interface between users and the code (the best place to put > documentation !) *and the most easy to maintain*. Each change in the > sphinx doc follows the git procedure, with possible control from all > developpers and history. Probably such collaborative work features are also > be possible with the wiki, but why would we sum / mix the tools ? > For example, the authors of the wiki page designated > Law2_ScGeom6D_NormalInelasticityPhys_NormalInelasticity as orphan and > colored it in red... Sure, it is up to class authors (me, here..) to > correct such things, but I wrote a description, with publications and > example script in (*).*Why should I/we re-type it in the wiki page ?* > > Let us focus on sphinx doc, so that it corresponds to / explains as best > as possible the c++ code. This is already a great challenge, maybe there is > no need to have to maintain wiki pages about the same subjects ? > > Jérôme > > (*) : > https://www.yade-dem.org/doc/yade.wrapper.html#yade.wrapper.Law2_ScGeom6D_NormalInelasticityPhys_NormalInelasticity > > > Le 22/05/2014 18:24, Christian Jakob a écrit : > > Hi, > > > I updated the wiki for constitutive laws [1]. > Please check for mistakes and add missing informations (examples, dev. > status, active users, ...). > > I detected a duplicate in law description in [2] and [3], which are > exactly the same. Can someone fix that, please? > > > Regards, > > Christian > > > [1] https://yade-dem.org/wiki/ConstitutiveLaws#Constitutive_laws > [2] > https://yade-dem.org/doc/yade.wrapper.html?highlight=cohesion#yade.wrapper.Law2_ScGeom6D_CohFrictPhys_CohesionMoment > [3] > https://yade-dem.org/doc/yade.wrapper.html?highlight=cohesion#yade.wrapper.Law2_ScGeom6D_InelastCohFrictPhys_CohesionMoment > > > _______________________________________________ > Mailing list: https://launchpad.net/~yade-dev > Post to : [email protected] > Unsubscribe : https://launchpad.net/~yade-dev > More help : https://help.launchpad.net/ListHelp > > > -- > Jérôme Duriez > Post-Doctorant UJF > Laboratoire 3SR > Bureau E139 - 04.56.52.86.30 > > > > _______________________________________________ > Mailing list: https://launchpad.net/~yade-dev > Post to : [email protected] > Unsubscribe : https://launchpad.net/~yade-dev > More help : https://help.launchpad.net/ListHelp > > > > -- > _______________ > Bruno Chareyre > Associate Professor > ENSE³ - Grenoble INP > Lab. 3SR > BP 53 > 38041 Grenoble cedex 9 > Tél : +33 4 56 52 86 21 > Fax : +33 4 76 82 70 43 > ________________ > > > > _______________________________________________ > Mailing list: https://launchpad.net/~yade-dev > Post to : [email protected] > Unsubscribe : https://launchpad.net/~yade-dev > More help : https://help.launchpad.net/ListHelp > > > -- > Jérôme Duriez > Post-Doctorant UJF > Laboratoire 3SR > Bureau E139 - 04.56.52.86.30 > > > > _______________________________________________ > Mailing list: https://launchpad.net/~yade-dev > Post to : [email protected] > Unsubscribe : https://launchpad.net/~yade-dev > More help : https://help.launchpad.net/ListHelp > > > > -- > _______________ > Bruno Chareyre > Associate Professor > ENSE³ - Grenoble INP > Lab. 3SR > BP 53 > 38041 Grenoble cedex 9 > Tél : +33 4 56 52 86 21 > Fax : +33 4 76 82 70 43 > ________________ > > > > _______________________________________________ > Mailing list: https://launchpad.net/~yade-dev > Post to : [email protected] > Unsubscribe : https://launchpad.net/~yade-dev > More help : https://help.launchpad.net/ListHelp > > > -- > Jérôme Duriez > Post-Doctorant UJF > Laboratoire 3SR > Bureau E139 - 04.56.52.86.30 > > > _______________________________________________ > Mailing list: https://launchpad.net/~yade-dev > Post to : [email protected] > Unsubscribe : https://launchpad.net/~yade-dev > More help : https://help.launchpad.net/ListHelp > >
_______________________________________________ Mailing list: https://launchpad.net/~yade-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~yade-dev More help : https://help.launchpad.net/ListHelp
