Merge branch 'maint'

[hoomd-blue.git] / doc / user / examples.dox

/*
Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
(HOOMD-blue) Open Source Software License Copyright 2009-2014 The Regents of
the University of Michigan All rights reserved.

HOOMD-blue may contain modifications ("Contributions") provided, and to which
copyright is held, by various Contributors who have granted The Regents of the
University of Michigan the right to modify and/or distribute such Contributions.

You may redistribute, use, and create derivate works of HOOMD-blue, in source
and binary forms, provided you abide by the following conditions:

* Redistributions of source code must retain the above copyright notice, this
list of conditions, and the following disclaimer both in the code and
prominently in any materials provided with the distribution.

* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions, and the following disclaimer in the documentation and/or
other materials provided with the distribution.

* All publications and presentations based on HOOMD-blue, including any reports
or published results obtained, in whole or in part, with HOOMD-blue, will
acknowledge its use according to the terms posted at the time of submission on:
http://codeblue.umich.edu/hoomd-blue/citations.html

* Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
http://codeblue.umich.edu/hoomd-blue/

* Apart from the above required attributions, neither the name of the copyright
holder nor the names of HOOMD-blue's contributors may be used to endorse or
promote products derived from this software without specific prior written
permission.

Disclaimer

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.

IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

/*! \page page_example_scripts Example Scripts
\b Examples:

1. \ref dump_dcd "Writing DCD trajectory files" - demonstrates \link hoomd_script.dump.dcd dump.dcd\endlink<br>
    <i>write a file which can be viewed in visualization
    software such as VMD</i>\n
    \n
2. \ref analyze_imd "Visualizing simulations in real time" - demonstrates \link hoomd_script.analyze.imd analyze.imd\endlink<br>
    <i>use VMD to view a running simulation update in real time</i>\n
    \n
3. \ref create_random_polymers "Initialize a system with randomly generated polymers" - demonstrates \link hoomd_script.init.create_random_polymers init.create_random_polymers\endlink<br>
    <i>initialize a random system of polymers given configurable parameters</i>\n
    \n
4. \ref init_xml "Initialize from an XML file" - demonstrates \link hoomd_script.init.read_xml init.read_xml\endlink<br>
    <i>initialize a system with any configuration from a file</i>\n
    \n
5. \ref box_resize "Shrinking/expanding the simulation box" - demonstrates \link hoomd_script.update.box_resize update.box_resize\endlink<br>
    <i>slowly change the simulation box dimensions</i>\n
    \n
6. \ref box_resize_rigid "Shrinking/expanding the simulation box with rigid bodies" - demonstrates \link hoomd_script.update.box_resize update.box_resize\endlink<br>
    <i>behavior of update.box_resize with rigid bodies in the system</i>\n
    \n
7. \ref init_reset "Run multiple simulations in one job script" - demonstrates \link hoomd_script.init.reset init.reset\endlink<br>
    <i>use a python loop to run many simulations at different parameters in a single script</i>\n
    \n
8. \ref init_create_empty "Set initial conditions directly from python code" - demonstrates \link hoomd_script.init.create_empty init.create_empty\endlink<br>
    <i>use python code to create custom initial configurations without needing to write an xml file</i>\n
    \n
9. \ref pair_table "Use any functional form for pair interactions" - demonstrates \link hoomd_script.pair.table pair.table\endlink<br>
    <i>specify an abritrary pair interaction without needing to write C++ code</i>\n
    \n
10. \ref pair_table_file "Use any tabulated data for pair interactions" - demonstrates \link hoomd_script.pair.table pair.table\endlink<br>
    <i>specify an abritrary pair interaction, read from a file</i>\n
11. \ref bond_table "Use any tabulated data or functional form for bond interactions" - demonstrates \link hoomd_script.bond.table bond.table\endlink<br>
    <i>specify an abritrary bond interaction, read from a file or an evaluated function</i>\n

12. \ref angle_table "Use any tabulated data or functional form for angle interactions" - demonstrates \link hoomd_script.angle.table angle.table\endlink<br>
    <i>specify an abritrary angle interaction, read from a file or an evaluated function</i>\n

13. \ref dihedral_table "Use any tabulated data or functional form for dihedral interactions" - demonstrates \link hoomd_script.dihedral.table dihedral.table\endlink<br>
    <i>specify an abritrary dihedral interaction, read from a file or an evaluated function</i>\n
*/

