1. ExTASY-Project Avatar ExTASY-Project
  2. ExTASY
  3. MIST

Wiki

Clone wiki

MIST / Adding Integrators to MIST

View History

This section details the steps required to add new integrators into the MIST library.

Page Table of Contents

Class-level documentation

Comprehensive documentation for the MIST library, auto-generated using Doxygen, can be generated by running doxygen in the MIST root directory. It may be helpful to refer to while following the steps below.

Adding Integrators to MIST

Adding new integrators into MIST allows you to provide a new integrator for all the supported MD applications - i.e. LAMMPS, Amber, GROMACS and NAMD_Lite - by just introducing two new C++ files. This page is will guide you through the steps to add a new integrator to the MIST library. Throughout the information the new integrator is referred to as MyIntegrator.

This following steps basically need to be taken:

  1. Add a new integrator file MyIntegrator.cpp, providing the algorithm for your integrator.
  2. Create a MyIntegrator.h file, declaring the integrator as a class.
  3. Update mist.cpp to optionally create an instance of the new integrator class.
  4. Modify the Makefile.am.
  5. Build the MIST library.
  6. Build your application(s).

These steps are outlined in detail below.

Create files for the new integrator: MyIntegrator.cpp and MyIntegrator.h

Choose a name for the integrator and create MyIntegrator.cpp and MyIntegrator.h using the template code below which are also included in the MIST git repository:

These codes are written in C++.

MyIntegrator.h

/*******************************************************************************
*                                                                              *
*             MIST - Molecular Integration Simulation Toolkit                  *
*         A library of integration algorithms for Molecular Dynamics           *
*                                                                              *
*            Copyright (c) 2014-2020, The University of Edinburgh              *
*                            All rights reserved.                              *
*                     List of contributors in AUTHORS                          *
*                                                                              *
*            MIST is free software.  See LICENSE for details                   *
*                                                                              *
*******************************************************************************/

#ifndef MIST_MYINTEGRATOR_H
#define MIST_MYINTEGRATOR_H

#include "Integrator.h"

class MyIntegrator : public Integrator
{
  public:
    MyIntegrator(Param *p);
    virtual ~MyIntegrator();

    void Step(double dt);
};

#endif

Here, MyIntegrator() is the default constructor which takes the parameter p as a pointer to the parameter which have been read from the mist.params file. To retrieve the values associated with a particular parameter use the functions getParamDoubleValue() , getParamStringValue() etc. See params.h for details.

MyIntegrator.cpp

/*******************************************************************************
*                                                                              *
*             MIST - Molecular Integration Simulation Toolkit                  *
*         A library of integration algorithms for Molecular Dynamics           *
*                                                                              *
*            Copyright (c) 2014-2020, The University of Edinburgh              *
*                            All rights reserved.                              *
*                     List of contributors in AUTHORS                          *
*                                                                              *
*            MIST is free software.  See LICENSE for details                   *
*                                                                              *
*******************************************************************************/

#include “MyIntegrator.h"
#include "System.h"
#include <iostream>

MyIntegrator::MyIntegrator(Param *p) : Integrator(p)
{
    std::cout << "MIST: Using MyIntegrator" << std::endl;
}

MyIntegrator::~MyIntegrator() {}

void MyIntegrator::Step(double dt)
{
    // Add in your integrator algorithm here

    // Ensure you update velocity, position, and use updated forces

    //VelocityStep(double dt);
    //VelocityStep updates the velocity using v(t+dt)=v(t)+a(t)*dt
    //To change your timestep size, pass VelocityStep fractions of dt (e.g. 0.5*dt)

    //PositionStep(double dt);
    //PositionStep updates the position using x(t+dt)=x(t)+v(t)*dt
    //To change your timestep size, pass PositionStep fractions of dt (e.g. 0.5*dt)

    //Compute and update your forces using the following:
    system->UpdateForces();

}

Implementing the integrator

The purpose of the Step() function in an Integrator class is to integrate the positions and velocities from time t to t+dt - how you do this is up to you. Convenience functions for updates to all positions and velocities are provided in the Integrator base class:

void Integrator::PositionStep(double dt)
void Integrator::VelocityStep(double dt)
If your algorithm requires it you may use the GetPosition() / SetPosition() and GetVelocity() / SetVelocity() functions from the System class directly:

  • GetPosition(int i) - returns a Vector3 of the position of particle i.
  • SetPosition(int i, Vector3 p) - set the position of the ith particle with the contents of p.
  • GetVelocity(int i) - get the velocity, as a Vector3, of particle i.
  • SetVelocity(int i, Vector3 p) - set the velocity of the ith particle with the contents of p.

You can also update the forces acting on a particle by using:

  • system->UpdateForces() - this will calculate the forces based on the current particle positions.

You can also use (bond) constraints, these are resolved by the functions

void Integrator::ResolveConstraints_pos(double dt)
void Integrator::ResolveConstraints_vel(double dt)

more information on how to use constraints can be found in README_constraints. See the implementation of the LangevinBAOAB as an example. N.B. You should not need to make any changes to Integrator.cpp.

The next step is to link up these new files with the rest of the MIST package.

Update mist.cpp

In mist.cpp add:

#include "MyIntegrator.h"

Add the new Integrator as a recognised integrator type (from line 65 onwards), by adding a conditional for the name of integrator:

else if (strcasecmp(type, "myintegrator") == 0)
  {
  integrator = new MyIntegrator(p);
  }

Include new integrator in Makefile.am

In Makefile.am, edit the libmist_a_SOURCES line to include your integrator:

libmist_a_SOURCES = ConstraintSolver.cpp\
                    ContinuousTempering.cpp \
                    ContinuousTempering_TAMD.cpp \
                    Integrator.cpp \
                    IO.cpp \
                    LangevinBAOABIntegrator.cpp \
                    LeapfrogIntegrator.cpp \
                    mist.cpp \
                    MIST_Random.cpp \
                    params.c \
                    System.cpp \
                    TAMD.cpp \
                    VerletIntegrator.cpp \
                    Yoshida4Integrator.cpp \
                    Yoshida8Integrator.cpp \
                    MyIntegrator.cpp

Regenerate the Makefiles by running autoreconf in the mist root directory.

Recompile the applications

To use the new integrator you will need to recompile the mist library and rebuild your chosen code to link the updated library.

N.B. You do NOT need to re-patch the application.

For GROMACS, simply repeat the make and make install steps.

The mist.params file

To use the new integrator the mist.params file needs to be adapted accordingly: 

# Select which integration algorithm to use
integrator  myintegrator

For more details on compiling and installing MIST see: https://bitbucket.org/extasy-project/mist/wiki/Installing%20MIST

Up: Home; Previous: Constraints with MIST; Next: Testing MIST

Updated