From: ejjordan Date: Thu, 21 Oct 2021 21:21:41 +0000 (+0200) Subject: Improve doxygen in some nblib listed forces files X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?p=alexxy%2Fgromacs.git;a=commitdiff_plain;h=1b940b166ce144a0c479fb6da43416d43b84203a Improve doxygen in some nblib listed forces files This adds doxygen to some functions and makes the documentation more consistent in some cases. Also some functions are changed from being marked [[maybe_unused]] to not having parameter values in cases where that is possible. --- diff --git a/api/nblib/listed_forces/bondtypes.h b/api/nblib/listed_forces/bondtypes.h index 5a69f787e5..bb73541794 100644 --- a/api/nblib/listed_forces/bondtypes.h +++ b/api/nblib/listed_forces/bondtypes.h @@ -111,7 +111,7 @@ inline bool operator==(const TwoParameterInteraction& a, const TwoParam /*! \brief harmonic bond type * * It represents the interaction of the form - * V(r, forceConstant, equilDistance) = 0.5 * forceConstant * (r - equilConstant)^2 + * V(r, forceConstant, equilConstant) = 0.5 * forceConstant * (r - equilConstant)^2 */ using HarmonicBondType = TwoParameterInteraction; @@ -119,7 +119,7 @@ using HarmonicBondType = TwoParameterInteraction { @@ -136,7 +136,7 @@ public: /*! \brief FENE bond type * * It represents the interaction of the form - * V(r, forceConstant, equilDistance) = - 0.5 * forceConstant * equilDistance^2 * log( 1 - (r / equilConstant)^2) + * V(r, forceConstant, equilConstant) = - 0.5 * forceConstant * equilConstant^2 * log( 1 - (r / equilConstant)^2) */ using FENEBondType = TwoParameterInteraction; @@ -144,7 +144,7 @@ using FENEBondType = TwoParameterInteraction; /*! \brief Half-attractive quartic bond type * * It represents the interaction of the form - * V(r, forceConstant, equilConstant) = 0.5 * forceConstant * (r - equilDistance)^4 + * V(r, forceConstant, equilConstant) = 0.5 * forceConstant * (r - equilConstant)^4 */ using HalfAttractiveQuarticBondType = TwoParameterInteraction; @@ -154,7 +154,7 @@ using HalfAttractiveQuarticBondType = * * It represents the interaction of the form * V(r, quadraticForceConstant, cubicForceConstant, equilConstant) = quadraticForceConstant * (r - - * equilDistance)^2 + quadraticForceConstant * cubicForceConstant * (r - equilConstant) + * equilConstant)^2 + quadraticForceConstant * cubicForceConstant * (r - equilConstant) */ class CubicBondType { @@ -193,7 +193,7 @@ inline bool operator==(const CubicBondType& a, const CubicBondType& b) /*! \brief Morse bond type * * It represents the interaction of the form - * V(r, forceConstant, exponent, equilDistance) = forceConstant * ( 1 - exp( -exponent * (r - equilConstant)) + * V(r, forceConstant, exponent, equilConstant) = forceConstant * ( 1 - exp( -exponent * (r - equilConstant)) */ class MorseBondType { @@ -289,7 +289,7 @@ public: /*! \brief Harmonic angle type * * It represents the interaction of the form - * V(theta, forceConstant, equilAngle) = 0.5 * forceConstant * (theta - equilAngle)^2 + * V(theta, forceConstant, equilConstant) = 0.5 * forceConstant * (theta - equilConstant)^2 */ using HarmonicAngle = AngleInteractionType; @@ -325,22 +325,22 @@ public: /*! \brief G96 or Cosine-based angle type * * This represents the interaction of the form - * V(cos(theta), forceConstant, cos(equilAngle)) = 0.5 * forceConstant * (cos(theta) - cos(equilAngle))^2 + * V(cos(theta), forceConstant, cos(equilConstant)) = 0.5 * forceConstant * (cos(theta) - cos(equilConstant))^2 */ using G96Angle = CosineParamAngle; /*! \brief Restricted angle type * * This represents the interaction of the form - * V(cos(theta), forceConstant, cos(equilAngle)) = - * 0.5 * forceConstant * (cos(theta) - cos(equilAngle))^2 / (sin(theta))^2 + * V(cos(theta), forceConstant, cos(equilConstant)) = + * 0.5 * forceConstant * (cos(theta) - cos(equilConstant))^2 / (sin(theta))^2 */ using RestrictedAngle = CosineParamAngle; /*! \brief Quartic angle type * * It represents the interaction of the form of a fourth order polynomial - * V(theta, forceConstant, equilAngle) = sum[i = 0 -> 4](forceConstant_i * (theta - equilAngle)^i + * V(theta, forceConstant, equilConstant) = sum[i = 0 -> 4](forceConstant_i * (theta - equilConstant)^i */ class QuarticAngle { diff --git a/api/nblib/listed_forces/dataflow.hpp b/api/nblib/listed_forces/dataflow.hpp index 14b002b85c..74b3bcca53 100644 --- a/api/nblib/listed_forces/dataflow.hpp +++ b/api/nblib/listed_forces/dataflow.hpp @@ -72,8 +72,8 @@ inline ShiftForce* accessShiftForces(int shiftIndex, gmx::ArrayRef s } //! \brief dummy op in case shift forces are not computed (will be removed by the compiler) -inline std::nullptr_t accessShiftForces([[maybe_unused]] int shiftIndex, - [[maybe_unused]] gmx::ArrayRef shiftForces) +inline std::nullptr_t accessShiftForces(int /* shiftIndex */, + gmx::ArrayRef /* shiftForces */) { return nullptr; } @@ -149,7 +149,7 @@ addTwoCenterAggregate(const ThreeCenterType& parameters, const BasicVector& rij, BasicVector* fi, BasicVector* fj, BasicVector* fk, ShiftForce* shf_ij, ShiftForce* shf_kj, ShiftForce* shf_c) { - if (parameters.manifest == ThreeCenterType::Cargo::ij) +if (parameters.manifest == ThreeCenterType::Cargo::ij) { // i-j bond return computeTwoCenter(parameters.twoCenter(), rij, fi, fj, shf_ij, shf_c); @@ -167,15 +167,15 @@ addTwoCenterAggregate(const ThreeCenterType& parameters, const BasicVector& rij, template inline NBLIB_ALWAYS_INLINE std::enable_if_t::value, BasicVectorValueType_t> -addTwoCenterAggregate([[maybe_unused]] const ThreeCenterType& parameters, - [[maybe_unused]] const BasicVector& rij, - [[maybe_unused]] const BasicVector& rkj, - [[maybe_unused]] BasicVector* fi, - [[maybe_unused]] BasicVector* fj, - [[maybe_unused]] BasicVector* fk, - [[maybe_unused]] ShiftForce* shf_ij, - [[maybe_unused]] ShiftForce* shf_kj, - [[maybe_unused]] ShiftForce* shf_c) +addTwoCenterAggregate(const ThreeCenterType& /* parameters */, + const BasicVector& /* rij */, + const BasicVector& /* rkj */, + BasicVector* /* fi */, + BasicVector* /* fj */, + BasicVector* /* fk */, + ShiftForce* /* shf_ij */, + ShiftForce* /* shf_kj */, + ShiftForce* /* shf_c */) { return 0.0; }; @@ -260,7 +260,7 @@ auto computeThreeCenter(const CrossBondAngle& parameters, const BasicVector& rij { using ValueType = BasicVectorValueType_t; // 42 flops from the norm() calls - auto [ci, cj, ck, energy] = crossBondAngleKernel(norm(rij), norm(rkj), norm(rik), parameters); + auto [ci, cj, ck, energy] = threeCenterKernel(norm(rij), norm(rkj), norm(rik), parameters); BasicVector fi_loc = ci * rij + ck * rik; BasicVector fk_loc = cj * rkj - ck * rik; @@ -356,14 +356,14 @@ addThreeCenterAggregate(const FourCenterType& parameters, template inline NBLIB_ALWAYS_INLINE std::enable_if_t::value, BasicVectorValueType_t> -addThreeCenterAggregate([[maybe_unused]] const FourCenterType& parameters, - [[maybe_unused]] const BasicVector& rij, - [[maybe_unused]] const BasicVector& rkj, - [[maybe_unused]] const BasicVector& rkl, - [[maybe_unused]] BasicVector* fi, - [[maybe_unused]] BasicVector* fj, - [[maybe_unused]] BasicVector* fk, - [[maybe_unused]] BasicVector* fl) +addThreeCenterAggregate(const FourCenterType& /* parameters*/, + const BasicVector& /* rij */, + const BasicVector& /* rkj */, + const BasicVector& /* rkl */, + BasicVector* /* fi */, + BasicVector* /* fj */, + BasicVector* /* fk */, + BasicVector* /* fl */) { return 0.0; }; @@ -484,8 +484,9 @@ auto dispatchInteraction(InteractionIndex index, FiveCenterType fiveCenterTypeParams = parameters[std::get<5>(index)]; // this dispatch function is not in use yet, because CMap is not yet implemented - // we don't want to add [[maybe_unused]] in the signature - // and we also don't want compiler warnings, so we cast to void + // we don't want to add [[maybe_unused]] in the signature since the params will + // be used once CMap is implemented, and we also don't want compiler warnings, + // so we cast to void. (void)fiveCenterTypeParams; (void)forces; diff --git a/api/nblib/listed_forces/kernels.hpp b/api/nblib/listed_forces/kernels.hpp index b2a28a812f..e21f483c3e 100644 --- a/api/nblib/listed_forces/kernels.hpp +++ b/api/nblib/listed_forces/kernels.hpp @@ -51,8 +51,6 @@ #include "gromacs/math/vectypes.h" #include "nblib/listed_forces/bondtypes.h" -#define NBLIB_ALWAYS_INLINE __attribute((always_inline)) - namespace nblib { @@ -434,21 +432,21 @@ inline auto bondKernel(T dr, const HalfAttractiveQuarticBondType& bond) /*! \brief kernel to calculate the scalar part for linear angle forces * for lambda = 0 * - * \param k force constant - * \param a contribution of rij vector - * \param dr weighted distance metric + * \param k force constant + * \param a0 equilibrium angle + * \param angle current angle vaule * * \return tuple */ template -inline std::tuple linearAnglesScalar(T k, T a, T dr) +inline std::tuple linearAnglesScalarForce(T k, T a0, T angle) { - T b = T(1.0) - a; + T b = T(1.0) - a0; - T kdr = k * dr; - T epot = 0.5 * kdr * dr; + T kdr = k * angle; + T epot = 0.5 * kdr * angle; - T ci = a * k; + T ci = a0 * k; T ck = b * k; return std::make_tuple(ci, ck, epot); @@ -459,7 +457,7 @@ inline std::tuple linearAnglesScalar(T k, T a, T dr) template inline auto threeCenterKernel(T dr, const LinearAngle& angle) { - return linearAnglesScalar(angle.forceConstant(), angle.equilConstant(), dr); + return linearAnglesScalarForce(angle.forceConstant(), angle.equilConstant(), dr); } //! Harmonic Angle @@ -530,7 +528,7 @@ inline auto threeCenterKernel(T drij, T drkj, const CrossBondBond& crossBondBond * \param rkj input bond length between particles k & j * \param rik input bond length between particles i & k * - * \return tuple + * \return tuple */ template @@ -542,18 +540,18 @@ inline std::tuple crossBondAngleScalarForce(T k, T r0ij, T r0kj, T r T epot = k * sik * (sij + skj); - T ci = -k * sik / rij; - T cj = -k * sik / rkj; - T ck = -k * (sij + skj) / rik; + T fi = -k * sik / rij; + T fj = -k * sik / rkj; + T fk = -k * (sij + skj) / rik; - return std::make_tuple(ci, cj, ck, epot); + return std::make_tuple(fi, fj, fk, epot); /* That was 13 flops */ } //! Cross bond-bond interaction template -inline auto crossBondAngleKernel(T drij, T drkj, T drik, const CrossBondAngle& crossBondAngle) +inline auto threeCenterKernel(T drij, T drkj, T drik, const CrossBondAngle& crossBondAngle) { return crossBondAngleScalarForce(crossBondAngle.forceConstant(), crossBondAngle.equilDistanceIJ(), crossBondAngle.equilDistanceKJ(), crossBondAngle.equilDistanceIK(), drij, drkj, drik); } @@ -750,19 +748,25 @@ inline void addShiftForce([[maybe_unused]] const gmx::BasicVector& fij, { } -/*! \brief Spreads and accumulates the bonded forces to the two atoms and adds the virial contribution when needed +/*! \brief Spreads and accumulates the forces between two atoms and adds the virial contribution when needed * - * \p shiftIndex is used as the periodic shift. + * \tparam T The type of vector, e.g. float, double, etc + * \param force The Force + * \param dx Distance between centers + * \param force_i Force on center i + * \param force_j Force on center j + * \param shf_ik Shift force between centers i and j + * \param shf_c Shift force at the "center" of the two center interaction */ template -inline void spreadTwoCenterForces(const T bondForce, +inline void spreadTwoCenterForces(const T force, const gmx::BasicVector& dx, gmx::BasicVector* force_i, gmx::BasicVector* force_j, ShiftForce* shf_ij, ShiftForce* shf_c) { - gmx::BasicVector fij = bondForce * dx; + gmx::BasicVector fij = force * dx; *force_i += fij; *force_j -= fij; @@ -775,20 +779,23 @@ inline void spreadTwoCenterForces(const T bondForce, /*! \brief spread force to 3 centers based on scalar force and angle * - * \tparam T - * \param cos_theta - * \param force - * \param r_ij - * \param r_kj - * \param force_i - * \param force_j - * \param force_k + * \tparam T The type of vector, e.g. float, double, etc + * \param cos_theta Angle between two vectors + * \param force The Force + * \param dxIJ Distance between centers i and j + * \param dxJK Distance between centers j and k + * \param force_i Force on center i + * \param force_j Force on center j + * \param force_k Force on center k + * \param shf_ik Shift force between centers i and j + * \param shf_kj Shift force between centers k and j + * \param shf_c Shift force at the center subtending the angle */ template inline void spreadThreeCenterForces(T cos_theta, T force, - const gmx::BasicVector& r_ij, - const gmx::BasicVector& r_kj, + const gmx::BasicVector& dxIJ, + const gmx::BasicVector& dxKJ, gmx::BasicVector* force_i, gmx::BasicVector* force_j, gmx::BasicVector* force_k, @@ -801,16 +808,16 @@ inline void spreadThreeCenterForces(T cos_theta, { T st = force / std::sqrt(1 - cos_theta2); /* 12 */ T sth = st * cos_theta; /* 1 */ - T nrij2 = dot(r_ij, r_ij); /* 5 */ - T nrkj2 = dot(r_kj, r_kj); /* 5 */ + T nrij2 = dot(dxIJ, dxIJ); /* 5 */ + T nrkj2 = dot(dxKJ, dxKJ); /* 5 */ T cik = st / std::sqrt(nrij2 * nrkj2); /* 11 */ T cii = sth / nrij2; /* 1 */ T ckk = sth / nrkj2; /* 1 */ /* 33 */ - gmx::BasicVector f_i = cii * r_ij - cik * r_kj; - gmx::BasicVector f_k = ckk * r_kj - cik * r_ij; + gmx::BasicVector f_i = cii * dxIJ - cik * dxKJ; + gmx::BasicVector f_k = ckk * dxKJ - cik * dxIJ; gmx::BasicVector f_j = T(-1.0) * (f_i + f_k); *force_i += f_i; *force_j += f_j; @@ -824,6 +831,24 @@ inline void spreadThreeCenterForces(T cos_theta, } //! Four-center category common + +/*! \brief spread force to 4 centers + * + * \tparam T The type of vector, e.g. float, double, etc + * \param dxIJ Distance between centers i and j + * \param dxKJ Distance between centers j and k + * \param dxKL Distance between centers k and l + * \param m Cross product of \p dxIJ x \p dxKJ + * \param m Cross product of \p dxKJ x \p dxKL + * \param force_i Force on center i + * \param force_j Force on center j + * \param force_k Force on center k + * \param force_k Force on center l + * \param shf_ik Shift force between centers i and j + * \param shf_kj Shift force between centers k and j + * \param shf_lj Shift force between centers k and j + * \param shf_c Shift force at the center subtending the angle + */ template inline void spreadFourCenterForces(T force, const gmx::BasicVector& dxIJ, @@ -876,6 +901,4 @@ inline void spreadFourCenterForces(T force, } // namespace nblib -#undef NBLIB_ALWAYS_INLINE - #endif // NBLIB_LISTEDFORCES_KERNELS_HPP