Matlab Bindings

Introduction

The main binding to the Libisis framework which has been implemented is matlab. Each type defined in the framework has a module which contains type-specific methods for getting objects and variables from the matlab front-end and sending objects and variables back to the matlab front-end. These methods are called using two interfaces which are defined in a module IXMm_classname.

• IXBgetFromBinding
• IXBsendToBinding

This module is always defined in the file bindings/matlab/IXMclassname_m.f90. As a rule this module always contains the line use IXMclassname (it is however included automatically and does not need to be explicitly specified in the code)

The interfaces and methods of the IXMm_classname module are generated automatically using the preprocessor, in the following example for the IXTtestclass object in the IXMtestclass_m.f90 file. These are the only statements required to define the IXMm_testclass module.

module IXMm_testclass

#define IXD_TYPE testclass
#include "bindings_header.f90"

contains

#define IXD_TYPE testclass
#include "bindings_base.f90"

end module IXMm_testclass

If a class method implemented in the fortran framework is to be called from the matlab front-end various steps need to be followed.

define an appropriate binding subroutine in IXMclassname_m.f90

functions which are called from matlab are defined in the same file but outside of the IXMm_classname module. They are all prefixed with IXB. all the standard functions which are called such as IXBdisplay_classname, IXBcheck_classname are auto-generated using the preprocessor, so do not need any extra implementation.

#define IXD_TYPE testclass
#include "bindings_extra.f90"

only functions which are extra to the standard module subroutines which you need to call from matlab have to have a binding subroutine defined. We can create an IXBplus_testclass subroutine to allow matlab calling of the IXFplus_testclass method of IXTtestclass.

The arguments of every IXBmethod_classname subroutine are the same

• nlhs is the number of left hand side arguments from matlab (ie what is the output of the matlab call)
• plhs(nlhs) is an array of pointers to the left hand side arguments
• nrhs is the number of right hand side arguments from matlab (ie what are the arguments of the matlab call)
• prhs(nrhs) is an array of pointers to the right hand side arguments

for the most part memory is shared between the matlab binding and fortran framework, so we work with pointers.

there are four types of subroutine which can be called, each with different variables which are returned to the matlab front-end

1. functions which have no variable output eg. display,check (defined in bindings_base.f90)
2. functions which return a simple type (real, integer, character) eg. getting a value from an object
3. functions which return an object(s) (IXTtestclass, IXTdataset_2d) eg. the result of a plus operation (defined below)
4. functions which return an object(s) and a simple type back to matlab

the IXBgetFromBinding command reads data into a variable which has been passed down to the bindings layer from the matlab front-end. the call syntax is defined below.

    call IXFgetFromBinding(prhs(number),' ',1,0,variable,status)
    call IXFgetFromBindingPtr(prhs(number),' ',1,0,variable,status)

• the 1st argument defines which matlab pointer to read the data from according to number, which refers to the position of the right hand side argument when the matlab function is called
• the 2nd, 3rd & 4th arguments are always ' ',1,0
• the 5th argument is the variable to be populated
• if a variable length array is to be populated, the variable is defined as a pointer and the IXBgetFromBindingPtr subroutine is called, with the same syntax
• if a structure is to be returned to the matlab front-end prhs(1) is generally reserved for the object to be returned, it does not need to be read in, more details are specified below

when data is sent back to the matlab front-end the IXBsendToBinding subroutine is called. There are two possible syntaxes:

1) if we are returning a simple type variable

    call IXFsendToBinding(plhs(number_left),' ',1,0,variable,status)

• the 1st argument defines which matlab pointer to write the data in to according to number_left, which refers to the position of the left hand side argument when the matlab function is called
• the 2nd, 3rd & 4th arguments are always ' ',1,0
• the 5th argument is the variable to be sent back to the matlab front-end

2) if we are returning a structure

    call IXFsendToBinding(plhs(number_left),prhs(number_right),' ',1,0,variable,status)

• the 1st argument defines which matlab pointer to write the data in to according to number_left, which refers to the position of the left hand side argument when the matlab function is called
• the 2nd argument is the return type which has been sent from matlab
• the 3rd, 4th & 5th arguments are always ' ',1,0
• the 6th argument is the variable to be populated, it must agree with the type which has been sent in prhs(number_right)

