This file is indexed.

/usr/share/doc/coop-computing-tools/manual/awe.html is in coop-computing-tools-doc 4.0-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
<html>

<head>
<title>AWE User's Manual</title>
</head>

<body>

<style type="text/css">
pre {
background: #ffffcc;
font-family: monospace;
font-size: 75%
font-align: left;
white-space: pre;
border: solid 1px black;
padding: 5px;
margin: 20px;
}

table {
border: 2px solid black;
border-collapse: collapse;
width: 75%;
}
th {
border-width: 2px;
padding:4px;
border-style:solid;
background-color: #DAD8D8;
}
td {
border-width: 2px;
padding:4px;
border-style:solid;
}
</style>
<h1>AWE User's Manual</h1>
<b>Last Updated March 2013</b>
<p>
AWE is Copyright (C) 2013- The University of Notre Dame.
This software is distributed under the GNU General Public License.
See the file COPYING for details.
<p>
<h2>Overview</h2>

Accelerated Weighted Ensemble or AWE package provides a Python library for adaptive
sampling of molecular dynamics. The framework decomposes the resampling
computations and the molecular dynamics simulations into tasks that are
dispatched for execution on resources allocated from clusters, clouds, grids, or
any idle machines.

<p>AWE uses Work Queue, which is part of the Cooperating Computing Tools (CCTools)
package, for dispatching jobs for execution on allocated resources.
Documentation on downloading, installing, and using Work Queue can be found 
<a href="http://www.nd.edu/~ccl/software/manuals/workqueue.html">here</a>. 

<h2>Software Requirements</h2>
AWE currently uses the GROMACS molecular dynamics simulation package. So it
requires an installation of GROMACS 4.5 or above and its installed location
added to PATH. It also requires the GROMACS XTC library for operation. 

<p>
The software requirements of AWE are summarized below along with how AWE finds
and accesses them:

<table>
<tr>
<th>Software</th><th>Version</th><th>Must be present in environment variable</th>
</tr>
<tr>
<td><a href="http://python.org">Python</a></td><td>2.6 or 2.7</td><td>PATH and PYTHONPATH</td>
</tr>
<tr>
<td><a href="http://www.gromacs.org">GROMACS</a></td><td>4.5 or higher</td><td>PATH</td>
</tr>
<tr>
<td><a
href="http://www.gromacs.org/Developer_Zone/Programming_Guide/XTC_Library">GROMACS XTC Library</a></td><td>1.1 or higher</td><td>C_INCLUDE_PATH and LD_LIBRARY_PATH</td>
</tr>
<tr>
<td><a href="http://www.numpy.org">Numpy</a></td><td>1.5 or higher</td><td>PYTHONPATH</td>
</tr>
<tr>
<td><a href="http://www.csb.pitt.edu/prody">Prody</a></td><td>0.9.4 or higher</td><td>PYTHONPATH</td>
</tr>
<tr>
<td><a href="http://www.gnu.org/software/gsl/">GNU Scientific Library</a></td><td>1.15 or higher</td><td>C_INCLUDE_PATH and LD_LIBRARY_PATH</td>
</tr>
<tr>
<td><a href="http://matplotlib.org">Matplotlib</a></td><td>1.1.0 or higher</td><td>PYTHONPATH</td>
</tr>
</table> 

<h2>Building and Installing AWE</h2>
Download the CCTools source package from this <a
href="http://www.nd.edu/~ccl/software/download">web page</a> and install
using the steps <a href="http://www.nd.edu/~ccl/software/manuals/install.html">here</a>. 

<p> 
First, determine the location where AWE is to be installed. For example:
<pre>
% export AWE_INSTALL_PATH=$HOME/awe
</pre>

Compile and install AWE in the location pointed by $AWE_INSTALL_PATH using:
<pre>
% cd cctools-xxx-src
% cd apps/awe
% ./configure --prefix $AWE_INSTALL_PATH
% make install
</pre>

Next, set PATH to include the installed AWE binaries:
<pre>
% export PATH=${AWE_INSTALL_PATH}/bin:${PATH}
</pre>

