Software
========

Prerequisites
-------------

To run the software you need:

* `python <http://www.python.org/>`_

* `numpy <http://numpy.scipy.org/>`_

* `Tkinter <http://wiki.python.org/moin/TkInter>`_

* Postscript viewer such as `GSview <http://pages.cs.wisc.edu/~ghost/gsview/index.htm>`_

These tools are standard under linux (at least in Ubuntu) and
available as well under windows.

The File (download)
-------------------

Copyright (c) 2009 Martin J. Mohlenkamp.
Released under the terms of the
`GNU General Public License <http://www.gnu.org/licenses/gpl.html>`_.

`<trvtool.py>`_

Most users will just run the software, and so do not need to worry
about the contents of the file. If you want to know more about how the
code is structured, see the code documentation:  

.. toctree::
   :maxdepth: 2

   code.rst


User's Manual
-------------

To start the visualization tool, run the file trvtool.py using
python. In linux that means open a shell and type::

   python trvtool.py

The initial window has the following buttons:

Exit
   Exit this window and all children.

Load State
   Load in a visualization that was previously created and saved to a
   file. Data files are included with many of the examples, such as
   `<2x2x2pr2G3.dat>`_ for
   the example in :ref:`G3-section-label`.  

New, Random
   Start a new visualization. The user specifies 

   * the field (R or C)

   * the dimension

   * the rank for :math:`T_1`, :math:`T_2`, and :math:`T_3`

   * the plotting rank

   * the resolutions :math:`M_i`. This can be entered as a single
     integer (e.g. 2) or as a list with length the dimension
     (e.g. [2,2,3,3]).

New, Manual over R
   Start a new visualization, over the real numbers. The user enters
   the plotting rank and the tensors :math:`T_1`, :math:`T_2`, and
   :math:`T_3`. These tensors are entered in python syntax as a list
   of lists of lists. Specifically,
   [[[a,b,c],[d,e,f]],[[g,h,i],[j,k,l]]] means

   .. math::
      [a,b,c]\otimes[d,e,f]+[g,h,i]\otimes[j,k,l]

   For example, to start the example in  :ref:`G3-section-label` that
   eventually produced `<2x2x2pr2G3.dat>`_, we entered plotrank 2 and
   the three tensors as

   [[[ 1,1],[0,1],[0,1]]]

   [[[1,-1],[1,0],[1,0]]]

   [[[0,1],[1,1],[1,-1]]]


New, Manual over C
   Start a new visualization, over the complex numbers. Similar to the
   real case, but only two tensors are entered. To enter a complex
   number for an entry, use the python syntax, which is 3.4+2.5j means
   :math:`3.4+2.5i`.

Once a visualization has been loaded or created, the main
visualization window opens.

Main Visualization Tool
^^^^^^^^^^^^^^^^^^^^^^^

Help
   Directs you back to this web page for help.

State Info
   Opens a new window in which the current state is printed as
   text. This is useful to check that you are plotting what you think
   you are, and make sure nothing unpleasant like a singular matrix
   was encountered.

Save State
   Opens a file dialog window that allows the state to be saved. The
   state includes all the parameters needed to recover the
   visualization, but does not include things like the latest
   rectangle rendered to.

Exit
  Exit the visualization tool, but not its parent. Multiple
  visualizations can be run from the same parent.

Update
  Change the plotting rank. This allows one to keep the same tensors
  to define the line/plane. If the rank is increased then plotted
  points are retained; otherwise they are cleared.

Render to
  The user specifies a rectangle to render to, noting that there is a
  tensor defining the line/plane at :math:`(0,0)` and one at
  :math:`(1,0)`. The user then gives a filename (default tmp) and
  this button writes an encapsulated postscript file that one can then
  view to actually see the visualization.
  In linux that means open a shell and type::

     gv tmp.eps&

  If one is using gv, then one can set its "State" to "Watch file" so
  it will reload whenever you re-render. 

ALS
  The user specifies a rectangle and a number of points with which to
  discretize that rectangle in each direction. Tensors on the plane at
  those grid points are constructed, and then fit to with a tensor of
  the rank being plotted. These approximations are then plotted.

Crop
  The user specifies a rectangle, and all points falling outside this
  are permanantly deleted. Note that the "Render to" button does not
  plot points outside of its rectangle anyway.

Trim Covered
   Remove plotting discs that are (mostly) covered by darker
   disks. This uses a niave, heuristic algorithm. 
   It does produce a smaller state to save.

Line 
   This button is only available for visualizations over the real
   numbers. The user specifies a pair of :math:`T_j` to connect with a
   line. The indexing starts at 0, so valid pairs are (0,1), (0,2),
   (1,2), and permutations. The user then gives the (parametric) start and end
   points of the line, with (0,1) corresponding to the line segment
   that just connects the two points. The user also gives the number
   of points/tensors to use along the line. If the tensors along the
   line have rank larger than the plotting rank, then the line is
   refused.