Versions Compared

Old Version 2

changes.mady.by.user Bartosz Palak

Saved on

compared with

New Version 3

changes.mady.by.user Bartosz Palak

Saved on

Key

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

...

1. What code wrapper actually does?

The code wrapper intermediates between Kepler actor and user code:

  • Passes variables of language built-in types (int, char, etc) from actor to the code
  • Reads IDS(es) from UAL and passes data to user code
  • Passes input code parameters (XML/XSD files) to user code
  • Calls user subroutine/function
  • Saves output IDS(es)

2. Development of Fortran codes

2.1 Subroutine syntax

subroutine name ( <in/out arguments list> [,code_parameters] [,diagnostic_info] )

  • name - subroutine name
  • in/out arguments list - a list of input and output subroutine arguments

    • diagnostic_info - arbitrary output diagnostic information

    2.2. Arguments list

    • A mandatory position
    • A list of input and output subroutine arguments including:
      • Fortran intrisic data types, eg:
        • integer :: input
        • character(50) :: charstring
        • integer,dimension(4) :: tabint
      • IDSes, eg:
        • type (type_equilibrium),pointer :: equilibriumin(:)
        • type (type_distsource),pointer :: distsourceout(:)
    Warning
    • Always describe IDS as an array. In case of time slice, the size of the input IDS is 1 (!)
    • Do not forget to add: use imas_schemas, while playing with IDSes
    • Please use intent(in), intent(out) to point in/out parameters

    2.3. Code parameters

    • user defined input parameters
    • input / optional

    • Argument of type: type_param

      Code Block
      type type_param  !
  character(len=132), dimension(:), pointer ::parameters 
  character(len=132), dimension(:), pointer ::default_param  
  character(len=132), dimension(:), pointer ::schema         
