== An example with water and TREMOLO ==

We want to create a box filled with water.

We need the following file '''singleh2o.data'''. Take the remainder of the required files (for a TREMOLO simulation) from the respective ''h2o'' example of TREMOLO.

Next, we create a 10x10x10 box filled with water at 1g/cm^3^ by calling molecuilder as follows:
{{{
molecuilder --parse-tremolo-potentials h2o.potentials -i h2o.data -o tremolo xyz --change-box "10,0,10,0,0,10" --fill-void singleh2o.data --distances "3.1,3.1,3.1"
}}}

We explain briefly the function of each action:
 * ''--parse-tremolo-potentials'': parses a TREMOLO's potentials file. Without it, molecuilder does not know that '''OT''' actually refers to an oxygen atom (with element symbol '''O''')
 * ''-i'': This is the specification of the output file (also the input file, if it contains atoms already, water is filled around it).
 * ''--change-box'': We set the box dimension by giving a vector of each edge's lengths.
 * ''--fill-void'': The empty space in the box (i.e. all of it) is filled with the atoms given by '''singleh2o.data'''. ''--distances'' refers to the distance between each molecule's center per axis (x,y,z). Note that you may also specify ''--random-atom-displacement'', ''--random-molecule-displacement'', and ''--!DoRotate'' to give the maximum random displacement for each atom, each molecule or a general rotation. Note even more that you can specify the random number generator used by the action ''--set-random-number-distribution''. Thereby, you can even have the random angles for rotation drawn from a discrete set and hence generate a discrete set of orientations of the water molecules.

If you are interested in how the last note works, try this:
{{{
molecuilder --parse-tremolo-potentials h2o.potentials -i h2o.data -o tremolo xyz --change-box "10,0,10,0,0,10" --set-random-number-distribution uniform_int --random-number-distribution-parameters "min=0;max=4" --fill-void singleh2o.data --distances "3.1,3.1,3.1" --distance-to-boundary 2 --DoRotate 1
}}}

Now, we need some more parameters:
 * ''--set-random-number-distribution'': set the random number distribution, here a uniform integral distribution.
 * ''--random-number-distribution-parameters'': We set min to 0 and max to 4, i.e. we have a five-sided dice.
 * ''--distance-to-boundary'': Minimum distance to boundary should be 2 for the molecule to be placed, otherwise it is removed.
 * ''--!DoRotate'': Enable random rotations.