Finally, set PYTHONPATH to include the installed AWE Python modules:
<pre>
% export PYTHONPATH=${AWE_INSTALL_PATH}/lib/python2.6/site-packages:${PYTHONPATH}
</pre>

Note that the AWE Python modules will be built for the version of Python
accessible in your installed environment. The installation script creates a
directory (under <tt>$AWE_INSTALL_PATH/lib</tt>) named with the version of Python for
which the modules are built and copies the modules to this directory. So if your
environment has a Python version different from 2.6, replace the version string
accordingly when setting <tt>PYTHONPATH</tt>.

<p>You can check if AWE was correctly installed by running:
<pre>
% awe-verify
</pre>

<h2>Running AWE</h2>

First, create a directory from which you want to instantiate and run the AWE
program. In this manual, we are going to run AWE to sample the state transitions
of the Alanine Dipeptide protein using the code in <tt>awe-ala.py</tt>.  <pre>
% cd $HOME
% mkdir awe-alanine 
% cd awe-alanine 
</pre>

<p>To run AWE to sample a protein molecule, you will need to have the files
describing the topology of atoms in that molecule, the coordinates of the
walkers, and the coordinates of the cells.  In addition, AWE transfers the
executables from the GROMACS package required for running the simulations of
each walker. 

<p>These files and executables can be fetched to the current working directory by running 
 
<pre>
% awe-prepare
</pre>

<p>This will create two directories named <tt>awe-generic-data</tt> and
<tt>awe-instance-data</tt>. <tt>awe-generic-data</tt> will contain files that
all AWE runs will require, such as the task executables and Gromacs forcefield
files. <tt>awe-instance-data</tt> will contain files that are particular to a
protein system such as the state definitions, initial protein coordinates, etc.
Note that <tt>awe-prepare</tt>, by default, will transfer the files for the
Alanine Dipeptide protein molecule. Further, <tt>awe-prepare</tt> will also copy
the example program <tt>awe-ala.py</tt> provided in the AWE source that samples
the state transitions for the Alanine Dipeptide protein. 

<p>To run the example in <tt>awe-ala.py</tt>, do

<pre>
% python awe-ala.py
</pre>

<p> You will see this output right away:
<pre>
 Running on port 9123...
 Loading cells and walkers
</pre>

The AWE master program successfully started and began loading the cells and
walkers for running the simulations. After that, the master waits for workers to
connect so it can dispatch the simulation tasks for execution by the connected
workers.

Now, start a worker for this master on the same machine:
<pre>
% work_queue_worker localhost 9123
</pre>

However, to run a really large sampling, you will need to run as many workers as
possible.  A simple (but tiresome) way of doing so is to <tt>ssh</tt> into
several machines and manually run <tt>work_queue_worker</tt> as above.  But, if
you have access to a batch system like <a
href=http://www.cs.wisc.edu/condor>Condor</a> or <a
href=http://www.sun.com/software/sge>SGE</a>, you can use them to start many
workers with a single submit command.

<p>
We have provided some scripts to make this easy.  For example, to submit 10
workers to your local Condor pool:

<pre>
% condor_submit_workers master.somewhere.edu 9123 10
Submitting job(s)..........
Logging submit event(s)..........
10 job(s) submitted to cluster 298.
</pre>

Or, to submit 10 worker processes to your SGE cluster:
<pre>
% sge_submit_workers master.somewhere.edu 9123 10
Your job 1054781 ("worker.sh") has been submitted
Your job 1054782 ("worker.sh") has been submitted
Your job 1054783 ("worker.sh") has been submitted
...
</pre>

Once the workers begin running, the AWE master can dispatch tasks to
each one very quickly.  It's ok if a machine running a worker crashes
or is turned off; the work will be silently sent elsewhere to run.
<p>
When the AWE master process completes, your workers will
still be available, so you can either run another master with the
same workers, remove them from the batch system, or wait for them to
expire.  If you do nothing for 15 minutes, they will automatically exit.

