Matlab(R) High Level Architecture Toolbox

(MatlabHLA-Toolbox)

-

C. Stenzel, S. Pawletta

February 2008

Abstract

The MatlabHLA-Toolbox is developed through the research group Computational Engineering and Automation at the University of Wismar. It provides HLA connectivity within Matlab under Linux and Windows. The current toolbox supports the HLA standard 1.3. It is licensed under the LPGL, the additional demos are licensed under the GPL. The recommended Runtime Infrastructure (RTI) is ONERA CERTI. The development takes place on the ONERA CERTI development web site at Savannah.
Contents Introduction
The High Level Architecture (HLA) is a standard for distributed simulation. Invented and developed by the American Department of Defense HLA arised to the first IEEE standard for distributed simulation in september 2000. The middleware providing HLA services is called Runtime Infrastructure (RTI).

Today different commercial and non-commercial RTI implementations exist. All of these implementations provide an API to C++ and/or Java conform to the interface specification of the HLA standard. This absolutely fulfills the requirements of the military domain where most of the simulations are coded in object-oriented programming languages like C++ or Java.

In the civilian domain simulations are created with the help of so-called Commercial of the Shelf Simulation Packages (COTSSP). HLA integration is not widely provided by today's COTSSP.

Simulation model design and execution in the engineering and scientific domain are often characterized by the usage of Scientific and technical Computation Environments (SCE) like Matlab, a famous commercial SCE. Other free SCEs already exist like Octave or Scilab. These systems replaces more and more the traditional Fortran coding. But existing Fortran programs are daily used througout the scientific and engineering community. Especially for the supercomputing community Fortran is still today the primary programming language.

In respect of the increasing importance of HLA there is a need to provide engineers a native HLA interface in their "daily working environments". This approach promises to reduce the effort for applying HLA in the engineering community to a minimum.

The MatlabHLA-Toolbox closes this gap for Matlab. The related software project F90HLA of the research group CEA provides an HLA interface within Fortran90 (libF90HLA).

Features
The current version of the MatlabHLA-Toolbox fully supports the management areas federation management, declaration management, object management and time management of the HLA 1.3 standard (for a complete list see section Supported Services).

Further design aspects concentrate on the interactive resp. interpretive way of working within Matlab. Features as abbreviated RTI service designators, optional exception handling and default interactive federate services shall provide a maximum possible native Matlab integration.

Beside these points the use of vectorization and implicit data types leads to a relevant simplification of the MatlabHLA-Toolbox compared to the original RTI interface.

Matlab RTI Linkage
When integrating the object oriented RTI interface within a procedural language environment four main challanges have to be overcome: Typically, a federate is only member of one federation. Originating of that assumption a federate have to instantiate one object of the RTIambassador class. The methods of the RTIambassador object are so-called RTI services. Furthermore a derived class of the abstract FederateAmbassador class have to be instantiated. The methods of that object are the so-called federate services and are application specific. These methods allow libRTI to call into the application and can best compared as callbacks. Both objects typically stay in memory until the process terminates.

The Matlab External (MEX) interface allows access to external libraries. In the case of interfacing libRTI special precautions have to be taken.

The binding mechanism to Matlab instantiates both required objects statically in one special function (rtiOn). From this it follows that accidental or automatic module unloading have to be avoided under any circumstances. This is reached through module locking. Once instantiated a procedural interface towards libRTI as shown in the right figure can be built up.

The usage of methods with the same name but different signatures is common practise in the object orientation. Also the RTI-C++-interface makes extensive use of overloaded methods. However, Matlab do not support overloading natively. But the MEX interface of MATLAB provides the ability to analyse function signatures manually. Also signature analysis within m-functions is possible.

All functions of the MatlabHLA toolbox provide an optional error return value. If a more complex error handling than the default is required an potential exception can be handled on the application layer.

