HexAtom User Guide

Student 1

CSC520 – Fall 2012
This page is intentionally blank. (Here is an example of change tracking[DEP1].)

Contents

Environment Set Up

Starting HexAtom

Command Line Options

Configuration Options

Probability Configuration

Generating an Atom

GUI Control and Operation

Atom Generation

Command Line Commands Enter Area

Command Output Results Window

Game Status

Live Coding & Importing Python Functions

Live Coding

Importing and Loading Code and Python Functions

Loading and Saving Code

Importing Python Functions

Appendix A – Atom Colors

Appendix B - interp Command Syntax

Appendix C – Defects and Enhancements

Appendix D – Version History

Environment Set Up

In order to run HexAtom, a user’s environment must be configured with the required software, proper permissions and environmental variables. HexAtom can be run on any system that supports Java, check applicable operating system documentation for specifics on configuring these settings.

  • Software – The following software packages are required to compile and run HexAtom. See platform specific installation instructions for details on installation and configuration.
  • Java Runtime Environment
  • Java Software Development Kit
  • Jython
  • Permissions – HexAtom requires the ability to run, or have running, Java’s rmiregistry. This process will open a system level port and start up a listener. Local administrator (Windows) or root (Linux) permissions allow this access. If this level of permission is not possible, work with the system administrator to have the process started at system boot or to create a user role with access to start the process
  • Environmental Variables - There are two environmental variables that need to be configured to run HexAtom.
  • PATH – The PATH environmental variable must contain the path to both Java and Jython.
  • For Windows based systems:
  • Control Panel -> System -> Advanced -> Environment Variables and set system variable PATH to include the path to Java and Jython, making sure to use \ in a path and ‘;’ as a separator.
  • For Linux based systems (Assuming bash shell):
  • export PATH="DIRECTORYHOLDINGJYTHON:DIRECTORYHOLDINGJAVA:$PATH"
  • CLASSPATH – The CLASSPATH environmental variable must contain the path to the main directory for the Java code for HexAtom (for example: /home/john/JavaLang) and path to the location of the jcip-annotations.jar file; this needs to include the name of the jar file in the path (Example: /home/john/Java/Lib/jcip-annotations.jar)
  • Command Line Access – Separate command windows are required to start the HexAtom server and each of the GUIs.
  • Running HexAtom on a remote server – HexAtom can be run on a linux based system and accessed from a Windows or Apple based system. In order to do this, the Windows or Apple based system must have an X Server running, SSH client and the users SSH sessions must be configured to tunnel X-11 traffic.
  • X Server - Xming is a freeware X Server that works well on MS Windows 7 ( Download, install and launch Xming server on the users Windows system.
  • SSH Client – SSH access is required to access linux based systems. PuTTY is a freeware SSH client (
  • SSH X-11 configuration – SSH must be configured to tunnel X-11 traffic back through the users SSH session. This is done by enabling X-11 forwarding and specifying the localhost and port for the session. Below is the configuration for a PuTTY session, once configured, the session can be saved for future use.
  • Virtual Machines – Virtual Machines are an excellent resource for development and testing of applications, including HexAtom. Oracle’s Virtual Box ( is freeware VM software package that runs on Windows 7, is simple to install and allows for basic VM functionality. Once installed, a virtual machine running Windows based OS or Linux based OS can be built and used for development and testing. Testing and development for this documentation was primarily completed on a Debian Linux server ( which was a virtual server built in Oracle’s Virtual Box. All this was running on an HP Windows 7 laptop. Access to the VM based Debian was via PuTTY and used Xming to manage the session windows.

Starting HexAtom

Starting HexAtom is simple and requires one command window per GUI. Currently there are three python scripts used to run the HexAtom server and GUIs:

  1. ‘testgame’ – This is a wrapper to start the HexAtom command line server which starts the output display for HexAtom. HexAtom is designed to run on a planetarium ceiling, so the output has a circle to mark the edges of the display.
  2. ‘testui’ – This is a wrapper to run the python HexAtomCmdInterp.py script. This launches the GUI that is used to display atoms and to do live coding.
  3. ‘testmidi’ – This is a wrapper to run the python MidiMapCmdInterp.py script. This starts the GUI that handles the midi portion of HexAtom. This version of the user guide does not document the use or features of testmidi; there are no further references to testmidi in this guide. For documentation on testmidi, check later versions of this guide (which may have this disclaimer omitted) or with Dr Parson for more information or documentation.

To Start HexAtom:

  1. Start Java’s rmiregistry.
  2. Run ‘rmiregistry &’ to start the process in the background
  1. Start ‘testgame’ to launch the display window.
  2. Run ‘testgame’ to start the main command session, the file location must either be specified or in the PATH.
  1. A small window will open. This window is used to position the main window and is required because of an issue when using multiple monitors.
  1. Move the initial window into position on the display and click ‘Normal Display’
  1. The main display window will open

  1. Press enter in the command window. The system will display basic debug information; HexAtom is now ready for command line use.

  1. Start ‘testui’ to launch the GUI console.
  2. In a separate command window from the one used to launch the server, run ‘testui’ to start the main command session, the file location must either be specified or in the PATH.
  1. The GUI will load and is ready for use

  1. Troubleshooting – HexAtom should run without error if the environment is set up and the user account has proper permissions. There are a few errors that can occur if the servers are not properly started, not started in the proper order, or one of the servers crashes.
  2. rmiregistry is not running. The rmiregistry server/process is required for the other programs to properly execute; however, testgame will start without rmiregistry. It will start and load the display windows; however, it will generate the error: “Cannot construct server, please run rmiregistry: Connection refused to host:”

The resolution is to stop the testgame process, start rmiregistry and restart testgame.

  1. HexAtom is not running. HexAtom is launched via the testgame python script and it starts the command line server. If HexAtom is not running and the HexAtomCmdInterp.py (via testui) is run, HexAtomCmdInterp.py will timeout with the error: “java.net.SocketTimeoutException: Receive timed out”

To resolve this, start HexAtom (via testgame) and restart HexAtomCmdInterp.py (via testui).

  1. HexAtom stops responding or crashes. If HexAtom crashes or is stopped while there are still active HexAtomCmdInterp.py sessions running, HexAtomCmdInterp.py will generate the error: “java.net.ConnectException: Connection refused”

To resolve this, end the HexAtomCmdInterp.py session, restart HexAtom (via testgame) and restart HexAtomCmdInterp.py (via testui).

Command Line Options

Configuration Options

There are several options for configuring the environment and view the configuration.

Diameter – The diameter of the ‘universe’ for the display is set by using the command: d<number>. The number must be an odd integer greater than or equal to 3.

Tempo – The tempo is the rate of change of game state in moves per minute. ‘t1’ advances the game once per minute, t60 yields 60 times per minute (once per second). The tempo is set using the command: t<number>. The number must be an integer greater than 0.

Fake Factor – This is a setting used for testing only. It is set using the command f<number>. The number can be a decimal value between 0.0 and 1.0.

Querying Parameters – The command: q can be used to query the current run options. ‘q’ can be run by itself to display the basic run options:

It can also be run with a specific parameter to see the value for that option. Example: qt

Probability Configuration

There are multiple probability options that control how atoms behave within the display. All options have a default value, so none need to be set; however, setting these allows greater control over the display and can be used to generate unique and custom displays.

There are nine specific probability options. Each option can have a decimal value ranging from 0.0 to 1.0, a value of 0 means that probability will not occur and a value of 1 means it will always occur. Additionally probabilities can be set for each Atomic Value.

  • pcd for probability of changing direction
  • This is the probability that an atom will alter its path when impacted by another atom.
  • pde for probability of disappearing at edge
  • This is the probability that an atom will disappear at the edge of the ‘universe’. A value of 0 means it will not and will bounce back into the universe; a value of 1 means it will disappear when it reaches the edge.
  • pdf for probability of deflection on collision
  • This is the probably that an atom will deflect on collision.
  • pfi for probability of fission
  • This is the probably that an atom will break into other atoms.
  • pft for probability of following track
  • pfu for probability of fusion
  • This is the probability that an atom will fuse with another atom on collision.
  • pmt for probability of making track
  • pst for probability of stopping
  • This is the probably that an atom will stop upon collision with another atom.
  • pxu for probability of extending universe
  • This is the probability that if the universe ‘diameter max’ is larger than the current diameter, that an atom hitting the edge will cause the universe to expand (up to the max).

There is also a reset option for the probabilities:

  • paz resets element to its default probabilities -

Command Syntax: <probability<atomic number>=<value>

Example: pfu10=0.5

Viewing the probability configuration: The ‘q’ option can be used to display the current configured probabilities. ‘qp’ will display all the configured probabilities, ‘qp<atomic value>’, will display the probabilities for a particular Atomic Value.

Generating an Atom

The command generate a new atom is ‘a<atomic number<direction<delay> @<location>’. The location is optional, all other options are required

Atomic Number: Valid atomic numbers are 0 – 11. In terms of functionality, the atomic number determines the color of the atom when it is generated. For a full listing of colors, including pictures, see “Appendix A - Atom Colors”

Direction:There are seven direction options when generating an atom; the direction of the atom is relative to the location on the X, Y plane. The perception of the atom to the location is relative to the viewing position. When looking up at the planetarium, the atoms will appear as in the first image below (labeled ‘On Planetarium Display’). When viewing on a local computer, East and West will appear to be reversed. The direction options are:

  • ‘n’ – North
/
On Planetarium Display /
On Local Computer Display
  • ‘ne’ – Northeast

  • ‘se’ – Southeast

  • ‘s’ – South

  • ‘sw’ – Southwest

  • ‘nw’ – Northwest

  • ‘x’ – Center

Delay: This delay is the time an atom will wait at a location before moving, in terms of the tempo. For example, at t60 (tempo 60), an atom with a delay of 1 will wait 1 extra second, i.e., it will move once every 2 seconds. A delay of 2 makes it wait another time period t, etc. Other atoms ‘hitting’ the atom will affect the atom regardless of the delay.

Location: Location refers to the location of the new atom in the X,Y coordinate plane. Location is not required, but can be specified and is useful for creating custom displays. When specifying location, both X and Y values must either both be even or odd.

GUI Control and Operation

HexAtom has a GUI that can be used to control the game and will accept the same commands as the command line interface. The GUI is separated into four separate areas; used to monitor and control the game.

Atom Generation

The “Atom Generation” section is at the top of the GUI and is used to generate new atoms.

The top line of the Atom Generation section of the GUI is used to control how the atoms are created when the ‘FIRE!’ button is clicked. These options are used to build the new atoms, using the command line atom syntax format ‘a<atomic number<direction<delay>’

  • Low Atom – This sets the lowest atomic number for an atom that is created. The default is ‘0’, this means that the first atom that is created will have an atomic number of 0. Valid options are 0 – 11. The atomic number controls the color when the atom is created (see ‘Appendix A – Atom Colors’ for color information).
  • High Atom – This sets the highest atomic number for an atom that is created. The default is ‘0’, this means that as atoms are created, the highest atomic number for the atoms will be 0. Valid options are 0 – 11. The atomic number controls the color when the atom is created (see ‘Appendix A – Atom Colors’ for color information).
  • Low Direction – This sets the first direction value used to create an atom, when the ‘FIRE!’ button is clicked. Options are: ‘se’, ‘ne’, ‘n’, ‘nw’, ‘sw’, ‘s’. The default is ‘se’ or Southeast.
  • High Direction – This sets the last direction value used to create an atom, when the ‘FIRE!’ button is clicked. Options are: ‘se’, ‘ne’, ‘n’, ‘nw’, ‘sw’, ‘s’. The default is ‘s’ or South.
  • Delay – Delay is used to set the delay of the atom.
  • Add Count – This is used to set how many atoms are generated when the ‘FIRE!’ button is clicked, the default is 1.
  • Add Location – This is used to set where the atom will be created. Options are either ‘origin’ which is the center of the game display, or ‘various’ which will create the atom at a random location.
  • ‘Secs’ and ‘Auto’ are not configurable.
  • ‘FIRE!’ – creates the new atom or atoms based on the other configured options. For example, if the atom controls were set as follows:
  • Low Atom: 1
  • High Atom: 5
  • Low Direction: se
  • High Direction: n
  • Delay: 0
  • Add Count: 6
  • Add Location: Various

If the ‘FIRE!’ button is clicked, the GUI will generate the six following atoms, at random locations on the game display:

a1se0

a2ne0

a3n0

a4se0

a5ne0

a1n0

Command Line Commands Enter Area

The “Command Line Commands Enter Area” is directly below the Atom Generation area and is used to enter command line format commands. See the Command Line section of this document for details on command line syntax.

This section of the GUI is also used for live coding and import functions (see ‘Live Coding & Importing Python Functions’ section of this guide).

Command Output Results Window

The “Command Output Results Window” section of the GUI displays the output from commands run in either the Atom Generation section or Command Line Commands Enter Area. The output below is from running ‘q’ in the command window.

Game Status

The “Game Status” bar of the GUI is used to display the real time status of the game. This includes a count of atoms and display of the basic game parameters.

The first 12 numbers listed in the status are count of each of the 12 atomic number atoms. In the output above, it shows the game had 4 ‘a0’ atoms, 6 ‘a1’ atoms, 6 ‘a2’ atoms, 5 ‘a3’ atoms, etc… The display also shows a total atom count and the diameter of the game display and tempo of the game.

Live Coding & Importing Python Functions

The HexAtom GUI allows for ‘live coding’ (or code written in real time) and for importing Python functions. The coding and importing is done in the “Command Line Commands Enter Area” of the GUI. The results of the code or functions are displayed in the “Command Output Results Window”.

Live Coding

Live coding is writing python code in the GUI which can be interpreted without having to recompile the source code for the game. Code is entered in the GUI and then enter is pressed twice to execute the code. Enter must be pressed twice because some code may require multiple lines. The example below is a simple ‘for loop’ written in python that will create 1000 atoms with the atomic number 0, direction of ‘n’ and no delay

The top window is where the code is entered; the bottom window displays the results of the code execution. The example below shows a nested loop that creates 50 atoms for each atomic value (0 thru 11). The code also uses the variable ‘y’ to specify the atomic number of the atom, rather than hard coding it as in the previous example. The output is shown on the right.

The result of the code execution is displayed in the bottom window and the status bar shows the count of each of the atoms, by atomic number.

Live coding is a valuable tool to use to during game play or performances. HexAtom supports multiple user sessions and each session supports live coding.

Importing and Loading Code and Python Functions

Live coding is valuable for ‘on the fly’ input; however, some outputs may require complex coding and so need to be built prior to running the game and loaded at runtime. HexAtom supports loading, saving, importing and the execution of Python functions and scripts.