HexAtom User Guide. Student 1

Transcription

1 HexAtom User Guide Student 1 CSC520 Fall 2012

2 This page left blank intentionally Page 2 of 25

3 Contents Environment Set Up... 4 Starting HexAtom... 6 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 Page 3 of 25

4 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. o Java Runtime Environment o Java Software Development Kit o 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. o 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:$P ATH" o 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; Page 4 of 25

5 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. o 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. o SSH Client SSH access is required to access linux based systems. PuTTY is a freeware SSH client ( o 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. o 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. Page 5 of 25

6 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 lauches 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. a. Run rmiregistry & to start the process in the background 2. Start testgame to launch the display window. a. Run testgame to start the main command session, the file location must either be specified or in the PATH. b. 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. Page 6 of 25

7 c. Move the initial window into position on the display and click Normal Display d. The main display window will open e. Press enter in the command window. The system will display basic debug information; HexAtom is now ready for command line use. Page 7 of 25

8 3. Start testui to launch the GUI console. a. 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. b. The GUI will load and is ready for use 4. 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. a. 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: Page 8 of 25

9 The resolution is to stop the testgame process, start rmiregistry and restart testgame. b. 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). c. 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 Page 9 of 25

10 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 Page 10 of 25

11 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 o This is the probability that an atom will alter its path when impacted by another atom. pde for probability of disappearing at edge o 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 o This is the probably that an atom will deflect on collision. pfi for probability of fission o This is the probably that an atom will break into other atoms. pft for probability of following track pfu for probability of fusion o 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 o This is the probably that an atom will stop upon collision with another atom. pxu for probability of extending universe o 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 Page 11 of 25

12 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 The location is optional, all other options are required Atomic Number: Valid atomic numbers are 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 ne Northeast se Southeast s South sw Southwest nw Northwest x Center On Planetarium Display On Local Computer Display 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., Page 12 of 25

13 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. Page 13 of 25

14 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 The atomic number controls the color when the atom is created (see Appendix A Atom Colors for color information). High Atom 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 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: o Low Atom: 1 o High Atom: 5 o Low Direction: se o High Direction: n o Delay: 0 Page 14 of 25

15 o Add Count: 6 o 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. Page 15 of 25

16 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 Page 16 of 25

17 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. Loading and Saving Code Code can be written for use in the GUI and loaded during game play. As with live coding, Enter must be pressed twice after each line of code or nested code (loops, control structures, etc..). This is useful for longer or complex commands that are just a few lines long, but need to be executed quickly during game play. To load code: load( <filename> ) The file must be located in the same directory in which the GUI was launched. Page 17 of 25

18 It is also possible to save code that was written in the GUI. To save code: save( <filename> ) This will save the code to the same directory in which the GUI was launched. Importing Python Functions Loading code is valuable; however, advance game play may require code that is more extensive than a few lines. Loading and pressing Enter twice after each line may be cumbersome and slow game play. To address this, HexAtom allows Python functions to be written and loaded into the GUI. This allows the entire function to be executed with a single function call. Page 18 of 25

19 The steps to import and use Python functions are fairly simple; however, there are some syntactical differences between the Python code and the command line code or live coding syntax. The primary change is the format of the commands; the imported functions require the use of a function named interp in order to properly execute. Additionally the values for the command options are put in parenthesis rather than using =. The syntax for interp is as follows: interp.<param>(option values) The option values are dependent on the parameter; if multiple option values are set, they must be separated by a comma. Strings require single quotes. See Appendix B - interp Command Syntax for full command options and syntax. Below is an example of a Python function that creates a big X on the display screen. This code uses common programming processes including loops, decision structures and variables so it shows the value in writing functions in advance for use during game play. def bigx(interp): max = 125 width = 9 interp.d(max) interp.t(5) for i in range(0,max): j = i * -1 k = i l = i * -1 count = 0 while k > 0 and count <= width : m = k * -1 n = l * -1 if i % 4 == 1 : interp.a(i%12, 'x', 0, (k,i)) elif i % 4 == 2: interp.a(i%12, 'x', 0, (l,i)) elif i % 4 == 3: interp.a(i%12, 'x', 0, (m,j)) else: interp.a(i%12, 'x', 0, (n,j)) k -= 1 l += 1 count += 1 interp.t(50) Page 19 of 25

