Line data    Source code

       1             : // Copyright (C) 2015 Technische Universitaet Muenchen
       2             : // This file is part of the Mamico project. For conditions of distribution
       3             : // and use, please see the copyright notice in Mamico's main folder, or at
       4             : // www5.in.tum.de/mamico
       5             : #ifndef _MOLECULARDYNAMICS_COUPLING_MDSOLVERINTERFACE_H_
       6             : #define _MOLECULARDYNAMICS_COUPLING_MDSOLVERINTERFACE_H_
       7             : 
       8             : namespace coupling {
       9             : namespace interface {
      10             : template <class LinkedCell, unsigned int dim> class MDSolverInterface;
      11             : }
      12             : } // namespace coupling
      13             : 
      14             : #include "coupling/indexing/IndexingService.h"
      15             : #include "coupling/interface/Molecule.h"
      16             : #include "coupling/interface/MoleculeIterator.h"
      17             : #include "tarch/la/Vector.h"
      18             : #include <list>
      19             : 
      20             : /** This class provides
      21             :  *      @brief interface to the MD simulation
      22             :  *      @tparam dim Number of dimensions; it can be 1, 2 or 3
      23             :  *  @author Philipp Neumann
      24             :  */
      25          36 : template <class LinkedCell, unsigned int dim> class coupling::interface::MDSolverInterface {
      26             : public:
      27             :   using CellIndex_T = I11;
      28             : 
      29             :   /** Destructor */
      30          32 :   virtual ~MDSolverInterface() {}
      31             : 
      32             :   /** This function specifies a particular linked cell inside a coupling
      33             :    *cell. The coupling cells are currently located on the same process as the
      34             :    *respective linked cells. However, several linked cells may be part of a
      35             :    *coupling cell. The coupling cells also contain a ghost layer which
      36             :    *surrounds each local domain; the very first coupling cell inside the
      37             :    *global MD domain (or local MD domain) is thus given by coordinates (1,1,1)
      38             :    *(or (1,1) in 2D, respectively). The index linkedCellInCouplingCell
      39             :    *corresponds to the coordinates of the linked cell inside the given
      40             :    *coupling cell. These coordinates thus lie in a range
      41             :    *(0,linkedCellsPerCouplingCell-1).
      42             :    *    @param couplingCellIndex
      43             :    *    @param linkedCellInCouplingCell
      44             :    *    @param linkedCellsPerCouplingCell
      45             :    *    @returns a particular linked cell inside a coupling cell.
      46             :    */
      47             :   virtual LinkedCell& getLinkedCell(const CellIndex_T& couplingCellIndex, const tarch::la::Vector<dim, unsigned int>& linkedCellInCouplingCell,
      48             :                                     const tarch::la::Vector<dim, unsigned int>& linkedCellsPerCouplingCell) = 0;
      49             : 
      50             :   /** This function specifies the global size of the box-shaped MD domain
      51             :    *  @returns the global size of the box-shaped MD domain */
      52             :   virtual tarch::la::Vector<dim, double> getGlobalMDDomainSize() const = 0;
      53             : 
      54             :   /** This function determines the offset (i.e. lower,left corner) of MD domain
      55             :    *  @returns the offset (i.e. lower,left corner) of MD domain */
      56             :   virtual tarch::la::Vector<dim, double> getGlobalMDDomainOffset() const = 0;
      57             : 
      58             :   /** This function specifies the mass of a single fluid molecule
      59             :    *  @returns the mass of a single fluid molecule */
      60             :   virtual double getMoleculeMass() const = 0;
      61             : 
      62             :   /**
      63             :    *  @returns Boltzmann's constant */
      64             :   virtual double getKB() const = 0;
      65             : 
      66             :   /**
      67             :    *  @returns the sigma parameter of the Lennard-Jones potential
      68             :    */
      69             :   virtual double getMoleculeSigma() const = 0;
      70             : 
      71             :   /**
      72             :    *  @returns the epsilon parameter of the Lennard-Jones potential */
      73             :   virtual double getMoleculeEpsilon() const = 0;
      74             : 
      75             :   /** This function sets a random velocity in the vector 'initialVelocity'. This
      76             :    *velocity is sampled from a Maxwellian assuming a mean flow velocity
      77             :    *'meanVelocity' and a temperature 'temperature' of the fluid.
      78             :    *    @param meanVelocity
      79             :    *    @param kB
      80             :    *    @param temperature
      81             :    *    @param initialVelocity
      82             :    */
      83             :   virtual void getInitialVelocity(const tarch::la::Vector<dim, double>& meanVelocity, const double& kB, const double& temperature,
      84             :                                   tarch::la::Vector<dim, double>& initialVelocity) const = 0;
      85             : 
      86             :   /** This function deletes the molecule from the MD simulation
      87             :    *    @param molecule
      88             :    *    @param cell
      89             :    */
      90             :   virtual void deleteMoleculeFromMDSimulation(const coupling::interface::Molecule<dim>& molecule, LinkedCell& cell) = 0;
      91             : 
      92             :   /** This function adds the molecule to the MD simulation.
      93             :    *    @param molecule
      94             :    */
      95             :   virtual void addMoleculeToMDSimulation(const coupling::interface::Molecule<dim>& molecule) = 0;
      96             : 
      97             :   /** This function sets up the potential energy landscape over the domain
      98             :    *spanned by indexOfFirstCouplingCell and rangeCoordinates. The first
      99             :    *vector denotes the position of the lower,left,front corner of the domain,
     100             :    *rangeCoordinates the number of coupling cells in each spatial direction
     101             :    *in which the potential energy needs to be computed.
     102             :    *    @param indexOfFirstCouplingCell
     103             :    *    @param rangeCouplingCells
     104             :    *    @param linkedCellsPerCouplingCell
     105             :    */
     106             :   virtual void setupPotentialEnergyLandscape(const tarch::la::Vector<dim, unsigned int>& indexOfFirstCouplingCell,
     107             :                                              const tarch::la::Vector<dim, unsigned int>& rangeCouplingCells,
     108             :                                              const tarch::la::Vector<dim, unsigned int>& linkedCellsPerCouplingCell) = 0;
     109             : 
     110             :   /** This function specifies the local index vector (w.r.t. lexicographic
     111             :    *ordering of the linked cells in the MD simulation, for the linked cell that
     112             :    *the position 'position' belongs to. This method is crucial for the USHER
     113             :    *particle insertion scheme as we need to loop over all neighboured linked
     114             :    *cells and the cell itself to determine potential energy and forces acting on
     115             :    *the molecule at position 'position'.
     116             :    *    @param position
     117             :    *    @return the local index vector for the linked cell that the position
     118             :    *'position' belongs to
     119             :    *    @sa getLinkedCell()
     120             :    */
     121             :   virtual tarch::la::Vector<dim, unsigned int> getLinkedCellIndexForMoleculePosition(const tarch::la::Vector<dim, double>& position) = 0;
     122             : 
     123             :   /** This function assumes that a molecule is placed somewhere inside the
     124             :    *linked cell at index 'linkedCellIndex' and computes the force and potential
     125             :    *energy contributions from all molecules in the same linked cell and the
     126             :    *neighboured linked cells onto this molecule. The molecule "molecule" is
     127             :    *considered to NOT be part of the simulation domain and thus the linked
     128             :    *cells. Therefore, another molecule inside the linked cells may even coincide
     129             :    *with "molecule". The results are stored within the molecule.
     130             :    *    @param molecule
     131             :    */
     132             :   virtual void calculateForceAndEnergy(coupling::interface::Molecule<dim>& molecule) = 0;
     133             : 
     134             :   /** This function is called each time when MaMiCo tried to insert/ delete
     135             :    * molecules from the MD simulation. As a consequence, a synchronization
     136             :    * between processes or with local boundary data might be necessary. Example:
     137             :    * If in the lower left cell of a 2D MD simulation a molecule was inserted and
     138             :    * we use periodic boundary conditions, we need to provide the inserted
     139             :    * molecule (amongst others) to the upper right cell by adding this molecule
     140             :    * to the ghost boundary layer (when using the builtin MD simulation). For the
     141             :    * builtin MD simulation, the implementation of this method clears all
     142             :    * molecules from the ghost layers and re-fills the ghost layers again.
     143             :    */
     144             :   virtual void synchronizeMoleculesAfterMassModification() = 0;
     145             : 
     146             :   /** This function is called each time when MaMiCo tried to insert momentum in
     147             :    * the MD simulation. For the builtin MD simulation, this method is empty as
     148             :    * the simulation does not need to synchronize changing momentum over the
     149             :    * processes within a timestep (only the positions and numbers of molecules in
     150             :    * possible ghost layers matter!). However, other solvers might need to
     151             :    * implement something in here.
     152             :    */
     153             :   virtual void synchronizeMoleculesAfterMomentumModification() = 0;
     154             : 
     155             :   /**
     156             :    *  @returns the timestep of the MD simulation
     157             :    */
     158             :   virtual double getDt() = 0;
     159             : 
     160             :   /**
     161             :    *    @param cell
     162             :    *  @returns a new molecule iterator for a certain linked cell
     163             :    */
     164             :   virtual coupling::interface::MoleculeIterator<LinkedCell, dim>* getMoleculeIterator(LinkedCell& cell) = 0;
     165             : };
     166             : 
     167             : #endif // _MOLECULARDYNAMICS_COUPLING_MDSOLVERINTERFACE_H_