Marsette Vona: XSim Info

XSim Info

click to run the applet, applet with auto library download, or Java Web Start

Crystalline Robots

Crystalline robots are a type of unit-modular self-reconfiguring robot where each module is a rectilinear atom whose faces can extend and retract.

This page introduces XSim, a Java and JScheme simulator for 3D crystalline robots with hardware-accelerated graphics. You can run XSim as an applet or via Java Web Start by clicking one of the links at the top of the page.

Requirements and Installation

XSim has been tested under 1.5+ JREs from Sun with Java3D 1.5+ on Linux (Mozilla), Windows (Firefox) and Mac OS X (Safari). Other JREs may work, but working installations of Java3D (not typically included with a JRE) and Swing (typically only included in full with Sun JREs, at the time of this writing) are required to run as a stand-alone application. Note that at the time of this writing, Java3D 1.5+ on Mac OS X itself apparrently requires JOGL. Both the Java Web Start and the the applet with library auto-download links above should automatically download any necessary Java3D and JOGL libraries. Note that you should only use the applet with library auto-download if you do not already have the necessary libraries installed on your system. For example, Apple has recently been delivering Java on OS X with the necessry libraries pre-installed. If unsure, try each link above in order. Finally, note that the auto-download system does not actually install the downloaded libraries onto your system; they will only be available for the execution of this applet.

Usage

XSim is implemented as a REPL-style interactive JScheme interpreter, with a built-in API extended to include the particular XSim simulation and display APIs, as well as some additional sugar. Several variables are pre-set, including:

xtal: the Xtal simulator instance (this is generally used only implicitly via calls to simulation APIs, such as (xadd ...))
xdisplay: the simulation Display instance (again, this is generally used only implicitly via calls to display APIs like (fit))
X, Y, Z, P, N: axis and direction identifier constants
C, E, I, O and related: expansion and connection state constants

The full XSim JScheme API is defined in xsim-api.scm, with additional scheme sugar in xsim-extra.scm. In general, the JScheme api is a thin cover over the corresponding Java API. For example, (xremove-all) covers Xtal.removeAll().

See the javadoc and the source for full details. In particular, a read through the header doc for Xtal and Display, followed by a scan of xsim-api.scm and xsim-extra.scm, will give a good picture of all XSim functions and how to invoke them.

When run as an application (java -jar XSim.jar), you interact with XSim via the console. It may be more convenient to use a console with specific support for scheme interaction, for example, Emacs Quack (tip: open xsim-api.scm and xsim-extra.scm in the same Emacs session and you'll get M-/ name completion for the XSim API). Source files specified on the command line (ending in ".scm"), if any, are loaded in order. If a file named "init.scm" is specified, it is loaded before the GUI is displayed and can thus set an initial configuration. Other files are loaded after the GUI is displayed.

When run as an applet, you interact with XSim via the pop-up text box.

See the SimpleMixedJ3D and Display class header documentation for details on how to navigate using the mouse and keyboard, how to pick atoms, and how to change properties of the display.

Scalability

In brief, the simulator requires space linear in the total number of atoms, and time linear in the number of atoms for each operation or parallel set of operations. See the Xtal javadoc for details.

Scalablity tests were performed for 1M and 10M atom simulations on the following platform:


AMD Athlon(tm) XP 2100+, 1734.408MHz, 256 KB cache
1GB RAM
Linux 2.6.17-prep i686 athlon i386 GNU/Linux
NVIDIA GPU GeForce FX 5500, VideoRAM: 262144 kBytes

Java HotSpot(TM) Client VM (build 1.5.0_06-b05, mixed mode, sharing)
java options: -Xmx900m -ea

For 1M atoms, construction of the initial xtal took about 8s, and resulted in a total application footprint of about 125MB. (draw-fast-planar) renders of the entire xtal took about 5s; topological operations took about 0.2s, and geometric operations took about 11s.

For 10M atoms, construction of the initial xtal took about 120s, and resulted in a total application footprint of about 870MB. (draw-fast-planar) renders of the entire xtal took about 35s; topological operations took about 1.7s, and geometric operations took about 41s.

Download

XSim is released in source and binary form under the GNU GPL.

Building

The build system is based on the Super-Ninja Makefile. The distribution jar comes with everything rolled into one: java source, scheme source, html (m4) source, the makefile and related stuff, and precompiled versions of everything (both java class files and javadoc). Further, it includes the pure java dependencies of XSim, which are Vona's java utilities and (a slightly modified) JScheme.

You'll probably want to create a directory into which to unpack the jar (jar xvf XSim.jar). The code for XSim proper will be under the unpacked directory xsim/.

make clean removes the precompiled stuff, make rebuilds the class files, and make javadoc builds the documentation.

To build you'll need a 1.5 JDK available (i.e. with the binaries on your path) with a full Swing implementation and Java3D 1.5. You'll also need (GNU) make and m4.

Disclaimer

THIS INFORMATION AND/OR SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS INFORMATION AND/OR SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

vona@mit.edu

Wed Jan 23 18:31:22 EST 2008