Wir schaffen Wissen heute für morgen

Transcription

1 Wir schaffen Wissen heute für morgen The MEXperience, Getting to Grips with MATLAB Executable Files Jan Chrin Paul Scherrer Institut

2 Contents Motivation Context of SwissFEL Injector Test Facility ( ) also SLS C++ Channel Access Interface Feeding the MEX-file Summary: Main Points and Next Steps

3 SLS MATLAB Application Count at the Swiss Light Source (SLS) Year No. MATLAB Applications (nil!) but increasing (TIARA Project) 2000 applications at the SLS dominated by Tcl/Tk 2012 Test Infrastructure and Accelerator Research Area (TIARA) (distributed European Accelerator R&D facility)

4 SwissFEL Injector Test Facility MATLAB Application Count at the Swiss Light Source (SLS) Year No. MATLAB Applications (nil!) (TIARA Project) MATLAB Application Count at the SwissFEL Injector Test Facility Phase I: August 2010, Phase IV: February 2013, End: September 2014 Year No. MATLAB Applications 2010 (Phase I) Lots! 2012 (Phase III) >50 (1 C++/Qt and 1 Java are the exception)

5 Use of MATLAB has surged! Motivation Large dependency -> reappraisal of ca requirements for MATLAB -> more extensive interface to the presently used mca Support data types other than double and string, e.g. unsigned short (mxuint16_class) in analysis/storage of camera data used in beam profile measurements: more efficient use of memory CA-aware classes for specific operations, e.g. acquisition of machine snapshots, orbit data, (using ca synchronous groups) Compilation on a 64-bit Linux machine, comparison of injector data with OPAL, a computationally intensive 3D space-charge simulation model Stability, Robustness: improved reconnection management

6 Channel Access Interface Library C++ Channel access interface library, CAFE synchronous, asynchronous interaction (blocking, non-blocking determined by setting policies) for individual, collections/groups of channels Data passed through CA in native data type data may be presented to client in any meaningful type (true also of enumerated types) Extensive use of templates get/set operations, underlying CA classes, data conversions Connection/reconnection (memory) management Connectivity remains in a well-defined state in every eventuality! All details of a PV and its state held in a hash table (Boost Container)

7 mocha: The Channel Access MEX File The Missing Link! MATLAB Mocha MATLAB objects for channel access MEX-file CAFE Library

8 The MEX-file Ingredients MEX-file: MATLAB Executable File (compiled) Functions implemented as MEX-files can be called directly from MATLAB MEX-files can be created from C/C++ by using the mex command Source code written using the MEX API which provide functions to read/write input/output arguments from/to MATLAB, or to access global variables Mex-files include: (1) mexfunction gateway (2) #include mex.h (mx* and mex* routines) (3) mxarray (4) API (mx* and mex*) functions

9 A Basic MEX-file #include mex.h (mx* and mex* ) mx* functions used to access data inside mxarrays mex* functions perform operations back in MATLAB mexfunction Gateway: interfaces with MATLAB The mexfunction is the entry point to underlying C/C++ code and declares the four variables that interface our code to MATLAB void mexfunction (int nlhs, mxarray * plhs[], int nrhs, const mxarray * prhs[] ) { } nlhs = Number Left Hand Side, i.e. the number of outputs (expected mxarrays) plhs = Array of pointers to mxarrays for output (must be explicitly created) nrhs = Number Right Hand Side, i.e. the number of inputs prhs = Array of pointers to mxarrays for input data (should not be altered)

10 mxarray mxarray is a special structure that encapsulates MATLAB data It is the C representation of a MATLAB array All MATLAB variables, scalars, vectors, matrices, strings, cell arrays, and structures are stored as mxarrays

11 MEX-file API API functions (Two Types) mx* functions used to create and access data inside arrays Array Creation: mxcreatenumericarray, mccreatedoublematrix, mxcreatecellarray Array Access: mxgetpr, mxgetdata, mxgetcell Memory Management: mxmalloc, mxfree mex* functions mexevalstring mexcallmatlab mexprintf perform operations back in MATLAB (Execute MATLAB command in caller s workspace) (Call MATLAB function) mxis* functions to determine various states of an array; used to check input to MEX-file and ensure they are of correct type

12 The MEX Cycle Data Flow within Gateway Routine MATLAB Call to MEX-file mocha: [status]=mocha( set, handle, value) Passes variables set, handle and value to the mocha MEX-file. status is unassigned const mxarray * value; value = prhs[2] const mxarray * handle; handle= prhs[1] const mxarray * message; message= (mxarray *) prhs[0] mocha.cpp void mexfunction( int nlhs, mxarray *plhs[], int nrhs, const mxarray *prhs[]) (1) Validate input argument prhs[0]; extract data from prhs[0] using the mxget* function (2) Find matching index in The Big Switch MATLAB On return from MEX-file mocha: [status]=mocha( set, handle, value) plhs[0] is assigned to status (3) Use mxget* functions to extract remaining input arguments, prhs[1](handle), prhs[2](value) (4) Validate data, e.g. mxgetnoelements(prhs[2]) (5) Use mxcreate* functions to create the MATLAB array for the output argument, plhs[0] (status) (6) Call cafe->set function passing the data input and output data pointers as function parameters mxarray * status; status = prls[0]

