
View is a data manipulation and plotting tool written by Dave
Gillespie.  

If you have a web browser, the best way to learn about what View is
and how to install it is to pick up the latest version of the webdoc
Web pages (webdocX.XX.tar.gz, where X.XX is a version number) from the
same place you picked up this file. Once you have this Web tree
untarred, point your Web browser (examples of Web browsers include
Mosaic, Lynx, Netscape, and tkWWW) to webdoc/index.html for the home
page of the Chipmunk tools, and to webdoc/compile/compile.html for
compilation instructions.


The rest of this file is written assuming that you don't have access
to a Web browser -- all text is copied from webdoc pages
verbatim. I'll do my best to keep this file up to date, but the Web
tree is now the primary documentation for all aspects of the Chipmunk
system.

---------

View is a data manipulation and plotting tool written by Dave
Gillespie. View is primarily useful for processing and displaying
large collections of one-dimensional data curves. Volume and surface
visualizations are not supported. Programs in View language can be
interactively entered at a shell prompt, or interpreted as batch
files. Features of View include:

Data manipulation 
   View language supports math operations on curves as basic
   operations, as well as scalar math operations and vector-to-scalar
   reduction operations. Other operations allow the extraction and
   insertion of scalars into vectors. Many math functions
   (trigonometric, hyperbolic, and rounding) are included. Symbolic
   functions can be evaluated over ranges specified by curves,
   supporting the comparison of experimental data with theory.
   View supports automatic curve fitting for arbitrary non-linear
   functions. 

Data plotting 
   Auto-scaling plotting of data curves is supported, included dual Y
   axis scales, broken line variants, and symbol plotting. Plots can be
   interactively previewed. Postscript, HPGL, and the file format for
   the Chipmunk graphics editor Until are supported. 

Libraries 
   Libraries written in View language support error bar generation,
   histogram generation, numerical integration, zero-crossing
   detection, and data smoothing. 

Compatability 
   View accepts data file input from the Log data visualization
   system, supporting data analysis and plotting of simulation data
   from Log simulators (Analog and Diglog). 

Instrument Control 
   View includes an HPIB instrument control library, Mt , and
   drivers for several HP and Keithly instruments. Another HPIB
   package included with view interfaces directly to a Tektronics
   2430 scope. These programs were used under Unix in a Sun Sparc
   environment to interface to instruments using an IOTech HPIB
   card; rewriting the low-level interface for a different hardware
   environment should be feasible. 

Users not requiring the power of a commercial data plotting and
manipulation tool such as MATLAB sometimes find View a cost-free
alternative; Log users sometimes find View to be an effective
post-processing tool for simulation results. These two classes of users
make up the current View userbase. 


Platforms and Requirements 
--------------------------

The Chipmunk tools require an ANSI c compiler (typically GCC) and
X11 (R4, R5, or R6). Color displays with 8 bits per pixel work best for
Chipmunk (other than 8bpp can be problematic), although Log supports
black-and-white displays. An HTML browser (like Mosaic or Lynx or
Netscape) is also necessary to access the Chipmunk documentation.

These are the currently supported platforms, with details of
platform-specific requirements: 

   AmigaOS. Requires ADE X or AmiWin X11. 
   Apple Macintosh, OS/X and AU/X. 
   DEC MIPS-based DECstations 
   HP Series 300/400, HPUX. 
   HP Series 700, HPUX. The HP-supplied cc, with extra-cost
   ANSI option, will also compile Chipmunk. 
   IBM PC and Compatibles, FreeBSD. 
   IBM PC and Compatibles, Linux, Slackware. 
   IBM RS/6000. The IBM xlc compiler is known to compile
   Chipmunk; gcc has not been tested. 
   SGI. Chipmunk known to work on Indigo and Challenge, no
   others were tested. The SGI cc is recommended. 
   Sun SPARC, Solaris 1.X (SunOS 4.X). 
   Sun SPARC, Solaris 2.X (SunOS 5.X). 
   IBM PC and Compatibles, OS/2. 

     OS/2 Requirements 

     Only the Log system (diglog, analog and loged) is ported. However,
     porting Log meant porting Psys: if you are an OS/2 user who is 
     interested in porting View, the Log port gives you a good head
     start.

     Here are the requirements for Log:

     The icc compiler. Not known if gcc will work also, please let
     me know if you try gcc. 

     OS/2 with TCPIP and X11 (PMX). OS/2 revisions 2.1 and higher
     should work, but all current testing has been done using WARP.
     TCPIP version 2.0 with the "latest CSD's" to the Base kit is also
     needed, as is the X-server (PMX) kit. 


