MCCCS Towhee (example manual)

 

 

Overview
    This section describes the examples included with the current download version of Towhee and gives some tips for getting started with these examples. The examples are intended as a place to get started, as well as doubling as the test suite for code validation. They are almost universally set to much too short of a simulation run to produce statistically useful output for publication, but many of them are otherwise setup properly for performing "real work".
History of the Examples
    All of the example files are found in the Examples directory that comes with the default download package. You will find a file named answer_current in each directory that contains the testing output for each example.
    • Tests for version 3.14.9 through 4.13.1 were run using gcc version 3.2.2 with the FFLAGS=-fbounds-check option in the configure script.
    • Starting with version 4.13.1, the configure option ./configure --enable-safe-compare attempts to minimize differences in the output between platforms for comparison purposes.
    • The examples were substantially reordered and modified with the release of version 6.2.10.
    These compilation options are intended for debugging and comparison purposes, but do not result in especially fast simulations. For production runs letting the ./configure option automatically determine the optimization level.
Using the Examples
    Each towhee_input file specifies the complete path for the force field files it requires. The default setting is something like /towheebase/ForceFields/towhee_ff_Charmm22 where Charmm22 would be the force field you are using. You can either change the /towheebase section to be the directory path for the ForceFields file, or you can set a symbolic link for /towheebase using the standard unix command
      ln -s /Your/Actual/Directory /towheebase

    As an alternative to either manually modifying the ForceFields files or creating symbolic links, execute the relocate_examples.pl script in the Examples directory. This script copies all the examples to a directory named test in the towhee root directory, and will simultaneously rewrite all references to /towheebase appropriately. You can then execute examples in the normal fashion from the test directory.

    To run the code you need to be in one of the example directories and then execute a command similar to /towheebase/Source/towhee where again /towheebase is replaced by your actual directory structure.