an example IXBmethod_classname is defined below

  subroutine IXBplus_testclass(nlhs, plhs, nrhs, prhs, status)

this provides access to the IXBgetFromBinding and IXBsendtoBinding interfaces to read/write variables from/to matlab

    use IXMm_testclass
    implicit none

standard declarations

    integer :: nlhs, nrhs
    integer(cpointer_t) :: plhs(nlhs), prhs(nrhs)

• declarations of input and output objects used by the method called
• array input is defined as a pointer

    type(IXTtestclass) :: wres, w1, w2
    real(dp),pointer::array(:)
    type(IXTstatus) :: status

• read in two structures which will be added together
• check read went OK - report errors and return if not

    call IXBgetFromBinding(prhs(2),' ', 1, 0, w1, status)
    call IXBgetFromBinding(prhs(3),' ', 1, 0, w2, status)
    call IXBgetFromBindingPtr(prhs(4),' ', 1, 0, array, status)
    if (status == IXCseverity_error) return

do adding operation

    call IXFplus_testclass(wres, w1, w2,array, status)

wres has now been filled and needs to be entered into the matlab memory if the process was successfull

    if (status == IXCseverity_error) then
        plhs(1)=ixDuplicateArray(prhs(1))
    else
        call IXBsendToBinding(plhs(1), prhs(1), ' ', 1, 0, wres, status)
    endif
  end subroutine IXBplus_testclass

preprocessing operations

preprocesing can also be used to generate common code in the bindings, for example to create general code for unary operations (log, exp,sin etc...) called from the matlab front-end, there is explanation on preprocessing files here

in the file bindings/matlab/IXMdataset_2d_m.f90 the KEYWORDS are defined

#define IXD_TYPE	dataset_2d
#define IXD_NAME	Sin_Dataset_2d
#include "unary_ops.f90"

and in the include file bindings/matlab/unary_ops.f90 they are substituted

#if defined(IXD_TYPE) && defined(IXD_NAME)

subroutine IXB&/**/
              &IXD_NAME (nlhs, plhs, nrhs, prhs, s)
  use IXMm_&/**/
           &IXD_TYPE
  implicit none
  integer :: nlhs,nrhs
  integer(cpointer_t) :: plhs(nlhs),prhs(nrhs)
  type(IXT&/**/
          &IXD_TYPE ), allocatable :: wres(:), w1(:)
  type(IXTstatus) :: s
  integer n, i
  n = ixGetNumberOfElements(prhs(2))
  allocate(w1(n),wres(n))
  call IXBgetFromBinding(prhs(2), ' ', 1, 0, w1, s)
  if (s == IXCseverity_error) return
  do i = 1,n
      call IXF&/**/
              &IXD_NAME (wres(i),w1(i),s)
  enddo
  if (s == IXCseverity_error) then
    plhs(1)=ixDuplicateArray(prhs(1))
  else
    call IXBsendToBinding(plhs(1), prhs(1), ' ', 1, 0, wres, s)
  endif
  deallocate(w1,wres)
end subroutine

#undef IXD_NAME
#undef IXD_TYPE

#endif /* defined(IXD_TYPE) && defined(IXD_NAME) */

define object method pair in bindings/matlab/libisisexc.txt

we need to define all the subroutines which need to be accessed from the matlab front-end in another file, together with the number of input and output arguments. they are defined as a classname/method pair in the bindings/matlab/libisisexc.txt file with a general constuction:

IXTclassname     method    no_of_output_args   no_of_input_args

if the number of arguments is variable then -1 is defined. the number of arguments is essentially nrhs

where # is a comment character, the definition for IXTtestclass is as follows:

#
# IXTtestclass
#
IXTtestclass		plus			1		4
IXTtestclass		display			0		1
IXTtestclass		create			1		2
IXTtestclass		check			1		1
IXTtestclass		read			1		3
IXTtestclass		write			1		3

write an appropriate matlab function

in bindings/matlab/classes/@IXTclassname directory

this function must make a call to the libisisexc DLL