Compile dependencies
- CMake, 2.8+
- C++11 compiler, such as GCC 4.8+
- HDF5, 1.8+ with high-level interface compile option
- Eigen Matrix Library, 3.0+
Python dependencies. Depending on your use-case for Upside, you may not need all of these libraries. The error message in case of a missing library should be clear enough to figure out.
- Python 3.7+
- Numpy
- Scipy (sometimes needed for
upside_config.py, depending on options) - PyTables (needed for reading HDF5 files from Python)
- Prody (needed for reading .pdb files)
- Pandas (needed for
predict_chi1.py) - H5py (needed for
generate_restart_config.py) - MDTraj (optional but capable of loading and analyzing Upside trajectories)
- Pymbar (optional but capable of doing mbar reweighting for REMD simulations)
This guide assumes that you have all of the compile dependencies satisfied. In particular, the HDF5 high-level must be specifically enabled by a configuration switch when installing HDF5. Please check with your system administrator to ensure it is installed.
This install guide assumes that you are using Linux or OS X. Upside should install and run on Windows as well, but this has not been tested.
The build system uses CMake (www.CMake.org) to find dependencies. Please change to the root directory of the upside directory. You may change the path for Eigen and python in source_sh based on your environment. Then, just run the following commands.
./install.sh
After these commands execute successfully, the obj/ directory will contain
the upside executable and the libupside.so shared library (exact name of
shared library may depend on operating system).
The following sections illustrate running simple molecular dynamics simulations with Upside.
Starting from a PDB file, we create FASTA, position, and side chain files using
upside/py/PDB_to_initial_structure.py /path/to/input.pdb output_basename
which will create output_basename.fasta containing the FASTA sequence,
output_basename.initial.pkl containing a Python pickle file of the
coordinates of the N, CA, and C atoms of the backbone, and
output_basename.chi containing the chi1 and chi2 angles for the side chains.
The .chi file is not needed for MD simulation, unless you want to run with
inflexible side chain rotamers. PDB_to_initial_structure.py will fail if there
are breaks in the chain, as chain breaks will cause the MD to be invalid. See
--help for information on how to choose the PDB model or chains to include.
From the output of PDB_to_inital_structure.py, we can create an Upside
configuration, simulation.up. The following instructions are for a typical
folding or conformational dynamics simulation.
upside/py/upside_config.py --output simulation.up \
--fasta output_basename.fasta \
--initial-structure output_basename.initial.npy \
--hbond-energy upside/parameters/ff_2.1/hbond.h5 \
--dynamic-rotamer-1body \
--rotamer-placement upside/parameters/ff_2.1/sidechain.h5 \
--rotamer-interaction upside/parameters/ff_2.1/sidechain.h5 \
--environment-potential upside/parameters/ff_2.1/environment.h5 \
--bb-environment-potential upside/parameters/ff_2.1/bb_env.dat \
--rama-library upside/parameters/common/rama.dat \
--rama-sheet-mixing-energy upside/parameters/ff_2.1/sheet \
--reference-state-rama upside/parameters/common/rama_reference.pkl
If --initial-structure is omitted, the simulation will be initialized with
random (possibly-clashing) Ramachandran angles, which is useful for de novo
structure prediction.
The output simulation.up is an HDF5 file, and the simulation configuration is
written in the "/input" group within the .up file. The upside_config.py
copies all of the parameters into its output, so that only simulation.up is
needed to run the simulation.
A simple, constant-temperature simulation may be run with
upside/obj/upside --duration 1e7 --frame-interval 1e2 --temperature 0.85 --seed $RANDOM simulation.up
Note that the simulation results are written into the "/output" group of the
provide simulation.up file. This ensures that simulation output is stored in
the same file as the input, aiding in later reproducibility of the simulation.
The temperature, duration, and frame-interval are in natural units. The times
should not be interpreted as picoseconds. We are still investigating the
precise relationship of Upside time to experimental folding time, but the time
relationship may be conformation-dependent since the Upside backbone moves in a
smoother energy landscape than standard MD due to the side chain model.
The equilibration time of Upside simulations is highly temperature-dependent.
Typically, folding studies in Upside start with a replica exchange simulation
to establish the temperature range of the melting transition. Hamiltonian and
temperature replica exchange are handled in the same manner in Upside. First,
use upside_config.py repeatedly to create N configurations (or just copy
the output of a single upside_config.py run). To run the replica exchange on
five configurations,
upside/obj/upside --duration 1e7 --frame-interval 1e2 \
--temperature 0.5,0.53,0.56,0.60,0.64 \
--swap-set 0-1,2-3 \
--swap-set 1-2,3-4 \
--replica-interval 20 \
--monte-carlo-interval 5 \
--seed $RANDOM \
config_0.up config_1.up config_2.up config_3.up config_4.up
The multiple simulations are parallelized using OpenMP threads on a single
machine. On the SLURM scheduler, jobs should be launched with sbatch --ntasks 1 --cpus-per-task 5 for a five simulation replica exchange job. The
--replica-interval controls the frequency at which replica exchange swaps are
attempted. The --swap-sets arguments are non-overlapping pairs of replica
swaps that are attempted simultaneously. For a linear chain of temperatures,
there should always be two swap sets to ensure ergodicity of swaps without
having any overlapping pairs.
The --monte-carlo-interval controls the frequency at which pivot moves, a
discrete change in the phi and psi angles of a single, randomly-chosen residue,
are attempted. These Monte Carlo pivot moves are accepted with a Metropolis
criterion so that the Boltzmann ensemble of simulation is unchanged by pivot
moves. Typically, pivot moves are highly advantageous in replica exchange
simulation because pivot moves have high acceptance rates in high-temperature
unfolded conformations, greatly speeding the sampling of unfolded states.
Pivot moves have very low acceptance in collapsed conformations but add very
little to the computational time. The faster sampling in the unfolded states
feeds conformational diversity to the lower temperatures in replica exchange.
Monte Carlo moves are also permitted in constant temperature simulation. If
--monte-carlo-interval is not provided, pivot moves are never attempted.
The output of replica exchange is written into the "/output" group of each of
the input configurations. The replicas are written by temperature/Hamiltonian,
so that in the example above, config_0.up contains all of the simulation
frames at the temperature 0.5. This means that in the limit of infinite sampling,
config_0.up will contain samples from a Boltzmann ensemble at temperature 0.5 but
the trajectory will be discontinuous due to replica swapping.
Explore the upside/example/ folder for examples on running with restraints, membrane
simulations, pulling simulations, HDX prediction, and more.
The contents of a .up file can be listed with
upside/py/attr_overview.py simulation.up
which included copies of the full command lines used to invoke both
upside_config.py and upside.
To load the simulation in VMD, first convert to a trajectory format that VMD can read. This can be done with
upside/py/extract_vtf simulation.up simulation.vtf
and the .vtf file can be read natively by VMD. Alternatively, the MDTraj
library described below can read simulation.up directly, either to visualize
in an IPython notebook or to convert to another format. In either case, amide
hydrogen and carbonyl oxygen are added as atoms in the trajectory to aid
structure viewers.
To load the Upside trajectory as an MDTraj Trajectory object, use the
mdtraj_upside.py library in the Upside distribution.
import sys
sys.path.append('upside/py')
import mdtraj_upside as mu
traj = mu.load_upside_traj('simulation.up')
When the trajectory is loaded, the atoms H, O, and CB will be added to the trajectory.