/*! \example dump_dcd
This simple example is an adaptation of the quick start script. It performs a simulation of a Lennard-Jones liquid,
dumping snapshots of the system every 100 time steps.

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x dump_dcd
\endcode

Running this quick simulation will result in two output files being generated
in the current working directory: \c dump_dcd.xml and \c dump_dcd.dcd. The
\c .xml file generated by \link hoomd_script.dump.xml dump.xml \endlink
contains the particle names and coordinates at time step 0. If there were
any bonds specified, they would be included too. VMD or other applications
can read in the \c .xml to obtain this information.

\c dump.dcd includes snapshots of the system state (particle position
coordinates only) written every 100 time steps. This file can be loaded into
visualization software such as VMD and played as a movie or read for
analysis purposes.

If you have VMD installed, you can load up the entire simulation trajectory
by running
\code
$ vmd -hoomd dump_dcd.xml dump_dcd.dcd
\endcode
on the command line or by loading these files using VMD's GUI. For the best
visualization, open VMD's <i>Graphical Representation</i> menu and set the
<i>Drawing Method</i> to VDW.

<hr>

*/

/*! \example analyze_imd
Here is the same simulation as \ref dump_dcd, this time configured for real-time display in VMD using the IMD
interface.

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x analyze_imd
\endcode

The simulation is now running in hoomd (you may get a prompt from your firewall asking if hoomd is allowed to act as
a server, allow it). In another terminal, cd into the examples directory and load the initial configuration in vmd:
\code
$ vmd -hoomd analyze_imd.xml
\endcode

Then go to the VMD command window and run the command
\code
imd connect localhost 54321
\endcode
The particles in the display window should begin moving. The display
is of the current state of the simulation, updated in \b real-time.
The best visualization is obtained by setting the <i>Drawing Method</i> to VDW in
VMD's <i>Graphical Representation</i> menu.

Switch back to the terminal where hoomd is running and press CTRL-C to kill the
simulation. It is set to run for an extremely long time on purpose to allow
ample time to launch VMD and issue the \c imd command.

<hr>
*/

/*! \example create_random_polymers
Here is a script that generates a system of bead-spring polymers that self-assemble
into a hex phase when run for a few million time steps. The polymers are A6B7A6 block copolymers
in an implicit solvent. The script also shows a few examples of how writing python
code in the script can be handy: here the concentration \c phi_P is a parameter and
math operations are performed to calculate the length of the box.

For more information on the model in this script, see<br>
"Micellar crystals in solution from molecular dynamics simulations"<br>
J. Chem. Phys. \b 128, 184906 (2008); DOI:10.1063/1.2913522<br>
http://link.aip.org/link/?JCPSA6/128/184906/1

Any of the polymer systems in the paper could be easily run just by changing a few parameters in
this script.

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x create_random_polymers
\endcode

The results of this example may be visualized with VMD:
\code
$ vmd -hoomd create_random_polymers.xml create_random_polymers.dcd
\endcode

<hr>

*/

/*! \example init_xml

HOOMD-blue is not limited by its built-in random initial condition generators. You can load in an arbitrary initial
condition from a formatted xml file. Here is a simple example demonstrating most of the types of data that can be
input (see \ref page_xml_file_format for full documentation of this format):

\include init_xml.xml

The initial conditions can be read into a simulation
using the command \link hoomd_script.init.read_xml init.read_xml\endlink as shown in the example script below.

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x init_xml
\endcode

The results of this example may be visualized with VMD:
\code
$ vmd -hoomd init_xml.xml init_xml.dcd
\endcode

<hr>

*/

