################################################################################
#
#   MD/OPX README
#
#   Yinglong Miao
#   Center for Cell and Virus Theory
#   Department of Chemistry
#   Indiana University, Bloomington, USA
#   yimiao@indiana.edu 
#
#   Last updated: 6/12/2008
#
################################################################################

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 MD/OPX is implemented 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.

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

* Modify NAMD code (available through
http://www.ks.uiuc.edu/Research/namd/) 
  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 verions NAMD 2.6) for running MD/OPX simulation. 
  Please refer to the NAMD documents for compiling and installation
instructions.

* Compile Fortran 90 code under "AMAf90" 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 the current directory 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 simulation parameters in file "ama_para.dat" with the following
format
  in three lines (see parameter expanations in "ama_para.tcl"):
  ----------------------
  molname
  InitMinsteps InitMDsteps MDsteps4x OPtimestep MinOPsteps MDOPsteps
LSF npts a_avg_tol_min a_max_tol_run polynomial order nreplicas
  cycle t_start t_end
  ----------------------

  See a sample file under directory "tests/1cwp-vmd-H-MDOPX/"

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

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

* 1cwp-vmd-H-MDOPX: CCMV protomer (X-ray crystal structure downloaded
from PDB)
  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
* "${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.

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
#