start coding wavelist method wf_add_var(), in preparation for future

[gwave-svn.git] / README

CAUTION: gwave2 is an experimental port of gwave to Gtk-2 using
the guile-gnome-platform toolkit.   This alpha release may still
crash or contain other bugs.



gwave - a  viewer for the output of spice-like simulators and other
sorts of of analog data.

by:

Steve Tell 
steve@telltronics.org

building and Installation:
        See the INSTALL file

Usage:
        gwave [options] [waveform-file ...]

The gwave main window is dominated by one or more "WavePanels" or
graticules in which waveforms can be displayed.  WavePanels can be
added and deleted with the menus.

As waveform files are loaded from the command line or File->Read menu
item, a window containing a scrolling list of variables in the file
pops up.  Use the left mouse button to drag-and-drop variables into
the WavePanels.  Double-clicking a variable in the the list adds it to
the currently selected panel.  If you choose to close the variable
list to neaten up your desktop, or lose the list under other windows,
use the View->Variable List menu to open it again or bring it to
the top.

To the left side of the WavePanels are scrolling lists of buttons 
corresponding to each waveform shown in the panel.  A waveform shown
in a panel is called a VisibleWave.   
There are two GUI functions overloaded onto the button for a
VisibleWave:
- Click with the left mousebutton to "select" one or more VisibleWaves.
- Press and hold the right mousebutton to pop up a menu of operations
related to that particular VisibleWave.  

To remove waves from the display , select one or more of them and then
press the "delete" button at the top of the main window.  Alternately, use
the delete item on the VisibleWave-button popup menu.

Click on the waveform panels with the left and center mouse buttons to
set two cursors for measuring.  Hold down these mouse buttons to drag
the cursors.

Pressing and holding the right mouse button while the cursor is in a
waveform panel brings up a popup menu.  From this menu you can insert
and delete waveform panels.  Some of the zoom commands are also
replicated on this menu.  

Zooming of the Y axis to magnify a signal verticaly is only available
on the wavepanel popup-menu because it affects each wavepanel
seperately.  By default, each wavepanel automaticly scales to enclose
the minimum and maximum values of the signals displayed in it.  Adding
or removing signals may change the y-axis extents.  After a Y-zoom or
XY-zoom operation, the Y axis for that particular wavepanel changes to
"manual" mode and remains fixed.  To restore the panel to full-size
with automatic Y zooming, select the "Zoom Y Full + Auto" menu option.


Exporting data.

A selected subset of the data from a waveform file may be exported in
a tabular ascii format for postprocessing by external programs.
Select "Export Data..." from the File menu of the waveform variable
list window.

In the current version of gwave, data from multiple files, or from
multiple independent variables within a single file, cannot be
combined and exported to a single file.

Plotting.

A view of the displayed waveforms can be plotted to postscript,
bitmap, and other formats for printing and documenataion.  
All plot rendering is handled by external programs; currently gnu graph
and gnuplot are supported.
Choose the "Plot..." item from the main window or from any wavepanel's
popup menu. 

Only a subset of the features of the external plot-rendering tools are
directly available from the plot dialog box.  To make more advanced
use of these tools, select "Keep Tempfiles" in the plot dialog box.
This will preserve all of the temporary files and scripts used to
drive the external plot-rendering tool.  These files will have names
generated from the name of the plot output by appending suffixes.  Consult
the documentation for each plot-rendering tool for information on additional
options that can be used in the script files.

Additional plot-rendering tools can be supported by writing an
appropriate scheme module; see export-gnugraph.scm and export-gnuplot.scm
for examples.

Configuration save/restore

A gwave panel and VisibleWave setup can be saved and restored.  To save 
all settings for all data files, use the "Save Configuration as Script" from
the man window's File menu.   To save the configuration for one file only,
use the "Save" option on that file's scrolling variable-list window.

Scripts saved by either method can be run to restore gwave
configuration in two ways: 
- From the main window of a fresh gwave session, use the "File->Execute
  Script" menu item.  
- From the unix shell command line.  Either type "gwave -s <script>," or
simply type the name of the script.  Either way, gwave will start and run the
named script, producing wave panels set up exactly as they were when saved.

Scripts written by gwave that restore only a single file's
configuration can also be applied to another file, provided that the
second data file has variables with the same names as those in the
first.  Load the new data file, using the main window File->Read menu
item.  Then, from the variable-list File menu, pick "Apply Script to
File" and choose the script.  Variables in the new data file will be
displayed in panels in the same manner as those from the original
file.  This can be extremely useful, say for comparing the results of
simulating the same circuit under different temperature or component-value
conditions.

In addition to the configuration-script-writing facilities described
here, you are welcome to create your own guile scripts for specialized
gwave applications.  For general guile information, see
http://www.gnu.org/software/guile/guile.html 

For information on gwave-specfic features available for scripting
gwave using guile, see the text files gwave-concepts.txt,
gwave-hooks.txt, gwave-procedures.txt, and gwave-variables.txt All of
gwave's menus and many of its user-interface features are written in
guile; the code in the scheme subdirectory may also be useful as an
example.


Remote Control

A running gwave process may be remotely controlled by any process that
has permission to connect to the same X server.  Use the "xauth" and
"xhost" utilities carefully to control access to your X server at all
times.  This is especialy true when running gwave; anyone who can
connect to your X server can cause your gwave to execute arbitrary
guile code.

The gwave-exec command sends a single guile expression to gwave to
be executed, and displays the result and output of that command.

For example 
        gwave-exec '(x-zoom! 10e-6 20e-6)'

will zoom gwave's display so that the region of time from 10 to 20
nanoseconds is visible.

