1. 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. 2. Development of Fortran codes

2.1. 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. 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 (ids_equilibrium)   :: equilibriumin <== SINGE SLICE
      • type (ids_core_profiles) :: coreprofoutout  <== ALL SLICES

 

  • Do not forget to add: use ids_schemas, while playing with IDSes
  • Please use intent(in), intent(out) to point in/out parameters

2.3. 2.3. Code parameters

  • user defined input parameters
  • input / optional

  • Argument of type: type_param

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

2.4. 2.4. Diagnostic info

  • arbitrary output diagnostic information

    • output / optional

           !----  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. 2.5. Examples

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

 

 

Example 2 A IDS array as a subroutine argument
subroutine equil2dist(equilibrium_in, core_prof_out)
  use imas_schemas
  implicit none

 !input
 type (ids_equilibrium) :: equilibrium_in
 !output
 type (ids_core_profiles) :: core_prof_out

 

 

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

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

  !output
  type(ids_equilibrium) :: equi
  character(50), intent(out) :: tabchar

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

3. 3 Development of C++ codes

3.1. 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. 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:
      • IdsNs::IDS::equilibrium & eq      <= SINGLE SLICE
      • IdsNs::IDS::core_profiles & cp   <= ALL SLICE'S

3.3. 3.3 Code parameters

  • Optional
  • User defined input parameters

  • Argument of type: IdsNs::codeparam_t &

    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: IdsNs::codeparam_t & codeparam

3.4. 3.4 Diagnostic info

  • arbitrary output diagnostic information

  • output / optional

     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

Required header

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

 

 

3.5. 3.5 Examples

 

 

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

void mycppfunction(IdsNs::IDS::core_profiles& cp, int& x, double&  y, IdsNs::codeparam_t& codeparam)

Initialization

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

 

 

4. 4. Delivery of the user code

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


 
Example 6. Building of Fortran code
F90 = ifort
COPTS = -g -O0 -assume no2underscore -fPIC -shared-intel

INCLUDES = $(shell pkg-config --cflags imas-ifort)

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
Example 7. Building of C++ code
CXX=g++
CXXFLAGS= -g -fPIC
CXXINCLUDES= ${shell pkg-config --cflags imas-cpp}

all: libsimplecppactor.a

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

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

clean:
        rm *.a *.o

 

 

Recomendations

  • Please use 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.

 

 

 

  • No labels