How to create MatLab Extensions
1. Introduction
Using Extensions is the most simple way to add new functionalities to GraphTea. GraphTea itself is written by Java language, but it is possible to write extensions for it with another languages including MatLab.
After reading this article you will be able to create a Graph Report extension using MatLab.
2. How it works?
Adding MatLab extensions to GraphTea is so simple and is done in a similar way to another extension. You write your extenion in a ".m" MatLab file and put it in extensions directory. On starting, GraphTea will load your file into a standard Report extension, and it will be shown on Reports Sidebar. When user wants to calculate the report value, GraphTea will open a MatLab engine and calculate your ".m" file giving it, its desired inputs; and after that GraphTea will show the calculated result to the user. So the only thing you should do is to put your ".m" file in "extensions directory", and give GraphTea some information about the arguments of your function and so on.
3. A Sample MatLab Extension
This is a Sample MatLab Extension:
helloWorld.m:
% description: Hello Description % args: num_of_vertices() , @java.lang.Integer k = 5 function y=helloWorld(n,x) y=n+x;
The first line of your file MUST start with "% description: ", Other wise GraphTea will not consider your file as a MatLab extension. The text after (Hello Description) will provide a decription of what your extension does. Write there a brief description of your extension.
If you write description line properly, GraphTea will assume your file as a MatLab report extension. The extension name will be your file name ("helloWorld"), and when it wants to calculate your report it will open a MatLab engine, change the workspace directory to the directory of your extension and call a the file name as a function ("helloWorld(n,x)"). So if yout file name is "xxx.m" your extension name will be "xxx" and you should create a function in your file named "xxx(...)".
Your reports will need some information about current editing graph to do the calculations based on. GraphTea provides a simple way to give your extensions its necessary information. First of all you add them as your function parameters ("n,x"), Then you should tell GraphTea about the type of parameters, and the way they can be filled.
The second line is the args line. is starts with "% args: " and after that the the descriptions of your function arguments one by one. You can use two types of arguments.
1. Automatically filled arguments:
These arguments are automatically filled and passed to your function and GraphTea will not see them at all. For example you may want to have incidence matrix of currently editing graph as a parameter. These parameters are filled using GraphTea Shell. You write a shell command as a description and GraphTea will execute it each time it wants to run your extension and puts the result of command in your argument. here "num_of_vertices()" is a shell command which returns the number of graph verticecs.
Running num_of_vertices() as a Shell command
You can put every shell command as argument descriptor. There are 2 methods that would help you alot:
weighted_matrix(): will generate a MatLab styled weighted incidence matrix of edges.
bsh % print(weighted_matrix()); [ 0 , 0 , 1 ; 0 , 0 , 0 ; 1 , 0 , 0 ]
matlab_matrix(): will generate the incidence matrix.
You can also define your own shell command to use as arguments.
2. User Arguments:
These arguments are filled by user. For example you may want to create an extension which calculates the number of vertices which degree is equal to "k". So k will not have a fixed value. One time user may wants to know the number of vertices with degree 1 (i.e. the number of tree leafs) and another time he may wants to know the number of vertices with degree 2. These arguments are known as User Arguments. The argument descryptor should be in this form:
@type name = dafault value
Type represents the argument type. It should be a java class name (Including package name) , (here: "java.lang.Integer"). As you may not know much about java language you can use following types blindly as your type ;)
java.lang.Integer -> when your argument is an Integer (like 1 , 2, 3, -1 ,-100 ,...)
java.lang.double -> when your argument is a Double (like 1.1, -45.324, ...)
java.lang.Boolean -> when your argument is a Boolean (True, False)
java.lang.String -> when your argument is a String ("Hi there", "message...")
name represents the name of your arguments which will be shown to the user (here "k"). Choose a small, brief and descriptive name for your argument.
default value represents the default value of your argument. (here "5").
User arguments are similar to parameters of extensions, (you can read about them in: create your first extension), So they will be added to prameter window like this:
The Parameter window, parameter name is "k" and its default value is "5"
read more about it in: What is Reports
3. Last Notes
1.There is a MatLab extension which calculates the network flow in a graph. it is located in extensions\graphtea\extensions\networkFlow.m. It may help you to understand the MatLab Extensions better!
2. GraphTea will create a shell command for your MatLab Extensions. It's name will be the same of your extension name, and it's parameters are consisted of your extension's User Arguments. So if you are familiar with java programming language, you can use your extension directly from shell to perform more complicated calculations.
running a command in shell
4. Farther Reading