Hi Jérôme, I am not in favor of removing some documentation, thank you for asking.

`In my view such patch would be a regression. I don't understand the`

`motivation, see below.`

On 02/21/2018 05:59 PM, Jerome Duriez wrote:

After seeing Yet Another Doubts on "young" meaning /Ip2_FrictMat_FrictMat_FrictPhys contact model (a PhD student in myinstitute), I'm proposing to explicitly mention the underlyingequations in the doc, once for all.The corresponding would-be diff appears at the end of the email, youmay also compare the attached screenshot withhttps://yade-dem.org/doc/yade.wrapper.html#yade.wrapper.Ip2_FrictMat_FrictMat_FrictPhys.

`The equations are _already_ in the documentation as can be seen`

`following the link, and you patch is not adding any if I read correctly.`

`What the diff does is that it removes the physical explanations of the`

`model. I am a bit lost then. Or maybe you did not paste the correct diff?`

From the diff, you will see I'm also proposing to remove the "harmonicaverage stiffness" comment, for instance because there actually is a"2" factor missing/extra between the comment and the actual code.

`The model is really based on an harmonic average, why is it better to`

`hide it?`

Where is the problem with a factor 2? Something to fix somewhere?

`The patch is mentioning an "equivalent" diameter, what is that? Diameter`

`is just true diameter.`

In the case of the above-mentioned PhD student, confusion also arosebecause of https://yade-dem.org/doc/formulation.html#stiffnesses andhttps://yade-dem.org/doc/formulation.html#normal-stiffness.As such, I would also propose to simply remove these two sections fromthe doc.From my point of view, they actually are too Ip2-specific to appear inthe general doc.

`What was wrong in these sections based on the student feedback? What can`

`be improved?`

`These sections describe what happens in almost all contact models (even`

`Hertz-Mindlin is defining the compliance of an interaction as the sum of`

`the compliances of each particle). Contact stiffness is such a`

`cornerstone, I don't see a reason to not explain it in the general`

`introduction of DEM. I am not at all speaking of "functors" here.`

If necessary, a reference to the (equivalent) 2.2.1 and 2.2.1.1.sections from Vaclav's thesis ([Smilauer2010b] reference) could beintroduced e.g. in Ip2_CpmMat_CpmMat_CpmPhys andIp2_FrictMat_FrictMat_FrictPhys docstrings, to keep track of thesecomments that could be made concerning the Ip2 equations.

`I don't understand why removing some sections would be an improvement`

`which would help people to understand the "Young" parameter.`

`You seem to think that there is something specific for`

`Ip2_CpmMat_CpmMat_CpmPhys and Ip2_FrictMat_FrictMat_FrictPhys, but it is`

`not the case.`

`All functors I just checked (~10 of them) are following exactly the same`

`logic.`

This email probably is Yet Another non-critical one, but since itdeals about (the doc of) central pieces of code, and lines probablywritten by Vaclav, I'm opening a possible discussion here beforeperforming the changes.

No, it does not deal with central pieces of code.

`Instead this chapter gives a general introduction to DEM relatively`

`independently of the code (co-authored by Vaclav and I, mostly written`

`by Vaclav in its original version). This is not some code documentation`

`(even if - of course - some comments are specific to Yade).`

PS: next step would be to movehttps://yade-dem.org/doc/formulation.html#strain-evaluation to Ig2docstrings but I'm not planning on it...

Huh??

`The last step would be to remove the "formulation" chapter probably, but`

`why?`

Duplicating the same explanation in every functor would be horrible. Would you also repeat everywhere the figures on contact geometry?

`I would strongly disagree with such move. This section and the other you`

`mentioned before are sections which most (if not all) functors can refer to.`

`The functor documentation should focus on what is specific to a given`

`functor, and give pointers to elsewhere (preferably on yade-dem.org) for`

`generalities on contact models.`

`One thing I just tried to improve [1] after your email is that the text`

`was mixing the descriptions in terms of "stress" and "force" a bit`

`inconsistently.`

`I replaced "strain" by more neutral names in some places, like`

`"deformation", "kinematic variable", "relative movement",...`

`There is still a sentence to explain that everything can be put either`

`in terms of strain/stress or displacement/force.`

Cheers Bruno

`[1]`

`https://github.com/yade/trunk/commit/ef725bd2cdfddb1f9b532ced849403b500713db2`