A Matlab federate invokes RTI services by calling the appropriate MatlabHLA-Toolbox m-function. The m-function directly calls a C++-wrapper function. There all necessary type conversion are done. After that the actual library function is called. All RTI services return after execution immediatly. RTI initiated calls are handled first on the wrapper layer. LibRTI calls the implemented federate services. There a type conversion from C resp. C++ types into Matlab types takes place. Finally the appropriate m-file service is called through invoking the MEX function mexCallMatlab(). Finally the execution returns to libRTI.

Supported Services
Federation Management - RTI Services (4)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
4.2 createFederationExecution createFedExec 1
4.3 destroyFederationExecution destroyFedExec 1
4.4 joinFederationExecution joinFedExec 1
4.5 resignFederationExecution resignFedExec 1
4.6 registerFederationSynchronizationPoint registerFedSyncPoint 1
4.9 synchronizationPointAchieved syncPointAchieved 1
4.11 requestFederationSave requestFedSave 1
4.13 federateSaveBegun fedSaveBegun 1
4.14 federateSaveComplete fedSaveComplete 1
4.14 federateSaveNotComplete fedSaveNotComplete 1
4.16 requestFederationRestore requestFedRestore 1
4.20 federateRestoreComplete fedResComplete 1
4.20 federateRestoreNotComplete fedResNotComplete 1

Federation Management - Federate Services (4)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
4.7 synchronizationPointRegistrationSucceeded syncPointRegSucceeded 1
4.7 synchronizationPointRegistrationFailed syncPointRegFailed 1
4.8 announceSynchronizationPoint announceSyncPoint 1
4.10 federationSynchronized fedSync 1
4.12 initiateFederateSave initiateFedSave 1
4.15 federationSaved fedSaved 1
4.15 federationNotSaved fedNotSaved 1
4.17 requestFederationRestoreSucceeded requestFedResSucceeded 1
4.17 requestFederationRestoreFailed requestFedResFailed 1
4.18 federationRestoreBegun fedResBegun 1
4.19 initiateFederateRestore initiateFedRestore 1
4.21 federationRestored fedRestored 1
4.21 federationNotRestored fedNotRestored 1

Declaration Management - RTI Services (5)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
5.2 publishObjectClass publishObjClass 1
5.3 unpublishObjectClass unpublishObjClass 1
5.4 publishInteractionClass publishInteractClass 1
5.5 unpublishInteractionClass unpublishInteractClass 1
5.6 subscribeObjectClassAttributes subscribeObjClassAttr 1
5.7 unsubscribeObjectClass unsubscribeObjClass 1
5.8 subscribeInteractionClass subscribeInteractClass 1
5.9 unsubscribeInteractionClass unsubscribeInteractClass 1

Declaration Management - Federate Services (5)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
5.10 startRegistrationForObjectClass startRegForObjClass 1
5.11 stopRegistrationForObjectClass stopRegForObjClass 1
5.12 turnInteractionsOn turnInteractOn 1
5.13 turnInteractionsOff turnInteractOff 1

Object Management - RTI Services (6)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
6.2 registerObjectInstance registerObjInst 1
6.4 updateAttributeValues updateAttrVal 1
6.6 sendInteraction sendInteract 1
6.8 deleteObjectInstance deleteObjInst 1
6.10 localDeleteObjectInstance localDelObjInst 1
6.11 changeAttributeTransportType changeAttrTransType 1
6.12 changeInteractionTransportType changeInteractTransType 1
6.15 requestObjectAttributeValueUpdate requestObjAttrValUp 1

Object Management - Federate Services (6)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
6.3 discoverObjectInstance discoverObjInst 1
6.5 reflectAttributeValues reflectAttrVal 1
6.7 receiveInteraction receiveInteract 1
6.9 removeObjectInstance removeObjInst 1
6.13 attributesInScope attrInScope 1
6.14 attributesOutOfScope attrOutOfScope 1
6.16 provideAttributeValueUpdate provideAttrValUpdate 1
6.16 turnUpdatesOnForObjectInstance turnUpdatesOnForObjInst 1
6.18 turnUpdatesOffForObjectInstance turnUpdatesOffForObjInst 1

