PREVIOUS: Building the Dummy Program

Making an Object Runnable

The final step in wrapping our program, is to tell OCCAM how to run it.

Create a launch file

This process is somewhat more complex than building, since you would need knowledge on how OCCAM processes experiments internally. This tutorial will not focus on those details, therefore we provide you with a helper file and a ready to run launch script, which we will briefly explain.

Download these files and place them inside the ~/occam_workspace/simulator-ExampleSim directory.

The launch file

The lauch file obtains information from OCCAM about the experiment currently being run. For our program, we will focus on three items: 1. The input files 2. The configuration files 3. The output files

The first thing the launch script does is load all the information from OCCAM (using the helper file) and sets up some information about the directories:

import os
import json
from occam import Occam

# Load OCCAM information
object = Occam.load()
# Gather paths
scripts_path    = os.path.dirname(__file__)
job_path        = os.getcwd()
object_path = "/occam/%s-%s" % (object.id(), object.revision())

Then, it sets the path to the dummy program executable:

# Path to your executable
executable_path="dummy_program/dummy"

Note: If you use another executable path, or are wrapping your own program, then change this line to reflect your program!

In the next section, the script gets the configuration options. The configuration is automatically generated by OCCAM imediately before running the object.

input_configurations_path = object.configuration_file("Configuration Options")

After the configuration file, the script checks if there is an input file to the OCCAM object and sets the input_file_path variable with its path. If there is no input file in the workflow (experiment), then the program will use a default (the input.txt we used before).

# Set default input file
default_input_file_path="dummy_program/input.txt"
input_file_path=os.path.join(object_path,default_input_file_path)
inputs = object.inputs()
if len(inputs) > 0:
    files = inputs[0].files()
    if len(files) > 0:
        input_file_path = inputs[0].files()[0]

Note: If you want to change the default input file change the first line on this section.

The script then defines where the output file should be created - as defined in the object description file (object.json).

# Output file dir and path
output_dir_path="new_output"
output_file_path=os.path.join(output_dir_path,"statistics.json")
# Create dir and set full path
output_dir_full_path = os.path.join(object.path(), output_dir_path)
if not os.path.exists(output_dir_full_path):
    os.mkdir(output_dir_full_path);
output_full_path = os.path.join(object.path(), output_file_path)

And finally tells OCCAM how to run the program.

executable=os.path.join(object_path,executable_path)
args=[
    executable,
    input_file_path,
    input_configurations_path,
    output_full_path
]
command = ' '.join(args)
Occam.report(command)

Add the run information to the object description file

Similarly to the build process, we need to add the run information to the object description file (object.json):

"run": {
    "script": "launch.py",
    "version": "3.3.0",
    "language": "python"
}    

Note that because the architecture and the environment information was added before, we don't need to add it again. However, this information is required to run an object.

Your full object description file (object.json) should look like this:

{
    "type": "simulator",
    "id": "95fdb476-8984-11e6-8e21-1c1b0d0a9044",
    "name": "ExampleSim",
    "configurations": [
        {
            "schema": "config_schema.json",
            "file": "input.json",
            "name": "Configuration Options"
        }
    ],
    "inputs": [
        {
            "type": "volume"
        }
    ],
    "outputs": [
        {
            "createIn": "new_output",
            "file": "statistics.json",
            "schema": "output_schema.json",
            "type": "application/json"
        }
    ],
    "architecture": "x86-64",
    "environment": "ubuntu:14.04",
    "build": {
        "script": "build.sh",
        "language": "bash"
    },
    "run": {
        "script": "launch.py",
        "version": "3.3.0",
        "language": "python"
    }    
}

Commit the new revision

Now we can commit the new revision of the object.

$ git add object.json
$ git add launch.py
$ git add occam.py
$ git commit -am "Object can run now"
$ occam commit

Build the new object revision

Since we have commited a new revision, we need to build it.

$ occam build

Running an experiment

The wrapper around our program is ready, however, we still need a volume to input into object. We will now create such volume, and run an experiment with our object.

Creating a new volume

First lets create the volume:

$ cd ~/occam_workspace
$ occam new volume ExampleVol

$ cd volume-ExampleVol
$ touch obj_input.txt

Edit the file with your favourite editor adding some text to it, e.g.:

This is the input file in volume ExampleVol.
If all goes right this should be printed!

Now commit your changes.

$ git add obj_input.txt
$ git commit -am "Added a file to the volume"
$ occam commit

Note: Since there is no build to be done, the volume is ready to be used!

Setting up the experiment

Go to your OCCAM web interface and create a new experiment.

Attach the ExampleSim object to the workflow. Then, click the plus sign behind the object, and add the ExampleVol object.

On the ExampleVol configuration pane, check the obj_input.txt file and click update on the bottom of the page. Then, configure the ExampleSim object as you please and click Update on the bottom of the page.

Note: Clicking Update is required to submit your changes into the experiment!

Finally, run the experiment. When the run finishes, check the output for the contents of the input file. Once you have found them, refresh the webpage in order to be able to check the outputs.