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
[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( 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/
_______________________________________________
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
_______________________________________________
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
