Program 2 CS320 Reread the Policy statement at the beginning of the class notes; you MUST do your own work on all assignments and programs. The file ~cs320/calendar will contain all published deadlines, including occasional extra credit deadlines. HOW TO SET UP: For the purposes of this discussion, '~' means "the home directory of the masc0nnn rohan account assigned to you for this class"; you may own other rohan accounts, but you must use this masc account for your CS320 projects. Similarly, ~cs320 resolves to "the home directory of the cs320 repository". You will need to copy a file from a subdirectory of the cs320 account. Note that ~cs320 is a directory found only on rohan (and also note that ~cs320 means something different than ~/cs320). Your activity for this assignment should take place in a directory called ~/Two . The material you want graded must be in the proper directory in your account on rohan by the due date to receive any credit for Program 2. Every programming assignment for this class must be developed and run on rohan ...except for this one. For Program 2, you have the option of developing this on your home machine, and then transferring the workspace to rohan (by the deadline) for grading. If you have a linux machine, the form at: http://www.microapl.co.uk/apl/linux_pe_form.html ...will allow you to download aplx; this [older] version of aplx will never expire. If you have a Mac or Windows machine, the form at: http://www.microapl.co.uk/apl/demo_form.html ...will allow you to download the latest aplx, but it will expire in 1 month (but this is sufficient time to complete our APL assignment). These downloads will set everything up correctly, give you all the fonts you need, and make it easy to print and edit your functions using aplx. Alternately, you can use the computers in GMCS425, which already have the newest version of aplx installed, print your program there, and transfer your workspace to rohan using sftp (which is also installed on every host in GMCS425). HOW TO SET UP: If you are using aplx on your own Windows machine, then you need to download ftp://rohan.sdsu.edu/pub/ibm/SSHSecureShellClient-3.2.9.exe and install it, to give you ssh (for logging on to rohan) and sftp (for transferring files to and from rohan). [Assuming you are using Windows; if you use linux on your home machine (or a Mac), these utilities should already be there.] My automation will look for your [transferred] work under the ~/Two directory in the masc0nnn account I provided, so you should: rohan% mkdir ~/Two ...and make sure your APL workspace is in that directory at the due date (so that my automation can retrieve a copy for me to test 'by hand'). Under the ~cs320/Two/ directory, you will find a P2 workspace which contains a few convenient functions and variables (IDENT, MAKE_DECK, MAKE_HANDS, HAND1 and HAND2). If you are using aplx at home, you need ~cs320/Two/P2.aws copied to your home machine (but you must later move your improved, completed version to ~/Two/P2.aws in your masc account). If you are using the GMCS425 lab, move P2.aws to the machine you are using, and move it back to rohan after editing. (You can just use the ~/Two/P2.aws file from the previous assignment; if you instead use the generic copy in ~cs320/Two/P2.aws, don't forget to edit the IDENT function again!) CAUTION: This is a binary file, not a text file. It will be mangled if you transfer it in ASCII mode. Therefore, when using sftp to move the file, make sure you do: Secure File Transfer Client --> Operation --> File Transfer Mode --> Binary ...so that you get the un-mangled version! Once you have a copy of the P2 workspace in your preferred location, fire it up and issue the command: )LOAD P2 ...to gain access to the functions/variables I have defined in this workspace. (On a Windows PC, you'll need to put P2.aws into your "My Documents" folder, or in some cases on your desktop, for aplx to find it without specifying a full path.) The MAKE_DECK function in the P2 workspace is the same one shown on Page 123 of the lecture notes; it creates a deck of 52 cards. HAND1 and HAND2 are variables containing two particular ways these cards might be shuffled. Type: HAND1 ...to see a printout of one of these shuffled decks. (The MAKE_HANDS function is provided to conveniently regenerate HAND1 and HAND2, in case you somehow blow them away during your experiments.) IGNORE this paragraph UNLESS you are using linux. If you're using the older linux aplx installation, there are some things that need updating. The startup script was probably installed as /usr/local/aplxpe/bin/startaplx, and will benefit from some editing. Line 12 of this file is: APLX_PRINT_FONT_PATH=/usr/lib/X11/fonts/Type1 If you have a /usr/lib/X11/fonts/Type1 directory, fine. If not, change the path to the appropriate directory (on my ubuntu system, this needs to be: APLX_PRINT_FONT_PATH=/usr/share/fonts/X11/Type1 ). Then add the following two lines near the top of the file: savedir=`pwd` # use backquotes (`, not ') in this line. LANG=en_US;export LANG Finally, just above the last two lines of startaplx, add this line: cd $savedir Now as long as you run startaplx from the directory containing P2.aws, )LOAD P2 will work, without needing a full pathname. Once you have installed aplx, you can run aplx by invoking it from the menus as you would any other utility (but on a linux system, you can also start it from a shell by typing 'startaplx'). Under the 'File' drop-down menu, you can choose 'Open' and then navigate to your P2.aws workspace and click on it to )LOAD it. The bottom item in the 'Edit' menu brings up a panel that lets you type in the name of a new function, or lets you click on the name of an existing function. Once you do so, you get an additional window with a nice full-screen editor (which is always in 'insert-mode', and you can click anywhere to relocate the insertion point). The normal Control-C and Control-V works for copy and paste [between aplx windows, and you can even take stuff from other windows and paste it in here (which is a good idea if you need to generate a whole bunch of lowercase letters, and don't want to wear out your ALT-key :-) ]. To figure out how to type the crazy characters, you may want to keep Page 118 of the lecture notes in front of you -- but you can go to the 'Help' menu and choose 'Keyboard layout' to get a window with a nicer version of this legend (nicer because the four colors make it easier to see which key combinations you need). After you have created/edited your line[s] of code, 'File'->'Save' will 'fix' the definition in the current workspace [use the drop-down 'File' menu in the 'EDIT' window, NOT the 'APLX Session' window!]. CAUTION: if you just quit now, the definition will be lost. To preserve it, make sure you also use 'File'->'Save' from the 'APLX Session' to write the entire contents of your current workspace out to disk. You can also do this from the command line, just by typing: )SAVE WARNING: Make sure you do not have NumLock or CapsLock turned on, or dealing with the 'new' keyboard layout will be even more confusing. Some aplx versions use the 'Unified' keyboard as the default (which you can choose from a drop-down menu); the keyboard shown in my notes is the 'Classic' APL keyboard. If you have a Mac, pay attention to the installation instructions -- you'll have screwy fonts until you download the correct ones (this is a separate step for Mac users only). Also, if you test-run the function prior to saving it, and there is an interpreter error, the system will not allow you to save until you clear the )SI state indicator (you can do this from a drop-down menu with the item: Clear Execution Stack). See the advice under "TROUBLESHOOTING" below for further tips that can save you grief. WHAT TO PROGRAM: Your program2 will modify the P2 workspace and define two functions related to the card game 'bridge'. In order of increasing complexity, you will: (1) create a function called DEAL which will [randomly] 'deal out' four piles of 13 cards each, which should be displayed in the format shown: Q982AQT93T934 AKJ657428J987 K865AKJ54KQT3 T743JQ762A652 SSSSHHHHHDDDC SSSSSHHHDCCCC HHHHDDDDDCCCC SSSSHDDDDCCCC DEAL will return a different result each time; the above is just a sample. You must return a 2x56 character array (56 = 52 cards + 4 blanks [four, because you will later find it convenient to also have blanks on the end of the rows]), representing the cards in the deck, separated [by blanks] into four 'hands'. Each hand should be sorted by suit (Spades on the left, then Hearts, then Diamonds, and Clubs on the right). Within each suit, the cards should be arranged in descending order (AKQJT98765432). Be careful to ensure that DEAL *returns* a set of hands, rather than just *printing* a set of hands. That is, make sure you understand why I have: HAND <- ...on both line [0] and line [1] of the POKER_DEAL function on page 82. This is important, because the next function (SCORE) needs to be able to use the value that DEAL returns. NOTE: The first line mentioning 'HAND' is line [0] of the function. The line on page 82 just above that (the one with the rectangle inside of square brackets) is what I had to type into the session window to get APL to display the lines of the function -- it's not something you should try to reproduce in the editor window! (2) create a SCORE function, which will accept input in the form that DEAL returns (that is, a 2x56 character array) and 'decorate' this with labels (one for each player, traditionally labeled NORTH, EAST, SOUTH, and WEST). Your SCORE function will additionally tally the 'points' each of the four hands are worth [details about how to do this will be given later, at the end of this file] and display these totals below each hand. The format should look like: NORTH EAST SOUTH WEST Q982AQT93T934 AKJ657428J987 K865AKJ54KQT3 T743JQ762A652 SSSSHHHHHDDDC SSSSSHHHDCCCC HHHHDDDDDCCCC SSSSHDDDDCCCC 10 11 19 9 Your SCORE function should accept a left and a right argument; you can ignore the right argument unless you are attempting the extra credit. The left argument is a 2x56 array; a typical invocation would be: HAND1 SCORE 0 or DEAL SCORE 0 The sample shown above is the correct output for HAND1 SCORE 0 . You'll probably want to use one of the variants of Format (Pages 99-100 of ~cs320/APLX_Language_Manual.pdf) to turn the numbers you generate into the proper-sized character strings, to make them easier to align in the proper columns. Extra credit is available if you create a 3-dimensional array when given a righthand argument of 1. Here is the proper format for HAND1 SCORE 1 NORTH Q982AQT93T934 10 SSSSHHHHHDDDC EAST AKJ657428J987 11 SSSSSHHHDCCCC SOUTH K865AKJ54KQT3 19 HHHHDDDDDCCCC WEST T743JQ762A652 9 SSSSHDDDDCCCC The blank lines naturally occur when APL prints 3-dimensional objects; those blank lines separate the planes. The above is a 4x2x19 character array. (19 = 13 cards + 1 blank + 5 columns for the label [e.g., 'SOUTH']). Note that the '9' and '19' have to be turned into characters to 'fit' them into this structure; 'Format' (Page 99) is again your friend. The dyadic form of Transpose (Page 77) will be needed to get the dimensions swapped around the way you need them. [Once you do that, the point-totaling formula becomes much easier, so the extra credit is definitely worth doing. Indeed, you'll probably want to always make a 3-D array for generating the point totals.] Like most APL operators, your SCORE function will have monadic behavior as well as dyadic behavior. In particular, if you have no left argument, as in: SCORE 0 ...then SCORE should behave as though you had said: DEAL SCORE 0 (that is, if score is not given a hand to score, it should generate a hand and score that [random] hand). Page 29 of ~cs320/APLX_Language_Manual.pdf shows the magic syntax for testing if a function has been invoked with two or only one parameter (by checking if the 'name classification' of the left-hand dummy variable is zero, and if so, branching to the line labeled 'START'). Remember, it's perfectly fine to 'reuse' such code verbatim, as long as you include a citation (e.g., "as per Page 29 of APLX_Language_Manual.pdf"). Actually, you don't want to use it verbatim -- they use an 'equal' (Shift-5) where their logic indicates that they really wanted 'not-equal' (Shift-8). Here is the proper output for: HAND2 SCORE 1 NORTH T3AQ7632AT872 12 SSHHHHDDCCCCC EAST KQ7JT52Q65653 8 SSSHHHHDDDCCC SOUTH J865K843KQJ94 13 SSSSHHHHCCCCC WEST A9429AKJT9874 17 SSSSHDDDDDDDD Here's the bridge-scoring description, stolen from: http://www.eecs.berkeley.edu/~bh/ssch9/bridge.html At the beginning of a game of bridge, each player assigns a value to his or her hand by counting points. Bridge players use these points in the first part of the game, the "bidding," to decide how high to bid. (A bid is a promise about how well you'll do in the rest of the game. If you succeed in meeting your bid you win, and if you don't meet the bid, you lose.) For example, if you have fewer than six points, you generally don't bid anything at all. You're going to write a computer program to look at a bridge hand and decide how many points it's worth. You won't have to know anything about the rest of the game; we'll tell you the rules for counting points. A bridge hand contains thirteen cards. Each ace in the hand is worth four points, each king is worth three points, each queen two points, and each jack one. The other cards, twos through tens, have no point value. So if your hand has two aces, a king, two jacks, and eight other cards, it's worth 13 points. A bridge hand might also have some "distribution" points, which are points having to do with the distribution of the thirteen cards among the four suits. If your hand has only two cards of a particular suit, then it is worth an extra point. If it has a "singleton," only one card of a particular suit, that's worth two extra points. A "void," no cards in a particular suit, is worth three points. For example, one of our sample hands, A9429AKJT9874 SSSSHDDDDDDDD ...is worth 17 points. The two Aces are worth 4 points each, the King 3, the Jack 1, plus you get 3 points for having no clubs, and 2 points for having only one heart: 4+4+3+1+3+2 = 17 WHAT TO HAND IN: 1) You must have your APL workspace, named ~/Two/P2.aws in place by the due date (and it must be a different size than ~cs320/Two/P2.aws, indicating that you actually added something to my initial workspace!) My automation will make a copy of this on the due date, which I will test 'by hand' (making sure SCORE gives the right output for HAND1 and HAND2, that DEAL works, etc.) 2) A workspace listing, which will include your DEAL and SCORE functions. This is due the BEGINNING of class the next day (the day after I do the electronic collection of the workspace; see ~cs320/calendar for the current due dates). Printing in aplx is simple; the 'File' drop-down menu has a 'Print' option. [If you are using the older linux version of aplx, and are having trouble printing, see me for guidance.] CAUTION: You are being asked to print a workspace listing, not just individual functions, so follow the directions in the above paragraph. If you have done it right, the first line of the printout will be "APLX Workspace Listing" or "Workspace Listing: P2" (depending on which version of APLX you have). It should NOT begin with "Edit;" or "WS Explorer" or be simple screenshots. TROUBLESHOOTING: It's very easy to build up a complicated state within your workspace, which will make it non-portable (or worse, make it so that it fails to open even on your own computer). Typically, you will get a message that says: SYSTEM ERROR Location: aplflex.c ... In such a case, you may be able to resurrect your work by opening a new workspace, then using the )COPY command (under the File menu) to import the definitions from the broken workspace. There's no guarantee that this cloning trick will always work, so SAVE your workspace every time you make significant progress, and make a copy of it so that you have a relatively recent backup to use if disaster strikes. After you are ready to upload your workspace, save it to another filename, then open a clear workspace, use the above cloning trick, then save this clone. You should find that it is a streamlined and much smaller version than your original. Double-check that your clone works, then upload it to rohan (it MUST be named ~/Two/P2.aws, with this exact capitalization). [And if you're really paranoid, you can simulate what I will be doing: transfer your file from your rohan account back to your local machine, and verify that it still opens and executes correctly.] EXTRA CREDIT: The file called ~/Two/GradeEarly (note the odd capitalization) is intended to signal that you have completed the project a week early, and wish to take advantage of the extra credit reward. The contents of the file are immaterial; the autograder will only test for the existence of this file. If the file has been created by the 120% deadline, your project will be picked up for grading at that time (so no further changes to your code or documentation will be possible). Your score will be augmented by 20% (for example, if you would have normally received 70% of the points, you will instead qualify for 84% of the points possible). GRADING CONSIDERATIONS: Don't forget that you're using an array-manipulation language. In our APL samples, there were no loops demonstrated; whatever we needed to do, we did in parallel. If you wind up processing each of the four hands in turn, you're not really learning how to use APL, and your grade will reflect that failure (doing things piecemeal is better than doing nothing, but not all that much better). DEAL and SCORE could be one-line functions [I don't recommend putting everything on one line, but it's possible]. Make sure you understand how to make use of an outer product (Page 118); it lets you do far more than any sane person would reasonably expect. (Don't confuse Shift-J [the symbol you need] with Shift-O [which does trig functions].) I've shown you a dozen ways to produce something as trivial as the evens with APL; if two students turn in similar solutions to these complicated tasks, don't expect to convince me this could happen by coincidence. TIME-MANAGEMENT STRATEGIES: The tutorial in the class notes shows what happens when you type everything perfectly, and always use the syntax correctly. Your first experiences with APL might be slightly less perfect. You are likely to get some head-scratching errors, and get some output that is not at all what you expected. I can help explain what APL is telling you, but if you try to do the entire assignment in the last week, you'll run across far more roadblocks than you will have time to ask about. START EARLY! Strive for the extra-credit deadline. If you finish by then, you can do the simpler version of the assignment and still score over 100% [once the extra credit is added on]. For many of you, you'll find that you'll really need to invest more time than you thought to get it done -- and it's better to discover that while you still have a week to complete it.