20 The first line is used to define the function, bigx in this case. All subsequent code must be indented 2 spaces to be included in the function. If further nesting is done, each level is indented 2 additional spaces. def bigx(interp): The next few lines define and set control variables. max = 125 width = 9 The next two lines use the interp function to set the diameter of the display and the tempo of the game. The tempo of the game is slowed to 5 so that all the atoms populate the display at the same time. interp.d(max) interp.t(5) The main work of the function is done in the next block of code. This code uses a for loop and a nested while loop to generate the atoms. The location of the atoms is determined by the atomic number of the atom and is controlled by an if/else- if/else control structure. There are also variables that are the negative values of the for and while loop counters; these are used for placement of the atoms based on the atomic value. for i in range(0,max): j = i * -1 k = i l = i * -1 count = 0 while k > 0 and count <= width : m = k * -1 n = l * -1 if i % 4 == 1 : interp.a(i%12, 'x', 0, (k,i)) elif i % 4 == 2: interp.a(i%12, 'x', 0, (l,i)) elif i % 4 == 3: interp.a(i%12, 'x', 0, (m,j)) else: interp.a(i%12, 'x', 0, (n,j)) k -= 1 Page 20 of 25

21 l += 1 count += 1 After the atoms are generated, the tempo of the game is increased to 50. interp.t(50) Once a function is written, it must be imported to use. This is done through the GUI using the command syntax: from <python file> import * This must be followed by pressing Enter twice. Below is the output for importing a helper python file named johnhelper.py. Note: The file extension.py must be omitted from the import command. Once the file is imported, any functions contained in the file are ready for use. There is no way to display a list of imported functions, so the user must know the function names in order to use them. To call a function, the syntax is: <function name>(this()) This must be followed by pressing Enter twice. Below is an example of calling the bigx function, output is included to the right. Page 21 of 25

22 An imported file may contain multiple functions and multiple helper files may be imported into a user session. Below is another example of the function imported from the same python file, this function is named hex and the output is below. Page 22 of 25

23 Appendix A Atom Colors Atomic Number 0 Atomic Number 1 Atomic Number 2 Atomic Number 3 Atomic Number 4 Atomic Number 5 Atomic Number 6 Atomic Number 7 Atomic Number 8 Atomic Number 9 Atomic Number 10 Atomic Number 11 Page 23 of 25

24 Appendix B - interp Command Syntax Atom: Syntax interp.a(<atomic number>, <direction>, <delay>, (<x>, <y>)) atomic Number Integer Values: 0 11 Direction String Values: n, ne, se, s, sw, nw, x Delay Integer location (Optional) integers, both x and y axis values must be specified Example: Interp.a(8, n,0 (11,33)) Diameter: Syntax Diameter Example: interp.d(<diameter>) Integer Interp.d(125) Tempo: Syntax Tempo Example: interp.t(<tempo>) Integer Interp.t(500) Probability: Syntax probability atomic Number Value Example: interp.p( <probability>, <atomic number>, < value >) String Values: pcd, pde, pdf, pfi, pft, pfu, pmt, pst, pxu, paz String (integer in string format) Values: 0 12 (12 sets probability for all atomic values) String (decimal in string format) Values: Interp.p( pst, 6, ) Page 24 of 25

25 Appendix C Defects and Enhancements The following enhancement requests are recommended for HexAtom: 1. The paz probability command resets the probability back to the game defaults. The command syntax is: paz<#>=<value between 0.0 and 1.0> The syntax is ambiguous because a value should not have to be specified. Without digging in the code, a user could believe that the value specified is the value that will be set for all probabilities. Recommend changing the command syntax as follows: paz<#> 2. Add the functionality to list imported functions. When a user imports a helper file with python functions, they must know the names of all the functions. Recommend a command that will display all the imported functions. 3. Add the functionality to import python functions from the HexAtom server command window. This would allow a user to run python functions from the CMD: prompt. 4. Add the functionality to make imported functions available to all GUI sessions. This may need to be built in conjunction with adding the ability to import functions at the main server window. Appendix D Version History Version Date Author Description of updates 1.0 Dec 2012 Student 1 Initial User Guide (CSC- 520) Fall 2012 Page 25 of 25