Editing TkMadagascar

tkMadagascar is a pure-Python, Tkinter graphical user interface for Madagascar.  It allows users to construct processing flows using a graphical tool as well as on the command line.  

tkMadagascar is comprised of two main programs: the standalone program browser and the main user interface.

= Video tutorials = 

Please view the following tutorials on YouTube for a quick introduction to tkMadagascar:

==Standalone program browser==

<youtube>q5O07-XGvhM</youtube>

==Introduction to tkMadagascar==

<youtube>piQTfk0aUfo</youtube>

==Linking flows in tkMadagascar==

<youtube>eJEAP9OJFTA</youtube>

==Running SCons from within tkMadagascar==

<youtube>AEGbOuOyI9c</youtube>

==Using templates in tkMadagascar==

<youtube>E8jE_qXfj4A</youtube>

==Finite difference modeling in tkMadagascar==

<youtube>Mj3vmzs7rb8</youtube>

= Program Browser = 

The program browser allows users to quickly view the self-documentation for Madagascar programs.  To access the browser simply enter:  '''sfbrowser''' on the command prompt. 

The browser is a single window consisting of multiple frames.  To the left, is the area where the self-documentation will show for RSF programs.  On the right is a list of all Madagascar programs contained within your local installation.  This list is repopulated everytime that the browser is run, so it will be up-to-date provided that you have updated the Madagascar self-documentation (via a reinstall).  

== Search by name ==

To select programs, simply double-click on their names in the program list.  If you know the name of your program, you can enter it into the box to the left of the '''Find Program''' button, and then press '''Find Program''' which will take you to the program that you requested.  

== Search by functionality == 

Additionally, you can search program descriptions if you are not sure which program to use for a specific task.  To do so, click on '''Search by functionality''', which opens a separate window.  Type the keyword or phrase you want to look for in program descriptions.  For example, to look for programs to add RSF files together, we might search for "add".  Then click '''Search'''.  Once the result list is populated, you can either double-click or click the '''Select''' button, to bring that programs self-documentation into the other window.

= Main interface =

The main interface is accessed by entering: '''sfgui''' on the command line.  It allows users to create and manage processing flows using Madagascar and SCons.

== Sandbox ==

The main window of the interface is called the "Sandbox."  It is where all of your Flows, Plots, and Results will show up as you add and configure them.  The Sandbox is also the home screen.  Closing the Sandbox terminates tkMadagascar.

The Sandbox has the following menus:

=== File === 

The File menu handles file input/output operations.  

New - Resets the Sandbox.

Load state - Load the previous state of a saved Sandbox, or load items from a saved Sandbox.

Save state - Save the state of the Sandbox (includes all items attached to a Sandbox). 

Export to SConstruct - Export all Flows, Plots and Result commands to an SConstruct of your choosing for later execution on the command line.

Close - terminate tkMadagascar.

=== View === 

The view menu lets you choose which other windows to show:

Program browser, lets you find and select programs to add to your Sandbox.
Log, lets you view the output of running processes.

=== Run === 

The run menu lets you execute commands from the command line on the items attached to your Sandbox.  List of commands is below:

scons - build Results and their dependencies

scons view - build Results and their dependencies, try to open a plot command for each Result

scons lock - build Results and save them to $RSFFIGS

scons -c   - clean the local directory

scons -n   - try a dry-run of scons

== Program browser == 

The program browser is nearly identical to the standalone version mentioned above, but this version has three additional buttons:

=== Add Flow === 

Add the selected program as a Flow item to the Sandbox.  Flows have black outlines.

=== Add Plot ===

Add the selected program as a Plot item to the Sandbox.  Plots have purple outlines.

=== Add Result === 

Add the selected program as a Result item to the Sandbox.  Results have blue outlines.

== Log == 

The log updates you on the status of a running process.  You are only allowed to have 1 (one) running process at a time.  If the child process is hanging, you may kill the process simply by clicking '''Kill process'''.  The process is then killed immediately, without a clean termination.

