Introduction ------------ Yorick is a tool for analyzing numerical data. It has an interpreter that uses a C-like language and can operate on entire arrays without any need for do loops over the array indices. Yorick has a file I/O package with the ability to conveniently read text files with columns of numbers. The file I/O package can easily be trained to read a wide variety of binary and text files, if the formatting rules for the file are known. Yorick has a 2D graphics package that includes polylines, contour plots, cell arrays, and filled mesh plots. The new 3D graphics package provides surface plots, slicing planes, and iso-surfaces. Instructions to the unix version of yorick are typed in a command window, and yorick writes responses to the command window and draws plots in one or more graphics windows. The user interface for yorick is text input oriented by design - the easiest way to specify transformations to apply to data is usually some equation-like form. The Macintosh version has a somewhat more user friendly interface, but it is still controlled via text commands. Gist is a program that displays frames in binary CGM files written by yorick and other applications (e.g. ATC GKS, IDL). gist is particularly useful for making PICT files from a CGM file written by a Unix version of yorick. The performance of yorick on the Macintosh is good in comparison to competing analysis tools. The PowerMac version delivers performance comparable to a current low end Sun workstation for computation intensive tasks. The graphics performance on my PowerMac 7100 is about like a high end x-terminal, which is less than a low end workstation. The graphics performance should be better on a PCI based Mac (I have not had a chance to test this). The Macintosh version of Yorick was created by Steve Langer (shl@icf.llnl.gov) from the Unix version written by Dave Munro. This file contains some short notes about the Macintosh version, but it is in no way an introduction to yorick. To learn how to use yorick you will have to examine the files in the doc directory and run yorick. The first thing you should probably do is to print the "cheat sheets". These PostScript files summarize the yorick language and commands. If you have a copy of Adobe's ATM, you can print PostScript files using the SendPS utility. Once you have yorick running, one of the nice features is the help command. If you know that "plg" is the command to make a y versus x plot, but don't remember the arguments, type "help,plg". By paying attention to the "see also" functions, you can find out a great deal without needing to look at the manual. Installation ------------ Yorick is distributed in several self-extracting archive files. There is a version that runs on any 68020, 68030, or 68040 Mac with a floating point chip (FPU), another version that runs on 68020, 68030, or 68040 Macs without an FPU (e.g. 68040LC), and a Power Mac version. There is also a PowerMac version of gist and a 68000 version that does not require an FPU. Each version of gist and yorick checks for the Mac hardware and software it requires and aborts if it is not found (it is possible that detection of old 68000 Macs does not work). The include, startup, and gist directories must be in the same folder as the yorick application (they are organized this way in the files we distribute). If you frequently need to include files from specific directories, add the directory to the yorick search path in your custom.i file (located in the yorick/include folder). If you have MacBinary capability in your ftp program, download the "sea" file. If you are using a unix-like ftp, download the "hqx" file and use a program like UnStuffIt to decode the BinHex file. Once you have the "sea" file, double-click on it and it will automatically split itself apart into the constituent files. NOTE: Yorick ships with a preferred memory allocation of 3-5 MB, depending on the target procesor. Most simple calculations (like operations on 1D arrays) should run just fine in the minimum 2 MB. The larger size is intended to permit reasonable 2D computations. You can increase the memory allocation if you are working on large 2D or 3D datasets. Macintosh Version ----------------- The Macintosh version of yorick is very similar to the Unix version, and almost all of the yorick documentation should apply. The main difference between the Mac and unix versions of yorick is in the user interface. The unix version runs in a terminal window while the mac version includes a built in command window with command re-issue capabilities and text editor windows that can be used to prepare yorick programs. Another difference is that the Mac version can save any graphics window to a PICT file (as well as yorick's native CGM and Postscript formats). The macyorick command window is closer to being a text editor than a dumb terminal window. The main thing to know about the command window is that when you press the return key, everything to the left of the cursor in the current line is passed to yorick as a command. If there is any selected text when the return key is pressed, the selected text is passed to yorick as a command. This last feature can be used to send several lines at a time to yorick. All yorick output will be sent to the command window. When you type a command or call the read function to get keyboard input, macyorick first removes anything it recognizes as a prompt string from the start of the line and then passes the rest of the line. This usually works well, but it can be fooled if you do something like declaring a variable called cont and then try to evaluate the following expression: cont> 3 mac yorick will remove the "cont> " before processing the line. This is a consequence of prompt removal, not a bug. Don't use prompt strings at the start of an input line ("read> ", "do> ", "cont> "). Don't set the prompt string for the read function to the name of one of your variables. Yorick has simple text editor windows that can be used for examining ascii data files or preparing yorick input decks. An editor is created using the "New Editor" command in the file menu. Text editor windows have an "execute" button that causes the contents fo the editor to be read as if yorick had been given an include command. If you are creating a new file, the file must be saved before the execute button will work. When yorick detects an error while processing the commands in a file (even nested include files), it will open the offending file in a text editor and place the cursor on the bad input line (this behavior can be disabled). If you double-click in the Finder on a file of type 'TEXT' with a creator "York', yorick will be launched, it will set it's working directory to the directory where the file is located, and it will then open the file into a text editor window. To run the program, just click the execute button. The Macintosh version also supports the use of "command-period" to abort long running yorick calculations. Yorick only checks for command-period between interpreted commands and while writing to the command window. If you have started a matrix solve that will take an hour to complete, using command-period will not help, because it will not be checked until the matrix solve completes. This feature is turned on by default, but may be disabled in the preferences dialog in the edit menu. Yorick and gist both have a preferences dialog that is reached from the Edit menu. Graphics preferences in gist apply to the single graphics window. In yorick, graphics preferences can be set for future graphics windows from the edit menu or for an existing window using the preferences button in the window. gist has an option to select either yorick-style CGM files or CGM files made by ATC GKS. If you don't know what this means, stick with yorick CGM files. Graphics -------- The Macintosh version of yorick implements the full gist graphics package. Each graphics window has a button that saves the current plot as a PICT file, a button to redraw the window, and a button to set the preferences flags for graphics. The PICT file can be set up either to produce a high quality image when printed or in a form that will make it easier to edit the PICT file in Canvas, MacDraw, etc. macyorick includes the new 3D graphics functions found in the unix version. These include surface plots, slicing planes, and isosurfaces. These functions use a drawing algorithm that is fast but may generate incorrect results for polygons that extend a long way into the screen. If you are plotting using a reasonably smooth grid, you should not see any problems. The new 3D package is easy to use, for a 3D package. The problem with 3D graphics is that you need to give depth cues on a 2D screen, and generating good depth cues is not always easy. Yorick includes functions to set the position of the light(s) illuminating the surfaces and to rotate objects in 3D. Look at the examples in demo5.i and experiment with your own favorite plots. This package will continue to evolve as we get more experience with 3D graphics. If you have any comments, please contact us so we can consider your suggestions. There is another problem that occurs with color plots when you have an 8 bit deep screen. Yorick loads a color table of roughly 240 colors and uses those in plotting to the screen. Yorick allows you to pick from a number of pre-defined color tables, or to create your own. This allows you to produce striking cell arrays or filled meshes on an 8 bit screen. The problem is that if you save the plot in a PICT file, any Mac program that loads the PICT file is unlikely to be using the same color table as yorick used in creating the image. The Mac will do the best job of displaying the image that it can given the current color table, but a lot of "banding" may show up in the image. The only way to fix this, with an 8 bit screen, is to load the same color table into the other Mac program as was used by yorick (non-trivial). HOWEVER, all of the color information is still present in the file, so the colors will show up properly on a color printer. This problem should not be noticeable on a 16 or 24 bit "true color" screen. macyorick supports yorick's animated graphics mode. In the normal graphics mode, everything appears on the screen as it is drawn. In animation mode, the whole plot is drawn in an offscreen pixmap and then copied to the screen all at one time. The result is that in animation mode, the transition between successive pictures is smooth. Animation mode is particularly useful in viewing the results of a time dependent simulation. The simulation might have saved its results in a file, or the simulation might actually be run directly by yorick (see demo2.i for an example). Run demo3.i for an introduction to animation mode. Yorick can write plots to binary CGM files. The CGM file was originally developed for use on mainframe computers, and the standard is showing its age in some respects. One of the key problems is that there is no defined way to specify the exact font you desire in a CGM file. The result is that the program that wrote the CGM file can usually display it exactly, but other programs (e.g. Canvas) only produce an approximate rendition. My suggestion is that you use CGM files as places to store a group of related images (the CGM file could even be written on a Unix workstation). When you need to use an image in another Mac program, load the CGM file into the Macintosh version of gist (a CGM file browser) and save the desired frame as a PICT file. Known Bugs and Missing Features ------------------------------- 0) Yorick has been heavily tested on Unix workstations for a couple of years now and has been available on the Macintosh since late in 1994. It has been used for a wide variety of production calculations, but we still find several bugs a year. The bugs don't prevent us from using yorick, and are about what should be expected from a code of this complexity. The Mac version of yorick is roughly as reliable as the unix version. The core code is the same as for the unix version, so any Mac specific bugs are most likely to be in the graphics package or the user interface. As a new yorick user, your problems are most likely to stem from giving yorick the wrong command, or possibly from asking yorick to do something that will take forever. Look at the examples and start with simple problems, and things should go pretty smoothly. 1) If your CGM files wind up in pure black and white, try using the "dump=1" option on the hcp_file command. The default behavior is to dump a gray scale file on the theory that most printers are black and white. There is some reason to think that the default should be to dump the color table, but for now you need to explicitly dump it. 2) PICT files should have proper colors, but programs like MacDraw and Canvas will often fail to display the full range of colors on 8 bit screens. This happens because they are using a color table that does not match the one originally used by yorick. The proper colors should show up on 16 and 24 bit screens, and will always be OK on color printers. 3) The Mac version of yorick doesn't have an "interrupt key" like the control-C on unix versions, which can interrupt at an arbitrary point in the program. Macyorick instead checks for the command-period key when it sends a line of output to the command window and at the start of every interpreted instruction. Interrupting macyorick works well if you are doing a complicated interpreted calculation, but it will not work if you have told yorick to solve a 1000x1000 matrix or some other single operation that will take a very long time. command period detection is turned on by default. 4) There is always a chance that yorick will cause your Mac to lock up. Yorick checks for out of memory conditions, but it can't help if a toolbox routine runs out of memory. The first thing to check is thus whether the problem goes away when you increase the memory allocation for yorick. If it is not a memory problem and you can find a simple way to repeat the problem, I would like to know what it is so I can try to fix it. If your Mac locks up after hours of use and lots of number crunching, I won't be able to reproduce your problem, so I am unlikely to be able to fix it. 5) The save window size button in the preferences dialog does not work due to problems with the FaceIt library. I hope to fix this in a future version. Source Code for Mac Yorick -------------------------- The Macintosh version of yorick was built using the FaceIt package from FaceWare, 1310 N. Broadway, Urbana, Illinois, 61801, (217) 328-5842, faceware@aol.com. This package is no longer under development, and at some future date I hope to convert to the use of either the Symantec or Metrowerks class library. The source code for yorick is available if you wish to build a custom version incorporating your own compiled routines (don't bother compiling your own routines until you are sure that an interpreted version with array syntax is too slow). To build a Macintosh version, you will need to get a copy of FaceIt, and then request the Macintosh source from me.