Image RemovedWarning

Stop here for a moment. Make sure you have followed the configuration setup before proceeding any further!

Configuration related tutorial is here -> Click me! <-

 

Quote of the day:
Anything that can go wrong, will go wrong- Murphy's law

 

Image Removed

1. Introduction

This tutorial is designed to introduce the concept of using FC2K tool in order to build Kepler compatible actors.

 

Image Removed

Info
This tutorial explains how to set up codes for FC2K how to build actor using FC2K how to incorporate actor within Kepler workflow

 

4.1.

Kepler is a workflow engine and design platform for analyzing and modeling scientific data. Kepler provides a graphical interface and a library of pre-defined components to enable users to construct scientific workflows which can undertake a wide range of functionality. It is primarily designed to access, analyse, and visualise scientific data but can be used to construct whole programs or run pre-existing simulation codes.

Kepler builds upon the mature Ptolemy II framework, developed at the University of California, Berkeley. Kepler itself is developed and maintained by the cross-project Kepler collaboration.

The main components in a Kepler workflow are actors, which are used in a design (inherited from Ptolemy II) that separates workflow components ("actors") from workflow orchestration ("directors"), making components more easily reusable. Workflows can work at very levels of granularity, from low-level workflows (that explicitly move data around or start and monitor remote jobs, for example) to high-level workflows that interlink complex steps/actors. Actors can be reused to construct more complex actors enabling complex functionality to be encapsulated in easy to use packages. A wide range of actors are available for use and reuse.

1.2. FC2K

FC2K is a tool for wrapping a Fortran or C++ source code into a Kepler actor. Before using it, your physics code should be ITM-compliant (i.e. use CPOs as input/output). After running the ITMv1 script (to properly set up the environment variables), FC2K can be run simply by typing fc2k in the Linux command line. FC2K was developed by ISIP in Java/Python. You can find more regarding FC2K at following location.

2. Requirements for the tutorial

Image Removed

FC2K basics

4.1.

Image Removed

3. FC2K basics

1 What FC2K actually does?

• Generates a Fortran/CPP wrapper, which intermediates between Kepler actor and user code in terms of:
  • reading/writing of in/out physical data (CPO)
  • passing arguments of standard types to/from the actor
• Creates a Kepler actor that:
  • calls a user code
  • provides error handling
  • calls debugger (if run in "debug" mode)
  • calls batch submission commands for MPI based actors

 

Developer guidelines A detailed guidelines and recommendations for code developers could be found here

 

4.1.2 FC2K main window

Fig. 1. FC2K main window

Image Removed

Warning
If you open an existing project, all relative paths defined within project will be relative to a directory within which fc2k was started

 

4.

1.1 Actor description

This group of graphical controls allows to set the description of the actor and its "place" in hierarchy of Kepler elements in Kepler "Component" browser

• Project - defines a branch in Kepler "Component" browser where an actor will be placed
• Name - a user defined name of the actor
• Version - a user defined version of user codes
• Subroutine - A name of user subroutine (Fortran) or function (C++)

 

Image Removed

Warning
A name of user subroutine must be exactly the same as it was defined in user code

 

3.2.2 Environment

The Environment text fields shows UAL and Kepler locations.

• Kepler - Kepler location (usually the same as $KEPLER)
• UAL - UAL location (usually the same as $UAL)

 

Image Removed

Info
Environment settings Both Kepler and UAL locations are originally set to reflect system variables ($KEPLER and $UAL) The change of their values could be made (e.g. for testing purposes), however it is recommended for experienced users only.

 

3.3 "Arguments" tab explained

Below you can find explanation of FC2K arguments tab.

!
Fig. 2. "Arguments" tab

• Type - Defines a type of an argument. It is possible to choose either CPO based type (e.g. equilibrium, topinfo, etc.) or primitive type (e.g. int, long, double, char)
• Single slice - Determines if CPO is passed as single slice or an array. (This setting is valid for CPO types only )
  • if turned ON - Only one slice is passed. An actor will get an additional port to define a time.
  • if turned OFF - An array of all CPOs for given shot run is passed.
• Is array - Determines if a primitive type is passed as a scalar or an array
  • if turned ON - An argument is passed as an array. It requires definition of array size (dynamic array are not supported)
  • if turned OFF - An argument is passed as a scalar.
• Array size - Defines the size of an array of primitive types
• Input - Defines argument as an input
• Output - Defines argument as an output
• Label - User defined name of an argument (and actor port)

 