endtype
    • Derived type type_param describes:
      • parameters - Actual value of the code parameters (instance of coparam/parameters in XML format).
      • default_param - Default value of the code parameters (instance of coparam/parameters in XML format).
      • schema - Code parameters schema.
    • An example: 
      • (type_param) :: codeparam{{

    2.4. Diagnostic info

    • arbitrary output diagnostic information

      • output / optional

        Code Block
             !----  Diagnostic info  ----
     integer, intent(out)     ::     user_out_outputFlag
     character(len=:), pointer, intent(out)    ::    user_out_diagnosticInfo

      • outputFlag - indicates if user subroutine was successfully executed

        • outpuflag = 0    - SUCCESS, no action is taken

        • outputFlag > 0  - WARNING, a warning message is displayed, workflow continuue execution

        • outputFlag < 0 - ERROR, actor throws an exception, workflow stops

      • diagnosticInfo - an arbitrary string

    2.5. Examples

    Code Block
    titleExample 1 Simple in/out argument types
    subroutine noids(input, output)
   integer, intent(in):: input
   integer, intent(out):: output

     

     

    Code Block
    titleExample 2 A IDS array as a subroutine argument
    subroutine equil2dist(equilibriumin, distsourceout)
  use imas_schemas
  implicit none

 !input
 type (type_equilibrium), pointer :: equilibriumin(:)
 !output
 type (type_distsource), pointer :: distsourceout(:)

     

     

    Code Block
    titleExample 3 Usage of code input parameters
    subroutine teststring(coreprof,equi,tabint,tabchar,codeparam)
   use imas_schemas                                                                              
   implicit none                                             

  !input
  type(type_coreprof),pointer,dimension(:) :: coreprof
  integer, dimension(4), intent(in) :: tabint

  !output
  type(type_equilibrium),pointer,dimension(:) :: equi
  character(50), intent(out) :: tabchar

  !code parameters
  type(type_param), intent(in) :: codeparam

    3 Development of C++ codes

    3.1 Function syntax

    void name ( <in/out arguments list> [,code_parameters] [,diagnostic_info] )

    • name - function name
    • code_parameters - optional - user defined input parameters
    • diagnostic_info -  arbitrary output diagnostic information

    3.2 Arguments list

    • in/out arguments list
    •  mandatory
    • a list of input and output function arguments including:
      • CPP intrisic data types, eg:
        • int &x
        • double &y
      • IDSes, eg:
        • ItmNs::Itm::antennas & ant
        • ItmNs::Itm::equilibriumArray & eq

    3.3 Code parameters

    • Optional
    • User defined input parameters

    • Argument of type: ItmNs::codeparam_t &

      Code Block
      languagecpp
      typedef struct {
        char **parameters;
        char **default_param;
        char **schema;
    } codeparam_t;

       

       
    • A structure codeparam_t describes:
      • parameters - Actual value of the code parameters (instance of coparam/parameters in XML format).
      • default_param - Default value of the code parameters (instance of coparam/parameters in XML format).
      • schema - Code parameters schema.
    • An example: ItmNs::codeparam_t & codeparam

    3.4 Diagnostic info

    • arbitrary output diagnostic information

    • output / optional

      Code Block
      languagecpp
       void name(...., int* output_flag, char** diagnostic_info)

    • output_flag - indicates if user subroutine was successfully executed

      • output_flag = 0  - SUCCESS, no action is taken

      • output_flag > 0  - WARNING, a warning message is displayed, workflow continuue execution

      • output_flag < 0  - ERROR, actor throws an exception, workflow stops

    • diagnostic_info - an arbitrary string

    Warning

    Required header

    Do not forget to add #include "UALClasses.h" while playing with IDSes!

     

     

    3.5 Examples

     

     

    Code Block
    languagecpp
    titleExample 4. Simple in/out argument types
    void simplecppactornoids(double &x, double &y)
    Code Block
    languagecpp
    title Example 5. A IDS array as a function argument
    void simplecppactor(ItmNs::Itm::equilibrium &eq, double &x, double &y)
    Code Block
    languagecpp
    titleExample 6. Usage of init function and code input parameters
    void mycppfunctionbis_init();

void mycppfunction(ItmNs::Itm::summary& sum, ItmNs::Itm::equilibrium& eq, int& x, ItmNs::Itm::coreimpur& cor,  double&  y, ItmNs::codeparam_t& codeparam)
    Info

    Initialization

    If user function needs any pre-initialization, an additional function <name>_init could be defined.

     

     

    4. Delivery of the user code

    The user code should be delivered as a static library.
    Please find examples of the simple "makefiles" below:


     
    Code Block
    languagebash
    titleExample 6. Building of Fortran code
    F90 = $(ITM_INTEL_FC)
COPTS = -g -O0 -assume no2underscore -fPIC -shared-intel

INCLUDES = $(shell eval-pkg-config --cflags ual-$(ITM_INTEL_OBJECTCODE))

all: equilibrium2distsource.o libequilibrium2distsource

libequilibrium2distsource: equilibrium2distsource.o
        ar -rvs libequilibrium2distsource.a equilibrium2distsource.o

equilibrium2distsource.o: equilibrium2distsource.f90
        $(F90) $(COPTS) -c -o $@ $^ ${INCLUDES} 

clean:
        rm -f *.o *.a
    Code Block
    titleExample 7. Building of C++ code
    CXX=g++
CXXFLAGS= -g -fPIC
CXXINCLUDES= ${shell eval-pkg-config --cflags ual-cpp-gnu}

all: libsimplecppactor.a

libsimplecppactor.a: simplecppactor.o
        ar -rvs $@ $^

simplecppactor.o: simplecppactor.cpp
        $(CXX) $(CXXFLAGS) $(CXXINCLUDES) -c -o $@ $^

clean:
        rm *.a *.o

     

     

    Tip

    Recomendations

    • Please use eval-pkg-config to get UAL flags and not hard coded references.
    • The usage of environment variables for identifying compilers and versions of the pkg-config is recommended.

     

     

    ...