Page History
Info | ||
---|---|---|
| ||
Each custom application is represented by a GIT repository stored in Application Workbench. To connect to the EPISODES Platform correctly, there are some requirements imposed on the contents of the repository, that ensure we can interpret, display and run the application correctly. |
Configuration files
In order to create an application that can be integrated with the EPISODES Platform, you have to properly prepare it's files. The files are stored in a dedicated repository within the Application Workbench, which can be created either manually or by using a dedicated wizard provided by the EPISODES Platform (for more information on creating such a repository see Creating New Application guide). The files should contain an Application Definition file, which is a mandatory descriptor that tells the EPISODES Platform how to display and execute the application, as well as any number of Application code files. Additionally, an Application Description file can be present in the repository, to enhance the display of the application within the EPISODES Platform. Other supplementary files, like a readme or a license file can also be added.
The following pages contain detailed information on the above mentioned files configuration and placement:
Children Display |
---|
Validation
Anchor | ||||
---|---|---|---|---|
|
To check the application configuration, you may use the validation provided by the EPISODES Platform. For this purpose, use the Validate option for your application in the My Apps Management tab (marked in Figure 1).
Figure 1. My Apps Management view within EPISODES Platform with Validate option marked
The validation checks the existence and structure of the Application Definition file, the existence of the script file declared as executableScriptName within the Application Definition file, and the structure of the Application Description file (if it is present). Note, that the code files contents are not checked, only the consistency of the files with the application definition is.
The result of the check is displayed in a popup window - if the configuration is correct, the result will be similar to Figure 2, otherwise the invalid components will be marked in red or grey (if the file is absent and not required). See the Common Issues guide for examples of validation errors.
Figure 2. Result of validation - valid configuration
Note, that apart from the main version of the application, you can also check any branch or tag that was created, by selecting another revision from the Select version drop-down menu
Related Documents
Content by Label | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
This document contains a description of files that can or should be present in an application repository. Note that instead of preparing the files manually you can also use a dedicated application creation wizard that is available on the EPISODES platform.
Table of Contents | ||
---|---|---|
|
Application Definition (Required)
A JSON file named appDefinition.json. Specifies inputs and outputs of the application and how the application should be run.
Options
- scriptLanguage - name of the scripting language in which the application is written. Currently only one language is available:
- MATLAB - MATLAB programming language. This applies also to Octave applications
- executableScriptName - name of the application executable file
- functionName - name of main function used to execute the application
- inputFiles (Optional) - input files that are needed by the application. For each input file defined here, the application panel will show a button to choose the location of that file. When the application is run the input files will be read into a MATLAB variable and passed as arguments to the main executable function. The order in which the inputs are passed to the function is described in Executable Script section. Each input file is defined by:
- dataType - data type of the input (see Data Types section below)
- typeLabel (Optional) - a name distinguishing this input file from others. Allows to have multiple input files with the same data type. Each input file with different type label will be treated as a separate input and be passed to the main function as a separate argument
- multiplicity - how many inputs of that type are expected (written as string value). Defines minimum required number and maximum allowed number of inputs. The portal validates if the user selected the minimal required number of input files, and if not it will forbid the application from being run. Depending on what multiplicity is given the input(s) might be passed to the main function in a different way (see Input Multiplicity section). The possible values are:
- ? - zero or one. The input is optional, there can be at most one input file
- * - zero or more. The input is optional and there is no upper limit of how many input files there can be
- + - one or more. At least one file is required and there is no upper limit of how many input files there can be
- n - exactly n input files are expected - no more, no less
- [n, m] - there should be at least n input files and at most m input files
- inputParameters (Optional) - simple input parameters that should be entered by the user. For each parameter defined here, the application panel will show input form where the user can enter the value of the parameter. When the application is run, the parameters' values will be passed as arguments to the main executable function. The order in which the parameters are passed to the function is described in Executable Script section. When adding a parameter you have to specify what kind of value it should have. The available options are:
- TEXT - a text value
- BOOLEAN - a true or false value
- DOUBLE - a real number value
- INTEGER - an integer value
- TIME - a date value
Thats how the input paramters will look like when they are presented as input forms in the application panel:
- outputs - list of outputs generated by the application. The outputs defined here should be returned as output variables by the main executable function. After the function is run each of these outputs will be saved as a mat file and returned as a result of the application. Each output is defined by:
- dataType - data type that this output file should have (see Data Types section below)
- fileName - name of the file under which this output should be saved
- requiredTools - list of programs or tools that are needed to run the application. At least one value should be present - the script interpreter. Please contact us if you need any other tools, or toolboxes, or if you require a specific version of a Matlab or Octave interpreter. Available options are:
- matlab - the MATLAB interpreter. By default one of these versions will be used: 2019b or 2021a (this is subject to change).
- matlab-signal_processing_toolbox - signal processing toolbox. Usable only with MATLAB
- matlab-image_processing_toolbox - image processing toolbox. Usable only with MATLAB
- octave - the Octave interpreter. By default one of these versions will be used: 3.8.1 or 4.2.1 (this is subject to change)
- requiredComputationResources (Optional) - a map defining what computational resources should be available to the application. Available options are:
- COMPUTATION_TIME - maximum time that an application needs for the computation (in minutes). If not specified it defaults to 30 minutes
- MEMORY - maximum memory that an application needs for the computation (in gigabytes). If not specified it defaults to 2GB
- CPU_COUNT - number of processors that should be available to the application. If not specified it defaults to 1
Sample file
Code Block | ||
---|---|---|
| ||
{
"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"
]
} |
Optional Fields
If a field is marked as 'Optional' it means that it doesn't have to be present in the file. For example, the above example without any optional fields would like like this:
Code Block | ||
---|---|---|
| ||
{
"scriptLanguage":"MATLAB",
"executableScriptName":"sampleScriptName.m",
"functionName":"sampleScriptName",
"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. The most commons types are:
- double_vector - a vector of real number values
- time_vector - a vector of date values
- integer_vector - a vector of integer values
- boolean_vector - a vector of boolean values
- string_vector - a vector of text values
- catalog - a seismic catalog
- seed - a SEED file
- fullseed - a SEED file containing both data records and station information
- miniseed - a SEED file that contains only data record
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:
Code Block | ||
---|---|---|
| ||
"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:
Code Block |
---|
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:
- intValues - corresponds to the input file with type 'integer_vector'
- stringValues - corresponds to the input file with type 'string_vector'
- text - corresponds to the input parameter with type TEXT
- multiplicator - corresponds to the input parameter with type DOUBLE
- outputDoubleValues - corresponds to the output with type 'double_vector'
- outputBooleanValues - corresponds to the output with type 'boolean_vector'
Input Multiplicity
Depending on what multiplicity is given the input(s) might be passed to the main function in a different way:
- multiplicity is set to exactly one input file - when the application is run, this file will be read to a MATLAB variable and this variable will be passed directly as argument to the main function
- any other multiplicity - when the application is run, these files will be read to MATLAB variables and they will packed into a single cell array before it will be passed as argument to the main function.
- 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 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
- shortName (Required) - short name of the application. The short name will be used for creating application directory within the workspace. It is not recommended to include special characters in the application name, some of them are not allowed
- lastUpdate - a date when the application was last updated, written In format "dd-MM-yyyy HH:mm:ss"
- references - links to additional resources that can be displayed with the application (e.g. user guide). It is a map where the key will be the text of the link and the value will be its web address (URL)
- categories - categories to which the application can be assigned. It is advisable to use the categories already present within the portal. However, you can also add your own
- keywords - keywords that match the application. If relevant, use the keywords already defined within the portal, but add also your own, to describe the application best
- hidden - if this application should be visible in the EPISODES platform
- translations - a map that contains translations of descriptions that are subject to internationalization. The key of the map is the language of the translation written as a two letter language code, e.g. "en", or "pl" and the value contains the translated descriptions written in that language. There should be at least one language present - "en". The available description fields are:
- name (Required) - full name of the application, that will be visible on the application list. May contain spaces.
- description - longer description of the application. May contain HTML tags, including links. May also include the input or output type name written as ${D__data_type}, where "data_type" is the data type of the input or output file - this will be filled with a full name of this data type that will be automatically translated into an appropriate language (if that translation is available)
- license - license used for publishing the application. If you wish your application to be open to other users, include a license here. You might also include it as a LICENCE.txt file in your code repository
- author - author of the application, may contain your name, institution and/or project affiliation.
- citation - citations (articles) related to the application (e.g. the algorithms it uses). A generic portal and its application part is added to the citations, therefore, include here only citations related solely to this application.
- inputsDescription - description of the application inputs. May contain HTML tags, including links. By default it should include listing of the types of inputs, but adding more detailed description is advisable. Input types should be written as ${D__data_type}, where "data_type" is the data type of the input file
- resultsDescription - description of the application results. May contain HTML tags, including links. By default it should include listing of the types of outputs, but adding more detailed description is advisable. Output types should be written as ${D__data_type}, where "data_type" is the data type of the output file
- computationalCharacteristic - description of the features of the application that might have impact on its computation time or other resources consumption.
Sample file
Code Block | ||
---|---|---|
| ||
{
"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"
],
"hidden":false,
"translations":{
"en":{
"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"
},
"pl":{
"name":"Aplikacja",
"description":"Dłuższy opis z ${D__data_types} i <a href='#app:AppId'>linkiem</a>.",
"license":"Licencja",
"author":"Autor",
"citation":"Rerefencje do artykułów",
"inputsDescription":"${D__data_type}",
"resultsDescription":"${D__other_data_type}",
"computationalCharacteristic":"Opis charakterystyki obliczeniowej"
}
}
} |
Other Files
...