// Copyright (c) 2009-2016 The Regents of the University of Michigan
// This file is part of the HOOMD-blue project, released under the BSD 3-Clause License.



/*! \page page_quick_start Quick Start Tutorial

<h2>Example script</h2>

So you have HOOMD-blue installed. Now what? <br>
Let's start with the classic MD simulation, the Lennard-Jones liquid. Place \em N particles randomly
in a box and allow them to interact with the following potential between pairs of particles:
\f[ V(r) = 4 \varepsilon \left[ \left( \frac{\sigma}{r} \right)^{12} -
                                \left( \frac{\sigma}{r} \right)^{6} \right] \f]
To configure HOOMD-blue to perform this simulation, you need a simple python script.
\code
from hoomd_script import *
context.initialize()

# create 100 random particles of name A
init.create_random(N=100, phi_p=0.01, name='A')

# specify Lennard-Jones interactions between particle pairs
lj = pair.lj(r_cut=3.0)
lj.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)

# integrate at constant temperature
all = group.all();
integrate.mode_standard(dt=0.005)
integrate.nvt(group=all, T=1.2, tau=0.5)

# run 10,000 time steps
run(10e3)
\endcode

If you don't know Python, don't worry. You can learn everything about it that you need to know for HOOMD-blue scripts
here. Of course if you do know Python (which is a full-fledged object oriented programming language:
tutorials at http://www.python.org) then you could make use of its capabilities in setting up
complicated simulations.

<hr>
<h2>Running the example</h2>

For now, copy and paste the above code into a file \em test.hoomd. Assuming you have installed HOOMD-blue,
you can run the simulation script from the command line:
\code
$ hoomd test.hoomd
\endcode
And you should see output that looks something like this:
\code
HOOMD-blue 0.9.0
Compiled: Wed Oct 28 06:58:46 EDT 2009
Copyright 2008, 2009 Ames Laboratory Iowa State University and the Regents of the University of Michigan
-----
http://codeblue.umich.edu/hoomd-blue/
This code is the implementation of the algorithms discussed in:
   Joshua A. Anderson, Chris D. Lorenz, and Alex Travesset - 'General
   Purpose Molecular Dynamics Fully Implemented on Graphics Processing
   Units', Journal of Computational Physics 227 (2008) 5342-5359
-----
test.hoomd:004  |  init.create_random(N=100, phi_p=0.01, name='A')
test.hoomd:007  |  lj = pair.lj(r_cut=3.0)
test.hoomd:008  |  lj.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
test.hoomd:011  |  all = group.all();
Group "all" created containing 100 particles
test.hoomd:012  |  integrate.mode_standard(dt=0.005)
test.hoomd:013  |  integrate.nvt(group=all, T=1.2, tau=0.5)
test.hoomd:016  |  run(10e3)
** starting run **
Time 00:00:00 | Step 10000 / 10000 | TPS 35417.9 | ETA 00:00:00
Average TPS: 35405
---------
-- Neighborlist stats:
370 normal updates / 100 forced updates / 0 dangerous updates
n_neigh_min: 0 / n_neigh_max: 10 / n_neigh_avg: 2.41
bins_min: 0 / bins_max: 6 / bins_avg: 1.5625
** run complete **
\endcode

<b>That's it!</b> You've just run your first simulation with HOOMD-blue.

<hr>
<h2>Understanding the output</h2>

The first few lines of output are just a header notifying you which version of HOOMD-blue you are running and when
it was compiled along with a link to the website and the reference to the paper discussing the algorithms
used in HOOMD-blue.

The simulation output starts at:
\code test.hoomd:004  |  init.create_random(N=100, phi_p=0.01, name='A') \endcode
Each hoomd_script command prints the file and line where it was run along with the entire text of the command.
This can be potentially very useful in debugging problems, as it will allow you to hone in on the command in the
script that is producing the error message.

When a \link hoomd_script.run() run()\endlink command is executed, hoomd steps the simulation forward that many time
steps. While it is doing so, it periodically prints out status lines like the one seen above.
\code
Time 00:00:00 | Step 10000 / 10000 | TPS 41990.9 | ETA 00:00:00
\endcode
 - \b Time is the total time spent (so far) in the current simulation in HH:MM:SS (totaled over multiple \link hoomd_script.run() run()\endlink commands)
 - <b>Step current / final</b> prints the \em current time step the simulation is at and the \em final time step of the \link hoomd_script.run() run()\endlink
 - \b TPS is the current rate (in <b>T</b>ime steps <b>P</b>er <b>S</b>econd) at which the simulation is progressing.
 - \b ETA is the estimated time to completion of the current \link hoomd_script.run() run()\endlink in HH:MM:SS

Since this run was so short, only one line was printed at the end. Modify the script to run a few million
time steps and run it to see what happens in longer simulations. Or just see here...
\code
Time 00:00:10 | Step 488501 / 10000000 | TPS 48850.1 | ETA 00:03:14
Time 00:00:20 | Step 976312 / 10000000 | TPS 48781.1 | ETA 00:03:04
Time 00:00:30 | Step 1462718 / 10000000 | TPS 48640.5 | ETA 00:02:55
Time 00:00:40 | Step 1950647 / 10000000 | TPS 48792.8 | ETA 00:02:44
Time 00:00:50 | Step 2436905 / 10000000 | TPS 48625.4 | ETA 00:02:35
Time 00:01:00 | Step 2924701 / 10000000 | TPS 48779.5 | ETA 00:02:25
Time 00:01:10 | Step 3410821 / 10000000 | TPS 48612 | ETA 00:02:15
\endcode

The final bit of output at the end of the run prints statistics from various parts of the computation.
In this example, only the neighbor list prints statistics.
\code
---------
-- Neighborlist stats:
370 normal updates / 100 forced updates / 0 dangerous updates
n_neigh_min: 0 / n_neigh_max: 10 / n_neigh_avg: 2.41
bins_min: 0 / bins_max: 6 / bins_avg: 1.5625
\endcode
Differently configured simulation scripts may print additional information here.

<hr>
<h2>Line by line details</h2>
 -# The first line of every hoomd job script (except for comment lines starting with #) must be
\code
from hoomd_script import *
\endcode
This line takes the python code of hoomd_script, compiles it and loads it in so it can be used.
hoomd_script contains the code for commands such as \link hoomd_script.init.create_random() init.create_random()\endlink which is why this line
must be first.<br><br>
 -# The next line initializes the execution context. This also parses command line arguments. The context must be initialized before any other command can be executed.
\code
context.initialize()
\endcode
 -# After the context is initialized, the system must be initialized. In this example,
 we create a 100 random particles named \b A.
\code
init.create_random(N=100, phi_p=0.01, name='A')
\endcode
 Here is a good point to call attention to one of HOOMD-blue's nifty features. You can name a particle type <b>anything you want</b>.
 If you want to name a particular particle type 'My ridiculously long particle type name', be my guest. hoomd doesn't care one
 way or another as it just stores the string you give it. Just be warned that some software packages only handle names up
 to a certain length, so some information may be lost when they load mol2 (\link hoomd_script.dump.mol2 dump.mol2\endlink)
 or xml (\link hoomd_script.dump.xml dump.xml\endlink) files written by HOOMD-blue.<br>
 Documentation for \link hoomd_script.init.create_random init.create_random\endlink<br><br>
 -# The next line specifies the pair force between particle pairs in the simulation. In the example, we create a Lennard-Jones
 pair force with a cutoff radius of 3.0.
\code
lj = pair.lj(r_cut=3.0)
\endcode
 This line has the structure \c variable=command which saves the result of the command for later modification (see why on the
 next line of the script). In HOOMD-blue, any number of forces can be specified, even zero if that is what you need
 (use a separate line and variable name for each one). All specified forces are added together during the simulation.<br>
 Documentation for \link hoomd_script.pair.lj pair.lj\endlink<br><br>
 -# The parameters of the force must also be specified before the simulation is \link hoomd_script.run() run()\endlink (you will get
     an error if you forget). The next line sets the parameters \a epsilon and \a sigma for the Lennard-Jones force
     between particles of types A and A.
\code
lj.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
\endcode
    The example script only has a single particle type in the simulation so one line is sufficient. In more complicated
    simulations with more than one particle type every unique pair must be specified (i.e. 'A','A', 'A','B', and 'B',B').
    Use one line like that above for each pair, or specify a list of types to assign the given parameters
    (see \link hoomd_script.pair.coeff.set() pair_coeff.set()\endlink for examples).<br><br>
 -# After that, we choose the integrator to move particles forward in time. As with forces, more than one integration
    method can be applied, as long as they are set on different groups. However, only one integration \b mode can be
    active at a time (specifying another will overwrite the first). Also, there \b must be an integration mode set. If
    you try running the simulation without one hoomd will print an error message. Here, we specify a standard
    integration mode with a time step \a dt set to 0.005. The Nos&eacute;-Hoover thermostat is applied to a group
    containing all particles, with the temperature target \a T set at 1.2 and the parameter \a tau at 0.5. Like with
    the pair force above, the group is saved in a variable to be used a few lines later in the script.
\code
all = group.all();
integrate.mode_standard(dt=0.005)
integrate.nvt(group=all, T=1.2, tau=0.5)
\endcode
    After the initialization and before the \link hoomd_script.run() run()\endlink command, the order in which commands are called
    doesn't matter. The NVT integrator could just as easily been specified before the pair force.<br>
    Documentation for \link hoomd_script.group group\endlink<br>
    Documentation for \link hoomd_script.integrate integrate\endlink<br>
    Documentation for \link hoomd_script.integrate.mode_standard integrate.mode_standard\endlink<br>
    Documentation for \link hoomd_script.integrate.nvt integrate.nvt\endlink<br><br>
 -# Finally, the run command actually takes the job settings previously specified and runs the simulation through time.
\code
run(10e3)
\endcode
    This simple example only runs for 10,000 steps but real simulations might be run for 10's of millions, spending days of computation time
    in this single command. There is no limit that there be a single run command in a given script. If your simulation needs to turn
    off a certain force or change integrators and then continue, you can do that. Just execute the commands to make the changes after the first
    run and before the second.<br>
    Documentation for \link hoomd_script.run() run()\endlink

<hr>
<h2>Components of a %hoomd_script command</h2>

The init line is as good an example as any.
\code
init.create_random(N=100, phi_p=0.01, name='A')
\endcode
Parts of the command
 - \b init - The package. Every command is in its own package to keep it organized
 - \b . - Python syntax needed to access a member of the package
 - \b create_random - The command name to run
 - \b ( - Python required syntax to note the start of an argument list
 - <b>N=100, phi_p=0.01, name='A'</b> - Arguments (more on these below)
 - \b ) - Python required syntax to note the end of an argument list
 - \<enter\> - Python required syntax to execute the command

About the arguments<br>
Multiple arguments of the form \c name=value are separated by commas. Whitespace is ignored
so \c name \c = \c value works too. The order of arguments doesn't matter (as long as
you specify them by name). I.e. all of the following are identical:
\code
init.create_random(N=100, name='A', phi_p=0.01)
init.create_random(phi_p = 0.01, N = 100, name = 'A')
init.create_random(phi_p=0.01, name='A', N=100)
\endcode

Check the documentation for a specific command to see what the arguments are and what they mean (i.e.
see \link hoomd_script.init.create_random init.create_random\endlink). Here
is a copy of the documentation for init.create_random:
\code
init.create_random
    (         N,
              phi_p,
              name = "A",
              min_dist = 1.0
    )

Parameters:
        N     Number of particles to create
        phi_p     Packing fraction of particles in the simulation box
        name     Name of the particle type to create
        min_dist     Minimum distance particles will be separated by
\endcode

First of all, notice in the header for the command that some arguments are listed with an = sign, like \c name="A". This means
that argument has a default value associated with it. If you are happy with the default value, you don't need to specify that
argument in the list. In our example, we have always been setting \c name='A' anyways so using
\code
init.create_random(N=100, phi_p=0.01)
\endcode
is identical.

Those arguments that are listed without the = sign (N, phi_P here) have no default value and \b must be specified. Python
will give you an error if you don't.

init.create_random() doesn't have any optional arguments, but some commands do. Optional arguments will be labeled as
such and have a default value of \c None. The documentation for any optional arguments will clearly indicate what
occurs when you do or do not specify it in the argument list.

<hr>
<h2>Where to go from here</h2>
This quick tutorial is only the tip of the iceberg. There are a lot more resources in the documentation.
 - Find out how to control what resources hoomd uses to execute simulations: \ref page_command_line_options
 - Page through the list of all commands you can use to define a simulation: \ref page_command_list
 - Examine more complicated scripts that illustrate typical usage scenarios: \ref page_example_scripts
 - Learn how to compile hoomd so you can modify the code to suit your needs: \ref page_compile_guide

*/
