webstart |  download |  browse source |  javadoc

A Simulator for 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.

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.

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

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
GNU/Linux 2.6.17-prep i686 athlon i386
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.

Requirements and Installation

XSim has been tested under 1.5+ JREs from Sun with Java3D 1.5+ on GNU/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. Note that at the time of this writing, Java3D 1.5+ on Mac OS X itself apparrently requires JOGL.

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