Ownership Management - RTI Services (7)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
7.2 unconditionalAttributeOwnershipDivestiture unconditionalAttrOsDivest 0
7.3 negotiatedAttributeOwnershipDivestiture negotiatedAttrOsDivest 0
7.7 attributeOwnershipAcquisition attrOsAcq 0
7.8 attributeOwnershipAcquisitionIfAvailable attrOsAcqIfAvail 0
7.11 attributeOwnershipReleaseResponse attrOsRelRes 0
7.12 cancelNegotiatedAttributeOwnershipDivestiture cancelNegAttrOsDivest 0
7.13 cancelAttributeOwnershipAcquisition cancelAttrOsAcq 0
7.15 queryAttributeOwnership queryAttrOs 0
7.17 isAttributeOwnedByFederate isAttrOwnedByFed 0

Ownership Management - Federate Services (7)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
7.4 requestAttributeOwnershipAssumption requestAttrOsAssump 0
7.5 attributeOwnershipDivestitureNotification attrOsDivestNot 0
7.6 attributeOwnershipAcquisitionNotification attrOsAcqNot 0
7.9 attributeOwnershipUnavailable attrOsUnavail 0
7.10 requestAttributeOwnershipRelease requestAttrOsRel 0
7.14 confirmAttributeOwnershipAcquisitionCancellation confirmAttrOsAcqCancel 0
7.16 informAttributeOwnership informAttrOs 0
7.16 attributeIsNotOwned attrIsNotOwned 0
7.16 attributeOwnedByRTI attrOwnedByRTI 0

Time Management - RTI Services (8)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
8.2 enableTimeRegulation enableTimeReg 1
8.4 disableTimeRegulation disableTimeReg 1
8.5 enableTimeConstrained enableTimeConstr 1
8.7 disableTimeConstrained disableTimeConstr 1
8.8 timeAdvanceRequest timeAdvReq 1
8.9 timeAdvanceRequestAvailable timeAdvReqAvail 1
8.10 nextEventRequest nextEventReq 1
8.11 nextEventRequestAvailable nextEventReqAvail 1
8.12 flushQueueRequest flushQueueReq 1
8.14 enableAsynchronousDelivery enableAsyncDeliv 1
8.15 disableAsynchronousDelivery disableAsyncDeliv 1
8.16 queryLBTS queryLBTS 1
8.17 queryFederateTime queryFedTime 1
8.18 queryMinNextEventTime queryMinNextEventTime 1
8.19 modifyLookahead modifyLookahead 1
8.20 queryLookahead queryLookahead 1
8.21 retract retract 1
8.23 changeAttributeOrderType changeAttrOrderType 1
8.24 changeInteractionOrderType changeInteractOrderType 1

Time Management - Federate Services (8)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
8.3 timeRegulationEnabled timeRegEnabled 1
8.6 timeConstrainedEnabled timeConstrEnabled 1
8.13 timeAdvanceGrant timeAdvGrant 1
8.22 requestRetraction requestRetract 1

Data Distribution Management - RTI Services (9)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
9.2 createRegion createRegion 0
9.3 notifyAboutRegionModification notifyAboutRegMod 0
9.4 deleteRegion deleteRegion 0
9.5 registerObjectInstanceWithRegion registerObjInstWR 0
9.6 associateRegionForUpdates associateRegForUpdates 0
9.7 unassociateRegionForUpdates unassociateRegForUpdates 0
9.8 subscribeObjectClassAttributesWithRegion subscribeObjClassAttrWR 0
9.9 unsubscribeObjectClassAttributesWithRegion unsubscribeObjClassAttrWR 0
9.10 subscribeInteractionClassWithRegion subscribeInteractClassWR 0
9.11 unsubscribeInteractionClassWithRegion unsubscribeInteractClassWR 0
9.12 sendInteractionWithRegion sendInteractionWR 0
9.13 requestClassAttributeValueUpdateWithRegion requestClassAttrValUpdateWR 0

RTI Support Services (10)

