MCCCS Towhee (User Manual)



    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 Towhee code manual.

    Several illustrative test cases are included with the Towhee download. Information about running those test cases can be found in the Towhee example manual.
Towhee Input Files
    towhee_input (input file) towhee_coords (input file)
      This file is used when you are first setting up the run and you want the code to directly read the initial coordinates (initstyle='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.

      A towhee_coords file may also be created from a towhee_final file (see below) by stripping all data preceding the atom coordinates. This technique can be useful for restarting from final coordinates while allowing hmatrix and maximum displacement parameters to be defined in the towhee_input file.
    towhee_ff (input file)
      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 Towhee Force Field File documentation.
    towhee_initial (input file)
      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. Please see the Towhee Restart Manual for more information about this file format. Note that you must set linit 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 towhee_initial is used, the hmatrix parameter, as well as parameters describing maximum move sizes, in towhee_input are ignored.
    towhee_parallel (input file)
      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.
      Current Release version
    towhee_partial (input file)
      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 pdb2towhee.F 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.
    towhee_template (input file)
      This file is used to generate an initial template for molecules when first setting up the initial configuration (linit=.true. and initstyle='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 initstyle='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).
Towhee Output Files
    standard output (output file)
      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.
        ./towhee > towhee_output
      For more information about this output file, and a discussion of the chemical potential and pressure calculations, please see the Towhee standard output manual.
    box_xx_step_nnn.pdb (output file)
      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 pdb_output_freq variable in the towhee_input file. Rasmol is a freely available program for visualizing pdb files.
    towhee_altinp (output file)
      This file contains all of the information needed to create the molecule input file for inpstyle=0 needed in towhee_input. This is output whenever you are using an inpstyle 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 inpstyle=0 for subsequent runs. If you want to use the inpstyle=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.
    towhee_backup (output file)
      This file contains the box lengths, maximum displacements, and coordinates for the system. It is output periodically from the code (see backupfreq 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).
    towhee_cbmc (output file)
      This file contains information about the trial distributions used to generate each bond and angle in the configurational-bias routines. The amount of information is controlled by the cbmc_analysis variable. Originally implemented in version 7.1.0.
    towhee_citations (output file)
      Contains a list of suggested citations given the ensemble, moves, and force fields used in a particular simulation. For more information see the Citation Manual.
    towhee_restart_nnn (output file)
      This restart file is identical in format to towhee_backup; 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 restartfreq parameter in the towhee_input.
    towhee_final (output file)
      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).
    towhee_histogram (output files) towhee_movie (output file)
      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 moviefreq 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 analyse_movie computes many different distribution functions from towhee_movie.
    towhee_ostwald (output file)
      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).
    towhee_vlcc (output file)
      This file is only generated if you have at least 1 block in the block averages, there are 2 simulation boxes (numboxes=2), and there is only one molecule type (nmolty=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 fitcoex utility routine for more information about the uses of the towhee_vlcc files.
Database Input Files
LAMMPS Input Files
    lammps_data (input file)
      This file is only used when the inputformat 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 LAMMPS massively parallel molecular dynamics code.


Return to the main towhee web page

Send comments to: Marcus G. Martin

Last updated: August 11, 2014