yade-dev team mailing list archive

[Klaus Thoeni <klaus.thoeni@xxxxxxxxxxxxxxxx>]

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 <
jerome.duriez@xxxxxxxxxxxxxxx> 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     : yade-dev@xxxxxxxxxxxxxxxxxxx
> 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     : yade-dev@xxxxxxxxxxxxxxxxxxx
> 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     : yade-dev@xxxxxxxxxxxxxxxxxxx
> 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     : yade-dev@xxxxxxxxxxxxxxxxxxx
> 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     : yade-dev@xxxxxxxxxxxxxxxxxxx
> 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     : yade-dev@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~yade-dev
> More help   : https://help.launchpad.net/ListHelp
>
>