OpenAWSEM and Open3SPN2 are open-source, cross-compatible implementations of coarse-grained models for protein (AWSEM) and DNA (3SPN2) molecular dynamics simulations within the OpenMM framework. These new implementations retain the chemical accuracy and intrinsic efficiency of the original models, while adding GPU acceleration and the ability to easily modify the forcefield using OpenMM's Custom Forces software framework. By utilizing GPUs, OpenAWSEM and Open3SPN2 achieve a significant speedup in protein and protein-DNA simulations, making them suitable for simulating large proteins and protein-DNA systems. These codes provide a useful tool for the molecular biophysics community, facilitating the study of protein folding, protein-DNA binding, and other cellular processes.

Installation

OpenAWSEM installation

1. Make sure you have installed Git on your computer. This will allow you to clone the Openawsem repository from GitHub. You can download git from the following page: 
   https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
   
   
2. Clone the Openawsem repository using the following command:
   
   git clone https://github.com/npschafer/openawsem.git

    

3. Download and install STRIDE from the following link: 
   http://webclu.bio.wzw.tum.de/stride/
   Make sure to put the STRIDE binary in your PATH, so that you can run it from the command line.
   
   
4. Download and install psiblast from the following link: 
   ftp://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST/
   Make sure to put the psiblast binary in your PATH, so that you can run it from the command line.
   
   
5. Download the pdb_seqres.txt file from the PDB website using the following command:
   
   wget ftp://ftp.wwpdb.org/pub/pdb/derived_data/pdb_seqres.txt
   
   
6. Move the pdb_seqres.txt file to the location where you cloned the Openawsem repository.
   
   
7. Install conda or miniconda from the following link: https://conda.io/en/latest/miniconda.html. This will allow you to manage your Python environments and packages easily.
   
   
8. Create a new conda environment called openmm that includes the necessary Python packages. To do this, run the following command:
   
   conda create -n openmm python=3.6 biopython matplotlib numpy pandas
   
   
9. Set the OPENAWSEM_LOCATION environment variable to the location where you cloned the Openawsem repository. 
   This will allow Openawsem to find the necessary files and data. To set the environment variable, add the following command to .bashrc:
   
   export OPENAWSEM_LOCATION='/YOUR/OPENAWSEM/DIRECTORY/'
   
   
10. Activate the openmm environment using the following command:
    source activate openmm
    
    
11. Install additional Python packages using the following command:
    conda install -c omnia -c conda-forge openmm pdbfixer mdtraj
    
    
12. After completing these steps, you should be able to use Openawsem on your computer.

Open3SPN2 installation

1. Activate the openmm environment using the following command:
   
   source activate openmm
   
   

2. Configure the Anaconda package manager to include the omnia and conda-forge channels. This will allow you to access the necessary dependencies from these channels. To do this, run the following commands in a terminal:

   conda config --append channels omnia
   conda config --append channels conda-forge

    

3. Install open3SPN2 using the Anaconda package manager. To do this, run the following command in a terminal:

   conda install -c wolynes-lab open3spn2

    

4. Install X3DNA >= 2.4. This is necessary for open3SPN2 to run properly. To do this, follow the instructions on the X3DNA website: http://x3dna.org/

    

5. Set the X3DNA environment variable to the location of the X3DNA installation folder. This will allow open3SPN2 to find the X3DNA executables. To do this, run the following command in a terminal, replacing /path/to/x3dna-v2.4 with the actual path to the X3DNA installation folder:
   
   export X3DNA=/path/to/x3dna-v2.4
   
   
6. If you want to use open3SPN2 for protein-DNA simulations, you will also need to install openAWSEM. To do this, you must have followed the previous instruction. Also add the openAWSEM path to the PYTHONPATH environment variable. This will allow open3SPN2 to import openAWSEM modules. To do this, run the following command in a terminal, replacing /path/to/openawsem with the actual path to the openAWSEM installation folder:
   
   export PYTHONPATH=/path/to/openawsem:$PYTHONPATH
   
   
