Bridging Waters
Bridging Waters 1.0
-------------------

REQUIREMENTS: VMD Version 1.0 or greater

DESCRIPTION:
	When the frame changes, a cache is checked to see if a selection has been
	computed for it.  If not, one is made and added to the cache.  The Tcl
	variable "bridging" is set to the atomselection, and element 0 of the
	graphics list is changed to "@bridging".  This forces that element to
	be redrawn using the new selection.

HOW IT WORKS:
        One of the researchers here needed a way to see which waters bridged
        between a protein and a nucleic acid during a trajectory.  The
        specific waters change during the simulation, so the static method
        used in the graphics form doesn't work.  Instead, the vmd_frame
        variable and a caching method similar to the sscache of the previous
        section was used for the following solution:

        The cache data is stored in the array bridging_waters.  Unlike
        sscache, this array is indexed only by the frame number; you'll
        have to modify it to analyze multiple changing selections.

        When the frame number changes, the cache is checked and, if no data
        exists, the selection is rebuilt.  Since the selection is created in a
        procedure, it must be given by the global command to make it exist
        outside that procedure's context.

        The global Tcl variable bridging is set to the selection for
        this frame.

        The first text selection in the graphics form is set to 
        @bridging.  This is one of the special extensions to the selection
        language which enable the selections to reference a Tcl variable.
        Note also that the display updates are temporarily turned off.  This
        is used to keep the display from being drawn an additional time by the
        call to mol modselect.  This is done every time the frame
        changes since that's the only way to tell VMD the graphics have
        changed; forcing it to recalculate that representation's display.

        Since the selections are available in the global scope, you can analyze
        the results at any time.  The num_bridging function prints how many 
        atoms are in each selection of the cache.

PROCEDURES:
	start_bridging molid -- start the trace on the vmd_frame for molid
	stop_bridging -- stop the current trace
	calc_bridging -- check the cache, create a selection if needed
	num_bridging -- example of how to get data from the cache


EXAMPLE USAGE:
	mol load psf er-ere.psf pdb er-ere.pdb
	# start the bridge calculations
	start_bridging
	# however, one frame has already been read, so do its calculations
	# by hand
	calc_bridging
	# read the rest of the frames (the selections are automatically computed)
	animate read dcd dyn100frames.DCD

DOWNLOAD THE FILE:
	bridging_waters.tcl

AUTHOR:
	Andrew Dalke (dalke@ks.uiuc.edu)