This tutorial will go over how to manually add an application into the simu framework. Note that many of these steps will be automated in the final release.

We will begin by simply getting an application to print hello world, in this case we will use a python script to accomplish this.

Our initial script might look something like this, (NOTE: The #! /bin/python allows it to become an executable using a bash like shell, on windows you can use something like py2exe or cython to accomplish the same thing)

app.py  
#! /bin/python  
  
print('hello world')  

The SimU framework does not get output from stdout though, we must put output into a file called OUTPUT.txt. Everything that is put into OUTPUT.txt must be json, with each individual output on a single line. Currently only 3 types of output are supported (text, img, and html), with more to come. The formats for each are below, remember that the output cannot contain newlines

HTML
{
"type" : "html",
"html" : string,
"required_files" : array  # This is an array of strings that are relative file paths
    # for any file required by the html (i.e., css, javascript,
    # img, …).
}

Text
{
"type" : "text",
"text" : string
}

Image
{
"type" : "img",
"image" : string,  # This is a relative file path to the image you want to display
"width" : int,
"height" : int
}

Back to the example, we need to change our print statement to write to OUTPUT.txt. We will use the json module included in python to make things easier as it has a function to write a dictionary to a json string.

app.py
#! /bin/python
import json

output_dict  = { "type":"html", "html":"<p>hello world</p>" }
with open("OUTPUT.txt", 'a') as out_file:
  json.dump(output_dict, out_file)

(NOTE: For final release, this is about all you will need to know to get an application into the framework, everything from this point on will become more automated)

Now we need to write the configuration file so the framework will know how to execute the application. The config file is written in json, and basically describes execution options and any parameters for your application. The full spec can be found here.

sim.cfg
{
  "cmd" : true,
  "preprocessing": false,
  "postprocessing": false,
  "parameters" : {}
}

Now we have everything required for the script to work with the framework, so how do we add it into website? Every application in SimU is indexed by a UUID (Universally Unique Identifier). The SAM will look in its application library for a directory named by this UUID that contains everything the SAM needs to execute an application. This includes its config file, executables, and any asset files. We need a UUID for our application which can be generated at this online UUID generator. The library is called “packages” and is located in the directory that contains the sam.py script. Make this directory and then place the config file and executable in it. Rename the executable to “application” (note there is no file extension), so you should end up with a file structure that looks something like this:

sam
├── packages
│   ├── d5980e92-875c-4dd9-8b3f-715a364ce060
│   │   ├── application
│   │   └── sim.cfg
└── sam.py

This is good for the SAM side, now we must configure the website to show the application by adding it to the database. This can be done through pgAdmin or SQL statements. First we must add the application to the “website_package” table. You can run the following SQL statement on the database replacing the first value with the UUID you generated, or add the data in manually from within pgAdmin.

INSERT INTO website_package
VALUES ('d5980e92-875c-4dd9-8b3f-715a364ce060', 
        'Hello World', 
        'A hello world example', 
        NULL, 
       false)

This is all you need for this toy example, but most application will require parameters. Lets extend our hello world app to instead say hello . Starting with the python script, we need to get the first argument and print it out.

app.py
#! /bin/python
import json
import sys

output_dict  = { "type":"html", "html":"<p>hello {0}</p>".format(sys.argv[1]) }
with open("OUTPUT.txt", 'a') as out_file:
  json.dump(output_dict, out_file)

Now the first positional argument is printed instead of world. We need to add this parameter to the sim.cfg so the SAM know about it when it executes the application. Each parameter requires a few bits of information. First we need a label for the parameter so it can be identified. It also has a type, a flag, and a order. Since this argument is position, we will leave the flag blank.

sim.cfg
{
  "cmd" : true,
  "preprocessing": false,
  "postprocessing": false,
  "save_data": false,
  "params" : {
    "name" : {
      "type" : "str",
      "flag" : "",
      "order" : 1
  }
}

Remember to put these files into the package directory again if you did not already do so.