Sebastian Steiger

I recently created a GUI for my NEGF simulator ANGEL and got it installed in nanoHUB.org. Despite the fact that I admire the nanoHUB.org project, I feel like it was hard for me plowing through the bits and pieces of information offered to contributors and in the end making it happen. So maybe this little how-to can shed light on dark spots which in the end are essential for the tool deployment but were not spoken of.

Let me start out by describing the situation I was in at the beginning, and maybe you can compare your own situation to it:

• I had developed an up-and-running simulator, no GUI, under Linux.
• I wanted to make the simulator accessible to people around the world.

Clear task, isn't it? Being in the semiconductor device simulation field, it was clear to me that nanoHUB.org is the one and only place to put my simulator. If you are in a similar position then continue reading to see what it takes from your side.

To GUI or not to GUI

The first decision to make is whether to do a GUI a not. A nanoHUB "Tool" will only be accessible with some sort of GUI. Alternatively, you can create a "Download": make a zip- or tar-file of the code, put a license on it (be sure not to violate your Univeristy's regulations!), and upload it. That's straightforward and almost no work is involvd. But: interest and traffic will be minimal, people will not spot your contribution, and they will probably have the hardest time compiling and installing it on their own machine. I first created the Download and then, some months later, wrapped my head around the GUI.

Use Rappture to create the GUI

Once you decide to create a Tool, you need to decide how you are going to create the GUI. Here the language Rappture, invented and maintained by the Nanohub people, is your method of choice. In principle you could use Qt, wxWidgets etc. to do the design yourself. However, Rappture has been tailored for Nanohub in that a rappturized tool will automatically provide user statistics, etc. when being deployed on NAnohub. Furthermore, Rappture contains some visualization widgets (components) which other methods are missing.
Some useful general info about Rappture:

• In Rappture you do not actually design the GUI. You only specify a collection of input and output widgets in a file called tool.xml using the XML language. The arrangement on the screen is done by Rappture itself (in consecutive order).
• The principal idea is to have an <input> and an <output> section in the tool.xml file. Upon pressing the Simulate button, which is always there (you don't specify it in tool.xml), some kind of executable (specified by you in tool.xml) is executed which processes the values in the input section given by the user, starts up your simulator, and somehow hook up the simulation results with the output section.
• The Simulate button creates a file called driver12345.xml which contains all the user-specified simulation input. Your simulator then either has to able to read this XML-file directly, or you need to transform it into a compatible input deck yourself. Upon completion of the simulation, you are expected to feed the simulation results back into a file called run12345.xml which is then used by Rappture to visualize the results. Here 12345 stands for some unique identifier for each simulation run.
• Rappture is open source and can be easily downloaded and installed on your local Linux workstation. Like this you're able to test the GUI outside of nanoHUB.org.
• Rappture has Tcl/Tk underneath. Two people in the nanoHUB team, Michael McLennan and George Howlett, are true Tcl experts and have worked with it for decades.
• Right now there are 2 major new developments: iRappture, which itself is a GUI to create tool.xml files, and Rappture 2.0, a major facelift to be released later this year.

Them widgets

When it comes to creating the tool.xml file, you might ask which widgets (components) you have at your disposal for input and output. You can go to this site for an answer, but I find the documentation patchy. Here's a shortlist:

Input side:

• <number> Real number input field on steroids (optionally handles physical units).
• <integer> Integer input field
• <string> A text field
• <choice> A drop-down list
• <boolean> A checkbox
• <table> I'm not sure how this works - I believe it's not a "real" table.
• <structure> This is a nice and sophisticated widget to specify parameters for a 1D-layered structure (like e.g. layer lengths).

All these widgets can be grouped together:

• <group id="something"> creates simple groups of widgets
• <group id="tabs"> The special keyword tabs splits up the input section into tabs. Each tab can itself be structured into groups
• <phase> I didn't use this myself so far, but it's the top-level structuring of specifying input: phase 1 can have tabs and groups, phase 2 can have tabs and groups, etc.

Output side:

• <curve> A nice, sophisticated 1D plotting tool.
• <cloud> A tool to visualize 2D/3D data. However, I've had severe problems, I think it has very limited functionality and I can't recommend it. Part of could are the <mesh> and <field> sections.
• <unirect2d> A tool to visualize 2D data defined on a tensorial grid that has uniform grid spacing both in x and y.
• <image > simply puts an image somewhere.

I believe on the output side there is a lot of room for improvement:

• 3D structures (like e.g. viewed in Paraview, Tecplot, Geomview, ...) cannot be visualized.
• Contour plots nada. I tried the cloud widget, it doesn't really work. However, there is a way to create contour plots (this is the main output of my simulator, so I really need it!): your wrapper script (the one called by rappture, which runs the simulator and translates the .xml-data into simulation I/O and back) can start up matplotlib (or even matlab) to generate static images, which than can be hooked up in an <image> widget.

As a side note, nanoHUB "fakes" interactive (mouse-controlled) rotation of e.g. the 3D-field in Quantum Dot Lab. When the user drags the mouse, nanoHUB in the back sends calls to rendering servers which render static images and put it back into the widget.
I believe there is now work on visualizing VTK-files under way.

Create the Tool, follow the nanoHUB process

At this stage you can follow the process on nanoHUB.org to create a new Tool.

• You get a web-accessible "workspace" on nanoHUB.org that is essentially a Debian-Linux installation using the GNOME desktop. You can access this desktop using the internet (it works through a Java applet), but if you are using Linux anyway (like me), you can also simply ssh to nanohub.org.
• You get an SVN repository on nanoHUB.org. It is very convenient to transfer your code from / to nanoHUB.org via this repository. If you don't know what SVN is then I suggest learning about it immediately. I've now ended up using the nanohub repository as the one-and-only place I store my simulator.

Installation of the code on nanoHUB.org

There are some particularities when getting it ready for deployment. Keep in mind: in the end a nanoHUB.org application engineer like Steve Clark must be able to compile your code by typing "make install"! So all the compilation (including your wrapper script etc.) must be automated. If you don't know that a Makefile is, I suggest you quit this page and start learning abut it.

What actually happens when my tool is run by some user?

The tool is started from a temporary directory in ~/data/sessions. Because your tool is not started from the location it was installed you need to make sure that all the paths to executables etc. are hardcoded and not relative. The value of course should in the end be specified by some $PWD or (shell pwd) call in the Makefile, since it will be located in /apps/yourtool and not /home/you/src/!.
Alternatively you can place all your binaries in the bin/ directory of your tool, since this directory will be added to the PATH environment variable and hence the binaries will be found.
(If you have no clue wtf I am talking about then this tutorial is maybe not meant for you...)

Some more requirements

• All source code and the Makefile (and associated files) must be located in the src/ directory.
• Make sure your tool does not rely on environment variables.
• Make sure your tool has good default settings such that a user can just click the "Simulate" button.
• Make sure your tool cleans up after itself, i.e. it deletes the simulation output after it has finished shoveling it into Rappture.
• If you have difficulties getting rid of hardcoded paths in your code, try determining the path by some shell command in the makefile and then handing it over as a preprocessor flas: -DMY_DIR=\"/home/steiger/\".
• Keep in mind: you need to be able and type "make install", and the whole thing needs to configure and compile itself. That includes the platform-dependent settings.

Interaction with nanoHUB.org

No matter how hard you try and how carefully you read all the documentation including this how-to, there will be some point along the process where either you're stuck or you have a setup which is not conforming to the nanoHUB rules. In that case, you can always submit a ticket and it will get replied at some stage. I've had an exchange of about 50 e-mails during the whole process, and you should not feel bad or discouraged by solving problems the old-fashioned way: by talking to people!

Enjoy your Tool