/*! \example box_resize
\link hoomd_script.update.box_resize update.box_resize\endlink can be used to slowly resize the simulation box
dimensions during a run(). To use it, specify a \link hoomd_script.variant variant\endlink mapping time steps to
box lengths and give it to the update.box_resize command. It can optionally rescale all particle coordinates into
the new box, or just leave all particle coordinates alone.

\note An update period of 1 will result in extremely slow simulations (box resizing is performed on the CPU, not
the GPU). Use a slow box resize and a larger update period (i.e. 100) for faster simulations.

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x box_resize
\endcode

The results of this example may be visualized with VMD:
\code
$ vmd -hoomd box_resize.xml box_resize.dcd
\endcode

<hr>
*/

/*! \example box_resize_rigid
\link hoomd_script.update.box_resize update.box_resize\endlink can be used to slowly resize the simulation box
dimensions during a run(). To use it, specify a \link hoomd_script.variant variant\endlink mapping time steps to
box lengths and give it to the update.box_resize command. It operates properly on systems of particles, rigid
bodies, and systems with both. Rigid bodies are handled by scaling (if scaling is enabled) the center of mass
position of each body while keeping the size of the body fixed.

\note An update period of 1 will result in extremely slow simulations (box resizing is performed on the CPU, not
the GPU). Use a slow box resize and a larger update period (i.e. 100) for faster simulations.

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x box_resize_rigid
\endcode

The results of this example may be visualized with VMD:
\code
$ vmd -hoomd box_resize_rigid.xml box_resize_rigid.dcd
\endcode

<hr>

*/

/*! \example init_reset

In a loop, this example performs a simulation of a Lennard-Jones liquid
at different system sizes one after the other. It shows how the power of python
code in a hoomd script can be utilized to accomplish complicated tasks.
For more information on python and a tutorial on the python language,
check out http://www.python.org.

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x init_reset
\endcode

<hr>

*/

/*! \example init_create_empty

This example performs a simulation of a Lennard-Jones liquid of two types of particles A and B. The initial condition
is a simple cubic lattice, with the top half of the box containing particles of type B and the bottom half type A.

It demonstrates several use-cases for accessing particle data from within python that could be easily copied
and used in other scripts.
 - Initialization of all particle positions
 - Initialization of a thermal velocity distribution
 - Changing the type of a group of particles

For more information on python and a tutorial on the python language,
check out http://www.python.org . Details about the relevant commands in hoomd_script can be found here:
 - \link hoomd_script.init.create_empty init.create_empty\endlink
 - hoomd_script.data

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x init_create_empty
\endcode

<hr>

*/

/*! \example pair_table

This example demonstrates how to use \link hoomd_script.pair.table pair.table\endlink to specify an arbitrary
particle pair interaction, given a functional form for \f$ V(r) \f$ and \f$ F(r) = -\frac{\partial V}{\partial r}\f$.

First, write a python function which evaluates \f$ V(r) \f$ and \f$ F(r) \f$ in the following form
~~~~~~~~~~~~~{.py}
def my_potential(r, rmin, rmax, coeff1, coeff2, coeff3):
    V = # function of r, rmin, rmax, coeff1, ...
    F = # function of r, rmin, rmax, coeff1, ... (-dV/dr)
    return (V, F)
~~~~~~~~~~~~~

Then, initialize the table potential with a chosen number of points:
~~~~~~~~~~~~~{.py}
table = pair.table(width=1000)
~~~~~~~~~~~~~

The function, parameters *rmin* and *rmax*, and coefficients can be set individually for each type pair:
~~~~~~~~~~~~~{.py}
table.pair_coeff.set('A', 'A', func=my_potential, rmin=0.8, rmax=3.0, coeff=dict(coeff1=1.5, coeff2=1.0, coeff3=-4.5))
~~~~~~~~~~~~~
Any number of coefficients of any name may be present in your function. The function is evaluated at *width* points in
in the range `[rmin,rmax]`. Outside of the range `[rmin,rmax]`, both the force and energy evaluate to zero.
In the range, the given *r* in a pair interaction is used to interpolate linearly between the two nearest points in
the table.

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x pair_table
\endcode

<hr>

*/

