We well know that one example is worth a thousand words, therefore, we present you with a handful of examples illustrating various functionalities that can be used in your custom applications. Each of them can be copied and directly used in your workspace, and, later, modified to better suit your research.

Contents of this guide

This guide contains links to sample ready-to-use applications, that will help you understand different possibilities related to custom applications. Each sample application is described presenting the aspects of configuration it shows. The guide contains also an instruction on how to copy and use the sample applications for yourself.   

How to use the examples

Each example contains a link to the sample application within the Application Workbench. After accessing it, you will see a list of its files, where you can browse them (you will not be able to edit them at this point). If you decide you want to test this application in your workspace and later use it as a base for your own codes, use the Fork button in the right upper corner of the page (see Figure 1).   

Note that, to access and fork the sample applications you will have to log in to the Application Workbench first.

Figure 1. Page displaying sample application with Fork button marked

Upon this action, you will be able to decide on the name under which the application will be copied to your account (Repository Name, marked with (1) in Figure 2). You will be also able to add your custom description (Description, marked with (2) in Figure 2). 

Figure 2. Creating a new forked repository

After confirming with the Fork Repository button, your copy of the application repository will be created and presented to you. The copied application will have the same contents, therefore, the view will much resemble the original application (Figure 1). However, notice the change of the user name (the repository name may also be changed if you did that in the previous step) and the information that the repository is forked (marked in Figure 3). The button Fork will also be disabled as you cannot create another fork from a repository that already is a fork. You will also have more controls enabling management of your repository and edition of files.

Figure 3. Forked repository view

Since this moment you will be able to see the application also within My Apps Management tab in EPISODES Platform.

Figure 4. Forked sample application visible in My Apps Management tab within EPISODES Platform

The above means that you will also be able to use the application and run it in your workspace (see also Running your custom application guide) as it will appear within the Applications list in the EPISODES Platform (note, that it will be visible only as long as you are logged in).

Figure 5. Forked sample application visible in Applications list within EPISODES Platform 

Example 1 (Matlab/Octave)

Link to the application: https://epos-apps.grid.cyfronet.pl/tcs-test-user/MatlabSampleApp1

Programming language: the application is written in Octave programming language and configured to be run with Octave interpreter (settings underlined in Figure 6), however, it is also compatible with Matlab programming language and could be run with Matlab interpreter as well.

The application contains a simple code that plots a vector of double-precision numbers and returns it in a form of a PNG file - as demonstrated in Excerpt 1. This, however simple, code, to be correctly interpreted by the EPISODES Platform, requires a configuration, called Application Definition, which will tell the Platform how to transfer the input files to your application and what to do with the output files. Figure 6 shows the configuration used for this application, with input files definition marked with (1): one file of type double_vector, and output files definition marked with (2): one output file of type image_data and name vectorPlot.png, in PNG format. Thanks to this definition the interface of the application within the EPISODES Platform would allow you to add a double_vector file (e.g. a magnitude vector extracted from a Seismic Catalog with Catalog to Vectors converter) as input to the application, and will look for a file vectorPlot.png when the application finishes and transfer it to your workspace, where you will be able to display it - exactly as shown in Figure 7. Note, that if you change your code, so that it produces another file, it will be ignored by the system, unless you add it to the appDefinition.json. Similarly, to add another input to the application, you have to add it both to the application script and to the appDefinition.json file.

Note, that the configuration file presented here is generated by the EPISODES Platform through a dedicated wizard (see also Creating new application guide), therefore, it might be more verbose than necessary, but if you use this wizard, your file will look like this one. In the Application Definition file guide, you can find alternatives to the configuration elements that can make them simpler (and shorter) - an example of this is shown in rectangles in Figure 6 - both of the rectangles represent the same meaning as the part of code marked with (1).

function sampleApp(inVector)

    plot(inVector);
    print('-dpng', 'vectorPlot.png');

end

Excerpt 1. Content of the MatlabSampleApp1 application script

Figure 6. Content of appDefinition.json file from MatlabSampleApp1 application, with most important elements marked

Figure 7. MatlabSampleApp1 displayed and run in workspace with inputs and outputs marked

Example 2 (Matlab/Octave)

Link to the application: https://epos-apps.grid.cyfronet.pl/tcs-test-user/MatlabSampleApp2

Programming language: the application is written in Octave programming language and configured to be run with Octave interpreter, however, it is also compatible with Matlab programming language and could be run with Matlab interpreter as well.

The application contains a simple code that multiplies a vector of double-precision numbers by an (integer) multiplier and returns the resulting vector - demonstrated in Excerpt 2. As with the previous application (and, in fact, any application), along the script we need the Application Definition file to be use it within the EPISODES Platform. Figure 8 shows the configuration used for this application, with input files definition marked with (1): one file of type double_vector, input parameter marked with (2): integer named 'Multiplier' and output files definition marked with (3): one output file of type double_vector (the same as input type) that is returned by the function (will be in Matlab data format). For this configuration, the EPISODES Platform will allow you to add a double_vector file (e.g. a magnitude vector extracted from a Seismic Catalog with Catalog to Vectors converter) as input to the application (similarly as in the previous application), and to specify an input paremeter named Multiplier through the application form. It will also look for a file double_vector.mat (the name is derieved from the output data type) when the application finishes and transfer it to your workspace, where you will be able to display it - as shown in Figure 9. Note, that the result file is displayed using the default visualization for double_vector, therefore, the output is presented as a plot, with possibility to also list the values inside.

function outVector = sampleApp(inVector, multiplier)

    outVector = inVector .* multiplier;

end

Excerpt 2. Content of the MatlabSampleApp2 application script

Figure 8. Content of appDefinition.json file from MatlabSampleApp2 application, with most important elements marked

Figure 9. MatlabSampleApp2 displayed and run in workspace with inputs, form parameters and outputs marked

Example 3 (Python)

Link to the application: https://epos-apps.grid.cyfronet.pl/tcs-test-user/PythonSampleApp

Programming language: the application is written in Python programming language and configured to be run with Python 3 interpreter (settings underlined in Figure 10).

The application presents functionality being a combination of the the two previous examples. It takes an array of numbers, multiplies them by another number (integer) and plots them on a figure that is saved to a file. The Application Definition (appDefinition.json) file defines the input (marked with (1) in Figure 10) and output (marked with (3) in Figure 10) in similar way as in Example 1, and input parameter - as in Example 2. The important difference is that with Python, we are responsible for reading the content of the input file ourselves, whereas with Matlab/Octave, the content of the Matlab data file is automatically loaded to the interpreter context. Due to thie, the input type is text_data as the code for reading text data in Python is much less complex than for reading a Matlab format file (which, nevertheless, possible). 

from numpy import loadtxt
import matplotlib.pyplot as plt

def main(numbers_file, multiplier):

    numbers = loadtxt(numbers_file, comments="#", delimiter=",", unpack=False)
    multiplied_numbers = numbers * multiplier
    plt.figure()
    plt.plot(multiplied_numbers)
    plt.savefig('multiplied_numbers_plot.png')

Excerpt 3. Content of the PythonSampleApp application script

Figure 10. Content of appDefinition.json file from PythonSampleApp application, with most important elements marked

Figure 11. PythonSampleApp displayed and run in workspace with inputs, form parameters and outputs marked


Related Documents

  • No labels


EPISODES Platform is maintained by the TCS AH Consortium. © 2023 IG PAS & ACC Cyfronet AGH