pyUHBD README

                           Michael J. Harms
                        B. Garcia-Moreno E. Lab
                      The Johns Hopkins University
                            January 28, 2008
                               v 1.1.0

pyUHBD is a python wrapper that performes single-site finite difference contiuum
electrostatics calculations on pdb files using the University of Houston
Brownian Dynamics (UHBD) package.

Environment:
    NOTE: This script *REQUIRES* Python 2.3 or later!

    The system must have a valid compile of UHBD that is user executable.
    pyUHBD finds the location of this directory through the $UHBD environment
    variable.  Specifically, pyUHBD calls the following binaries:
        uhbd (single site, full)
        getgrids (single site), getgrid (full)
        getpots (single site), getpot (full)
        hybrids (single site), hybrid (full)

    Hydrogens are added to the pdb files using pdb_addH.py, which is part of the
    pdb_tools package.


Input files:
    The main file required by pyUHBD is a pdb file with hydrogens.  Such a file
    can be created using pdb_addH.  There is a difference between the hydrogens
    added for full or single-site calculations, so make sure that you specify
    the correct option for addH.  The program will run with only a pdb file
    (or set of pdb files) specified, but many other options can be chosen from
    the command line (type pyUHBD -h for a list).

    Some options require input files.  In most cases, these files can simply a
    list of numbers separated by whitespace (spaces, tabs, character returns).
    All lines beginning with "#" are treated as comments and ignored.  Two
    notable exceptions are -g (grid) which requires a grid specification in
    proper uhbd format:
        1.5 65 65 65
        1.0 40 40 40
        ... (up to five grids)
    and -o (override), which requires a properly formatted uhbd input file.

    The user can also choose which parameter file to use (-a --parameter-file).
    This is particularly important for full calculations.  When the user
    specifies a parameter file, the program will first look in the calling
    directory.  If the file is not there, it will look in pyUHBD/parameters.  If
    it cannot find the file, the program will die.

Output:
    Output from a pyUHBD calculation is saved in a directory based on the pdb
    file input:
        pdb_root/[single | full]/D[dielectric constant]/[ionic strength]/output
    The code does not perform any checks for previously performed calculations,
    so make sure you don't aren't going to wipe out a previous calculation when
    you set up a run.