<h2> Output of AWE</h2>

The AWE master creates the following output files on completion:
<ul>
<li><tt>cell-weights.csv</tt> describing the weight of the cells </li>
<li><tt>walker-history.csv</tt> describing the cells that were visited by the walkers </li>
<li><tt>color-transition-matrix.csv</tt> that describes the number of
transitions between the defined cell groups</li> 
<li><tt>walker-weights.csv</tt> that describes the weights of the walkers</li>
</ul>

You can use these output files to generate different plots that visualize the
output of the AWE run. To generate a Ramachandran plot (free energy landscape on
phi-psi space) using <tt>cell-weights.csv</tt>, run the following command.
<pre>
% python awe-rama-ala.py -w cell-weights.csv -p awe-instance-data/topol.pdb -c awe-instance-data/cells.dat -n 100
</pre>

where, <tt>-w</tt> specifies the csv file recording cell weights, <tt>-p</tt>
the structure file of simulation target, <tt>-c</tt> the data file recording
coordinates of cell centers, and <tt>-n</tt> the number of cells

This produces an output file named <tt>awe-rama-ala.png</tt> that contains the
Ramachandran plot.

<p>To generate and visualize forward and backward fluxes from the output file
<tt>color-transition-matrix.dat</tt>, use the script <tt>awe-flux.py</tt>.

<pre>
% python awe-flux.py -i color-transition-matrix.csv -l 0.01
</pre>

where <tt>-i</tt> specifies the data file recording transitions at every
iteration, <tt>-l</tt> specifies the scale iteration length to actual unit and
(nano/pico/femto-seconds).

This will produce the following outputs:		
<ul>
<li><tt>instan-forward-flux.dat</tt>: instantaneous forward flux</li>
<li><tt>instan-backward-flux.dat</tt>: instantaneous backward flux</li>
<li><tt>forward-flux.png</tt>: plot of forward flux</li>
<li><tt>backward-flux.png</tt>: plot of backward flux</li>
</ul>

<p>Finally, to generate transition probability matrix from AWE output, run the
script <tt>awe-transMatrix.py</tt>

<pre>
% python awe-transMatrix.py -p walker-history.dat -w walker-weights.dat -t 1 -n 100
</pre>
where <tt>-p</tt> specifies the data file recording dependencies of walkers,
<tt>-w</tt> specifies the data file recording weights and cell ID of walkers,
<tt>-t</tt> specifies the time lag (number of iterations) for calculating,
transition matrix, and <tt>-n</tt> specifies the number of cells

<p>This prints the matrix to a file called <tt>trans-probability-matrix.csv</tt>.

<h2> Running AWE on Different Protein Systems</h2>
You can run AWE to sample a different protein system by following the steps
below:

<ol>
<li> Sample the conformations space of the protein using ensemble simulations, replica
exchange, etc. </li>
<li> Cluster the data to obtain the cell definitions.</li>
<li> Extract the conformations from each cluster as individual walkers.</li>
</ol>

Specifically, these steps translate to the following:

<ol>
<li> Describe the topology of the system in <tt>topol.pdb</tt>.
<li> Prepare the state definitions and list them in <tt>cells.dat</tt> </li>
<li> Select the subset of atoms from the cell definitions <tt>cells.dat</tt> and list
them in <tt>CellIndices.dat</tt></li>
<li> Select the subset of atoms from the walker topology file <tt>topol.pdb</tt>
and list them in <tt>StructureIndices.dat</tt></li>
<li> Define the initial coordinates for the walkers in <tt>State$i-$j.pdb</tt>
where <tt>i</tt> is the index of the cell and <tt>j</tt> is the index of the walker.</li>
<li> Specify the parameters for the walker simulation by GROMACS in
<tt>sim.mdp</tt>. 
</ol>

<h2>For More Information</h2>

For the latest information about AWE, please visit our <a
href=http://www.nd.edu/~ccl/software/awe>web site</a> and subscribe to our <a
href=http://www.nd.edu/~ccl/software/help.shtml>mailing list</a>.
</body>
</html>