sudoku - 24leesten/SimU-Wiki GitHub Wiki

Please read the Adding an application to the SimU framework tutorial before starting this guide. This guide is meant to show a few of the aspects of adding a package to SimU that were not covered in the former guide.

In this tutorial we will add the Sudoku Solver to the SimU framework. All the needed code and files can be found on this git repository.

The first thing to note is that this java application already outputs everything to OUTPUT.txt correctly. There are 3 files that you will need to download to your computer from the git repository to get this application running:

  • sudoku.jar: The executable jar file
  • css/sudoku.css: The css to display the results
  • res/test.csv (This file is necessary unless you want to create your own)

The first thing you will want to do is create the folder for your package ation in packages. You can use this UUID generator in order to generate the uuid for your package.

In your package folder create two files:

  • assets
  • src

Place the sudoku.jar file in your src folder and the sudoku.css file in your assets folder.

Now you need to create your simulation file. Since an executable jar file is called using a java command it is easier to create a small wrapper script to run the sudoku solver. Your script should look something like the following:

simulation
#!/bin/python
import os
import sys

print("running")
cmd = "java -jar src/sudoku.jar " + sys.argv[1]
os.system(cmd)

This file will take in the parameter that we will define later. It will then plug in that parameter to the command line argument and call it.

Note: Java and Python must be working on your SAM server. You may also need to add execute permissions to the file.

You may be wondering what the sudoku.css file is. This is the css that will format your html when you display it after the simulation has run. You may recall that when sending HTML across a network the json will look something like this:

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, …).
}

In our situation the required files line will read:

"required_files" : ["sudoku.css"]

Note: You the json is already generated for this example. The above is just to demonstrate how it is done.

Now we need to create the config file. Remember 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. In this example the only thing we need to do is add a parameter. To do this we add the parameter to the appropriate section. It will look like this:

sim.cfg
{
  "cmd" : true,
  "preprocessing": false,
  "postprocessing": true,
  "save_data": false,
  "pre_params" : {
    "outfile" : {
      "type" : "str",
      "flag" : "-o",
      "order" : 1
    }
  },
  "params":{
    "filename": {
    "type": "file",
    "flag": "",
    "order": 1
    }
  }
}

Next we must add the parameter to the website database as well so it will show in the form. To do this you will need to interact with a few tables. These are the tables we will be interacting with:

  • Package
  • Parameter
  • Option
  • OptionChildParameter

To add the relevant information to the database you will either need admin access to your SimU Site or you will need to be able to access the database directly for your SimU site. This tutorial assumes you have admin access and will walk you through the necessary steps using the admin site.

Once you have logged in as admin click on your name/email. In the drop down you will see a link to the admin site. Click on it. Once you are in the admin site you will have access to all the tables you need to edit.

The Package table is the table that houses the main information for the Simulation you are trying to upload. All you truly need to add to this table are:

  • id (UUID)
    • The simulation UUID you got earlier
  • label (str)
    • "Sudoku"
  • public (boolean)
    • TRUE or FALSE

NOTE: Here is the SQL command if you want to do it that way. Don't forget to replace the UUID:

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

The next table you will have to add to is Parameter. This table tells what parameters your simulation requires. Here the the required values are:

  • name (str)
    • "csv_file"
  • type (str)
    • "FLE"
  • required (boolean)
    • TRUE
  • display_order (int)
    • 1
  • package_id (UUID)
    • the UUID of the Sudoku simulation
  • label
    • "CSV File"

NOTE: Here is the SQL command if you want to do it that way. Don't forget to replace the UUID:

INSERT INTO website_parameter
VALUES ('csv_file', 
        'FLE', 
        true, 
        NULL, 
        1,
        NULL,
        NULL,
        NULL,
        'd5980e92-875c-4dd9-8b3f-715a364ce060',
        'CSV File',
        NULL,
        NULL,
        NULL)

The other two tables are not actually needed for this simulation. Once you have added this information to the database you should be good to go.