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 my institute), I'm proposing to explicitly mention the underlying equations in the doc, once for all. The corresponding would-be diff appears at the end of the email, you may also compare the attached screenshot with https://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 "harmonic average 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 arose because of https://yade-dem.org/doc/formulation.html#stiffnesses and https://yade-dem.org/doc/formulation.html#normal-stiffness. As such, I would also propose to simply remove these two sections from the doc. From my point of view, they actually are too Ip2-specific to appear in the 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 be introduced e.g. in Ip2_CpmMat_CpmMat_CpmPhys and Ip2_FrictMat_FrictMat_FrictPhys docstrings, to keep track of these comments 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 it deals about (the doc of) central pieces of code, and lines probably written by Vaclav, I'm opening a possible discussion here before performing 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 move https://yade-dem.org/doc/formulation.html#strain-evaluation to Ig2 docstrings 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







****************** 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( const shared_ptr<Material>& b1
        Real Va         = mat1->poisson;
Real Vb         = mat2->poisson;


-       //harmonic average of the two stiffnesses when (2*Ri*Ei) is the 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: public IPhysFunctor{
                        const shared_ptr<Material>& b2,
const shared_ptr<Interaction>& interaction);
FUNCTOR2D(FrictMat,FrictMat);

- YADE_CLASS_BASE_DOC_ATTRS(Ip2_FrictMat_FrictMat_FrictPhys,IPhysFunctor,"Create a :yref:FrictPhys from two :yref:FrictMats<FrictMat>. The compliance 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 compliances from 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 of stiffnesss (as in e.g. [Scholtes2009a]_), which is how kn is actually computed 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 defined via the material parameter :yref:ElastMat::poisson, as ks=poisson*kn, and the resulting shear stiffness of the interaction will 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 the default value will be used.", + YADE_CLASS_BASE_DOC_ATTRS(Ip2_FrictMat_FrictMat_FrictPhys,IPhysFunctor,"Create a :yref:FrictPhys from two :yref:FrictMats<FrictMat> as per the following 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 each contacting 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))$ by default (see :yref:frictAngle attribute<Ip2_FrictMat_FrictMat_FrictPhys.frictAngle>), where $\\mu=$ :yref:FrictPhys.tangensOfFrictionAngle and the $\\phi_i$ are the bodies' :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/

_______________________________________________



_______________________________________________