Versions Compared

Old Version 12

changes.mady.by.user Bartosz Palak

Saved on

compared with

New Version 13

changes.mady.by.user Bartosz Palak

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

Children Display

 

Table of contents
Table of Contents

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

 

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. FC2K basics

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 (IDS)
    • 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

 

Info

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

 

 

4.1.2 FC2K main window

Image Removed

Fig. 1. FC2K main window
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.3 Actor description

 Image Removed

Fig. 2. FC2K actor description

...

...

 

...

 

Warning

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

 

4

...

.

...

Image Removed

Fig. 3. FC2K environment tab

...

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

 

Info

Environment settings

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

 

4.1.5 "Arguments" tab explained

Below you can find explanation of FC2K arguments tab.

Image Removed
Fig. 4. "Arguments" tab
  • Type - Defines a type of an argument. It is possible to choose either IDS based type (e.g. equilibrium, topinfo, etc.) or primitive type (e.g. int, long, double, char)
  • Single slice - Determines if IDS is passed as single slice or an array. (This setting is valid for IDS types only )
    • if turned ON - Only one slice is passed. An actor will get an additional port to define a time.
    • if turned OFF - All IDSes 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)

 

Warning

Restrictions concerning type and order of arguments

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

Image Removed

Fig. 5. An example of subroutine arguments

Please take a look on a screenshot above:

  • equilibrium - an input parameter - one IDS (slice)
  • amns - an input parameter - all amns IDS 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" IDS
  • waves - an output parameter - all slices of "waves" IDS

4.1.6 "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 IDS data structures.

Image Removed

Fig. 6. "Parameters" tab
  • Frequently Used XML - Actual value of the code parameters
  • Default XML - Default values of the code parameters
  • Schema - A (XSD) XML schema

 

Info

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

 

4.1.7 "Source" tab explained

Image Removed

Fig. 7. "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

4.1.7.1 Libraries

"Main library"

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

Image Removed

Fig. 8. "Source" tab - A path to "main" and "optional" library
"Optional library"

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

 

"Custom libraries"

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

Image Removed

Fig. 9. "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
"System libraries"

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

Image Removed

Fig. 10. "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)

Image Removed

Fig. 11. Adding "system" libraries
Tip
  • 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 IDS 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

 

4.1.8 "Settings" tab explained

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

Image Removed

Fig. 12. "Settings" tab - code description
  • Programming languange:
    • Type - Defines programming language of user codes. It could be set to:
      • Fortran
      • _C/C++
    • Compiler - Defines compiler being used. Possible values:
      • ifort, gfortran
      • gcc, g++
  • Computation:
    • 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)
  • Additional features:
    • Calls init method - If user function needs any pre-initialization, an additional function will be called.
    • Returns diagnostic info - adds output diagnostic information

4.1.9 "Documentation" tab explained

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

Image Removed

Fig. 13. "Documentation" tab

4.1.10 "Interface" tab explained

The "Interface" tab specifies interface for Kepler actor.

Image Removed

Fig. 14. "Interface" 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++ / Fortran codes for FC2K
  • how to prepare C++ / Fortran library
  • how set up Makefile
  • how start and configure FC2K tool

...