== General workflow ==

=== A new session === 

When a new instance of tkMadagascar is opened, the user is presented with an empty Sandbox.  To get started, the user should open the '''Program browser''' from the '''View''' menu.  The user may then browse, select, and add as many Flows, Plots or Results as they would like from the Program browser.  

=== Interacting with Flows, Plots and Results === 

Flows, Plots and Results appear in the Sandbox after they are added by the Program browser.  All behaviors and actions that we describe are equally valid for Flows, Plots, and Results.  For simplicity, we refer to only Flows from here on.

You may move Flows by clicking and dragging with the left mouse-button.  Additionally, all Flows are initially added to the Sandbox in the '''unconfigured''' state.  To configure a Flow you must edit its parameters, selecting valid values for the parameters that you wish to set.  To edit a Flow's parameters, you can '''right-click''' over the Flow, which will bring up a drop-down menu.  Select '''Edit parameters''' from this drop-down menu, which opens a menu with a list of parameters and entry boxes.

=== Configuring Flows ===

Once the '''Edit parameters:''' window is open, you can simply input values for the parameters that you want to set.  You only need to enter the value, you do not need to enter the value in "key=val" format.  There are some special parameters that every Flow has:

'''output''' - the name or names of files that you want to output to.  If multiple files, then separate the names with a space.  You do not need to include '.rsf' on the end of file names.

'''input'''  - the name or names of files that you want to input to.  Same rules as above.

'''custom''' - a raw string of any additional parameters that you want to set.  You must set these parameters in "key=val" format, unlike the other parameters.  There is no parameter checking for parameters set this way.  Multiple parameters should be separated by spaces.

Additionally, some programs have parameters that work on any axis.  For example, sfspike allows the user to set the number of samples (n#) for any axis.  These parameters are listed as the parameter name, with the # still attached.  These parameters must be set with "key=val" formatting as well. 

For sfspike's n# parameter, you might set:  n#=   n1=100 n2=100

Once a Flow is configured, the Flow will change color to have a green background and the name of the output file will appear inside the flow.  A green Flow is good-to-go, and does not require any additional configuration.  It will be automatically saved, exported, or executed.  Unconfigured Flows may be saved, but will not be exported or executed.

Click '''Accept''' to save your parameter selections.
Click '''Preview''' to see how the Flow would look in an SConstruct (useful for debugging).
Click '''Self-documentation''' to see the Programs self-documentation while editing parameters.

=== Linking Flows === 

One of the nicest features of Madagascar is that programs can pipe their output to other programs, greatly reducing the need for intermediate files.  This functionality is fully supported by tkMadagascar.  To link two Flows, right click on the flow that you want to link to another Flow, and select ''' Link'''.  The cursor will change to a cross-hair to indicate that you are in '''Link''' mode.  Once in '''Link''' mode, click on the Flow that you want to link to.  The Flow that is selected for linking is assumed to have desired output for the Flow that you right-clicked on.  

Once Linked, the two Flows move together, their borders change color, and their input and output parameters are automatically changed to reflect the fact that one is piping into the other.  The border colors change as follows:
Flows  become light gray,
Plots become light purple,
Results become light blue.

To '''Unlink''' a Flow, simply '''right-click''' on the Flow you wish to unlink, and then select unlink.  The Flow will be detached.  The other Flows in the Linked Flow will be detached as well, or placed into separate Linked Flows.

=== Deleting Flows === 

To delete a Flow from the Sandbox simply '''right-click''' on the Flow, and select '''Delete'''.  If you select '''Delete''' for a Linked Flow, then you will delete all Flows linked to it.

= Requirements = 
tkMadagascar requires Python 2.5 or higher, and Tkinter 8.0 or higher.  Tkinter is included by default with your Python installation, so you will have to upgrade your Python installation to a higher version to upgrade Tkinter if needed.  If in doubt, try to run tkMadagascar first, before upgrading, as your version may still work properly.

'''Note: you must have a fully functional RSF installation before you can use tkMadagascar.'''