yade-dev team mailing list archive

["Janek Kozicki (yade-dev)" <janek_listy@xxxxx>]

When it comes to documentation, for me it’s: never remove anything, always improve :)

On 21 Feb 2018, 22:25 +0100, Robert Caulk <rcaulk@xxxxxxxxxxxx>, wrote:
> Hello Jérôme,
>
> I support clarifying the meaning of particle young in the class reference as you suggest. There is no doubt that newcomers to DEM and Yade confuse micro young's modulus with macro young's modulus all the time.
>
> I would vote for clarifying the general doc instead of full removal of stiffness and normal stiffness section in general doc, I think they provide good examples of how Yade treats micro stiffness. If we decide to keep the sections I can look into improving their clarity. But if others think removal is best, I am not against it :-)
>
> Best,
>
> Robert
>
> > On Wed, Feb 21, 2018 at 8:59 AM, Jerome Duriez <jerome.duriez@xxxxxxxxx> wrote:
> > > Hi,
> > >
> > > 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.
> > > 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.
> > >
> > >
> > > 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.
> > >
> > >
> > > 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.
> > >
> > >
> > > 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.
> > >
> > >
> > > Jérôme
> > >
> > > 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...
> > >
> > >
> > > ****************** 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
>