<html>
<head>
<title>MCCCS Towhee (User Manual)</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table width="800" border="0" cellspacing="0" cellpadding="0" height="590">
<tr>
<td colspan="2" height="29">
<div align="center"> <font size="5"> <b><font face="Arial, Helvetica, sans-serif"><a name="top"></a>MCCCS Towhee (User Manual)</font></b></font></div>
</td>
</tr>
<A href="http://sourceforge.net">
<IMG src="http://sourceforge.net/sflogo.php?group_id=87039&type=5" width="210" height="62" border="0" alt="SourceForge.net Logo" align="right"/>
</A>
<tr>
<td width="18" height="371" valign="top">
<p> </p>
<p> </p>
</td>
<td width="700" valign="top">
<p></p>
<b>Overview</b>
<ul>
This section covers the basic information that is needed to set up the input files for Towhee and to get some useful work done with the code. It also
describes the files that are generated by the Towhee program. Note that Towhee has a version control number that is related to the input files. The first
number changes only when modifications to Towhee require a new format for towhee_initial, the second number changes only modifications to Towhee require
a new format for towhee_input, and the final number is changed when Towhee is modified in such a way that none of the input files have been altered
(generally for bug fixes). For information about the Towhee program files see the <a href="code/code_manual.html">Towhee code manual</a>.
<p></p>
Several illustrative test cases are included with the Towhee download. Information about running those test cases can be found in the
<a href="examples/example_manual.html">Towhee example manual</a>.
</ul>
<dt><font color="red">Towhee Input Files</font></dt>
<ul>
<b>towhee_input (input file)</b>
<ul>
This is the main input file for Towhee and is generally the only file that needs to be edited on a regular basis. It has a regimented style to the
input. The variables are described here in the order they appear in this file. Please look at one of the example files (included with the code
release) for the precise file format.
<dt> <i>Current Release version</i></dt>
<dt><a href="input/towhee_input_v7_0_x.html">towhee_input Version 7.0.x</a></dt>
<dt> <i>Older input file versions</i></dt>
<dt><a href="input/towhee_input_v6_2_x.html">towhee_input Version 6.2.x</a></dt>
<dt><a href="input/towhee_input_v6_1_x.html">towhee_input Version 6.1.x</a></dt>
<dt><a href="input/towhee_input_v6_0_x.html">towhee_input Version 6.0.x</a></dt>
<dt><a href="input/oldversionindex.html">towhee_input Versions 1 through 5</a></dt>
</ul>
<a name="towhee_coords"><b>towhee_coords (input file)</b></a>
<ul>
This file is used when you are first setting up the run and you want the code to directly read the initial coordinates (<b>initstyle</b>='coords').
The code will read one set of atom coordinates from each line (x,y,z). Note that the code builds the entire first box configuration before moving on to
subsequent boxes and it also places all molecules of type 1 in the box before placing those of subsequent types. This file is most useful when you
already have a coordinate file from another source (such as a pdb file, or output from another code) and just want to directly read that into Towhee.
<p></p>
A <b>towhee_coords</b> file may also be created from a <b>towhee_final</b> file (see below) by stripping all data preceding the atom coordinates.
This technique can be useful for restarting from final coordinates while allowing <b>hmatrix</b> and maximum displacement parameters to be defined
in the <b>towhee_input</b> file.
</ul>
<b>towhee_ff (input file)</b>
<ul>
This file contains all of the force field parameters for any user-defined force field. Several common forcefields are provided with the download
package. This file follows a very rigid format which is described in the <a href="towhee_ff.html">Towhee Force Field File</a> documentation.
</ul>
<b>towhee_initial (input file)</b>
<ul>
This file contains the box lengths, maximum displacements, and coordinates for the system. It is used when you wish to restart a job from the final
configuration of a previous run. The previous run output (either towhee_final or towhee_backup) is simply copied to towhee_initial and the next
simulation continues from this configuration. Note that you must set <b>linit</b> to .false. when you want to restart and that there is some error
checking to make sure the information in towhee_initial matches information in towhee_input. The code can read in previous versions of the
towhee_initial file without difficulty as the version number is at the top of the file. It is possible to directly edit this file, but if you are
clever enough to play around in towhee_initial then you are smart enough to look in the code (rwconf.F) to figure out how to do it. Please note
that when <b>towhee_initial</b> is used, the <b>hmatrix</b> parameter, as well as parameters describing maximum move sizes, in <b>towhee_input</b>
are ignored.
</ul>
<b>towhee_parallel (input file)</b>
<ul>
This file specifies the style of parallelism to use when running the parallel version of the code. This file is not needed for a serial job run using
the towhee version of the code. Only the current release version is maintained here.
<dt> <i>Current Release version</i></dt>
<dt><a href="towhee_parallel.html">towhee_parallel</a></dt>
</ul>
<b>towhee_partial (input file)</b>
<ul>
This file is used when you are first setting up the run and you want the code to read in a partial list of atom positions, match them against the
expected positions (specified in towhee_input), and then use configurational-bias to fill in any missing atoms. It is suggested that you generate
this file using the <a href="utils/pdb2towhee.html">pdb2towhee.F</a> utility. If you are using this file to generate multiple molecules in a single
run then you can simply cat all of the files together and then remove all of the "nul" lines, except for the final instance.
</ul>
<a name="towhee_template"><b>towhee_template (input file)</b></a>
<ul>
This file is used to generate an initial template for molecules when first setting up the initial configuration (<b>linit</b>=.true. and
<b>initstyle</b>='template'). The molecules are read from the template in the order they are listed in towhee_input and note that if any of the boxes
are set to <b>initstyle</b>='full cbmc' for one of the molecules then that molecule template is generated via configurational-bias in all of the boxes
and towhee_template is not used. The format for towhee_template is one unread line (where you can put in a note to remind yourself the name of the
molecule for that template) and then the x,y,z coordinates for each atom with one atom per line. This file works best if the first atom is placed
at (0.0,0.0,0.0).
</ul>
</ul>
<dt><font color="red">Towhee Output Files</font></dt>
<ul>
<b>standard output (output file)</b>
<ul>
Towhee outputs quite a bit of run time information to standard output (Fortran unit 6) and normally you will want to redirect this output to a
filename of your choosing. That is done using standard Unix commands: for example to redirect the standard output to a file named "towhee_output"
you would execute the following command.
<ul>
<b>./towhee > towhee_output</b>
</ul>
For more information about this output file, and a discussion of the chemical potential and pressure calculations,
please see the <a href="standard_output.html">Towhee standard output</a> manual.
</ul>
<b>box_xx_step_nnn.pdb (output file)</b>
<ul>
This file is output for each box (where xx is replaced by the box number and nnn by the step number) at the beginning, end, and intermediate points of
a simulation, as specified by the <b>pdb_output_freq</b> variable in the towhee_input file.
<a href="http://www.bernstein-plus-sons.com/software/rasmol/">Rasmol</a> is a freely available program for visualizing pdb files.
</ul>
<b>towhee_altinp (output file)</b>
<ul>
This file contains all of the information needed to create the molecule input file for <b>inpstyle</b>=0 needed in towhee_input. This is output
whenever you are using an <b>inpstyle</b> other than 0 in towhee_input. For very large molecules (like proteins) it can take a considerable amount of
time to setup the force field (on the order of 20 minutes) so there are occasions when you only want to do this the first time you run and then use
the <b>inpstyle</b>=0 for subsequent runs. If you want to use the <b>inpstyle</b>=0 information then just paste this file into the appropriate section
of towhee_input. This file is also useful for seeing exactly which force field interactions are used for every term in case you want to check the
builder to make sure it was doing what you thought it should be doing.
</ul>
<b>towhee_backup (output file)</b>
<ul>
This file contains the box lengths, maximum displacements, and coordinates for the system. It is output periodically from the code
(see <b>backupfreq</b> in the towhee_input section) and can be used to restart the simulation from this configuration. In order to restart using this
configuration you need to copy towhee_backup to towhee_initial (see towhee_initial).
</ul>
<b>towhee_citations (output file)</b>
<ul>
Contains a list of suggested citations given the ensemble, moves, and force fields used in a particular simulation. For more information
see the <a href="citation_manual.html">Citation Manual</a>.
</ul>
<b>towhee_restart_nnn (output file)</b>
<ul>
This restart file is identical in format to <b>towhee_backup</b>; the nnn suffix, which corresponds to the step at which it was written, makes the
filename unique for a given run, so that new towhee_restart files do not overwrite old ones. This is useful if you wish to restart from intermediate
points of a simulation. towhee_restart is controlled by the <b>restartfreq</b> parameter in the towhee_input.
</ul>
<b>towhee_final (output file)</b>
<ul>
This file contains the box lengths, maximum displacements, and coordinates for the system. It is output at the end of the simulation and can be used
to restart the simulation from this configuration. In order to restart using this configuration you need to copy towhee_final to towhee_initial
(see towhee_initial).
</ul>
<b>towhee_histogram (output files)</b>
<ul>
This file contains run information output during a grand-canonical ensemble run and are suitable for use in the
<a href="references.html#methods_histogram_reweighting">Histogram Reweighting method.</a> The utility program
<a href="utils/analyse_histogram.html">analyse_histogram</a> is used to process this output file.
</ul>
<b>towhee_movie (output file)</b>
<ul>
This file contains a series of snapshots of the positions of all of the atoms in each simulation box. The frequency of this output is controlled by
the <b>moviefreq</b> variable (set in towhee_input). This movie file allows the user to compute quantities that depend upon positions as a
post-processing operation. The utility program <a href="utils/analyse_movie.html">analyse_movie</a> computes many different distribution functions
from towhee_movie.
</ul>
<b>towhee_ostwald (output file)</b>
<ul>
This file contains information that is useful when computing partition coefficients and free energies of transfer. The Ostwald coefficient
(the ratio of densities in two phases/boxes) is computed and used to compute the free energy of transfer. The output contains the box numbers,
partition coefficients, standard deviations of partition coefficients, free energies of transfer, and standard deviations of free energies of
transfer for each molecule type in the simulation. Partition coefficients are not output if the densities are essentially zero in the second box
(to avoid dividing by zero).
</ul>
<b>towhee_vlcc (output file)</b>
<ul>
This file is only generated if you have at least 1 block in the block averages, there are 2 simulation boxes (<b>numboxes</b>=2), and there is only
one molecule type (<b>nmolty</b>=1). It contains a single line of information with the temperature, the gas phase specific density, the standard
deviation of gas phase specific density, the liquid phase specific density, and the standard deviation of the liquid phase specific density. This is
useful when constructing vapor-liquid coexistence curves. The box with the higher density is assumed to be the liquid phase, and the other box is
the vapor phase. See the <a href="utils/fitcoex.html">fitcoex</a> utility routine for more information about the uses of the towhee_vlcc files.
</ul>
</ul>
<dt><font color="red">Database Input Files</font></dt>
<ul>
<b>database_input (input file)</b>
<ul>
This file is only used when the <b>inputformat</b> is set to 'Database' and is designed for use in fitting force fields. See
the <a href="database/database_input.html"> database_input</a> manual for more information.
</ul>
</ul>
<dt><font color="red">LAMMPS Input Files</font></dt>
<ul>
<b>lammps_data (input file)</b>
<ul>
This file is only used when the <b>inputformat</b> is set to 'LAMMPS'. It is read into the code and used to create an initial conformation and
force field file. This exists to facilitate transfer of simulation data between Towhee and the
<a href="http://lammps.sandia.gov/">LAMMPS</a> massively parallel molecular dynamics code.
</ul>
</ul>
<p> </p>
<a href="index.html">Return to the main towhee web page</a>
</td>
</tr>
</table>
<p></p>
<hr width="715" align="left">
<i><font size="2">Send comments to:</font></i>
<font size="2"> <a href="mailto:marcus_martin@users.sourceforge.net">Marcus G. Martin</a><br></br>
<i>Last updated:</i> <!-- #BeginDate format:Am1 -->August 12, 2011<!-- #EndDate -->
</font>
<br></br>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
2f8321c8e2a11ea8b160a642cfc9fd7f
>
files
>
307
