1. 4.1. FC2K basics

1.1. 4.1.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

1.2. 4.1.2 FC2K main window

Fig. 1. FC2K main window

1.2.1. 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++)

1.2.2. 4.1.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)

1.2.3. 4.1.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)

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

1.2.4. 4.1.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

1.2.5. 4.1.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

1.2.5.1. 4.1.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)

1.2.5.2. 4.1.5.2 Libraries

1.2.5.2.1.1. 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

1.2.5.2.2. 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

1.2.5.2.3. 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

1.2.6. 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

2. 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

2.1. 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

2.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