If your configuration is different than the ones described above,
only take the package if you feel confident in your C/Unix abilities
to do the porting required. If you do successfully port to a new
architecture or OS, send us the changes required, and we will
incorporate your port in the next release of the chipmunk tools.

Here is the know status of Chipmunk on popular platforms not currently
supported

   IBM PC-Compatibles, MS-DOS or Windows. Several failed
   porting attempts have occurred. However, a new porting effort
   is underway by a group in Europe. Contact me for details.
 
   IBM PC-Compatibles, NextStep. No ports are in progress, to
   my knowledge. 

   Apple Macintosh, MacOS. No ports are in progress, to my
   knowledge. 

   DEC Alpha, OSF/1 or VMS. Several Alpha ports have failed,
   because of 64-bit compatibility problems with binary file I/O. I
   don't think the port is impossible, just more difficult than the
   successful ports listed above. 

To get view running, first bring over a copy of psys-Y.YY.tar.Z (where
Y.YY is a version number), available at the same place this file was
found. Untar and make psys per instructions in the package.  After
psys is installed, you can start to install view.


Compiling View 
--------------

This document assumes that you have successfully compiled the Psys 
libraries. This document also assumes that you have uncompressed and
untarred the View file, and installed it in the chipmunk directory.
Note that view has not been ported to OS/2.


Begin by descending to the view directory. Edit the file Makefile, 
and make any necessary changes. Comments in the Makefile will guide
you through these changes; the changes are labeled with the markers (1),
(2), (3), ect. Once these changes are made, execute the command 

make install 

If things are working correctly, a long series of compilations, linkings,
and file movements should occur without error. This will create the
program chipmunk/bin/vc. The name is changed from view 
during the copy to chipmunk/bin/ because an existing Unix tool
uses that name. 

To do a quick test, start view by executing chipmunk/bin/vc and
typing the following test program into the program. 

basis i = 1:10:1 

y = i*i 

fplot i y 

quit 

After the "fplot" command, a window should pop up with the curves, one
a straight line and one a curve. To learn more about using view, see the 
user documentation. 


Problems and Solutions 
----------------------

Its quite possible that compilation did not proceed smoothly, or that
execution problems happen while using the tool. Here are some possible
ways that things could have went wrong, along with suggestions. 

Plotting doesn't work 
   If you have a monochrome machine, you will notice a bug in the
   plotting routines that results in blank on-screen plots. I've spent
   some time trying to find this without success. Note that the
   problem is purely in display; Postscript produced by the plot
   portion of view will be correct, but you'll be flying blind while
   creating the plot. 

The view source distribution includes routines for using view as a test
instrument control environment using GPIB. These routines are no longer
used by the maintainer, but are included in the package as a starting point
for someone to continue development on the GPIB portion of view. The
directories mt/ and tek2430/ are there for GPIB users, and can be
safely ignored by everyone else. If you have an HPIB card in your
workstation and want to try resurrecting these tools, type make clean
myinstall in the view directory, and be prepared to start detective
work! 

If you have problems compiling view, or need guidance in a GPIB
development, I'd be happy to offer suggestions.Send email to
lazzaro@cs.berkeley.edu and include the following information.

   Complete machine configuration, including machine type, OS
   revision, compilers, and X servers. 

   A listing of the output from the failed compilation process, or
   any messages printed by a Chipmunk program or the OS or X
   when an error occurs.
 
   Details of any changes you have made to the distribution before
   this compilation. 

   The effects of following any advice given in the compilation
   instructions. 

