api/nblib/molecules.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2020,2021, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \file
  36  * \brief
  37  * Implements nblib Molecule
  38  *
  39  * \author Victor Holanda <victor.holanda@cscs.ch>
  40  * \author Joe Jordan <ejjordan@kth.se>
  41  * \author Prashanth Kanduri <kanduri@cscs.ch>
  42  * \author Sebastian Keller <keller@cscs.ch>
  43  * \author Artem Zhmurov <zhmurov@gmail.com>
  44  *
  45  * \inpublicapi
  46  * \ingroup nblib
  47  */
  48 #ifndef NBLIB_MOLECULES_H
  49 #define NBLIB_MOLECULES_H
  50
  51 #include <string>
  52 #include <tuple>
  53 #include <unordered_map>
  54 #include <vector>
  55
  56 #include "nblib/listed_forces/definitions.h"
  57 #include "nblib/particletype.h"
  58
  59 namespace nblib
  60 {
  61 class TopologyBuilder;
  62
  63 //! Named type for unique identifier for a particle in a molecule
  64 using ParticleName = StrongType<std::string, struct ParticleNameParameter>;
  65
  66 //! Named type for charges on a particle within a molecule
  67 using Charge = StrongType<real, struct ChargeParameter>;
  68
  69 //! Named type for residue name used to diffentiate between sections of a molecule
  70 using ResidueName = StrongType<std::string, struct ResidueNameParameter>;
  71
  72 //! Named type for the name of a molecule
  73 using MoleculeName = StrongType<std::string, struct MoleculeNameParameter>;
  74
  75 struct ParticleData
  76 {
  77     std::string particleName_;
  78     std::string residueName_;
  79     std::string particleTypeName_;
  80     real        charge_;
  81 };
  82
  83 //! \brief uniquely identifies a particle within a Molecule
  84 class ParticleIdentifier final
  85 {
  86 public:
  87     //! \brief construct form a ParticleName, allow implicit conversion
  88     ParticleIdentifier(ParticleName particleName) :
  89         particleName_(std::move(particleName)), residueName_()
  90     {
  91     }
  92
  93     //! \brief construct with a non-default ResidueName
  94     ParticleIdentifier(ParticleName particleName, ResidueName residueName) :
  95         particleName_(std::move(particleName)), residueName_(std::move(residueName))
  96     {
  97     }
  98
  99     [[nodiscard]] const ParticleName& particleName() const { return particleName_; }
 100     [[nodiscard]] const ResidueName&  residueName() const { return residueName_; }
 101
 102 private:
 103     ParticleName particleName_;
 104     ResidueName  residueName_;
 105
 106     friend inline bool operator==(const ParticleIdentifier& lhs, const ParticleIdentifier& rhs)
 107     {
 108         return lhs.particleName_ == rhs.particleName_ && lhs.residueName_ == rhs.residueName_;
 109     }
 110 };
 111
 112 //! \brief Molecule class that holds particles and their bonded interactions
 113 class Molecule final
 114 {
 115     //! \brief per-InteractionType storage container for listed interaction with string-based particle IDs
 116     template<class InteractionType>
 117     struct InteractionTypeData
 118     {
 119         using type           = InteractionType;
 120         using IdentifierType = Repeat<TypeList<ParticleName, ResidueName>, NCenter<InteractionType>{}>;
 121
 122         std::vector<InteractionType>                    interactionTypes_;
 123         std::vector<Reduce<std::tuple, IdentifierType>> interactions_;
 124     };
 125
 126     //! this creates a tuple containing an instance of InteractionType data for each supported listed type
 127     using InteractionTuple = Reduce<std::tuple, Map<InteractionTypeData, SupportedListedTypes>>;
 128
 129     //! \brief returns the default residue name if necessary
 130     ResidueName residueName(const ParticleIdentifier& particleIdentifier);
 131
 132     //! \brief adds an interaction to the InteractionTuple
 133     template<class ListedVariant, class... ParticleIdentifiers>
 134     void addInteractionImpl(const ListedVariant& interaction, const ParticleIdentifiers&... particles);
 135
 136 public:
 137     explicit Molecule(MoleculeName moleculeName);
 138
 139     //! Add a particle to the molecule with full specification of parameters.
 140     Molecule& addParticle(const ParticleName& particleName,
 141                           const ResidueName&  residueName,
 142                           const Charge&       charge,
 143                           ParticleType const& particleType);
 144
 145     //! Add a particle to the molecule with implicit charge of 0
 146     Molecule& addParticle(const ParticleName& particleName,
 147                           const ResidueName&  residueName,
 148                           ParticleType const& particleType);
 149
 150     //! \brief Add a particle to the molecule with residueName set using particleName
 151     Molecule& addParticle(const ParticleName& particleName, const Charge& charge, ParticleType const& particleType);
 152
 153     //! \brief Add a particle to the molecule with residueName set using particleName with implicit charge of 0
 154     Molecule& addParticle(const ParticleName& particleName, const ParticleType& particleType);
 155
 156     /*! \brief Specify an exclusion between two particles that have been added to the molecule
 157      *
 158      * Exclusion of a particle with itself is detected and handled correctly.
 159      * Note that adding an exclusion between particles not present in the Molecule will \throw an
 160      * exception.
 161      */
 162     void addExclusion(const ParticleIdentifier& particle, const ParticleIdentifier& particleToExclude);
 163
 164     /*! \brief Add 2-particle interactions such as harmonic bonds
 165      *
 166      * Note that adding an interaction between particles not present in the Molecule will \throw an
 167      * exception.
 168      */
 169     void addInteraction(const ParticleIdentifier&   particleI,
 170                         const ParticleIdentifier&   particleJ,
 171                         const TwoCenterInteraction& interaction);
 172
 173     //! \brief Add 3-particle interactions such as angles
 174     void addInteraction(const ParticleIdentifier&     particleI,
 175                         const ParticleIdentifier&     particleJ,
 176                         const ParticleIdentifier&     particleK,
 177                         const ThreeCenterInteraction& interaction);
 178
 179     //! \brief Add 4-particle interactions such as (im)proper-dihedrals
 180     void addInteraction(const ParticleIdentifier&    particleI,
 181                         const ParticleIdentifier&    particleJ,
 182                         const ParticleIdentifier&    particleK,
 183                         const ParticleIdentifier&    particleL,
 184                         const FourCenterInteraction& interaction);
 185
 186     //! \brief Add 5-particle interactions such as CMAP
 187     void addInteraction(const ParticleIdentifier&    particleI,
 188                         const ParticleIdentifier&    particleJ,
 189                         const ParticleIdentifier&    particleK,
 190                         const ParticleIdentifier&    particleL,
 191                         const ParticleIdentifier&    particleM,
 192                         const FiveCenterInteraction& interaction);
 193
 194     //! \brief The number of molecules
 195     int numParticlesInMolecule() const;
 196
 197     //! \brief Return the ParticleType data for a specific particle name that has been added to the molecule
 198     const ParticleType& at(const std::string& particlesTypeName) const;
 199
 200     /*! \brief access integer-based exclusions
 201      *
 202      * Convert exclusions given by name to indices and unify with exclusions given by indices
 203      * returns a sorted vector containing no duplicates of particles to exclude by indices
 204      */
 205     std::vector<std::tuple<int, int>> getExclusions() const;
 206
 207     //! \brief Return all interactions stored in Molecule
 208     const InteractionTuple& interactionData() const;
 209
 210     //! \brief Return name of i-th particle
 211     ParticleName particleName(int i) const;
 212
 213     //! \brief Return name of i-th residue
 214     ResidueName residueName(int i) const;
 215
 216     //! \brief Return array of data structs on particle types
 217     std::vector<ParticleData> particleData() const;
 218
 219     //! \brief Return map of particle types and their names
 220     std::unordered_map<std::string, ParticleType> particleTypesMap() const;
 221
 222     //! \brief The molecule name
 223     MoleculeName name() const;
 224
 225 private:
 226     //! Name of the molecule
 227     MoleculeName name_;
 228
 229     //! one entry per particle in molecule
 230     std::vector<ParticleData> particles_;
 231
 232     //! collection of distinct particle types in molecule
 233     std::unordered_map<std::string, ParticleType> particleTypes_;
 234
 235     //! Used for calculated exclusions based on particle indices in molecule
 236     std::vector<std::tuple<int, int>> exclusions_;
 237
 238     //! we cannot efficiently compute indices during the build-phase
 239     //! so we delay the conversion until TopologyBuilder requests it
 240     std::vector<std::tuple<std::string, std::string, std::string, std::string>> exclusionsByName_;
 241
 242     //! collection of data for all types of interactions
 243     InteractionTuple interactionData_;
 244 };
 245
 246 } // namespace nblib
 247 #endif // NBLIB_MOLECULES_H