IONIZE 0.1 README 
=================

Overview: 
--------- 
Ionize is a threaded program for placing
counterions near a biological molecule in preparation for molecular
dynamics simulations. In this case, placement is performed by
calculating the coulombic potential due to the molecule in the nearby
volume, and placing ions at points of minimal energy. After each ion
is placed, the potential is updated, so that subsequent ions will
be placed in response to this. Unlike some ion placement tools,
ionize should be used *prior* to solvation so that the potential
from unequilibrated water does not interfere with it (the addition
of water would also make the energy calculations even more time
consuming). Ionize is designed to be used on multiple processors;
it uses a pthreads parallel implementation to run on shared memory
machines (any traditional multiprocessor machine, or shared memory
clusters such as an SGI Altix). After ionize is finished, you should
solvate your system normally.

Compiling: 
----------
The ionize distribution comes with a makefile
for a variety of supported target architectures. Type `make` with
no arguments to see a list of possible targets, and `make TARGET`
to build ionize for the architecture `TARGET`. Ionize is written
in standard C; current compilation options exist for gcc and icc.

Usage: 
------ 
Ionize requires as input a pdb file of the molecule to have ions
added *with the charge of each atom in its beta field*, and will
output a pdb containing the ion coordinates.  Running the ionize
executable with no arguments will bring up a short list of possible
options, which is reproduced below:

    ionize: Place ions by finding minima in a coulombic potential
    Usage: ionize (options) input.pdb output.pdb
        input.pdb must be a pdb file with atom charges in the beta field
    Optional arguments (with defaults):
        -n number of ions to place (1) 
        -r Minimum distance from ions
        to solute (6.0) 
        -i Minimum distance between placed ions (10.0) 
        -g Grid spacing in angstroms (0.5) 
        -b Additional perimeter to search for ion locations (10.0) 
        -t ion name (SOD) 
        -q ion charge (1.0) 
        -p max_processors (1)

Most of these options should be fairly self-explanatory. Note that
ionize currently only adds one ion type at a time; future versions
will support both addition of multiple ion types, and saving of
the energy grid for later use. Note that the -p switch specifies
the maximum number of processors to be used by ionize, but it will
not try to exceed the maximum number available (for example, the
number allocated on an Altix run).

Ionize can also be run from a configuration file, using the wrapper
script runionize. In this case, ionize is run with the command

    runionize configfile

where `configfile` contains options formatted as for a
[SODIUM](http://www.ks.uiuc.edu/Development/MDTools/sodium/)
input file.

Authors: 
-------- 
Ionize and the associated infrastructure were
written by Peter Freddolino, John Stone, and Leonardo Trabuco. Please
contact [Peter Freddolino](mailto:petefred@ks.uiuc.edu) with any
questions or comments.

License: 
--------
Ionize is released under the [UIUC Open Source License](http://www.ks.uiuc.edu/Development/MDTools/ionize/license.html). This license is reproduced in the file `LICENSE` included with the ionize source distribution.

Unit Test:
----------
You can test your ionize installation by running `make test` in the ionize build directory. This will run a short ionize job on a small alpha helix and compare the results to a standard answer included in the ionize distribution. The differences, if any, will then be displayed. You should be worried if there are any differences outside of the last significant digit of the coordinates.
