This document contains a description of files that can or should be present in an Application Workbench. Note that instead of preparing the files manually you can also use a dedicated application creation wizard that is available on the EPISODES platform.

Application Definition (Required)

A JSON file (see this documentation for more information on JSON format) named appDefinition.json. Specifies inputs and outputs of the application and how the application should be run.

Options

 

* If a field is marked as 'Optional' it means that it doesn't have to be present in the file

Sample file

{
  "scriptLanguage":"MATLAB",
  "executableScriptName":"sampleScriptName.m",
  "functionName":"sampleScriptName",
  "inputFiles":[
    {
      "dataType":"double_vector",
      "multiplicity":"1",
      "typeLabel": "label"
    }
  ],
  "inputParameters":[
    "DOUBLE",
    "TEXT"
  ],
  "outputs":[
    {
      "dataType":"double_vector",
      "fileName":"output.mat"
    }
  ],
  "requiredComputationResources":{
    "COMPUTATION_TIME":5
  },
  "requiredTools":[
    "octave"
  ]
}

Data Types

The data type field that is present in input and output definition must contain a name of one of predefined data types. It is important that the name is written in exactly the same way as it is in the predefined data type. You can check the possible data types in the upload file form in the platform, or you can contact us. The most commons types are: 

Executable Script (Required)

The main script of the application that is the entry point of the application. The name of the script file should be the same as executableScriptName defined in the application definition file and the script should contain a function that has the same name as the functionName. The main function should have the same number of inputs and outputs as defined in the application definition file. The names of the input and output variables are irrelevant. For example, if the application definition contains:

"functionName": "sampleFunctionName",
"inputParameters": ["TEXT", "DOUBLE"],
"inputFiles": [{ "dataType" : "integer_vector", "multiplicity" : "1"},  { "dataType" : "string_vector", "multiplicity" : "1"}],
"outputs": [{ "dataType" : "double_vector", "fileName" : "output1.mat"},  { "dataType" : "boolean_vector", "fileName" : "output2.mat"}]

the executable script could look like that:

function [outputDoubleValues, outputBooleanValues] = sampleFunctionName(intValues, stringValues, text, multiplicator)
  outputDoubleValues = double(intValues) * multiplicator;
  outputBooleanValues = strcmp(stringValues, text);
end

The order of inputs and outputs corresponds to the order in which they are defined in the application definition file, with the note that inputFiles variables come before inputParameters variables. For the above example the order of variables would be as follows:

Handling custom multiplicity in input files

Depending on what multiplicity is given, the input(s) might be passed to the main function in a different way. In the example above, all input files had multiplicity defined as "1" (default) - in such case, each file is read to a MATLAB variable which is passed directly as argument to the main function. If the multiplicity is set to any other value, all the files provided by the user for this input are read to MATLAB variables and packed into a single cell array before being passed as argument to the main function. For example, if the function has one input of type double_vector and multiplicity set to "*" and there are 3 input files, the function will receive a cell array containing three double vectors. If, however there are no input files present, an empty cell array will be passed. The variables in the cell array are not guaranteed to be in any specific order. This is done by design, inputs of the same data type and non-singular multiplicity are undistinguishable from each other. If you need to have a few inputs with the same data type, and you need to be able to distinguish between them use typeLabel instead.  

Application Description (Optional)

A JSON file (see this documentation for more information on JSON format) named appDescription.json. Defines how the application will be described in the Applications page inside the EPISODES platform, and how a workspace directory will be named when the application is created. This file is optional - if it is not present the required fields - shortName and name - will be filled with the name of the repository, and all other fields will be left empty.

Options

Sample file

{
  "shortName":"AppDir",
  "references":{
    "User Guide":"https://docs.cyfronet.pl/pages/viewpage.action?pageId=somepage"
  },
  "lastUpdate":"28-02-2021 20:50:12",
  "categories":[
    "Category"
  ],
  "keywords":[
    "keyword1",
    "keyword2"
  ],
  "name":"Application name",
  "description":"Longer description containing some ${D__data_types} and <a href='#app:AppId'>links</a>.",
  "license":"Sample licence",
  "author":"Sample author",
  "citation":"Sample citations",
  "inputsDescription":"${D__data_type}",
  "resultsDescription":"${D__other_data_type}",
  "computationalCharacteristic":"Description of computational characteristic"
}

Other Files

You are free to add any other files to the repository if you wish. You can, for example, include additional script files to help better organize the code, or you can add some supplementary files like a readme or a license file.