Anything that can go wrong, will go wrong- Murphy's law
| 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
|
...
- 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 |
4.1.2 FC2K main window
|
| 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 FC2K was started |
4.1.3 Actor description
|
| Fig. 2. FC2K actor description |
|---|
...
| Warning |
|---|
A name of user subroutine must be exactly the same as it was defined in user code |
4.1.4 Environment
|
| Fig. 3. FC2K environment tab |
|---|
...
Below you can find explanation of FC2K arguments tab.
|
| 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.
- if turned ON - An argument is passed as an array. It requires definition of array size (dynamic array are not supported)
- Array size - Defines the size of an array of primitive types (-1 in case of arrays of dynamic size)
- 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. |
|
| Fig. 5. An example of subroutine arguments |
|---|
...
- equilibrium - an input parameter - one IDS (slice)
- amns_data - an input parameter - all amns_data IDS slices stored in given shot/run
- integer - an input parameter - a scalar
- double - an input parameter - an array of size 10
- edge_source - an in/out parameter - single slice of "edge_source" IDS
- waves - an output parameter - all slices of "waves" IDS
...
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 IMAS data structures.
|
| Fig. 6. "Parameters" tab |
|---|
...
| Info |
|---|
Usage of code parameters |
4.1.7 "Source" tab explained
|
| Fig. 7. "Source" tab |
|---|
...
A "Main library" field allows to define a path to library containing user subroutine/function.
|
| Fig. 8. "Source" tab - A path to "main" and "optional" library |
|---|
...
"Custom libraries" are non-standard static libraries required for building the user code.
|
| Fig. 9. "Source" tab - A list of "custom" libraries |
|---|
...
"System libraries" are system libraries handled by pkg-config mechanism and required for building the user code.
|
| Fig. 10. "Source" tab - A list of "system" libraries |
|---|
...
- add library from the list,
- remove library
- display detailed info (library definition returned by pkg-config mechanism)
|
| Fig. 11. Adding "system" libraries |
|---|
| Tip |
|---|
|
...
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. 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++
- Type - Defines programming language of user codes. It could be set to:
- 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 Sandbox
"Sandbox" - a directory, in which actor will be run. Before execution of user codes wrapped by FC2K generated actor, directory will be changed to "sandbox", and after actor finishes, current directory will be switched back to previous value. The name (path) of "sandbox" directory will be created automatically or specified by user in actor configuration dialog.
Actor will use existing directory or will create it, if directory not exists. All directories created automatically or having user specified relative path will be created under <SANDBOX_ROOT> ( $ITMSCRATCH/KEPLER_SANDBOXon the Gateway).
|
| Fig. 15. "Sandbox" functionality |
|---|
"Use sandbox" - enables / disables "sandbox"
"Sandbox" disabled
- Actor behavior not changed, comparing to previous versions
- A temporary directory is created in "Standalone" "Batch" "MPI" or "Debug-standalone" execution modes ( $HOME/public/KEPLEREXECUTION/<actor_name>_<timestamp> )
"Sandbox" enabled:
- actor uses sandbox
- a sandbox parameters shown in actor configuration dialog
4.1.10 "Documentation" tab explained
The "Documentation" tab specifies an user-defined Kepler actor description. It could be displayed from actor pop-up menu.
|
| Fig. 13. "Documentation" tab |
|---|
4.1.
...
11 "Interface" tab explained
The "Interface" tab specifies interface for Kepler actor.
|
| 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++ codes for FC2K
- how to prepare C++ library
- how set up Makefile
- how start and configure FC2K tool
...
Warning
Stop here for a moment. Make sure you have followed the configuration setup before proceeding any further!
...