13 mexfunction( ) within the Gateway routine try { cafe->set(handle, value); } catch (CAFEException &catchaspill) { } Exceptions not caught!

14 What happened to my Exception? try { cafe->set(handle, value); } catch (CAFEException &catchaspill) { } Exceptions not caught! Behaviour caused by version linker script mexfunction.map Solutions: Link against a static version of the library Don t use exceptions, rather status return codes Create a wrapper library which does not conform to mexfunction.map /* Source of MEX-file which calls the wrapper shared library. Previous content of the mexfunction moved to the wrapper library; now call the function in the wrapper library instead. */ #include "macchinetta.h" extern void _main(); void mexfunction(int nlhs,mxarray *plhs[],int nrhs, const mxarray *prhs[]) { macchinettafunction(nlhs,plhs,nrhs,prhs); }

15 mocha syntax Feed Mex-file with further ca functionality, by follow the same pattern: First checks to make sure that the function was called correctly: correct number of inputs, verify that the input is the right format, e.g. scalar, Create the mxarrays to assign to output parameters handle = mocha ( open, pvname ); [val, status] = mocha( get, handle); datastruct = mocha( getstruct, handle); [val, status, isstatusok] = mocha( getgroup, grouphandle); ctrlstruct = mocha( getctrlstruct, handle); status = mocha( set, handle, data); status = mocha( monitor, handle, action ); status = mocha( close, handle); mocha( close);

16 Synchronous Groups and MATLAB Classes classdef cafeorbit < handle properties (SetAccess = private) groupname=''; ghandle=0; s=0; bpmnames=''; nbpm=0; x=0; y=0; I=0; xyvalid=0; IValid=0; xstatus=1; ystatus=1; IStatus=1; xyvalidstatus=1; IValidStatus =1; isvalidok=true; isstatusok=true; end %define en event called cafeerrorreport events cafeerrorreport end SLSOrbit=cafeOrbit() methods function mcorbit = cafeorbit(); mcorbit.groupname='gdbpm'; mcorbit.ghandle = mocha('opengroup','gdbpm'); [mcorbit.bpmnames, mcorbit.s] = mocha('getstaticdata','cdbpm','master.xml'); [mcorbit.x, mcorbit.y, mcorbit.i, mcorbit.xyvalid, mcorbit.ivalid,... mcorbit.xstatus, mcorbit.ystatus, mcorbit.istatus, mcorbit.xyvalidstatus,... mcorbit.ivalidstatus, mcorbit.isvalidok, mcorbit.isstatusok] = mocha('getorbit',mcorbit.ghandle); mcorbit.nbpm = length(mcorbit.x); %[mcorbit.data, mcorbit.statuscode, mcorbit.isstatusok] = mocha('getgroup',mcorbit.handle); cafeerrormanager.addcafe(mcorbit); end return function get(mcorbit) = mocha('getorbit',mcorbit.ghandle); end end % methods end % classdef [mcorbit.x, mcorbit.y, mcorbit.i, mcorbit.xyvalid, mcorbit.ivalid,... mcorbit.xstatus, mcorbit.ystatus, mcorbit.istatus,mcorbit.xyvalidstatus,... mcorbit.ivalidstatus, mcorbit.isvalidok, mcorbit.isstatusok] return

17 Monitors Mocha monitors: mocha( monitor, handle, action ) Cache updated values, optionally execute a script to update widget mocha MEX-File CAFE well separated! i.e. CAFE has no knowledge of the MEX API. mocha( monitor, handle, action ) cafe->confighandle_add_monitoraction(handle, action ); timer('timerfcn','mocha(''monitorflushevent'')','period',0.1,'executionmode','fixedspacing'); vector<string> al; status=cafe->getmonitoraction(al); [No Queue Class!]

18 Mocha Index to switch index get with selected type No of methods can be greatly reduced! e.g. one set sufficient mocha mca-compatible MATLAB scripts provided to facilitate transition from mca to mocha

19 Main Points Mocha MEX-file interfaces channel access (thru CAFE) methods to MATLAB Mocha (as mca) is single MEX-file cf labca interfaces EZCA to MATLAB multiple MEX-files Sizeof (mocha code) << Sizeof (mca code) Binding procedure follows a recognizable pattern: Extract, validate input arguments, invoke CAFE method, convert CAFE output arguments into MATLAB data type, prepare data format (array, struct..) for return to caller mocha mca-compatible MATLAB scripts provided to facilitate transition from mca to mocha Immediate tangible benefits: Access to all MATLAB primitive data types MATLAB oo: mocha-aware classes (orbit data, machine snapshot). Classes, on initialization, extract static data, i.e. node names, positions from the accelerator XML (á la XAL) Compilation on a 64-bit Linux Server (machine data / 3D simulations) Mocha monitors: Cache updated values, optionally execute a script to update widget (but MATLAB s Event and Listener model would be another approach).

20 Summary Getting To Grips with MEX API has allowed us to create: uncomplicated, robust, extendable, MEX-file for channel access In use at the SwissFEL Injector Test Facility and SLS Next: Consolidate (and expose remaining CAFE) methods to provide a general-purpose MATLAB-ca interface Acknowledgements Groundwork for channel access connectivity laid by mca

21 Epics-Language Index source: