This is a still very experimental tool to investigate the cram-packing (stuffing) of predefined volumes (cavities) with branched polymers. It is thus supposed to become a polymer design tool, for devising polymers that will fold up in a designed, rigid three-dimensional shape, with high predictability.

The current state of this program (version 0.3) should probably be considered to not even be alpha, as it still is mainly a toy that does not yet perform any production quality work. It is released mainly to satisfy the curiosity of interested individuals. Have fun, and try to improve it.

FIGURE: This is about how good cavstuf does at the moment. Bridging the gulf between this tree molecule and actual real world utility would probably take merely a little over one order of magnitude in improvement... :-)

Capsule Summary of CavStuf

The purpose of the CavityStuffer program is to propose tree-like polymeric molecules, which when synthesized and allowed to fold into their globular structure, will densely fill a given volume, the surface of which was prescribed to atomic detail. The CavityStuffer program generates its proposals by growing polymers blindly, and in a randomized fashion, it chooses sites on the tree for further attachment and elongation. Once a site has been chosen, a moiety (monomer) is selected from a library of allowed moieties, similar in concept to allowed moves in a game of chess. The moieties are stored in the library as rigid, three-dimensional puzzle-pieces (as rotamers); so the CavityStuffer program works by trying to fit three-dimensional geometric shapes into the given volume. Whenever a chosen moiety does not fit (i.e. if it clashes with other atoms already in place), it is discarded, and a different moiety will be tried instead.

This scheme largely avoids the expensive numerical tasks encountered in energy calculations (which are commonly used for studies of folding polymers such as proteins), because clash-detection is quick. Because the generation of individual proposals is fast, a large number can be generated automatically without human super-vision and sorted according to how well they fill the volume. There are various places in the program where one could add in smarter and higher-level strategies than the random selection mechanism used now.

INSTALLATION and tiny User Guide

- Get the latest distribution. Version-0.3 now consists of one single distribution tar file:

cavstuf-0.3.tar.gz .

For historical purposes, the old Version-0.2.2 can still be accessed, but i did find a couple of bugs in it.

- un-gzip and untar the archive. do a cd cavstuf-0.3/lisp/ .

- Note for Mac-fanatics: The newline characters in the files are UN!X-style linefeeds. The cavstuf lisp files first need to be converted to Mac-style carriage returns, if run on a Mac. A text editor such as BBEdit or Alpha can be used for this. If run in MCL, the PDB files can remain as they are. They can be read nevertheless, with the (read-line ...) modification that is included.

- CavStuf has been tested in CMUCL-18a, GCL-2.2.1, ECL-0.27. Also, a long time ago, in some old version of CLISP, in Allegro ACL-4.3 , and in MCL2. Nowadays, almost certainly small adjustments would be needed for some of these in "0.cavstuf-loader.lisp". My current bias is to shift all development over to CMUCL.

The machine specific setup quirks and naming of directories, etc., should all be confined to the file
, which should be the only file that might need editing. So, in order to prepare for loading the CavityStuffer code, execute

(load "0.cavstuf-loader.lisp")
at the CommonLISP prompt. Then, execute the following two lines to compile and load the code:
(in-package :cvst)

Please feel free to provide feedback about problems encountered, and about ports to further CommonLISP implementations.

- While it is not necessary, a sample moiety library can be rebuilt by running the file
. This will need the small PDB files that are included in the distribution. It is still relatively cumbersome to generate more and novel moieties from scratch. This involves some hand-work, and a good working knowledge in organic chemistry and a molecular editing and energy minimization program are needed. At some point, I'll probably write a tutorial on how to do this, and some additional tools. In the meantime, please let me know of problems, and I will try to help out, as time permits.

Please also note that it might be best to just try using the *.mlib file that is included for the first experiments. It does not necessarily need to be rebuilt. Attention when using ECL-0.22 : there seems to be a bug with writing out arrays. Some of them only get printed in a manner that can not be read back in. In that case, one needs to use the *.mlib that is supplied, until this bug is fixed. This is still not fixed in ECL-0.27 .

- Building polymers and controlling the program can be done by modifying some of the examples provided by the file
. That basically represents the current user interface. :-) CavStuf was mainly intended to be run in batch mode, crunching for a long time, and then storing a few (hopefully) good PDB files.

Internals of CavStuf

For some amount of overview of the program structure, start with reading the file "doc/Architecture.txt". The basic data structures that deal with molecules, etc. are described in "structure-defs.lisp". The highest level driving of the underlying code machinery emanates from the file "growth-driver.lisp".

Who created CavStuf ?

CavityStuffer was mainly written by M. Krummenacker (KR), with valuable input from K. E. Drexler. The work was funded up to the end of 1993 by IMM, the Institute for Molecular Manufacturing, Palo Alto, CA. Thank you very much.

This program is copyrighted by IMM (c) 1993, with additions since then copyrighted by KR. I have been granted the right by IMM to grant unrestricted, non-exclusive sub-licenses in any manner that pleases me, and so I am doing the following:

The program "CavityStuffer" is provided to the world in terms of the GNU GPL (General Public License), a copy of which resides in the file "COPYING-2.0". A copy of that file also can be obtained from

Free Software Foundation, Inc.
59 Temple Place - Suite 330
Boston, MA 02111-1307, USA

Feedback, bug reports, improvements, etc., are very welcome, and should be directed to:

Markus Krummenacker

There are plans to put together a mailing list for CavityStuffer issues and development. People interested in this, and who want to be kept up to date, should send their eddress to KR.

As the effort behind CavStuf currently is entirely carried by my (sparingly available) spare time, donations of any and all kinds and of any size (or smallness) are gratefully accepted and appreciated, and might provide additional motivation to push CavStuf to a higher level of functionality and utility. Contributions can be sent to:

Markus Krummenacker
P.O.Box 1073
Los Altos CA 94023-1073

Thanx for the interest in CavityStuffer.

Many Greetings, KR

last updated April 20 1998
[Back to kr's Home Page]