api/nblib/topology.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2020, 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 /*! \inpublicapi \file
  36  * \brief
  37  * Implements nblib Topology and TopologyBuilder
  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 #ifndef NBLIB_TOPOLOGY_H
  46 #define NBLIB_TOPOLOGY_H
  47
  48 #include <vector>
  49
  50 #include "nblib/interactions.h"
  51 #include "nblib/listed_forces/definitions.h"
  52 #include "nblib/molecules.h"
  53 #include "nblib/topologyhelpers.h"
  54
  55 namespace gmx
  56 {
  57 template<typename>
  58 class ListOfLists;
  59 } // namespace gmx
  60
  61 namespace nblib
  62 {
  63
  64 /*! \inpublicapi
  65  * \ingroup nblib
  66  * \brief System Topology
  67  *
  68  * Contains all topology information meant to be used by the simulation
  69  * engine internally. Private constructor ensures that a Topology object
  70  * exists in a scope in a valid state after it has been built using a
  71  * Topology Builder.
  72  */
  73 class Topology final
  74 {
  75
  76 public:
  77     //! Returns the total number of particles in the system
  78     int numParticles() const;
  79
  80     //! Returns a vector of particle types
  81     std::vector<ParticleType> getParticleTypes() const;
  82
  83     //! Return the ParticleType ID of all particles
  84     std::vector<int> getParticleTypeIdOfAllParticles() const;
  85
  86     //! Returns a vector of particles partial charges
  87     std::vector<real> getCharges() const;
  88
  89     //! Returns exclusions in proper, performant, GROMACS layout
  90     gmx::ListOfLists<int> getGmxExclusions() const;
  91
  92     //! Returns the unique ID of a specific particle belonging to a molecule in the global space
  93     int sequenceID(MoleculeName moleculeName, int moleculeNr, ResidueName residueName, ParticleName particleName) const;
  94
  95     //! Returns a map of non-bonded force parameters indexed by ParticleType names
  96     NonBondedInteractionMap getNonBondedInteractionMap() const;
  97
  98     //! Returns the interaction data
  99     ListedInteractionData getInteractionData() const;
 100
 101     //! Returns the combination rule used to generate the NonBondedInteractionMap
 102     CombinationRule getCombinationRule() const;
 103
 104 private:
 105     Topology() = default;
 106
 107     friend class TopologyBuilder;
 108
 109     //! Total number of particles in the system
 110     int numParticles_;
 111     //! unique collection of ParticleTypes
 112     std::vector<ParticleType> particleTypes_;
 113     //! store an ID of each particles's type
 114     std::vector<int> particleTypeIdOfAllParticles_;
 115     //! Storage for particles partial charges
 116     std::vector<real> charges_;
 117     //! Information about exclusions.
 118     gmx::ListOfLists<int> exclusions_;
 119     //! Associate molecule, residue and particle names with sequence numbers
 120     detail::ParticleSequencer particleSequencer_;
 121     //! Map that should hold all nonbonded interactions for all particle types
 122     NonBondedInteractionMap nonBondedInteractionMap_;
 123     //! data about bonds for all supported types
 124     ListedInteractionData interactionData_;
 125     //! Combination Rule used to generate the nonbonded interactions
 126     CombinationRule combinationRule_;
 127 };
 128
 129 /*! \brief Topology Builder
 130  *
 131  * \libinternal
 132  * \ingroup nblib
 133  *
 134  * A helper class to assist building of topologies. They also ensure that
 135  * topologies only exist in a valid state within the scope of the
 136  * simulation program.
 137  *
 138  */
 139 class TopologyBuilder final
 140 {
 141 public:
 142     //! Constructor
 143     TopologyBuilder();
 144
 145     /*! \brief
 146      * Builds and Returns a valid Topology
 147      *
 148      * This function accounts for all the molecules added along with their
 149      * exclusions and returns a topology with a valid state that is usable
 150      * by the GROMACS back-end.
 151      */
 152     Topology buildTopology();
 153
 154     //! Adds a molecules of a certain type into the topology
 155     TopologyBuilder& addMolecule(const Molecule& moleculeType, int nMolecules);
 156
 157     //! Add non-bonded interaction map to the topology
 158     void addParticleTypesInteractions(const ParticleTypesInteractions& particleTypesInteractions);
 159
 160 private:
 161     //! Internally stored topology
 162     Topology topology_;
 163
 164     //! Total number of particles in the system
 165     int numParticles_;
 166
 167     //! List of molecule types and number of molecules
 168     std::vector<std::tuple<Molecule, int>> molecules_;
 169
 170     //! Builds a GROMACS-compliant performant exclusions list aggregating exclusions from all molecules
 171     gmx::ListOfLists<int> createExclusionsListOfLists() const;
 172
 173     //! Gather interaction data from molecules
 174     ListedInteractionData createInteractionData(const detail::ParticleSequencer&);
 175
 176     //! Helper function to extract quantities like mass, charge, etc from the system
 177     template<typename T, class Extractor>
 178     std::vector<T> extractParticleTypeQuantity(Extractor&& extractor);
 179
 180     //! Distinct collection of ParticleTypes
 181     std::unordered_map<std::string, ParticleType> particleTypes_;
 182
 183     //! ParticleType nonbonded parameters
 184     ParticleTypesInteractions particleTypesInteractions_;
 185 };
 186
 187 //! utility function to extract Particle quantities and expand them to the full
 188 //! array of length numParticles()
 189 template<class F>
 190 inline auto expandQuantity(const Topology& topology, F&& particleTypeExtractor)
 191 {
 192     using ValueType = decltype((std::declval<ParticleType>().*std::declval<F>())());
 193
 194     std::vector<ValueType> ret;
 195     ret.reserve(topology.numParticles());
 196
 197     const std::vector<ParticleType>& particleTypes = topology.getParticleTypes();
 198
 199     for (size_t id : topology.getParticleTypeIdOfAllParticles())
 200     {
 201         ret.push_back((particleTypes[id].*particleTypeExtractor)());
 202     }
 203
 204     return ret;
 205 }
 206
 207 } // namespace nblib
 208
 209 #endif // NBLIB_TOPOLOGY_H