/*! \example pair_table_file

This example demonstrates how to use \link hoomd_script.pair.table pair.table\endlink to specify an arbitrary
particle pair interaction, where \f$ V(r) \f$ and \f$ F(r) = -\frac{\partial V}{\partial r}\f$ are provided in a file.

First, write a file that lists \f$ V(r) \f$ and \f$ F(r) \f$ in the following form:
\snippet pair_table_file.dat start
...
\snippet pair_table_file.dat end

The first column lists all the *r* values. The first *r* value in the file is taken to be *rmin*. The last
is *rmax*. All values in-between must be evenly spaced and monotonically increasing. The second column specifies
\f$ V(r) \f$ and the third specifies \f$ F(r) \f$.

Then, initialize the table potential with a chosen number of points. The number of points must match the number of
rows in the data file.
~~~~~~~~~~~~~{.py}
table = pair.table(width=171)
~~~~~~~~~~~~~

Use one individual file for each type pair. When using more than one file, all must have the same number of rows.
~~~~~~~~~~~~~{.py}
table.set_from_file('A', 'A', filename='pair_table_file.dat')
~~~~~~~~~~~~~
Outside of the range `[rmin,rmax]`, both the force and energy evaluate to zero. In the range, the given *r* in a pair
interaction is used to interpolate linearly between the two nearest points in the provided table.

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x pair_table_file
\endcode

<hr>

*/

/*! \example bond_table

This example demonstrates how to use \link hoomd_script.bond.table bond.table\endlink to specify an arbitrary
bond interaction, where \f$ V(r) \f$ and \f$ F(r) = -\frac{\partial V}{\partial r}\f$ are provided in a file or
via function evaluation.

To specify a potential in a file, first write a file that lists \f$ V(r) \f$ and \f$ F(r) \f$ in the following form:
\snippet bond_table.dat start
...

The first column lists all the *r* values. The first *r* value in the file is taken to be *rmin*. The last
is *rmax*. All values in-between must be evenly spaced and monotonically increasing. The second column specifies
\f$ V(r) \f$ and the third specifies \f$ F(r) \f$.

Then, initialize the table potential with a chosen number of points. The number of points must match the number of
rows in the data file.
~~~~~~~~~~~~~{.py}
btable = bond.table(width=1000)
~~~~~~~~~~~~~

Use one individual file for each bond type. When using more than one file, all must have the same number of rows.
~~~~~~~~~~~~~{.py}
btable.set_from_file('bond1', 'bond_table.dat')
~~~~~~~~~~~~~
Outside of the range `[rmin,rmax]`, both the force and energy evaluate to zero. In the range, the given *r* in a pair
interaction is used to interpolate linearly between the two nearest points in the provided table.

To specify a tabulated function, write a python function which evaluates \f$ V(r) \f$ and \f$ F(r) \f$ in the following form
~~~~~~~~~~~~~{.py}
def my_potential(r, rmin, rmax, coeff1, coeff2, coeff3):
    V = # function of r, rmin, rmax, coeff1, ...
    F = # function of r, rmin, rmax, coeff1, ... (-dV/dr)
    return (V, F)
~~~~~~~~~~~~~

The function, parameters *rmin* and *rmax*, and coefficients can be set individually for each bond type:
~~~~~~~~~~~~~{.py}
btable.bond_coeff.set('bond2', func=my_potential, rmin=0.2, rmax=5.0, coeff=dict(coeff1=1.5, coeff2=1.0, coeff3=-4.5))
~~~~~~~~~~~~~
Any number of coefficients of any name may be present in your function. The function is evaluated at *width* points in
in the range `[rmin,rmax]`. Outside of the range `[rmin,rmax]`, both the force and energy evaluate to zero.
In the range, the given *r* in a pair interaction is used to interpolate linearly between the two nearest points in
the table.

To run this example, copy the examples directory from share/hoomd/examples your hoomd installation directory.
\code
cp -R HOOMD-INSTALL-DIR/share/hoomd/examples ~/hoomd-examples
cd ~/hoomd-examples
\endcode

Then run:
\code
$ hoomd -x bond_table
\endcode

<hr>

/*! \example angle_table */

/*! \example dihedral_table */

*/