ExecutableLatexTutorial

This tutorial shows how to edit an executable paper using VisTrails and its LaTeX extensions. It requires LaTeX and VisTrails (version 1.6.2 or later). Please download them if you have not done so already.

1. The tutorial will involve this paper. Please download the source here.
2. After downloading and extracting the source directory, compile the paper. If you have make installed, you can use the included Makefile. If not, type
   

   pdflatex --shell-escape tutorial

   Make sure that vistrails.sty and includevistrail.py are included in the same directory as the paper.
3. Open the newly created tutorial.pdf. You should see the generated figure.
4. Click on the figure. This should download a .vtl file from the ALPS server. If this file does not open automatically with VisTrails, double-click it and define the file extension association or open it directly in VisTrails via File -> Open.
5. 

   VisTrails Spreadsheet
   The VisTrails Spreadsheet should display the same figure. You can pan and zoom the plot as you would with matplotlib.
   
6. 

   VisTrails Builder Window
   If the "Builder Window" is not shown, display it using Window -> Show Builder Window.
   
7. Switch to the"Pipeline" view. Click the corresponding button in the toolbar at the top of the builder window.
8. 

   Editing the computation
   Select the module titled "a" (it is displayed as a box with ports that connect to other modules).
   
9. 

   New figure in spreadsheet
   In the "Set Methods" panel on the right, change the "value" parameter from 1.0 to 1.4 and click the Execute button. VisTrails will create a new plot that shows divergence of the individual lines.
   
10. Save the vistrail in the same directory as the LaTeX source. Choose File -> Save As... and find the source directory, naming the file "alps.vt".
11. Switch to the "History" view.
12. 

    Embedding the result
    Click the Embed button in the lower-right corner. This will bring up an assistant that will generate new LaTeX code that can be copied back to the LaTeX source. Note: If you have not saved the file, you will see a message asking you to save your vistrail before proceeding.
    
13. Make sure "Workflow Results" and "Latex" are selected in the top drop-down menus. Check the "As PDF", "Cache Images", and "Include Workflow" options, and click Copy to Clipboard.
14. Open the tutorial.tex in your favorite text editor.
15. Find the \begin{figure} section and replace the text between the "Begin edit area" and "End edit area" comments with the text from the clipboard. The new code should look similar to the following:

    \vistrail[filename=alps.vt, version=2, pdf, embedworkflow]{}

16. Note that you will probably wish to size the figure correctly so add the width inside the braces. For example,
    

    \vistrail[filename=alps.vt, version=2, pdf, embedworkflow]{width=0.45\textwidth}

17. Edit the \renewcommand{\vistrailspath}{...} line to point to your VisTrails install. Note that for Mac OS X, you need to provide the path to the executable inside the application bundle. For example,
    

    renewcommand{\vistrailspath}{/Applications/VisTrails.app/Contents/MacOS/vistrails}

18. Save the modified file.
19. Quit VisTrails.
20. Recompile the LaTeX source. Again, you may use the included Makefile or call pdflatex directly. LaTeX will call VisTrails to generate the new figure and include it in the new paper.
21. You should see a new version of the paper with the modified results included. It should look something like this. If you run into an error, make sure you have quit VisTrails before running the command and that you have redefined \vistrailspath to point to your local copy of VisTrails. Also, make sure that you have saved the .vt file (from Step 10) to the same directory as the tutorial.tex file.