libhoomd/data_structures/SystemDefinition.h

   1 /*
   2 Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
   3 (HOOMD-blue) Open Source Software License Copyright 2009-2014 The Regents of
   4 the University of Michigan All rights reserved.
   5
   6 HOOMD-blue may contain modifications ("Contributions") provided, and to which
   7 copyright is held, by various Contributors who have granted The Regents of the
   8 University of Michigan the right to modify and/or distribute such Contributions.
   9
  10 You may redistribute, use, and create derivate works of HOOMD-blue, in source
  11 and binary forms, provided you abide by the following conditions:
  12
  13 * Redistributions of source code must retain the above copyright notice, this
  14 list of conditions, and the following disclaimer both in the code and
  15 prominently in any materials provided with the distribution.
  16
  17 * Redistributions in binary form must reproduce the above copyright notice, this
  18 list of conditions, and the following disclaimer in the documentation and/or
  19 other materials provided with the distribution.
  20
  21 * All publications and presentations based on HOOMD-blue, including any reports
  22 or published results obtained, in whole or in part, with HOOMD-blue, will
  23 acknowledge its use according to the terms posted at the time of submission on:
  24 http://codeblue.umich.edu/hoomd-blue/citations.html
  25
  26 * Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
  27 http://codeblue.umich.edu/hoomd-blue/
  28
  29 * Apart from the above required attributions, neither the name of the copyright
  30 holder nor the names of HOOMD-blue's contributors may be used to endorse or
  31 promote products derived from this software without specific prior written
  32 permission.
  33
  34 Disclaimer
  35
  36 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
  37 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  38 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
  39 WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.
  40
  41 IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  42 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  43 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  44 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  45 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  46 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  47 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  48 */
  49
  50 // Maintainer: joaander
  51
  52 /*! \file SystemDefinition.h
  53     \brief Defines the SystemDefinition class
  54  */
  55
  56 #ifdef NVCC
  57 #error This header cannot be compiled by nvcc
  58 #endif
  59
  60 #include "ParticleData.h"
  61 #include "WallData.h"
  62 #include "RigidData.h"
  63 #include "IntegratorData.h"
  64 #include "BondedGroupData.h"
  65
  66 #include <boost/shared_ptr.hpp>
  67
  68 #ifndef __SYSTEM_DEFINITION_H__
  69 #define __SYSTEM_DEFINITION_H__
  70
  71 #ifdef ENABLE_MPI
  72 //! Forward declaration of Communicator
  73 class Communicator;
  74 #endif
  75
  76 //! Forward declaration of SnapshotSytemData
  77 class SnapshotSystemData;
  78
  79 //! Container class for all data needed to define the MD system
  80 /*! SystemDefinition is a big bucket where all of the data defining the MD system goes.
  81     Everything is stored as a shared pointer for quick and easy access from within C++
  82     and python without worrying about data management.
  83
  84     <b>Background and intended usage</b>
  85
  86     The most fundamental data structure stored in SystemDefinition is the ParticleData.
  87     It stores essential data on a per particle basis (position, velocity, type, mass, etc...)
  88     as well as defining the number of particles in the system and the simulation box. Many other
  89     data structures in SystemDefinition also refer to particles and store other data related to
  90     them (i.e. BondData lists bonds between particles). These will need access to information such
  91     as the number of particles in the system or potentially some of the per-particle data stored
  92     in ParticleData. To facilitate this, ParticleData will always be initialized \b fist and its
  93     shared pointer can then be passed to any future data structure in SystemDefinition that needs
  94     such a reference.
  95
  96     More generally, any data structure class in SystemDefinition can potentially reference any other,
  97     simply by giving the shared pointer to the referenced class to the constructor of the one that
  98     needs to refer to it. Note that using this setup, there can be no circular references. This is a
  99     \b good \b thing ^TM, as it promotes good separation and isolation of the various classes responsibilities.
 100
 101     In rare circumstances, a references back really is required (i.e. notification of referring classes when
 102     ParticleData resorts particles). Any event based notifications of such should be managed with boost::signals2.
 103     Any ongoing references where two data structure classes are so interwoven that they must constantly refer to
 104     each other should be avoided (consider merging them into one class).
 105
 106     <b>Initializing</b>
 107
 108     A default constructed SystemDefinition is full of NULL shared pointers. Such is intended to be assigned to
 109     by one created by a SystemInitializer.
 110
 111     Several other default constructors are provided, mainly to provide backward compatibility to unit tests that
 112     relied on the simple initialization constructors provided by ParticleData.
 113
 114     \ingroup data_structs
 115 */
 116 class SystemDefinition
 117     {
 118     public:
 119         //! Constructs a NULL SystemDefinition
 120         SystemDefinition();
 121         //! Conctructs a SystemDefinition with a simply initialized ParticleData
 122         SystemDefinition(unsigned int N,
 123                          const BoxDim &box,
 124                          unsigned int n_types=1,
 125                          unsigned int n_bond_types=0,
 126                          unsigned int n_angle_types=0,
 127                          unsigned int n_dihedral_types=0,
 128                          unsigned int n_improper_types=0,
 129                          boost::shared_ptr<ExecutionConfiguration> exec_conf=boost::shared_ptr<ExecutionConfiguration>(new ExecutionConfiguration()),
 130                          boost::shared_ptr<DomainDecomposition> decomposition=boost::shared_ptr<DomainDecomposition>());
 131
 132         //! Construct from a snapshot
 133         SystemDefinition(boost::shared_ptr<const SnapshotSystemData> snapshot,
 134                          boost::shared_ptr<ExecutionConfiguration> exec_conf=boost::shared_ptr<ExecutionConfiguration>(new ExecutionConfiguration()),
 135                          boost::shared_ptr<DomainDecomposition> decomposition=boost::shared_ptr<DomainDecomposition>());
 136
 137         //! Set the dimensionality of the system
 138         void setNDimensions(unsigned int);
 139
 140         //! Get the dimensionality of the system
 141         unsigned int getNDimensions() const
 142             {
 143             return m_n_dimensions;
 144             }
 145         //! Get the particle data
 146         boost::shared_ptr<ParticleData> getParticleData() const
 147             {
 148             return m_particle_data;
 149             }
 150         //! Get the bond data
 151         boost::shared_ptr<BondData> getBondData() const
 152             {
 153             return m_bond_data;
 154             }
 155         //! Get the wall data
 156         boost::shared_ptr<WallData> getWallData() const
 157             {
 158             return m_wall_data;
 159             }
 160         //! Get the rigid body data
 161         boost::shared_ptr<RigidData> getRigidData() const
 162             {
 163             return m_rigid_data;
 164             }
 165         //! Access the angle data defined for the simulation
 166         boost::shared_ptr<AngleData> getAngleData()
 167             {
 168             return m_angle_data;
 169             }
 170         //! Access the dihedral data defined for the simulation
 171         boost::shared_ptr<DihedralData> getDihedralData()
 172             {
 173             return m_dihedral_data;
 174             }
 175         //! Access the improper data defined for the simulation
 176         boost::shared_ptr<ImproperData> getImproperData()
 177             {
 178             return m_improper_data;
 179             }
 180
 181         //! Returns the integrator variables (if applicable)
 182         boost::shared_ptr<IntegratorData> getIntegratorData()
 183             {
 184             return m_integrator_data;
 185             }
 186
 187         //! Helper for python memory managment in init.reset
 188         long getPDataRefs()
 189             {
 190             return m_particle_data.use_count();
 191             }
 192
 193         //! Return a snapshot of the current system data
 194         boost::shared_ptr<SnapshotSystemData> takeSnapshot(bool particles,
 195                                                            bool bonds,
 196                                                            bool angles,
 197                                                            bool dihedrals,
 198                                                            bool impropers,
 199                                                            bool rigid,
 200                                                            bool walls,
 201                                                            bool integrators);
 202
 203         //! Re-initialize the system from a snapshot
 204         void initializeFromSnapshot(boost::shared_ptr<SnapshotSystemData> snapshot);
 205
 206     private:
 207         unsigned int m_n_dimensions;                        //!< Dimensionality of the system
 208         boost::shared_ptr<ParticleData> m_particle_data;    //!< Particle data for the system
 209         boost::shared_ptr<BondData> m_bond_data;            //!< Bond data for the system
 210         boost::shared_ptr<WallData> m_wall_data;            //!< Wall data for the system
 211         boost::shared_ptr<RigidData> m_rigid_data;          //!< Rigid bodies data for the system
 212         boost::shared_ptr<AngleData> m_angle_data;          //!< Angle data for the system
 213         boost::shared_ptr<DihedralData> m_dihedral_data;    //!< Dihedral data for the system
 214         boost::shared_ptr<ImproperData> m_improper_data;    //!< Improper data for the system
 215         boost::shared_ptr<IntegratorData> m_integrator_data;    //!< Integrator data for the system
 216     };
 217
 218 //! Exports SystemDefinition to python
 219 void export_SystemDefinition();
 220
 221 #endif