===== Can I Perform a Diagnostic Test of Easyviz? =====

Yes. It is wise to perform a diagnostic test before reporting any error
or trouble to the SciTools maintainers. Find the source folder of SciTools
and go to the `misc` subfolder. Run
!bc dsni
python diagonstic.py
!ec
On the screen, you can see what you have of working software that Easyviz
may use. You do not need to see "ok" after each test, but at least
one plotting program must be properly installed. Include the detailed
diagonstics in the `scitools_diagnostic.log` file as attachment in any
mail to the SciTools developers.

===== The Plot Window Disappears Immediately =====

Depending on the backend used for plotting with Easyviz, the plot
window may be killed when the program terminates. Adding a statement
that makes the program halt provides a remedy:
!bc cod
raw_input('Press Return key to quit: ')
!ec
The plot window will now stay on the screen until hitting the Enter/Return key.

Another remedy can be to add a `show()` call at the end of the plotting:
!bc cod
show()
!ec
# test on Windows!

===== I Get Thread Errors While Plotting =====

With the Gnuplot backend, thread errors from Python may occur if you
plot many curves. The remedy is to do `import time` and insert
a `time.sleep(0.2)` (pause the program for 0.2 sec) between each call
to the `plot` command.

Remark: Scitools v0.8 automatically inserts a 0.2 sec pause when
plotting many curves with the Gnuplot backend.

===== I Get Strange Errors Saying Something About LaTeX =====

You probably run Easyviz with Matplotlib as backend, and you do not
have a working LaTeX installation. Matplotlib applies LaTeX for
improved rendering of legends, titles, and numbers.  The fix is to
turn off the use of LaTeX, which is done by the `text.usetex`
parameter in the `matplotlib` section of the configuration file.  Set
this parameter to `false`. See the subsection "Setting Parameters in
the Configuration File" in the section "Advanced Easyviz Topics" in
the Easyviz tutorial. The tutorial can be reached from the code.google.com
site or by running pydoc scitools.easyviz. If you use Matplotlib as
default plotting engine, we recommend to have a `.scitools.cfg`
configuration file in your home folder and that use control the use
of Matplotlib parameters in this file.

Another fix of LaTeX-related problems is to switch to another backend
than Matplotlib.


===== Old Programs with 2D Scalar/Vector Field Plotting Do Not Work =====

SciTools version 0.7 changed the default backend for plotting to
Matplotlib instead of Gnuplot (provided you have Matplotlib and you
run `setup.py` to install SciTools - binaries for Debian still has
Gnuplot as the plotting engine). Some functionality in Gnuplot, especially
regarding 2D vector/scalar fields, is not yet present in Matplotlib
and/or supported by the Easyviz interface to Matplotlib.
You then need to explicitly run the script with Gnuplot as plottin
engine:
!bc
python myprogram.py --SCITOOLS_easyviz_backend gnuplot
!ec
or you must import gnuplot explicitly in the program:
!bc
from scitools.std import *
from scitools.easyviz.gnuplot_ import *
!ec
or you can edit the installed `scitools.cfg` file ("backend" keyword
in the "easyviz" section), or your local version `.scitools.cfg` in
your home folder, or maybe the simplest solution is to reinstall
SciTools with Gnuplot as plotting engine:
!bc
python setup.py install --easyviz_backend gnuplot
!ec


===== Check Your Backends! =====

When you encounter a problem with Easyviz plotting, make sure that the
backend works correctly on its own (there may, e.g., be installation
problems with the backend - Easyviz just calls the backend to do the
plotting).

=== Gnuplot ===

For the Gnuplot backend you can try the following commands in a
terminal window:
!bc rpy
Unix/DOS> gnuplot
gnuplot> plot sin(x)
!ec
This should result in a plot of the sine function on the screen.
If this command does not work, Easyviz will not work with the Gnuplot
backend. A common problem is that Gnuplot is installed, but the path
to the Gnuplot executable is not registered in the `PATH` environment
variable. See the section *Installing Gnuplot* if you need help with
installing the Gnuplot program and its Python interface.

=== Matplotlib ===

The following code tests if you have installed Matplotlib correctly:
!bc
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 2*np.pi, 101)
y = np.sin(x)
plt.plot(x, y)
plt.show()
!ec
In case of problems, go to the Matplotlib source directory, remove the
`build` subdirectory, and try a new install with `python setup.py install`.


===== Can I Easily Turn Off All Plotting? =====

Yes, this is very convenient when debugging other (non-plotting) parts
of a program. Just write
!bc
from scitools.std import *
turn_off_plotting(globals())
!ec


===== How Can I Change the Type of Gnuplot Window? =====

The configuration file (`.scitools.cfg` in your home directory or a
local directory, copied from `scitools.cfg` in the SciTools source
code distribution) has an item for controlling the type of *terminal*
used by Gnuplot:
!bc
[gnuplot]
...
default_term               = <str> wxt
!ec
Here, the `wxt` terminal, based on wxWidgets, is chosen. Other
choices are `x11` on systems supporting X11 graphics, or `aqua` on
Mac. The `wxt` value is an allround choice since wxWidgets work, in theory,
on all platforms.