Service Number HLA Interface Specification Method MatlabHLA-Toolbox Function Implementation Status
10.2 getObjectClassHandle getObjClassHdl 1
10.3 getObjectClassName getObjClassName 0
10.4 getAttributeHandle getAttrHdl 1
10.5 getAttributeName getAttrName 0
10.6 getInteractionClassHandle getInteractClassHdl 1
10.7 getInteractionClassName getInteractClassName 0
10.8 getParameterHandle getParamHdl 1
10.9 getParameterName getParamName 0
10.10 getObjectInstanceHandle getObjInstHdl 0
10.11 getObjectInstanceName getObjInstName 0
10.12 getRoutingSpaceHandle getRoutingSpaceHdl 0
10.13 getRoutingSpaceName getRoutingSpaceName 0
10.14 getDimensionHandle getDimHdl 0
10.15 getDimensionName getDimName 0
10.16 getAttributeRoutingSpaceHandle getAttrRoutingSpaceHdl 0
10.17 getObjectClass getObjClass 0
10.18 getInteractionRoutingSpaceHandle getInteractRoutingSpaceHdl 0
10.19 getTransportationHandle getTransHdl 1
10.20 getTransportationName getTransName 0
10.21 getOrderingHandle getOrderingHdl 1
10.22 getOrderingName getOrderingName 0
10.23 enableClassRelevanceAdvisorySwitch enableClassRelAdvisSwitch 0
10.24 disableClassRelevanceAdvisorySwitch disableClassRelAdvisSwitch 0
10.25 enableAttributeRelevanceAdvisorySwitch enableAttrRelAdvisSwitch 1
10.26 disableAttributeRelevanceAdvisorySwitch disableAttrRelAdvisSwitch 0
10.27 enableAttributeScopeAdvisorySwitch enableAttrScopeAdvisSwitch 0
10.28 disableAttributeScopeAdvisorySwitch disableAttrScopeAdvisSwitch 0
10.29 enableInteractionRelevanceAdvisorySwitch enableInteractRelAdvisSwitch 0
10.30 disableInteractionRelevanceAdvisorySwitch disableInteractRelAdvisSwitch 0
- tick tick 1
- getRegionToken getRegionToken 0
- getRegion getRegion 0

Major Development Steps
2008 2007 2006 2005 2003 2002 2000 1999 1998
Getting MatlabHLA-Toolbox
There are three possibilities to obtain the MatlabHLA-Toolbox:
  1. Download the latest release from the ONERA CERTI contrib folder as source tar ball. This is the recommended method for most users.
  2. If you want to improve the MatlabHLA-Toolbox or if you are interested in the latest changes you can get the current development state from ONERA CERTI through anonymous CVS with the following instruction:

    cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/certi co -d MatlabHLA applications/MatlabHLA_Toolbox

  3. The third method is for registered ONERA CERTI users only. Visit http://savannah.nongnu.org/cvs/?group=certi for further details.
Installing MatlabHLA-Toolbox
Note: The install instructions are based upon a former successful ONERA CERTI installation. A working Matlab installation is required. If you compile on a x64 architecture change the MEXSUFFIX variable in the Makefile to mexa64.

  1. Change to the MatlabHLA directory.
  2. Read the README file.
  3. make && make install
  4. Set your Matlab path to the created toolbox directory.
  5. Copy all FED files of the demonstration applications under the federations directory to your CERTI_FED directory.
  6. Verify your installation with one of the demo applications.
Sending Patches
To create patches please work via CVS as described above. Create patches against the current cvs repository with

cvs diff -uN . > /tmp/myChanges.patch

The command line option -u creates an unified diff, -N adds new files to the patch. Please send your patch to the project supervisor.

Bug Report
The recommended method is to report the bug at the ONERA CERTI bug tracker. Choose MatlabHLA_Toolbox in the category field. This method requires a vaild login at Savannah. Another but particularly not recommended method is to write directly an email to the project supervisor.
Belonging Publications
This section tries to list all publications dealing with the High Level Architecture (HLA) and Scientific Computational Environments (SCE) or Fortran. It would be very nice if you can help to complete the list below. If you have a literature hint please send an email to the project supervisor.

2007

2006 2001 2000
Feb. 2008, C. Stenzel