Thank you for downloading 3dt and Systre. This file contains some
basic information and can be found under the name README in the folder
you choose to install the program in.
The following information applies to 3dt version 0.6.0 and Systre version
1.2.0.
===========================================================================
Introduction:
------------
The following will serve as a very basic introduction into the
3-dimensional tiler (3dt) program. Everything not mentioned here will
hopefully be fairly self-explanatory. If enough people are interested
in the program, there might some day be a proper manual.
Information on Systre, which is also part of this distribution, can be
accessed by simply clicking the "Help" button within the program.
Both Systre and 3dt are part of the Gavrog project. For news and
updates on these programs and the project in general, you can always
check the project website http://www.gavrog.org.
===========================================================================
Installation and prerequisites:
------------------------------
Gavrog requires a Java runtime environment (JRE) of version 1.5 or
higher. On some systems, Java might already be installed as a
prerequisite for other programs. Otherwise, the most straightforward way
to get a JRE is to download it from http://java.com and follow the
installation instructions given there. Set all path variables correctly
for your system as instructed (this should be done automatically for you
in most case), so that the java command can be recognized. If supported
on your system, make sure that the file extension '.jar' is associated
with the Java executable.
You should now be able to execute the installer by either double-clicking
on it's icon or, if that does not work, type the command
java -jar
in a terminal window. In the latter case, make sure you're in the same
directory as the installer file or else include the full path in the file
name.
===========================================================================
Calling the programs:
--------------------
On Windows and Linux systems, the installer can produce desktop icons
for Systre and 3dt. This is currently not possible on Apple computers,
and may fail on some Linux and other Unix systems. In this case, Systre
and 3dt can be execute using the following command line statements:
for Systre: java -jar /Systre.jar
----------
for 3dt : /bin/3dt
-------
where must be replaced with whatever location
you chose to install the programs in when prompted by the installer.
===========================================================================
Interface basics:
----------------
When 3dt is started, two windows appear - "3dt Viewer" and "3dt Controls".
The viewer window contains the main menu and displays tilings. Most of its
menu should be either self-explanatory or reveal itself after a bit of
experimentation.
The current scene can be rotated by dragging with the left mouse button
pressed, moved around by dragging with the middle button and pulled or
pushed by dragging with the middle mouse button while simultaneously
pressing the key. Pressing the right mouse button while over a face
brings up a context menu that lets you add, remove and recolor tiles.
There are also two shortcuts for quick scene manipulation:
- adds a tile at the face the mouse is over, whereas
- removes a tile. Right-clicking on a node or edge of
the underlying net of a tiling invokes similar behavior.
If the control window is in the way, you can close it and later re-open
it by selecting "View/Show Controls" on the viewer window. Please note
that closing the viewer window terminates the program.
The control window has three parts, which can be changed in size by
dragging the separating bars. The top left one is used to modify settings
for 3dt. These are saved to a configuration file after any change and
reloaded each time the program is started. Press the "Apply" button to
make changes effective.
The top right part of the control window contains information about the
current tile, and the bottom part shows any diagnostic output that might
be produced.
===========================================================================
File formats I - Delaney symbols:
--------------------------------
The 3-dimensional tiler (3dt) is based on the theory of D-symbols (short
for Delaney symbols or Delaney-Dress symbols), originally developed by
Andreas Dress. Further information can be found on
http://www.gavrog.org.
Notation varies slightly between publications. Most papers published in
mathematical journals denote the actions that assign to a chamber its d+1
neighbors (where d is the dimension) by a suffix consisting of the greek
letter "sigma" and an index between 0 and d. Others use the more familiar
functional notation 's_0(t)', 's_1(t)' and so on, where 't' is the chamber
in question. We will use the latter form. Also, the degree functions are
sometimes written 'm_01(t)' and so on, sometimes, in older papers, using
an 'r' instead of an 'm'. We will use the more recent notation.
Delaney symbol files use the suffix '.ds'. Each Delaney symbol (which
means: each tiling) is represented by a sequence of lines, the first one of
which must start with an opening angular bracket '<', whereas the final one
must end with a closing bracket '>'. Here is a simple example:
<1.1:2 3:1 2,1 2,1 2,2:3 3,3 4,4>
Each entry consists of four sections separated by colons. Thus, ignoring
the delimiting brackets, the example entry consists of the sections
'1.1', '2 3', '1 2,1 2,1 2,2' and '3 3,3 4,4'.
The first section is just for bookkeeping. It must consist of two arbitrary
positive integers, separated by a dot. The first number in the second
section is the size of the D-symbol and the second one its dimension. If
the dimension's missing, it is assumed to be 2.
By convention, elements (chambers) are numbered from 1 up to the size n of
the symbol, while indexes go from 0 to d.
The third section consists of d+1 comma-separated parts, each defining one
of the functions s_0 up to s_d (so in this case, up to s_3). In our
example, the four parts are thus
'1 2', '1 2', '1 2' and '2'.
Within the i-th part, the values for the function s_i are given in order,
starting from s_i(1) and going up to s_i(d). If s_i(a)=b for b>a, we omit
the specification of s_i(b), because it is already clear that it must be
a. Thus, the first part '1 2' defines s_0(1)=1 and s_0(2)=2, and similarly
for the second and third part. The fourth part means that s_3(1)=2 and,
consequently s_3(2)=1. If our example symbol had more than 2 elements, the
next value would be s_3(3), not s_3(2).
The fourth section consists of d parts, in this case
'3 3', '3 4' and '4'.
These define the values of the functions m_01, m_12 and so on, up to (in
this case) m_23. The number m_ij only appears once for each i,j-orbit. In
particular, in the third part, m_23(2) is not specified because s_3(1)=2,
thus m_23(1)=m_23(2) and m_23(1) has already been given. The complete
D-symbol in tabular form thus looks like this:
| s_0 | s_1 | s_2 | s_3 || m_01 | m_12 | m_23
---+-----+-----+-----+-----++------+------+------
1 | 1 | 1 | 1 | 2 || 3 | 3 | 4
2 | 2 | 2 | 2 | 1 || 3 | 4 | 4
===========================================================================
File formats II - face lists:
----------------------------
Writing Delaney symbols by hand is a nice excercise, but nothing you
would want to do on a regular basis. If coordinates for a tiling are
available, there is a more pleasant option, a face-list file. The
suffix is '.cgd' (which stands for 'crystal geometry data'). The file
'cube.cgd' in this distribution provides two examples, both defining
the well-known face-to-face tiling by ordinary cubes. Let's look at
the first entry:
TILING
NAME primitive-cubic
FACES
4 0 0 0 1 0 0 1 1 0 0 1 0
4 0 0 0 1 0 0 1 0 1 0 0 1
4 0 0 0 0 1 0 0 1 1 0 0 1
END
The 'TILING' and 'END' lines are obligatory and serve as delimiters, just
like the '<' and '>' in D-symbol files. The 'NAME' line is optional. Each
line between 'FACES' and 'END' specifies one 2-dimensional face of the
tiling. This is specified by a face size (the number of vertices or corners
for this face), followed by the list of vertices, each given by three
ordinary cartesian coordinates. So in this example, the faces given are
three unit squares, one for each pair of opposite faces of a neatly aligned
unit cube.
All remaining faces of the tiling are generated by applying all the
symmetries, which in this case are not specified explicitly. The default
symmetry group is generated by the three unit translations along the x-, y-
and z-axis. In effect, the "standard" tiling by unit cubes is produced.
People familiar with crystallographic groups may save a fair amount of
typing by specifying an appropriate group. For example, the second entry in
'cube.cgd' looks like this:
TILING
NAME primitive-cubic
GROUP P432
FACES
4 0 0 0 1 0 0 1 1 0 0 1 0
END
Here, the 'GROUP' line specifies a crystallographic space group by its
conventional name, implying a set of extra symmetry generators as given in
the "International Tables for Crystallography, Volume A" entry for that
group. Because the three faces as given in the first example are really
symmetric to each other, we only need to specify one of them now.
In this notation, our example from the D-symbols section might look like
this:
TILING
NAME octa-tetra
GROUP F432
FACES 3 0.5 0.5 0 0.5 0 0.5 0 0.5 0.5
END
Without the extra symmetry, one would need to specify 32 triangles.
In addition to a symmetry group, unit cell parameters can also be
specified. This is useful if you want 3dt to use the coordinates from
the input file directly instead of computing its own. We can add the unit
cell specification for the first example tiling above like this:
TILING
NAME primitive-cubic
CELL 1.0 2.0 3.0 90.0 75.0 60.0
FACES
4 0 0 0 1 0 0 1 1 0 0 1 0
4 0 0 0 1 0 0 1 0 1 0 0 1
4 0 0 0 0 1 0 0 1 1 0 0 1
END
Here, as usual, the six numbers specify the lengths a, b and c of the x-,
y- and z-axis, respectively, followed by the y-z angle alpha, the x-z
angle beta and finally the x-y angle gamma.
===========================================================================
That's all folks! Have fun with the program and please keep in touch.
Olaf Delgado
===========================================================================