Math Solutions 1995 October/Math_Solutions_CD-ROM_Walnut_Creek_October_1995.iso/pc/mac/docs_1/readmema.cyo

Text File | 1995-07-17 | 15.5 KB | 255 lines

The Macintosh version of Yorick was created by Steve Langer
([e-mail]) from the Unix version written by Dave Munro. This file
contains some short notes about the Macintosh version, but it is not 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 "refs.ps" (the cheat sheets). These PostScript files
summarize the yorick language and commands. You can use DropPS, freeware
from Bare Bones software (for information, send E-mail to [e-mail]
on the Internet), to send the PostScript files to your printer. 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 printed documents.

Macintosh versions of Yorick are labeled by the version number of the
corresponding Unix release followed by the Mac version. For example,
version 1.1v1 in the get info box means the first version based on Unix
release 1.1.


New Features in release 1.1
---------------------------
There have been several changes since the last release of macyorick in
January 1995. The most important are improvements in the graphics
package and the debut of a Power Macintosh version.

The Power Macintosh version delivers performance comparable to a low
end Sun workstation for computation intensive tasks. The graphics
performance using the built-in graphics is about like a high end x-terminal,
which is less than a low end workstation. The graphics performance will
probably improve significantly on the new PCI based Macs. The Power Mac
version and both 68K Mac versions now have the QR and SVD matrix solvers.

Graphics output is much faster than in the previous version, and there are
several customization options. The quality of thick and dashed lines has been
improved. This release implements yorick's animation mode. Run demo3.i to
get an idea of how this works. The animations should run well on a
PowerMacintosh or a 68040 Mac, but the frame rate will be slow on older Macs.


Usage notes
--------------------------------------
Yorick tests carefully to see that it succeeds when it allocates
memory, but it can crash if it runs out of memory inside the toolbox
or in the interface library.

Yorick is often used for some serious number crunching, so I have used high
levels of optimization during compilation. I have had several cases where
these levels of optimization produced bad code. I believe that I have found
and dealt with all such problems, but I don't have an exhaustive test suite.
If you find a case where yorick repeatably produces the wrong answer,
please send me an example.

Yorick ships with a rather large suggested memory size of 5.5 MB. Most simple
calculations (like operations on 1D arrays) should run just fine in 2 MB. The
large size is intended to permit 2D computations and the use of animated
graphics, but it is possible to come up with tasks that require even more memory.


Changes since the original release
-------------------------
Most of the changes since the first release are in the user interface. In addition
to the command window, there is now an editor window. An editor window is a
basic text editor with an execute button. You create an editor with the
"New Editor" command in the File menu. Use the standard Open command to load
a file into the editor. When you click on the execute button, the file is SAVED and
then included and executed by yorick. All yorick output will be sent to the
command window. If you double-click on a file of type 'TEXT' with a creator
'York', yorick will be launched (if not already running), it will set it's working
directory to the directory where the file is located, and it will open the file in
an editor window. The yorick.dir and gist.dir files used in the first release to
tell yorick and gist where their support files are located are no longer needed.
The support files must now be located in the same directory with yorick and gist
(they are organized this way in the "sea" 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 (or perhaps at the top of another include file).
There is also a set directory command in the file menu.

This version of yorick can be set up so that when yorick detects a syntax error
(or on some run time errors), it will open the file containing the error in an
editor window and select the offending line. This feature is turned on by default,
but may be disabled in the preferences dialog in the edit menu. Yorick will be
unable to open the file if it is in use by another program (e.g. a text editor)
and will generate an error message.

Other changes include the addition of a way to interrupt some long running
calculations. Select the "allow-command'period" check box in the preferences
dialog in the edit menu, then when you hold down the command-period key,
yorick will return to the prompt at the end of the next yorick instruction or at
suitable points in the write routines. See the discussion at the end for more details.

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.


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
(68881 etc.), another version that runs on all 68020, 68030, or 68040 Macs and
under emulation on PowerMacs (it doesn't use a floating point chip, even if one
is present) , and a native Power Mac version. Another program that is included is a
Macintosh version of gist, a binary CGM file reader. gist can read the CGM files
written by yorick and can read some other binary CGM files, too. gist is
particularly useful for making PICT files from a CGM file written by a Unix
version of yorick. gist does not require a floating point chip and will run under
emulation on a Power Mac. gist and all versions of yorick require Color Quickdraw.
The yorick versions check for the required hardware and quit if it is not found
(it is possible that the detection scheme will fail on pre-System 6 Macs, but
the program will not run there anyway).

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.

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 also has a 2D graphics package
that includes polylines, contour plots, cell arrays, and filled mesh plots.

History
-------
Yorick was originally written to run on Unix workstations. Instructions to
yorick are typed in a command window. 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.

Macintosh Version
-----------------
The Macintosh version of yorick is very similar to the Unix version, and almost
all of the yorick documentation should apply. The principal differences are that
the Mac version can save any graphics window to a PICT file (as well as yorick's
native CGM and Postscript formats), and that the 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. The enter key does not cause the line to be executed, so it can
be used in building multi-line commands to be executed as a single "selection".
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 of the editor to be read as if yorick had been given an include
command. When yorick detects an error while reading 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).

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.
You can disable this feature using the preferences dialog in the edit menu.

The Macintosh version of yorick was built using the FaceIt package from
FaceWare, 1310 N. Broadway, Urbana, Illinois, 61801,
[phone], [e-mail].
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 buy a copy of FaceIt, and
then request the Macintosh source from me. At some point in the future, there
may be a Mac version based on the class library provided with Think C or
Metrowerks C, which would make it simpler to create custom versions.

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. This choice can be made for an individual graphics
window using the Window Props button, or for future graphics windows using
the window prefs button in the preferences dialog under the edit menu.

Another graphics preference controls whether or not everything that is drawn
to a graphics window is simultaneously recorded in a PICT in memory.
The previous versions of mac yorick always recorded a PICT, but this slowed
graphics significantly. The default is now not to record the PICT, but
mac yorick no longer "repairs" windows when they are hidden behind other
windows then brought to the front again. To redraw the window contents,
click on the redraw button. The window preferences can be used
to force PICT recording if you get tired of clicking the redraw button.

There is a problem that occurs with color plots when you have an 8 bit deep
screen. Yorick loads a color table of roughly 210 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 noticable on a 16 or 24 bit "true color" screen.

This version of mac yorick supports yorick's animated graphics mode. In the
normal graphics mode, everything appears on the screen as each graphics
command is executed. 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 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 demo3.i or demo2.i for an example).

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
-------------------------------
1) Yorick has been heavily tested on Unix workstations for a couple of years now.
It has been used for a wide variety of production calculations, but we still find
around a bug (usually obscure) a month. The bugs don't prevent us from using
yorick, and are about what should be expected from a code of this complexity.
As a new yorick user, most of your problems are 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.

The Mac version of yorick has not been tested as heavily as the unix version,
so there are probably more bugs in it. The core code is the same as for the unix
version, so any bugs are most likely to be in the graphics package or the user
interface, the parts of yorick that had to be changed the most in porting to the
Mac. In spite of this caveat, I expect the Mac version to be pretty reliable. If you
can find a simple, repeatable way to make yorick crash or get a wrong answer,
I would like to know what it is, so I can try to fix it. If it locks up after hours
of use and lots of number crunching, I won't be able to reproduce your problem.
My hope is that I will get enough simple examples to stamp out any reproducible
bugs in fairly short order.

2) 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 automatically dump the color table, but for
now you need to explicitly dump it.