Yorick Quick Start ----------------------------- Yorick is distributed as a self-extracting archive file called yorwin14.exe. This is done so that the proper directory structure is created without any special efort on the part of the user. (At sites that do not accept self-extracting archive files yorwin14.exe will be placed inside a zip file, e.g. yor14vr2.zip, along with this README file. If you have the zip file, extract yorwin14.exe from the zip file and follow the instructions below.) Double-click on yorwin14.exe in Windows Explorer. If you accept the defaults there will now be a directory called C:\Yorick14. Double-click the file called yor_win.exe in the Yorick14 directory. You are now running yorick. Type: #include "demo1.i" demo1 in the command window. Yorick will create a graphics window and make some plots. Select "exit" from the file menu or type "quit" in the command window and yorick will quit. To see more of the capabilities of yorick, run demo2 through demo5. To learn how the demos work, use the open command in yorick's file menu to load demo1.i (or another text file) into a text editor window. If you see a command you don't understand, e.g. "pli", go back to the command window and type: help,pli Yorick documentation is available as Tex sources, PostScript, or HTML from ftp://ftp-icf.llnl.gov/pub/Yorick or http://wuarchive.wustl.edu/languages/yorick. The UNIX distribution directory contains the user manual and a set of 6 quick reference sheets. Yorick is freeware and is freely distributable. Details on the installation and use of yorick follow below. Steve Langer 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, filled contour plots, cell arrays, and filled mesh plots. The 3D graphics package provides surface plots, slicing planes, and iso-surfaces. This is the third version of Yorick 1.4 for Windows 95 and Windows NT. This version of yorick has essentially all the functionality of the Unix version plus a couple of additional features specifically for Windows. The graphics and computing performance of this version is good. It should be about as fast as the Linux version on the same hardware, except for animated graphics, which seems to suffer on machines where the vendor has written a lousy graphics driver. I would appreciate reports of bugs or "mis-features". I can't promise to fix everything, but I certainly won't fix a problem if I don't know about it. Features in release 1.4 -------------------------------------------- It is now possible to interrupt a yorick calculation. This is done using the STOP button in the toolbar. This feature is not a true interrupt - it actually checks the STOP button several times per second and after several interpreted instructions have been run. In most real world cases this feature works without any problems. A side benefit of adding this feature is that you can do a bit of window re-arranging while yorick is running (in prior versions, the user interface did not work while yorick was running). See item (9) under Windows Specific Features for more details. The text editor and command windows now have a GoToLine command under the Edit menu. This command works based on the number of lines on the screen, while yorick's error messages refer to output lines. If you make the window wide enough that nothing wraps around, the two sets of line numbers will agree. Printing should work - including color. However, I have not tested on anything except PostScript printers. There are a huge number of different printers out there, so I am curious about which ones give trouble. Please let me know of any printer where yorick can't print well but your other programs can. If you click on the title bar of a graphics window, you will make it the active engine for yorick and cause its color table to be used. As an example, suppose you make window 0, draw to it, then create window 1 and draw to it using a different color table (use the "palette" command to select another color table). If you now click on the title bar of window 0 and go back to the command window and type another plot command, it will be drawn in window 0. The window title includes the window number. The Windows version supports "zooming" plots by using the mouse, a feature that has always been present in the UNIX version. The Windows version will zoom in on the spot where you click the left mouse button in a plot. If you click the right mouse button, it will zoom out by the same amount that it zooms in on a left click. The Windows version does not support dragging a rectangle to specify the new view, but it does support dragging the target point of the zoom to a new point in the window. The mouse function (try: help,mouse) works, but the mouse down and up location will always be the same place. IN SUMMARY - left-click and right-click in the window and see what happens. This is the first version of yorick for Windows that supports command line arguments. To take advantage of this capability, you must start yorick from a "DOS prompt". Wild card characters like * and ? are not expanded. This version should run under Windows 95 and Windows NT (both 3.5.1 and 4.0). I do not anticipate any problems with Windows 98, but I have not yet tried that. It might be possible for someone to modify the source code to use an earlier version of the Microsoft Foundation Classes and thus permit yorick to run using win32s under Windows 3.1 or OS/2. I do not plan to do this because the version of Microsoft C++ that I am using does not support win32s. Learning to use Yorick ---------------------- The user communicates with yorick by typing commands in the command window. Commands are not passed to yorick until you press the Enter key, so you can backspace, cut and paste, etc. until you get the command typed correctly, then press the Enter key. I am not a terribly accurate typist, so I often make mistakes in what I type. When this happens, yorick usually responds with a complaint about a syntax error. At this point you don't have to retype the whole line - just use the mouse to position the cursor in your input line, fix the mistake, click with the mouse at the end of the line, and type Enter again. Yorick will read the input line and send its output to the end of the command window. If you want to clean up the command window, drag across some text with the mouse and press the backspace key. The selected text will be deleted and yorick won't notice that anything happened. The command window is scrollable and its contents can be saved to a text file. The example yorick run in the Quick Start section showed how to run a pre-existing program (demo1.i in this case). The #include command takes the contents of the file and hands them to yorick just as if you had typed each line in the command window. When you are first starting out, you will probably type commands directly in the command window. When you start doing more complicated things and doing pretty much the same thing over-and-over, consider putting your commands in a file and using #include. By convention yorick input files have an extension of ".i". A good way to start learning yorick is to type algebraic expressions in the command window. When you know how to make vectors, try plotting them using the plg command. Then you can move on to multi-dimensional arrays and display them with the pli command. After that you are ready to investigate those parts of yorick that are most useful to you. Use yorick's help command when you can't remember the arguments to a particular command. I often try something like: help,plg when I can't remember how to turn occasional markers along a curve off. The answer may not appear directly, but the "see also" section of the help output often reminds me of the name of the thing I am really looking for. Windows Specific Features -------------------------------------------- 1) If your PC is running in 256 color mode, there aren't always enough colors to go around. The foreground (active) application gets to choose its favorite colors and background applications can only set whatever colors are left from the original 256. The net result is that the colors in a yorick graphics window may look awful if another color using application (e.g. Netscape or Corel Draw) is the foreground application. Don't worry - when you bring yorick back to the foreground, the colors will be OK again. There is another case of the same difficulty if you make two yorick windows and use different color tables in them. In this case the active graphics window will get its choice of color table and all other graphics will use that same color table. As soon as another graphics window becomes active, all other graphics windows will switch to the color table of the new window. When you click on the title bar of a graphics window, its color table becomes active and all other graphics windows are redrawn using the new color table. 2) Windows Enhanced Meta files can be made using the hcp command. To do so, first issue an hcp_file command with a file name that ends with ".emf". Subsequent hcp commands will create a windows metafile until you change the file name to something that does not end ".emf". If the part of the file name just before ".emf" consists of a string of digits, each hcp command will increment this "number" and write to a new file. If the file name does not have such a "number", each hcp command will overwrite the previous metafile. There is no support for per window metafiles via the "hcp" keyword on the window command. I have had success reading these metafiles into Adobe Illustrator 7.0 and PowerPoint (from Office 95). Corel Draw cannot import metafiles, CGM files, or Postscript files correctly. I have absolutely no idea why Corel Draw is the leading drawing program under Windows, but I will avoid it whenever possible. 3) The Save and SaveAs commands from the File menu are dimmed when a graphics window is in front (this may change someday). When you use Save or SaveAs for either the command window or an editor window, yorick will save a text file. You should set the file extension yourself in the file naming dialog. 4) You must use UNIX-style directory names to specify files. For example, use "/c/temp/test_file.pdb" as the name in a yorick command, not "c:\temp\test_file.pdb". Thinking of file names as sort of like URL's may help. 5) Yorick on UNIX systems and the Macintosh comes with a companion program, called gist, that is used to view CGM graphics files. A Windows version of this program will be made available if there is sufficient demand. 6) Yorick has special commands to set the font and character size for editor and command windows, and to set the default size of graphics and editor windows. These commands will usually be run out of the custom.i file as yorick is starting up, but can also be run later. The Windows specific commands are part of the yorick ylep system just like the normal commands. If you get the file win32.doc, you can find out about the Windows specific functions. 7) The window command has been enhanced to let you choose any size you want. This is done using the dpi argument to the window command. The window is always intended to be roughly 6"x6". If you type "window,1,dpi=50", you will get a window that is roughly 300x300 pixels. This feature should be a big help on laptops with 640x480 screens. 8) Sometimes it is helpful to be able to "resend" a series of commands that you typed earlier. If the commands are next to one-another and you want to issue them one right after another, select the whole range and type the return key. If you want to re-issue a command, do a few things, and then re-issue another command, you can use the F8 key to jump back to the last point where you typed a return key (ignoring returns typed at the end of the command window). 9) There is now a way to interrupt a yorick program. Yorick checks whether the STOP button on the toolbar has been pressed several times a second. If the button is pressed, yorick stops the current calculation and returns to the prompt. One limitation of this feature is that these checks only occur while yorick is executing interpreted instructions. If you tell yorick to solve a 1000 by 1000 matrix, the STOP button will not work because yorick is running the compiled matrix solver function. In most cases the STOP button works as expected. 10) When a graphics window is active and you select the Copy command from the Edit menu, yorick will copy the current plot to the Windows clipboard. You can then paste the plot into a word processor, a page layout program, or a presentation program. The restriction is that the program must be able to display a Windows metafile, which frequently works. Thanks to Tom Short for contributing the code to do this. Getting and Installing Yorick ----------------------------- If you have an earlier version of yorick for Windows, you might want to rename its directory and not delete it until you are satisfied with the new version. Yorick is distributed in a self-extracting archive file. The self-extractor program will suggest that everything should be unzipped into "C:\". If you accept this suggestion, the extractor will create a C:\Yorick14 folder and unzip everything into it. If you pick another directory/disk to extract into, a Yorick14 folder will be created there. In either case, the directory you select here is the "yorick root directory". If a Yorick14 folder already exists in the root directory, the extractor will by default over-write the existing files. If you would like to customize yorick and have easy access to your own set of yorick "dot-i" files, make a directory called "Yorick" in the "yorick root directory" you selected during installation. The default is thus C:\yorick. By using this directory structure, your personal files are not in danger of being over-written by a new version of yorick. The yorick executable and two DLL files will be in the Yorick14 directory. There will be sub-directories called "gist", "include", and "startup". Double-click on "yor_win.exe" to start the program. The DLL files should remain in the same folder as the yorick exe file to ensure that yorick gets the version that it needs (you may have other versions of these files on your disk). If you are confused about something, try the help command or look at the document files in the main yorick directory of the ftp site. You can subscribe to the Yorick mailing list by sending the message subscribe yorick (in the *body* of the message, *not* the Subject: header) to majordomo@lists.llnl.gov If you have some question, comment, or Yorick source code you think might be valuable to other Yorick users, you may post it to all the subscribers by sending it to yorick@llnl.gov (Questions you don't want to ask publicly - and all installation problems - should still go to munro@icf.llnl.gov, or to shl@icf.llnl.gov if they are Mac or Windows specific.) Steve Langer May 29, 1998 langer1@llnl.gov