Wrapping a Simulator:

In order to import a simulator, the files below are necessary. These files are presented in the recommended order to be written, except for the output_schema.json and parse.py. They are suggested to be written at the same time.

• input_schema.json
• config.py
• build.sh
• object.json
• launch.py
• output_schema.json
• parse.py

Input_schema.json

The input_schema.json will be used in the creation of the simulator web form. This JSON script should contain JSON objects for variables that the user has the opportunity to change (e.g. command line functions, options in the configure file, etc). Each JSON object should contain an object name that can be used or manipulated easily later when writing the config.py file and the following subschemas: “type”, “default”, “label”, and “description”. The default value can be the default in the configure file or any other default value deemed appropriate. Other possible subschemas are “validations” or “enables”. The “validations” subschema is an array that should be used if a certain input must be something like 0 to 1 or a power of two. The “enables” subschema says that if the given key “is” a certain value show another “key” as in the example below:

"model_type": {
    "type": ["block", "grid"],
    "default": "block",
    "label": "Themal Model",
    "description": "Which mode to use. Block is faster, but grid is more accurate.",
    "enables": {
        "key": "secondary_path",
        "is": "grid"
    }
}

This says that if the object “model_type” is set to “grid”, then show “secondary_path”. That way a user cannot manipulate values that are irrelevant or should be set to certain values with a given key value. Examples of these files can be found in the HotSpot Simulator and DramSim2. The HotSpot input_schema.json is a collection of the command line values given in the How-To Documentation here and the options given in the hotspot.config file. ##Config.py The config.py is a Python script to parse the input.json (output file of the web forum) and write the values into the configure file that the simulator uses. The configure file should be written with the same format and order as the default configure file but with the user’s values unless the simulator can handle a difference in format and order. ##Build.sh The build.sh is a unix shell script which should make the simulator, make any other necessary files, and move through directories when necessary. This is used in the object.json. ##Object.json The object.json is a JSON script should contain all objects necessary to install, build, and run the simulator along with descriptive information of the simulator. It should contain at least the following of the simulator: name, type, installation (type of file installed, website to install, and necessary schemas to turn it into a package or array of packages), build (base type, script from which to build, and language of build script), run (script from which to run, language of run script, and version of the language), official website, description, authors, organization, license, and tags. Other possible schemas are benchmarks, documentation website, and citations. A basic template for the object.json is given below where [] should be replaced by quotes surrounding the object(s) described between the brackets.

{
    "name": [simulator name],
    "type": "simulator",
    "install": {
        [type of file the simulator is downloaded in]: [website url from which the simulator can be installed]
        [values to turn this into one package or an array of packages]
    },
    "build": {
        "using": "ubuntu-base-2014-06",
        "script": "build.sh",
        "language": "bash"
    },
    "run":  {
    },
    "configurations": [
        "name": "Options",
        "schema": "input_schema.json",
        "file": "input.json"
    ],
    "website": [official website url],
    "description": [short description],
    "authors": [array of authors names],
    "organization": [name of organization who created or supports simulator],
    "license": [license],
    "tags": [array of keywords relevant to the simulator]
}

##Launch.py The launch.py is the Python script that reads the command line options from the user’s input (in input.json), aggregates them into a command, runs the simulator with the aggregated command, writes the output of the program to output.raw, and then runs parse.py with the directory of the output.raw file. This script should find the paths for all files determined by the user that is relevant for the command-line options. ##Output_schema.json The output_schema.json will be used in parsing the output (in output.raw) of the simulator and be used by parse.py to display the output to the user on the web. This JSON script should contain JSON objects for all the different results in the simulator. Each JSON object should contain an object name that can be used or easily created later in parse.py when reading from the output file and parsing it to the output.json and should also contain the following subschemas: “type”, and “units”. The output file of output.raw will be the same as the output of the simulator, just outputted to a file instead of the screen. ##Parse.py The parse.py is a Python script which parses the output (in output.raw) of the simulator and writes it into output.json so that it can be displayed on the web. Basically, the best way to do this is the following:

• create an empty dictionary
• read line by line through the data to gather appropriate keys and their values
• manipulate the data names so that they are the same as the output_schema.json keys names
• store the output.raw values into the given dictionary with the index of the key value, creating the index where necessary
• write this all into output.json, by JSON dumping the dictionary into the file

If need be, the script should read through subschemas. It is necessary to look at the format of the output to parse it into a dictionary.

#Testing the Files

##Input_schema.json * occam new command generates an input.json from the default values and will give syntax error messages. Note: Occam commands require installation of occam-worker. * Importing into the Occam Web, creating a Work Set and running it (see below). Check that the web form looks as intended. Also, play with default values to ensure that the input_schema.json has the correct validations and types. A red box will appear around the values which fail validation and it will stay on the page. Config.py * Obtaining an input.json from the occam new command and running config.py through python. Ensure that the file outputted by config.py matches the file that is used to configure the simulator. (It should be an exact match unless the simulator can handle differences.) The new input.json can be renamed to the simulators configure file and tested by running the simulator. If the simulator gives errors, the input_schema.json or config.py needs to be changed to fix them. ##Build.sh * Executing the shell script: sh build.sh and checking that an instance of the simulator has been built where expected. * occam build can also test build.sh, but requires a working object.json and occam install command prior to the command. Note: Occam commands require installation of occam-worker. ##Object.json * Using the different Occam commands to test the different parts: occam install tests the “install” key, occam build tests the “build” key, and occam run tests the “run” key. note: Occam commands require an installation of occam-worker. ##Launch.py * Execute the python script, however, it requires an input.json (obtainable through command occam new), working config.py. The running of the parse.py can be commented out and the output.raw should look like the output generated by the simulator. ##Parse.py * Execute the python script. It requires output.raw file. It will output to the output.json which should have all the values the user will view. ##Output_schema.json * Importing into the Occam Web, creating a Work Set and running it (see below). Then view the results. Check that the Results web form looks as intended.