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.2.2) 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.2.2 has the moiety-library in a separate directory structure, which needs to be obtained separately. So the two files that currently need to be downloaded are:

cavstuf-0.2.2.tar.gz and
mlib-0.2.2.tar.gz .

- un-gzip and untar the two archives. Three directories will have been created.

- 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 GCL-2.2, ECL-0.22, some old version of CLISP, and in MCL2.
GCL can be found at
ECL can be found at or
CLISP can be found at
MCL : Too bad. This is a commercial product. Info can be found at

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 load the CavityStuffer code, execute
(load "0.cavstuf-loader.lisp")
at the CommonLISP prompt.

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

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

- 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 "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 Oct. 5 1996
[Back to kr's Home Page]