The gwaverepl program enters an interactive "read-evaluate-print" loop
in which multiple guile expressions may be entered.  Each expression
is evaultated, and the results printed.  Gwaverepl uses the GNU
Readline facility for input line-editing and history scrollback, so
all of the usual emacs (or vi) editing keys may be used.  Type the
End-Of-File character (usually Control-D) to exit gwaverepl.


Bug: do not use gwave-exec or gwaverepl when running multiple
instances of gwave at a time on the same X server.


Waveform Input files.

Gwave understands CAzM transient output (.N/.B/.W) files, the binary
and ascii outputs from HSPICE (.tr0, .sw0, and .ac0) files, Ascii
nanosim "out" format, and tabular ascii files with a header line.
Gwave tries to guess the type of the file based on filename, and then
tries all file formats until one succedes.

Details on using Gwave with the output of various simulators:

Berkeley Spice3F5 and ng-spice.  Gwave can read both the the ascii and
binary forms of the spice "rawfile" output.  If difficulty is
encountered with the binary format, Try selecting the ascii form by
setting the environment variable SPICE_ASCIIRAWFILE to "1" before
running spice3. 

Reading of binary rawfiles has only been tested with both ng-spice and
gwave running on a little-endian machine.  Your mileage may vary (but
please send bug reports!)


GnuCAP (http://www.gnu.org/software/gnucap), and its predecessor 
ACS (Al's Circuit Simulator, http://www.geda.seul.org/tools/acs/index.html)
Gwave should identify and read ACS/GnuCAP output files, generated with
the '>' option to a .tran statement.

Synopsys (formerly Avanti, formerly Meta Software) HSPICE.
Gwave should work with both ascii and binary output in the form of
.tr0/.sw0/.ac0 files.  If one form doesn't work for you, try the other form.
I used to have problems with some .ac0 files but I believe this is fixed. 
Try putting ".options probe" in your input file if you have troubles.

Tanner Research T-Spice.
It has been a while since I tried tspice, but gwave should read the output,
at least from transient analysis runs.  T-Spice output is in a variant of the
CAzM format, not surprising since Tanner bought the rights to CAzM from MCNC.

Silvaco SmartSpice
Gwave works with the variant of berkeley spice rawfile format produced
by SmartSpice.  Both ascii and binary files should work, although this
hasn't been tested recently.

Apache Design Automation NSPICE
Nspice produces yet another variant of the berkeley spice3 rawfile format.
Both ascii and binary files should work.

Synopsys Nanosim
GWave can read the ".out" format from nanosim.

Your own custom waveforms:

The easiest of the input formats to generate with simple scripts and
other tools is the "ascii" format.  See the ACS-simulator output file
tpwl.acs in the examples directory for an example of this format.  The
first line lists the variable names, seperated by whitespace.  The
variable in the first column is assumed to be the independent
variable, for example "time."  Subsequent lines in the file contain
the data, one timestep per line.  The independent variable must be
nondecreasing.  Lines in the file can be arbitrarily long.

Note that the '#' in examples/tpwl.acs is for the benefit of other
tools (such as gnuplot), that don't expect column titles or variable
names in the file.  To gwave, the first line is not a comment but
contains whitespace-seperated fields naming the variables.  The result
is that gwave thinks the independent variable name is "#Time," but
don't let that bother you.


Bugs:

An oft-reported problem in gwave is that the scrolling variable list
window is unable to scroll and show more than one screen of variables
when your simulation has a very large number of them.  This is
actually a limitation in the Gtk+ toolkit; srolling windows can't be
taller than the 32,768 pixel limitation of X11 ofscreen pixmaps.
Workaround: probe fewer variables, or use sp2sp to select only the
ones you need.



----------------------------------------------------------------------

The sp2sp utility.  

In addition to gwave, I've included a utility program called "sp2sp"
(for spice-to-spice).  It uses the same spicefile reaer code to
convert among some of the goofy raw file formats output by spice-like
simulators.  Its primary output format is the simple "ascii" format,
consisting of one line per step, with whitespace-seperated columns.
This format can be read by gwave, but is also ideal for feeding to
awk, perl, or gnuplot.

A complete manual page for sp2sp is provided and installed, but here are
a few hints:

Unlike gwave itself, sp2sp does not autodetect the file format.  Use
the -t option to specify the input file format.

sp2sp can produce arbitrarily long output lines.  This can cause
trouble with very old versions of some unix utilities.

Example sp2sp usage:

        sp2sp -t hspice aoi.W.tr0

----------------------------------------------------------------------
This tool is far from complete. Partial contents of the To Do list:

- better handling of datafiles containing complex numbers.  Currently, 
  these files are read, but only the real part can be displayed.  
  Workaround: Sp2sp prints out both the real and imaginary parts; convert
  the file to generic ascii format using sp2sp.

- Send feedback and error messages from loading of files to a popup window
  or status line instead of to stdout or stderr.
- Drag-and-drop to move waveform from one panel to another
- More guile methods to round out the interface, including:
        access to selected-VisibleWave list, others.
- Drawing a labeled graticule in the waveform area
- Seperate lists for selecting voltage/current/etc. types of variables
- Documentation, both user's manual and programmer's manual.
  Autodocs for guile primitives need to be extracted into text files.

----------------------------------------------------------------------
Acknowledgements

Thanks to my colleagues at work including John Poulton, John Eyles,
Fred Heaton, Trey Greer, and Teva Stone for giving gwave heavy use
over the last several years.

Thanks to Greg Badros and Maciej Stachowiak for the SCWM window
manager, which inspired me to use guile as the extension language for
gwave.  A number of code fragments and a bit of the general style of
the Guile/C interaction was borrowed from SCWM.  Any misinterpretation
and bugs introduced along the way are most certainly my fault.

And last but not least, thanks to the authors of Gtk+, Guile, and
Guile-gnome-platform for some great building blocks.