################################################################################
#
#   MD/OPX README
#
#   Center for Cell and Virus Theory
#   Department of Chemistry
#   Indiana University, Bloomington, USA
#
#   Last updated: Oct 2008
#
################################################################################

####################
Overview
####################

MD/OPX stands for Molecular Dynamics/Order Parameter eXtrapolation. It is an 
approach designed to simulate large bionanosystems over long time periods by
using a short MD run to extrapolate the structural order parameters (OPs) of
the system over large time intervals and thus advance the system over long time.

The present implementation of MD/OPX is based on NAMD using its Tcl scripting
interface and requires NAMD for running. A Fortran code is used to read 
the output structure of a short dt NAMD run, calculate the resultant OPs, 
extrapolate the OPs for dT, generate an atomic configuration at t+dT 
with the extrapolated OPs and put the result all-atom structure back into 
NAMD to start the next (dt, dT) cycle. 

Please refer to the following paper for the theoretical details and
implementation algorithms of MD/OPX:

Miao, Y. and P.J. Ortoleva, Molecular Dynamics/Order Parameter
eXtrapolation for Bionanosystem Simulations. J. Comp. Chem, Published
Online, DOI: 10.1002/jcc.21071 (2008)
(http://www3.interscience.wiley.com/journal/120780497/abstract)

This README file includes the instructions for setting up MD/OPX, runing
and testing the program, explanations of the simulation output, and
procedures for bug reporting and help request.

####################
Setting up
####################

Setting up MD/OPX needs a successful installation of NAMD (available through
http://www.ks.uiuc.edu/Research/namd/) with its three source files updated
with those included in this package in order to allow outputting
seperate DCD files for multiple MD runs for efficient MD/OPX simulation. NAMD 
documentations can be referred to for compiling and installation instructions.
The program also needs a Fortran code compiled and installed for
doing OPX. "Makefile" is included for compiling the code. Please change
the Fortran compiler and compiling flags according to your computer
environment. 

Following are instructions for the setting up procedure:

* Modify NAMD code to allow outputting separate DCD files for multiple MD runs:
  update the following three source files with those under directory
  "namd_changes/":
  ** Output.C
  ** SimParameters.h
  ** SimParameters.C
  Compile the package and install a copy of the program ("namd2" by
  default for the latest verion NAMD 2.6) for running MD/OPX simulation. 

* Compile Fortran 90 code under "src/AMAF" directory and install the result executable
  "AMA.exe" for doing OPX in MD/OPX. Please update the Fortran compiler
  and compiling flags in the "Makefile" provided for compiling the code.

* Prepare the configuration file for running NAMD (refer to the user
  guide via http://www.ks.uiuc.edu/Research/namd/2.6/ug/). Execute the TCL scripts 
  under directory "src/" in NAMD configuration file to run MD/OPX simulation:
  ** set "amadir" to the right directory in the NAMD configuration file
  ** source "ama_para.tcl" at the beginning
  ** source "ama_namd.tcl" at the end
  ** turn on "tclForces" with
  ----------------------
  tclForces           on
  tclForcesScript     ${amadir}/ref_calcF.tcl
  ----------------------

  A sample configuraton file for running MD/OPX on CCMV protomer can be found under
  directory "tests/1cwp-vmd-H-MDOPX/" ("1cwp-vmd-H.conf")

* Set MD/OPX simulation parameters in a file named "ama_para.dat" with
  one parameter one line in the following format:

  KEYWORD VALUE (OPTIOANL COMMENT)

  The keywords are case insensitive and there is no restriction on the
  sequence for specifing the parameters.

  A sample file is like the following (included under directory
  "tests/1cwp-vmd-H-MDOPX/"):

  ----------------------
  molID           1cwp-vmd-H      # Molecule ID
  TotNatoms       7202    # Total number of atoms in the system
  StrNatoms       7202    # Number of atoms in molecular structure (i.e., system excluding water and ions)
  InitEMsteps     0       # Initial Energy Minimization steps
  InitMDsteps     0       # Initial MD steps
  MDsteps4OPX     200     # MD steps used for OPX
  OPtimestep      1000    # OP timestep
  EMOPsteps       100     # Energy Minimization steps after OPX
  MDOPsteps       1000    # MD steps used for maturing energy-minimized OPX structure
  npts            5       # Number of MD snapshots used for calculating system OPs and their extrapolation
  Atol            100     # Tolerance of maximum atomic acceleration before running maturing MD
  polynomial      legendre        # Polynomial used for constructing the system dynamic modes and OPs
  degree          3       # Degree of polynomial orders used for the construction
  nreplicaMDs     10      # Number of MD replica runs used for calculating system OPs and their extrapolation
  cycle           0       # The serial number of current cycle
  start           5000    # Simulation start time (a value greater than 0 indicates a restarted simulation)
  end             10000   # Simulation end time
  ----------------------

####################
Testing and Running
####################

Sample input files for running MD/OPX simulations are included in directory "tests":

* 1cwp-vmd-H-MDOPX: CCMV protomer (PDB ID: 1CWP)
  cd tests/1cwp-vmd-H-MDOPX/
  namd2 1cwp-vmd-H.conf

Note: make sure the force field parameter file is pointed to the right
location (check parameter "para" in the configuration file) under
directory "common/".

####################
simulation output
####################

Apart from the stardard NAMD simulation outputs, an MD/OPX simulation will output 
the following *.dat and *.dcd files assuming the base name of the simulated structure 
is "molname":
* "${molname}-out-ref.dat": file saving the reference structure information in format:
  N
  mstar
  cen
  box
  mlist
  xlist
  ylist
  zlist
* "${molname}-out-ref.bin": binary file of "${molname}-out-ref.dat"
* "${molname}-out-B.dat": file saving the B matrix calculated from the atomic
  coordinates of the reference configuration; it is used in solving the linear 
  equations for OPs.
* "${molname}-out-OP.dat":  file saving OPs calculated during the simulation
* "${molname}-out-time.dat": file recording the timestep of OPs applied in the MD/OPX cycles
* "${molname}-out-OP-*.dcd", "${molname}-out-coher-*.dcd" and "${molname}-out-sigma-*.dcd":
  DCD files recording the trajectory of the simulated structure after the 
  ${cycle}th MD/OPX cycle and its coherent structure generated with extrapolated 
  OPs and the residual.

  "${molname}-out-MinOP-*.dcd", "${molname}-out-MDOP-*.dcd" and
  "${molname}-out-MD4OPX-*.dcd":
  DCD files saved during running energy minimization, maturing MD, and
  short MD runs for OPX in each MD/OPX cycle

Files for MD/OPX simulation restart are saved at the end of each MD/OPX cycle.

####################
Tools
####################

Under directory "tools", a set of TCL scripts that can be executed with
VMD (http://www.ks.uiuc.edu/Research/vmd/) are provided to prepare the
system for MD/OPX simulation and analyze the simulation outputs.

* "solvate.tcl": 
  Generate the .psf and .pdb files from input PDB structure, solvate the
  structure in water and ionize the system with VMD to prepare the
  system for simulation

* "vmd-merge.tcl":
  Merge multiple frames of a structure, like the
  "${molname}-out-OP-*.dcd", "${molname}-out-coher-*.dcd" and
  "${molname}-out-sigma-*.dcd" output from MD/OPX simulation, into a single DCD file

####################
Problem/Bug Reporting
####################

Please email "Yinglong Miao" <yimiao@indiana.edu> regarding any problems
or bugs of the program right now. A web portal is being set up via
http://sysbio.indiana.edu. More services will be provided when it becomes
ready.

################################################################################
# MD/OPX
#
#   TCL scprits for Molecular Dynamics/Order Parameter eXtrapolation (MD/OPX)
#   simulations of large biosystems (e.g. viruses) over long periods of time
#   based on NAMD.
#
#   Yinglong Miao
#   Center for Cell and Virus Theory
#   Department of Chemistry
#   Indiana University, Bloomington, USA
#   yimiao@indiana.edu 
#
####################
#   version 0.5
####################
#
#   8/29/2007
#
#   * Use Least Squares Fitting (LSF) for OP time courses to allow larger OP time
#   step
#
#   11/14/2007
#
#   * Apply mature process after OPX
#
####################
#   version 0.6
####################
#
#   11/16/2007
#
#   * Apply adaptive timesteps to OPs in MD/OPX cycles
#   * use an ensemble of short MD runs initialized differently for OPX
#    and extrapolate the OP average values
#
#   12/12/2007
#
#   * optimize ama_cycle.tcl when OPE = 1 && NOPX > 1: read OPs instead of
#   calculating OPs again for OPX 
#
#   12/14/2007
#
#   * make sure the right snapshots are used for OPX when NOPX > 1 and
#   minimization snapshots have been appended to the dcd file
#
####################
#   version 0.7
####################
#
#   3/5/2008
#
#   * Remove calling VMD in the scripts
#   * Save atomic coordinates in binary dcd files instead of ASCII dat files
#
#
#   3/29/2008
#
#   * Use "backspace" for reading the OP file for OPX
#   * Try using direct access to read MD snapshots at the end of the DCD file
#     -> this doesn't work for binary DCD files
#
#   4/25/2008
#
#   * Modify NAMD source code to create different DCD files for multiple MD
#   runs
#
####################
#   version 0.8
####################
#
#   5/26/2008
#
#   * Extrapolate the average of OPs calculated from replica MD runs, instead
#   of the OPs calculated from a single MD run
#   * Modify NAMD source code to allow ouput different DCD files for multiple
#   MD runs
#   * Optimize the equilibration scheme of the OPX result structure
#
####################
#   version 0.9
####################
#
#   6/19/2008
#
#   * Parallelize AMA.f90 with MPI
#
####################
#   version 1.0
####################
#
#   8/22/2008
#
#   * Formulate the parameter configuration file by putting each
#   parameter in a separate line
#   * Automate the MD/OPX simulation input by outputing the parameter
#   file "ama_para.dat" through executing "solvate.tcl" with VMD
#