Documentation for View 
----------------------

All of the documentation for using View is included in the webdoc
package. See:

webdoc/document/view/index.html

----

If using the Webdoc documention isn't practical, most of the contents
of the Webdoc log pages are contained in the following files in 
view/man/*. These are shipped in TeX and postscript form.

view.ps: User manual. This manual serves as an introduction to view

viewprg.ps: Language manual. This manual describes the scripting language
of view.

viewmod.ps: Programmers manual This manual describes how to write new
tools for view. It was written for the Pascal version of view.
However, since the port to C was done using a Pascal-to-C translator,
it isn't too difficult to apply the information in the manual to C
programming.

Several libraries, written in view language, are included with view,
in view/lib. On-line help, and comments in the library source, form
the main documentation of these libraries. Here is a list of
libraries. 

crunch.view 
   Simple routine for decimating curves, written to reduce the size of large data curves produced by digital
   oscilliscopes. 
ebasis.view 
   Extends the builtin basis command to support exponential basis functions. 
errbar2.view 
   Adds error bars to a curve. 
examples.view 
   This isn't a library, but a set of programming examples designed as a 
   tutorial for new view-language users. 
filter.view 
   Applies simple a smoothing filter to a curve. 
histogram.view 
   Computes a histogram of a curve. 
integrate.view 
   Numerically integrates a curve. 
reverse.view 
   Reverse the order of a curve. 
swapxy.view 
   Exchange x and y values in curve, 
zcross.view 
   Finds zero-crossing points of a curve. 

One major feature added (by Harold Levy, Caltech) after the port to
Unix, and thus not described in the manuals above, is a package for
arbitrary non-linear curve fitting, fit.  Here is what is printed in
view in response to "help" for fit.

fit  < data >   < function >   < param1 >   < param2 >  ...
  Fit a computed function to a data curve with the same
  basis.  This is done via simplex minimization of chi^2
  over the specified parameters of the function.  The
  constant "fit_tol" is used to specify the goodness
  of fit, and is created with a default value of 0.001
  if not previously set.  Output can be redirected to a
  specified file if the "  >  file_name" convention is
  appended to the command line.

Here is a simple example to type in to understand fit: 

here is a simple example to type in to understand "fit"

basis i = 1:100:1   ## make a straight line curve
a = 10              ## make up some variables
b = 100             ## make up some variables
y == a*i + b        ## set up a model equation for a straight line
fplot y i           ## note how parameter a and b are a bad fit to data i
fit i y a b         ## run the fit program
fplot y i           ## note the better fit

Here is a more intense example ... 

basis v=0:5:1                                   ## independent variable
i = 1.23e-6 * log(1+exp((v-.67)/.05))^2         ## here's the data
i0 = 1                                          ## make up some variables
vt = 1                                          ## make up some variables
f == i0 * log(1+exp((v-vt)/.05))^2              ## here's the model
fplot i f                                       ## look at initial bad fit
fit i f i0 vt                                   ## fit with fit_tol = 1e-3
fplot i f                                       ## look at better fit
fit_tol = 1e-12                                 ## try for even better
fit i f i0 vt                                   ## fit with better guess
style 1 circ                                    ## here's new plot style
fplot i@1 f                                     ## look at best fit
list i0 vt                                      ## dump the values


New Features
------------

Apart from the Web documentation and ports, only minor changes have
been made to View:

Postscript updates. All Chipmunk tools now produce encapsulated
postscript that is compatible with the psfig macros distributed with
TeX. John Platt and Dave Gillespie of Synaptics, Michael Godfrey at
ISL, Himanshu R. Pota of ADFA in Australia, and
gary@minster.york.ac.uk contributed to these improvements.

Bugfixes. Lots of small bugs found and fixed in view, especially ones
on the HP 700 series platform.