7. If you want to install open3SPN2 locally instead of using the Anaconda package manager, you can clone the open3SPN2 repository from GitHub and install it manually. To do this, run the following commands in a terminal:
   
   git clone https://github.com/cabb99/open3spn2.git
   cd open3spn2
   pip install -e .
   
   
8. After completing these steps, you should be able to use open3SPN2 on your computer. Keep in mind that you will need to set the X3DNA and PYTHONPATH environment variables every time you open a new terminal or log in to your computer. If you want these variables to be set automatically, you can add the export commands to your .bashrc file. This will set the environment variables every time you open a new terminal.

Note: Adding a location to the PATH

 To add a location to your PATH environment variable in Linux, you need to do the following:

1. Open a terminal and run the following command to open the .bashrc file in a text editor:
   
   nano ~/.bashrc
   
   
2. Scroll to the bottom of the .bashrc file and add the following line, replacing /your/path with the location you want to add to the PATH variable:
   
   export PATH=$PATH:/your/path
   
   Note: You can add any environment variable in a similar way:
   export VAR=/Some/path/
   *Don't add spaces next to the "=" sign
   
   
3. Press CTRL + X to exit the editor, then press Y to save the changes and Enter to confirm the file name.
   
   
4. Run the following command to apply the changes to the current terminal session:
   
   source ~/.bashrc
   
   
5. Verify that the location was added to the PATH variable correctly by running the following command:
   
   echo $PATH
   
   
6. You should see the new location in the list of paths that is printed to the screen. Keep in mind that you will need to open a new terminal or log out and log back in for the changes to take effect.

Note: Running python script interactively

Open3SPN2 simulations can be setup and run in python. To run a Python script interactively using Jupyter notebook, follow these steps

1. Activate the openmm environment using the following command:
   
   source activate openmm
   
   
2. Install Jupyter notebook by running the following command in your terminal:
   
   pip install jupyter
   
   
3. Once Jupyter is installed, start the Jupyter notebook server by running the following command in your terminal:
   
   jupyter notebook
   
   This will open the Jupyter dashboard in your web browser.
4. In the dashboard, you can create a new jupyter notebook.
   
   
5. Once the script is open, you can run individual code cells by clicking on them and pressing Shift+Enter. The output of the code will be displayed below the code cell.
   You can also edit the code in the cells and re-run them to see the updated output.
   
   
6. When you're done running the script, you can save your changes by clicking on the Save button in the toolbar.
   
   
7. Note: You can also run the entire script by clicking on the Run button in the toolbar, or by choosing Run > Run All from the menu. This will run all the code cells in the script in order.

Running simulations

Protein simulations

To simulate a small protein using openAWSEM, follow these steps:

1. Activate the openmm environment by running the following command in your terminal:
   
   source activate openmm
   
   
2. Set up a simulation folder for your protein by running the following command:
   
   python YOUR_OPENAWSEM_LOCATION/mm_create_project.py 1r69 --frag
   
   If you already have the PDB file for your protein, use the following command instead:
   
   python YOUR_OPENAWSEM_LOCATION/mm_create_project.py PATH_TO_YOUR_PDB/1r69.pdb --frag
   
   
3. Run the simulation using the following command:
   
   python mm_run.py 1r69 --platform CPU --steps 1e5 --tempStart 800 --tempEnd 200 -f forces_setup.py
   
   
4. To compute the energy and Q of your protein, run the following command:
   
   python mm_analysis.py 1r69 > energy.dat
   
   The qvalue can be found in the second column of energy.dat
   
   Note: The forces_setup.py file controls which force (energy) terms will be included in the simulation.
   
   Note 2: If you don't have a GPU available, you may want to consider using http://awsem-md.org. For small proteins, the LAMMPS version could be faster than openAWSEM.
   
   Note 3: Due to size limitations, the data for the paper "OpenAWSEM with Open3SPN2: a fast, flexible, and accessible framework for large-scale coarse-grained biomolecular simulations" is stored in https://app.globus.org/file-manager?origin_id=b4cef8ce-7773-4016-8513-829f388f7986&origin_path=%2FopenAWSEM_data%2F.

DNA simulations

Detailed instruction for DNA simulations and protein-DNA simulations can be found in https://open3spn2.readthedocs.io/en/latest/tutorial.html.