****************** Diff herein proposed for commit ************** diff --git a/pkg/dem/FrictPhys.cpp b/pkg/dem/FrictPhys.cpp index cb904da..4f8ffe8 100644 --- a/pkg/dem/FrictPhys.cpp +++ b/pkg/dem/FrictPhys.cpp@@ -26,9 +26,7 @@ void Ip2_FrictMat_FrictMat_FrictPhys::go( constshared_ptr<Material>& b1Real Va = mat1->poisson; Real Vb = mat2->poisson;- //harmonic average of the two stiffnesses when (2*Ri*Ei) isthe stiffness of a contact point on sphere "i"Real Kn = 2*Ea*Ra*Eb*Rb/(Ea*Ra+Eb*Rb); - //same for shear stiffness Real Ks = 2*Ea*Ra*Va*Eb*Rb*Vb/(Ea*Ra*Va+Eb*Rb*Vb);Real frictionAngle = (!frictAngle) ?std::min(mat1->frictionAngle,mat2->frictionAngle) :(*frictAngle)(mat1->id,mat2->id,mat1->frictionAngle,mat2->frictionAngle);diff --git a/pkg/dem/FrictPhys.hpp b/pkg/dem/FrictPhys.hpp index eeb2ef4..12c85ee 100644 --- a/pkg/dem/FrictPhys.hpp +++ b/pkg/dem/FrictPhys.hpp@@ -44,7 +44,7 @@ class Ip2_FrictMat_FrictMat_FrictPhys: publicIPhysFunctor{const shared_ptr<Material>& b2, const shared_ptr<Interaction>& interaction); FUNCTOR2D(FrictMat,FrictMat);-YADE_CLASS_BASE_DOC_ATTRS(Ip2_FrictMat_FrictMat_FrictPhys,IPhysFunctor,"Createa :yref:`FrictPhys` from two :yref:`FrictMats<FrictMat>`. Thecompliance of one sphere under point load is defined here as$1/(E.D)$, with $E$ the stiffness of the sphere and $D$ its diameter.The compliance of the contact itself will be the sum of compliancesfrom each sphere, i.e. $1/(E_1.D_1)+1/(E_2.D_2)$ in the general case,or $2/(E.D)$ in the special case of equal sizes and equal stiffness.Note that summing compliances corresponds to an harmonic average ofstiffnesss (as in e.g. [Scholtes2009a]_), which is how kn is actuallycomputed in the :yref:`Ip2_FrictMat_FrictMat_FrictPhys` functor:\n\n$k_n = \\frac{E_1D_1*E_2D_2}{E_1D_1+E_2D_2}=\\frac{k_1*k_2}{k_1+k_2}$,with $k_i=E_iD_i$.\n\n The shear stiffness ks of one sphere is definedvia the material parameter :yref:`ElastMat::poisson`, asks=poisson*kn, and the resulting shear stiffness of the interactionwill be also an harmonic average. In the case of a contact between a:yref:`ViscElMat` and a :yref:`FrictMat`, be sure to set:yref:`FrictMat::young` and :yref:`FrictMat::poisson`, otherwise thedefault value will be used.",+YADE_CLASS_BASE_DOC_ATTRS(Ip2_FrictMat_FrictMat_FrictPhys,IPhysFunctor,"Createa :yref:`FrictPhys` from two :yref:`FrictMats<FrictMat>` as per thefollowing expressions: \n\n$k_n =\\frac{E_1D_1*E_2D_2}{E_1D_1+E_2D_2}$ where $k_n=$:yref:`FrictPhys.kn`, the $E_i$ are :yref:`FrictMat.young` for eachcontacting body $i=1;2$, and the $D_i$ are the bodies' (equivalent)diameters\n\n$k_s = \\frac{E_1D_1P_1*E_2D_2P_2}{E_1D_1P_1+E_2D_2P_2}$where $k_s=$ :yref:`FrictPhys.ks` and the $P_i$ are the bodies':yref:`FrictMat.poisson`\n\n$\\mu = \\tan(min(\\phi_1,\\phi_2))$ bydefault (see :yref:`frictAngleattribute<Ip2_FrictMat_FrictMat_FrictPhys.frictAngle>`), where $\\mu=$:yref:`FrictPhys.tangensOfFrictionAngle` and the $\\phi_i$ are thebodies' :yref:`FrictMat.frictionAngle`.",------ Chargé de Recherche / Research Associate Irstea, RECOVER 3275 route de Cézanne – CS 40061 13182 Aix-en-Provence Cedex 5 FRANCE +33 (0)4 42 66 99 21 A free DEM conference in April:https://2ndyadeworkshop.sciencesconf.org/ _______________________________________________ Mailing list: https://launchpad.net/~yade-dev Post to : yade-dev@lists.launchpad.net Unsubscribe : https://launchpad.net/~yade-dev More help : https://help.launchpad.net/ListHelp

_______________________________________________ Mailing list: https://launchpad.net/~yade-dev Post to : yade-dev@lists.launchpad.net Unsubscribe : https://launchpad.net/~yade-dev More help : https://help.launchpad.net/ListHelp