Descriptive List of Examples
    Canonical Ensemble
    • Canonical_Ensemble/AVB1_Methane
        A single box simulation that demonstrates the use of the agregation-volume-bias move type 1. Uses the Lennard-Jones potential and the TraPPE-UA force field.
    • Canonical_Ensemble/Amber_Villin
        A toy problem with a short peptide chain in vacuum to demonstrate the use of the protein builder functionality. Uses the Lennard-Jones potential and the Amber96 force field.
    • Canonical_Ensemble/Benzene_AA_autofit
        A toy problem testing Configurational-bias algorithm regrowths for an all-atom cyclic molecule
    • Canonical_Ensemble/Charmm19_ubiquitin
        A single box simulation that demonstrates the use of the Charmm19-EEF1 potential with implicit water solvation for a protein.
    • Canonical_Ensemble/Charmm27_Benzene
        A toy problem testing Configurational-bias algorithm regrowths for Charmm27 all-atom benzene.
    • Canonical_Ensemble/Charmm27_Heme
        A toy problem that shows how to set up a Heme group in Charmm27 using the atom builder.
    • Canonical_Ensemble/Charmm27_Nucleic_Acid
        A toy problem that demonstrates the nucleic acid builder for the Charmm27 force field.
    • Canonical_Ensemble/Charmm27_Polyalanine
        A toy problem that demonstrates the use of the 'helix cbmc' initialization option. This builds a polypeptide with the C&alpha atoms in a helix of specified radius and angle and then grows the rest of the atom using configurational-bias.
    • Canonical_Ensemble/Compass_Methanol
        A toy problem testing the energy of a single molecule in vacuum by disabling the Ewald sum. Uses the 9-6 potentials and the Compass force field.
    • Canonical_Ensemble/DREIDING
        A toy problem that shows how to minimize an initial structure by using single atom translations and a low temperature. Uses the DREIDING force field.
    • Canonical_Ensemble/Formamide_Scaled
        A one box, two component simulation that demonstrates how to perform a simulation with a 'Scaled Lennard-Jones' classical potential.
    • Canonical_Ensemble/Fris_Walls
        A one box, single component simulation that demonstrates how to perform a simulation between Lennard-Jones walls with additional hard walls and an "umbrella" potential.
    • Canonical_Ensemble/Hard_Sphere
        A single box, multicomponent simulation of hard spheres. Uses the Hard Sphere potential and force field.
    • Canonical_Ensemble/NaCl_1x1x1
        A toy problem that computes the Madelung constant to verify the accuracy of the Ewald summation. The correct answer is 1.747558 (dimensionless) and this example allows the user to modify the parameters of the Ewald sum and see how this affects the accuracy of the total coulombic energy.
    • Canonical_Ensemble/Shukla_Gasses
        A toy problem testing the 'Skukla' classical mixing rule for a simulation containing four different small molecules in the gas phase using the Shukla 1987 force field.
    • Canonical_Ensemble/Small_Peptide
        An example of how to create a small peptide with the initial structure generated via CBMC.
    • Canonical_Ensemble/Square_Well_Chain
        A single box, single component demonstration of the configurational-bias algorithm for a tangent sphere square well chain in the canonical ensemble. Uses the Square Well potential with the generic SquareWell force field.
    • Canonical_Ensemble/TraPPE_Isomers
        Two butene isomers that demonstrate the builder features that allow the user to specify the difference between cis and trans dihedrals using the TraPPE-UA forcefield.
    • Canonical_Ensemble/TraPPE_Molecules
        A batch of single molecule structures to test the assembler and bond increment method for the TraPPE-UA force field and to test the center-of-mass switch move for polyatomic molecules.
    • Canonical_Ensemble/Triglycerol
        A toy problem showing how to build the simple triglyceride model from the Sum et al. paper using the Sum2003 forcefield.
    • Canonical_Ensemble/UFF
        An example that shows how to minimize an initial structure by using single atom translations and a low temperature. Uses the UFF force field.
    • Canonical_Ensemble/Wall_Water
        An example of use of fields in Towhee. Demonstrates water between two hard walls.
    Isobaric-Isothermal Ensemble
    • Isobaric_Isothermal_Ensemble/Au_Cu_Switch
        A single box simulation demonstrating the use of the center-of-mass switch move for a mixture of monatomic metal molecules with an EAM potential.
    • Isobaric_Isothermal_Ensemble/Charmm22_Ethanethiol
        A single box simulation that demonstrates how to compute a liquid density using the isobaric-isothermal ensemble. Uses the Lennard-Jones potential and the Charmm22 force field.
    • Isobaric_Isothermal_Ensemble/Cu_Pb_EAM
        A single box simulation using the embedded atom potential for a mixture of copper and lead.
    • Isobaric_Isothermal_Ensemble/Dick1994_PETN
        An example that shows how to construct an initial system by replicating a unit cell. Creates a PETN solid using the Dick and Ritchie 1994 force field.
    • Isobaric_Isothermal_Ensemble/Gromos_Methylpropylsulfide
        A single box, single component simulation that demonstrates how to determine liquid densities. Uses the Lennard-Jones potential and the Gromos43A1 force field.
    • Isobaric_Isothermal/Henry Law
        A single box, multicomponent simulation designed to measure the Henry's Law coefficient of four small gases in a liquid ethanol solvent. This example reproduces the results from the winner of the Second Industrial Fluids Simulation Challenge Problem 2 involving the Henry's law coefficient for methane, O2, N2 and CO2 in ethanol using a combination of the TraPPE-UA, TraPPE-EH, and Coon1987 force fields. I suggest using an nstep value of 50000 and a blocksize of 10000 for production runs of this system as the chemical potential is challenging to compute precisely with Widom insertion.
    • Isobaric_Isothermal/Ideal_Chain
        A single box, single component demonstration of the configurational-bias algorithm for a flexible ideal chain in the isobaric-isothermal ensemble. Uses the Hard Sphere potential with the zero diameter hard sphere force field.
    • MMFF94_Ethyleneoxide
        A single box, single component simulation of Ethyleneoxide using the MMFF94 force field in the isobaric-isothermal ensemble. Provides a test for configurational-bias on all-atom flexible three membered rings and the Buffered 14-7 potential. This example was first included in version 7.1.1.
    • Isobaric_Isothermal/OPLS_Propanamide
        A single box single component liquid density determination. Uses the Lennard-Jones potential and the OPLS-aa force field.
    • Isobaric_Isothermal_Ensemble/SMMKmain_2244688nonane
        An example of how to create an initial structure of 2,2,4,4,6,8,8-heptamethyl nonane using the SMMKmain forcefield. Also serves as a test of the special one-five interactions.
    • Isobaric_Isothermal/Solid_LJium
        A simulation of solid Lennard-Jonesium to demonstrate the use of the plane shift and row shift moves.
    • Isobaric_Isothermal/Wielop1985_Ethyleneoxide
        A simulation of the Wielop1985 rigid ethyleneoxide model A with the same system size as in the original Wielopolski and Smith 1985 paper, but utlizes the isobaric-isothermal ensemble instead of the canoncal ensemble. Provides a test of the configurational-bias regrowth logic for rigid three membered rings. This example was first included in version 7.1.0.
    Gibbs Ensemble
    • Gibbs_Ensemble/Amber_IsoPropanol
        A two box NVT Gibbs ensemble that demonstrates the setup for determining single-component vapor-liquid coexistence. Uses the Lennard-Jones potential and the Amber96 force field.
    • Gibbs_Ensemble/Catlow_Zeolite_4a
        A two box, multi-component simulation demonstrating the setup for computing adsorption isotherms in porous materials. Uses the combined exponential-6 and Lennard-Jones potential and the Catlow force field.
    • Gibbs_Ensemble/Cu_VLE
        A two box simulation using the embedded atom potential to compute vapor-liquid coexistence for copper.
    • Gibbs_Ensemble/Cui2002_Hexane
        A two box simulation using the Cui2002 force field for n-hexane. This force field uses many potential forms that are atypical, as they all involve multi-well square well potentials for not just the nonbond interactions, but the bonded terms as well. Provides a test of configurational-bias with all of the square well intramolecular potentials. This example was first included in version 7.1.0.
    • Gibbs_Ensemble/Dubb_Zeolite
        A Gibbs ensemble simulation computing adsorption in a zeolite without using energy biasing for the first atom insertion. Uses the Dubb2004 force field.
    • Gibbs_Ensemble/EPM_VLCC
        An example of an NVT-Gibbs Ensemble single-component vapor-liquid coexistence simulation taken from Table 4 of Harris and Yung 1995. Uses the Lennard-Jones potential and the EPM2 force field.
    • Gibbs_Ensemble/FENE_Hexamer
        A toy problem using the FENE bond potential for a simple Lennard-Jones hexamer. This example was rebuilt to use the FENE bonds (Kremer and Grest 1990) that were implemented into the Lennard-Jonesium force field starting with version 7.1.0. Provides a test of configurational-bias with FENE bonds. Moved from the Canonical_Ensemble directory to the more appropriate Gibbs_Ensemble directory in version 7.2.0.
    • Gibbs_Ensemble/Gordon
        A toy problem just to check that the Gordon n-6 potential gives the same energies and pressures as the Lennard-Jones potential when n is set to 12.
    • Gibbs_Ensemble/Gromos_Isobutane
        A two box, single component simulation that demonstrates how to perform a single-component vapor-liquid coexistence curve. Uses the Lennard-Jones potential and the Gromos43A1 force field.
    • Gibbs_Ensemble/MM2_Ethane
        A two box simulation of ethane using the MM2 force field.
    • Gibbs_Ensemble/Potter_CF2H2
        An example of the 'LB plus manual' classical mixing rule applied to reproduce a two box vapor-liquid coexistence point using the Potter et al. 1997 force field.
    • Gibbs_Ensemble/SKS_Pentane
        An example from the literature to illustrate the calculation of vapor-liquid coexistence using the SKS potential for n-alkanes. Also serves as a test case for rotational-bias and configurational-bias 2 box swap moves.
    • Gibbs_Ensemble/SMMKnaip_Ethylpentane
        An example of how to create an initial system suitable for 2-box Gibbs ensemble determination of vapor-liquid coexistence of 3-ethylpentane using the SMMKnaip forcefield. Equilibrating this starting structure (likely several runs of 10,000 cycles) should result in agreement with the densities reported in Table 3 of Siepmann et al. 1997.
    • Gibbs_Ensemble/TraPPE_Pentane
        An example of a single-component vapor-liquid coexistence simulation. Uses the Lennard-Jones potential and the TraPPE-UA force field.
    • Gibbs_Ensemble/Vink2001
        An example of a vapor-liquid coexistence calculation in the Gibbs ensemble using the multibody Stillinger-Weber potential. Uses the Vink 2001 force field.
    • Gibbs_Ensemble/Weiner1984
    Grand Canonical Ensemble Convert
    • Convert/LAMMPS_class2
        Demonstrates the conversion of LAMMPS files into Towhee input files. To perform this conversion change the first line of the towhee_input file to the 'LAMMPS' inputformat instead of the 'Towhee' inputformat. Running Towhee will create files suitable for a real Towhee run. Copy these as instructed by the code and then run again to perform a Towhee simulation with the new files. Uses the 9-6 force field.
    • Convert/LAMMPS_decane
        Demonstrates the conversion of LAMMPS files into Towhee input files. To perform this conversion change the first line of the towhee_input file to the 'LAMMPS' inputformat instead of the 'Towhee' inputformat. Running Towhee will create files suitable for a real Towhee run. Copy these as instructed by the code and then run again to perform a Towhee simulation with the new files. Uses the Lennard-Jones force field.
    • Convert/LAMMPS_lc
        Demonstrates the conversion of LAMMPS files into Towhee input files. To perform this conversion change the first line of the towhee_input file to the 'LAMMPS' inputformat instead of the 'Towhee' inputformat. Running Towhee will create files suitable for a real Towhee run. Copy these as instructed by the code and then run again to perform a Towhee simulation with the new files. Uses the Lennard-Jones force field.
    Transition Matrix
    • TMMC/LJ
        Examples with Lennard-Jones for performing grand-canonical transition-matrix Monte Carlo (TMMC).
    • TMMC/SPC_E_WATER
        Examples with SPC/E Water for performing grand-canonical transition-matrix Monte Carlo (TMMC).
    Other Examples
    • DFT_Field
        Test case that combines Towhee with the Tramonto package as an implicit solvent. This test case is one of the few that is not included in the test suite and is therefore likely to be out of date.
    • Histogram
        This directory contains three subdirectories (Phase, PVT, Weights) that each illustrate one aspect of the analyse_histogram routine. This routine is used to process the output from grand canonical simulations using the Histogram Reweighting method. Please see the README.histogram file in the Examples/Histogram directory for more information.
    • Parallel_Test
        An example of how to use the towhee_parallel file with the mpitowhee version of the code to run multiple simulations on one or more processors.
    • VLCC_Fit
        A set of README documents and data files that provides an example of how to use the fitcoex utility program to analyse a set of towhee_vlcc output files to extrapolate a critical temperature and critical density for a single component system and compare that graphically to experimental data. This requires the fitcoex utility program to process the files and the plot script uses the freely available xmgrace program to graph the results.
Return to the main towhee web page

 


Send comments to: Marcus G. Martin

Last updated: July 19, 2016