===== How Can The Aspect Ratio of The Axes Be Controlled? =====

See the section "Controlling the Aspect Ratio of Axes" in the
tutorial.

===== Trouble with Gnuplot and Threads =====

When using the Gnuplot backend, the following error may be encountered:
!bc
thread.error: can't start new thread
!ec
A remedy is to create fewer plots, and for animations, update the plot
window less frequently. For example,
!bc cod
for i in range(number_of_frames_in_animation):
    <prepare data>
    if i % == 100:     # plot every 100 frames
        <make plot>
!ec

===== Trouble with Movie Making =====

The call to `movie` demands that you have video encoders installed.
The legal encoders are `mencoder`, `ffmpeg`, `mpeg_encode`, `ppmtompeg`,
`mpeg2enc`, and `convert`. Some of these also require additional
software to be installed.

To install (e.g.) `convert`, you need to install the ImageMagick
software suite, since `convert` is a part of that package. ImageMagick
is easy to install on most platforms. The `ppmtompeg` encoder is a part
of the Netpbm software, while `mpeg2enc` is a part of `mjpegtools`.

On Linux Ubuntu you can issue the following installation command to install most of the available encoders for the `movie` function:
!bc
Unix> sudo apt-get install mencoder ffmpeg libavcodec-unstripped-51 netpbm mjpegtools imagemagick
!ec

When something goes wrong with the movie making, check the output in
the terminal window. By default, Easyviz prints the command that makes
the movie. You can manually copy this command and run it again to start
finding out what can be wrong. Just switching to a different encoder can be
a quick remedy. The switch is done with the `encoder` keyword argument
to `movie`, e.g.,
!bc
# Make animated GIF movie in the file tmpmovie.gif
movie('tmp_*.png', encoder='convert', fps=2,
      output_file='tmpmovie.gif')
!ec

===== I Get Thread Errors with Gnuplot =====

When plotting inside a loop, e.g.,
!bc
for i in some_values:
    ...
    plot(t, X0, 'r-6', axis=(0, 1, -2, 2),
         xlabel='t', ylabel='Xt', title='My Title')
!ec
Gnuplot may lead to thread errors. A remedy is to do some plotting
outside the loop and then only update the data inside the loop:
!bc
plot(t, X0, 'r-6', axis=(0, 1, -2, 2),
     xlabel='t', ylabel='Xt', title='My Title')
for i in some_values:
    ...
    plot(t, X0)
!ec


===== Where Can I Find Easyviz Documentation? =====

There is a verbose Easyviz documentation that mainly focuses on an
introduction to Easyviz (what you read now is a part of that
documentation).

Another useful source of information is the many examples that come
with the SciTools/Easyviz source code. The examples are located in
the `examples` subfolder of the source.


===== Grace Gives Error Messages When Calling Savefig/Hardcopy =====

Some versions of grace do not like commands for printing the plot
to file. Try the interactive GUI: set options in Print setup... and
then click on Print.

===== I Cannot Find Out How My Plot Can Be Created =====

Note that Easyviz only support the most basic types of plots:

  * y=f(x) curves
  * bar plots
  * contour plots of 2D scalar fields
  * elevated 3D surfaces of 2D scalar fields
  * 3D isosurfaces of 3D scalar fields
  * arrows reflecting 2D/3D vector fields
  * streamlines, streamtubes, and streamribbon for 3D vector fields.

For such standard plots you can use Easyviz, otherwise you have to
use a plotting package like Matplotlib, Gnuplot, or VTK directly
from your Python program.

The following Matlab-like commands (functions) are available (but not
supported by all backends):

  * autumn,
  * axes,
  * axis,
  * bone,
  * box,
  * brighten,
  * camdolly,
  * camlight,
  * camlookat,
  * campos,
  * camproj,
  * camroll,
  * camtarget,
  * camup,
  * camva,
  * camzoom,
  * caxis,
  * cla,
  * clabel,
  * clf,
  * close,
  * closefig,
  * closefigs,
  * colorbar,
  * colorcube,
  * colormap,
  * coneplot,
  * contour,
  * contour3,
  * contourf,
  * contourslice,
  * cool,
  * copper,
  * daspect,
  * figure,
  * fill,
  * fill3,
  * flag,
  * gca,
  * gcf,
  * get,
  * gray,
  * grid,
  * hardcopy,
  * hidden,
  * hold,
  * hot,
  * hsv,
  * ishold,
  * isocaps,
  * isosurface,
  * jet,
  * legend,
  * light,
  * lines,
  * loglog,
  * material,
  * mesh,
  * meshc,
  * openfig,
  * pcolor,
  * pink,
  * plot,
  * plot3,
  * prism,
  * quiver,
  * quiver3,
  * reducevolum,
  * savefig,
  * semilogx,
  * semilogy,
  * set,
  * shading,
  * show,
  * slice_,
  * spring,
  * streamline,
  * streamribbon,
  * streamslice,
  * streamtube,
  * subplot,
  * subvolume,
  * summer,
  * surf,
  * surfc,
  * surfl,
  * title,
  * vga,
  * view,
  * white,
  * winter,
  * xlabel,
  * ylabel,
  * zlabel