Restrictions concerning type and order of arguments Arguments specified in this tab must match a type and order of arguments of the routine/function.

Fig. 3. An example of subroutine arguments

Please take a look on a screenshot above:

• equilibrium - an input parameter - one CPO (slice)
• amns - an input parameter - an array of all "amns" CPO slices stored in given shot/run
• integer - an input parameter - a scalar
• double - an input parameter - an array of size 10
• edge - an in/out parameter - single slice of "edge" CPO
• waves - an output parameter - all slices of "waves" CPO

3.4 "Parameters" tab explained

Code specific parameters are all parameters which are specific to the code (like switches, scaling parameters, and parameters for built-in analytical models) as well as parameters to explicitly overrule fields in the ITM data structures.

Fig. 4. "Parameters" tab

• Frequently Used XML - Actual value of the code parameters
• Default XML - Default values of the code parameters
• Schema - A (XSD) XML schema

 

Usage of code parameters For a detailed description concerning the usage of code parameters please take a look at following page Please note that new development made this page slightly deprecated.

 

3.5 "Source" tab explained

Fig. 5. "Source" tab

The purpose of this tab is to define all code related issues:

• a programming language
• utilized compiler,
• type of code execution (sequential of parallel)
• libraries being used

3.5.1 Code description

A user, using this tab, selects programming language of codes provided, compiler used to built library and type of code execution (sequential or parallel)

Fig. 6. "Source" tab - code description

• Type - Defines programming language of user codes. It could be set to:
  • Fortran
  • _C/C++
• Compiler - Defines compiler being used. Possible values:
  • ifort, g95, gfortran
  • gcc, g++
• Parallel MPI - If turned ON uses MPI compilers (mpiifort for ifort, mpif90 for gfortran, mpigxx for C)
• OPENMP - Defined if usage of OpenMP directives is turned ON/OFF
• Batch - If turned ON, submits a user code to jobs queue (combined with Parallel MPI or OPENMP switch runs user code as parallel job)

3.5.2 Libraries

3.5.2.1 "Main library"

A "Main library" field allows to define a path to library containing user subroutine/function.

Fig. 7. "Source" tab - A path to "main" library

Developer guidelines A detailed guidelines and recommendations for code developers could be found here

 

3.5.2.2 "Custom libraries"

"Custom libraries" are non-standard static libraries required for building the user code.

Fig. 8. "Source" tab - A list of "custom" libraries

Available operations on libraries list:

• "Add..." - Adds a new library to the list
• "Edit..." - Edits library path
• "Remove" - Removes a new library from the list

3.5.2.1 "System libraries"

"System libraries" are system libraries handled by pkg-config mechanism and required for building the user code.

Fig. 9. "Source" tab - A list of "system" libraries

A user can:

• add library from the list,
• remove library
• display detailed info (library definition returned by pkg-config mechanism)

Fig. 10. Adding "system" libraries

Hints Tooltips show a detailed info about parameters that would be added to Makefile for selected library "Search" field allows for easy filtering the list of libraries Only ITM libraries (80+) are shown by default. To see a list of all libraries (250+) defined by pkg-config mechanism "List all system libraries" checkbox should be selected. The libraries marked as built for compiler other than currently selected one are filtered out of the list. To turn off this filter unselect appropriate checkbox

 

3.6 "Documentation" tab explained

The "Documentation" tab specifies an user-defined Kepler actor description. It could be displayed from actor pop-up menu.

Fig. 11. "Documentation" tab

4. Incorporating user codes into Kepler using FC2K - exercises

In this part of the tutorial you will learn how to incorporate Fortran and C++ codes into Kepler.
Hands-on exercises show:

• how to prepare C++ codes for FC2K
• how to prepare C++ library
• how set up Makefile
• how start and configure FC2K tool

Image Added

Warning Stop here for a moment. Make sure you have followed the configuration setup before proceeding any further! Configuration related tutorial is here -> Click me! <-   Q

4.1 Embedding Fortran codes into Kepler

Simple Fortran code
In this exercise you will execute simple Fortran code (multiplying input value by two) within Kepler.

Exercise no. 1

Fortran UAL example (CPO handling)

In this exercise you will create Kepler actor that uses UAL.
Exercise no. 2

4.2 Embedding C++ codes

Simple C++ code

Simple C++ code that will be incorporated into Kepler via FC2K tool - addition of one to the value passed into input port of the actor
Exercise no. 3

C++ code within Kepler (CPO)
In this exercise you will create Kepler actor that uses UAL.
Exercise no. 4