CIONIZE 0.2 README 
=================

Overview: 
--------- 
CIonize  (short for "coulombic 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: 
----------
CIonize is now built as part of the VMD plugin distribution.

Usage: 
------ 
CIonize requires as input a file of the molecule to have ions added 
in a format that includes charges, and will output a file containing
the ion coordinates.  Running the ionize executable with no arguments will
bring up a short list of possible options, which is reproduced below:

    cionize: Place ions by finding minima in a coulombic potential
    Usage: cionize (-p numprocs) (-i configfile) (-f inputformat) inputfile
        -i inputfile (stdin)
        -p max_processors (1)
        -f Input file format (guesses from extension if not given)

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).

Once cionize has been started, commands may be either read from an input
file (specified by the -i switch) or from standard input (in which case the
ionize run will be interactive). Any given ionize run consists of two phases:
before and after the calculation of a coulombic energy grid. At any point
the user may enter the command `HELP` to get a list of current options (these
options are also outlined below). In the initial phase of the program, which
lasts until the `BEGIN` keyword is entered, the parameters of the calculation
may be modified, and a previously calculated energy grid (in the dx format)
may be specified. When the `BEGIN` keyword is given, the energy grid will be
calculated (unless a previously calculated grid was input), and the program
will pass to a mode where ions will be placed.

When in this second mode, users may place ions, save the previous batch of
ions to a pdb file, or save the current energy grid (which incorporates the
effects of ions placed up until that point) to a dx file. Note that placing
ions *does not* automatically save them; a separate command is required for
this. The ion placement mode will last until the `EXIT` keyword is specified
or the program encounters an EOF in the input.

Recognized keywords:
--------------------

In all cases, `value` represents a required argument, and `(value)`
and optional argument. Input keywords are not case sensitive, but arguments
such as filenames are.

### Before energy grid calculation ###

+ `R_ION_SOLUTE r` -- Minimum ion-solute distance
+ `R_ION_ION r`--Minimum ion-ion distance
+ `BORDERSIZE distance`--Distance beyond solute to extend calculations
+ `GRIDSPACING spacing`--Grid density in angstroms
+ `GRIDFILE file`--Use energy grid from the specified file instead of calculating a new one
+ `SHOWOPT`--Show the values of current settings
+ `BEGIN`--Calculate the energy grid with the existing parameters

### After energy grid calculation ###

+ `SAVEGRID file`--Save current energy grid to a dx file
+ `PLACEION ionname n ioncharge`--Place a set of n ions using the current grid
+ `SAVEION (filetype) file`--Save the most recently placed batch of ions
to a file. If `filetype` is ommitted, it is guessed from the extension. of `file`


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