You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

1. Introduction

1.1. Motivations

Complex simulations often combines a number of physics codes, potentially provided by various actors and written in different programming languages. To make them working together, an additional layer, that 'orchestrates' execution of particular codes, and takes care on passing data between 'producers' and 'consumers' is needed. Sometimes the functionality of such layer is provided by dedicated software (aka 'workflow orchestrators', like Kepler https://kepler-project.org/), sometimes it can be handled by much simpler mechanism like Python scripts.  Unfortunately all components ('actors') that constitute a computing scenario ('workflow') must be implemented in the same programming language, defining the same API.

Unfortunately, in most cases, scientific, simulation codes that performs computing intensive calculations  (due to performance reasons) are written in C++ or Fortran, while 'workflow orchestrators' are implemented in (more popular nowadays) languages, like Java, Python, etc. Hence the need for a 'wrapper' that intermediates between native code language and language of the orchestrator. Such wrappers can be developed manually, however users may benefit from a tool that automatise this process - iWrap

1.2. iWrap - actor generator

iWrap is a modular component generator, implemented in Python, used for creating IMAS actors from physics models. This mechanism allows to integrate physics codes written in one language (Fortran, CPP) within complex computing scenarios designed in other language (e.g. Python).

It's plug-in based modular design with clear separation of concerns allows to generate various types of actors and easily change data access paradigm (from dataset descriptor for AL to direct HDC data for instance)

For user conveniency it provides two kinds of interfaces: user friendly graphical interface that allows non-experienced users to define an actor in intuitive way and command line interface foreseen for more advanced users that may want to e.g. automatise actor generation process using scripts.


  • iWrap 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 other arguments to/from the actor
  • iWrap creates a Python script (aka an actor) that:
    • calls a user code
    • provides error handling
    • calls debugger (if run in "debug" mode)


Glossary

Scenario (aka workflow)

  • A set of components (actors) constituting a directed graph to execute a computing algorithm
  • Actors are dependent: a control and data is passed from actor to actor
  • Usually the order of actors execution and the way how data are passed from actor to actor is managed by so called "workflow system". Such manager can be a simple script (codes) or more sophisticated "orchestrator" (e.g. Kepler)

Actor

  • A basic component of scenario / workflow
  • An actor performs some actions (e.g. computations, visualisation, etc)
  • Usually given actor consumes results provided by a previous actor in a scenario and produces data for a next actor in a scenario

  • Actor API strictly depends on targeted workflow system: an orchestrator "fires" particular actions on actor 

  • An actor, using its internal mechanisms ('wrappers') calls 'native code' method(s), usually written in other language than an actor  

Native code

  • A physics code, of standardised signature, provided by software developer 


2. Preparation of code

A signature of user code must follow strict rules to allow interaction between it and wrapping actor.  Please use following  >>link<< to get detailed guidelines for integration of native code into workflows using iWrap  

3. Code and actor description

iWrap, to properly wrap the code, needs detailed informations about both: the wrapped code and an actor to be generated. A formal description ot the code provides information about the programming language used, arguments passed to/from the code, type of these arguments, etc, etc, while an actor description tells iWrap how to name generated actor, where to put it, etc. Such descriptions has to be provided in YAML format file, prepared manually, or automatically with help of iWrap GUI.

3.1.  YAML file syntax

The YAML file consists of two independent parts (aka 'YAML documents'), marked by tags corresponding to their roles: actor_description and code_description. Only code description part is mandatory, and  actor description could be provided in a file, or using iWrap commandline switches or interacting with GUI.

The structure of the file is following:


iwrap_file.yaml
# actor description part - optional 
--- !actor_description
	<see chapter below for details>
...

# code description part - mandatory
 --- !code_description  
 	<see chapter below for details> 
...


3.2. Native code description

Description of the native code has to be provided as a YAML document. It consist of two parts. The first one contains generic information common for all languages, The latter one contains information specific for a given language of the native code (currently defined only for Fortran and CPP). 


  • All YAML fields are MANDATORY, unless explicitly described as OPTIONAL
  • A code description part must begin with "--- !code_description" 


3.2.1. Common part

 Generic information common for all (or at least majority of) programming languages.

  • programming_language
    • meaning:  language of physics code
    • value: one of predefined values: 'Fortran', 'CPP'
    • example: 'Fortran'
  • code_name
    • meaning:
      • name of user method / subroutine to be called,
      • must be exactly the same as name of called method / subroutine
      • it is used also as an actor name
    • value: string
    • example: 'my_subroutine' 
  • data_type
    • meaning: data type handled by the physics code
    • value: 'legacy' (currently only 'Legacy IDS' type has been implemented)
    • example: 'legacy'
  • arguments - list of arguments
    • argument definition: 
      • name:
        • meaning: user defined argument name
        • value: string
        • example: equilibrium00   
      • type:
        • meaning: a type of an IDS argument
        • value: 
          • predefined name of one of the IDSes
        • example: 'equilibrium' 
      • intent
        • meaning: determines if given argument is input or output one
        • value: predefined - string "IN", "OUT"
  • code_path: 
    • meaning: path to system library (C, CPP) , script (Python), etc containing the physics code, including method/subroutine to be run
    • value: string, valid path to file
    • example: 'any text'  
  • code_parameters - a structure containing parameters and schema entry:
    • parameters:
      • meaning: path to XML file containing user defined parameters of the physics code
      • value: string, valid path to file
      • example: './code_parameters/parameters.xml'
    • schema:
      • meaning: path to XSD file contains schema of XML parameters, to be able to validate them
      • value: string, valid path to file
      • example: './code_parameters/parameters.xsd'
  • documentation:
    • meaning: human readable description of native code
    • value: string
    • example: 'any text'

3.2.2. Language specific part - Fortran/C++

  • compiler:
    • meaning: the name/vendor of the compiler (and not compiler command!) used to compile native codes
    • value: string, one of vendors of compilers, currently: 'Intel' or 'GCC'
    • example: 'Intel'
  • mpi_flavour:
    • meaning: MPI compiler flavour to be used
    • values: string, one of:  MPICH, MPICH2, MVAPICH2, OpenMPI, etc.
    • example 'MPICH2'
  • open_mp:
    • meaning: if user code should be compiled with OpenMP flag
    • values: boolean
    • example 'true'
  • system_libraries:
    • meaning: a list of system libraries, managed using pkg-config mechanism,  that has to be used while native code linking
    • value: a list of system libraries names, as they are published by pkg-config 

    • example: 

      - fftw3f
      - glib
      - mkl

  • custom_libraries:
    • meaning: additional libraries, not managed by pkg-config mechanism, necessary to link of the physics code :
    • value:  a list of paths to libraries 

    • example: 

      - ./lib/custom/libcustom1.a
      - ./lib/custom/libcustom2.a

3.2.3. Example - Fortran code description


fortran_code.yaml
--- !code_description
programming_language: Fortran
code_name: demo_code
data_type: legacy
arguments:
-   name: equilibrium00
    type: equilibrium
    intent: IN
-   name: equilibrium01
    type: equilibrium
    intent: IN
-   name: equilibrium10
    type: equilibrium
    intent: OUT
-   name: equilibrium11
    type: equilibrium
    intent: OUT
code_path: ./lib/libmy_lib.a
code_parameters:
    parameters: ./code_paramneters/parameters.xml
    schema: ./code_paramneters/parameters.xsd
documentation: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
    eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
    veniam... '
language_specific:
    compiler: Intel
    mpi_flavour: MPICH2
    open_mp: false
    system_libraries:
    - fftw3f
    - glib
    - mkl
    custom_libraries:
    - ./lib/custom/libcustom1.a
    - ./lib/custom/libcustom2.a

3.3. Actor description

  • All YAML fields are MANDATORY
  • An actor description part must begin with "--- !actor_description" 

3.3.1. Actor description syntax


  • actor_name:
    • meaning: the name/vendor of the compiler (and not compiler command!) used to compile native codes
    • value: string, one of vendors of compilers, currently: 'Intel' or 'GCC'
    • example: 'Intel'
  • actor_type:
    • meaning: MPI compiler flavour to be used
    • values: string, one of:  MPICH, MPICH2, MVAPICH2, OpenMPI, etc.
    • example 'MPICH2'
  • data_type:
    • meaning: data type handled by the physics code
    • value: 'legacy' (currently only 'Legacy IDS' type has been implemented)
    • example: 'legacy'
  • install_dir:
    • meaning: MPI compiler flavour to be used
    • values: string, one of:  MPICH, MPICH2, MVAPICH2, OpenMPI, etc.
    • example 'MPICH2'

3.3.2. Example

actor_description.yaml
--- !actor_description
actor_name: core2dist
actor_type: python
data_type: legacy
install_dir: /afs/eufus.eu/user/g/g2bpalak/IWRAP_ACTORS
...


3.4.  iWrap graphical interface

>>here<<


4. wrapping (job description, iWrap)

5. usage of actor within WF

  • No labels